Dotnet Desktop Winforms Controls Netframeworkdesktop 4.8

Dê a sua opinião sobre a experiência de download do PDF.
Controles de formulários do Windows

Artigo • 02/06/2023
À medida que você cria e modifica a interface do usuário de seus aplicativos dos
Windows Forms, será necessário adicionar, alinhar e posicionar controles. Os controles
são objetos que estão contidos em objetos de formulário. Cada tipo de controle tem
seu próprio conjunto de propriedades, métodos e eventos que o tornam adequado para
uma finalidade específica. Você pode manipular os controles no designer e escrever o
código para adicionar controles dinamicamente em tempo de execução.
Nesta seção
Colocando controles nos Windows Forms
Fornece links relacionados à colocação de controles em formulários.
Organizando controles nos Windows Forms

Artigos relacionados à organização de controles em formulários.
Identificando controles dos Windows Forms individuais e fornecendo atalhos para eles
Descreve os usos dos atalhos de teclado, rótulos de texto em controles e teclas
modificadoras.
Controles a serem usados nos Windows Forms

Lista os controles que funcionam com o Windows Forms e tarefas básicas que você
pode realizar com cada controle.
Desenvolvendo controles dos Windows Forms personalizados com o .NET Framework

Fornece informações básicas e exemplos para ajudar os usuários a desenvolver
controles personalizados dos Windows Forms.
Desenvolvendo controles do Windows Forms no tempo de design

Descreve técnicas para criar controles personalizados por meio de herança e design.
Seções relacionadas
Aplicativos cliente
Fornece uma visão geral do desenvolvimento de aplicativos baseados no Windows.
Como alinhar vários controles nos
Windows Forms
Artigo • 02/06/2023
Para padronizar o layout da interface do usuário do aplicativo baseado no Windows,

você pode posicionar grupos de controles com um único comando.
Para alinhar vários controles em um formulário

1. No Visual Studio, abra o formulário que contém os controles que você deseja
posicionar no Designer Windows Forms.
2. Selecione os controles que você deseja alinhar. O primeiro controle selecionado é

o controle primário ao qual os outros serão alinhados.
3. No menu Formatar , selecione Alinhar e selecione uma das sete opções

disponíveis.
Confira também
controles Windows Forms
Como Adicionar Controles ao Windows Forms
Controles dos Windows Forms por função
Instruções passo a passo: organizando controles no Windows Forms usando guias
de alinhamento
Passo a passo: organizando controles nos Windows Forms usando um
TableLayoutPanel
Passo a passo: Organizando controles nos Windows Forms utilizando um
FlowLayoutPanel
Como: Transferir controles existentes a um pai diferente
Como ancorar controles no Windows
Forms
Artigo • 02/06/2023
Se você estiver projetando um formulário que o usuário pode redimensionar em tempo

de execução, os controles em seu formulário deverão redimensionar e reposicionar
corretamente. Para redimensionar controles dinamicamente com o formulário, você
pode usar a Anchor propriedade de controles Windows Forms. A Anchor propriedade
define uma posição de âncora para o controle. Quando um controle é ancorado a um
formulário e esse formulário é redimensionado, o controle mantém a distância entre o
controle e as posições de âncora. Por exemplo, se você tiver um TextBox controle
ancorado nas bordas esquerda, direita e inferior do formulário, conforme o formulário
for redimensionado, o TextBox controle será redimensionado horizontalmente para
manter a mesma distância dos lados direito e esquerdo do formulário. Além disso, o
controle se posiciona verticalmente para que sua localização seja sempre a mesma
distância da borda inferior do formulário. Se um controle não estiver ancorado e o
formulário for redimensionado, a posição do controle em relação às bordas do
formulário será alterada.
A Anchor propriedade interage com a AutoSize propriedade. Para obter mais

informações, consulte Visão Geral da Propriedade AutoSize.
Ancorar um controle em um formulário

1. No Visual Studio, selecione o controle que você deseja ancorar.
７ Observação
É possível ancorar vários controles simultaneamente pressionando a tecla

CTRL, clicando em cada controle para selecioná-lo e, em seguida, seguindo o
resto desse procedimento.
2. Na janela Propriedades , clique na seta à direita da Anchor propriedade.
Um editor será exibido e mostra uma cruz.
3. Para definir uma âncora, clique na seção superior, esquerda, direita ou inferior da
cruz.
Os controles estão ancorados na parte superior e esquerda por padrão.

4. Para limpar um lado do controle que foi ancorado, clique nessa parte da cruz.
5. Para fechar o Anchor editor de propriedades, clique no nome da Anchor

propriedade novamente.
Quando o formulário é exibido em tempo de execução, o controle é redimensionado

para permanecer posicionado na mesma distância da borda do formulário. A distância
da borda ancorada sempre é a mesma distância definida quando o controle é
posicionado no Designer de Formulários do Windows.
７ Observação
Determinados controles, como o ComboBox controle, têm um limite para sua

altura. Ancorar o controle na parte inferior do formulário ou contêiner não pode
forçar o controle a exceder o limite de altura.
Controles herdados devem ser Protected para serem ancorados. Para alterar o nível de
acesso de um controle, defina sua propriedade Modifiers na janela Propriedades.
Confira também
Visão geral da propriedade AutoSize
Como encaixar controles no Windows Forms
FlowLayoutPanel
TableLayoutPanel
Passo a passo: Definir o layout de controles do Windows Forms com
preenchimento, margens e a propriedade AutoSize
Como encaixar controles no Windows
Forms
Artigo • 02/06/2023
Você pode encaixar controles nas bordas do formulário ou fazer com que eles
preencham o contêiner do controle (um controle de contêiner ou formulário). Por
exemplo, o Windows Explorer encaixa seu TreeView controle no lado esquerdo da janela
e seu ListView controle para o lado direito da janela. Use a Dock propriedade para todos
os controles de Windows Forms visíveis para definir o modo de encaixe.
７ Observação
Controles são encaixados na ordem z inversa.
A Dock propriedade interage com a AutoSize propriedade. Para obter mais informações,
consulte Visão Geral da Propriedade AutoSize.
Para encaixar um controle

1. No Visual Studio, selecione o controle que você deseja encaixar.
2. Na janela Propriedades , clique na seta à direita da Dock propriedade.
Um editor será exibido que mostra uma série de caixas que representam as bordas
e o centro do formulário.
3. Clique no botão que representa a borda do formulário no qual você deseja

encaixar o controle. Para preencher o conteúdo do controle de contêiner ou
formulário do controle, clique na caixa do centro. Clique em (nenhum) para
desabilitar o encaixe.
O controle é redimensionado automaticamente para ajustar os limites da borda

encaixada.
７ Observação
Controles herdados devem ser Protected para poderem ser encaixados. Para
alterar o nível de acesso de um controle, defina sua propriedade Modifier na
janela Propriedades .
Confira também
Identificando controles dos Windows Forms individuais e fornecendo atalhos para
eles
Como: Ancorar e encaixar controles filho em um controle FlowLayoutPanel
Como ancorar e encaixar controles filho em um controle TableLayoutPanel
Como ancorar controles no Windows Forms
como: objetos de camada no Windows
Forms
Artigo • 02/06/2023
Ao criar uma interface do usuário complexa ou trabalhar com um formulário MDI

(interface de múltiplos documentos), geralmente se deseja dispor em camadas controles
e formulários filho para criar interfaces do usuário (UI) mais complexas. Para mover e
acompanhar controles e janelas no contexto de um grupo, você manipula sua ordem z.
A ordem z consiste na disposição em camadas visuais de controles em um formulário ao
longo do eixo z do formulário (profundidade). A janela na parte superior da ordem z se
sobrepõe a todas as outras janelas. Todas as outras janelas se sobrepõe a janela na
parte inferior da ordem z.
Dispondo controles em camadas no design

time
1. em Visual Studio, selecione um controle que você deseja camada.
2. No menu Formatar , selecione pedidoe, em seguida, selecione trazer para frente

ou Enviar para trás.
Dispondo controles em camadas de forma

programática
Use os BringToFront métodos e SendToBack para manipular a ordem z dos controles.
Por exemplo, se um TextBox controle, txtFirstName , estiver abaixo de outro controle e

você quiser tê-lo na parte superior, use o seguinte código:
C#
txtFirstName.BringToFront();
７ Observação
Windows Forms dá suporte a Contenção de controle. A contenção de controle

envolve colocar um número de controles dentro de um controle recipiente, como
um número de RadioButton controles dentro de um GroupBox controle. Em
seguida, é possível dispor os controles em camadas no controle de contenção.
Mover a caixa de grupo move também os controles, já que estes estão contidos
dentro dela.
Confira também
controles de Windows Forms
eles
Como bloquear controles para Windows
Forms
Artigo • 02/06/2023
Ao projetar a interface do usuário do seu aplicativo do Windows, você pode bloquear os

controles quando eles são posicionados corretamente, para que você não os mova nem
os redimensione inadvertidamente ao configurar outras propriedades.
Além disso, você pode bloquear e desbloquear todos os controles no formulário de

uma vez, o que é útil para formulários com muitos controles ou você pode desbloquear
controles individuais. Depois de colocar todos os controles no local desejado no
formulário, bloqueie-os no local para evitar a movimentação incorreta.
Para bloquear um controle

Na janela Propriedades do Visual Studio, selecione a propriedade Bloqueado e
selecione true. (Clicar duas vezes no nome alterna a configuração da propriedade.)
Como alternativa, clique com o botão direito do mouse no controle e escolha Bloquear
Controles.
７ Observação
O bloqueio dos controles evita que eles sejam arrastados para um novo tamanho
ou local na superfície de design. No entanto, você ainda pode alterar o tamanho ou
local dos controles por meio da janela Propriedades ou no código.
Para bloquear todos os controles em um

formulário
No menu Formatar, escolha Bloquear Controles.
７ Observação
Esse comando bloqueia também o tamanho do formulário, pois um formulário é

um controle.
Para desbloquear todos os controles
bloqueados em um formulário
No menu Formatar, escolha Bloquear Controles.
Todos os controles bloqueados anteriormente no formulário agora estão

desbloqueados.
Para desbloquear controles bloqueados

individualmente
Na janela Propriedades , selecione a propriedade Bloqueado e selecione false. (Clicar
duas vezes no nome alterna a configuração da propriedade.)
Confira também
eles
Como posicionar controles no Windows
Forms
Artigo • 02/06/2023
Para posicionar controles, use o designer Windows Forms no Visual Studio ou

especifique a Location propriedade .
Posicionar um controle na superfície de design

do designer Windows Forms
Em Visual Studio, arraste o controle para o local apropriado com o mouse.
７ Observação
Selecione o controle e mova-o com as teclas de direção para posicioná-lo com

mais precisão. Além disso, as guias de alinhamento ajudam a posicionar os
controles com precisão em seu formulário. Para obter mais informações, consulte
Instruções passo a passo: organizando controles nos Windows Forms usando
guias de alinhamento.
Posicionar um controle usando o janela

Propriedades
1. Em Visual Studio, selecione o controle que você deseja posicionar.
2. Na janela Propriedades , insira valores para Location a propriedade, separados por

uma vírgula, para posicionar o controle dentro de seu contêiner.
O primeiro número (X) é a distância entre a borda esquerda do contêiner; o

segundo número (Y) é a distância entre a borda superior da área do recipiente,
medida em pixels.
７ Observação
Você pode expandir a Location propriedade para digitar os valores X e Y

individualmente.
Posicionar um controle programaticamente
1. De definir Location a propriedade do controle como um Point.
C#
button1.Location = new Point(100, 100);
2. Altere a coordenada X do local do controle usando a Left subpropriedade.
C#
button1.Left = 300;
Incrementar o local de um controle

programaticamente
De definir Left a subpropriedade para incrementar a coordenada X do controle.
C#
button1.Left += 200;
７ Observação
Use a Location propriedade para definir as posições X e Y de um controle

simultaneamente. Para definir uma posição individualmente, use a Left
subpropriedade (X) Top ou (Y) do controle. Não tente definir implicitamente as
coordenadas Point X e Y da estrutura que representa o local do botão, pois essa
estrutura contém uma cópia das coordenadas do botão.
Confira também
de alinhamento
TableLayoutPanel
FlowLayoutPanel
eles
Como configurar o local da tela dos Windows Forms
Como redimensionar controles no
Windows Forms
Artigo • 02/06/2023
Você pode redimensionar controles individuais e redimensionar vários controles do

mesmo tipo ou de outro tipo, como Button e GroupBox controles.
Para redimensionar um controle

No Visual Studio, selecione o controle a ser redimensionado e arraste uma das oito alças
de dimensionamento.
７ Observação
Selecione o controle e pressione as teclas de direção enquanto mantém

pressionada a tecla Shift para redimensionar o controle um pixel por vez. Pressione
a seta para baixo ou as teclas de direção para a direita enquanto segura as teclas
Shift e Ctrl para redimensionar o controle em incrementos grandes.
Para redimensionar vários controles em um

formulário
1. No Visual Studio, mantenha pressionada a tecla Ctrl ou Shift e selecione os
controles que você deseja redimensionar. O tamanho do primeiro controle
selecionado será usado para os outros controles.
2. No menu Formato, selecione Igualar tamanho e selecione uma das quatro opções.
Os três primeiros comandos alteram as dimensões dos controles para
corresponder ao controle selecionado primeiro.
Confira também
Controles de Windows Forms
eles
Como redimensionar Windows Forms usando o designer
Como definir opções de grade para
todos os Windows Forms
Artigo • 02/06/2023
À medida que você se acostuma a trabalhar no ambiente de desenvolvimento do Visual

Studio, você pode definir preferências para todos os formulários e projetos com os
quais trabalha no Designer Windows Forms.
Definir opções globais de Windows Forms

1. No Visual Studio, no menu Ferramentas , selecione Opções.
2. No painel esquerdo da caixa de diálogo Opções, clique em Designer de

Formulários do Windows.
No painel direito, sob o título Configurações de Layout, você pode configurar as

configurações de grade padrão para todos os novos formulários criados. Essas
configurações incluem o tamanho da grade, se os controles se ajustam a ela e se
ela é ativada por padrão. Além disso, você pode selecionar entre os modos de
layout SnapToGrid e SnapLines. Para obter mais informações sobre guias de
alinhamento, veja Instruções passo a passo: organizando controles nos Windows
Forms usando guias de alinhamento.
Confira também
Opções: Designer de Windows Forms
Como definir a ordem de tabulação em
Windows Forms
Artigo • 02/06/2023
A ordem de tabulação é a ordem na qual um usuário move o foco de um controle para

outro pressionando a tecla Tab. Cada formulário tem sua própria ordem de tabulação.
Por padrão, a ordem de tabulação é igual à ordem em que você criou os controles. A
numeração da ordem de tabulação começa com zero.
Para definir a ordem de tabulação de um

controle
1. Em Visual Studio, no menu Exibir, selecione Tab Order.
Isso ativa o modo de seleção de ordem de tabulação do formulário. Um número

(que representa a TabIndex propriedade) aparece no canto superior esquerdo de
cada controle.
2. Clique nos controles sequencialmente para estabelecer a ordem de tabulação

desejada.
７ Observação
Local do controle na ordem de tabulação pode ser definido como qualquer

valor maior ou igual a 0. Quando ocorrem duplicatas, a ordem z dos dois
controles é avaliada e o controle na parte superior é tabulado primeiro. (A
ordem z é a camada visual de controles em um formulário ao longo do eixo z
do formulário [profundidade]. A ordem z determina quais controles estão na
frente de outros controles.) Para obter mais informações sobre a ordem z,
consulte Objetos em camadas no Windows Forms.
3. Quando terminar, selecione Tab Order no menu Exibir novamente para sair do
modo de ordem de tabulação.
７ Observação
Controles que não podem obter o foco, bem como controles desabilitados e
invisíveis, não têm uma TabIndex propriedade e não estão incluídos na ordem
de tabulação. À medida que um usuário pressiona a tecla Tab, esses controles
são ignorados.
Como alternativa, a ordem de tabulação pode ser definida no janela Propriedades

usando a TabIndex propriedade. A TabIndex propriedade de um controle determina
onde ele está posicionado na ordem de tabulação. Por padrão, o primeiro controle
desenhado tem um TabIndex valor de 0, o segundo tem um TabIndex de 1 e assim por
diante.
Além disso, por padrão, um GroupBox controle tem seu próprio TabIndex valor, que é
um número inteiro. Um GroupBox controle em si não pode ter foco em tempo de
execução. Assim, cada controle dentro de um GroupBox tem seu próprio valor decimal
TabIndex , começando com .0. Naturalmente, à medida que o TabIndexGroupBox
controle é incrementado, os controles dentro dele serão incrementados
adequadamente. Se você alterou um TabIndex valor de 5 para 6, o TabIndex valor do
primeiro controle em seu grupo será alterado automaticamente para 6,0 e assim por
diante.
Por fim, qualquer controle dos muitos no seu formulário podem ser ignorados na ordem
de tabulação. Normalmente, pressionar Tab sucessivamente em tempo de execução
seleciona cada controle na ordem de tabulação. Ao desativar a TabStop propriedade,
você pode fazer com que um controle seja passado na ordem de tabulação do
formulário.
Para remover um controle da ordem de

tabulação
Defina a propriedade do TabStop controle como false na janela Propriedades .
Um controle cuja TabStop propriedade foi definida para false ainda manter sua
posição na ordem de tabulação, mesmo que o controle seja ignorado quando você
percorre os controles com a tecla Tab.
７ Observação
Um grupo de botões de opção tem uma única parada de tabulação no tempo de

execução. O botão selecionado (ou seja, o botão com sua Checked propriedade
definida como true ) tem sua TabStop propriedade definida automaticamente
como true , enquanto os outros botões têm sua TabStop propriedade definida
como false . Para obter mais informações sobre controles de
agrupamentoRadioButton, consulte Agrupamento Windows Forms controles
RadioButton para funcionar como um conjunto.
Consulte também
Passo a passo: organizar controles em
Windows Forms usando snaplines
Artigo • 02/06/2023
O posicionamento exato dos controles no formulário é uma prioridade alta para muitos
aplicativos. O Designer de Formulários do Windows fornece várias ferramentas de
layout para fazer isso. Um dos mais importantes é o SnapLine recurso.
As guias de alinhamento mostram exatamente onde alinhar os controles com outros

controles. Eles também mostram as distâncias recomendadas para margens entre
controles, conforme especificado pelas diretrizes da Interface do Usuário do Windows.
As guias de alinhamento facilitam o alinhamento dos controles para garantir uma

aparência e um comportamento claros e profissionais.
Criar o projeto
1. No Visual Studio, crie um projeto de aplicativo baseado no Windows chamado
"SnaplineExample".
2. Selecione o formulário no Designer de Formulários.
Espaço e alinhar controles

As guias de alinhamento oferecem uma maneira intuitiva e precisa de alinhar os
controles no formulário. Elas aparecem quando você está movendo um controle ou
controles selecionados para perto de uma posição que se alinha a outro controle ou
conjunto de controles. Sua seleção será "ajustada" para a posição sugerida ao ser
movida passando pelos outros controles.
Para organizar os controles usando guias de alinhamento

1. Arraste um Button controle da Caixa de Ferramentas para o formulário.
2. Mova o Button controle para o canto inferior direito do formulário. Observe as

linhas de ajuste que aparecem à medida que o Button controle se aproxima das
bordas inferior e direita do formulário. Essas guias de alinhamento exibem a
distância recomendada entre as bordas do controle e o formulário.
3. Mova o Button controle ao redor das bordas do formulário e observe onde os
snaplines aparecem. Quando terminar, mova o Button controle para perto do
centro do formulário.
4. Arraste outro Button controle da Caixa de Ferramentas para o formulário.
5. Mova o segundo Button controle até que ele esteja quase nivelado com o
primeiro. Observe a guia de alinhamento que aparece na linha de base de texto de
ambos os botões e observe que o controle que você está movendo se ajusta para
uma posição nivelada exatamente com o outro controle.
6. Mova o segundo Button controle até que ele seja posicionado diretamente acima
do primeiro. Observe as guias de alinhamento que aparecem ao longo das bordas
esquerda e direita de ambos os botões e observe que o controle que você está
movendo se ajusta para uma posição alinhada exatamente com o outro controle.
7. Selecione um dos Button controles e mova-o para perto do outro, até que eles
estejam quase tocando. Observe a guia de alinhamento que aparece entre eles.
Essa é a distância recomendada entre as bordas dos controles. Observe também
que o controle que você está movendo se encaixa nessa posição.
8. Arraste dois Panel controles da Caixa de Ferramentas para o formulário.
9. Mova um dos Panel controles até que esteja quase nivelado com o primeiro.
Observe as guias de alinhamento que aparecem ao longo das bordas superior e
inferior de ambos os controles e observe que o controle que você está movendo
se ajusta para uma posição alinhada exatamente com o outro controle.
Alinhar às margens de formulário e contêiner

As guias de alinhamento ajudam a alinhar os controles às margens do formulário e do
contêiner de uma maneira consistente.
1. Selecione um dos Button controles e mova-o para perto da borda direita do

formulário até que um snapline seja exibido. A distância do snapline da borda
direita é a soma da propriedade do Margin controle e dos valores de propriedade
do Padding formulário.
７ Observação
Se a propriedade do Padding formulário estiver definida como 0,0,0,0, o

Designer de Windows Forms fornecerá ao formulário um valor sombreado
Padding de 9,9,9,9.9. Para substituir esse comportamento, atribua um valor
diferente de 0,0,0,0.
2. Altere o valor da Button propriedade do Margin controle expandindo a Margin

entrada na janela Propriedades e definindo a All propriedade como 0. Para obter
detalhes, consulte Instruções passo a passo: projetando controles dos Windows
Forms com preenchimento, margens e a propriedade AutoSize.
3. Mova o Button controle para perto da borda direita do formulário até que um
snapline seja exibido. Essa distância agora é fornecida pelo valor da propriedade
do Padding formulário.
4. Arraste um GroupBox controle da Caixa de Ferramentas para o formulário.
5. Altere o valor da GroupBox propriedade do Padding controle expandindo a

Padding entrada na janela Propriedades e definindo a All propriedade como 10.
6. Arraste um Button controle da Caixa de Ferramentas para o GroupBox controle.
7. Mova o Button controle para perto da borda direita do GroupBox controle até que
um snapline seja exibido. Mova o Button controle dentro do GroupBox controle e
observe onde as linhas de ajuste aparecem.
Alinhar aos controles agrupados

Você pode usar snaplines para alinhar controles agrupados, bem como controles dentro
de um GroupBox controle.
1. Selecione dois dos controles no formulário. Mova um pouco a seleção e observe

as guias de alinhamento que aparecem entre a seleção e os outros controles.
2. Arraste um GroupBox controle da Caixa de Ferramentas para o formulário.
3. Arraste um Button controle da Caixa de Ferramentas para o GroupBox controle.
4. Selecione um dos Button controles e mova-o ao redor do GroupBox controle.

Observe as linhas de ajuste que aparecem nas bordas do GroupBox controle.
Observe também os snaplines que aparecem nas bordas do Button controle
contidas pelo GroupBox controle. Os controles que são filhos de uma caixa de
controles também dão suporte a guias de alinhamento.
Use snaplines para colocar um controle
delineando seu tamanho
1. Na Caixa de Ferramentas, clique no ícone de Button controle. Não o arraste para o
formulário.
2. Mova o ponteiro do mouse sobre a superfície de design do formulário. Observe

que o ponteiro é alterado para uma mira com o ícone de Button controle anexado.
Observe também os snaplines que parecem sugerir posições alinhadas para o
Button controle.
3. Clique e mantenha o botão do mouse pressionado.
4. Arraste o ponteiro do mouse sobre o formulário. Observe que uma estrutura de

tópicos é desenhada, indicando a posição e o tamanho do controle.
5. Arraste o ponteiro até que ele se alinhe com o outro controle no formulário.
Observe que aparece uma guia de alinhamento para indicar o alinhamento.
6. Solte o botão do mouse. O controle é criado com a posição e com o tamanho

indicados pela estrutura de tópicos.
Usar snaplines ao arrastar um controle da Caixa

de Ferramentas
1. Arraste um Button controle da Caixa de Ferramentas para o formulário, mas não
solte o botão do mouse.
2. Mova o ponteiro do mouse sobre a superfície de design do formulário. Observe

que o ponteiro é alterado para indicar a posição na qual o novo Button controle
será criado.
3. Arraste o ponteiro do mouse sobre o formulário. Observe os snaplines que

parecem sugerir posições alinhadas para o Button controle. Localize uma posição
que esteja alinhada com outros controles.
4. Solte o botão do mouse. O controle é criado na posição indicada pela guia de

alinhamento.
Redimensionar um controle usando snaplines

2. Redimensione o Button controle pegando uma das alças de dimensionamento de
canto e arrastando. Para obter detalhes, consulte Instruções: redimensionar
controles nos Windows Forms.
3. Arraste o identificador de dimensionamento até que uma das Button bordas do

controle esteja alinhada com outro controle. Observe que uma guia de
alinhamento aparece. Observe também que a alça de dimensionamento se encaixa
na posição indicada pela guia de alinhamento.
4. Redimensione o Button controle em direções diferentes e alinhe o identificador de

dimensionamento com controles diferentes. Observe como as guias de
alinhamento aparecem em várias orientações para indicar o alinhamento.
Alinhar um rótulo ao texto de um controle

1. Arraste um TextBox controle da Caixa de Ferramentas para o formulário. Quando
você soltar o TextBox controle no formulário, clique no glifo de marca inteligente e
selecione a opção Definir texto para textBox1 . Para obter detalhes, consulte Passo
a passo: executar tarefas comuns usando ações de designer.
2. Arraste um Label controle da Caixa de Ferramentas para o formulário.
3. Altere o valor da propriedade Label do controle AutoSize para true . Observe que
as bordas do controle são ajustadas para se ajustar ao texto de exibição.
4. Mova o Label controle para a esquerda do TextBox controle, para que ele seja
alinhado com a borda inferior do TextBox controle. Observe a guia de alinhamento
que aparece ao longo das bordas inferiores dos dois controles.
5. Mova o Label controle ligeiramente para cima até que o Label texto e o TextBox
texto estejam alinhados. Observe a guia de alinhamento com um estilo diferente
que aparece, indicando quando os campos de texto de ambos os controles estão
alinhados.
Usar snaplines com navegação por teclado

1. Arraste um Button controle da Caixa de Ferramentas para o formulário. Coloque-o
no canto superior esquerdo do formulário.
2. Pressione Ctrl+seta para baixo. Observe que o controle se move para baixo no
formulário até a primeira posição de alinhamento horizontal disponível.
3. Pressione Ctrl+seta para baixo até que o controle chegue à parte inferior do
formulário. Observe as posições que ele ocupa conforme se move para baixo no
formulário.
4. Pressione Ctrl+seta para a direita. Observe que o controle percorre o formulário

até a primeira posição de alinhamento vertical disponível.
5. Pressione aseta para a direitactrl+ até que o controle atinja o lado do formulário.
Observe as posições que ele ocupa conforme se move no formulário.
6. Mova o controle no formulário com uma combinação de teclas de direção.

Observe as posições ocupadas pelo controle e as guias de alinhamento que o
acompanham.
7. Pressioneas teclas de direçãoShift+ para redimensionar o Button controle por

incrementos de um pixel.
8. Pressione asteclasde direção Ctrl+Shift+ para redimensionar o Button controle em

incrementos de snapline.
Desabilitar seletivamente snaplines

1. Arraste um TableLayoutPanel controle da Caixa de Ferramentas para o formulário.
2. Clique duas vezes no Button ícone de controle na Caixa de Ferramentas. Observe

que um novo controle de botão aparece na TableLayoutPanel primeira célula do
controle.
3. Clique duas vezes no Button ícone de controle na Caixa de Ferramentas duas

vezes mais. Isso deixa uma célula vazia no TableLayoutPanel controle.
4. Arraste um Button controle da Caixa de Ferramentas para a célula vazia do

TableLayoutPanel controle. Observe que não aparece nenhuma guia de
alinhamento.
5. Arraste o Button controle para fora do TableLayoutPanel controle e mova-o ao

redor do TableLayoutPanel controle. Observe que as guias de alinhamento
aparecem novamente.
Desabilitar snaplines
Pressione a tecla Alt e, ao mover um controle ao redor do formulário.
Não são exibidas linhas de ajuste e o controle não se ajusta a nenhuma posição de
alinhamento em potencial.
Para desabilitar as guias de alinhamento no ambiente de

design
1. No menu Ferramentas, abra a caixa de diálogo Opções. Selecione Windows Forms
Designer.
2. Selecione o nó Geral. Na seção Modo de Layout, altere a seleção de SnapLines

para SnapToGrid.
3. Selecione OK para aplicar a configuração.
4. Selecione um controle no formulário e mova-o em torno dos outros controles.

Observe que as guias de alinhamento não aparecem.
Próximas etapas
As guias de alinhamento oferecem uma forma intuitiva de alinhar controles no
formulário. Sugestões para exploração adicional incluem:
Tente aninhar um GroupBox controle dentro de outro GroupBox controle. Coloque

um Button controle dentro do controle filho GroupBox e outro dentro do controle
pai GroupBox . Mova os Button controles para ver como os snaplines cruzam os
limites do contêiner.
Crie uma coluna de TextBox controles e uma coluna correspondente de Label

controles. Defina o valor da Label propriedade dos AutoSize controles como true .
Use snaplines para mover os Label controles para que o texto exibido esteja
alinhado com o texto nos TextBox controles.
Confira também
SnapLine
FlowLayoutPanel
TableLayoutPanel
Como reatribuir controles existentes
para um pai diferente
Artigo • 02/06/2023
Você pode atribuir controles existentes em seu formulário a um novo controle de

contêiner.
1. No Visual Studio, arraste três Button controles da Caixa de Ferramentas para o

formulário. Posicione-os próximo entre si, mas deixe-os desalinhados.
2. Na Caixa de Ferramentas, clique no ícone de FlowLayoutPanel controle. (Não

arraste o ícone para o formulário.)
3. Mova o ponteiro do mouse para perto dos três Button controles.
O ponteiro é alterado para uma mira com o ícone de FlowLayoutPanel controle

anexado.
5. Arraste o ponteiro do mouse para desenhar a estrutura de tópicos do

FlowLayoutPanel controle.
6. Desenhe a estrutura de tópicos em torno dos três Button controles.
7. Solte o botão do mouse.
Os três Button controles agora são inseridos no FlowLayoutPanel controle.
Confira também
FlowLayoutPanel
TableLayoutPanel
TableLayoutPanel
de alinhamento
Passo a passo: definir controles com
preenchimento, margens e a
propriedade AutoSize
Artigo • 02/06/2023
aplicativos. O Designer de Windows Forms no Visual Studio oferece muitas ferramentas
de layout para fazer isso. Três das mais importantes são as Marginpropriedades ,
Paddinge AutoSize que estão presentes em todos os controles Windows Forms.
A Margin propriedade define o espaço em torno do controle que mantém outros

controles a uma distância especificada das bordas do controle.
A Padding propriedade define o espaço no interior de um controle que mantém o

conteúdo do controle (por exemplo, o valor de sua Text propriedade) a uma distância
especificada das bordas do controle.
A ilustração a seguir mostra as propriedades e Margin as Padding propriedades em um

controle.
A AutoSize propriedade informa a um controle para dimensionar-se automaticamente

para seu conteúdo. Ele não se redimensionará para ser menor que o valor de sua
propriedade original Size , e será responsável pelo valor de sua Padding propriedade.
Pré-requisitos
Você precisará do Visual Studio para concluir este passo a passo.
Criar o projeto
1. No Visual Studio, crie um projeto de aplicativo do Windows chamado
LayoutExample .
2. Selecione o formulário no Designer de Formulários do Windows.
Definir margens para controles

Você pode definir a distância padrão entre seus controles usando a Margin propriedade.
Quando você move um controle feche suficiente para um outro controle, você verá uma
guia de alinhamento que mostra as margens para os dois controles. O controle que
você está movendo também se ajustará à distância definida pelas margens.
Organizar controles em seu formulário usando a

propriedade Margin
1. Arraste dois Button controles da Caixa de Ferramentas para o formulário.
2. Selecione um dos Button controles e mova-o para perto do outro, até que eles
estejam quase tocando.
Observe a guia de alinhamento que aparece entre eles. Essa distância é a soma
dos valores dos Margin dois controles. O controle que você está movendo se
ajusta a essa distância. Para mais detalhes, consulte Instruções passo a passo:
organizando controles nos Windows Forms usando linhas de alinhamento.
3. Altere a Margin propriedade de um dos controles expandindo a Margin entrada na

janela Propriedades e definindo a All propriedade como 20.
4. Selecione um dos Button controles e mova-o para perto do outro.
A guia de alinhamento definindo a soma dos valores de margem é maior e o

controle se ajusta a uma distância maior de outro controle.
5. Altere a Margin propriedade do controle selecionado expandindo a Margin

entrada na janela Propriedades e definindo a Top propriedade como 5.
6. Mover o controle selecionado abaixo de outro controle e observar que a guia de

alinhamento é menor. Mover o controle selecionado para a esquerda de outro
controle e observe que a guia de alinhamento retém o valor observado na etapa 4.
7. Você pode definir cada um dos aspectos da Margin propriedade, Left, Top,
Rightpara Bottomvalores diferentes, ou você pode defini-los todos com o mesmo
valor com a All propriedade.
Definir o preenchimento para controles

Para alcançar o layout preciso necessário para seu aplicativo, os controles geralmente
contém controles filho. Quando você quiser especificar a proximidade da borda do
controle filho com a borda do controle pai, use a propriedade do Padding controle pai
em conjunto com a propriedade do Margin controle filho. A Padding propriedade
também é usada para controlar a proximidade do conteúdo de um controle (por
exemplo, a propriedade de Text um Button controle) para suas bordas.
Organizar controles em seu formulário usando

preenchimento
2. Altere o valor da Button propriedade do AutoSize controle para true.
3. Altere a Padding propriedade expandindo a Padding entrada na janela

Propriedades e definindo a All propriedade como 5.
O controle se expande para fornecer espaço para o novo preenchimento.
4. Arraste um GroupBox controle da Caixa de Ferramentas para o formulário. Arraste

um Button controle da Caixa de Ferramentas para o GroupBox controle. Posicione
o Button controle para que ele seja liberado com o canto inferior direito do
GroupBox controle.
Observe as linhas de ajuste que aparecem à medida que o Button controle se

aproxima das bordas inferior e direita do GroupBox controle. Esses snaplines
correspondem à Margin propriedade do Button.
5. Altere a GroupBox propriedade do Padding controle expandindo a Padding

entrada na janela Propriedades e definindo a All propriedade como 20.
6. Selecione o Button controle dentro do GroupBox controle e mova-o para o centro

do GroupBox.
Os snaplines aparecem a uma distância maior das bordas do GroupBox controle.

Essa distância é a soma da Button propriedade do Margin controle e GroupBox da
propriedade do Padding controle.
Controles de tamanho automaticamente
Em alguns aplicativos, o tamanho de um controle não será o mesmo no momento de
execução como era no momento de design. O texto de um Button controle, por
exemplo, pode ser retirado de um banco de dados e seu comprimento não é conhecido
com antecedência.
Quando a AutoSize propriedade for definida como true , o controle será dimensionado
para seu conteúdo. Para obter mais informações, consulte Visão Geral da Propriedade
AutoSize.
Organizar controles em seu formulário usando a

propriedade AutoSize
3. Alterar a Button propriedade do Text controle para este botão tem uma cadeia de
caracteres longa para sua propriedade Text.
Quando você confirma a alteração, o Button controle se redimensiona para se

ajustar ao novo texto.
4. Arraste outro Button controle da Caixa de Ferramentas para o formulário.
5. Altere a Button propriedade do Text controle para "Este botão tem uma cadeia de
caracteres longa para sua propriedade Text".
Quando você confirma a alteração, o Button controle não se redimensiona e o

texto é recortado pela borda direita do controle.
6. Altere a Padding propriedade expandindo a Padding entrada na janela

Propriedades e definindo a All propriedade como 5.
O texto no interior do controle é cortado nos quatro lados.
7. Altere a Button propriedade do AutoSize controle para true.
O Button controle se redimensiona para abranger toda a cadeia de caracteres.

Além disso, o preenchimento foi adicionado ao redor do texto, fazendo com que o
Button controle se expanda em todas as quatro direções.
8. Arraste um Button controle da Caixa de Ferramentas para o formulário. Posicione

no canto inferior direito do formulário.
10. Defina a Button propriedade do Anchor controle como Right, Bottom.
11. Altere a Button propriedade do Text controle para "Este botão tem uma cadeia de
caracteres longa para sua propriedade Text".
Quando você confirma a alteração, o Button controle se redimensiona em direção à

esquerda. Em geral, o dimensionamento automático aumentará o tamanho de um
controle na direção oposta à configuração de propriedade Anchor .
AutoSize e propriedades AutoSizeMode

Alguns controles oferecem suporte a AutoSizeMode propriedade, que lhe dá controle
mais refinado sobre o comportamento de dimensionamento automático de um
controle.
Usar a propriedade AutoSizeMode

1. Arraste um Panel controle da Caixa de Ferramentas para o formulário.
2. Defina o valor da Panel propriedade do AutoSize controle como true.
3. Arraste um Button controle da Caixa de Ferramentas para o Panel controle.
4. Coloque o Button controle perto do canto inferior direito do Panel controle.
5. Selecione o Panel controle e pegue o identificador de dimensionamento inferior

direito. Redimensione o Panel controle para ser maior e menor.
７ Observação
Você pode redimensionar livremente o Panel controle, mas não pode

dimensioná-lo menor que a posição do Button canto inferior direito do
controle. Esse comportamento é especificado pelo valor padrão da
AutoSizeMode propriedade, que é GrowOnly.
6. Defina o valor da Panel propriedade do AutoSizeMode controle como

GrowAndShrink.
O Panel controle se dimensiona para cercar o Button controle. Você não pode
redimensionar o Panel controle.
7. Arraste o Button controle em direção ao canto superior esquerdo do Panel
controle.
O Panel controle redimensiona para a Button nova posição do controle.
Próximas etapas
Há muitos outros recursos de layout para organizar controles em seus aplicativos dos
Windows Forms. Aqui estão algumas combinações que você pode tentar:
Crie um formulário usando um TableLayoutPanel controle. Para mais detalhes,

consulte Explicação passo a passo: organizando controles nos Windows Forms
utilizando um TableLayoutPanel. Tente alterar os valores da TableLayoutPanel
propriedade do Padding controle, bem como a Margin propriedade em seus
controles filho.
Experimente o mesmo experimento usando um FlowLayoutPanel controle. Para

mais detalhes, consulte Explicação passo a passo: organizando controles nos
Windows Forms utilizando um FlowLayoutPanel.
Experimente o encaixe de controles filho em um Panel controle. A Padding

propriedade é uma realização mais geral da propriedade, e você pode satisfazer a
DockPadding si mesmo que esse é o caso colocando um controle filho em um
Panel controle e definindo a propriedade do Dock controle filho como Fill. Defina a
Panel propriedade do Padding controle como vários valores e observe o efeito.
Confira também
AutoSize
DockPadding
Margin
Padding
TableLayoutPanel
FlowLayoutPanel
de alinhamento
Colocando controles nos Windows
Forms
Artigo • 02/06/2023
Há uma grande variedade de controles que você pode colocar em Windows Forms,
dependendo das necessidades do seu aplicativo.
Nesta seção
Fornece instruções para anexar controles ao formulário.
Como adicionar controles sem uma interface do usuário aos Windows Forms
Fornece instruções para acrescentar controles sem interface do usuário para seu
aplicativo.
Como: Adicionar a ou remover de uma coleção de controles em tempo de execução

Explica como adicionar e remover controles em um painel em tempo de execução.
Passo a passo: Preencher de forma automática a caixa de ferramentas com

componentes personalizados
Demonstra como você pode fazer com que um componente personalizado apareça
automaticamente na Caixa de Ferramentas depois que o componente é criado.
Como adicionar controles do ActiveX ao Windows Forms

Fornece instruções para trabalhar com controles ActiveX herdados.
Considerações sobre quando hospedar um controle ActiveX em um Windows Form

Descreve o que ter em mente ao planejar um aplicativo que usa controles ActiveX.
Fornece links para tópicos introdutórios sobre controles e o que você pode fazer com
eles.
Validação da entrada do usuário no Windows Forms

Explica as noções básicas e a teoria por trás da validação do conteúdo dos controles dos
Windows Forms.
Como adicionar controles aos Windows
Forms
Artigo • 02/06/2023
A maioria dos formulários é projetada adicionando controles à superfície do formulário

para definir uma interface do usuário (IU). Um controle é um componente em um
formulário usado para exibir informações ou aceitar a entrada do usuário. Para obter
mais informações sobre controles, consulte Controles do Windows Forms.
Desenhar um controle em um formulário

1. Abra o formulário. Para obter mais informações, consulte Como exibir Windows
Forms no Designer.
2. Na Caixa de ferramentas, clique no controle que você deseja adicionar ao

formulário.
3. No formulário, clique onde você deseja que o canto superior esquerdo do controle
se localize e arraste até onde você deseja posicionar o canto inferior direito do
controle.
O controle é adicionado ao formulário com a localização e o tamanho

especificados.
７ Observação
Cada controle tem um tamanho padrão definido. Você pode adicionar um

controle ao seu formulário no tamanho de padrão do controle arrastando-o
da Caixa de ferramentas para o formulário.
Arrastar um controle para um formulário

1. Abra o formulário. Para obter mais informações, consulte Como exibir Windows
Forms no Designer.
2. Na Caixa de ferramentas, clique no controle que você deseja e arraste-o para o

formulário.
O controle é adicionado ao formulário na localização e tamanho especificados.

７ Observação
Você pode clicar duas vezes em um controle na Caixa de ferramentas para

adicioná-lo ao canto superior esquerdo do formulário com seu tamanho
padrão.
Você também pode adicionar controles dinamicamente a um formulário no tempo

de execução. No exemplo de código a seguir, um TextBox controle será adicionado
ao formulário quando um Button controle for clicado.
７ Observação
O procedimento a seguir requer a existência de um formulário com um

controle Botão, Button1 , já inserido nele.
Adicionar um controle a um formulário com

programação
1. No método que trata o evento Click do botão na classe do formulário, insira
código semelhante ao seguinte para adicionar uma referência à variável do
controle, defina o Location do controle e adicione o controle.
C#
private void button1_Click(object sender, System.EventArgs e)

{
TextBox myText = new TextBox();
myText.Location = new Point(25,25);
this.Controls.Add (myText);
}
７ Observação
Você também pode adicionar código para inicializar outras propriedades do

controle.
） Importante
Você poderia expor seu computador local a um risco de segurança por meio
da rede referenciando um UserControl mal-intencionado. Isso seria um
problemas apenas no caso de uma pessoa mal-intencionada criar um controle
personalizado prejudicial e você adicioná-lo por engano ao seu projeto.
Confira também
Como redimensionar controles no Windows Forms
Como definir o texto exibido por um controle dos Windows Forms
Como adicionar controles sem uma
interface do usuário aos Windows
Forms
Artigo • 02/06/2023
Um controle (ou componente) não visual fornece funcionalidade ao seu aplicativo.

Diferente de outros controles, os componentes não fornecem uma interface do usuário
ao usuário e, portanto, não precisam ser exibido na superfície do Designer de
Formulários do Windows. Quando um componente é adicionado a um formulário, o
Designer de Formulários do Windows exibe uma bandeja redimensionável na parte
inferior do formulário em que todos os componentes são exibidos. Quando um controle
é adicionado à bandeja de componentes, você pode selecionar o componente e definir
suas propriedades como faria com qualquer outro controle no formulário.
Adicionar um componente a um Formulário do

Windows
1. Abra o formulário no Visual Studio. Para ver mais detalhes, consulte Como exibir
Windows Forms no Designer.
2. Na Caixa de ferramentas, clique em um componente e arraste-o para o

formulário.
O componente aparece na bandeja de componentes.
Além disso, os componentes podem ser adicionados a um formulário no tempo de

execução. Esse é um cenário comum, especialmente porque os componentes não têm
uma expressão visual, diferente de controles que têm uma interface do usuário. No
exemplo abaixo, um Timer componente é adicionado em tempo de execução. (Observe
que o Visual Studio contém vários temporizadores diferentes; nesse caso, use um
componente Windows FormsTimer. Para obter mais informações sobre os diferentes
temporizadores no Visual Studio, consulte Introdução a Server-Based Timers.)
Ｕ Cuidado
Componentes geralmente têm propriedades específicas de controle que devem ser

definidas para o componente funcionar com eficiência. No caso do Timer
componente abaixo, você define a Interval propriedade. Verifique se as
propriedades necessárias para o componente foram definidas ao adicioná-lo ao
projeto.
Adicionar um componente a um Formulário do

Windows programaticamente
1. Crie uma instância da Timer classe no código.
2. Defina a propriedade Interval para determinar o tempo entre os tiques do

temporizador.
3. Configure as outras propriedades necessárias para seu componente.
O código a seguir mostra a criação de um Timer com seu Interval conjunto de

propriedades.
C#
public void createTimer()

{
System.Windows.Forms.Timer timerKeepTrack = new
System.Windows.Forms.Timer();
timerKeepTrack.Interval = 1000;
}
） Importante
Você poderia expor seu computador local a um risco de segurança por meio
da rede referenciando um UserControl mal-intencionado. Isso seria um
problemas apenas no caso de uma pessoa mal-intencionada criar um controle
personalizado prejudicial e você adicioná-lo por engano ao seu projeto.
Confira também
eles
Como: Adicionar a ou remover de uma
coleção de controles em tempo de
execução
Artigo • 02/06/2023
Tarefas comuns no desenvolvimento de aplicativos são adicionar controles e remover

controles de qualquer controle de contêiner em seus formulários ( PanelGroupBox como
o controle ou ou até mesmo o próprio formulário). Em tempo de design, controles
podem ser arrastados diretamente para um painel ou caixa de grupo. Em tempo de
execução, esses controles mantêm uma coleção Controls , que mantém o controle de
quais controles são colocados neles.
７ Observação
O exemplo de código a seguir aplica-se a qualquer controle que mantém uma

coleção de controles dentro dele.
Para adicionar um controle a uma coleção de forma

programática
1. Crie uma instância do controle a ser adicionado.
2. Defina as propriedades do novo controle.
3. Adicione o controle à coleção Controls do controle pai.
O exemplo de código a seguir mostra como criar uma instância do Button controle
. Ele requer um formulário com um Panel controle e que o método de manipulação
de eventos para o botão que está sendo criado, NewPanelButton_Click , já existe.
C#
public Button newPanelButton = new Button();
public void addNewControl()

{
// The Add method will accept as a parameter any object that derives
// from the Control class. In this case, it is a Button control.
panel1.Controls.Add(newPanelButton);
// The event handler indicated for the Click event in the code
// below is used as an example. Substitute the appropriate event
// handler for your application.
this.newPanelButton.Click += new System.EventHandler(this.
NewPanelButton_Click);
}
Para remover os controles de uma coleção de forma

programática
1. Remova o manipulador de eventos do evento. No Visual Basic, use a palavra-chave
Instrução RemoveHandler; em C#, use o operador -= .
2. Use o método Remove para excluir o controle desejado da coleção Controls do

painel.
3. Chame o Dispose método para liberar todos os recursos usados pelo controle .
C#
private void removeControl(object sender, System.EventArgs e)

{
// NOTE: The code below uses the instance of
// the button (newPanelButton) from the previous example.
if(panel1.Controls.Contains(newPanelButton))
{
this.newPanelButton.Click -= new System.EventHandler(this.
NewPanelButton_Click);
panel1.Controls.Remove(newPanelButton);
newPanelButton.Dispose();
}
}
Confira também
Panel
Controle do painel
Passo a passo: Preencher de forma
automática a caixa de ferramentas com
Artigo • 02/06/2023
Se seus componentes forem definidos por um projeto na solução aberta no momento,

eles aparecerão automaticamente na Caixa de Ferramentas sem exigir que você execute
nenhuma ação. Você também pode preencher manualmente a Caixa de Ferramentas
com seus componentes personalizados usando a Caixa de Diálogo Escolher Itens da
Caixa de Ferramentas (Visual Studio), mas a Caixa de Ferramentas leva em conta itens
nas saídas de build da sua solução com todas as seguintes características:
IComponentImplementa;
Não tem ToolboxItemAttribute definido como false ;
Não tem DesignTimeVisibleAttribute definido como false .
７ Observação
A Caixa de Ferramentas não segue cadeias de referência, portanto, não exibirá

itens que não são criados por um projeto em sua solução.
Este passo a passo demonstra como um componente personalizado aparece

automaticamente na Caixa de Ferramentas depois que o componente é criado. As
tarefas ilustradas neste passo a passo incluem:
Criando um projeto dos Windows Forms.
Criando um componente personalizado.
Criando uma instância de um componente personalizado.
Descarregando e recarregando um componente personalizado.
Quando tiver terminado, verá que a Caixa de Ferramentas é preenchida com um

componente que você criou.
Criar o projeto
ToolboxExample (File>New>Project>Visual C# ou Visual Basic>Classic
Desktop>Windows Forms Application).
2. Adicione um novo componente ao projeto. Chame DemoComponent .
Para obter mais informações, consulte Como adicionar novos itens de projeto.
3. Compile o projeto.
4. No menu Ferramentas, clique no item Opções. Clique em Geral no item Designer

de Formulários do Windows e certifique-se de que a opção AutoToolboxPopulate
esteja definida como True.
Criar uma instância de um componente

personalizado
A próxima etapa é criar uma instância do componente personalizado no formulário.
Uma vez que a Caixa de Ferramentas automaticamente conta para o novo componente,
isso é tão fácil quanto criar qualquer outro componente ou controle.
1. Abra o formulário do projeto no Designer de Formulários.
2. Na Caixa de Ferramentas, clique na nova guia chamada Componentes de

ToolboxExample.
Ao clicar na guia, você verá DemoComponent.
７ Observação
Por motivos de desempenho, os componentes na área preenchida

automaticamente da Caixa de Ferramentas não exibem bitmaps
personalizados e ToolboxBitmapAttribute não há suporte. Para exibir um
ícone para um componente personalizado na Caixa de Ferramentas, use a
caixa de diálogo Escolher Itens da Caixa de Ferramentas para carregar seu
componente.
3. Arraste o componente para seu formulário.
Uma instância do componente é criada e adicionada à Bandeja de Componentes.

Descarregar e recarregar um componente
personalizado
A Caixa de Ferramentas considera os componentes em cada projeto carregado e,
quando um projeto é descarregado, ela remove referências aos componentes do
projeto.
1. Descarregue o projeto da solução.
Para obter mais informações sobre o descarregamento de projetos, consulte Como

descarregar e recarregar projetos. Se você for solicitado a salvar, escolha Sim.
2. Adicione um novo projeto de Aplicativos do Windows à solução. Abra o

formulário no Designer.
A guia Componentes de ToolboxExample do projeto anterior agora está ausente.
3. Recarregue o projeto ToolboxExample .
A guia Componentes de ToolboxExample agora será exibida novamente.
Próximas etapas
Este passo a passo demonstra que a Caixa de Ferramentas leva em conta componentes
do projeto, mas a Caixa de Ferramentas também leva em os controles. Experimente
seus próprios controles personalizados adicionando e removendo projetos de controle
de sua solução.
Confira também
Geral, Designer de Formulários do Windows, Caixa de Diálogo Opções
Como manipular guias da caixa de ferramentas
Caixa de diálogo Escolher Itens da Caixa de Ferramentas (Visual Studio)
Como adicionar controles ActiveX aos
Windows Forms
Artigo • 02/06/2023
Embora o Designer de Windows Forms no Visual Studio seja otimizado para hospedar
controles Windows Forms, você também pode colocar controles ActiveX em Windows
Forms.
Ｕ Cuidado
Há limitações de desempenho para o Windows Forms quando os controles ActiveX

são adicionados a ele.
Antes de adicionar controles ActiveX ao seu formulário, você deve adicioná-los à caixa
de ferramentas. Para obter mais informações, consulte Componentes COM, Caixa de
diálogo Personalizar caixa de ferramentas.
Adicionar um controle ActiveX ao formulário

do Windows
Para adicionar um controle ActiveX ao Windows Form, clique duas vezes no controle na
Caixa de Ferramentas.
O Visual Studio adiciona todas as referências ao controle em seu projeto. Para obter
mais informações sobre as coisas para ter em mente ao usar controles ActiveX nos
Windows Forms, consulte Considerações sobre quando hospedar um controle ActiveX
em um Windows Form.
７ Observação
O Importador de controle ActiveX dos Windows Forms (AxImp.exe) cria os

argumentos de evento de um tipo diferente do que o esperado após a importação
de bibliotecas de link dinâmico do ActiveX. Os argumentos criados pelo AxImp.exe
são semelhantes ao seguinte: Invoke(object sender,
DWebBrowserEvents2_ProgressChangeEvent e) , quando Invoke(object sender,
DWebBrowserEvents2_ProgressChangeEventArgs e) for esperado. Lembre-se de que
essa irregularidade não impede que o código funcione normalmente. Para obter
detalhes, consulte Importador de Controle ActiveX dos Windows Forms
(Aximp.exe).
Confira também
Controles e objetos programáveis comparados em diversas linguagens e
bibliotecas
eles
Considerações sobre quando hospedar
um controle ActiveX em um Windows
Form
Artigo • 02/06/2023
Embora o Windows Forms tenha sido otimizada para hospedar controles dos Windows
Forms, você ainda poderá usar controles ActiveX. Lembre-se das seguintes
considerações ao planejar um aplicativo que usa os controles ActiveX:
Segurança O Common Language Runtime foi aprimorado em relação à segurança

de acesso do código. Aplicativos que contém formulários dos Windows Forms
podem ser executados em um ambiente totalmente confiável sem problemas e em
um ambiente de confiança parcial com a maioria das funcionalidades acessíveis.
Controles dos Windows Forms podem ser hospedados em um navegador sem
complicações. No entanto, controles ActiveX nos Windows Forms não podem
aproveitar essas melhorias de segurança. A execução de um controle ActiveX
requer permissão de código não gerenciada, que é definida com a
SecurityPermissionAttribute.UnmanagedCode propriedade. Para obter mais
informações sobre segurança e permissão de código não gerenciado, consulte
SecurityPermissionAttribute.
Custo total de propriedade Controles ActiveX adicionados a um Windows Form

são implantados com esse Windows Form integralmente, o que pode aumentar
significativamente o tamanho do arquivo criado. Além disso, usar controles
ActiveX nos Windows Forms requer a gravação no Registro. Isso é mais invasivo no
computador do usuário que os controles dos Windows Forms, que não exigem
isso.
７ Observação
Trabalhar com um controle ActiveX requer o uso de um wrapper de

interoperabilidade COM. Para obter mais informações, consulte
Interoperabilidade COM em Visual Basic e Visual C#.
７ Observação
Se o nome de um membro do controle ActiveX corresponder a um nome

definido no .NET Framework, o Importador de Controle ActiveX prefixará o
nome do membro com Ctl quando ele criar a AxHost classe derivada. Por
exemplo, se o controle ActiveX tiver um membro chamado Layout, ele será
renomeado ctlLayout na classe derivada de AxHost porque o evento Layout é
definido dentro do .NET Framework.
Confira também
Segurança de Acesso ao Código
Controles e objetos programáveis comparados em diversas linguagens e
bibliotecas
Rotular controles Windows Forms
individuais e fornecer atalhos
Artigo • 02/06/2023
Os controles adicionados a Windows Forms têm propriedades e métodos que são

usados para especializar ainda mais a experiência do usuário. Personalizar sua interface
do usuário para atender às necessidades do usuário é extremamente importante para
aplicativos windows bem projetados.
Nesta seção
Descreve como atribuir um rótulo de texto a um controle.
Como definir a imagem exibida por um controle dos Windows Forms

Explica como configurar um controle para exibir imagens.
Como criar teclas de acesso para controles dos Windows Forms

Fornece informações sobre como criar atalhos de teclado predefinidos.
Fornecendo informações de acessibilidade para os controles de um Windows Form

Fornece informações sobre como habilitar seus controles para trabalhar com auxílios de
acessibilidade.
Links para outras coisas básicas que você pode fazer com controles.
Como criar chaves de acesso para
Artigo • 02/06/2023
Uma chave de acesso é um caractere de sublinhado no texto de um menu, item de menu

ou rótulo de um controle como um botão. Com uma chave de acesso, o usuário pode
"clicar" em um botão pressionando a tecla Alt em combinação com a chave de acesso
predefinida. Por exemplo, se um botão executa um procedimento para imprimir um
formulário e, portanto, sua Text propriedade é definida como "Imprimir", adicionando
uma escarpa antes que a letra "P" faz com que a letra "P" seja sublinhada no texto do
botão em tempo de execução. O usuário pode executar o comando associado ao botão
pressionando Alt+P.
Os controles que não podem receber o foco não podem ter chaves de acesso.
Programático
Defina a Text propriedade como uma cadeia de caracteres que inclui uma ampersand
(&) antes da letra que será o atalho.
C#
// Set the letter "P" as an access key.

button1.Text = "&Print";
７ Observação
Para usar uma ampersand em uma legenda sem criar uma chave de acesso, inclua
duas escarpas (&&). Uma única ampersand é exibida na legenda e nenhum
caractere é sublinhado.
Designer
Na janela Propriedades do Visual Studio, defina a propriedade Text como uma cadeia
de caracteres que inclui uma escarpa ('&') antes da letra que será a chave de acesso. Por
exemplo, para definir a letra "P" como a chave de acesso, insira &Imprimir.
Confira também
Button
Como responder a cliques no botão dos Windows Forms
eles
Como definir o texto exibido por um
controle Windows Forms
Artigo • 02/06/2023
Windows Forms controles geralmente exibem alguns textos relacionados à função

primária do controle. Por exemplo, um Button controle geralmente exibe uma legenda
indicando qual ação será executada se o botão for clicado. Para todos os controles, você
pode definir ou retornar o texto usando a Text propriedade. Você pode alterar a fonte
usando a Font propriedade.
Você também pode definir o texto usando o designer.
Programático
1. Defina a Text propriedade como uma cadeia de caracteres.
Para criar uma chave de acesso sublinhada, inclui um escarp (&) antes da letra que
será a chave de acesso.
2. Defina a Font propriedade como um objeto do tipo Font.
C#
button1.Text = "Click here to save changes";

button1.Font = new Font("Arial", 10, FontStyle.Bold,
GraphicsUnit.Point);
７ Observação
Você pode usar um caractere de escape para exibir um caractere especial nos
elementos de interface do usuário que seriam normalmente interpretados de
maneira diferente, como itens de menu. Por exemplo, a seguinte linha de
código define o texto do item de menu para ler "& Now For Something
Completely Different":
C#
mpMenuItem.Text = "&& Now For Something Completely Different";

Designer
1. Na janela Propriedades em Visual Studio, defina a propriedade Text do controle
como uma cadeia de caracteres apropriada.
Para criar uma tecla de atalho sublinhada, inclui um escarp (&) antes da letra que
será a tecla de atalho.
2. Na janela Propriedades , selecione o botão de reticências ( ) ao lado da

propriedade Fonte .
Na caixa de diálogo de fonte padrão, escolha a fonte, o estilo da fonte, o tamanho,

efeitos (como riscado ou sublinhado) e o script que você deseja.
Confira também
Control.Text
Como definir a imagem exibida por um
controle Windows Forms
Artigo • 02/06/2023
Vários controles de Windows Forms podem exibir imagens. Essas imagens podem ser
ícones que esclarecem a finalidade do controle, como um ícone de diskette em um
botão que indica o comando Salvar. Como alternativa, os ícones podem ser imagens em
segundo plano para dar ao controle a aparência e o comportamento desejados.
Programático
Defina a propriedade ou BackgroundImage o Image controle como um objeto do
tipoImage. Em geral, você carregará a imagem de um arquivo usando o FromFile
método.
No exemplo de código a seguir, o conjunto de caminhos para o local da imagem é a

pasta Minhas Imagens . A maioria dos computadores que executam o sistema
operacional Windows inclui esse diretório. Isso também permite que usuários com
níveis mínimos de acesso do sistema executem o aplicativo com segurança. O exemplo
de código a seguir requer que você já tenha um formulário com um PictureBox controle
adicionado.
C#
// Replace the image named below with your own icon.

// Note the escape character used (@) when specifying the path.
pictureBox1.Image = Image.FromFile
(System.Environment.GetFolderPath
(System.Environment.SpecialFolder.MyPictures)
+ @"\Image.gif");
Designer
1. Na janela Propriedades do Visual Studio, selecione a propriedade Image ou
BackgroundImage do controle e selecione as reticências ( ) para exibir a caixa de
diálogo Selecionar Recurso .
2. Selecione a imagem que você deseja exibir.

Confira também
FromFile
Image
BackgroundImage
Fornecendo informações de
acessibilidade para controles em um
Windows Form
Artigo • 02/06/2023
Os recursos de acessibilidade são programas e dispositivos especializados que ajudam

as pessoas com deficiência a usarem computadores de forma mais eficaz. Alguns
exemplos incluem leitores de tela para pessoas cegas e utilitários de entrada de voz
para as pessoas que fornecem comandos verbais em vez de usar o mouse ou teclado.
Esses recursos de acessibilidade interagem com as propriedades de acessibilidade
expostas pelos controles dos Windows Forms. Essas propriedades são:
AccessibilityObject
AccessibleDefaultActionDescription
AccessibleDescription
AccessibleName
AccessibleRole
Propriedade AccessibilityObject
Essa propriedade somente leitura contém uma AccessibleObject instância. O
AccessibleObject implementa a IAccessible interface, que fornece informações sobre a
descrição do controle, o local da tela, as habilidades de navegação e o valor do controle.
O designer define esse valor quando o controle é adicionado ao formulário.
Propriedade
AccessibleDefaultActionDescription
Essa cadeia de caracteres descreve as ações do controle. Ela não aparece na janela
Propriedades e só pode ser definido no código. O exemplo a seguir define essa
propriedade para um controle de botão:
C#
Button1.AccessibleDefaultActionDescription =
"Closes the application.";
Propriedade AccessibleDescription
Essa cadeia de caracteres descreve o controle. Ele pode ser definido na janela
Propriedades ou no código da seguinte maneira:
C#
Button1.AccessibleDescription = "A button with text 'Exit'";
Propriedade AccessibleName
Esse é o nome de um controle relatado para os recursos de acessibilidade. Ele pode ser
definido na janela Propriedades ou no código da seguinte maneira:
C#
Button1.AccessibleName = "Order";
Propriedade AccessibleRole
Essa propriedade, que contém uma AccessibleRole enumeração, descreve a função de
interface do usuário do controle. Um novo controle tem o valor definido como Default .
Isso significa que, por padrão, um controle Botão atua como um Botão. Pode ser útil
redefinir essa propriedade se um controle tiver outra função. Por exemplo, você pode
estar usando um controle PictureBox como um Gráfico e pode desejar que os recursos
de acessibilidade relatem a função como um Gráfico, não como PictureBox. Também
pode ser útil especificar essa propriedade para controles personalizados desenvolvidos
por você. Essa propriedade pode ser definida na janela Propriedades ou no código da
seguinte maneira:
C#
PictureBox1.AccessibleRole = AccessibleRole.Chart;
Confira também
AccessibleObject
Control.AccessibilityObject
Control.AccessibleDefaultActionDescription
Control.AccessibleDescription
Control.AccessibleName
Control.AccessibleRole
AccessibleRole
Controles a serem usados nos Windows
Forms
Artigo • 02/06/2023
Esta é uma lista alfabética de controles e componentes que podem ser usados nos
Windows Forms. Além dos controles dos Windows Forms abordados nesta seção, você
pode adicionar ActiveX e controles personalizados ao Windows Forms. Se não encontrar
o controle necessário listado aqui, você poderá criar seus próprios. Para mais detalhes,
consulte Desenvolvendo controles dos Windows Forms no tempo de design. Para mais
informações sobre como escolher o controle necessário, consulte Controles dos
Windows Forms por função.
７ Observação
Visual Basic controles são baseados em classes fornecidas pelo .NET Framework.
Nesta seção
Lista e descreve os Windows Forms baseados no .NET Framework.
Controles com suporte de desenho do proprietário interno

Descreve como alterar aspectos da aparência de um controle que não estão disponíveis
por meio de propriedades.
Componente BackgroundWorker
Permite que um formulário ou controle execute uma operação assíncrona.
Controle BindingNavigator
Fornece interface do usuário de navegação e manipulação para controles associados a
dados.
Componente BindingSource
Encapsula uma fonte de dados para associação aos controles.
Controle de botão
Apresenta um botão padrão que o usuário pode clicar para executar ações.
Controle CheckBox
Indica se uma condição é ativada ou desativada.
Controle CheckedListBox
Exibe uma lista de itens com uma caixa de seleção perto de cada item.
Componente ColorDialog
Permite que o usuário escolha uma cor de uma paleta em uma caixa de diálogo pré-
configurada e adicione cores personalizadas a essa paleta.
Controle ComboBox
Exibe dados em uma caixa de combinação suspensa.
Componente ContextMenu
Fornece aos usuários um menu facilmente acessível dos comandos usados com
frequência que são associados ao objeto selecionado. Embora ContextMenuStrip
substitua e adiciona funcionalidade ao ContextMenu controle de versões anteriores,
ContextMenu é mantido para compatibilidade com versões anteriores e uso futuro, se
assim desejar.
Controle ContextMenuStrip
Representa um menu de atalho. Embora ContextMenuStrip substitua e adiciona
funcionalidade ao ContextMenu controle de versões anteriores, ContextMenu é mantido
para compatibilidade com versões anteriores e uso futuro, se assim desejar.
Controle DataGrid
Exibe dados tabulares de um conjunto de dados e permite atualizações para a fonte de
dados.
Controle DataGridView
Fornece um sistema flexível e extensível para exibir e editar dados tabulares.
Controle DateTimePicker
Permite que o usuário selecione um único item de uma lista de datas ou horas.
Controles e componentes da caixa de diálogo

Descreve um conjunto de controles que permitem aos usuários executar interações
padrão com o aplicativo ou o sistema.
Controle DomainUpDown
Exibe as cadeias de caracteres de texto que um usuário pode procurar e selecionar.
Componente ErrorProvider
Exibe informações de erro para o usuário de forma não intrusiva.
Classe FileDialog Fornece funcionalidade de classe base para caixas de diálogo de

arquivo.
Controle FlowLayoutPanel
Representa um painel que dispõe de forma dinâmica o conteúdo horizontal ou
verticalmente.
Componente FolderBrowserDialog
Exibe uma interface com a qual os usuários podem procurar e selecionar um diretório
ou criar um novo.
Componente FontDialog
Expõe as fontes atualmente instaladas no sistema.
Controle GroupBox
Fornece um agrupamento de identificação para outros controles.
Componente HelpProvider
Associa um arquivo de Ajuda em HTML com um aplicativo baseado em Windows.
Controles HScrollBar e VScrollBar

Fornece navegação por meio de uma lista de itens ou uma grande quantidade de
informações ao rolar horizontal ou verticalmente dentro de um aplicativo ou controle.
Componente ImageList
Exibe imagens em outros controles.
Controle de rótulo
Exibe o texto que não pode ser editado pelo usuário.
Controle LinkLabel
Permite que você adicione links no estilo Web para aplicativos dos Windows Forms.
Controle ListBox
Permite que o usuário selecione um ou mais itens de uma lista predefinida.
Controle ListView
Exibe uma lista de itens com ícones, da maneira do Windows Explorer.
Componente MainMenu
Exibe um menu no tempo de execução. Embora MenuStrip substitua e adicione
funcionalidade ao controle MainMenu de versões anteriores, MainMenu é mantido para
compatibilidade com versões anteriores e uso futuro, se desejado.
Controle MaskedTextBox
Restringe o formato da entrada de usuário em um formulário.
Controle MenuStrip
Fornece um sistema de menus para um formulário. Embora MenuStrip substitua e
adicione funcionalidade ao controle MainMenu de versões anteriores, MainMenu é
mantido para compatibilidade com versões anteriores e uso futuro, se desejado.
Controle MonthCalendar
Apresenta uma interface gráfica intuitiva para os usuários exibirem e definirem as
informações de data.
Componente NotifyIcon
Exibe ícones para processos que são executados em segundo plano e não teriam
interfaces do usuário.
Controle NumericUpDown
Exibe os números que um usuário pode procurar e selecionar.
Componente OpenFileDialog
Permite aos usuários abrir arquivos por meio de uma caixa de diálogo pré-configurada.
Componente PageSetupDialog
Define detalhes de páginas para impressão por meio de uma caixa de diálogo pré-
configurada.
Controle do painel
Fornece um agrupamento de identificação para outros controles e permite a rolagem.
Controle PictureBox
Exibe gráficos em formato de bitmap, GIF, JPEG, metarquivo ou ícone.
Componente PrintDialog
Seleciona uma impressora, escolhe as páginas a serem impressas e determina as outras
configurações relacionadas à impressão.
Componente PrintDocument
Define as propriedades que descrevem o que imprimir e imprime o documento em
aplicativos baseados no Windows.
Controle PrintPreviewControl
Permite que você crie seus próprios PrintPreview componentes ou caixa de diálogo em
vez de usar a versão previamente configurada.
Controle PrintPreviewDialog
Exibe um documento como ele aparecerá quando for impresso.
Controle ProgressBar
Indica o andamento de uma ação em relação à conclusão graficamente.
Controle RadioButton
Apresenta um conjunto de duas ou mais opções mutuamente exclusivas para o usuário.
Controle RichTextBox
Permite aos usuários inserir, exibir e manipular texto com formatação.
Componente SaveFileDialog
Seleciona os arquivos a serem salvos e onde salvá-los.
Classe SoundPlayer Permite que você inclua facilmente sons em seus aplicativos.
Controle SplitContainer
Permite que o usuário redimensione um controle encaixado.
Controle Divisor
Permite que o usuário resize um controle encaixado (.NET Framework versão 1.x).
Controle StatusBar
Exibe informações de status relacionadas ao controle que tem o foco. Embora o
StatusStrip substitua e estenda o controle StatusBar de versões anteriores, StatusBar é
mantido para compatibilidade com versões anteriores e uso futuro, se desejado.
Controle StatusStrip
Representa um controle de barra de status do Windows. Embora o StatusStrip substitua
e estenda o controle StatusBar de versões anteriores, StatusBar é mantido para
compatibilidade com versões anteriores e uso futuro, se desejado.
Controle TabControl
Exibe várias guias que podem conter imagens ou outros controles.
Controle TableLayoutPanel
Representa um painel que dispõe de forma dinâmica o conteúdo em uma grade
composta por linhas e colunas.
Controle TextBox
Permite entrada editável de várias linhas do usuário.
Componente de Temporizador
Gera um evento em intervalos regulares.
Controle ToolBar
Exibe os menus e botões de bitmap que ativam comandos. Você pode estender a
funcionalidade do controle e modificar sua aparência e comportamento. Embora
ToolStrip substitua e adicione funcionalidade ao controle ToolBar de versões anteriores,
ToolBar é mantido para compatibilidade com versões anteriores e uso futuro, se
desejado.
Controle ToolStrip
Cria menus e barras de ferramentas personalizadas em seus aplicativos dos Windows
Forms. Embora ToolStrip substitua e adicione funcionalidade ao controle ToolBar de
versões anteriores, ToolBar é mantido para compatibilidade com versões anteriores e
uso futuro, se desejado.
Controle ToolStripContainer
Fornece painéis em cada lado de um formulário para encaixar, ToolStrip reacoplar e
organizar controles e um central ToolStripContentPanel para controles tradicionais.
Controle ToolStripPanel
Fornece um painel para encaixar, reacoplar e organizar controles ToolStrip .
Visão geral do controle ToolStripProgressBar

Indica o andamento de uma ação em relação à conclusão graficamente. O
ToolStripProgressBar normalmente está contido em um StatusStrip.
Controle ToolStripStatusLabel
Representa um painel em um controle StatusStrip.
Componente ToolTip
Exibe o texto quando o usuário aponta para outros controles.
Controle TrackBar
Permite a navegação por meio de uma grande quantidade de informações ou ajuste
visual de uma configuração numérica.
Controle TreeView
Exibe uma hierarquia de nós que podem ser expandidos ou recolhidos.
Controle WebBrowser
Hospeda páginas da Web e fornece recursos de navegação na Internet para seu
aplicativo.
Controles dos Windows Forms usados para listar opções

Descreve um conjunto de controles usados para fornecer aos usuários uma lista de
opções de escolha.
Explica o uso de controles dos Windows Forms e descreve conceitos importantes para
trabalhar com eles.

Fornece links para tópicos passo a passo, recomendações sobre qual tipo de controle
criar e outras informações sobre como criar seu próprio controle.
Controles e objetos programáveis comparados em diversas linguagens e bibliotecas

Fornece uma tabela que mapeia controles Visual Basic 6.0 para o controle
correspondente no Visual Basic .NET. Observe que os controles agora são classes no
.NET Framework.

Descreve como usar controles ActiveX em Windows Forms.
Controles dos Windows Forms por
função
Artigo • 02/06/2023
O Windows Forms oferece controles e componentes que executam várias funções. A

tabela a seguir lista os controles e componentes dos Windows Forms de acordo com a
função geral. Além disso, quando há vários controles que têm a mesma função, o
controle recomendado é listado com uma observação sobre o controle que foi
substituído por ele. Em uma tabela separada posterior, os controles substituídos são
listados com suas substituições recomendadas.
７ Observação
As tabelas a seguir não listam todos os controles ou componentes que você pode
usar nos Windows Forms. Para obter uma lista mais abrangente, consulte Controles
a serem usados nos Windows Forms
Controles e componentes recomendados

Função Control Descrição
Exibição de Controle O DataGridView controle fornece uma tabela

dados DataGridView personalizável para exibir dados. A DataGridView classe
permite a personalização de células, linhas, colunas e
bordas. Nota: O DataGridView controle fornece vários
recursos básicos e avançados que estão ausentes no
DataGrid controle. Para obter mais informações,
consulte Diferenças entre o Windows Forms
DataGridView e os Controles do DataGrid
Vinculação de componente Simplifica a associação de controles em um formulário

dados e BindingSource a dados, fornecendo gerenciamento de moeda,
navegação notificação de alteração e outros serviços.
Controle Fornece uma interface do tipo de barra de ferramentas

BindingNavigator para navegar e manipular dados em um formulário.
Edição de texto Controle TextBox Exibe o texto inserido em tempo de design que pode
ser editado por usuários em tempo de execução ou ser
modificado programaticamente.
Controle Permite que o texto seja exibido formatado em texto

RichTextBox sem formatação ou em RTF (Formato Rich Text).
Controle Restringe o formato da entrada do usuário

MaskedTextBox
Exibição de Controle Label Exibe o texto que os usuários não podem editar
informações diretamente.
(somente
leitura)
Controle LinkLabel Exibe o texto como um link com estilo da Web e

dispara um evento quando o usuário clica no texto
especial. Normalmente, o texto é um link para outra
janela ou site.
Controle StatusStrip Exibe informações sobre o estado atual do aplicativo

usando uma área com quadros, geralmente na parte
inferior de um formulário pai.
Controle Exibe o progresso atual de uma operação para o

ProgressBar usuário.
Exibição de Controle Permite ao usuário navegar em páginas da Web dentro

página da Web WebBrowser do seu formulário.
Seleção de uma Controle Exibe uma lista rolável de itens, cada um deles
lista CheckedListBox acompanhado por uma caixa de seleção.
Controle ComboBox Exibe uma lista suspensa de itens.
Controle Exibe uma lista de itens de texto que os usuários

DomainUpDown podem percorrer usando os botões para cima e para
baixo.
Controle ListBox Exibe uma lista de texto e itens gráficos (ícones).
Controle ListView Exibe os itens em um dos quatro modos de exibição

diferentes. Os modos de exibição incluem somente
texto, texto com ícones pequenos, texto com ícones
grandes e exibição de detalhes.
Controle Exibe uma lista de numerais que os usuários podem

NumericUpDown percorrer usando os botões para cima e para baixo.
Controle TreeView Exibe uma coleção hierárquica de objetos de nó que

podem consistir em texto com caixas de seleção
opcionais ou ícones.
Exibição de Controle PictureBox Exibe arquivos gráficos, como bitmaps e ícones, em um

gráficos quadro.
Armazenamento Controle ImageList Serve como um repositório de imagens. ImageList os

de gráficos controles e as imagens que eles contêm podem ser
reutilizados de um aplicativo para o próximo.
Configuração do Controle CheckBox Exibe uma caixa de seleção e um rótulo de texto.

valor Geralmente, é usado para definir opções.
Controle Exibe uma lista rolável de itens, cada um deles

CheckedListBox acompanhado por uma caixa de seleção.
Controle Exibe um botão que pode ser ativado ou desativado.

RadioButton
Controle TrackBar Permite aos usuários definir valores em uma escala

movendo um "controle de posição" ao longo da escala.
Configuração de Controle Exibe um calendário gráfico para permitir que os

data DateTimePicker usuários selecionem uma data ou hora.
Controle Exibe um calendário gráfico para permitir que os

MonthCalendar usuários selecionem um intervalo de datas.
Caixas de Controle Exibe a caixa de diálogo do seletor de cor que permite

diálogo ColorDialog que os usuários definam a cor de um elemento de
interface.
Controle FontDialog Exibe uma caixa de diálogo que permite que os

usuários definam uma fonte e seus atributos.
Controle Exibe uma caixa de diálogo que permite que os

OpenFileDialog usuários naveguem até um arquivo e o selecionem.
Controle PrintDialog Exibe uma caixa de diálogo que permite que os

usuários selecionem uma impressora e definam seus
atributos.
Controle Exibe uma caixa de diálogo que exibe como um

PrintPreviewDialog componente de PrintDocument controle será exibido
quando impresso.

FolderBrowserDialog usuários naveguem, criem e, eventualmente,
selecionem uma pasta

SaveFileDialog usuários salvem um arquivo.
Controles de Controle MenuStrip Cria menus personalizados. Nota: O MenuStrip foi

menu projetado para substituir o MainMenu controle .
Controle Cria menus de contexto personalizados. Observação: O

ContextMenuStrip ContextMenuStrip é projetado para substituir o
ContextMenu controle.
Comandos Controle Button Inicia, para ou interrompe um processo.

janela ou site.
Controle NotifyIcon Exibe um ícone na área de notificação de status da

barra de tarefas que representa um aplicativo em
execução em segundo plano.
Controle ToolStrip Cria barras de ferramentas que podem ter a aparência

do Microsoft Windows XP, Microsoft Office, Microsoft
Internet Explorer ou uma aparência personalizada, com
ou sem temas e com suporte para estouro e
reordenação de itens em tempo de execução.
Observação: O ToolStrip controle foi projetado para
substituir o ToolBar controle.
Ajuda do componente Fornece Ajuda pop-up ou online para os controles.

usuário HelpProvider
componente ToolTip Fornece uma janela pop-up que exibe uma breve
descrição da finalidade do controle quando o usuário
deixa o ponteiro sobre o controle.
Agrupando Controle Panel Agrupa um conjunto de controles em um quadro

outros controles rolável sem rótulo.
Controle GroupBox Agrupa um conjunto de controles (como botões de

opção) em um quadro não rolável rotulado.
Controle TabControl Fornece uma página com guias para organizar e

acessar objetos agrupados com eficiência.
Controle Fornece dois painéis separados por uma barra móvel.

SplitContainer Observação: O SplitContainer controle foi projetado
para substituir o Splitter controle.
Controle Representa um painel que dispõe de forma dinâmica o

TableLayoutPanel conteúdo em uma grade composta por linhas e
colunas.

FlowLayoutPanel conteúdo horizontal ou verticalmente.
Áudio Controle Reproduz arquivos de som no formato .wav. Os sons

SoundPlayer podem ser carregados ou executados de forma
assíncrona.
Controles e componentes substituídos por

função
Função Controle Substituição
substituído recomendada
Exibição de dados DataGrid DataGridView
Exibição de informações (controles somente StatusBar StatusStrip

leitura)
Controles de menu ContextMenu ContextMenuStrip
MainMenu MenuStrip
Comandos ToolBar ToolStrip
StatusBar StatusStrip
Layout de formulários Splitter SplitContainer
Confira também
Desenvolvendo controles dos Windows Forms personalizados com o .NET
Framework
Controles com suporte de desenho do
proprietário interno
Artigo • 02/06/2023
Proprietário do desenho nos Windows Forms, que é também conhecido como desenho
personalizado, é uma técnica para alterar a aparência visual de certos controles.
７ Observação
A palavra "controle" neste tópico é usada para significar classes que derivam de um
Control ou Component.
Normalmente, o Windows manipula a pintura automaticamente usando configurações

de propriedade, como BackColor para determinar a aparência de um controle. Com o
desenho do proprietário, assumir o processo de pintura, alterando os elementos que
não estão disponíveis usando propriedades de aparência. Por exemplo, muitos controles
permitem que você defina a cor do texto que é exibido, mas você está limitado a uma
única cor. Desenho do proprietário permite que você faça coisas como parte do texto
de exibição em preto e parte em vermelho.
Na prática, o desenho do proprietário é semelhante ao desenho de gráficos em um

formulário. Por exemplo, você poderia usar métodos gráficos em um manipulador para
o evento do formulário para emular um ListBox controle, mas precisaria escrever seu
próprio código para lidar com toda a interação do Paint usuário. Com o desenho do
proprietário, o controle usa seu código para desenhar seu conteúdo, mas caso contrário
retém todos os seus recursos intrínsecos. Você pode usar métodos gráficos para
desenhar cada item no controle ou personalizar alguns aspectos de cada item enquanto
você usa a aparência padrão para outros aspectos de cada item.
Desenho do proprietário no Controle dos

Windows Forms
Para executar o desenho do proprietário na controles que oferecem suporte a ele, você
normalmente define uma propriedade e manipular um ou mais eventos.
A maioria dos controles têm de desenho do proprietário que suporte uma propriedade
OwnerDraw ou DrawMode que indica se o controle será aumentará seu evento ou eventos
de desenho quando ela pinta a si mesma.

Controles que não têm uma propriedade OwnerDraw ou DrawMode , incluem o
DataGridView controle, que fornece eventos de desenho que ocorrem automaticamente
e o ToolStrip controle, que é desenhado usando uma classe de renderização externa
que tem seus próprios eventos relacionados ao desenho.
Há muitos tipos diferentes de eventos de desenho, mas ocorre um evento típico de

desenho para desenhar um único item em um controle. O manipulador de eventos
recebe um EventArgs objeto que contém informações sobre o item que está sendo
desenhado e ferramentas que você pode usar para desenhá-lo. Por exemplo, esse
objeto normalmente contém o número de índice do item dentro de sua coleção pai, um
Rectangle que indica os limites de exibição do item e um Graphics objeto para chamar
métodos de tinta. Em alguns casos, o EventArgs objeto fornece informações adicionais
sobre o item e os métodos que você pode chamar para pintar alguns aspectos do item
por padrão, como a tela de fundo ou um retângulo de foco.
Para criar um controle reutilizável que contém as personalizações desenhados pelo

proprietário, crie uma nova classe que deriva de uma classe de controle que dá suporte
ao desenho do proprietário. Em vez de manipular eventos de desenho, incluir o código
de desenho do proprietário em substituições de método ou métodos apropriados de
On EventName na nova classe. Certifique-se de que você chamar o método ou métodos
da classe base On EventName nesse caso, para que os usuários de seu controle possam
manipular eventos de desenho do proprietário e fornecer personalização adicional.
O Windows Forms a seguir controla desenho do proprietário em todas as versões do

.NET Framework:
ListBox
ComboBox
MenuItem (usado por MainMenu e ContextMenu)
TabControl
Os controles a seguir dão suporte ao desenho do proprietário somente no .NET

Framework 2.0:
ToolTip
ListView
TreeView
Os controles a seguir dão suporte ao desenho do proprietário e são novos no .NET
Framework 2.0:
DataGridView
ToolStrip
As seções a seguir fornecem detalhes adicionais para cada um desses controles.
Controles de Caixa de Combinação e Caixa de listagem

Os ListBox controles e os ComboBox controles permitem que você desenhe itens
individuais no controle, todos em um tamanho ou em tamanhos variados.
７ Observação
Embora o CheckedListBox controle seja derivado do controle, ele não dá suporte

ao ListBox desenho do proprietário.
Para desenhar cada item do mesmo tamanho, defina a DrawMode propriedade como
OwnerDrawFixed e manipule o DrawItem evento.
Para desenhar cada item usando um tamanho diferente, defina a DrawMode propriedade
OwnerDrawVariable como e manipule os eventos e DrawItem os MeasureItem eventos. O
evento MeasureItem permite indicar o tamanho de um item antes do evento DrawItem
ocorrer para aquele item.
Para obter mais informações, incluindo exemplos de código, consulte os seguintes

tópicos:
ListBox.DrawMode
ListBox.MeasureItem
ListBox.DrawItem
ComboBox.DrawMode
ComboBox.MeasureItem
ComboBox.DrawItem
Como: Criar texto dimensionado da variável em um controle ComboBox

Componente do MenuItem
O MenuItem componente representa um único item de menu em um MainMenu ou
ContextMenu componente.
Para desenhar um MenuItem, defina sua OwnerDraw propriedade e true manipule seu
DrawItem evento. Para personalizar o tamanho do item de menu antes do evento
DrawItem ocorrer, identifique os eventos MeasureItem do item.

tópicos de referência:
MenuItem.OwnerDraw
MenuItem.DrawItem
MenuItem.MeasureItem
Controle TabControl
O TabControl controle permite desenhar guias individuais no controle. O desenho do
proprietário afeta apenas as guias; o TabPage conteúdo não é afetado.
Para desenhar cada guia em uma TabControl, defina a DrawMode propriedade

OwnerDrawFixed como e manipule o DrawItem evento. Esse evento ocorre uma vez para
cada guia somente quando a guia estiver visível no controle.

TabControl.DrawMode
TabControl.DrawItem
Componente ToolTip
O ToolTip componente permite que você desenhe toda a Dica de Ferramenta quando
ela é exibida.
Para desenhar um ToolTip, defina sua OwnerDraw propriedade e true manipule seu Draw
evento. Para personalizar o tamanho do antes Draw do ToolTip evento ocorrer, manipule
o Popup evento e defina a ToolTipSize propriedade no manipulador de eventos.
ToolTip.OwnerDraw
ToolTip.Draw
ToolTip.Popup
Controle ListView
O ListView controle permite que você desenhe itens individuais, subitens e cabeçalhos
de coluna no controle.
Para habilitar o controle de desenho do proprietário, defina a propriedade OwnerDraw

para true .
Para desenhar cada item no controle, identifique o evento DrawItem .
Para desenhar cada subitem ou cabeçalho de coluna no controle quando a View

propriedade estiver definida comoDetails, manipule o e DrawColumnHeader os
DrawSubItem eventos.

ListView.OwnerDraw
ListView.DrawItem
ListView.DrawSubItem
ListView.DrawColumnHeader
Controle TreeView
O TreeView controle permite que você desenhe nós individuais no controle.
Para desenhar apenas o texto exibido em cada nó, defina a DrawMode propriedade
OwnerDrawText e manipule o DrawNode evento para desenhar o texto.
Para desenhar todos os elementos de cada nó, defina a DrawMode propriedade

OwnerDrawAll e manipule o DrawNode evento para desenhar todos os elementos
necessários, como texto, ícones, caixas de seleção, sinais de adição e menos e linhas que
conectam os nós.

TreeView.DrawMode
TreeView.DrawNode
O DataGridView controle permite que você desenhe células e linhas individuais no
controle.
Para desenhar células individuais, identifique o evento CellPainting .
Para desenhar linhas individuais ou elementos de linhas, identifique um ou ambos os

eventos RowPrePaint e RowPostPaint . O evento RowPrePaint ocorre antes das células em
uma linha serem pintadas e o evento RowPostPaint ocorre depois que as células são
pintadas. Você pode identificar ambos os eventos e o evento CellPainting para pintar a
tela de fundo de linha, células individuais e primeiro plano linha separadamente ou você
pode fornecer personalizações específicas em que você precisa deles e use a exibição
padrão para outros elementos da linha.

tópicos:
CellPainting
RowPrePaint
RowPostPaint
Como personalizar a aparência de células no controle DataGridView dos Windows

Forms
Como: Personalizar a aparência de linhas no controle DataGridView do Windows

Forms
Controle ToolStrip
ToolStrip e controles derivados permitem que você personalize qualquer aspecto de sua
aparência.
Para fornecer renderização personalizada para ToolStrip controles, defina a Renderer
propriedade de umToolStrip, ToolStripManagerToolStripPanelou ToolStripContentPanel
para um ToolStripRenderer objeto e manipule um ou mais dos muitos eventos de
desenho fornecidos pela ToolStripRenderer classe. Como alternativa, defina uma
Renderer propriedade como uma instância de sua própria classe derivada de
ToolStripRenderer , ToolStripProfessionalRendererou ToolStripSystemRenderer que
implemente ou substitua métodos EventName específicos On .

tópicos:
ToolStripRenderer
Como: Criar e definir um renderizador personalizado para o controle ToolStrip no

Windows Forms
Como: Personalizar o desenho de um controle ToolStrip
Confira também
Artigo • 02/06/2023
O componente BackgroundWorker permite que seu formulário ou controle execute uma

operação assíncrona.
Nesta seção
Visão geral do componente BackgroundWorker
Descreve o componente BackgroundWorker , que permite executar operações demoradas
de forma assíncrona ("no segundo plano"), em um thread diferente do thread principal
da interface do usuário do aplicativo.
Passo a passo: Executando uma operação em segundo plano

Demonstra como usar o componente BackgroundWorker no designer para executar uma
operação demorada em um thread separado.
Como: Executar uma operação em segundo plano

Demonstra como usar o componente BackgroundWorker para executar uma operação
demorada em um thread separado.
Passo a passo: Implementando um formulário que usa uma operação em segundo plano
Cria um aplicativo usando o designer que faz cálculos matemáticos de forma assíncrona.
Como: Implementar um formulário que usa uma operação em segundo plano

Cria um aplicativo que faz cálculos matemáticos de forma assíncrona.
Como: Como baixar um arquivo em segundo plano

Demonstra como usar o componente BackgroundWorker para baixar um arquivo em um
thread separado.
Referência
BackgroundWorker
Descreve essa classe e tem links para todos os seus membros.
RunWorkerCompletedEventArgs
Descreve o tipo que contém dados para o RunWorkerCompleted evento.
ProgressChangedEventArgs
Descreve o tipo que contém dados para o ProgressChanged evento.
Visão geral do padrão assíncrono baseado em evento
Descreve como o padrão assíncrono disponibiliza as vantagens de aplicativos de vários
threads enquanto oculta muitos problemas complexos inerentes ao design com vários
threads.
Visão geral do componente
BackgroundWorker
Artigo • 02/06/2023
Há muitas operações realizadas com frequência que podem levar muito tempo para
serem executadas. Por exemplo:
Downloads de imagens
Invocações de serviço Web
Downloads e uploads de arquivos (inclusive de aplicativos ponto a ponto)
Cálculos locais complexos
Transações de banco de dados
Acesso ao disco local, dada a sua baixa velocidade em relação ao acesso à

memória
Operações como essas podem fazer com que a interface do usuário seja bloqueada
durante a execução. Se você quer uma interface que responda com agilidade e está
enfrentando longos atrasos associados a essas operações, o componente
BackgroundWorker fornece uma solução conveniente.
O componente BackgroundWorker possibilita executar operações demoradas de forma

assíncrona ("no segundo plano"), em um thread diferente do thread principal da
interface do usuário do aplicativo. Para usar um BackgroundWorker, basta indicar o
método de trabalho demorado que será executado em segundo plano e chamar o
método RunWorkerAsync. Seu thread de chamada continua a funcionar normalmente
enquanto o método de trabalho é executado de forma assíncrona. Quando o método é
concluído, o BackgroundWorker alerta o thread de chamada disparando o evento
RunWorkerCompleted, que contém, opcionalmente, os resultados da operação.
O BackgroundWorker componente está disponível na caixa de ferramentas, na guia

Componentes . Para adicionar um BackgroundWorker ao formulário, arraste o
componente para o BackgroundWorker formulário. Ele aparece na bandeja de
componentes e suas propriedades aparecem na janela Propriedades.
Para iniciar a operação assíncrona, use o método RunWorkerAsync. RunWorkerAsync

usa um parâmetro opcional object , que pode ser usado para passar argumentos para o
seu método de trabalho. A classe BackgroundWorker expõe o evento DoWork, ao qual o
seu thread de trabalho está anexado por meio de um manipulador de eventos DoWork.
O manipulador de eventos DoWork usa um parâmetro DoWorkEventArgs, que tem uma

propriedade Argument. Esta propriedade recebe o parâmetro de RunWorkerAsync e
pode ser passada para o seu método de trabalho, que será chamado no manipulador de
eventos DoWork. O exemplo a seguir mostra como atribuir um resultado de um método
de trabalho chamado ComputeFibonacci . Ele faz parte de um exemplo maior, que pode
ser encontrado em Como implementar um formulário que usa uma operação em
segundo plano.
C#
// This event handler is where the actual,

// potentially time-consuming work is done.
private void backgroundWorker1_DoWork(object sender,
DoWorkEventArgs e)
{
// Get the BackgroundWorker that raised this event.
BackgroundWorker worker = sender as BackgroundWorker;
// Assign the result of the computation

// to the Result property of the DoWorkEventArgs
// object. This is will be available to the
// RunWorkerCompleted eventhandler.
e.Result = ComputeFibonacci((int)e.Argument, worker, e);
}
Para obter mais informações sobre o uso de manipuladores de eventos, consulte

Eventos.
Ｕ Cuidado
O uso de multithreading de qualquer tipo pode expor o computador a bugs muito

sérios e complexos. Consulte as Melhores práticas de threading gerenciado antes
de implementar qualquer solução que use multithreading.
Para obter mais informações sobre como usar a BackgroundWorker classe, consulte
Como executar uma operação em segundo plano.
Confira também
Threading gerenciado
Como: Executar uma operação em
segundo plano
Artigo • 02/06/2023
Se você tiver uma operação que levará muito tempo para ser concluída e não quiser
causar atrasos na interface do usuário, poderá usar a BackgroundWorker classe para
executar a operação em outro thread.
O exemplo de código a seguir mostra como executar uma operação demorada em

segundo plano. O formulário tem botões Iniciar e Cancelar . Clique no botão Iniciar
para executar uma operação assíncrona. Clique no botão Cancelar para interromper
uma operação assíncrona em execução. O resultado de cada operação é exibido em um
MessageBox .
Há um suporte abrangente para esta tarefa no Visual Studio.
Consulte também a explicação: executando uma operação em segundo plano.
Exemplo
C#
using System;
using System.ComponentModel;
using System.Drawing;
using System.Threading;
using System.Windows.Forms;
namespace BackgroundWorkerExample
{
public class Form1 : Form
{
public Form1()
{
InitializeComponent();
}
private void backgroundWorker1_DoWork(object sender, DoWorkEventArgs

e)
{
// Do not access the form's BackgroundWorker reference directly.
// Instead, use the reference provided by the sender parameter.
BackgroundWorker bw = sender as BackgroundWorker;
// Extract the argument.

int arg = (int)e.Argument;
// Start the time-consuming operation.
e.Result = TimeConsumingOperation(bw, arg);
// If the operation was canceled by the user,

// set the DoWorkEventArgs.Cancel property to true.
if (bw.CancellationPending)
{
e.Cancel = true;
}
}
// This event handler demonstrates how to interpret

// the outcome of the asynchronous operation implemented
// in the DoWork event handler.
private void backgroundWorker1_RunWorkerCompleted(
object sender,
RunWorkerCompletedEventArgs e)
{
if (e.Cancelled)
{
// The user canceled the operation.
MessageBox.Show("Operation was canceled");
}
else if (e.Error != null)
{
// There was an error during the operation.
string msg = String.Format("An error occurred: {0}",
e.Error.Message);
MessageBox.Show(msg);
}
else
{
// The operation completed normally.
string msg = String.Format("Result = {0}", e.Result);
}
}
// This method models an operation that may take a long time

// to run. It can be cancelled, it can raise an exception,
// or it can exit normally and return a result. These outcomes
// are chosen randomly.
private int TimeConsumingOperation(
BackgroundWorker bw,
int sleepPeriod )
{
int result = 0;
Random rand = new Random();
while (!bw.CancellationPending)
{
bool exit = false;
switch (rand.Next(3))
{
// Raise an exception.
case 0:
{
throw new Exception("An error condition occurred.");
break;
}
// Sleep for the number of milliseconds

// specified by the sleepPeriod parameter.
case 1:
{
Thread.Sleep(sleepPeriod);
break;
}
// Exit and return normally.

case 2:
{
result = 23;
exit = true;
break;
}
default:
{
break;
}
}
if( exit )
{
break;
}
}
return result;
}
private void startBtn_Click(object sender, EventArgs e)

{
this.backgroundWorker1.RunWorkerAsync(2000);
}
private void cancelBtn_Click(object sender, EventArgs e)

{
this.backgroundWorker1.CancelAsync();
}
/// <summary>
/// Required designer variable.
/// </summary>
private System.ComponentModel.IContainer components = null;
/// <summary>
/// Clean up any resources being used.
/// </summary>
/// <param name="disposing">true if managed resources should be
disposed; otherwise, false.</param>
protected override void Dispose(bool disposing)
{
if (disposing && (components != null))
{
components.Dispose();
}
base.Dispose(disposing);
}
#region Windows Form Designer generated code
/// <summary>
/// Required method for Designer support - do not modify
/// the contents of this method with the code editor.
/// </summary>
private void InitializeComponent()
{
this.backgroundWorker1 = new
System.ComponentModel.BackgroundWorker();
this.startBtn = new System.Windows.Forms.Button();
this.cancelBtn = new System.Windows.Forms.Button();
this.SuspendLayout();
//
// backgroundWorker1
//
this.backgroundWorker1.WorkerSupportsCancellation = true;
this.backgroundWorker1.DoWork += new
System.ComponentModel.DoWorkEventHandler(this.backgroundWorker1_DoWork);
this.backgroundWorker1.RunWorkerCompleted += new
System.ComponentModel.RunWorkerCompletedEventHandler(this.backgroundWorker1_
RunWorkerCompleted);
//
// startBtn
//
this.startBtn.Location = new System.Drawing.Point(12, 12);
this.startBtn.Name = "startBtn";
this.startBtn.Size = new System.Drawing.Size(75, 23);
this.startBtn.TabIndex = 0;
this.startBtn.Text = "Start";
this.startBtn.Click += new
System.EventHandler(this.startBtn_Click);
//
// cancelBtn
//
this.cancelBtn.Location = new System.Drawing.Point(94, 11);
this.cancelBtn.Name = "cancelBtn";
this.cancelBtn.Size = new System.Drawing.Size(75, 23);
this.cancelBtn.TabIndex = 1;
this.cancelBtn.Text = "Cancel";
this.cancelBtn.Click += new
System.EventHandler(this.cancelBtn_Click);
//
// Form1
//
this.AutoScaleDimensions = new System.Drawing.SizeF(6F, 13F);
this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
this.ClientSize = new System.Drawing.Size(183, 49);
this.Controls.Add(this.cancelBtn);
this.Controls.Add(this.startBtn);
this.Name = "Form1";
this.Text = "Form1";
this.ResumeLayout(false);
}
#endregion
private System.ComponentModel.BackgroundWorker backgroundWorker1;

private System.Windows.Forms.Button startBtn;
private System.Windows.Forms.Button cancelBtn;
}
public class Program

{
private Program()
{
}
/// <summary>
/// The main entry point for the application.
/// </summary>
[STAThread]
static void Main()
{
Application.EnableVisualStyles();
Application.Run(new Form1());
}
}
}
Compilando o código
Este exemplo requer:
Referências aos assemblies System, System.Drawing e System.Windows.Forms.
Confira também
BackgroundWorker
DoWorkEventArgs
Como: Como baixar um arquivo em
segundo plano
Artigo • 21/06/2023
Baixar um arquivo é uma tarefa comum e costuma ser útil executar esta operação
potencialmente demorada em um thread separado. Use o BackgroundWorker
componente para realizar essa tarefa com muito pouco código.
Exemplo
O exemplo de código a seguir demonstra como usar um BackgroundWorker
componente para carregar um arquivo XML de uma URL. Quando o usuário clica no
botão Baixar , o Click manipulador de eventos chama o RunWorkerAsync método de um
BackgroundWorker componente para iniciar a operação de download. O botão é
desabilitado durante o download e então habilitado quando o download for concluído.
Um MessageBox exibe o conteúdo do arquivo.
C#
using System;
using System.Collections.Generic;
using System.Xml;

{
private BackgroundWorker backgroundWorker1;
private Button downloadButton;
private ProgressBar progressBar1;
private XmlDocument document = null;
public Form1()
{
// Instantiate BackgroundWorker and attach handlers to its

// DoWork and RunWorkerCompleted events.
backgroundWorker1 = new System.ComponentModel.BackgroundWorker();
backgroundWorker1.DoWork += new
System.ComponentModel.DoWorkEventHandler(this.backgroundWorker1_DoWork);
backgroundWorker1.RunWorkerCompleted += new
System.ComponentModel.RunWorkerCompletedEventHandler(this.backgroundWorker1_
RunWorkerCompleted);
}
private void downloadButton_Click(object sender, EventArgs e)

{
// Start the download operation in the background.
this.backgroundWorker1.RunWorkerAsync();
// Disable the button for the duration of the download.

this.downloadButton.Enabled = false;
// Once you have started the background thread you

// can exit the handler and the application will
// wait until the RunWorkerCompleted event is raised.
// Or if you want to do something else in the main thread,

// such as update a progress bar, you can do so in a loop
// while checking IsBusy to see if the background task is
// still running.
while (this.backgroundWorker1.IsBusy)
{
progressBar1.Increment(1);
// Keep UI messages moving, so the form remains
// responsive during the asynchronous operation.
Application.DoEvents();
}
}
private void backgroundWorker1_DoWork(

object sender,
DoWorkEventArgs e)
{
document = new XmlDocument();
// Uncomment the following line to

// simulate a noticeable latency.
//Thread.Sleep(5000);
// Replace this file name with a valid file name.

document.Load(@"http://www.tailspintoys.com/sample.xml");
}

object sender,
{
// Set progress bar to 100% in case it's not already there.
progressBar1.Value = 100;
if (e.Error == null)
{
MessageBox.Show(document.InnerXml, "Download Complete");
}
else
{
MessageBox.Show(
"Failed to download file",
"Download failed",
MessageBoxButtons.OK,
MessageBoxIcon.Error);
}
// Enable the download button and reset the progress bar.

this.downloadButton.Enabled = true;
}
/// <summary>
/// </summary>
/// <summary>
/// </summary>
{
{
}
}
/// <summary>
/// Required method for Designer support
/// </summary>
{
this.downloadButton = new System.Windows.Forms.Button();
this.progressBar1 = new System.Windows.Forms.ProgressBar();
//
// downloadButton
//
this.downloadButton.Location = new System.Drawing.Point(12, 12);
this.downloadButton.Name = "downloadButton";
this.downloadButton.Size = new System.Drawing.Size(100, 23);
this.downloadButton.TabIndex = 0;
this.downloadButton.Text = "Download file";
this.downloadButton.UseVisualStyleBackColor = true;
this.downloadButton.Click += new
System.EventHandler(this.downloadButton_Click);
//
// progressBar1
//
this.progressBar1.Location = new System.Drawing.Point(12, 50);
this.progressBar1.Name = "progressBar1";
this.progressBar1.Size = new System.Drawing.Size(100, 26);
this.progressBar1.TabIndex = 1;
//
// Form1
//
this.Controls.Add(this.progressBar1);
this.Controls.Add(this.downloadButton);
}
#endregion
}
static class Program

{
/// <summary>
/// </summary>
[STAThread]
static void Main()
{
}
}
Baixando o arquivo
O arquivo é baixado no BackgroundWorker thread de trabalho do componente, que

executa o DoWork manipulador de eventos. Esse thread é iniciado quando o código
chama o RunWorkerAsync método .
C#

object sender,
DoWorkEventArgs e)
{
document = new XmlDocument();
// Uncomment the following line to

// simulate a noticeable latency.
//Thread.Sleep(5000);

document.Load(@"http://www.tailspintoys.com/sample.xml");
}
Aguardando a conclusão de um BackgroundWorker
O downloadButton_Click manipulador de eventos demonstra como esperar que um

BackgroundWorker componente conclua sua tarefa assíncrona.
Se você só deseja que o aplicativo responda a eventos e não quer realizar trabalhos no
thread principal enquanto aguarda o thread em segundo plano concluir, basta sair do
manipulador.
Se você quiser continuar trabalhando no thread main, use a IsBusy propriedade para
determinar se o BackgroundWorker thread ainda está em execução. No exemplo, uma
barra de progresso é atualizada enquanto o download é processado. Certifique-se de
chamar o Application.DoEvents método para manter a interface do usuário responsiva.
C#
private void downloadButton_Click(object sender, EventArgs e)

{
// Start the download operation in the background.
this.backgroundWorker1.RunWorkerAsync();
// Disable the button for the duration of the download.

this.downloadButton.Enabled = false;
// Once you have started the background thread you

// can exit the handler and the application will
// wait until the RunWorkerCompleted event is raised.
// Or if you want to do something else in the main thread,

// such as update a progress bar, you can do so in a loop
// while checking IsBusy to see if the background task is
// still running.
while (this.backgroundWorker1.IsBusy)
{
progressBar1.Increment(1);
// Keep UI messages moving, so the form remains
// responsive during the asynchronous operation.
Application.DoEvents();
}
}
Exibindo o resultado
O backgroundWorker1_RunWorkerCompleted método manipula o RunWorkerCompleted

evento e é chamado quando a operação em segundo plano é concluída. Esse método
primeiro verifica a AsyncCompletedEventArgs.Error propriedade . Se
AsyncCompletedEventArgs.Error for null , esse método exibirá o conteúdo do arquivo.
Ele habilita então o botão de download, que estava desabilitado quando o download
começou, e reinicia a barra de progresso.
C#

object sender,
{
// Set progress bar to 100% in case it's not already there.
if (e.Error == null)
{
MessageBox.Show(document.InnerXml, "Download Complete");
}
else
{
MessageBox.Show(
"Failed to download file",
"Download failed",
MessageBoxButtons.OK,
}
// Enable the download button and reset the progress bar.

this.downloadButton.Enabled = true;
}
Referências aos assemblies System.Drawing, System.Windows.Forms e System.Xml.
Programação robusta
Sempre marcar a AsyncCompletedEventArgs.Error propriedade no
RunWorkerCompleted manipulador de eventos antes de tentar acessar a
RunWorkerCompletedEventArgs.Result propriedade ou qualquer outro objeto que
possa ter sido afetado pelo DoWork manipulador de eventos.
Confira também
BackgroundWorker
Como: Implementar um formulário que
usa uma operação em segundo plano
Artigo • 02/06/2023
O programa de exemplo a seguir cria um formulário que calcula os números de

Fibonacci. O cálculo é executado em um thread separado do thread da interface do
usuário, portanto, a interface do usuário continua a ser executada sem atrasos conforme
o cálculo continua.
Há um suporte abrangente para esta tarefa no Visual Studio.
Consulte também passo a passos: Implementando um formulário que usa uma

operação em segundo plano.
Exemplo
C#
using System;
using System.Collections;
namespace BackgroundWorkerExample
{
public class FibonacciForm : System.Windows.Forms.Form
{
private int numberToCompute = 0;
private int highestPercentageReached = 0;
private System.Windows.Forms.NumericUpDown numericUpDown1;

private System.Windows.Forms.Button startAsyncButton;
private System.Windows.Forms.Button cancelAsyncButton;
private System.Windows.Forms.ProgressBar progressBar1;
private System.Windows.Forms.Label resultLabel;
public FibonacciForm()
{
InitializeBackgroundWorker();
}
// Set up the BackgroundWorker object by

// attaching event handlers.
private void InitializeBackgroundWorker()
{
backgroundWorker1.DoWork +=
new DoWorkEventHandler(backgroundWorker1_DoWork);
backgroundWorker1.RunWorkerCompleted +=
new RunWorkerCompletedEventHandler(
backgroundWorker1_RunWorkerCompleted);
backgroundWorker1.ProgressChanged +=
new ProgressChangedEventHandler(
backgroundWorker1_ProgressChanged);
}
private void startAsyncButton_Click(System.Object sender,

System.EventArgs e)
{
// Reset the text in the result label.
resultLabel.Text = String.Empty;
// Disable the UpDown control until

// the asynchronous operation is done.
this.numericUpDown1.Enabled = false;
// Disable the Start button until

this.startAsyncButton.Enabled = false;
// Enable the Cancel button while

// the asynchronous operation runs.
this.cancelAsyncButton.Enabled = true;
// Get the value from the UpDown control.

numberToCompute = (int)numericUpDown1.Value;
// Reset the variable for percentage tracking.

highestPercentageReached = 0;
// Start the asynchronous operation.

backgroundWorker1.RunWorkerAsync(numberToCompute);
}
private void cancelAsyncButton_Click(System.Object sender,

System.EventArgs e)
{
// Cancel the asynchronous operation.
// Disable the Cancel button.

cancelAsyncButton.Enabled = false;
}

DoWorkEventArgs e)
{

}
// This event handler deals with the results of the

// background operation.
object sender, RunWorkerCompletedEventArgs e)
{
// First, handle the case where an exception was thrown.
if (e.Error != null)
{
MessageBox.Show(e.Error.Message);
}
else if (e.Cancelled)
{
// Next, handle the case where the user canceled
// the operation.
// Note that due to a race condition in
// the DoWork event handler, the Cancelled
// flag may not have been set, even though
// CancelAsync was called.
resultLabel.Text = "Canceled";
}
else
{
// Finally, handle the case where the operation
// succeeded.
resultLabel.Text = e.Result.ToString();
}
// Enable the UpDown control.

this.numericUpDown1.Enabled = true;
// Enable the Start button.

startAsyncButton.Enabled = true;

}
// This event handler updates the progress bar.

private void backgroundWorker1_ProgressChanged(object sender,
ProgressChangedEventArgs e)
{
this.progressBar1.Value = e.ProgressPercentage;
}
// This is the method that does the actual work. For this
// example, it computes a Fibonacci number and
// reports progress as it does its work.
long ComputeFibonacci(int n, BackgroundWorker worker,
DoWorkEventArgs e)
{
// The parameter n must be >= 0 and <= 91.
// Fib(n), with n > 91, overflows a long.
if ((n < 0) || (n > 91))
{
throw new ArgumentException(
"value must be >= 0 and <= 91", "n");
}
long result = 0;
// Abort the operation if the user has canceled.

// Note that a call to CancelAsync may have set
// CancellationPending to true just after the
// last invocation of this method exits, so this
// code will not have the opportunity to set the
// DoWorkEventArgs.Cancel flag to true. This means
// that RunWorkerCompletedEventArgs.Cancelled will
// not be set to true in your RunWorkerCompleted
// event handler. This is a race condition.
if (worker.CancellationPending)
{
e.Cancel = true;
}
else
{
if (n < 2)
{
result = 1;
}
else
{
result = ComputeFibonacci(n - 1, worker, e) +
ComputeFibonacci(n - 2, worker, e);
}
// Report progress as a percentage of the total task.

int percentComplete =
(int)((float)n / (float)numberToCompute * 100);
if (percentComplete > highestPercentageReached)
{
highestPercentageReached = percentComplete;
worker.ReportProgress(percentComplete);
}
}
return result;
}

{
this.numericUpDown1 = new System.Windows.Forms.NumericUpDown();
this.startAsyncButton = new System.Windows.Forms.Button();
this.cancelAsyncButton = new System.Windows.Forms.Button();
this.resultLabel = new System.Windows.Forms.Label();
this.progressBar1 = new System.Windows.Forms.ProgressBar();
this.backgroundWorker1 = new
System.ComponentModel.BackgroundWorker();
((System.ComponentModel.ISupportInitialize)
(this.numericUpDown1)).BeginInit();
//
// numericUpDown1
//
this.numericUpDown1.Location = new System.Drawing.Point(16, 16);
this.numericUpDown1.Maximum = new System.Decimal(new int[] {
91,
0,
0,
0});
this.numericUpDown1.Minimum = new System.Decimal(new int[] {
1,
0,
0,
0});
this.numericUpDown1.Name = "numericUpDown1";
this.numericUpDown1.Size = new System.Drawing.Size(80, 20);
this.numericUpDown1.TabIndex = 0;
this.numericUpDown1.Value = new System.Decimal(new int[] {
1,
0,
0,
0});
//
// startAsyncButton
//
this.startAsyncButton.Location = new System.Drawing.Point(16,
72);
this.startAsyncButton.Name = "startAsyncButton";
this.startAsyncButton.Size = new System.Drawing.Size(120, 23);
this.startAsyncButton.TabIndex = 1;
this.startAsyncButton.Text = "Start Async";
this.startAsyncButton.Click += new
System.EventHandler(this.startAsyncButton_Click);
//
// cancelAsyncButton
//
this.cancelAsyncButton.Enabled = false;
this.cancelAsyncButton.Location = new System.Drawing.Point(153,
72);
this.cancelAsyncButton.Name = "cancelAsyncButton";
this.cancelAsyncButton.Size = new System.Drawing.Size(119, 23);
this.cancelAsyncButton.TabIndex = 2;
this.cancelAsyncButton.Text = "Cancel Async";
this.cancelAsyncButton.Click += new
System.EventHandler(this.cancelAsyncButton_Click);
//
// resultLabel
//
this.resultLabel.BorderStyle =
System.Windows.Forms.BorderStyle.Fixed3D;
this.resultLabel.Location = new System.Drawing.Point(112, 16);
this.resultLabel.Name = "resultLabel";
this.resultLabel.Size = new System.Drawing.Size(160, 23);
this.resultLabel.TabIndex = 3;
this.resultLabel.Text = "(no result)";
this.resultLabel.TextAlign =
System.Drawing.ContentAlignment.MiddleCenter;
//
// progressBar1
//
this.progressBar1.Location = new System.Drawing.Point(18, 48);
this.progressBar1.Name = "progressBar1";
this.progressBar1.Size = new System.Drawing.Size(256, 8);
this.progressBar1.Step = 2;
this.progressBar1.TabIndex = 4;
//
// backgroundWorker1
//
this.backgroundWorker1.WorkerReportsProgress = true;
this.backgroundWorker1.WorkerSupportsCancellation = true;
//
// FibonacciForm
//
this.Controls.Add(this.progressBar1);
this.Controls.Add(this.resultLabel);
this.Controls.Add(this.cancelAsyncButton);
this.Controls.Add(this.startAsyncButton);
this.Controls.Add(this.numericUpDown1);
this.Name = "FibonacciForm";
this.Text = "Fibonacci Calculator";
(this.numericUpDown1)).EndInit();
}
#endregion
[STAThread]
static void Main()
{
Application.Run(new FibonacciForm());
}
}
}
Ｕ Cuidado
O uso de multithreading de qualquer tipo pode expor o computador a bugs muito

sérios e complexos. Consulte as Melhores práticas de threading gerenciado antes
de implementar qualquer solução que use multithreading.
Confira também
BackgroundWorker
DoWorkEventArgs
Práticas recomendadas de threading gerenciado
Passo a passo: Executando uma
operação em segundo plano
Artigo • 21/06/2023
Se você tiver uma operação que levará muito tempo para ser concluída e não quiser
causar atrasos na interface do usuário, poderá usar a BackgroundWorker classe para
executar a operação em outro thread.
Para obter uma listagem completa do código usado neste exemplo, consulte Como
executar uma operação em segundo plano.
Executar uma operação em segundo plano

1. Com o formulário ativo no Windows Forms Designer no Visual Studio, arraste dois
Button controles da Caixa de Ferramentas para o formulário e defina as Name
propriedades e Text dos botões de acordo com a tabela a seguir.
Botão Nome Texto
button1 startBtn Iniciar
button2 cancelBtn Cancelar
2. Abra a Caixa de Ferramentas, clique na guia Componentes e arraste o

componente para o BackgroundWorker formulário.
O componente backgroundWorker1 aparece na Bandeja de Componentes.
3. Na janela Propriedades, defina a propriedade WorkerSupportsCancellation como

true .
4. Na janela Propriedades , clique no botão Eventos e clique duas vezes nos DoWork
eventos e RunWorkerCompleted para criar manipuladores de eventos.
5. Insira seu código demorado no DoWork manipulador de eventos.
6. Extraia todos os parâmetros exigidos pela operação da Argument propriedade do

DoWorkEventArgs parâmetro .
7. Atribua o resultado da computação à Result propriedade do DoWorkEventArgs.
Isso estará disponível para o RunWorkerCompleted manipulador de eventos.

C#
private void backgroundWorker1_DoWork(object sender, DoWorkEventArgs e)

{
// Do not access the form's BackgroundWorker reference directly.
// Instead, use the reference provided by the sender parameter.
BackgroundWorker bw = sender as BackgroundWorker;
// Extract the argument.

int arg = (int)e.Argument;
// Start the time-consuming operation.

e.Result = TimeConsumingOperation(bw, arg);
// If the operation was canceled by the user,

// set the DoWorkEventArgs.Cancel property to true.
if (bw.CancellationPending)
{
e.Cancel = true;
}
}
8. Insira o código para recuperar o resultado da operação no RunWorkerCompleted

manipulador de eventos.
C#
// This event handler demonstrates how to interpret

// the outcome of the asynchronous operation implemented
// in the DoWork event handler.
object sender,
{
if (e.Cancelled)
{
// The user canceled the operation.
MessageBox.Show("Operation was canceled");
}
else if (e.Error != null)
{
// There was an error during the operation.
string msg = String.Format("An error occurred: {0}",
e.Error.Message);
}
else
{
// The operation completed normally.
string msg = String.Format("Result = {0}", e.Result);
}
}
9. Implementar o método de TimeConsumingOperation .
C#
// This method models an operation that may take a long time

// to run. It can be cancelled, it can raise an exception,
// or it can exit normally and return a result. These outcomes
// are chosen randomly.
private int TimeConsumingOperation(
BackgroundWorker bw,
int sleepPeriod )
{
int result = 0;
Random rand = new Random();
while (!bw.CancellationPending)
{
bool exit = false;
switch (rand.Next(3))
{
// Raise an exception.
case 0:
{
throw new Exception("An error condition occurred.");
break;
}
// Sleep for the number of milliseconds

// specified by the sleepPeriod parameter.
case 1:
{
Thread.Sleep(sleepPeriod);
break;
}
// Exit and return normally.

case 2:
{
result = 23;
exit = true;
break;
}
default:
{
break;
}
}
if( exit )
{
break;
}
}
return result;
}
10. No Windows Forms Designer, clique startButton duas vezes para criar o Click
11. Chame o RunWorkerAsync método no Click manipulador de eventos para

startButton .
C#
private void startBtn_Click(object sender, EventArgs e)

{
this.backgroundWorker1.RunWorkerAsync(2000);
}
12. No Windows Forms Designer, clique cancelButton duas vezes para criar o Click
13. Chame o CancelAsync método no Click manipulador de eventos para

cancelButton .
C#

{
}
14. Na parte superior do arquivo, importe os namespaces System.ComponentModel e

System.Threading.
C#
using System;
15. Pressione F6 para criar a solução e pressione Ctrl+F5 para executar o aplicativo
fora do depurador.
７ Observação
Se você pressionar F5 para executar o aplicativo no depurador, a exceção

gerada no TimeConsumingOperation método será capturada e exibida pelo
depurador. Quando você executa o aplicativo fora do depurador, o
BackgroundWorker manipula a exceção e o Error armazena em cache na
propriedade do RunWorkerCompletedEventArgs.
16. Clique no botão Iniciar para executar uma operação assíncrona e, em seguida, no
botão Cancelar para interromper uma operação assíncrona em execução.
O resultado de cada operação é exibido em um MessageBox.
Próximas etapas
Implemente um formulário que relata o andamento à medida que uma operação
assíncrona prossegue. Para obter mais informações, consulte Como implementar
um formulário que usa uma operação em segundo plano.
Implemente uma classe que dá suporte ao padrão assíncrono para componentes.

Para obter mais informações, consulte Implementando o padrão assíncrono
baseado em evento.
Confira também
BackgroundWorker
DoWorkEventArgs
Passo a passo: Implementando um
formulário que usa uma operação em
segundo plano
Artigo • 02/06/2023
Se você tiver uma operação que levará muito tempo para ser concluída e não quiser que
a interface do usuário (interface do usuário) pare de responder ou bloqueie, você
poderá usar a BackgroundWorker classe para executar a operação em outro thread.
Este passo a passo ilustra como usar a BackgroundWorker classe para executar cálculos
demorados "em segundo plano", enquanto a interface do usuário permanece
responsiva. Quando terminar, você terá um aplicativo que calcula números de Fibonacci
de forma assíncrona. Embora o cálculo de um número de Fibonacci grande possa levar
um tempo considerável, o thread de interface do usuário principal não será
interrompido por esse atraso e o formulário será responsivo durante o cálculo.
As tarefas ilustradas neste passo a passo incluem:
Criando um aplicativo baseado no Windows
Criando um BackgroundWorker em seu formulário
Adição de manipuladores de evento assíncrono
Adicionando relatórios de progresso e suporte a cancelamento
Para obter uma listagem completa do código usado neste exemplo, consulte Como
implementar um formulário que usa uma operação em segundo plano.
Criar um formulário que usa uma operação em

segundo plano
BackgroundWorkerExample (File>New>Project>Visual C# ou Visual Basic>Classic
2. No Gerenciador de Soluções, clique com o botão direito do mouse em Form1 e

escolha Renomear no menu de atalho. Altere o nome de arquivo para
FibonacciCalculator . Clique no botão Sim quando solicitado se desejar renomear
todas as referências ao elemento de código ' Form1 '.

3. Arraste um NumericUpDown controle da Caixa de Ferramentas para o formulário.
Defina a Minimum propriedade como 1 e a Maximum propriedade como 91 .
4. Adicione dois Button controles ao formulário.
5. Renomeie o primeiro Button controle startAsyncButton e defina a Text

propriedade como Start Async . Renomeie o segundo Button controle
cancelAsyncButton e defina a Text propriedade como Cancel Async . Defina sua
Enabled propriedade como false .
6. Crie um manipulador de eventos para ambos os Button eventos dos Click

controles. Para detalhes, consulte Como criar manipuladores de eventos usando o
Designer.
7. Arraste um Label controle da Caixa de Ferramentas para o formulário e renomeie-

o resultLabel .
8. Arraste um ProgressBar controle da Caixa de Ferramentas para o formulário.
Criar um BackgroundWorker com o Designer

Você pode criar a BackgroundWorker operação assíncrona usando o Designer de
Formulários do Windows.
Na guia Componentes da Caixa de Ferramentas, arraste um BackgroundWorker para o

formulário.
Adicionar manipuladores de eventos

assíncronos
Agora você está pronto para adicionar manipuladores de eventos para os
BackgroundWorker eventos assíncronos do componente. A operação demorada que
será executada em segundo plano, que calcula os números de Fibonacci, é chamada por
um desses manipuladores de eventos.
1. Na janela Propriedades , com o BackgroundWorker componente ainda

selecionado, clique no botão Eventos . Clique duas vezes no e
RunWorkerCompleted nos DoWork eventos para criar manipuladores de eventos.
Para mais informações sobre como usar os manipuladores de evento, consulte
Como criar manipuladores de eventos usando o Designer.
2. Crie um novo método, chamado ComputeFibonacci , no formulário. Esse método faz
o trabalho real e ele será executado em segundo plano. Esse código demonstra a
implementação recursiva do algoritmo de Fibonacci, que é notavelmente
ineficiente, demorando mais tempo para concluir o cálculo de números maiores.
Ele é usado aqui para fins ilustrativos, para mostrar uma operação que pode
introduzir longos atrasos em seu aplicativo.
C#
// This is the method that does the actual work. For this
// example, it computes a Fibonacci number and
// reports progress as it does its work.
long ComputeFibonacci(int n, BackgroundWorker worker, DoWorkEventArgs
e)
{
// The parameter n must be >= 0 and <= 91.
// Fib(n), with n > 91, overflows a long.
if ((n < 0) || (n > 91))
{
throw new ArgumentException(
"value must be >= 0 and <= 91", "n");
}
long result = 0;
// Abort the operation if the user has canceled.

// Note that a call to CancelAsync may have set
// CancellationPending to true just after the
// last invocation of this method exits, so this
// code will not have the opportunity to set the
// DoWorkEventArgs.Cancel flag to true. This means
// that RunWorkerCompletedEventArgs.Cancelled will
// not be set to true in your RunWorkerCompleted
// event handler. This is a race condition.
{
e.Cancel = true;
}
else
{
if (n < 2)
{
result = 1;
}
else
{
result = ComputeFibonacci(n - 1, worker, e) +
ComputeFibonacci(n - 2, worker, e);
}

{
}
}
return result;
}
3. No manipulador de DoWork eventos, adicione uma chamada ao ComputeFibonacci

método. Pegue o primeiro parâmetro da ComputeFibonacci Argument propriedade
do DoWorkEventArgs. Os BackgroundWorker parâmetros e DoWorkEventArgs
serão usados posteriormente para suporte a relatórios de progresso e
cancelamento. Atribua o valor retornado à ComputeFibonacci Result propriedade do
DoWorkEventArgs. Esse resultado estará disponível para o RunWorkerCompleted
７ Observação
O DoWork manipulador de eventos não faz referência diretamente à variável

de backgroundWorker1 instância, pois isso associaria esse manipulador de
eventos a uma instância específica de BackgroundWorker. Em vez disso, uma
referência ao BackgroundWorker que gerou esse evento é recuperada do
sender parâmetro. Isso é importante quando o formulário hospeda mais de
um BackgroundWorker. Também é importante não manipular nenhum objeto

de interface do usuário no manipulador DoWork de eventos. Em vez disso,
comunique-se com a interface do usuário por meio dos BackgroundWorker
eventos.
C#

DoWorkEventArgs e)
{

}
4. startAsyncButton No manipulador de eventos do Click controle, adicione o código

que inicia a operação assíncrona.
C#
private void startAsyncButton_Click(System.Object sender,

System.EventArgs e)
{
// Reset the text in the result label.
resultLabel.Text = String.Empty;
// Disable the UpDown control until

this.numericUpDown1.Enabled = false;
// Disable the Start button until

this.startAsyncButton.Enabled = false;
// Enable the Cancel button while

// the asynchronous operation runs.
this.cancelAsyncButton.Enabled = true;
// Get the value from the UpDown control.

numberToCompute = (int)numericUpDown1.Value;
// Reset the variable for percentage tracking.

highestPercentageReached = 0;
// Start the asynchronous operation.

backgroundWorker1.RunWorkerAsync(numberToCompute);
}
5. RunWorkerCompleted No manipulador de eventos, atribua o resultado do cálculo

ao resultLabel controle.
C#
// This event handler deals with the results of the

// background operation.
object sender, RunWorkerCompletedEventArgs e)
{
// First, handle the case where an exception was thrown.
if (e.Error != null)
{
MessageBox.Show(e.Error.Message);
}
else if (e.Cancelled)
{
// Next, handle the case where the user canceled
// the operation.
// Note that due to a race condition in
// the DoWork event handler, the Cancelled
// flag may not have been set, even though
// CancelAsync was called.
resultLabel.Text = "Canceled";
}
else
{
// Finally, handle the case where the operation
// succeeded.
resultLabel.Text = e.Result.ToString();
}
// Enable the UpDown control.

this.numericUpDown1.Enabled = true;
// Enable the Start button.

startAsyncButton.Enabled = true;

}
Adicionando relatórios de progresso e suporte

a cancelamento
Para operações assíncronas que levarão um longo tempo, muitas vezes é desejável
relatar o progresso ao usuário e permitir que o usuário cancele a operação. A
BackgroundWorker classe fornece um evento que permite que você poste o progresso à
medida que sua operação em segundo plano prossegue. Ele também fornece um
sinalizador que permite que o código de trabalho detecte uma chamada CancelAsync e
interrompa a si mesmo.
Implementar relatórios de progresso

1. Na janela Propriedades, selecione backgroundWorker1 . Defina as propriedades
WorkerReportsProgress e WorkerSupportsCancellation como true .
2. Declare duas variáveis no formulário FibonacciCalculator . Elas serão usadas para

acompanhar o progresso.
C#
private int numberToCompute = 0;
private int highestPercentageReached = 0;
3. Adicione um manipulador de eventos para o ProgressChanged evento.

ProgressChanged No manipulador de eventos, atualize a ProgressBar propriedade
com ProgressPercentage o ProgressChangedEventArgs parâmetro.
C#
// This event handler updates the progress bar.

ProgressChangedEventArgs e)
{
this.progressBar1.Value = e.ProgressPercentage;
}
Implementar suporte para cancelamento

1. cancelAsyncButton No manipulador de eventos do Click controle, adicione o
código que cancela a operação assíncrona.
C#
private void cancelAsyncButton_Click(System.Object sender,

System.EventArgs e)
{
// Cancel the asynchronous operation.

}
2. Os fragmentos de código a seguir no relatório de método ComputeFibonacci

progridem e dão suporte ao cancelamento.
C#
{
e.Cancel = true;
}
C#
{
}
Ponto de verificação
Neste ponto, você pode compilar e executar o aplicativo Calculadora Fibonacci.
Pressione F5 para compilar e executar o aplicativo.
Enquanto o cálculo estiver em execução em segundo plano, você verá a ProgressBar

exibição do progresso do cálculo em direção à conclusão. Você também pode cancelar a
operação pendente.
Para números pequenos, o cálculo deve ser muito rápido, mas, para números maiores,
você deve ver um atraso considerável. Se inserir um valor de 30 ou mais, você deverá
ver um atraso de alguns segundos, dependendo da velocidade do seu computador. Para
valores maiores que 40, poderá levar minutos ou horas para concluir o cálculo.
Enquanto a calculadora estiver ocupada calculando um número de Fibonacci grande,
observe que você pode movimentar livremente o formulário, minimizar, maximizar e até
mesmo descartá-lo. Isso ocorre porque o thread da interface do usuário principal não
está aguardando concluir o cálculo.
Próximas etapas
Agora que você implementou um formulário que usa um BackgroundWorker
componente para executar uma computação em segundo plano, você pode explorar
outras possibilidades para operações assíncronas:
Use vários BackgroundWorker objetos para várias operações simultâneas.
Para depurar seu aplicativo multi-threaded, consulte Como usar a janela Threads.
Implemente seu próprio componente que dá suporte ao modelo de programação

assíncrona. Para mais informações, consulte Visão geral sobre o padrão assíncrono
baseado em evento.
Ｕ Cuidado
O uso de multithreading de qualquer tipo pode expor o computador a bugs

muito sérios e complexos. Consulte as Melhores práticas de threading
gerenciado antes de implementar qualquer solução que use multithreading.
Confira também
System.ComponentModel.BackgroundWorker
Threading gerenciado
Práticas recomendadas de threading gerenciado
Passo a passo: Executando uma operação em segundo plano
Controle BindingNavigator (Windows
Forms)
Artigo • 02/06/2023
O BindingNavigator controle é a interface do usuário (interface do usuário) de

navegação e manipulação para controles associados aos dados. O BindingNavigator
controle permite que os usuários naveguem e manipulem dados em um Formulário do
Windows.
Os tópicos desta seção fornecem uma visão geral do BindingNavigator controle e

oferecem instruções passo a passo sobre como usar os dados de navegação de controle
e passar por um DataSet.
Nesta seção
Visão geral do controle BindingNavigator
Apresenta os conceitos gerais do controle, que BindingNavigator permite que os
usuários passem pelos itens de uma fonte de dados.
Como: Navegar em dados com o controle BindingNavigator do Windows Forms

Fornece etapas para associar um BindingNavigator controle a uma fonte de dados.
Como: Avançar em um DataSet com o controle BindingNavigator do Windows Forms

Demonstra o uso de um BindingNavigator controle para percorrer registros em um
DataSet.
Consulte também Como adicionar botões Carregar, Salvar e Cancelar ao controle

BindingNavigator do Windows Forms.
Referência
BindingNavigator
Fornece a documentação de referência para o BindingNavigator controle.
BindingSource
Fornece a documentação de referência para o BindingSource controle.
Associar controles a dados no Visual Studio
Visão geral do controle
BindingNavigator (Windows Forms)
Artigo • 02/06/2023
Você pode usar o BindingNavigator controle para criar um meio padronizado para que
os usuários pesquisem e alterem dados em um Formulário do Windows. Você usa
BindingNavigator com frequência com o BindingSource componente para permitir que
os usuários se movam por meio de registros de dados em um formulário e interajam
com os registros.
Como o BindingNavigator funciona

O BindingNavigator controle é composto por uma ToolStrip série de ToolStripItem
objetos para a maioria das ações comuns relacionadas a dados: adicionar dados, excluir
dados e navegar por dados. Por padrão, o BindingNavigator controle contém esses
botões padrão. A captura de tela a seguir mostra o BindingNavigator controle em um
formulário:
A tabela a seguir lista os controles e descreve suas funções.
Control Função
Botão AddNewItem Insere uma nova linha na fonte de dados subjacente.
Botão DeleteItem Exclui a linha atual da fonte de dados subjacente.
Botão MoveFirstItem Move para o primeiro item da fonte de dados subjacente.
Botão MoveLastItem Move para o último item da fonte de dados subjacente.
Botão MoveNextItem Move para o próximo item da fonte de dados subjacente.
Botão MovePreviousItem Move para o item anterior da fonte de dados subjacente.

Control Função
Caixa de texto PositionItem Retorna a posição atual na fonte de dados subjacente.
Caixa de texto CountItem Retorna o número total de itens na fonte de dados subjacente.
Para cada controle nesta coleção, há um membro correspondente do BindingSource

componente que fornece programaticamente a mesma funcionalidade. Por exemplo, o
MoveFirstItem botão corresponde ao MoveFirst método do BindingSource componente,
o DeleteItem botão corresponde ao RemoveCurrent método e assim por diante.
Se os botões padrão não forem adequados para seu aplicativo ou se você precisar de
botões adicionais para dar suporte a outros tipos de funcionalidade, poderá fornecer
seus próprios ToolStrip botões. Consulte também Como adicionar botões Carregar,
Salvar e Cancelar ao controle BindingNavigator do Windows Forms.
Confira também
BindingNavigator
BindingSource
Como: Navegar em dados com o
controle BindingNavigator do Windows
Forms
Artigo • 21/06/2023
O advento do BindingNavigator controle no Windows Forms permite que os

desenvolvedores forneçam aos usuários finais uma interface de usuário simples de
navegação e manipulação de dados nos formulários que eles criam.
O BindingNavigator controle é um ToolStrip controle com botões pré-configurados para

navegação para o primeiro, o último, o próximo e o registro anterior em um conjunto
de dados, bem como botões para adicionar e excluir registros. Adicionar botões ao
BindingNavigator controle é fácil, pois é um ToolStrip controle. Para obter exemplos,
consulte Como adicionar botões carregar, salvar e cancelar ao controle
BindingNavigator do Windows Forms.
Para cada botão no BindingNavigator controle, há um membro correspondente do

BindingSource componente que permite programaticamente a mesma funcionalidade.
Por exemplo, o MoveFirstItem botão corresponde ao MoveFirst método do
BindingSource componente, o DeleteItem botão corresponde ao RemoveCurrent
método e assim por diante. Como resultado, habilitar o BindingNavigator controle para
navegar por registros de dados é simples como definir sua BindingSource propriedade
para o componente apropriado BindingSource no formulário.
Configurar o controle BindingNavigator

1. Adicione um BindingSource componente chamado bindingSource1 e dois TextBox
controles chamados textBox1 e textBox2 .
2. Associe bindingSource1 a dados e os controles da caixa de texto a bindingSource1 .

Para fazer isso, cole o código a seguir em seu formulário e chame LoadData do
construtor do formulário ou Load do método de tratamento de eventos.
C#
private void LoadData()

{
// The xml to bind to.
string xml = @"<US><states>"
+ @"<state><name>Washington</name><capital>Olympia</capital>
</state>"
+ @"<state><name>Oregon</name><capital>Salem</capital></state>"
+ @"<state><name>California</name><capital>Sacramento</capital>
</state>"
+ @"<state><name>Nevada</name><capital>Carson City</capital>
</state>"
+ @"</states></US>";
// Convert the xml string to bytes and load into a memory stream.
byte[] xmlBytes = Encoding.UTF8.GetBytes(xml);
MemoryStream stream = new MemoryStream(xmlBytes, false);
// Create a DataSet and load the xml into it.

DataSet set = new DataSet();
set.ReadXml(stream);
// Set the DataSource to the DataSet, and the DataMember

// to state.
bindingSource1.DataSource = set;
bindingSource1.DataMember = "state";
textBox1.DataBindings.Add("Text", bindingSource1, "name");

textBox2.DataBindings.Add("Text", bindingSource1, "capital");
}
3. Adicione um BindingNavigator controle chamado bindingNavigator1 ao

formulário.
4. Defina a BindingSource propriedade para como

bindingNavigator1 bindingSource1 . É possível fazer isso com o designer ou em
código.
C#
bindingNavigator1.BindingSource = bindingSource1;
Exemplo
O exemplo de código a seguir é o exemplo completo para as etapas listadas
anteriormente.
C#
using System;
using System.Data;
using System.Xml;
using System.IO;
using System.Text;
namespace System.Windows.Forms.BindingSourceCurrent
{
class Form1 : Form
{
private IContainer components;
private BindingNavigator bindingNavigator1;
private ToolStripButton bindingNavigatorAddNewItem;
private ToolStripLabel bindingNavigatorCountItem;
private ToolStripButton bindingNavigatorDeleteItem;
private ToolStripButton bindingNavigatorMoveFirstItem;
private ToolStripButton bindingNavigatorMovePreviousItem;
private ToolStripSeparator bindingNavigatorSeparator;
private ToolStripTextBox bindingNavigatorPositionItem;
private ToolStripSeparator bindingNavigatorSeparator1;
private ToolStripButton bindingNavigatorMoveNextItem;
private ToolStripButton bindingNavigatorMoveLastItem;
private TextBox textBox1;
private BindingSource bindingSource1;
private ToolStripSeparator bindingNavigatorSeparator2;
public Form1()
{
LoadData();
bindingNavigator1.BindingSource = bindingSource1;
}
private void LoadData()
{
// The xml to bind to.
string xml = @"<US><states>"
+ @"<state><name>Washington</name><capital>Olympia</capital>
</state>"
+ @"<state><name>Oregon</name><capital>Salem</capital>
</state>"
+ @"<state><name>California</name>
<capital>Sacramento</capital></state>"
+ @"<state><name>Nevada</name><capital>Carson City</capital>
</state>"
+ @"</states></US>";
// Convert the xml string to bytes and load into a memory

stream.
byte[] xmlBytes = Encoding.UTF8.GetBytes(xml);
MemoryStream stream = new MemoryStream(xmlBytes, false);
// Create a DataSet and load the xml into it.

DataSet set = new DataSet();
set.ReadXml(stream);
// Set the DataSource to the DataSet, and the DataMember
// to state.
bindingSource1.DataSource = set;
bindingSource1.DataMember = "state";
textBox1.DataBindings.Add("Text", bindingSource1, "name");

textBox2.DataBindings.Add("Text", bindingSource1, "capital");
}
[STAThread]
public static void Main()
{
}

{
this.components = new System.ComponentModel.Container();
System.ComponentModel.ComponentResourceManager resources =
new
System.ComponentModel.ComponentResourceManager(typeof(Form1));
this.bindingNavigator1 = new
System.Windows.Forms.BindingNavigator(this.components);
this.bindingNavigatorAddNewItem = new
System.Windows.Forms.ToolStripButton();
this.bindingNavigatorCountItem = new
System.Windows.Forms.ToolStripLabel();
this.bindingNavigatorDeleteItem = new
this.bindingNavigatorMoveFirstItem = new
this.bindingNavigatorMovePreviousItem = new
this.bindingNavigatorSeparator = new
System.Windows.Forms.ToolStripSeparator();
this.bindingNavigatorPositionItem = new
System.Windows.Forms.ToolStripTextBox();
this.bindingNavigatorSeparator1 = new
this.bindingNavigatorMoveNextItem = new
this.bindingNavigatorMoveLastItem = new
this.bindingNavigatorSeparator2 = new
this.textBox1 = new System.Windows.Forms.TextBox();
this.bindingSource1 = new
System.Windows.Forms.BindingSource(this.components);
(this.bindingNavigator1)).BeginInit();
this.bindingNavigator1.SuspendLayout();
(this.bindingSource1)).BeginInit();
//
// bindingNavigator1
//
this.bindingNavigator1.AddNewItem =
this.bindingNavigatorAddNewItem;
this.bindingNavigator1.CountItem =
this.bindingNavigatorCountItem;
this.bindingNavigator1.CountItemFormat = "of {0}";
this.bindingNavigator1.DeleteItem =
this.bindingNavigatorDeleteItem;
this.bindingNavigator1.Items.AddRange(new
System.Windows.Forms.ToolStripItem[] {
this.bindingNavigatorMoveFirstItem,
this.bindingNavigatorMovePreviousItem,
this.bindingNavigatorSeparator,
this.bindingNavigatorPositionItem,
this.bindingNavigatorCountItem,
this.bindingNavigatorSeparator1,
this.bindingNavigatorMoveNextItem,
this.bindingNavigatorMoveLastItem,
this.bindingNavigatorSeparator2,
this.bindingNavigatorAddNewItem,
this.bindingNavigatorDeleteItem});
this.bindingNavigator1.Location = new System.Drawing.Point(0,
0);
this.bindingNavigator1.MoveFirstItem =
this.bindingNavigatorMoveFirstItem;
this.bindingNavigator1.MoveLastItem =
this.bindingNavigatorMoveLastItem;
this.bindingNavigator1.MoveNextItem =
this.bindingNavigatorMoveNextItem;
this.bindingNavigator1.MovePreviousItem =
this.bindingNavigatorMovePreviousItem;
this.bindingNavigator1.Name = "bindingNavigator1";
this.bindingNavigator1.PositionItem =
this.bindingNavigatorPositionItem;
this.bindingNavigator1.TabIndex = 2;
this.bindingNavigator1.Text = "bindingNavigator1";
//
// bindingNavigatorAddNewItem
//
this.bindingNavigatorAddNewItem.Image =
((System.Drawing.Image)
(resources.GetObject("bindingNavigatorAddNewItem.Image")));
this.bindingNavigatorAddNewItem.Name =
"bindingNavigatorAddNewItem";
this.bindingNavigatorAddNewItem.Text = "Add new";
//
// bindingNavigatorCountItem
//
this.bindingNavigatorCountItem.Name =
"bindingNavigatorCountItem";
this.bindingNavigatorCountItem.Text = "of {0}";
this.bindingNavigatorCountItem.ToolTipText = "Total number of
items";
//
// bindingNavigatorDeleteItem
//
this.bindingNavigatorDeleteItem.Image =
(resources.GetObject("bindingNavigatorDeleteItem.Image")));
this.bindingNavigatorDeleteItem.Name =
"bindingNavigatorDeleteItem";
this.bindingNavigatorDeleteItem.Text = "Delete";
//
// bindingNavigatorMoveFirstItem
//
this.bindingNavigatorMoveFirstItem.Image =
(resources.GetObject("bindingNavigatorMoveFirstItem.Image")));
this.bindingNavigatorMoveFirstItem.Name =
"bindingNavigatorMoveFirstItem";
this.bindingNavigatorMoveFirstItem.Text = "Move first";
//
// bindingNavigatorMovePreviousItem
//
this.bindingNavigatorMovePreviousItem.Image =
(resources.GetObject("bindingNavigatorMovePreviousItem.Image")));
this.bindingNavigatorMovePreviousItem.Name =
"bindingNavigatorMovePreviousItem";
this.bindingNavigatorMovePreviousItem.Text = "Move previous";
//
// bindingNavigatorSeparator
//
this.bindingNavigatorSeparator.Name =
"bindingNavigatorSeparator";
//
// bindingNavigatorPositionItem
//
this.bindingNavigatorPositionItem.DisplayStyle =
System.Windows.Forms.ToolStripItemDisplayStyle.ImageAndText;
this.bindingNavigatorPositionItem.Name =
"bindingNavigatorPositionItem";
this.bindingNavigatorPositionItem.Size = new
System.Drawing.Size(50, 25);
this.bindingNavigatorPositionItem.Text = "0";
this.bindingNavigatorPositionItem.ToolTipText = "Current
position";
//
// bindingNavigatorSeparator1
//
this.bindingNavigatorSeparator1.Name =
"bindingNavigatorSeparator1";
// bindingNavigatorMoveNextItem
//
this.bindingNavigatorMoveNextItem.Image =
(resources.GetObject("bindingNavigatorMoveNextItem.Image")));
this.bindingNavigatorMoveNextItem.Name =
"bindingNavigatorMoveNextItem";
this.bindingNavigatorMoveNextItem.Text = "Move next";
//
// bindingNavigatorMoveLastItem
//
this.bindingNavigatorMoveLastItem.Image =
(resources.GetObject("bindingNavigatorMoveLastItem.Image")));
this.bindingNavigatorMoveLastItem.Name =
"bindingNavigatorMoveLastItem";
this.bindingNavigatorMoveLastItem.Text = "Move last";
//
// bindingNavigatorSeparator2
//
this.bindingNavigatorSeparator2.Name =
"bindingNavigatorSeparator2";
//
// textBox1
//
this.textBox1.Location = new System.Drawing.Point(46, 64);
this.textBox1.Name = "textBox1";
this.textBox1.TabIndex = 3;
//
// textBox2
//
//
// Form1
//
this.Controls.Add(this.textBox2);
this.Controls.Add(this.bindingNavigator1);
(this.bindingNavigator1)).EndInit();
this.bindingNavigator1.ResumeLayout(false);
this.bindingNavigator1.PerformLayout();
(this.bindingSource1)).EndInit();
this.PerformLayout();
}
}
}
Referência aos conjuntos System, System.Data, System.Drawing,

System.Windows.Forms e System.Xml.
Confira também
BindingNavigator
Controle ToolStrip
Como: Avançar em um DataSet com o
controle BindingNavigator do Windows
Forms
Artigo • 02/06/2023
À medida que você cria aplicativos controlados por dados, muitas vezes você precisará
exibir coleções de dados para os usuários. O BindingNavigator controle, em conjunto
com o BindingSource componente, fornece uma solução conveniente e extensível para
mover uma coleção e exibir itens sequencialmente.
Exemplo
O exemplo de código a seguir demonstra como usar um BindingNavigator controle
para mover os dados. O conjunto está contido em um DataView, que está associado a
um TextBox controle com um BindingSource componente.
７ Observação
O armazenamento das informações confidenciais (tal como uma senha) dentro da

cadeia de conexão pode afetar a segurança do aplicativo. O uso da Autenticação
do Windows (também conhecida como segurança integrada) é uma maneira mais
segura de controlar o acesso a um banco de dados. Para obter mais informações,
consulte Protegendo informações de conexão.
C#
using System;
using System.Data;
using System.Data.SqlClient;
// This form demonstrates using a BindingNavigator to display

// rows from a database query sequentially.
{
// This is the BindingNavigator that allows the user
// to navigate through the rows in a DataSet.
BindingNavigator customersBindingNavigator = new BindingNavigator(true);
// This is the BindingSource that provides data for
// the Textbox control.
BindingSource customersBindingSource = new BindingSource();
// This is the TextBox control that displays the CompanyName

// field from the DataSet.
TextBox companyNameTextBox = new TextBox();
public Form1()
{
// Set up the BindingSource component.
this.customersBindingNavigator.BindingSource =
this.customersBindingSource;
this.customersBindingNavigator.Dock = DockStyle.Top;
this.Controls.Add(this.customersBindingNavigator);
// Set up the TextBox control for displaying company names.

this.companyNameTextBox.Dock = DockStyle.Bottom;
this.Controls.Add(this.companyNameTextBox);
// Set up the form.

this.Size = new Size(800, 200);
this.Load += new EventHandler(Form1_Load);
}
void Form1_Load(object sender, EventArgs e)

{
// Open a connection to the database.
// Replace the value of connectString with a valid
// connection string to a Northwind database accessible
// to your system.
string connectString =
"Integrated Security=SSPI;Persist Security Info=False;" +
"Initial Catalog=Northwind;Data Source=localhost";
using (SqlConnection connection = new SqlConnection(connectString))

{
SqlDataAdapter dataAdapter1 =
new SqlDataAdapter(new SqlCommand("Select * From
Customers",connection));
DataSet ds = new DataSet("Northwind Customers");
ds.Tables.Add("Customers");
dataAdapter1.Fill(ds.Tables["Customers"]);
// Assign the DataSet as the DataSource for the BindingSource.

this.customersBindingSource.DataSource = ds.Tables["Customers"];
// Bind the CompanyName field to the TextBox control.

this.companyNameTextBox.DataBindings.Add(
new Binding("Text",
this.customersBindingSource,
"CompanyName",
true));
}
}
[STAThread]
{
}
}
Referência aos conjuntos System, System.Data, System.Drawing,

Confira também
BindingSource
DataGridView
BindingSource
Como: Associar um controle do Windows Forms a um tipo
Como: Adicionar botões Carregar, Salvar
e Cancelar ao controle
BindingNavigator do Windows Forms
Artigo • 21/06/2023
O BindingNavigator controle é um controle de finalidade ToolStrip especial destinado a

navegar e manipular controles em seu formulário associados aos dados.
Como é um ToolStrip controle, o BindingNavigator componente pode ser facilmente

modificado para incluir comandos adicionais ou alternativos para o usuário.
No procedimento a seguir, um TextBox controle é associado a dados e o ToolStrip

controle adicionado ao formulário é modificado para incluir botões de carregamento,
salvamento e cancelamento.
Adicionar botões de carregamento, salvamento

e cancelamento ao componente
BindingNavigator
1. No Visual Studio, adicione um TextBox controle ao formulário.
2. Associe-o a um BindingSource, que está associado a uma fonte de dados. Para

este exemplo, o BindingSource está associado a um banco de dados.
3. Depois que o conjunto de dados e o adaptador de tabela forem gerados, arraste

um BindingNavigator controle para o formulário.
4. Defina a BindingNavigator propriedade do BindingSource controle como no

BindingSource formulário associado aos controles.
5. Selecione o controle BindingNavigator.
6. Clique no glifo de ações do designer ( ) para que a caixa de diálogo Tarefas

bindingNavigator seja exibida e selecione Editar Itens.
O Editor de Coleção de Itens aparece.
7. No Editor de Coleção de Itens, faça o seguinte:
a. Adicione um ToolStripSeparator e três ToolStripButton itens selecionando o tipo

apropriado de ToolStripItem e clicando no botão Adicionar .
b. Defina a Name propriedade dos botões como LoadButton, SaveButton e
CancelButton, respectivamente.
c. Defina a Text propriedade dos botões como Carregar, Salvar e Cancelar.
d. Defina a DisplayStyle propriedade para cada um dos botões como Texto. Como
alternativa, você pode definir essa propriedade como Image ou ImageAndText
e definir a imagem para ser exibida na Image propriedade .
e. Clique em OK para fechar a caixa de diálogo. Os botões são adicionados ao

ToolStrip.
8. Clique com o botão direito do mouse no formulário e escolha Exibir Código.
9. No Editor de Códigos, localize a linha de código que carrega dados no adaptador

de tabela. Esse código foi gerado quando você configura a vinculação de dados na
etapa 2. O código deve ser semelhante ao seguinte:
TableAdapterName.Fill(DataSetName.TableName) . Provavelmente, ele estará no
evento do Load formulário.
10. Crie um manipulador de eventos para o Click evento da CargaToolStripButton que

você criou anteriormente e mova esse código de carregamento de dados para ele.
Agora, seu código deve ser semelhante ao seguinte:
C#
private void LoadButton_Click(System.Object sender,

System.EventArgs e)
{
TableAdapterName.Fill(DataSetName.TableName);
}
11. Crie um manipulador de eventos para o Click evento do SaveToolStripButton que

você criou anteriormente e escreva o código para atualizar os dados dentro da
tabela à qual o controle está associado.
C#
private void SaveButton_Click(System.Object sender,

System.EventArgs e)
{
TableAdapterName.Update(DataSetName.TableName);
}
７ Observação
Em alguns casos, o BindingNavigator componente já tem um botão Salvar,

mas nenhum código foi gerado pelo Windows Forms Designer. Nesse caso,
você pode colocar o código anterior no Click manipulador de eventos desse
botão, em vez de criar um botão totalmente novo no ToolStrip. No entanto, o
botão é desabilitado por padrão, portanto, você deve definir a Enabled
propriedade do botão para true que o botão funcione corretamente.
12. Crie um manipulador de eventos para o Click evento cancel queToolStripButton

você criou anteriormente e escreva o código para cancelar as alterações no
registro de dados exibido.
C#
private void CancelButton_Click(System.Object sender, System.EventArgs

e)
{
BindingSourceName.CancelEdit();
}
７ Observação
O CancelEdit método tem como escopo a linha de dados. Salve as alterações

feitas ao exibir um registro individual antes de navegar até o próximo registro.
Confira também
BindingNavigator
BindingSource
ToolStrip
Visão geral do componente BindingSource
Artigo • 02/06/2023
Encapsula uma fonte de dados para associação aos controles.
O BindingSource componente serve a duas finalidades. Primeiro, ele fornece uma

camada de indireção ao associar os controles em um formulário de dados. Isso é feito
associando o BindingSource componente à fonte de dados e associando os controles
no formulário ao BindingSource componente. Toda a interação adicional com os dados,
incluindo navegação, classificação, filtragem e atualização, é realizada com chamadas
para o BindingSource componente.
Em segundo lugar, o BindingSource componente pode atuar como uma fonte de dados
fortemente tipada. Adicionar um tipo ao BindingSource componente com o Add
método cria uma lista desse tipo.
Nesta seção
Apresenta os conceitos gerais do componente, o BindingSource que permite que você
associe uma fonte de dados a um controle.
Como: Como associar controles do Windows Forms a valores de banco de dados DBNull
Mostra como lidar com um DBNull valor da fonte de dados usando o BindingSource
componente.
Como: Classificar e filtrar dados ADO.NET com o componente BindingSource do

Windows Forms
Demonstra o uso do BindingSource componente para aplicar classificações e filtros aos
dados exibidos.
Como: Associar a um serviço Web usando o BindingSource do Windows Forms

Mostra como usar o BindingSource componente para associar a um serviço Web.
Como: Como identificar erros e exceções que ocorram na associação de dados

Demonstra o uso do BindingSource componente para lidar normalmente com erros que
ocorrem em uma operação de associação de dados.

Demonstra o uso de um BindingSource componente para associar a um tipo.
Como: Associar um controle do Windows Forms a um objeto de alocador
Demonstra o uso de um BindingSource componente para associar a um objeto ou
método de fábrica.
Como: Como personalizar a adição de item com o BindingSource do Windows Forms

Demonstra o uso de um BindingSource componente para criar novos itens e adicioná-
los a uma fonte de dados.
Como: Acionar notificações de alteração usando o método BindingSource ResetItem

Demonstra o uso de um BindingSource componente para gerar eventos de notificação
de alterações para fontes de dados que não dão suporte à notificação de alteração.
Como: Gerar notificações de alteração usando um BindingSource e a interface

INotifyPropertyChanged
Demonstra como usar um tipo que herda do INotifyPropertyChanged com um
BindingSource controle.
Como: Refletir atualizações feitas na fonte de dados em um controle do Windows Forms

com o BindingSource
Demonstra como responder a alterações na fonte de dados usando o BindingSource
componente.
Como: Compartilhar dados associados entre formulários usando o componente

BindingSource
Mostra como usar a associação de BindingSource vários formulários à mesma fonte de
dados.
Referência
BindingSource
Fornece a documentação de referência para o BindingSource componente.
BindingNavigator
Fornece a documentação de referência para o BindingNavigator controle.
Associação de dados do Windows Forms
Contém links para tópicos que descrevem a arquitetura de associação de dados do
Windows Forms.
Consulte também Associar controles a dados no Visual Studio.

BindingSource
Artigo • 21/06/2023
O BindingSource componente foi projetado para simplificar o processo de associação

de controles a uma fonte de dados subjacente. O BindingSource componente atua
como um canal e uma fonte de dados para outros controles a serem associados. Ele
fornece uma abstração da conexão de dados do formulário enquanto passa comandos
para a lista de dados subjacente. Além disso, você pode adicionar dados diretamente a
ele para que o próprio componente funcione como uma fonte de dados.
Componente BindingSource como um

intermediário
O BindingSource componente atua como a fonte de dados para alguns ou todos os
controles no formulário. No Visual Studio, o BindingSource pode ser associado a um
controle por meio da DataBindings propriedade , que pode ser acessada na janela
Propriedades . Confira também Como associar controles dos Windows Forms ao
componente BindingSource usando o Designer.
Você pode associar o BindingSource componente a ambas as fontes de dados simples,

como uma única propriedade de um objeto ou uma coleção básica como ArrayListe
fontes de dados complexas, como uma tabela de banco de dados. O BindingSource
componente atua como um intermediário que fornece serviços de associação e
gerenciamento de moedas. Em tempo de design ou tempo de execução, você pode
associar um BindingSource componente a uma fonte de dados complexa definindo suas
DataSource propriedades e DataMember para o banco de dados e tabela,
respectivamente. A ilustração a seguir demonstra onde o BindingSource componente se
encaixa na arquitetura de associação de dados existente.
Arquitetura de
７ Observação
Em tempo de design, algumas ações, como arrastar uma tabela de banco de dados
de uma janela de dados para um formulário em branco, criarão o BindingSource
componente, o associarão à fonte de dados subjacente e adicionarão controles
com reconhecimento de dados em uma única operação. Confira também
Associando controles dos Windows Forms a dados no Visual Studio.
Componente BindingSource como uma fonte

de dados
Se você começar a adicionar itens ao BindingSource componente sem primeiro
especificar uma lista a ser associada, o componente agirá como uma fonte de dados no
estilo lista e aceitará esses itens adicionados.
Além disso, você pode escrever código para fornecer a funcionalidade personalizada
"AddNew" por meio do AddingNew evento, que é gerado quando o AddNew método é
chamado antes do item ser adicionado à lista. Para obter mais informações, consulte
Arquitetura do componente BindingSource.
Navegação
Para usuários que precisam navegar pelos dados em um formulário, o BindingNavigator
componente permite que você navegue e manipule dados, em coordenação com um
BindingSource componente. Para obter mais informações, consulte Controle
BindingNavigator.
Manipulação de dados
O: BindingSource atua como um CurrencyManager para todas as suas associações e,
portanto, pode fornecer acesso a informações de moeda e posição sobre a fonte de
dados. A tabela a seguir mostra os membros que o BindingSource componente fornece
para acessar e manipular os dados subjacentes.
Membro Descrição
Propriedade Obtém o item atual da fonte de dados.

Current
Membro Descrição
Propriedade Obtém ou define a posição atual na lista subjacente.

Position
Propriedade Obtém a lista que é a avaliação do e DataMember da DataSource avaliação. Se

List DataMember não estiver definido, retornará a lista especificada por DataSource.
Método Insert Insere um item na lista no índice especificado.
Método Remove o item atual da lista.

RemoveCurrent
Método Aplica as alterações pendentes à fonte de dados subjacente.

EndEdit
Método Cancela a operação de edição atual.

CancelEdit
Método Adiciona um novo item à lista subjacente. Se a fonte de dados implementar

AddNew IBindingList e retornar um item do AddingNew evento, adicionará esse item.
Caso contrário, a solicitação será passada para o método da AddNew lista. Se a
lista subjacente não for um IBindingList, o item será criado automaticamente
por meio de seu construtor público sem parâmetros.
Classificando e filtrando
Normalmente, você deve trabalhar com uma exibição ordenada ou filtrada da fonte de
dados. A tabela a seguir mostra os membros que a fonte de dados do BindingSource
componente fornece.
Membro Descrição
Propriedade Se a fonte de dados for um IBindingList, obterá ou definirá um nome de coluna

Sort usado para classificar e classificar informações de ordem. Se a fonte de dados for
um IBindingListView e oferecer suporte à classificação avançada, obterá vários
nomes de coluna usados para classificar e classificar informações de ordem
Propriedade Se a fonte de dados for um IBindingListView, obterá ou definirá a expressão usada

Filter para filtrar quais linhas são exibidas.
Confira também
BindingSource
BindingNavigator
Arquitetura do componente BindingSource
associação de dados Windows Forms
Arquitetura do componente
BindingSource
Artigo • 02/06/2023
Com o BindingSource componente, você pode associar universalmente todos os

controles Windows Forms a fontes de dados.
O BindingSource componente simplifica o processo de controles de associação para

uma fonte de dados e fornece as seguintes vantagens sobre a associação de dados
tradicional:
Habilita a associação a objetos comerciais em tempo de design.
Encapsula a CurrencyManager funcionalidade e expõe CurrencyManager eventos

em tempo de design.
Simplifica a criação de uma lista que dá suporte à IBindingList interface fornecendo

notificação de alteração de lista para fontes de dados que não dão suporte nativo
à notificação de alteração de lista.
Fornece um ponto de extensibilidade para o IBindingList.AddNew método.
Fornece um nível de indireção entre a fonte de dados e o controle. A indireção é

importante quando a fonte de dados pode se alterar em tempo de execução.
Interopera com outros controles de Windows Forms relacionados a dados,

especificamente os controles e os BindingNavigatorDataGridView controles.
Por esses motivos, o BindingSource componente é a maneira preferida de associar seus

controles de Windows Forms a fontes de dados.
Recursos do BindingSource
O BindingSource componente fornece vários recursos para controles de associação aos
dados. Com esses recursos, você pode implementar a maioria dos cenários de
associação de dados com quase nenhuma codificação de sua parte.
O BindingSource componente faz isso fornecendo uma interface consistente para

acessar muitos tipos diferentes de fontes de dados. Isso significa que você usa o mesmo
procedimento para associar a qualquer tipo. Por exemplo, você pode anexar a
DataSource propriedade a um ou a um DataSet objeto de negócios e, em ambos os
casos, você usa o mesmo conjunto de propriedades, métodos e eventos para manipular
a fonte de dados.
A interface consistente fornecida pelo BindingSource componente simplifica muito o

processo de associação de dados aos controles. Para tipos de fonte de dados que
fornecem notificação de alteração, o BindingSource componente comunica
automaticamente as alterações entre o controle e a fonte de dados. Para tipos de fonte
de dados que não fornecem notificação de alteração, são fornecidos eventos que
permitem gerar notificações de alteração. A lista a seguir mostra os recursos
compatíveis com o BindingSource componente:
Indireção.
Gerenciamento de moeda.
Fonte de dados como uma lista.
BindingSource como um IBindingList.
Criação de item personalizado.
Criação de item transacional.
IEnumerable Apoio.
Suporte a tempo de design.
Métodos estáticos ListBindingHelper .
Classificação e filtragem com a IBindingListView interface.
Integração com BindingNavigator.
Indireção
O BindingSource componente fornece um nível de indireção entre um controle e uma
fonte de dados. Em vez de associar um controle diretamente a uma fonte de dados,
você associa o controle a um BindingSourcee anexa a fonte de dados à BindingSource
propriedade do DataSource componente.
Com esse nível de indireção, você pode alterar a fonte de dados sem redefinir a
associação de controle. Isso oferece as seguintes funcionalidades:
Você pode anexar a BindingSource fontes de dados diferentes enquanto mantém

as associações de controle atuais.
Você pode alterar os itens na fonte de dados e notificar os controles associados.
Para obter mais informações, consulte Como refletir atualizações feitas na fonte de
dados em um controle dos Windows Forms com o BindingSource.
Você pode associar a um Type objeto em vez de um objeto na memória. Para

obter mais informações, consulte Como associar um controle dos Windows Forms
a um tipo. Em seguida, você pode associar a um objeto em tempo de execução.
Gerenciamento de moedas
O BindingSource componente implementa a interface para lidar com o
ICurrencyManagerProvider gerenciamento de moeda para você. Com a
ICurrencyManagerProvider interface, você também pode acessar o gerenciador de
moedas para um BindingSource, além do gerenciador de moedas para outro
BindingSource associado ao mesmo DataMember.
O BindingSource componente encapsula a CurrencyManager funcionalidade e expõe as

propriedades e eventos mais comuns CurrencyManager . A tabela a seguir descreve
alguns dos membros relacionados ao gerenciamento de moeda.
Propriedade CurrencyManager
Obtém o gerenciador de moedas associado ao BindingSource.
Método GetRelatedCurrencyManager
Se houver outro BindingSource limite para o membro de dados especificado, obterá seu
gerenciador de moedas.
Propriedade Current
Obtém o item atual da fonte de dados.
Propriedade Position
Obtém ou define a posição atual na lista subjacente.
Método EndEdit
Aplica as alterações pendentes à fonte de dados subjacente.
Método CancelEdit
Cancela a operação de edição atual.
Fonte de dados como uma lista

O BindingSource componente implementa o e ITypedList as IBindingListView interfaces.
Com essa implementação, você pode usar o BindingSource próprio componente como
uma fonte de dados, sem nenhum armazenamento externo.
Quando o BindingSource componente é anexado a uma fonte de dados, ele expõe a

fonte de dados como uma lista.
A DataSource propriedade pode ser definida como várias fontes de dados. Isso inclui
tipos, objetos e listas de tipos. A fonte de dados resultante será exposta como uma lista.
A tabela a seguir mostra algumas das fontes de dados comuns e a avaliação de lista
resultante.
Propriedade DataSource Listar resultados
Uma referência nula ( Nothing no Visual Um vazio IBindingList de objetos. Adicionar um item
Basic) define a lista como o tipo do item adicionado.
Uma referência nula ( Nothing no Visual Sem suporte; ArgumentExceptiongera .

Basic) com DataMember conjunto
Tipo fora da lista ou objeto do tipo "T" Um vazio IBindingList do tipo "T".
Instância de matriz Um IBindingList que contém os elementos da matriz.
IEnumerable Instância Um IBindingList que contém os IEnumerable itens
Instância de lista que contém o tipo "T" Uma IBindingList instância que contém o tipo "T".
Além disso, DataSource pode ser definido como outros tipos de lista, como IListSource
e ITypedList, e eles BindingSource serão tratados adequadamente. Nesse caso, o tipo
contido na lista deve ter um construtor sem parâmetros.
BindingSource como uma IBindingList

O BindingSource componente fornece membros para acessar e manipular os dados
subjacentes como um IBindingList. A tabela a seguir descreve alguns desses membros.
Membro DESCRIÇÃO
Propriedade Obtém a lista que resulta da avaliação das propriedades ou DataMember da

List DataSource avaliação.
Método Adiciona um novo item à lista subjacente. Aplica-se a fontes de dados que
AddNew implementam a IBindingList interface e permitem a adição de itens (ou seja, a
AllowNew propriedade está definida como true ).
Criação de item personalizado

Você pode manipular o AddingNew evento para fornecer sua própria lógica de criação
de item. O AddingNew evento ocorre antes de um novo objeto ser adicionado ao
BindingSource. Esse evento é gerado depois que o AddNew método é chamado, mas
antes que o novo item seja adicionado à lista subjacente. Ao manipular esse evento,
você pode fornecer o comportamento de criação de item personalizado sem derivar da
BindingSource classe. Para obter mais informações, veja Como personalizar a adição de
item com o BindingSource dos Windows Forms.
Criação de item transacional

O BindingSource componente implementa a ICancelAddNew interface, que permite a
criação de item transacional. Depois que um novo item for criado provisoriamente
usando uma chamada, AddNewa adição poderá ser confirmada ou revertida das
seguintes maneiras:
O EndNew método confirmará explicitamente a adição pendente.
A realização de outra operação de coleção, como uma inserção, remoção ou

mover, confirmará implicitamente a adição pendente.
O CancelNew método reverterá a adição pendente se o método ainda não tiver

sido confirmado.
Suporte a IEnumerable
O BindingSource componente permite controles de associação a IEnumerable fontes de
dados. Com esse componente, você pode associar a uma fonte de dados, como um
System.Data.SqlClient.SqlDataReader.
Quando uma IEnumerable fonte de dados é atribuída ao BindingSource componente,

ela BindingSource cria um IBindingList e adiciona o conteúdo da fonte de IEnumerable
dados à lista.
Suporte a tempo de design

Alguns tipos de objeto não podem ser criados em tempo de design, como objetos
criados de uma classe de fábrica ou objetos retornados por um serviço Web. Às vezes é
necessário associar os controles a esses tipos em tempo de design, mesmo que não haja
nenhum objeto na memória aos quais os controles podem ser associados. Você pode,
por exemplo, precisar rotular os cabeçalhos de coluna de um DataGridView controle
com os nomes das propriedades públicas do tipo personalizado.
Para dar suporte a esse cenário, o BindingSource componente dá suporte à associação a
um Type. Quando você atribui uma Type à DataSource propriedade, o BindingSource
componente cria um vazio BindingList<T> de Type itens. Todos os controles que você
associar posteriormente ao BindingSource componente serão alertados sobre a
presença das propriedades ou esquema do seu tipo em tempo de design ou em tempo
de execução. Para obter mais informações, consulte Como associar um controle dos
Windows Forms a um tipo.
Métodos estáticos ListBindingHelper

O System.Windows.Forms.BindingContext, System.Windows.Forms.CurrencyManagere
BindingSource tipos, todos compartilham lógica comum para gerar uma lista de um
DataSource / DataMember par. Além disso, essa lógica comum é publicamente exposta
para ser usada por autores de controle e terceiros nos seguintes métodos static :
GetListItemProperties
GetList.
GetListName
GetListItemType
Classificação e filtragem com a interface IBindingListView

O BindingSource componente implementa a IBindingListView interface, que estende a
IBindingList interface. A IBindingList classificação de coluna única oferece classificação e
IBindingListView filtragem avançadas. Com IBindingListView, você pode classificar e
filtrar itens na fonte de dados, se a fonte de dados também implementar uma dessas
interfaces. O BindingSource componente não fornece uma implementação de referência
desses membros. Em vez disso, as chamadas são encaminhadas para a lista subjacente.
A tabela a seguir descreve as propriedades que você pode usar para classificação e
filtragem.
Membro DESCRIÇÃO
Propriedade Se a fonte de dados for uma IBindingListView, obtém ou define a expressão usada
Filter para filtrar quais linhas são exibidas.
Membro DESCRIÇÃO
Propriedade Se a fonte de dados for um IBindingList, obtém ou define um nome de coluna

Sort usado para classificar e classificar informações de ordem.
-ou-
Se a fonte de dados for uma IBindingListView e oferecer suporte à classificação

avançada, obterá vários nomes de coluna usados para classificação e ordem de
classificação
Integração com o BindingNavigator

Você pode usar o BindingSource componente para associar qualquer controle de
Windows Forms a uma fonte de dados, mas o BindingNavigator controle foi projetado
especificamente para funcionar com o BindingSource componente. O BindingNavigator
controle fornece uma interface do usuário para controlar o BindingSource item atual do
componente. Por padrão, o BindingNavigator controle fornece botões que
correspondem aos métodos de navegação no BindingSource componente. Para obter
mais informações, consulte Como navegar em dados com o controle BindingNavigator
dos Windows Forms.
Confira também
BindingSource
BindingNavigator
Como: Refletir atualizações feitas na fonte de dados em um controle do Windows
Forms com o BindingSource
Como: Associar um controle do
Windows Forms a um objeto de
alocador
Artigo • 02/06/2023
Quando você estiver criando controles que interagem com os dados, às vezes, será
necessário associar um controle a um objeto ou método que gere outros objetos. Esse
objeto ou método é chamado de alocador. A fonte de dados pode ser, por exemplo, o
valor retornado de uma chamada de método, em vez de um objeto na memória ou um
tipo. Você pode associar um controle a esse tipo de fonte de dados desde que a fonte
retorne uma coleção.
Você pode associar facilmente um controle a um objeto de fábrica usando o

BindingSource controle.
Exemplo
O exemplo a seguir demonstra como associar um DataGridView controle a um método
de fábrica usando um BindingSource controle. O método de fábrica chama-se
GetOrdersByCustomerId e retorna todos os pedidos para determinado cliente no banco
de dados Northwind.
C#
using System;
using System.Data;
using System.Data.Common;
using System.Diagnostics;
// This form demonstrates using a BindingSource to bind to a factory

// object.
public class Form1 : System.Windows.Forms.Form
{
// This is the TextBox for entering CustomerID values.
private TextBox customerIdTextBox = new TextBox();
// This is the DataGridView that displays orders for the

// specified customer.
private DataGridView customersDataGridView = new DataGridView();
// This is the BindingSource for binding the database query

// result set to the DataGridView.
private BindingSource ordersBindingSource = new BindingSource();
public Form1()
{
// Set up the CustomerID TextBox.
this.customerIdTextBox.Location = new Point(100, 200);
this.customerIdTextBox.Size = new Size(500, 30);
this.customerIdTextBox.Text =
"Enter a valid Northwind CustomerID, for example: ALFKI," +
" then RETURN or click outside the TextBox";
this.customerIdTextBox.Leave +=
new EventHandler(customerIdTextBox_Leave);
this.customerIdTextBox.KeyDown +=
new KeyEventHandler(customerIdTextBox_KeyDown);
this.Controls.Add(this.customerIdTextBox);
// Set up the DataGridView.

customersDataGridView.Dock = DockStyle.Top;
this.Controls.Add(customersDataGridView);
// Set up the form.

}
// This event handler binds the BindingSource to the DataGridView

// control's DataSource property.
private void Form1_Load(
System.Object sender,
System.EventArgs e)
{
// Attach the BindingSource to the DataGridView.
this.customersDataGridView.DataSource =
this.ordersBindingSource;
}
// This is a static factory method. It queries the Northwind

// database for the orders belonging to the specified
// customer and returns an IEnumerable.
public static IEnumerable GetOrdersByCustomerId(string id)
{
// Open a connection to the database.
string connectString = "Integrated Security=SSPI;" +
"Persist Security Info=False;Initial Catalog=Northwind;" +
"Data Source= localhost";
SqlConnection connection = new SqlConnection();
connection.ConnectionString = connectString;
connection.Open();
// Execute the query.

string queryString =
String.Format("Select * From Orders where CustomerID = '{0}'",
id);
SqlCommand command = new SqlCommand(queryString, connection);
SqlDataReader reader =
command.ExecuteReader(CommandBehavior.CloseConnection);
return reader;
}
// These event handlers are called when the user tabs or clicks
// out of the customerIdTextBox or hits the return key.
// The database is then queried with the CustomerID
// in the customerIdTextBox.Text property.
void customerIdTextBox_Leave(object sender, EventArgs e)
{
// Attach the data source to the BindingSource control.
this.ordersBindingSource.DataSource =
GetOrdersByCustomerId(this.customerIdTextBox.Text);
}
void customerIdTextBox_KeyDown(object sender, KeyEventArgs e)

{
if (e.KeyCode == Keys.Return)
{
// Attach the data source to the BindingSource control.
this.ordersBindingSource.DataSource =
GetOrdersByCustomerId(this.customerIdTextBox.Text);
}
}
[STAThread]
static void Main()
{
}
}
Referências aos assemblies System, System.Data, System.Drawing e

System.Windows.Forms.
Confira também
BindingNavigator
DataGridView
BindingSource
Windows Forms a um tipo
Artigo • 02/06/2023
Quando estiver criando controles que interagem com os dados, às vezes, achará
necessário associar um controle a um tipo, em vez de um objeto. Essa situação ocorre
especialmente em tempo de design, quando os dados podem não estar disponíveis,
mas seus controles ligados a dados ainda precisam exibir informações da interface
pública de um tipo. Por exemplo, você pode associar um DataGridView controle a um
objeto exposto por um serviço Web e desejar que o DataGridView controle rotule suas
colunas em tempo de design com os nomes de membro de um tipo personalizado.
Você pode associar facilmente um controle a um tipo com o BindingSource

componente.
Exemplo
O exemplo de código a seguir demonstra como associar um DataGridView controle a
um tipo personalizado usando um BindingSource componente. Ao executar o exemplo,
você observará as DataGridView colunas rotuladas que refletem as propriedades de um
Customer objeto, antes que o controle seja preenchido com dados. O exemplo tem um
botão Adicionar Cliente para adicionar dados ao DataGridView controle. Quando você
clica no botão, um novo Customer objeto é adicionado ao BindingSource. Em um
cenário do mundo real, os dados podem ser obtidos por uma chamada para um serviço
Web ou outra fonte de dados.
C#
using System;
using System.Data;
class Form1 : Form

{
BindingSource bSource = new BindingSource();
private Button button1;
DataGridView dgv = new DataGridView();
public Form1()
{
this.button1 = new System.Windows.Forms.Button();
this.button1.Location = new System.Drawing.Point(140, 326);
this.button1.Name = "button1";
this.button1.AutoSize = true;
this.button1.Text = "Add Customer";
this.button1.Click += new System.EventHandler(this.button1_Click);
this.Controls.Add(this.button1);
// Bind the BindingSource to the DemoCustomer type.

bSource.DataSource = typeof(DemoCustomer);
// Set up the DataGridView control.

dgv.Dock = DockStyle.Top;
this.Controls.Add(dgv);
// Bind the DataGridView control to the BindingSource.

dgv.DataSource = bSource;
}
{
}
private void button1_Click(object sender, EventArgs e)

{
bSource.Add(new DemoCustomer(DateTime.Today));
}
}
// This simple class is used to demonstrate binding to a type.

public class DemoCustomer
{
public DemoCustomer()
{
idValue = Guid.NewGuid();
}
public DemoCustomer(DateTime FirstOrderDate)

{
FirstOrder = FirstOrderDate;
idValue = Guid.NewGuid();
}
// These fields hold the data that backs the public properties.
private DateTime firstOrderDateValue;
private Guid idValue;
private string custNameValue;
public string CustomerName

{
get { return custNameValue; }
set { custNameValue = value; }
}
// This is a property that represents a birth date.

public DateTime FirstOrder
{
get
{
return this.firstOrderDateValue;
}
set
{
if (value != this.firstOrderDateValue)
{
this.firstOrderDateValue = value;
}
}
}
// This is a property that represents a customer ID.

public Guid ID
{
get
{
return this.idValue;
}
}
}
Referências aos assemblies System e System.Windows.Forms.
Confira também
BindingNavigator
DataGridView
BindingSource
Windows Forms a um tipo usando o
Designer
Artigo • 02/06/2023
Quando estiver compilando controles que interagem com os dados, pode ser necessário
associar um controle a um tipo, em vez de um objeto. Geralmente é necessário associar
um controle a um tipo no tempo de design, quando os dados podem não estar
disponíveis, mas ainda é recomendável fazer com que os controles associados a dados
exibam dados da interface pública de um tipo. Os procedimentos a seguir demonstram
como criar um novo BindingSource associado a um tipo e, em seguida, como associar
uma das propriedades do tipo à Text propriedade de um TextBox.
Associar o BindingSource a um tipo

1. Criar um projeto Windows Forms (Arquivo>Novo>Projeto>Visual C# ou Visual
Basic>Classic Desktop>Windows Forms Aplicativo).
2. No modo Design , arraste um BindingSource componente para o formulário.
3. Na janela Propriedades , clique na seta da DataSource propriedade.
4. No Editor de tipo de interface do usuário de DataSource, clique em Adicionar

fonte de dados do projeto.
5. Na página Escolher um tipo de fonte de dados, selecione Objeto e clique em

Avançar.
6. Selecione o tipo para associar a:
Se o tipo ao qual você deseja associar está no projeto atual ou o assembly

que contém o tipo já foi adicionado como uma referência, expanda os nós
para localizar o tipo desejado e, em seguida, selecione-o.
-ou-
Se o tipo ao qual você deseja associar estiver em outro assembly, no

momento não está na lista de referências, clique em Adicionar Referência e
clique na guia Projetos . Selecione o projeto que contém o objeto de
negócios desejado e clique em OK. Este projeto será exibido na lista de
assemblies, portanto é possível expandir os nós para encontrar o tipo
desejado e, em seguida, selecioná-lo.
７ Observação
Se você desejar associar a um tipo em uma estrutura ou assembly

Microsoft, desmarque a caixa de seleção Ocultar assemblies que
começam com Microsoft ou System.
7. Clique em Avançare em Concluir.
Associar o controle ao BindingSource

1. Adicione um TextBox ao formulário.
2. Na janela Propriedades, expanda o nó (DataBindings).
3. Clique na seta ao lado da Text propriedade.
4. No Editor de Tipos de Interface do Usuário do DataSource, expanda o nó para o

BindingSource adicionado anteriormente e selecione a propriedade do tipo
associado que você deseja associar à Text propriedade do .TextBox
Confira também
Como: Associar a um serviço Web
usando o BindingSource do Windows
Forms
Artigo • 02/06/2023
Se você quiser associar um controle do Windows Form aos resultados obtidos ao

chamar um serviço Web XML, poderá usar um BindingSource componente. Esse
procedimento é semelhante à associação de um BindingSource componente a um tipo.
É necessário criar um proxy do lado do cliente que contenha os métodos e tipos
expostos pelo serviço Web. O proxy do lado do cliente será gerado pelo próprio serviço
Web (.asmx) ou pelo arquivo de linguagem WSDL. Além disso, o proxy do lado do
cliente deve expor os campos dos tipos complexos usados pelo serviço Web como
propriedades públicas. Em seguida, você associa a BindingSource um dos tipos expostos
no proxy de serviço Web.
Criar e associar a um proxy do lado do cliente

1. Crie um formulário do Windows Forms em um diretório de sua escolha, com um
namespace apropriado.
2. Adicione um BindingSource componente ao formulário.
3. Abra o prompt de comando do SDK (Windows Software Development Kit) e

navegue até o mesmo diretório no qual seu formulário está localizado.
4. Com a ferramenta WSDL, digite wsdl e a URL do arquivo .asmx ou WSDL para o
serviço Web, seguida pelo namespace do aplicativo e, opcionalmente, o idioma de
trabalho.
O exemplo de código a seguir usa o serviço Web localizado em

http://webservices.eraserver.net/zipcoderesolver/zipcoderesolver.asmx . Por
exemplo, para o tipo wsdl

http://webservices.eraserver.net.zipcoderesolver/zipcoderesolver.asmx
/n:BindToWebService do C# ou para o tipo wsdl
http://webservices.eraserver.net.zipcoderesolver/zipcoderesolver.asmx
/n:BindToWebService /language:VB do Visual Basic. Passar o caminho como um
argumento para a ferramenta WSDL gerará um proxy do lado do cliente no

mesmo diretório e namespace do aplicativo, no idioma especificado. Se você
estiver usando o Visual Studio, adicione o arquivo ao seu projeto.
5. Selecione um tipo para associar ao proxy do lado do cliente.
Geralmente, esse é um tipo retornado por um método oferecido pelo serviço Web.
Os campos do tipo escolhido devem ser expostos como propriedades públicas
para fins de associação.
C#
[System.SerializableAttribute,
System.Xml.Serialization.XmlTypeAttribute(
Namespace="http://webservices.eraserver.net/")]
public class USPSAddress
{
private string streetField;
private string cityField;
private string stateField;
private string shortZIPField;
private string fullZIPField;
public string Street

{
get
{
return this.streetField;
}
set
{
this.streetField = value;
}
}
public string City

{
get
{
return this.cityField;
}
set
{
this.cityField = value;
}
}
public string State

{
get
{
return this.stateField;
}
set
{
this.stateField = value;
}
}
public string ShortZIP

{
get
{
return this.shortZIPField;
}
set
{
this.shortZIPField = value;
}
}
public string FullZIP

{
get
{
return this.fullZIPField;
}
set
{
this.fullZIPField = value;
}
}
}
6. Defina a DataSource propriedade do BindingSource tipo que você deseja que

esteja contida no proxy do lado do cliente do serviço Web.
C#
BindingSource1.DataSource = typeof(USPSAddress);
Associar controles ao BindingSource que está associado a

um serviço Web
Associe controles BindingSourceà propriedade pública do tipo de serviço Web que
você deseja como parâmetro.
C#
textBox1.DataBindings.Add("Text", this.BindingSource1, "FullZIP",

true);
Exemplo
O exemplo de código a seguir demonstra como associar um BindingSource
componente a um serviço Web e, em seguida, como associar uma caixa de texto ao
BindingSource componente. Ao clicar no botão, um método de serviço Web será
chamado e os resultados serão exibidos no textbox1 .
C#
using System;
namespace BindToWebService {
class Form1: Form
{
[STAThread]
{
}
private BindingSource BindingSource1 = new BindingSource();

private TextBox textBox1 = new TextBox();
private Button button1 = new Button();
public Form1()
{
textBox1.Location = new System.Drawing.Point(118, 131);
textBox1.ReadOnly = true;
button1.Location = new System.Drawing.Point(133, 60);
button1.Click += new EventHandler(button1_Click);
button1.Text = "Get zipcode";
ClientSize = new System.Drawing.Size(292, 266);
Controls.Add(this.button1);
Controls.Add(this.textBox1);
}

{
textBox1.Text = "Calling Web service..";

ZipCodeResolver resolver = new ZipCodeResolver();
BindingSource1.Add(resolver.CorrectedAddressXml("0",
"One Microsoft Way", "Redmond", "WA"));
}
public void Form1_Load(object sender, EventArgs e)

{
BindingSource1.DataSource = typeof(USPSAddress);
textBox1.DataBindings.Add("Text", this.BindingSource1,
"FullZIP", true);
}
}
[System.Web.Services.WebServiceBindingAttribute(Name="ZipCodeResolverSoap",
public class ZipCodeResolver:
System.Web.Services.Protocols.SoapHttpClientProtocol
public ZipCodeResolver() : base()

{
this.Url =
"http://webservices.eraserver.net/zipcoderesolver/zipcoderesolver.asmx";
}
//''<remarks/>
[System.Web.Services.Protocols.SoapDocumentMethodAttribute
("http://webservices.eraserver.net/CorrectedAddressXml",
RequestNamespace="http://webservices.eraserver.net/",
ResponseNamespace="http://webservices.eraserver.net/",
Use=System.Web.Services.Description.SoapBindingUse.Literal,
ParameterStyle=System.Web.Services.Protocols.SoapParameterStyle.Wrapped)]
public USPSAddress CorrectedAddressXml(string accessCode,
string address, string city, string state)
{
object[] results = this.Invoke("CorrectedAddressXml",
new object[]{accessCode, address, city, state});
return ((USPSAddress) results[0]);
}
//''<remarks/>
public System.IAsyncResult BeginCorrectedAddressXml(string
accessCode,
string address, string city, string state,
System.AsyncCallback callback, object asyncState)
{
return this.BeginInvoke("CorrectedAddressXml",
new object[]{accessCode, address, city, state}, callback,
asyncState);
}
public USPSAddress EndCorrectedAddressXml(System.IAsyncResult

asyncResult)
{
object[] results = this.EndInvoke(asyncResult);
return ((USPSAddress) results[0]);
}
}
[System.SerializableAttribute,
System.Xml.Serialization.XmlTypeAttribute(
public class USPSAddress
{
private string streetField;
private string cityField;
private string stateField;
private string shortZIPField;
private string fullZIPField;
public string Street

{
get
{
return this.streetField;
}
set
{
this.streetField = value;
}
}
public string City

{
get
{
return this.cityField;
}
set
{
this.cityField = value;
}
}
public string State

{
get
{
return this.stateField;
}
set
{
this.stateField = value;
}
}
public string ShortZIP

{
get
{
return this.shortZIPField;
}
set
{
this.shortZIPField = value;
}
}
public string FullZIP

{
get
{
return this.fullZIPField;
}
set
{
this.fullZIPField = value;
}
}
}
public delegate void CorrectedAddressXmlCompletedEventHandler(object

sender,
CorrectedAddressXmlCompletedEventArgs args);
public class CorrectedAddressXmlCompletedEventArgs:

System.ComponentModel.AsyncCompletedEventArgs
{
private object[] results;
internal CorrectedAddressXmlCompletedEventArgs(object[] results,

System.Exception exception, bool cancelled, object userState) :
base(exception, cancelled, userState)
{
this.results = results;
}
public USPSAddress Result

{
get
{
this.RaiseExceptionIfNecessary();
return ((USPSAddress) this.results[0]);
}
}
}
}
Este é um exemplo completo que inclui um método Main e uma versão abreviada do
código de proxy do lado do cliente.
Referências aos assemblies System, System.Drawing, System.Web.Services,

Confira também
Como: Como associar controles do
Windows Forms a valores de banco de
dados DBNull
Artigo • 02/06/2023
Quando você associa Windows Forms controles a uma fonte de dados e a fonte de
dados retorna um DBNull valor, você pode substituir um valor apropriado sem
manipular, formatar ou analisar eventos. A NullValue propriedade será convertida
DBNull em um objeto especificado ao formatar ou analisar os valores da fonte de
dados.
Exemplo
O exemplo a seguir demonstra como associar um DBNull valor em duas situações
diferentes. O primeiro demonstra como definir a NullValue propriedade de uma cadeia
de caracteres; a segunda demonstra como definir a NullValue propriedade de uma
imagem.
C#
using System;
using System.Data;
using System.Text;
namespace DBNullCS
{
{
public Form1()
{
}
// The controls and components we need for the form.

private PictureBox pictureBox1;
// Data table to hold the database data.
DataTable employeeTable = new DataTable();
void Form1_Load(object sender, EventArgs e)

{
// Basic form setup.
this.pictureBox1 = new PictureBox();
this.bindingSource1 = new BindingSource();
this.textBox1 = new TextBox();
this.textBox2 = new TextBox();
this.button1 = new Button();
this.pictureBox1.Location = new System.Drawing.Point(20, 20);
this.pictureBox1.Size = new System.Drawing.Size(174, 179);
this.textBox1.ReadOnly = true;
this.button1.Text = "Move Next";
this.button1.Click += new
System.EventHandler(this.button1_Click);
this.Controls.Add(this.pictureBox1);
// Create the connection string and populate the data table

// with data.
string connectionString = "Integrated Security=SSPI;" +
"Persist Security Info = False;Initial Catalog=Northwind;" +
"Data Source = localhost";
SqlConnection connection = new SqlConnection();
connection.ConnectionString = connectionString;
SqlDataAdapter employeeAdapter =
new SqlDataAdapter(new SqlCommand("Select * from Employees",
connection));
connection.Open();
employeeAdapter.Fill(employeeTable);
// Set the DataSource property of the BindingSource to the

employee table.
bindingSource1.DataSource = employeeTable;
// Set up the binding to the ReportsTo column.

Binding reportsToBinding = textBox2.DataBindings.Add("Text",
bindingSource1,
"ReportsTo", true);
// Set the NullValue property for this binding.

reportsToBinding.NullValue = "No Manager";
// Set up the binding for the PictureBox using the Add method,
setting
// the null value in method call.
pictureBox1.DataBindings.Add("Image", bindingSource1, "Photo",
true,
DataSourceUpdateMode.Never, new Bitmap(typeof(Button),
"Button.bmp"));
// Set up the remaining binding.

textBox1.DataBindings.Add("Text", bindingSource1, "LastName",
true);
}
// Move through the data when the button is clicked.

{
bindingSource1.MoveNext();
}
[STAThread]
static void Main()
{
}
}
}
Os tipos da propriedade associada e da NullValue propriedade devem ser os mesmos

ou um erro resultará e nenhum valor adicional NullValue será processado. Nessa
situação, uma exceção não será gerada.

Confira também
Como: Associar controles do Windows
Forms ao componente BindingSource
usando o designer
Artigo • 02/06/2023
Depois de adicionar controles ao formulário e determinar a interface do usuário para

seu aplicativo, você pode associar os controles a uma fonte de dados, para que os
usuários possam alterar e salvar dados relacionados ao aplicativo no tempo de
execução.
Associar um controle ou uma série de controles em Windows Forms é mais facilmente

realizada usando o BindingSource controle como uma ponte entre os controles no
formulário e a fonte de dados.
Um ou mais controles em um formulário podem ser associados a dados; no

procedimento a seguir, um TextBox controle está associado a uma fonte de dados.
Para concluir o procedimento, presume-se que você associará a uma fonte de dados
derivada de um banco de dados. Para obter mais informações sobre como criar fontes
de dados de outros armazenamentos de dados, consulte Adicionar novas fontes de
dados.
Associar um controle no tempo de design

1. Arraste um TextBox controle para o formulário.
2. Na janela Propriedades:
a. Expanda o nó (DataBindings).
b. Clique na seta ao lado da Text propriedade.
O editor de tipo de interface do usuário DataSource abre.
Se uma fonte de dados tiver sido configurada anteriormente para o projeto ou

formulário, ela será exibida.
3. Clique em Adicionar Fonte de Dados do Projeto para conectar-se aos dados e

criar uma fonte de dados.
4. Na página de boas-vindas do Assistente de Configuração de Fonte de Dados,
clique em Avançar.
5. Na página Escolher um tipo de fonte de dados, selecione Banco de dados.
6. Na página Escolha sua conexão de dados, selecione uma conexão de dados da

lista de conexões disponíveis. Se a conexão de dados desejada não estiver
disponível, selecione Nova Conexão para criar uma nova conexão de dados.
7. Selecione Sim, salvar a conexão para salvar a cadeia de conexão no arquivo de

configuração de aplicativo.
8. Selecione os objetos de banco de dados para trazer para o seu aplicativo. Nesse
caso, selecione um campo em uma tabela que você deseja TextBox exibir.
9. Substitua o nome do conjunto de dados padrão, se quiser.
10. Clique em Concluir.
11. Na janela Propriedades , clique na seta ao lado da Text propriedade novamente.

No editor de tipos de interface do usuário do DataSource , selecione o nome do
campo ao qual TextBox associar.
O editor de tipos de interface do usuário do DataSource fecha e o conjunto de

dados e BindingSource o adaptador de tabela específico para essa conexão de
dados são adicionados ao formulário.
Confira também
BindingSource
BindingNavigator
Adicionar novas fontes de dados
Janela Fontes de Dados
Como: Criar uma tabela de pesquisa
com o componente BindingSource do
Windows Forms
Artigo • 02/06/2023
A tabela de pesquisa é uma tabela de dados que tem uma coluna que exibe dados de
registros em uma tabela relacionada. Nos procedimentos a seguir, um controle
ComboBox é usado para exibir o campo com a relação de chave estrangeira da tabela
pai para a tabela filho.
Para ajudar a visualizar essas duas tabelas e essa relação, veja a seguir um exemplo de
uma tabela pai e filho:
CustomersTable (tabela pai)
CustomerID CustomerName
712 Paul Koch
713 Tamara Johnston
OrdersTable (tabela filho)
OrderID OrderDate CustomerID
903 12.02.04 712
904 13.02.04 713
Neste cenário, uma tabela, CustomersTable, armazena a informação real que você deseja
exibir e salvar. Mas, para economizar espaço, a tabela deixa de fora dados que
adicionam clareza. A outra tabela, OrdersTable, contém apenas informações
relacionadas à aparência sobre qual número da ID do cliente é equivalente a qual data
de pedido e ID do pedido. Não há nenhuma menção dos nomes dos clientes.
Quatro propriedades importantes são definidas no Controle ComboBox para criar a

tabela de pesquisa.
A propriedade DataSource contém o nome da tabela.
A propriedade DisplayMember contém a coluna de dados da tabela que você

deseja exibir para o texto de controle (nome do cliente).
A propriedade ValueMember contém a coluna de dados dessa tabela com as
informações armazenadas (o número de ID na tabela pai).
A propriedade SelectedValue fornece o valor de pesquisa da tabela filho, com base

no ValueMember.
Os procedimentos a seguir mostram como dispor um formulário como uma tabela de

pesquisa e vincular dados aos controles nele. Para concluir com êxito os procedimentos,
você deve ter uma fonte de dados com as tabelas pai e filho que tenham uma relação
de chave estrangeira, como mencionado anteriormente.
Para criar a interface do usuário

1. Na Caixa de Ferramentas, arraste um ComboBox controle para o formulário.
Esse controle exibirá a coluna da tabela pai.
2. Arraste outros controles para exibir detalhes da tabela filho. O formato dos dados
na tabela deve determinar quais controles você escolhe. Para obter mais
informações, consulte Controles dos Windows Forms por função.
3. Arraste um controle BindingNavigator para o formulário; isso permitirá que você

navegue os dados na tabela filho.
Para conectar-se aos dados e vinculá-lo aos controles

1. Selecione o ComboBox e clique no glifo da Tarefa Inteligente para exibir a caixa de
diálogo Tarefa Inteligente.
2. Selecione Usar itens vinculados aos dados.
3. Clique na seta ao lado da caixa suspensa Fonte de Dados. Se uma fonte de dados
foi configurada anteriormente para o projeto ou formulário, ela aparecerá; caso
contrário, siga as seguintes etapas (Este exemplo usa as tabelas Clientes e Pedidos
do banco de dados de amostra Northwind e refere-se a elas nos parênteses).
a. Clique em Adicionar Fonte de Dados do Projeto para conectar-se aos dados e

criar uma fonte de dados.
b. Na página de boas-vindas do Assistente de Configuração de Fonte de Dados,

clique em Avançar.
c. Selecione Banco de dados na página Escolher um tipo de fonte de dados.

d. Escolha uma conexão de dados na lista de conexões disponíveis na página
Escolha a conexão de dados. Se sua conexão de dados desejada não estiver
disponível, selecione Nova Conexão para criar uma nova conexão de dados.
e. Clique em Sim, salvar a conexão para salvar a cadeia de conexão no arquivo de

configuração de aplicativo.
f. Selecione os objetos de banco de dados para trazer para o seu aplicativo. Neste
caso, selecione uma tabela pai e uma tabela filho (por exemplo, clientes e
pedidos) com uma relação de chave estrangeira.
g. Substitua o nome do conjunto de dados padrão, se quiser.
h. Clique em Concluir.
4. Na caixa suspensa Exibir Membro, selecione o nome da coluna (por exemplo,

ContactName) a ser exibida na caixa de combinação.
5. Na caixa suspensa Membro do Valor, selecione a coluna (por exemplo,

CustomerID) para executar a operação de pesquisa na tabela filho.
6. Na caixa suspensa Valor Selecionado, navegue até Fontes de Dados do Projeto e

o conjunto de dados que você criou que contém as tabelas pai e filho. Selecione a
mesma propriedade da tabela filho que é o Membro do Valor da tabela pai (por
exemplo, Orders.CustomerID). Os BindingSource, componentes do conjunto de
dados e do adaptador de tabela adequado, serão criados e adicionados ao
formulário.
7. Vincule o controle BindingNavigator para o BindingSource da tabela filho (por

exemplo, OrdersBindingSource ).
8. Vincule os controles diferentes dos controles ComboBox e BindingNavigator aos

campos de detalhes do BindingSource da tabela filho (Por exemplo,
OrdersBindingSource ) que você deseja exibir.
Confira também
BindingSource
Controle ComboBox
Como: Como personalizar a adição de
item com o BindingSource do Windows
Forms
Artigo • 21/06/2023
Ao usar um BindingSource componente para associar um controle Windows Forms a

uma fonte de dados, talvez seja necessário personalizar a criação de novos itens. O
BindingSource componente torna isso simples fornecendo o AddingNew evento , que
normalmente é gerado quando o controle associado precisa criar um novo item. O
manipulador de eventos pode fornecer qualquer comportamento personalizado
necessário (por exemplo, chamar um método em um serviço Web ou obter um novo
objeto de uma fábrica de classes).
７ Observação
Quando um item é adicionado manipulando o AddingNew evento, a adição não

pode ser cancelada.
Exemplo
O exemplo a seguir demonstra como associar um DataGridView controle a uma fábrica
de classes usando um BindingSource componente . Quando o usuário clica na
DataGridView nova linha do controle, o AddingNew evento é gerado. O manipulador de
eventos cria um novo DemoCustomer objeto , que é atribuído à
AddingNewEventArgs.NewObject propriedade . Isso faz com que o novo DemoCustomer
objeto seja adicionado à BindingSource lista do componente e seja exibido na nova
linha do DataGridView controle.
C#
using System;
using System.Data;
// This form demonstrates using a BindingSource to provide

// data from a collection of custom types to a DataGridView control.
{
// This is the BindingSource that will provide data for
// the DataGridView control.
private BindingSource customersBindingSource = new BindingSource();
// This is the DataGridView control that will display our data.

// Set up the StatusBar for displaying ListChanged events.

private StatusBar status = new StatusBar();
public Form1()
{
// Set up the form.
this.Controls.Add(status);
// Set up the DataGridView control.

this.customersDataGridView.Dock = DockStyle.Fill;
// Attach an event handler for the AddingNew event.

this.customersBindingSource.AddingNew +=
new AddingNewEventHandler(customersBindingSource_AddingNew);
// Attach an event handler for the ListChanged event.

this.customersBindingSource.ListChanged +=
new ListChangedEventHandler(customersBindingSource_ListChanged);
}
private void Form1_Load(System.Object sender, System.EventArgs e)

{
// Add a DemoCustomer to cause a row to be displayed.
this.customersBindingSource.AddNew();
// Bind the BindingSource to the DataGridView

// control's DataSource.
}
// This event handler provides custom item-creation behavior.

void customersBindingSource_AddingNew(
object sender,
AddingNewEventArgs e)
{
e.NewObject = DemoCustomer.CreateNewCustomer();
}
// This event handler detects changes in the BindingSource

// list or changes to items within the list.
void customersBindingSource_ListChanged(
object sender,
ListChangedEventArgs e)
{
status.Text = e.ListChangedType.ToString();
}
[STAThread]
static void Main()
{
}
}
// This class implements a simple customer type.

{
// These fields hold the values for the public properties.
private Guid idValue = Guid.NewGuid();
private string customerName = String.Empty;
private string companyNameValue = String.Empty;
private string phoneNumberValue = String.Empty;
// The constructor is private to enforce the factory pattern.

private DemoCustomer()
{
customerName = "no data";
companyNameValue = "no data";
phoneNumberValue = "no data";
}
// This is the public factory method.

public static DemoCustomer CreateNewCustomer()
{
return new DemoCustomer();
}
// This property represents an ID, suitable

// for use as a primary key in a database.
public Guid ID
{
get
{
}
}
public string CompanyName

{
get
{
return this.companyNameValue;
}
set
{
this.companyNameValue = value;
}
}
public string PhoneNumber

{
get
{
return this.phoneNumberValue;
}
set
{
this.phoneNumberValue = value;
}
}
}

Confira também
BindingNavigator
DataGridView
BindingSource
Como: Como identificar erros e
exceções que ocorram na associação de
dados
Artigo • 21/06/2023
Muitas vezes, erros e exceções ocorrem nos objetos de negócios subjacentes quando
você os associa aos controles. Você pode interceptar esses erros e exceções e, em
seguida, recuperar ou passar as informações de erro para o usuário manipulando o
BindingComplete evento para um componente , BindingSourceou CurrencyManager
específicoBinding.
Exemplo
Este exemplo de código demonstra como tratar erros e exceções que ocorrem durante
uma operação de associação de dados. Ele demonstra como interceptar erros
manipulando o Binding.BindingComplete evento dos Binding objetos . Para interceptar
erros e exceções ao manipular esse evento, você deve habilitar a formatação para a
associação. Você pode habilitar a formatação quando a associação é construída ou
adicionada à coleção de associação ou definindo a FormattingEnabled propriedade
true como .
C#
using System;
class Form1 : Form

{
private BindingSource BindingSource1 = new BindingSource();
public Form1()
{
//Set up the textbox controls.
// Add the textbox controls to the form
// Handle the form's Load event.

this.Load += new System.EventHandler(this.Form1_Load);
}
Binding partNameBinding;
Binding partNumberBinding;
private void Form1_Load(object sender, EventArgs e)

{
// Set the DataSource of BindingSource1 to the Part type.
BindingSource1.DataSource = typeof(Part);
// Bind the textboxes to the properties of the Part type,

// enabling formatting.
partNameBinding = textBox1.DataBindings.Add("Text",
BindingSource1, "PartName", true);
partNumberBinding = textBox2.DataBindings.Add("Text",
BindingSource1, "PartNumber",
true);
//Bind the textbox to the PartPrice value with currency formatting.

textBox3.DataBindings.Add("Text", BindingSource1, "PartPrice", true,
DataSourceUpdateMode.OnPropertyChanged, 0, "C");
// Handle the BindingComplete event for BindingSource1 and

// the partNameBinding.
partNumberBinding.BindingComplete +=
new
BindingCompleteEventHandler(partNumberBinding_BindingComplete);
partNameBinding.BindingComplete +=
new
BindingCompleteEventHandler(partNameBinding_BindingComplete);
// Add a new part to BindingSource1.

BindingSource1.Add(new Part("Widget", 1234, 12.45));
}
// Handle the BindingComplete event to catch errors and exceptions

// in binding process.
void partNumberBinding_BindingComplete(object sender,
BindingCompleteEventArgs e)
{
if (e.BindingCompleteState != BindingCompleteState.Success)
MessageBox.Show("partNumberBinding: " + e.ErrorText);
}
// Handle the BindingComplete event to catch errors and

// exceptions in binding process.
void partNameBinding_BindingComplete(object sender,
{
if (e.BindingCompleteState != BindingCompleteState.Success)
MessageBox.Show("partNameBinding: " + e.ErrorText);
}
[STAThread]
static void Main()
{
}
}
// Represents a business object that throws exceptions when invalid values

are
// entered for some of its properties.
public class Part
{
private string name;
private int number;
private double price;
public Part(string name, int number, double price)

{
PartName = name;
PartNumber = number;
PartPrice = price;
}
public string PartName

{
get { return name; }
set
{
if (value.Length <= 0)
throw new Exception("Each part must have a name.");
else
name = value;
}
}
public double PartPrice
{
get { return price; }
set { price = value; }
}
public int PartNumber

{
get { return number; }
set
{
if (value < 100)
throw new Exception("Invalid part number." +
" Part numbers must be greater than 100.");
else
number = value;
}
}
}
Quando o código está em execução e uma cadeia de caracteres vazia é inserida para o
nome da peça ou um valor menor que 100 é inserido para o número de peça, uma caixa
de mensagem será exibida. Isso é resultado do tratamento do Binding.BindingComplete
evento para essas associações de caixa de texto.
Confira também
Binding.BindingComplete
BindingSource.BindingComplete
Como: Gerar notificações de alteração
usando um BindingSource e a interface
Artigo • 21/06/2023
O BindingSource componente detecta automaticamente alterações em uma fonte de

dados quando o tipo contido na fonte de dados implementa INotifyPropertyChanged e
gera PropertyChanged eventos quando um valor de propriedade é alterado. Essa
detecção de alteração é útil porque os BindingSource controles associados ao são
atualizados automaticamente à medida que os valores da fonte de dados são alterados.
７ Observação
Se a fonte de dados implementar INotifyPropertyChanged e você estiver

executando operações assíncronas, não deverá fazer alterações na fonte de dados
em um thread em segundo plano. Em vez disso, você deve ler os dados em um
thread em segundo plano e mesclar os dados em uma lista no thread da interface
do usuário.
Exemplo
O exemplo de código a seguir demonstra uma implementação simples da
INotifyPropertyChanged interface. Ele também mostra como o BindingSource passa
automaticamente uma alteração de fonte de dados para um controle associado quando
o BindingSource está associado a uma lista do INotifyPropertyChanged tipo.
Se você usar o atributo CallerMemberName , chamadas para o método

NotifyPropertyChanged não precisarão especificar o nome da propriedade como um
argumento de cadeia de caracteres. Para obter mais informações, consulte Informações

do chamador (C#) ou Informações do chamador (Visual Basic).
C#
using System;
using System.Runtime.CompilerServices;
// Change the namespace to the project name.
namespace TestNotifyPropertyChangedCS
{
// This form demonstrates using a BindingSource to bind
// a list to a DataGridView control. The list does not
// raise change notifications. However the DemoCustomer type
// in the list does.
public partial class Form1 : Form
{
// This button causes the value of a list element to be changed.
private Button changeItemBtn = new Button();
// This DataGridView control displays the contents of the list.

// This BindingSource binds the list to the DataGridView control.

public Form1()
{
// Set up the "Change Item" button.

this.changeItemBtn.Text = "Change Item";
this.changeItemBtn.Dock = DockStyle.Bottom;
this.changeItemBtn.Click +=
new EventHandler(changeItemBtn_Click);
this.Controls.Add(this.changeItemBtn);


}

{
// Create and populate the list of DemoCustomer objects
// which will supply data to the DataGridView.
BindingList<DemoCustomer> customerList = new
BindingList<DemoCustomer>();
customerList.Add(DemoCustomer.CreateNewCustomer());
// Bind the list to the BindingSource.

this.customersBindingSource.DataSource = customerList;

}
// Change the value of the CompanyName property for the first

// item in the list when the "Change Item" button is clicked.
void changeItemBtn_Click(object sender, EventArgs e)
{
// Get a reference to the list from the BindingSource.
BindingList<DemoCustomer> customerList =
this.customersBindingSource.DataSource as
BindingList<DemoCustomer>;
// Change the value of the CompanyName property for the

// first item in the list.
customerList[0].CustomerName = "Tailspin Toys";
customerList[0].PhoneNumber = "(708)555-0150";
}
}
// This is a simple customer class that

// implements the IPropertyChange interface.
public class DemoCustomer : INotifyPropertyChanged
{
private string customerNameValue = String.Empty;
public event PropertyChangedEventHandler PropertyChanged;
// This method is called by the Set accessor of each property.

// The CallerMemberName attribute that is applied to the optional
propertyName
// parameter causes the property name of the caller to be
substituted as an argument.
private void NotifyPropertyChanged([CallerMemberName] String
propertyName = "")
{
if (PropertyChanged != null)
{
PropertyChanged(this, new
PropertyChangedEventArgs(propertyName));
}
}

{
customerNameValue = "Customer";
phoneNumberValue = "(312)555-0100";
}

{
}

public Guid ID
{
get
{
}
}
public string CustomerName

{
get
{
return this.customerNameValue;
}
set
{
if (value != this.customerNameValue)
{
this.customerNameValue = value;
NotifyPropertyChanged();
}
}
}

{
get
{
}
set
{
if (value != this.phoneNumberValue)
{
NotifyPropertyChanged();
}
}
}
}
}

Confira também
Como: Acionar notificações de alteração usando o método BindingSource
ResetItem
Como: Acionar notificações de alteração
usando o método BindingSource
ResetItem
Artigo • 02/06/2023
Algumas fontes de dados para seus controles não geram notificações de alteração
quando os itens são alterados, adicionados ou excluídos. Com o BindingSource
componente, você pode associar a essas fontes de dados e gerar uma notificação de
alteração do código.
Exemplo
Esse formulário demonstra o uso de um BindingSource componente para associar uma
lista a um DataGridView controle. A lista não gera notificações de alteração, portanto, o
ResetItem método no BindingSource é chamado quando um item na lista é alterado. .
C#
using System;
using System.Data;
using System.Data.Common;
// This form demonstrates using a BindingSource to bind

// a list to a DataGridView control. The list does not
// raise change notifications, so the ResetItem method
// on the BindingSource is used.
{
// This button causes the value of a list element to be changed.
private Button changeItemBtn = new Button();
// This is the DataGridView control that displays the contents

// of the list.
// This is the BindingSource used to bind the list to the

// DataGridView control.
public Form1()
{
// Set up the "Change Item" button.
this.changeItemBtn.Text = "Change Item";
this.changeItemBtn.Dock = DockStyle.Bottom;
this.changeItemBtn.Click +=
new EventHandler(changeItemBtn_Click);
this.Controls.Add(this.changeItemBtn);

}

{
// Create and populate the list of DemoCustomer objects
// which will supply data to the DataGridView.
List<DemoCustomer> customerList = new List<DemoCustomer>();
// Bind the list to the BindingSource.

this.customersBindingSource.DataSource = customerList;

}
// This event handler changes the value of the CompanyName

// property for the first item in the list.
void changeItemBtn_Click(object sender, EventArgs e)
{
// Get a reference to the list from the BindingSource.
List<DemoCustomer> customerList =
this.customersBindingSource.DataSource as List<DemoCustomer>;
// Change the value of the CompanyName property for the

// first item in the list.
customerList[0].CompanyName = "Tailspin Toys";
// Call ResetItem to alert the BindingSource that the

// list has changed.
this.customersBindingSource.ResetItem(0);
}
[STAThread]
static void Main()
{
}
}
// This class implements a simple customer type.

{
private string customerName = String.Empty;
private string companyNameValue = String.Empty;

{
customerName = "no data";
companyNameValue = "no data";
phoneNumberValue = "no data";
}

{
}

public Guid ID
{
get
{
}
}
public string CompanyName

{
get
{
return this.companyNameValue;
}
set
{
this.companyNameValue = value;
}
}

{
get
{
}
set
{
}
}
}

Confira também
BindingNavigator
DataGridView
BindingSource
Como: Refletir atualizações feitas na
fonte de dados em um controle do
Windows Forms com o BindingSource
Artigo • 02/06/2023
Quando você usa controles associados a dados, às vezes você precisa responder a
alterações na fonte de dados quando a fonte de dados não gera eventos alterados pela
lista. Ao usar o BindingSource componente para associar sua fonte de dados a um
controle Windows Forms, você pode notificar o controle de que sua fonte de dados foi
alterada chamando o ResetBindings método.
Exemplo
O exemplo de código a seguir demonstra o uso do ResetBindings método para notificar
um controle associado sobre uma atualização na fonte de dados.
C#
using System;
using System.Text;
namespace System_Windows_Forms_UpdateBinding
{
class Form1 : Form
{
// Declare the objects on the form.
private Label label1;
ArrayList states;
public Form1()
{
// Basic form setup.
this.label1 = new System.Windows.Forms.Label();
this.button1.Size = new System.Drawing.Size(119, 38);
this.button1.Text = "RemoveAt(0)";
this.button1.Click += new
System.EventHandler(this.button1_Click);
this.textBox1.Size = new System.Drawing.Size(119, 20);
this.label1.Location = new System.Drawing.Point(12, 110);
this.label1.Size = new System.Drawing.Size(43, 14);
this.label1.Text = "Capital:";
this.label2.Text = "State:";
this.Controls.Add(this.label2);
// Create an ArrayList containing some of the State objects.

states = new ArrayList();
states.Add(new State("California", "Sacramento"));
states.Add(new State("Oregon", "Salem"));
states.Add(new State("Washington", "Olympia"));
states.Add(new State("Idaho", "Boise"));
states.Add(new State("Utah", "Salt Lake City"));
states.Add(new State("Hawaii", "Honolulu"));
states.Add(new State("Colorado", "Denver"));
states.Add(new State("Montana", "Helena"));
bindingSource1 = new BindingSource();
// Bind BindingSource1 to the list of states.

bindingSource1.DataSource = states;
// Bind the two text boxes to properties of State.

textBox1.DataBindings.Add("Text", bindingSource1, "Name");
textBox2.DataBindings.Add("Text", bindingSource1, "Capital");
}

{
// If items remain in the list, remove the first item.
if (states.Count > 0)
{
states.RemoveAt(0);
// Call ResetBindings to update the textboxes.

bindingSource1.ResetBindings(false);
}
}
[STAThread]
static void Main()
{
}
// The State class to add to the ArrayList.

private class State
{
private string stateName;
public string Name
{
get {return stateName;}
}
private string stateCapital;

public string Capital
{
get {return stateCapital;}
}
public State ( string name, string capital)

{
stateName = name;
stateCapital = capital;
}
}
}
}
Confira também
BindingNavigator
DataGridView
BindingSource
Como: Compartilhar dados associados
entre formulários usando o componente
BindingSource
Artigo • 21/06/2023
Você pode compartilhar facilmente dados entre formulários usando o BindingSource

componente . Por exemplo, talvez você queira exibir um formulário de somente leitura
que resume os dados de origem de dados e outro formulário editável que contém
informações detalhadas sobre o item atualmente selecionado na fonte de dados. Este
exemplo demonstra esse cenário.
Exemplo
O exemplo de código a seguir demonstra como compartilhar um BindingSource e seus
dados associados entre formulários. Neste exemplo, o compartilhado BindingSource é
passado para o construtor do formulário filho. O formulário filho permite que o usuário
edite os dados para o atualmente item selecionado no formulário principal.
７ Observação
O BindingComplete evento para o BindingSource componente é tratado no

exemplo para garantir que as duas formas permaneçam sincronizadas. Para obter
mais informações sobre o motivo de isso ser feito, consulte Como assegurar que
vários controles associados à mesma fonte de dados permaneçam sincronizados.
C#
using System;
using System.Data;
namespace BindingSourceMultipleForms
{
public class MainForm : Form
{
public MainForm()
{
this.Load += new EventHandler(MainForm_Load);
}
private void MainForm_Load(object sender, EventArgs e)

{
InitializeData();
}
private void InitializeData()

{
bindingSource1 = new System.Windows.Forms.BindingSource();
// Handle the BindingComplete event to ensure the two forms

// remain synchronized.
bindingSource1.BindingComplete +=
new
BindingCompleteEventHandler(bindingSource1_BindingComplete);
DataSet dataset1 = new DataSet();
// Some xml data to populate the DataSet with.

string musicXml =
"<?xml version='1.0' encoding='UTF-8'?>" +
"<music>" +
"<recording><artist>Dave Matthews</artist>" +
"<cd>Under the Table and Dreaming</cd>" +
"<releaseDate>1994</releaseDate><rating>3.5</rating>
</recording>" +
"<recording><artist>Coldplay</artist><cd>X&Y</cd>" +
"<releaseDate>2005</releaseDate><rating>4</rating>
</recording>" +
"<recording><artist>Dave Matthews</artist>" +
"<cd>Live at Red Rocks</cd>" +
"<releaseDate>1997</releaseDate><rating>4</rating>
</recording>" +
"<recording><artist>U2</artist>" +
"<cd>Joshua Tree</cd><releaseDate>1987</releaseDate>" +
"<rating>5</rating></recording>" +
"<recording><artist>U2</artist>" +
"<cd>How to Dismantle an Atomic Bomb</cd>" +
"<releaseDate>2004</releaseDate><rating>4.5</rating>
</recording>" +
"<recording><artist>Natalie Merchant</artist>" +
"<cd>Tigerlily</cd><releaseDate>1995</releaseDate>" +
"<rating>3.5</rating></recording>" +
"</music>";
// Read the xml.

System.IO.StringReader reader = new
System.IO.StringReader(musicXml);
dataset1.ReadXml(reader);
// Get a DataView of the table contained in the dataset.

DataTableCollection tables = dataset1.Tables;
DataView view1 = new DataView(tables[0]);
// Create a DataGridView control and add it to the form.
DataGridView datagridview1 = new DataGridView();
datagridview1.ReadOnly = true;
datagridview1.AutoGenerateColumns = true;
datagridview1.Width = 300;
this.Controls.Add(datagridview1);
bindingSource1.DataSource = view1;
datagridview1.DataSource = bindingSource1;
datagridview1.Columns.Remove("artist");
datagridview1.Columns.Remove("releaseDate");
// Create and add a button to the form.

button1 = new Button();
button1.AutoSize = true;
button1.Text = "Show/Edit Details";
this.Controls.Add(button1);
button1.Location = new Point(50, 200);
}
// Handle the BindingComplete event to ensure the two forms

// remain synchronized.
private void bindingSource1_BindingComplete(object sender,
{
if (e.BindingCompleteContext ==
BindingCompleteContext.DataSourceUpdate
&& e.Exception == null)
e.Binding.BindingManagerBase.EndCurrentEdit();
}
// The detailed form will be shown when the button is clicked.

{
DetailForm detailForm = new DetailForm(bindingSource1);
detailForm.Show();
}
[STAThread]
static void Main()
{
Application.Run(new MainForm());
}
}
// The detail form class.

public class DetailForm : Form
{
private BindingSource formDataSource;
// The constructor takes a BindingSource object.

public DetailForm(BindingSource dataSource)
{
formDataSource = dataSource;
this.ClientSize = new Size(240, 200);
TextBox textBox1 = new TextBox();
this.Text = "Selection Details";
textBox1.Width = 220;
// Associate each text box with a column from the data source.
textBox1.DataBindings.Add("Text", formDataSource, "cd", true,
DataSourceUpdateMode.OnPropertyChanged);
textBox2.DataBindings.Add("Text", formDataSource, "artist",

true);
textBox3.DataBindings.Add("Text", formDataSource, "releaseDate",
true);
textBox4.DataBindings.Add("Text", formDataSource, "rating",
true);
textBox1.Location = new Point(10, 10);
this.Controls.AddRange(new Control[] { textBox1, textBox2,
textBox3, textBox4 });
}
}
}
Referências aos assemblies System, System.Windows.Forms, System.Drawing,

System.Data e System.Xml.
Confira também
associação de dados Windows Forms
Como: Classificar e filtrar dados
ADO.NET com o componente
BindingSource do Windows Forms
Artigo • 21/06/2023
Você pode expor a capacidade de classificação e filtragem de BindingSource controle

por meio das Sort propriedades e Filter . Você pode aplicar classificação simples quando
a fonte de dados subjacente for um IBindingListe você pode aplicar filtragem e
classificação avançada quando a fonte de dados for um IBindingListView. A Sort
propriedade requer sintaxe de ADO.NET padrão: uma cadeia de caracteres que
representa o nome de uma coluna de dados na fonte de dados seguida por ASC ou
DESC para indicar se a lista deve ser classificada em ordem crescente ou decrescente.
Você pode definir a classificação avançada ou a classificação em várias colunas

separando cada coluna com um separador de vírgula. A Filter propriedade usa uma
expressão de cadeia de caracteres.
７ Observação

Filtrar os dados com o BindingSource

Defina a Filter propriedade como expressão desejada.
No exemplo de código a seguir, a expressão é um nome de coluna seguido pelo

valor que você deseja para a coluna.
C#
BindingSource1.Filter = "ContactTitle='Owner'";
Classificar os dados com o BindingSource

1. Defina a Sort propriedade como o nome da coluna que você deseja seguir ASC ou
DESC para indicar a ordem crescente ou decrescente.
2. Separe múltiplas colunas com uma vírgula.
C#
BindingSource1.Sort = "Country DESC, Address ASC";
Exemplo
O exemplo de código a seguir carrega dados da tabela Customers do banco de dados
de exemplo Northwind em um DataGridView controle e filtra e classifica os dados
exibidos.
C#
private void InitializeSortedFilteredBindingSource()

{
// Create the connection string, data adapter and data table.
SqlConnection connectionString =
new SqlConnection("Initial Catalog=Northwind;" +
"Data Source=localhost;Integrated Security=SSPI;");
SqlDataAdapter customersTableAdapter =
new SqlDataAdapter("Select * from Customers", connectionString);
DataTable customerTable = new DataTable();
// Fill the adapter with the contents of the customer table.

customersTableAdapter.Fill(customerTable);
// Set data source for BindingSource1.

BindingSource1.DataSource = customerTable;
// Filter the items to show contacts who are owners.

BindingSource1.Filter = "ContactTitle='Owner'";
// Sort the items on the company name in descending order.

BindingSource1.Sort = "Country DESC, Address ASC";
// Set the data source for dataGridView1 to BindingSource1.

dataGridView1.DataSource = BindingSource1;
}
Para executar este exemplo, cole o código em um formulário que contém um
BindingSource nomeado BindingSource1 e um DataGridView chamado dataGridView1 .
Manipule o Load evento para o formulário e chame
InitializeSortedFilteredBindingSource no método de manipulador de eventos de
carga.
Confira também
Sort
Filter
Como instalar bancos de dados de exemplo
Controle de botão (Windows Forms)
Artigo • 02/06/2023
O controle Button dos Windows Forms permite que o usuário clique nele para realizar
uma ação. O controle Button pode exibir texto e imagens. Quando o botão é clicado,
ele se parece como se estivesse sendo empurrado e solto.
Nesta seção
Visão geral do controle de botão
Explica o que é esse controle e seus principais recursos e propriedades.

Explica o uso mais básico de um botão em um Windows Form.
Como: Designar um botão do Windows Forms como o botão Aceitar

Explica como designar um controle do Button para ser o botão Aceitar, também
conhecido como o botão padrão.
Como: Designar um botão do Windows Forms como o botão Cancelar

Explica como designar um controle do Button para ser o botão Cancelar, que é clicado
sempre que o usuário pressiona a tecla ESC.
Forma de selecionar um controle de botão dos Windows Forms

Lista os métodos de seleção de um botão.
Consulte também Como designar um botão dos Windows Forms como botão Aceitar
usando o Designer e Como designar um botão dos Windows Forms como o botão
Cancelar usando o Designer.
Referência
Classe Button
Fornece uma lista completa dos controles dos Windows Forms, com links para
informações sobre seu uso.
Consulte também Entrada do usuário em caixas de diálogo e Como fechar caixas de
diálogo e manter a entrada do usuário.
Visão geral do controle Button
(Windows Forms)
Artigo • 21/06/2023
O controle Button dos Windows Forms permite que o usuário clique nele para realizar
uma ação. Quando o botão é clicado, ele se parece como se estivesse sendo empurrado
e solto. Sempre que o usuário clica em um botão, o Click manipulador de eventos é
invocado. Você coloca o código no Click manipulador de eventos para executar
qualquer ação escolhida.
O texto exibido no botão está contido na Text propriedade . Se o texto exceder a largura
do botão, ele será encapsulado para a próxima linha. No entanto, ele será recortado se
o controle não puder acomodar sua altura geral. Para obter mais informações, consulte
Como definir o texto exibido por um controle dos Windows Forms. A Text propriedade
pode conter uma tecla de acesso, o que permite que um usuário "clique" no controle
pressionando a tecla ALT com a tecla de acesso. Para obter mais detalhes, consulte
Como criar chaves de acesso para controles dos Windows Forms. A aparência do texto é
controlada pela Font propriedade e pela TextAlign propriedade .
O Button controle também pode exibir imagens usando as Image propriedades e

ImageList . Para obter mais informações, consulte Como definir a imagem exibida por
um controle dos Windows Forms.
Confira também
Button
Como: Designar um botão do Windows Forms como o botão Aceitar usando o
designer
Como: Designar um botão do Windows Forms como o botão Cancelar usando o
designer
Controle de botão
Como: Designar um botão do Windows
Forms como o botão Aceitar
Artigo • 02/06/2023
Em qualquer Formulário do Windows, você pode designar um Button controle para ser
o botão aceitar, também conhecido como botão padrão. Sempre que o usuário
pressiona a tecla ENTER, o botão padrão é clicado independentemente de qual outro
controle no formulário tenha o foco.
７ Observação
As exceções a isso são quando o controle com foco é outro botão — nesse caso, o
botão com o foco será clicado — ou uma caixa de texto de várias linhas ou um
controle personalizado que intercepta a tecla ENTER.
Para designar o botão aceitar

1. Defina a propriedade do AcceptButton formulário como o controle apropriado
Button .
C#
private void SetDefault(Button myDefaultBtn)

{
this.AcceptButton = myDefaultBtn;
}
Confira também
AcceptButton
Como: Designar um botão do Windows Forms como o botão Cancelar
Controle de botão
Forms como o botão Aceitar usando o
designer
Artigo • 02/06/2023
o botão aceitar, também conhecido como botão padrão. Sempre que o usuário
pressiona a tecla ENTER, o botão padrão é clicado independentemente de qual outro
controle no formulário tenha o foco. As exceções a isso são quando o controle com foco
é outro botão — nesse caso, o botão com o foco será clicado — ou uma caixa de texto
de várias linhas ou um controle personalizado que intercepta a tecla ENTER.
Para designar o botão aceitar

1. Selecione o formulário no qual o botão reside.
2. Na janela Propriedades , defina a propriedade do AcceptButton formulário como o

Button nome do controle.
Confira também
AcceptButton
Como: Designar um botão do Windows Forms como o botão Cancelar usando o
designer
Controle de botão
Forms como o botão Cancelar
Artigo • 02/06/2023
o botão cancelar. Um botão cancelar é clicado sempre que o usuário pressiona a tecla
ESC, independentemente de qual outro controle no formulário tenha o foco.
Normalmente, esse botão é programado para permitir que o usuário saia rapidamente
de uma operação sem se comprometer com nenhuma ação.
Para designar o botão cancelar

1. Defina a propriedade do CancelButton formulário como o controle apropriado
Button .
C#
private void SetCancelButton(Button myCancelBtn)

{
this.CancelButton = myCancelBtn;
}
Confira também
CancelButton
Como: Designar um botão do Windows Forms como o botão Aceitar
Controle de botão
Forms como o botão Cancelar usando o
designer
Artigo • 02/06/2023
o botão cancelar. Um botão cancelar é clicado sempre que o usuário pressiona a tecla
ESC, independentemente de qual outro controle no formulário tenha o foco.
Normalmente, esse botão é programado para permitir que o usuário saia rapidamente
de uma operação sem se comprometer com nenhuma ação.
Para designar o botão cancelar

1. Selecione o formulário no qual o botão reside.
2. Na janela Propriedades , defina a propriedade do CancelButton formulário como o

Button nome do controle.
Confira também
CancelButton
Como: Designar um botão do Windows Forms como o botão Aceitar usando o
designer
Controle de botão
Como responder a cliques no botão dos
Windows Forms
Artigo • 21/06/2023
O uso mais básico de um controle Windows Forms Button é executar algum código
quando o botão é clicado.
Clicar em um Button controle também gera vários outros eventos, como os

MouseEntereventos , MouseDowne MouseUp . Se você pretende anexar manipuladores
de eventos para esses eventos relacionados, verifique se suas ações não entrem em
conflito. Por exemplo, se clicar no botão limpa as informações que o usuário digitou na
caixa de texto, pausar o ponteiro do mouse sobre o botão não deverá exibir uma dica
de ferramenta com essas informações agora inexistentes.
Se o usuário tentar clicar duas vezes no Button controle, cada clique será processado
separadamente; ou seja, o controle não dá suporte ao evento de clique duplo.
Para responder a um clique de botão

No botão, Click EventHandler escreva o código a ser executado. Button1_Click
deve ser associado ao controle. Para saber mais, veja Como criar manipuladores de
eventos em tempo de execução para formulários dos Windows Forms.
C#

{
MessageBox.Show("button1 was clicked");
}
Confira também
Controle de botão
Forma de selecionar um controle de
botão dos Windows Forms
Artigo • 02/06/2023
Um botão dos Windows Forms pode ser selecionado das seguintes maneiras:
Use um mouse para clicar no botão.
Invoque o evento do Click botão no código.
Mova o foco para o botão pressionando a tecla TAB e, em seguida, escolha o

botão pressionando a barra de espaços ou ENTER.
Pressione a tecla de acesso (ALT + a letra sublinhada) para o botão. Para obter
mais informações sobre chaves de acesso, consulte Como criar chaves de acesso
para controles dos Windows Forms.
Se o botão for o botão "Aceitar" do formulário, pressionar ENTER seleciona o

botão, mesmo se outro controle tiver o foco — exceto se o outro controle for
outro botão, uma caixa de texto de várias linhas ou um controle personalizado que
intercepte a tecla enter.
Se o botão for o botão "Cancelar" do formulário, pressionar ESC seleciona o botão,

mesmo se outro controle tiver o foco.
Chame o PerformClick método para selecionar o botão programaticamente.
Confira também
Controle de botão
Controle CheckBox (Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms CheckBox indica se uma condição específica está ativada ou
desativada. É usado normalmente para apresentar uma seleção Sim/Não ou
Verdadeiro/Falso ao usuário. Use os controles de caixa de seleção em grupos para exibir
múltiplas opções entre as quais o usuário pode escolher uma ou mais. É semelhante ao
RadioButton controle, mas qualquer número de controles agrupados CheckBox pode ser
selecionado.
Nesta seção
Visão geral do controle CheckBox
Como responder a cliques em CheckBox dos Windows Forms

Explica como usar uma caixa de seleção para determinar as ações do aplicativo.
Como definir opções com controles CheckBox dos Windows Forms

Descreve como usar uma caixa de seleção para definir opções como propriedades de
um objeto.
Referência
Classe CheckBox
(Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms CheckBox indica se uma condição específica está ativada ou
desativada. É usado normalmente para apresentar uma seleção Sim/Não ou
Verdadeiro/Falso ao usuário. Use os controles de caixa de seleção em grupos para exibir
múltiplas opções entre as quais o usuário pode escolher uma ou mais.
O controle de caixa de seleção é similar ao controle de botão de opção, ambos são

usados para indicar uma seleção feita pelo usuário. A diferença é que apenas um botão
de opção em um grupo pode ser selecionado de cada vez. Entretanto, com o controle
de caixa de seleção é possível selecionar várias caixas de seleção.
Uma caixa de seleção pode se conectar aos elementos de um banco de dados usando
associação de dados simples. Várias caixas de seleção podem ser agrupadas usando o
GroupBox controle. Isso é útil para a aparência visual e também para o design de
interface do usuário, uma vez que os controles agrupados podem ser movidos juntos no
designer de formulários. Para mais informações, consulte Associação de dados do
Windows Forms e Controle do GroupBox.
O CheckBox controle tem duas propriedades importantes Checked e CheckState. A

Checked propriedade retorna ou true false . A CheckState propriedade retorna ou
Checked ; Uncheckedou, se a ThreeState propriedade estiver definida como true ,
CheckState também pode retornar Indeterminate. No estado indeterminado, a caixa é
mostrada com uma aparência esmaecida para indicar que a opção não está disponível.
Confira também
CheckBox
Controle CheckBox
Como responder a cliques CheckBox
dos Windows Forms
Artigo • 21/06/2023
Sempre que um usuário clica em um controle Windows FormsCheckBox, o Click evento

ocorre. Você pode programar seu aplicativo para realizar alguma ação dependendo do
estado da caixa de seleção.
Para responder a cliques na caixa de seleção

1. Click No manipulador de eventos, use a Checked propriedade para determinar o
estado do controle e execute qualquer ação necessária.
C#
private void checkBox1_Click(object sender, System.EventArgs e)

{
// The CheckBox control's Text property is changed each time the
// control is clicked, indicating a checked or unchecked state.
if (checkBox1.Checked)
{
checkBox1.Text = "Checked";
}
else
{
checkBox1.Text = "Unchecked";
}
}
７ Observação
Se o usuário tentar clicar duas vezes no CheckBox controle, cada clique será
processado separadamente; ou seja, o CheckBox controle não dá suporte ao
evento de clique duplo.
７ Observação
Quando a AutoCheck propriedade é true (o padrão), a CheckBox é

selecionada ou desmarcada automaticamente quando é clicada. Caso
contrário, você deve definir manualmente a Checked propriedade quando o
Click evento ocorrer.
Você também pode usar o CheckBox controle para determinar um curso de ação.
Para determinar um curso de ação quando uma caixa de

seleção é clicada
1. Use uma instrução case para consultar o valor da CheckState propriedade para
determinar um curso de ação. Quando a ThreeState propriedade é definida como
true , a CheckState propriedade pode retornar três valores possíveis, que
representam a caixa que está sendo marcada, a caixa que está sendo desmarcada
ou um terceiro estado indeterminado no qual a caixa é exibida com uma aparência
esmaecida para indicar que a opção está indisponível.
C#
private void checkBox1_Click(object sender, System.EventArgs e)

{
switch(checkBox1.CheckState)
{
case CheckState.Checked:
// Code for checked state.
break;
case CheckState.Unchecked:
// Code for unchecked state.
break;
case CheckState.Indeterminate:
// Code for indeterminate state.
break;
}
}
７ Observação
Quando a ThreeState propriedade é definida como true , a Checked

propriedade retorna true para e CheckedIndeterminate.
Confira também
CheckBox
Controle de CheckBox
Como definir opções com controles
CheckBox dos Windows Forms
Artigo • 21/06/2023
Um controle Windows Forms CheckBox é usado para fornecer aos usuários opções
True/False ou Sim/Não. O controle exibe uma marca de marcar quando é selecionado.
Para definir opções com controles CheckBox

1. Examine o valor da Checked propriedade para determinar seu estado e use esse
valor para definir uma opção.
No exemplo de código abaixo, quando o CheckBox evento do CheckedChanged

controle é gerado, a propriedade do AllowDrop formulário é definida false como
se a caixa marcar estiver marcada. Isso é útil para situações em que você deseja
restringir a interação do usuário.
C#
private void checkBox1_CheckedChanged(object sender, System.EventArgs

e)
{
// Determine the CheckState of the check box.
if (checkBox1.CheckState == CheckState.Checked)
{
// If checked, do not allow items to be dragged onto the form.
this.AllowDrop = false;
}
}
Confira também
CheckBox
Controle de CheckBox
Controle CheckedListBox (Windows
Forms)
Artigo • 02/06/2023
O controle Windows Forms CheckedListBox exibe uma lista de itens, como o ListBox
controle, e também pode exibir uma marca de seleção ao lado de itens na lista.
Nesta seção
Visão geral do controle CheckedListBox
Como: Determinar itens verificados no controle CheckedListBox do Windows Forms

Descreve como percorrer uma lista para determinar quais itens são verificados.
Referência
Classe CheckedListBox
Fornece uma lista de coisas que você pode fazer com caixas de listagem, caixas de
combinação e caixas de listagem marcadas.

(Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms CheckedListBox estende o ListBox controle. Ele faz quase
tudo o que uma caixa de listagem e também pode exibir uma marca de seleção ao lado
de itens na lista. Outras diferenças entre os dois controles são que as caixas de listagem
marcadas só dão suporte DrawMode.Normal; e que as caixas de listagem marcadas só
podem ter um item ou nenhum selecionado. Observe que um item selecionado é
realçado no formulário e não é o mesmo que um item marcado.
As caixas de listagem marcadas podem ter itens adicionados em tempo de design

usando o Editor de Coleção de Cadeias de Caracteres ou seus itens podem ser
adicionados dinamicamente de uma coleção em tempo de execução, usando a Items
propriedade. Para obter mais informações, veja Como adicionar e remover itens de um
controle ComboBox, ListBox ou CheckedListBox dos Windows Forms.
Confira também
CheckedListBox
CheckedListBox.Items
ListControl.DataSource
Visão geral do controle ListBox
Como: Determinar itens verificados no controle CheckedListBox do Windows
Forms
Como: Determinar itens verificados no
controle CheckedListBox do Windows
Forms
Artigo • 02/06/2023
ao apresentar dados em um controle de Windows Forms CheckedListBox , você pode

iterar pela coleção armazenada na CheckedItems propriedade ou percorrer a lista
usando o GetItemChecked método para determinar quais itens estão marcados. O
GetItemChecked método usa um número de índice de item como seu argumento e
retorna true ou false . Ao contrário do que você pode esperar, as SelectedItems
Propriedades e SelectedIndices não determinam quais itens são verificados; eles
determinam quais itens estão realçados.
Como determinar itens marcados em um controle

CheckedListBox
1. Itere pela CheckedItems coleção, começando em 0, pois a coleção é baseada em
zero. Observe que esse método lhe fornecerá o número de item na lista de itens
marcados, não na lista global. Portanto, se o primeiro item na lista não estiver
marcado e o segundo item estiver marcado, o código a seguir exibirá o texto
como "Item marcado 1 = MyListItem2".
C#
// Determine if there are any items checked.

if(checkedListBox1.CheckedItems.Count != 0)
{
// If so, loop through all checked items and print results.
string s = "";
for(int x = 0; x < checkedListBox1.CheckedItems.Count ; x++)
{
s = s + "Checked Item " + (x+1).ToString() + " = " +
checkedListBox1.CheckedItems[x].ToString() + "\n";
}
MessageBox.Show(s);
}
ou –
2. Percorra a Items coleção, começando em 0, pois a coleção é baseada em zero e

chama o GetItemChecked método para cada item. Observe que esse método lhe
fornecerá o número de item na lista geral, portanto, se o primeiro item na lista não
estiver marcado e o segundo item estiver marcado, ele exibirá algo como "Item 2
= MyListItem2".
C#
int i;
string s;
s = "Checked items:\n" ;
for (i = 0; i <= (checkedListBox1.Items.Count-1); i++)
{
if (checkedListBox1.GetItemChecked(i))
{
s = s + "Item " + (i+1).ToString() + " = " +
checkedListBox1.Items[i].ToString() + "\n";
}
}
MessageBox.Show (s);
Confira também
Componente ColorDialog (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms ColorDialog é uma caixa de diálogo pré-configurada

que permite que o usuário selecione uma cor de uma paleta e adicione cores
personalizadas a essa paleta. É a mesma caixa de diálogo que você vê em outros
aplicativos baseados no Windows para selecionar cores. Use-a em seu aplicativo
baseado no Windows como uma solução simples em vez de configurar sua própria caixa
de diálogo.
Nesta seção
Visão geral do componente ColorDialog
Apresenta os conceitos gerais do componente, que ColorDialog permite exibir uma
caixa de diálogo pré-configurada que os usuários podem usar para selecionar cores de
uma paleta.
Como: Alterar a aparência do componente ColorDialog do Windows Forms

Descreve como alterar as cores disponíveis para usuários e outras propriedades.
Como: Mostrar uma paleta de cores com o componente ColorDialog

Explica como selecionar uma cor em tempo de execução por meio de uma instância do
ColorDialog componente.
ColorDialog
Fornece informações de referência sobre a ColorDialog classe e seus membros.

Lista um conjunto de controles que permitem aos usuários executar interações padrão
com o aplicativo ou o sistema.
(Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms ColorDialog é uma caixa de diálogo pré-configurada

que permite que o usuário selecione uma cor de uma paleta e adicione cores
personalizadas a essa paleta. É a mesma caixa de diálogo que você vê em outros
aplicativos baseados no Windows para selecionar cores. Use-a em seu aplicativo
baseado no Windows como uma solução simples em vez de configurar sua própria caixa
de diálogo.
A cor selecionada na caixa de diálogo é retornada na Color propriedade. Se a

AllowFullOpen propriedade estiver definida como false , o botão "Definir Cores
Personalizadas" será desabilitado e o usuário ficará restrito às cores predefinidas na
paleta. Se a SolidColorOnly propriedade estiver definida como true , o usuário não
poderá selecionar cores dithered. Para exibir a caixa de diálogo, você deve chamar seu
ShowDialog método.
Confira também
ColorDialog
Como: Alterar a aparência do componente ColorDialog do Windows Forms
Como: Alterar a aparência do
componente ColorDialog do Windows
Forms
Artigo • 21/06/2023
Você pode configurar a aparência do componente Windows Forms ColorDialog com

várias de suas propriedades. A caixa de diálogo tem duas seções, uma que mostra as
cores básicas e outra que permite que o usuário defina cores personalizadas.
A maioria das propriedades restringe quais cores o usuário pode selecionar da caixa de
diálogo. Se a AllowFullOpen propriedade estiver definida true como , o usuário poderá
definir cores personalizadas. A FullOpen propriedade será true se a caixa de diálogo for
expandida para definir cores personalizadas; caso contrário, o usuário deverá clicar em
um botão "Definir Cores Personalizadas". Quando a AnyColor propriedade é definida
true como , a caixa de diálogo exibe todas as cores disponíveis no conjunto de cores
básicas. Se a SolidColorOnly propriedade estiver definida true como , o usuário não
poderá selecionar cores dithered; somente cores sólidas estarão disponíveis para
seleção.
Se a ShowHelp propriedade estiver definida true como , um botão Ajuda aparecerá na

caixa de diálogo. Quando o usuário clica no botão Ajuda, o ColorDialog evento do
HelpRequest componente é gerado.
Para configurar a aparência da caixa de diálogo de cor

1. Defina as AllowFullOpenpropriedades , AnyColor, SolidColorOnlye ShowHelp como
os valores desejados.
C#
colorDialog1.AllowFullOpen = true;
colorDialog1.AnyColor = true;
colorDialog1.SolidColorOnly = false;
colorDialog1.ShowHelp = true;
Confira também
ColorDialog
Como: Mostrar uma paleta de cores
com o componente ColorDialog
Artigo • 21/06/2023
O componente ColorDialog exibe uma paleta de cores e retorna uma propriedade que
contém a cor selecionada pelo usuário.
Para escolher uma cor usando o componente ColorDialog

1. Exiba a caixa de diálogo usando o ShowDialog método .
2. Use a DialogResult propriedade para determinar como a caixa de diálogo foi

fechada.
3. Use a Color propriedade do ColorDialog componente para definir a cor escolhida.
No exemplo abaixo, o Button manipulador de eventos do Click controle abre um

ColorDialog componente. Quando uma cor é escolhida e o usuário clica em OK, a
Button cor da tela de fundo do controle é definida como a cor escolhida. O
exemplo pressupõe que seu formulário tenha um Button controle e um
ColorDialog componente.
C#

{
if(colorDialog1.ShowDialog() == DialogResult.OK)
{
button1.BackColor = colorDialog1.Color;
}
}
(Visual C#, Visual C++) Coloque o seguinte código no construtor do formulário

para registrar o manipulador de eventos.
C#
Confira também
ColorDialog
Controle ComboBox (Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms ComboBox é usado para exibir dados em uma caixa de
combinação suspensa. Por padrão, o ComboBox controle aparece em duas partes: a parte
superior é uma caixa de texto que permite que o usuário digite um item de lista. A
segunda parte é uma caixa de listagem que exibe uma lista de itens na qual o usuário
pode selecionar item.
Nesta seção
Visão geral do controle ComboBox
Como: Criar texto dimensionado da variável em um controle ComboBox

Demonstra o desenho personalizado do texto em um ComboBox controle.
Referência
Classe ComboBox
Confira também
(Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms ComboBox é usado para exibir dados em uma caixa de
combinação suspensa. Por padrão, o ComboBox controle aparece em duas partes: a
parte superior é uma caixa de texto que permite que o usuário digite um item de lista. A
segunda parte é uma caixa de listagem que exibe uma lista de itens na qual o usuário
pode selecionar item. Para obter mais informações sobre outros estilos de caixa de
combinação, consulte Quando usar um ComboBox dos Windows Forms em vez de uma
caixa de listagem.
A SelectedIndex propriedade retorna um valor inteiro que corresponde ao item de lista

selecionado. Você pode alterar programaticamente o item selecionado alterando o
SelectedIndex valor no código; o item correspondente na lista aparecerá na parte da
caixa de texto da caixa de combinação. Se nenhum item for selecionado, o
SelectedIndex valor será -1. Se o primeiro item na lista for selecionado, o SelectedIndex
valor será 0. A SelectedItem propriedade é semelhante a SelectedIndex , mas retorna o
item em si, geralmente um valor de cadeia de caracteres. A Count propriedade reflete o
número de itens na lista e o valor da Count propriedade é sempre um a mais do que o
maior valor possível SelectedIndex porque SelectedIndex é baseado em zero.
Para adicionar ou excluir itens em um ComboBox controle, use o Addmétodo ou

Remove o ClearInsertmétodo. Como alternativa, você pode adicionar itens à lista
usando a Items propriedade no designer.
Confira também
ComboBox
Quando usar um ComboBox dos Windows Forms em vez de um ListBox
Como: Adicionar e remover itens de um controle ComboBox, ListBox ou
CheckedListBox do Windows Forms
Como: Classificar o conteúdo de um controle ComboBox, ListBox ou
Como: Acessar itens específicos em um controle ComboBox, ListBox ou
Como: Associar um controle ComboBox ou ListBox do Windows Forms aos dados
Como: Criar uma tabela de pesquisa para um controle ComboBox, ListBox ou
Como: Criar texto dimensionado da
variável em um controle ComboBox
Artigo • 02/06/2023
Este exemplo demonstra o desenho personalizado de texto em um ComboBox controle.

Quando um item atende a determinados critérios, ele é desenhado em uma fonte maior
e fica vermelho.
Exemplo
VB
Private Sub ComboBox1_MeasureItem(ByVal sender As Object, ByVal e As _

System.Windows.Forms.MeasureItemEventArgs) Handles ComboBox1.MeasureItem
Dim bFont As New Font("Arial", 8, FontStyle.Bold)
Dim lFont As New Font("Arial", 12, FontStyle.Bold)
Dim siText As SizeF
If ComboBox1.Items().Item(e.Index) = "Two" Then

siText = e.Graphics.MeasureString(ComboBox1.Items().Item(e.Index), _
lFont)
Else
siText = e.Graphics.MeasureString(ComboBox1.Items().Item(e.Index),
bFont)
End If
e.ItemHeight = siText.Height
e.ItemWidth = siText.Width
End Sub
Private Sub ComboBox1_DrawItem(ByVal sender As Object, ByVal e As _

System.Windows.Forms.DrawItemEventArgs) Handles ComboBox1.DrawItem
Dim g As Graphics = e.Graphics
Dim bFont As New Font("Arial", 8, FontStyle.Bold)
Dim lFont As New Font("Arial", 12, FontStyle.Bold)
If ComboBox1.Items().Item(e.Index) = "Two" Then

g.DrawString(ComboBox1.Items.Item(e.Index), lfont, Brushes.Red, _
e.Bounds.X, e.Bounds.Y)
Else
g.DrawString(ComboBox1.Items.Item(e.Index), bFont, Brushes.Black,
e.Bounds.X, e.Bounds.Y)
End If
End Sub
Um formulário do Windows.
Um ComboBox controle nomeado ListBox1 com três itens na Items propriedade.

Neste exemplo, os três itens são nomeados "One", Two", and Three" . A
DrawMode propriedade de ComboBox1 deve ser definida como OwnerDrawVariable.
７ Observação
Essa técnica também é aplicável ao ListBox controle – você pode substituir

um ListBox por ComboBox.
Referências aos namespaces System.Windows.Forms e System.Drawing.
Confira também
DrawItem
DrawItemEventArgs
MeasureItem
Controle ListBox
Controle ComboBox
Componente ContextMenu (Windows
Forms)
Artigo • 02/06/2023
７ Observação
Embora MenuStrip e ContextMenuStrip substitua e adicione funcionalidade aos

controles e ContextMenu às MainMenu versões anteriores e
ContextMenuMainMenu sejam mantidos para compatibilidade com versões
anteriores e uso futuro, se você escolher.
O componente Windows Forms ContextMenu é usado para fornecer aos usuários um

menu de atalho facilmente acessível de comandos usados com frequência associados ao
objeto selecionado. Os itens em um menu de atalho frequentemente são um
subconjunto dos itens de menus principais que aparecem em outro lugar no aplicativo.
Os menus de atalho geralmente estão disponíveis clicando com o botão direito do
mouse. Em Windows Forms estão associados a outros controles.
Nesta seção
Visão geral do componente ContextMenu
Apresenta os conceitos gerais do componente, que ContextMenu permite que os
usuários criem menus de comandos usados com frequência associados a um objeto
selecionado.
Como: Adicionar e remover itens de menu com o componente ContextMenu do

Windows Forms
Explica como adicionar e remover itens de menu de atalho em Windows Forms.
Referência
ContextMenu
Fornece informações de referência sobre a ContextMenu classe e seus membros.
Confira também
MenuStrip
ContextMenuStrip
ContextMenu (Windows Forms)
Artigo • 02/06/2023
） Importante
Embora MenuStrip substitua e ContextMenuStrip adicione funcionalidades aos

controles e ContextMenu versões MainMenu anteriores e ContextMenu sejam
mantidos para compatibilidade com versões MainMenu anteriores e uso futuro, se
você escolher.
Com o componente Windows FormsContextMenu, você pode fornecer aos usuários um

menu de atalho facilmente acessível de comandos usados com frequência associados ao
objeto selecionado. Os itens em um menu de atalho frequentemente são um
subconjunto dos itens de menus principais que aparecem em outro lugar no aplicativo.
Um usuário geralmente pode acessar um menu de atalho clicando com o botão direito
do mouse. nos Windows Forms, menus de atalho são associados a controles.
Propriedades da chave
Você pode associar um menu de atalho a um controle definindo a propriedade do
ContextMenu controle com o ContextMenu componente. Um único menu de atalho
pode ser associado a vários controles, mas cada controle pode ter apenas um menu de
atalho.
A propriedade chave do ContextMenu componente é a MenuItems propriedade. Você

pode adicionar itens de menu criando MenuItem objetos programaticamente e
adicionando-os Menu.MenuItemCollection ao menu de atalho. Como os itens em um
menu de atalho geralmente são retirados de outros menus, você provavelmente
adicionará itens ao menu de atalho copiando-os.
Confira também
ContextMenu
MenuStrip
ContextMenuStrip
Como: Adicionar e remover itens de
menu com o componente ContextMenu
do Windows Forms
Artigo • 02/06/2023
Explica como adicionar e remover itens de menu de atalho em Windows Forms.
O componente Windows Forms ContextMenu fornece um menu de comandos usados

com frequência relevantes para o objeto selecionado. Você pode adicionar itens ao
menu de atalho adicionando MenuItem objetos à MenuItems coleção.
Você pode remover itens de um menu de atalho permanentemente; no entanto, em

tempo de execução, pode ser mais apropriado ocultar ou desabilitar os itens.
） Importante

controles e ContextMenu às MainMenu versões anteriores e
ContextMenuMainMenu sejam mantidos para compatibilidade com versões
Para remover itens de um menu de atalho

1. Use o método ou RemoveAt o RemoveMenuItems método da coleção do
ContextMenu componente para remover um item de menu específico.
C#
// Removes the first item in the shortcut menu.

contextMenu1.MenuItems.RemoveAt(0);
// Removes a particular object from the shortcut menu.
contextMenu1.MenuItems.Remove(mnuItemNew);
-ou-
2. Use o Clear método da MenuItems coleção do ContextMenu componente para

remover todos os itens do menu.
C#
contextMenu1.MenuItems.Clear();
Confira também
ContextMenu
Componente ContextMenu
Visão geral do componente ContextMenu
Artigo • 21/06/2023
O ContextMenuStrip controle fornece um menu de atalho que você associa a um

controle .
Nesta seção
Visão geral do controle ContextMenuStrip
Explica o que é o controle e seus principais recursos e propriedades.
Como: Associar um ContextMenuStrip a um controle

Descreve a criação de um ContextMenuStrip menu de atalho para um controle
específico.
Como: Adicionar itens de menu a um ContextMenuStrip

Descreve como adicionar opções selecionáveis a um ContextMenuStrip.
Como: Configurar margens de imagem e margens de verificação ContextMenuStrip

Descreve como personalizar um ContextMenuStrip definindo marcar e propriedades de
margem de imagem de várias maneiras.
Como: Habilitar margens de verificação e de imagem em controles ContextMenuStrip

Descreve como ativar e desativar ContextMenuStrip as margens marcar.
Como: Identificar o evento de abertura ContextMenuStrip

Descreve como personalizar o comportamento de um ContextMenuStrip controle
manipulando o Opening evento.
Veja também Caixa de diálogo de tarefas ContextMenuStrip ou Editor de coleção de

itens ContextMenuStrip.
Referência
MenuStrip
Descreve os recursos da MenuStrip classe , que fornece um sistema de menus para um
formulário.
ContextMenuStrip
Descreve os recursos do ContextMenuStrip, que representa um menu de atalho.
ToolStripMenuItem
Descreve os recursos da ToolStripMenuItem classe , que representa uma opção
selecionável exibida em um MenuStrip ou ContextMenuStrip.
ContextMenuStrip
Artigo • 02/06/2023
７ Observação
O ContextMenuStrip controle substitui e adiciona funcionalidade ao ContextMenu

controle; no entanto, o ContextMenu controle é retido para compatibilidade com
versões anteriores e uso futuro, se você escolher.
Menus de atalho, também chamados de menus de contexto, aparecem na posição do

mouse quando o usuário clica no botão direito do mouse. Menus de atalho fornecem
opções para a área de cliente ou o controle no local do ponteiro do mouse.
O ContextMenuStrip controle foi projetado para funcionar perfeitamente com os

controles novos ToolStrip e relacionados, mas você pode associar um ContextMenuStrip
a outros controles com a mesma facilidade.
A tabela a seguir mostra as classes complementares importantes ContextMenuStrip .
Classe Descrição
ToolStripMenuItem Representa uma opção selecionável exibida em um MenuStrip ou

ContextMenuStrip.
ToolStripDropDown Representa um controle que permite que o usuário selecione um único

item em uma lista exibida quando o usuário clica em um ou em um
ToolStripDropDownButton item de menu de nível superior.
ToolStripDropDownItem Fornece funcionalidade básica para controles derivados ToolStripItem

desse item suspenso de exibição quando clicado.
Confira também
ToolStrip
MenuStrip
ContextMenuStrip
ToolStripMenuItem
ToolStripDropDown
Como: Associar um ContextMenuStrip a
um controle
Artigo • 02/06/2023
Depois de criar seus controles e menus de atalho, use os procedimentos a seguir para
exibir um determinado menu de atalho quando o usuário clicar com o botão direito do
mouse no controle. Esses procedimentos associam um ContextMenuStrip Formulário do
Windows e a um ToolStrip controle.
Para associar um ContextMenuStrip a um Formulário do

Windows
1. Defina a ContextMenuStrip propriedade como o nome do associado
ContextMenuStrip.
Para associar um ContextMenuStrip a um controle

ToolStrip
1. Defina a propriedade do ContextMenuStrip controle como o nome do associado
ContextMenuStrip.
Exemplo
O exemplo de código a seguir cria um Formulário do Windows e um ToolStripe associa
um controle diferente ContextMenuStrip a cada um deles.
C#
using System;
using System.Data;
using System.Text;
namespace WindowsApplication10
{
{
private ToolStripButton toolStripButton1;
private ContextMenuStrip contextMenuStrip1;
private IContainer components;
private ToolStripMenuItem toolStripMenuItem1;
private ContextMenuStrip contextMenuStrip2;
private ToolStripMenuItem rearrangeButtonsToolStripMenuItem;
private ToolStripMenuItem selectIconsToolStripMenuItem;
private ToolStrip toolStrip1;
public Form1()
{
}
[STAThread]
static void Main()
{
}

{
System.ComponentModel.ComponentResourceManager resources = new
this.toolStrip1 = new System.Windows.Forms.ToolStrip();
this.toolStripButton1 = new
this.contextMenuStrip1 = new
System.Windows.Forms.ContextMenuStrip(this.components);
this.contextMenuStrip2 = new
System.Windows.Forms.ContextMenuStrip(this.components);
this.toolStripMenuItem1 = new
System.Windows.Forms.ToolStripMenuItem();
this.rearrangeButtonsToolStripMenuItem = new
this.selectIconsToolStripMenuItem = new
this.toolStrip1.SuspendLayout();
this.contextMenuStrip1.SuspendLayout();
this.contextMenuStrip2.SuspendLayout();
//
// Associate contextMenuStrip2 with toolStrip1.
// toolStrip1 property settings follow.
//
this.toolStrip1.ContextMenuStrip = this.contextMenuStrip2;
this.toolStrip1.Items.AddRange(new
this.toolStripButton1,
this.toolStripButton2,
this.toolStripButton3});
this.toolStrip1.Location = new System.Drawing.Point(0, 0);
this.toolStrip1.Name = "toolStrip1";
this.toolStrip1.Size = new System.Drawing.Size(292, 25);
this.toolStrip1.TabIndex = 0;
this.toolStrip1.Text = "toolStrip1";
//
// toolStripButton1
//
this.toolStripButton1.DisplayStyle =
System.Windows.Forms.ToolStripItemDisplayStyle.Image;
this.toolStripButton1.Image = ((System.Drawing.Image)
(resources.GetObject("toolStripButton1.Image")));
this.toolStripButton1.ImageTransparentColor =
System.Drawing.Color.Magenta;
this.toolStripButton1.Name = "toolStripButton1";
this.toolStripButton1.Text = "toolStripButton1";
//
// toolStripButton2
//
//
// toolStripButton3
//
//
// contextMenuStrip1
//
this.contextMenuStrip1.Items.AddRange(new
this.toolStripMenuItem1,
this.toolStripMenuItem2});
this.contextMenuStrip1.Name = "contextMenuStrip1";
this.contextMenuStrip1.RightToLeft =
System.Windows.Forms.RightToLeft.No;
this.contextMenuStrip1.Size = new System.Drawing.Size(131, 48);
//
// contextMenuStrip2
//
this.rearrangeButtonsToolStripMenuItem,
this.selectIconsToolStripMenuItem});
this.contextMenuStrip2.Name = "contextMenuStrip2";
this.contextMenuStrip2.RightToLeft =
System.Windows.Forms.RightToLeft.No;
this.contextMenuStrip2.Size = new System.Drawing.Size(162, 48);
//
// toolStripMenuItem1
//
this.toolStripMenuItem1.Name = "toolStripMenuItem1";
this.toolStripMenuItem1.Text = "&Resize";
//
//
this.toolStripMenuItem2.Text = "&Keep on Top";
//
// rearrangeButtonsToolStripMenuItem
//
this.rearrangeButtonsToolStripMenuItem.Name =
"rearrangeButtonsToolStripMenuItem";
this.rearrangeButtonsToolStripMenuItem.Text = "R&earrange
Buttons";
//
// selectIconsToolStripMenuItem
//
this.selectIconsToolStripMenuItem.Name =
"selectIconsToolStripMenuItem";
this.selectIconsToolStripMenuItem.Text = "&Select Icons";
//
// Associate contextMenuStrip1 with Form1.
// Form1 property settings follow.
//
this.ContextMenuStrip = this.contextMenuStrip1;
this.Controls.Add(this.toolStrip1);
this.toolStrip1.ResumeLayout(false);
this.contextMenuStrip1.ResumeLayout(false);
this.contextMenuStrip2.ResumeLayout(false);
}
}
}
Confira também
ContextMenuStrip
ContextMenuStrip
ToolStrip
Como: Adicionar itens de menu a um ContextMenuStrip
Como: Adicionar itens de menu a um
ContextMenuStrip
Artigo • 02/06/2023
Você pode adicionar apenas um item de menu ou vários itens por vez a um
ContextMenuStrip.
Para adicionar um único item de menu a um

ContextMenuStrip
Use o Add método para adicionar um item de menu a um ContextMenuStrip.
C#
this.contextMenuStrip1.Items.Add(toolStripMenuItem1);
Para adicionar vários itens de menu a um

ContextMenuStrip
Use o AddRange método para adicionar vários itens de menu a um
ContextMenuStrip.
C#
this.toolStripMenuItem1, this.toolStripMenuItem2});
Confira também
Como: Configurar margens de imagem
e margens de verificação
ContextMenuStrip
Artigo • 02/06/2023
Você pode personalizar um ContextMenuStrip definindo as propriedades e

ShowCheckMargin as ShowImageMargin propriedades em várias combinações.
Exemplo
O exemplo de código a seguir demonstra como definir e personalizar as margens de
ContextMenuStrip verificação e imagem.
C#
using System;
C#
// This code example demonstrates how to set the check

// and image margins for a ToolStripMenuItem.
class Form5 : Form
{
public Form5()
{
// Size the form to show three wide menu items.
this.Width = 500;
this.Text = "ToolStripContextMenuStrip: Image and Check Margins";
// Create a new MenuStrip control.

MenuStrip ms = new MenuStrip();
// Create the ToolStripMenuItems for the MenuStrip control.

ToolStripMenuItem bothMargins = new
ToolStripMenuItem("BothMargins");
ToolStripMenuItem imageMarginOnly = new
ToolStripMenuItem("ImageMargin");
ToolStripMenuItem checkMarginOnly = new
ToolStripMenuItem("CheckMargin");
ToolStripMenuItem noMargins = new ToolStripMenuItem("NoMargins");
// Customize the DropDowns menus.

// This ToolStripMenuItem has an image margin
// and a check margin.
bothMargins.DropDown = CreateCheckImageContextMenuStrip();
((ContextMenuStrip)bothMargins.DropDown).ShowImageMargin = true;
((ContextMenuStrip)bothMargins.DropDown).ShowCheckMargin = true;
// This ToolStripMenuItem has only an image margin.

imageMarginOnly.DropDown = CreateCheckImageContextMenuStrip();
((ContextMenuStrip)imageMarginOnly.DropDown).ShowImageMargin = true;
((ContextMenuStrip)imageMarginOnly.DropDown).ShowCheckMargin =
false;
// This ToolStripMenuItem has only a check margin.

checkMarginOnly.DropDown = CreateCheckImageContextMenuStrip();
((ContextMenuStrip)checkMarginOnly.DropDown).ShowImageMargin =
false;
((ContextMenuStrip)checkMarginOnly.DropDown).ShowCheckMargin = true;
// This ToolStripMenuItem has no image and no check margin.

noMargins.DropDown = CreateCheckImageContextMenuStrip();
((ContextMenuStrip)noMargins.DropDown).ShowImageMargin = false;
((ContextMenuStrip)noMargins.DropDown).ShowCheckMargin = false;
// Populate the MenuStrip control with the ToolStripMenuItems.

ms.Items.Add(bothMargins);
ms.Items.Add(imageMarginOnly);
ms.Items.Add(checkMarginOnly);
ms.Items.Add(noMargins);
// Dock the MenuStrip control to the top of the form.

ms.Dock = DockStyle.Top;
// Add the MenuStrip control to the controls collection last.

// This is important for correct placement in the z-order.
this.Controls.Add(ms);
}
// This utility method creates a Bitmap for use in

// a ToolStripMenuItem's image margin.
internal Bitmap CreateSampleBitmap()
{
// The Bitmap is a smiley face.
Bitmap sampleBitmap = new Bitmap(32, 32);
Graphics g = Graphics.FromImage(sampleBitmap);
using (Pen p = new Pen(ProfessionalColors.ButtonPressedBorder))

{
// Set the Pen width.
p.Width = 4;
// Set up the mouth geometry.

Point[] curvePoints = new Point[]{
new Point(4,14),
new Point(16,24),
new Point(28,14)};
// Draw the mouth.
g.DrawCurve(p, curvePoints);
// Draw the eyes.

g.DrawEllipse(p, new Rectangle(new Point(7, 4), new Size(3,
3)));
3)));
}
return sampleBitmap;
}
// This utility method creates a ContextMenuStrip control

// that has four ToolStripMenuItems showing the four
// possible combinations of image and check margins.
internal ContextMenuStrip CreateCheckImageContextMenuStrip()
{
// Create a new ContextMenuStrip control.
ContextMenuStrip checkImageContextMenuStrip = new
ContextMenuStrip();
// Create a ToolStripMenuItem with a

// check margin and an image margin.
ToolStripMenuItem yesCheckYesImage =
new ToolStripMenuItem("Check, Image");
yesCheckYesImage.Checked = true;
yesCheckYesImage.Image = CreateSampleBitmap();
// Create a ToolStripMenuItem with no

// check margin and with an image margin.
ToolStripMenuItem noCheckYesImage =
new ToolStripMenuItem("No Check, Image");
noCheckYesImage.Checked = false;
noCheckYesImage.Image = CreateSampleBitmap();

// check margin and without an image margin.
ToolStripMenuItem yesCheckNoImage =
new ToolStripMenuItem("Check, No Image");
yesCheckNoImage.Checked = true;

// check margin and no image margin.
ToolStripMenuItem noCheckNoImage =
new ToolStripMenuItem("No Check, No Image");
noCheckNoImage.Checked = false;
// Add the ToolStripMenuItems to the ContextMenuStrip control.

checkImageContextMenuStrip.Items.Add(yesCheckYesImage);
checkImageContextMenuStrip.Items.Add(noCheckYesImage);
checkImageContextMenuStrip.Items.Add(yesCheckNoImage);
checkImageContextMenuStrip.Items.Add(noCheckNoImage);
return checkImageContextMenuStrip;
}
}
Referências aos assemblies System.Design, System.Drawing e

Confira também
ContextMenuStrip
ToolStripDropDown
Controle ToolStrip
Como: Habilitar margens de verificação e de imagem em controles
ContextMenuStrip
Como: Habilitar margens de verificação
e de imagem em controles
ContextMenuStrip
Artigo • 02/06/2023
Você pode personalizar os ToolStripMenuItem objetos em seu MenuStrip controle com

marcas de seleção e imagens personalizadas.
Exemplo
O exemplo de código a seguir demonstra como criar itens de menu que têm marcas de
seleção e imagens personalizadas.
C#
using System;
C#

class Form5 : Form
{
public Form5()
{
this.Width = 500;




false;

false;




}

{

{
p.Width = 4;

new Point(4,14),
new Point(16,24),
new Point(28,14)};
// Draw the mouth.
// Draw the eyes.

3)));
3)));
}
}

{
ContextMenuStrip();





}
}
Defina as propriedades e ToolStripDropDownMenu.ShowImageMargin as

ToolStripDropDownMenu.ShowCheckMargin propriedades a serem especificadas
quando marcas de seleção e imagens personalizadas aparecerem em seus itens de
menu.

Confira também
ToolStripMenuItem
ToolStripDropDownMenu
MenuStrip
ToolStrip
Controle ToolStrip
Como: Identificar o evento de abertura
ContextMenuStrip
Artigo • 21/06/2023
Você pode personalizar o comportamento do controle ContextMenuStrip manipulando

o Opening evento.
Exemplo
O exemplo de código a seguir demonstra como manipular o Opening evento. O
manipulador de eventos adiciona itens dinamicamente a um ContextMenuStrip controle
. Para obter o exemplo de código completo, consulte Como adicionar itens ToolStrip
dinamicamente.
C#
// This event handler is invoked when the ContextMenuStrip

// control's Opening event is raised. It demonstrates
// dynamic item addition and dynamic SourceControl
// determination with reuse.
void cms_Opening(object sender, System.ComponentModel.CancelEventArgs e)
{
// Acquire references to the owning control and item.
Control c = fruitContextMenuStrip.SourceControl as Control;
ToolStripDropDownItem tsi = fruitContextMenuStrip.OwnerItem as
ToolStripDropDownItem;
// Clear the ContextMenuStrip control's Items collection.

fruitContextMenuStrip.Items.Clear();
// Check the source control first.

if (c != null)
{
// Add custom item (Form)
fruitContextMenuStrip.Items.Add("Source: " +
c.GetType().ToString());
}
else if (tsi != null)
{
// Add custom item (ToolStripDropDownButton or ToolStripMenuItem)
tsi.GetType().ToString());
}
// Populate the ContextMenuStrip control with its default items.

fruitContextMenuStrip.Items.Add("-");
fruitContextMenuStrip.Items.Add("Apples");
fruitContextMenuStrip.Items.Add("Oranges");
fruitContextMenuStrip.Items.Add("Pears");
// Set Cancel to false.

// It is optimized to true based on empty entry.
e.Cancel = false;
}
Defina a CancelEventArgs.Cancel propriedade como true para impedir que o menu seja
aberto.
Confira também
ContextMenuStrip
Cancel
ToolStripDropDown
Controle ToolStrip
Controle DataGrid (Windows Forms)
Artigo • 02/06/2023
７ Observação
O controle DataGridView substitui e adiciona funcionalidade ao controle DataGrid ,

no entanto, o controle DataGrid é mantido para compatibilidade com versões
anteriores e para uso futuro, se desejado. Para obter mais informações, consulte
Diferenças entre os controles Windows Forms DataGridView e DataGrid.
O controle Windows Forms DataGrid fornece uma interface do usuário para ADO.NET
conjuntos de dados, exibindo dados tabulares e habilitando atualizações para a fonte de
dados.
Quando o controle DataGrid estiver definido como uma fonte de dados válido, o
controle é preenchido automaticamente, criando colunas e linhas com base na forma
dos dados. O controle DataGrid pode ser usado para exibir uma única tabela ou as
relações hierárquicas entre um conjunto de tabelas.
Nesta seção
Visão geral do controle DataGrid
Descreve os recursos básicos do console DataGrid .
Como: Adicionar tabelas e colunas do controle DataGrid do Windows Forms usando o

Designer
Descreve como adicionar tabelas e colunas ao controle DataGrid usando o designer.
Como: Adicionar tabelas e colunas ao controle DataGrid do Windows Forms

Descreve como adicionar tabelas e colunas ao controle DataGrid com programação.
Como: Associar o controle DataGrid do Windows Forms a uma fonte de dados usando o
Designer
Descreve como associar um conjunto de dados ADO.NET ao DataGrid controle usando
o designer.
Como: Associar o controle DataGrid do Windows Forms a uma fonte de dados

Descreve como associar um conjunto de dados ADO.NET ao DataGrid controle.
Como: Alterar os dados exibidos em tempo de execução no controle DataGrid do
Windows Forms
Descreve como alterar dados com programação no controle DataGrid .
Como: Criar listas mestre e de detalhes com o controle DataGrid do Windows Forms
usando o Designer
Descreve como exibir duas tabelas reunidas com uma relação pai/filho em dois
controles DataGrid separados usando o designer.
Como criar listas mestre/detalhes com o controle DataGrid do Windows Forms

Descreve como exibir duas tabelas reunidas com uma relação pai/filho em dois
controles DataGrid separados.
Como: Excluir ou ocultar colunas no controle DataGrid do Windows Forms

Descreve como remover colunas no controle DataGrid .
Como: Formatar o controle DataGrid do Windows Forms usando o Designer

Descreve como alterar as propriedades relacionadas à aparência do controle DataGrid
usando o designer.
Como: Formatar o controle DataGrid do Windows Forms

Descreve como alterar as propriedades relacionadas à aparência do controle DataGrid .
Atalhos de teclado para o controle DataGrid dos Windows Forms

Lista atalhos para navegarem por meio do controle DataGrid .
Como: Responder a cliques no controle DataGrid do Windows Forms

Descreve como determinar em qual célula um usuário clicou no controle DataGrid .
Como: Validar a entrada com o controle DataGrid do Windows Forms

Descreve como validar a entrada no conjunto de dados associado ao controle DataGrid .
Referência
DataGrid
Fornece uma visão geral da DataGrid classe.
DataSource
Fornece detalhes sobre como usar essa propriedade para associar o DataGrid controle
aos dados.
Fornece links para tópicos sobre a associação de dados no Windows Forms.
Confira também
Diferenças entre os controles DataGridView e DataGrid dos Windows Forms
(Windows Forms)
Artigo • 02/06/2023
７ Observação
O controle DataGridView substitui e adiciona funcionalidade ao controle DataGrid,

O controle Windows Forms DataGrid exibe dados em uma série de linhas e colunas. O
caso mais simples é quando a grade está associada a uma fonte de dados com uma
única tabela que não contém relações. Nesse caso, os dados aparecem em linhas e
colunas simples, como em uma planilha. Para obter mais informações sobre a vinculação
de dados a outros controles, consulte Vinculação de dados e Windows Forms.
Se estiver DataGrid associado a dados com várias tabelas relacionadas e se a navegação

estiver habilitada na grade, a grade exibirá expansores em cada linha. Com um
expansor, o usuário pode se mover de uma tabela pai para uma tabela filho. A tabela
filho é exibida ao clicar em um nó; a tabela pai original é exibida ao clicar em um botão
Voltar. Dessa forma, a grade exibe as relações hierárquicas entre tabelas.
A captura de tela a seguir mostra um DataGrid associado a dados com várias tabelas:
Ele DataGrid pode fornecer uma interface do usuário para um conjunto de dados,
navegação entre tabelas relacionadas e recursos avançados de formatação e edição.
A exibição e a manipulação de dados são funções separadas: o controle manipula a

interface do usuário, enquanto as atualizações de dados são tratadas pela arquitetura
de associação de dados Windows Forms e por provedores de dados .NET Framework.
Portanto, vários controles associados à mesma fonte de dados permanecerão em
sincronia.
７ Observação
Se você estiver familiarizado com o controle DataGrid no Visual Basic 6.0,

encontrará algumas diferenças significativas no controle Windows FormsDataGrid.
Quando a grade está associada a um DataSet, as colunas e linhas são criadas,

formatadas e preenchidas automaticamente. Para obter mais informações, consulte
Vinculação de dados e Windows Forms. Após a geração do DataGrid controle, você
pode adicionar, excluir, reorganizar e formatar colunas e linhas, dependendo de suas
necessidades.
Associação de dados ao controle

Para que o DataGrid controle funcione, ele deve ser associado a uma fonte de dados
usando o e DataMember as DataSource propriedades em tempo de design ou o
SetDataBinding método em tempo de execução. Essa associação aponta DataGrid para
um objeto de fonte de dados instanciado, como um DataSet ou DataTable). O DataGrid
controle mostra os resultados das ações executadas nos dados. A maioria das ações
específicas de dados não são executadas por meio da DataGrid fonte de dados, mas sim
por meio da fonte de dados.
Se os dados no conjunto de dados associados forem atualizados por meio de qualquer

mecanismo, o DataGrid controle refletirá as alterações. Se a grade de dados e seus
estilos de tabela e estilos de coluna tiverem a ReadOnly propriedade definida como
false , os dados no conjunto de dados poderão ser atualizados por meio do DataGrid
controle.
Somente uma tabela pode ser mostrada de DataGrid cada vez. Se uma relação pai-filho
for definida entre tabelas, o usuário poderá se mover entre as tabelas relacionadas para
selecionar a tabela a ser exibida no DataGrid controle. Para obter informações sobre
como associar um DataGrid controle a uma fonte de dados ADO.NET em tempo de
design ou tempo de execução, consulte Como associar o controle datagrid Windows
Forms a uma fonte de dados.
As fontes de dados válidas para o DataGrid incluem:
Classe DataTable
Classe DataView
Classe DataSet
Classe DataViewManager
Se a fonte for um conjunto de dados, ele poderá ser um objeto no formulário ou um

objeto passado para o formulário por um serviço Web XML. É possível associar a
conjuntos de dados tipados ou não tipados.
Você também pode associar um DataGrid controle a estruturas adicionais se os objetos

na estrutura, como os elementos em uma matriz, exporem propriedades públicas. A
grade exibirá todas as propriedades públicas dos elementos na estrutura. Por exemplo,
se você associar o DataGrid controle a uma matriz de objetos de cliente, a grade exibirá
todas as propriedades públicas desses objetos de cliente. Em alguns casos, isso significa
que, apesar de ser possível associar à estrutura, a estrutura associada resultante poderá
não ter aplicação prática. Você pode, por exemplo, associar a uma matriz de inteiros,
mas, como o tipo de dados Integer não dá suporte a uma propriedade pública, a grade
não consegue exibir nenhum dado.
Será possível se associar às estruturas a seguir se seus elementos expuserem

propriedades públicas:
Qualquer componente que implemente a IList interface. Isso inclui matrizes de

dimensão única.
Qualquer componente que implemente a IListSource interface.
Qualquer componente que implemente a IBindingList interface.
Para obter mais informações sobre possíveis fontes de dados, consulte Fontes de dados
com suporte dos Windows Forms.
Exibição de grade
Um uso comum do DataGrid controle é exibir uma única tabela de dados de um
conjunto de dados. No entanto, o controle também pode ser usado para exibir várias
tabelas, incluindo tabelas relacionadas. A exibição da grade é ajustada automaticamente
de acordo com a fonte de dados. A tabela a seguir mostra o que é exibido para várias
configurações.
Conteúdo O que é exibido

do conjunto
de dados
Tabela única. A tabela é exibida em uma grade.
Várias A grade pode exibir um modo de exibição de árvore em que os usuários podem
tabelas. navegar para localizar a tabela que desejam exibir.
Várias A grade pode exibir um modo de exibição de árvore para selecionar tabelas ou é
tabelas possível especificar para a grade exibir a tabela pai. Os registros na tabela pai
relacionadas. permitem que os usuários naveguem até linhas filho relacionadas.
７ Observação
As tabelas em um conjunto de dados estão relacionadas usando um DataRelation.

Consulte também Criar relações entre conjuntos de dados.
Quando o DataGrid controle estiver exibindo uma tabela e a propriedade estiver

definida como true , os AllowSorting dados poderão ser recorados clicando nos
cabeçalhos da coluna. O usuário também pode adicionar linhas e editar células.
As relações entre um conjunto de tabelas são exibidas aos usuários por meio do uso de
uma estrutura pai/filho de navegação. As tabelas pai são o nível mais alto de dados; as
tabelas filho são as tabelas de dados derivadas de listagens de individuais nas tabelas
pai. Os expansores são exibidos em cada linha pai que contém uma tabela filho. Ao
clicar em um expansor, é gerada uma lista de links semelhantes a links Web para as
tabelas filho. Quando o usuário seleciona um link, a tabela filho é exibida. Clicar no
ícone mostrar/ocultar linhas pai ( ) ocultará as informações sobre a tabela pai ou fará
com que ela reapareça se o usuário a tiver ocultado anteriormente. O usuário pode
clicar no botão Voltar para retornar à tabela visualizada anteriormente.
Colunas e linhas
Consiste DataGrid em uma coleção de DataGridTableStyle objetos contidos na DataGrid
propriedade do TableStyles controle. Um estilo de tabela pode conter uma coleção de
DataGridColumnStyle objetos contidos na GridColumnStyles propriedade .
DataGridTableStyle. Você pode editar as propriedades e GridColumnStyles as TableStyles
propriedades usando editores de coleção acessados pela janela Propriedades.
Qualquer DataGridTableStyle associado ao DataGrid controle pode ser acessado por
meio do GridTableStylesCollection. Ele GridTableStylesCollection pode ser editado no
designer com o editor de DataGridTableStyle coleção ou programaticamente por meio
da DataGrid propriedade do TableStyles controle.
A ilustração a seguir mostra os objetos incluídos no controle DataGrid:
Estilos de tabela e estilos de coluna são sincronizados com DataTable objetos e

DataColumn objetos definindo suas MappingName propriedades como as propriedades
apropriadasTableName.ColumnName Quando um DataGridTableStyle que não tem
estilos de coluna é adicionado a um DataGrid controle associado a uma fonte de dados
válida e a MappingName propriedade desse estilo de tabela é definida como uma
propriedade válida TableName , uma coleção de DataGridColumnStyle objetos é criada
para esse estilo de tabela. Para cada DataColumn um encontrado na Columns coleção
do DataTable, um correspondente DataGridColumnStyle é adicionado ao
GridColumnStylesCollection. GridColumnStylesCollection é acessado por meio da
GridColumnStyles propriedade do DataGridTableStyle. As colunas podem ser
adicionadas ou excluídas da grade usando o método ou Remove
.AddGridColumnStylesCollection Para obter mais informações, consulte Como adicionar
tabelas e colunas ao controle DataGrid dos Windows Forms e Como excluir ou ocultar
colunas no controle DataGrid dos Windows Forms.
Uma coleção de tipos de coluna estende a DataGridColumnStyle classe com recursos

avançados de formatação e edição. Todos os tipos de coluna herdam da
DataGridColumnStyle classe base. A classe criada depende da DataType propriedade da
DataColumn qual se DataGridColumn baseia. Por exemplo, um DataColumn que tem
sua DataType propriedade definida para Boolean ser associado ao DataGridBoolColumn.
A tabela a seguir descreve cada um desses tipos de coluna.
Tipo de coluna Descrição
DataGridTextBoxColumn Aceita e exibe os dados como cadeias de caracteres formatadas ou

não formatadas. Os recursos de edição são os mesmos que são para
editar dados em um simples TextBox. Herdada de
DataGridColumnStyle.
DataGridBoolColumn Aceita e exibe true , false e valores nulos. Herdada de

DataGridColumnStyle.
Ao clicar duas vezes na borda direita de uma coluna, a coluna é redimensionada para
exibir a legenda completa e a maior entrada.
Estilos de tabela e de coluna

Assim que tiver estabelecido o formato padrão do DataGrid controle, você poderá
personalizar as cores que serão usadas quando determinadas tabelas forem exibidas
dentro da grade de dados.
Isso é obtido criando instâncias da DataGridTableStyle classe. Os estilos de tabela

especificam a formatação de tabelas específicas, diferente da formatação padrão do
DataGrid próprio controle. Cada tabela poderá ter apenas um estilo de tabela definido
para ela de cada vez.
Às vezes, queremos que uma coluna específica tenha uma aparência diferente do
restante das colunas de uma tabela de dados específica. Você pode criar um conjunto
personalizado de estilos de coluna usando a GridColumnStyles propriedade.
Os estilos de coluna estão relacionados às colunas em um conjunto de dados, assim

como os estilos de tabelas estão relacionados às tabelas de dados. Assim como cada
tabela poderá ter apenas um estilo de tabela definido para ela por vez, cada coluna
poderá ter apenas um estilo de coluna definido para ela, em um estilo de tabela
específico. Essa relação é definida na propriedade da MappingName coluna.
Se você tiver criado um estilo de tabela sem estilos de coluna adicionados a ele, o Visual
Studio adicionará estilos de coluna padrão quando o formulário e a grade forem criados
em tempo de execução. No entanto, se você criou um estilo de tabela e adicionou
estilos de coluna a ele, o Visual Studio não criará nenhum estilo de coluna. Além disso,
será necessário definir estilos de coluna e atribuí-los com o nome de mapeamento para
que as colunas desejadas sejam exibidas na grade.
Como as colunas que serão incluídas na grade de dados são especificadas por meio da
atribuição de um estilo de coluna e como nenhum estilo de coluna foi atribuído às
colunas, é possível incluir colunas de dados no conjunto de dados que não são exibidas
na grade. Porém, já que a coluna de dados está incluída no conjunto de dados, os dados
não exibidos podem ser editados programaticamente.
７ Observação
Em geral, crie estilos de coluna e adicione-os à coleção de estilos de coluna antes

de adicionar os estilos de tabela à coleção de estilos de tabela. Quando você
adiciona um estilo de tabela vazio à coleção, os estilos de coluna são gerados
automaticamente. Consequentemente, uma exceção será gerada se você tentar
adicionar novos estilos de coluna com valores duplicados MappingName à coleção
de estilos de coluna.
Às vezes, será necessário ajustar somente uma coluna entre muitas colunas; por
exemplo, o conjunto de dados contém 50 colunas e você quer apenas 49. Nesse
caso, é mais fácil importar as 50 colunas e remover uma programaticamente, em
vez de adicionar programaticamente cada uma das 49 colunas individuais
desejadas.
Formatação
A formatação que pode ser aplicada ao DataGrid controle inclui estilos de borda, estilos
de linha de grade, fontes, propriedades de legenda, alinhamento de dados e cores
alternadas de plano de fundo entre linhas. Para obter mais informações, consulte Como
formatar o controle DataGrid dos Windows Forms.
Eventos
Além dos eventos de controle comuns, como MouseDown, Entere Scroll, o controle dá
suporte a DataGrid eventos associados à edição e navegação dentro da grade. A
CurrentCell propriedade determina qual célula está selecionada. O CurrentCellChanged
evento é gerado quando o usuário navega para uma nova célula. Quando o usuário
navega para uma nova tabela por meio de relações pai/filho, o Navigate evento é
gerado. O BackButtonClick evento é gerado quando o usuário clica no botão voltar
quando o usuário está exibindo uma tabela filho e o ShowParentDetailsButtonClick
evento é gerado quando o ícone mostrar/ocultar linhas pai é clicado.
Confira também
Controle DataGrid
Como: Formatar o controle DataGrid do Windows Forms
Como: Adicionar tabelas e colunas ao
controle DataGrid do Windows Forms
Artigo • 02/06/2023
７ Observação

Você pode exibir dados no controle Windows Forms DataGrid em tabelas e colunas
criando objetos DataGridTableStyle e adicionando-os ao objeto
GridTableStylesCollection, que é acessado por meio da DataGrid propriedade
TableStyles do controle. Cada estilo de tabela exibe o conteúdo da tabela de dados
especificada na propriedade MappingName do objeto DataGridTableStyle. Por padrão,
um estilo de tabela sem estilos de coluna especificados exibirá todas as colunas dentro
dessa tabela de dados. Você pode restringir quais colunas da tabela aparecem
adicionando objetos DataGridColumnStyle ao objeto GridColumnStylesCollection, que
é acessado por meio da propriedade GridColumnStyles de cada objeto
DataGridTableStyle.
Adicionar uma tabela e uma coluna a um DataGrid com

programação
1. Para exibir dados na tabela, primeiro você deve associar o DataGrid controle a um
conjunto de dados. Para obter mais informações, consulte Como associar o
controle DataGrid dos Windows Forms a uma fonte de dados.
Ｕ Cuidado
Ao especificar os estilos de coluna com programação, sempre crie os objetos

DataGridColumnStyle e adicione-os ao objeto GridColumnStylesCollection
objeto antes de adicionar objetos DataGridTableStyle para o objeto
GridTableStylesCollection. Ao adicionar um objeto DataGridTableStyle vazio
à coleção, os objetos DataGridColumnStyle são gerados automaticamente
para você. Consequentemente, uma exceção será gerada se você tentar
adicionar novos objetos DataGridColumnStyle com valores de
MappingName duplicados ao objeto GridColumnStylesCollection.
2. Declare um novo estilo de tabela e defina seu nome de mapeamento.
C#
DataGridTableStyle ts1 = new DataGridTableStyle();

ts1.MappingName = "Customers";
3. Declare um novo estilo de coluna e defina seu nome de mapeamento e outras

propriedades.
C#
DataGridBoolColumn myDataCol = new DataGridBoolColumn();

myDataCol.HeaderText = "My New Column";
myDataCol.MappingName = "Current";
4. Chame o método Adicionar do objeto GridColumnStylesCollection para adicionar

a coluna ao estilo de tabela
C#
ts1.GridColumnStyles.Add(myDataCol);
5. Chame o método Adicionar do objeto GridTableStylesCollection para adicionar o

estilo de tabela para a grade de dados.
C#
dataGrid1.TableStyles.Add(ts1);
Confira também
Controle DataGrid
Como: Adicionar tabelas e colunas do
usando o Designer
Artigo • 02/06/2023
７ Observação

Você pode exibir dados no controle Windows Forms DataGrid em tabelas e colunas
criando DataGridTableStyle objetos e adicionando-os GridTableStylesCollection ao
objeto, que é acessado por meio da DataGrid propriedade do TableStyles controle. Cada
estilo de tabela exibe o conteúdo de qualquer tabela de dados especificada na
MappingName propriedade do DataGridTableStyle. Por padrão, um estilo de tabela sem
estilos de coluna especificados exibirá todas as colunas dentro dessa tabela de dados.
Você pode restringir quais colunas da tabela aparecem adicionando
DataGridColumnStyle objetos ao GridColumnStylesCollection, que é acessado por meio
da GridColumnStyles propriedade de cada DataGridTableStyle.
Os procedimentos a seguir exigem um projeto de Aplicativo do Windows com um

formulário que contém um DataGrid controle. Para obter informações sobre como
configurar esse projeto, consulte Como criar um projeto de aplicativo Windows Forms e
como adicionar controles a Windows Forms. Por padrão, no Visual Studio 2005, o
DataGrid controle não está na Caixa de Ferramentas. Para obter informações sobre
como adicioná-lo, consulte Como Adicionar Itens à Caixa de Ferramentas.
Para adicionar uma tabela ao controle DataGrid no

designer
1. Para exibir dados na tabela, primeiro você deve associar o DataGrid controle a um
conjunto de dados. Para obter mais informações, consulte Como associar o
controle DataGrid dos Windows Forms a uma fonte de dados usando o designer.
2. Selecione a DataGrid propriedade do TableStyles controle no janela Propriedades e

clique no botão de reticências ( ) ao lado da propriedade para exibir o Editor de
Coleção DataGridTableStyle.
3. No editor de coleção, clique em Adicionar para inserir um estilo de tabela.
4. Clique em OK para fechar o editor de coleção e reabra-o clicando no botão de

reticências ao lado da TableStyles propriedade.
Quando você reabrir o editor de coleta, todas as tabelas de dados associadas ao

controle aparecerão na lista suspensa da MappingName propriedade do estilo de
tabela.
5. Na caixa Membros do editor de coleção, clique no estilo de tabela.
6. Na caixa Propriedades do editor de coleção, selecione o MappingName valor da

tabela que você deseja exibir.
Para adicionar uma coluna ao controle DataGrid no

designer
1. Na caixa Membros do Editor de Coleção DataGridTableStyle, selecione o estilo de
tabela adequado. Na caixa Propriedades do editor de coleção, selecione a
GridColumnStyles coleção e clique no botão de reticências ( ) ao lado da
propriedade para exibir o Editor de Coleção DataGridColumnStyle.
2. No editor de coleção, clique em Adicionar para inserir um estilo de coluna ou

clique na seta para baixo ao lado de Adicionar para especificar um tipo de coluna.
Na caixa suspensa, você pode selecionar o tipo ou DataGridBoolColumn o

DataGridTextBoxColumn tipo.
3. Clique em OK para fechar o Editor de Coleção DataGridColumnStyle e reabra-o

clicando no botão de reticências ao lado da GridColumnStyles propriedade.
Quando você reabrir o editor de coleta, todas as colunas de dados na tabela de

dados associada serão exibidas na lista suspensa da MappingName propriedade
do estilo de coluna.
4. Na caixa Membros do editor de coleção, clique no estilo de coluna.
5. Na caixa Propriedades do editor de coleção, selecione o MappingName valor da

coluna que você deseja exibir.
Confira também
Controle DataGrid
Como: Associar o controle DataGrid do
Windows Forms a uma fonte de dados
Artigo • 02/06/2023
７ Observação

O controle Windows Forms DataGrid foi projetado especificamente para exibir

informações de uma fonte de dados. Você associa o controle em tempo de execução
chamando o SetDataBinding método. Embora seja possível exibir dados de uma
variedade de fontes de dados, as fontes mais comuns são conjuntos de dados e
exibições de dados.
Associar dados ao controle DataGrid por com

programação
1. Grave código para preencher o conjunto de dados.
Se a fonte de dados for um conjunto de dados ou uma exibição de dados com

base em uma tabela de conjunto de dados, adicione código ao formulário para
preencher o conjunto de dados.
O código exato usado depende do local em que o conjunto de dados está

recebendo dados. Se o conjunto de dados estiver sendo preenchido diretamente
de um banco de dados, você normalmente chamará o Fill método de um
adaptador de dados, como no exemplo a seguir, que preenche um conjunto de
dados chamado DsCategories1 :
C#
sqlDataAdapter1.Fill(DsCategories1);
Se o conjunto de dados estiver sendo preenchido de um serviço Web XML,

geralmente uma instância do serviço será criada no seu código e uma chamada
será feita para um de seus métodos retornar um conjunto de dados. Em seguida,
mescle o conjunto de dados do serviço Web XML ao seu conjunto de dados local.
O exemplo a seguir mostra como você pode criar uma instância de um serviço
Web XML chamado CategoriesService , chamar seu GetCategories método e
mesclar o conjunto de dados resultante em um conjunto de dados local chamado
DsCategories1 :
C#
MyProject.localhost.CategoriesService ws = new
MyProject.localhost.CategoriesService();
ws.Credentials = System.Net.CredentialCache.DefaultCredentials;
DsCategories1.Merge(ws.GetCategories());
2. Chame o DataGrid método do SetDataBinding controle, passando-lhe a fonte de

dados e um membro de dados. Se você não precisar passar explicitamente um
membro de dados, passe uma cadeia de caracteres vazia.
７ Observação
Se você estiver associando a grade pela primeira vez, poderá definir as

propriedades e DataMember o DataSource controle. No entanto, não será
possível redefinir essas propriedades depois de serem definidas. Portanto, é
recomendável que você sempre use o SetDataBinding método.
O exemplo a seguir mostra como você pode associar programaticamente à tabela

Customers em um conjunto de dados chamado DsCustomers1 :
C#
DataGrid1.SetDataBinding(DsCustomers1, "Customers");
Se a tabela Clientes for a única tabela no conjunto de dados, também seria

possível associar a grade da seguinte forma:
C#
DataGrid1.SetDataBinding(DsCustomers1, "");
3. (Opcional) Adicione os estilos apropriados de tabela e coluna à grade. Se não

houver nenhum estilo de tabela, a tabela ainda será vista, mas com formatação
mínima e todas as colunas visíveis.
Confira também
Controle DataGrid
Como: Associar o controle DataGrid do
Windows Forms a uma fonte de dados
usando o Designer
Artigo • 02/06/2023
７ Observação

O controle Windows Forms DataGrid foi projetado especificamente para exibir

informações de uma fonte de dados. Você associa o controle em tempo de design
definindo as propriedades e DataMember as DataSource propriedades ou em tempo de
execução chamando o SetDataBinding método. Embora seja possível exibir dados de
uma variedade de fontes de dados, as fontes mais comuns são conjuntos de dados e
exibições de dados.
Se a fonte de dados estiver disponível em tempo de design – por exemplo, se o

formulário contiver uma instância de um conjunto ou exibição de dados –, será possível
associar a grade à fonte de dados em tempo de design. Então, será possível visualizar a
aparência dos dados na grade.
Também é possível associar a grade programaticamente, em tempo de execução. Isso é

útil quando se deseja definir uma fonte de dados com base nas informações obtidas em
tempo de execução. Por exemplo, o aplicativo pode permitir que o usuário especifique o
nome de uma tabela para exibir. Também é necessário em situações em que a fonte de
dados não existe em tempo de design. Isso inclui fontes de dados como matrizes,
coleções, conjuntos de dados não tipados e leitores de dados.
O procedimento a seguir requer um projeto de aplicativo do Windows com um

formulário que contém um DataGrid controle. Para obter informações sobre como
como adicionar controles a Windows Forms. No Visual Studio 2005, o DataGrid controle
não está na Caixa de Ferramentas por padrão. Para obter informações sobre como
adicioná-lo, consulte Como Adicionar Itens à Caixa de Ferramentas. Além disso, no
Visual Studio 2005, você pode usar a janela Fontes de Dados para associação de dados
em tempo de design. Para obter mais informações , consulte Associar controles a dados
no Visual Studio.
Associar os dados do controle DataGrid a uma

única tabela no designer
1. Defina a propriedade do DataSource controle para o objeto que contém os itens
de dados aos quais você deseja associar.
2. Se a fonte de dados for um conjunto de dados, defina a DataMember propriedade

como o nome da tabela a ser associada.
3. Se a fonte de dados for um conjunto de dados ou uma exibição de dados com

base em uma tabela de conjunto de dados, adicione código ao formulário para
preencher o conjunto de dados.
O código exato usado depende do local em que o conjunto de dados está

recebendo dados. Se o conjunto de dados estiver sendo preenchido diretamente
de um banco de dados, normalmente, chama-se o método Fill de um adaptador
de dados, como no exemplo de código a seguir, que preenche um conjunto de
dados chamado DsCategories1 :
C#
sqlDataAdapter1.Fill(DsCategories1);
4. (Opcional) Adicione os estilos apropriados de tabela e coluna à grade.
Se não houver nenhum estilo de tabela, a tabela ainda será vista, mas com
formatação mínima e todas as colunas visíveis.
Associar os dados do controle DataGrid a várias

tabelas em um conjunto de dados no designer
1. Defina a propriedade do DataSource controle para o objeto que contém os itens
de dados aos quais você deseja associar.
2. Se o conjunto de dados contiver tabelas relacionadas (ou seja, se ele contiver um

objeto de relação), defina a DataMember propriedade como o nome da tabela pai.
3. Grave código para preencher o conjunto de dados.

Confira também
Controle DataGrid
Acessando dados no Visual Studio
Como: Alterar os dados exibidos em
tempo de execução no controle
DataGrid do Windows Forms
Artigo • 02/06/2023
７ Observação

Depois de criar um Windows Forms DataGrid usando os recursos de tempo de design,

talvez você também queira alterar dinamicamente os DataSet elementos do objeto da
grade em tempo de execução. Isso pode incluir alterações em valores individuais da
tabela ou alterar qual fonte de dados está associada ao DataGrid controle. As alterações
em valores individuais são feitas por meio do DataSet objeto, não do DataGrid controle.
Alterar dados com programação

1. Especifique a tabela desejada do DataSet objeto e a linha e o campo desejados da
tabela e defina a célula igual ao novo valor.
７ Observação
Para especificar a primeira tabela da DataSet ou primeira linha da tabela, use

0.
O exemplo a seguir mostra como alterar a segunda entrada da primeira linha da

primeira tabela de um conjunto de dados clicando Button1 . As DataSet tabelas
( ds e tabelas 1 0 ) foram criadas anteriormente.
C#

{
ds.Tables[0].Rows[0][1]="NewEntry";
}
C#
Em tempo de execução, você pode usar o SetDataBinding método para associar o

DataGrid controle a uma fonte de dados diferente. Por exemplo, você pode ter
vários controles de dados ADO.NET, cada um conectado a um banco de dados
diferente.
Alterar o DataSource com programação

1. Defina o SetDataBinding método como o nome da fonte de dados e tabela à qual
você deseja associar.
O exemplo a seguir mostra como alterar a fonte de data usando o SetDataBinding

método para um controle de dados ADO.NET (adoPubsAuthors) que está
conectado à tabela Autores no banco de dados pubs.
C#
private void ResetSource()

{
DataGrid1.SetDataBinding(adoPubsAuthors, "Authors");
}
Confira também
DataSets ADO.NET
Como: Criar listas mestre e de detalhes
com o controle DataGrid do Windows
Forms
Artigo • 02/06/2023
７ Observação

Se você DataSet contiver uma série de tabelas relacionadas, poderá usar dois DataGrid
controles para exibir os dados em um formato mestre/detalhe. Um DataGrid é
designado para ser a grade mestra e o segundo é designado para ser a grade de
detalhes. Quando você seleciona uma entrada na lista mestra, todas as entradas filho
relacionados são mostradas na lista de detalhes. Por exemplo, se você DataSet contiver
uma tabela Customers e uma tabela pedidos relacionadas, você especificaria a tabela
Customers para ser a grade mestra e a tabela Pedidos para ser a grade de detalhes.
Quando um cliente é selecionado na grade principal, todos os pedidos associados a ele
na tabela Pedidos serão exibidos na grade de detalhes.
Definir uma relação mestre/detalhes com programação

1. Crie dois novos DataGrid controles e defina suas propriedades.
2. Adicione tabelas ao conjunto de dados.
3. Declare uma variável de tipo DataRelation para representar a relação que você
deseja criar.
4. Instancie o relacionamento especificando um nome para o relacionamento e

especificando a tabela, coluna e item que associará as duas tabelas.
5. Adicione a relação à DataSet coleção do Relations objeto.
6. Use o SetDataBinding método do DataGrid para associar cada uma das grades ao
DataSet.
O exemplo a seguir mostra como definir uma relação mestre/detalhe entre as
tabelas Clientes e Pedidos em um ( ds ) gerado DataSet anteriormente.
C#
DataRelation myDataRelation;
myDataRelation = new DataRelation("CustOrd",
ds.Tables["Customers"].Columns["CustomerID"],
ds.Tables["Orders"].Columns["CustomerID"]);
// Add the relation to the DataSet.
ds.Relations.Add(myDataRelation);
GridOrders.SetDataBinding(ds,"Customers");
GridDetails.SetDataBinding(ds,"Customers.CustOrd");
Confira também
Controle DataGrid
Como: Criar listas mestre e de detalhes
com o controle DataGrid do Windows
Forms usando o Designer
Artigo • 02/06/2023
７ Observação

Se você DataSet contiver uma série de tabelas relacionadas, poderá usar dois DataGrid
controles para exibir os dados em um formato de detalhes mestre. Um DataGrid é
designado para ser a grade mestra e o segundo é designado para ser a grade de
detalhes. Quando você seleciona uma entrada na lista mestra, todas as entradas filho
relacionados são mostradas na lista de detalhes. Por exemplo, se você DataSet contiver
uma tabela Customers e uma tabela pedidos relacionadas, você especificaria a tabela
Customers para ser a grade mestra e a tabela Pedidos para ser a grade de detalhes.
Quando um cliente é selecionado na grade principal, todos os pedidos associados a ele
na tabela Pedidos serão exibidos na grade de detalhes.
O procedimento a seguir requer um projeto de aplicativo do Windows

(Arquivo>Novo>Projeto>Visual C# ou Visual Basic>Classic Desktop>Windows Forms
Aplicativo).
Criar uma lista mestre/detalhes no designer

1. Adicione dois DataGrid controles ao formulário. Para mais informações, consulte
Como adicionar controles ao Windows Forms. No Visual Studio 2005, o DataGrid
controle não está na Caixa de Ferramentas por padrão. Para obter mais
informações, consulte Como adicionar itens à Caixa de ferramentas.
７ Observação
As etapas a seguir não são aplicáveis ao Visual Studio 2005, que usa a janela
Fontes de Dados para associação de dados em tempo de design. Para obter
mais informações, consulte Associar controles a dados no Visual Studio e
Como exibir dados relacionados em um Aplicativo do Windows Forms.
2. Arraste duas ou mais tabelas de Gerenciador de Servidores ao formulário.
3. No menu Dados, selecione Gerar conjunto de dados.
4. Defina as relações entre as tabelas usando o XML Designer. Para ver mais detalhes,
consulte “Como criar relacionamentos um para muitos em esquemas XML e
conjuntos de dados” no MSDN.
5. Salve os relacionamentos selecionando Salvar tudo do menu Arquivo.
6. Configure o DataGrid controle que você deseja designar a grade mestra, da

seguinte maneira:
a. Selecione a DataSet lista suspensa na DataSource propriedade.
b. Selecione a tabela mestra (por exemplo, "Clientes") na lista suspensa na

DataMember propriedade.
7. Configure o DataGrid controle que você deseja designar a grade de detalhes, da

seguinte maneira:
a. Selecione a DataSet lista suspensa na DataSource propriedade.
b. Selecione a relação (por exemplo, "Customers.CustOrd") entre as tabelas mestra

e de detalhes na lista suspensa na DataMember propriedade. Para ver a relação,
expanda o nó clicando no sinal de mais (+) ao lado da tabela mestre na lista
suspensa.
Confira também
Controle DataGrid
Como: Excluir ou ocultar colunas no
Artigo • 02/06/2023
７ Observação

Você pode excluir ou ocultar colunas programaticamente no controle Windows Forms

DataGrid usando as propriedades e os métodos do e DataGridColumnStyle dos
GridColumnStylesCollection objetos (que são membros da DataGridTableStyle classe).
As colunas excluídas ou ocultas ainda existem na fonte de dados à qual a grade está
associada e ainda podem ser acessados por meio de programação. Elas simplesmente
não são visíveis no datagrid.
７ Observação
Se seu aplicativo não acessar determinadas colunas de dados e você não desejar
exibi-los no datagrid, provavelmente não será necessário nem mesmo incluí-los na
fonte de dados.
Excluir uma coluna do DataGrid com programação

1. Na área de declarações do formulário, declare uma nova instância da
DataGridTableStyle classe.
2. Defina a DataGridTableStyle.MappingName propriedade para a tabela na fonte de

dados à qual você deseja aplicar o estilo. O exemplo a seguir usa a
DataGrid.DataMember propriedade, que ela pressupõe já estar definida.
3. Adicione o novo DataGridTableStyle objeto à coleção de estilos de tabela do

datagrid.
4. Chame o RemoveAt método da DataGridcoleção 's GridColumnStyles ,
especificando o índice de coluna da coluna a ser excluído.
C#
// Declare a new DataGridTableStyle in the

// declarations area of your form.
DataGridTableStyle ts = new DataGridTableStyle();
private void deleteColumn()

{
// Set the DataGridTableStyle.MappingName property
// to the table in the data source to map to.
ts.MappingName = dataGrid1.DataMember;
// Add it to the datagrid's TableStyles collection

dataGrid1.TableStyles.Add(ts);
// Delete the first column (index 0)

dataGrid1.TableStyles[0].GridColumnStyles.RemoveAt(0);
}
Ocultar uma coluna do DataGrid com programação

1. Na área de declarações do formulário, declare uma nova instância da
DataGridTableStyle classe.
2. Defina a MappingName propriedade da DataGridTableStyle tabela na fonte de

dados à qual você deseja aplicar o estilo. O exemplo de código a seguir usa a
DataGrid.DataMember propriedade, que ela pressupõe já estar definida.
3. Adicione o novo DataGridTableStyle objeto à coleção de estilos de tabela do

datagrid.
4. Oculte a coluna definindo sua Width propriedade como 0, especificando o índice

de coluna da coluna a ser ocultada.
C#
// Declare a new DataGridTableStyle in the

// declarations area of your form.
DataGridTableStyle ts = new DataGridTableStyle();
private void hideColumn()

{
// Set the DataGridTableStyle.MappingName property
// to the table in the data source to map to.
ts.MappingName = dataGrid1.DataMember;
// Add it to the datagrid's TableStyles collection
dataGrid1.TableStyles.Add(ts);
// Hide the first column (index 0)

dataGrid1.TableStyles[0].GridColumnStyles[0].Width = 0;
}
Confira também
Windows Forms
Como: Formatar o controle DataGrid do
Windows Forms
Artigo • 02/06/2023
７ Observação

Aplicar cores diferentes a várias partes de um DataGrid controle pode ajudar a facilitar a
leitura e a interpretação das informações. É possível aplicar cores às linhas e colunas.
Linhas e colunas também podem ser ocultadas ou exibidas como você desejar.
Há três aspectos básicos de formatação do DataGrid controle. Você pode definir as

propriedades para estabelecer um estilo padrão no qual os dados são exibidos. Com
base nisso, você pode então personalizar a maneira como determinadas tabelas são
exibidas no tempo de execução. Por fim, você pode modificar quais colunas são exibidas
na grade de dados, bem como as cores e outras formatações mostradas.
Como uma etapa inicial na formatação de uma grade de dados, você pode definir as
propriedades de DataGrid si mesmo. Essas opções de cor e formato formam a base da
qual você pode fazer alterações dependendo das tabelas de dados e colunas exibidas.
Estabelecer um estilo padrão para o controle DataGrid

1. Defina as seguintes propriedades conforme necessário:
Propriedade Descrição
AlternatingBackColor A propriedade BackColor define a cor das linhas de numeração

par da grade. Quando você define a AlternatingBackColor
propriedade como uma cor diferente, cada outra linha é definida
como essa nova cor (linhas 1, 3, 5 e assim por diante).
BackColor A cor da tela de fundo das linhas de numeração par da grade

(linhas 0, 2, 4, 6 e assim por diante).
BackgroundColor Enquanto as propriedades e AlternatingBackColor as BackColor

propriedades determinam a cor das linhas na grade, a
BackgroundColor propriedade determina a cor da área de não-
linha, que só fica visível quando a grade é rolada para a parte
inferior ou se apenas algumas linhas estão contidas na grade.
BorderStyle O estilo de borda da grade, um dos BorderStyle valores de

enumeração.
CaptionBackColor A cor da tela de fundo da legenda da janela da grade que aparece

logo acima da grade.
CaptionFont A fonte da legenda na parte superior da grade.
CaptionForeColor A cor da tela de fundo da legenda da janela da grade.
Font A fonte usada para exibir o texto na grade.
ForeColor A cor da fonte exibida pelos dados nas linhas da grade de dados.
GridLineColor A cor das linhas da grade dos dados.
GridLineStyle O estilo das linhas que separam as células da grade, um dos

valores de DataGridLineStyle enumeração.
HeaderBackColor A cor da tela de fundo dos cabeçalhos de linha e de coluna.
HeaderFont A fonte usada para os cabeçalhos de coluna.
HeaderForeColor A cor de primeiro plano dos cabeçalhos de coluna da grade,

incluindo o texto do cabeçalho de coluna e os glifos mais/menos
(para expandir linhas quando várias tabelas relacionadas são
exibidas).
LinkColor A cor do texto de todos os links na grade de dados, incluindo

links para tabelas filho, o nome da relação e assim por diante.
ParentRowsBackColor Na tabela filho, indica a cor da tela de fundo das linhas pai.
ParentRowsForeColor Na tabela filho, indica a cor de primeiro plano das linhas pai.
ParentRowsLabelStyle Determina se os nomes de tabela e coluna são exibidos na linha

pai, por meio da DataGridParentRowsLabelStyle enumeração.
PreferredColumnWidth A largura padrão (em pixels) das colunas na grade. Defina essa
propriedade antes de redefinir as DataSource propriedades (
DataMember separadamente ou por meio do SetDataBinding
método) ou a propriedade não terá nenhum efeito.
Não é possível definir a propriedade para um valor inferior a 0.

PreferredRowHeight A altura (em pixels) das linhas na grade. Defina essa propriedade
antes de redefinir as DataSource propriedades ( DataMember
separadamente ou por meio do SetDataBinding método) ou a
propriedade não terá nenhum efeito.
RowHeaderWidth A largura dos cabeçalhos de linha da grade.
SelectionBackColor Quando uma linha ou célula é selecionada, essa é a cor da tela de

fundo.
SelectionForeColor Quando uma linha ou célula é selecionada, essa é a cor de

primeiro plano.
７ Observação
Lembre-se que, ao personalizar as cores dos controles, é possível tornar o

controle inacessível devido a opção incorreta de cor (por exemplo, vermelho e
verde). Use as cores disponíveis na paleta de Cores do Sistema para evitar
esse problema.
Os procedimentos a seguir pressupõem que seu formulário tem um DataGrid

controle associado a uma tabela de dados. Para obter mais informações, consulte
Associando o controle DataGrid do Windows Forms a uma fonte de dados.
Definir o estilo de tabela e coluna de uma tabela de

dados com programação
1. Crie um novo estilo de tabela e defina suas propriedades.
2. Crie um estilo de coluna e defina suas propriedades.
3. Adicione o estilo de coluna à coleção de estilos de coluna do estilo de tabela.
4. Adicione o estilo de tabela à coleção de estilos de tabela da grade de dados.
5. No exemplo abaixo, crie uma instância de uma nova DataGridTableStyle e defina

sua MappingName propriedade.
6. Crie uma nova instância de um GridColumnStyle e defina seu MappingName (e

algumas outras propriedades de layout e exibição).
7. Repita as etapas 2 a 6 para cada estilo de coluna que você deseja criar.
O exemplo a seguir ilustra como um DataGridTextBoxColumn é criado, pois um

nome deve ser exibido na coluna. Além disso, você adiciona o estilo da coluna ao
GridColumnStylesCollection estilo da tabela e adiciona o estilo de tabela à
GridTableStylesCollection grade de dados.
C#
private void addCustomDataTableStyle()

{
// Add a GridTableStyle and set the MappingName
// to the name of the DataTable.
DataGridTableStyle TSAuthors = new DataGridTableStyle();
TSAuthors.MappingName = "Authors";
// Add a GridColumnStyle and set the MappingName

// to the name of a DataColumn in the DataTable.
// Set the HeaderText and Width properties.
DataGridColumnStyle TCFirstName = new DataGridTextBoxColumn();
TCFirstName.MappingName = " AV_FName";
TCFirstName.HeaderText = "First Name";
TCFirstName.Width = 75;
TSAuthors.GridColumnStyles.Add(TCFirstName);
// Add the DataGridTableStyle instance to

// the GridTableStylesCollection.
dataGrid1.TableStyles.Add(TSAuthors);
}
Confira também
GridTableStylesCollection
GridColumnStylesCollection
DataGrid
Controle DataGrid
Como: Formatar o controle DataGrid do
Windows Forms usando o Designer
Artigo • 02/06/2023
７ Observação

Aplicar cores diferentes a várias partes de um DataGrid controle pode ajudar a facilitar a
leitura e a interpretação das informações. É possível aplicar cores às linhas e colunas.
Linhas e colunas também podem ser ocultadas ou exibidas como você desejar.
Há três aspectos básicos de formatação do DataGrid controle:
Você pode definir as propriedades para estabelecer um estilo padrão no qual os

dados são exibidos.
Com base nisso, você pode então personalizar a maneira como determinadas
tabelas são exibidas no tempo de execução.
Por fim, você pode modificar quais colunas são exibidas na grade de dados, bem
como as cores e outras formatações mostradas.
Como uma etapa inicial na formatação de uma grade de dados, você pode definir as
propriedades de DataGrid si mesmo. Essas opções de cor e formato formam a base da
qual você pode fazer alterações dependendo das tabelas de dados e colunas exibidas.

formulário contendo um DataGrid controle. Para obter informações sobre como
como adicionar controles a Windows Forms. No Visual Studio 2005, o DataGrid controle
não está na Caixa de Ferramentas por padrão. Para obter mais informações, consulte
Como adicionar itens à Caixa de ferramentas.
Estabelecer um estilo padrão para o controle DataGrid

1. Selecione o controle DataGrid.
2. Na janela Propriedades, defina as seguintes propriedades, conforme adequado.
AlternatingBackColor A propriedade BackColor define a cor das linhas de numeração

par da grade. Quando você define a AlternatingBackColor
propriedade como uma cor diferente, cada outra linha é definida
como essa nova cor (linhas 1, 3, 5 e assim por diante).
BackColor A cor da tela de fundo das linhas de numeração par da grade

(linhas 0, 2, 4, 6 e assim por diante).
BackgroundColor Enquanto as propriedades e AlternatingBackColor as BackColor

propriedades determinam a cor das linhas na grade, a
BackgroundColor propriedade determina a cor da área fora da
área da linha, que só fica visível quando a grade é rolada para a
parte inferior ou se apenas algumas linhas estão contidas na
grade.
BorderStyle O estilo de borda da grade, um dos BorderStyle valores de

enumeração.
CaptionBackColor A cor da tela de fundo da legenda da janela da grade que aparece

logo acima da grade.
CaptionFont A fonte da legenda na parte superior da grade.
CaptionForeColor A cor da tela de fundo da legenda da janela da grade.
Font A fonte usada para exibir o texto na grade.
ForeColor A cor da fonte exibida pelos dados nas linhas da grade de dados.
GridLineColor A cor das linhas da grade dos dados.
GridLineStyle O estilo das linhas que separam as células da grade, um dos

valores de DataGridLineStyle enumeração.
HeaderBackColor A cor da tela de fundo dos cabeçalhos de linha e de coluna.
HeaderFont A fonte usada para os cabeçalhos de coluna.
HeaderForeColor A cor de primeiro plano dos cabeçalhos de coluna da grade,

incluindo o texto do cabeçalho de coluna e os glifos de sinal de
mais (+) e sinal de menos (-) que expandem e recolhem as linhas
quando várias tabelas relacionadas são exibidas.
LinkColor A cor do texto de todos os links na grade de dados, incluindo

links para tabelas filho, o nome da relação e assim por diante.
ParentRowsBackColor Na tabela filho, indica a cor da tela de fundo das linhas pai.
ParentRowsForeColor Na tabela filho, indica a cor de primeiro plano das linhas pai.
ParentRowsLabelStyle Determina se os nomes de tabela e coluna são exibidos na linha

pai, por meio da DataGridParentRowsLabelStyle enumeração.
PreferredColumnWidth A largura padrão (em pixels) das colunas na grade. Defina essa
propriedade antes de redefinir as DataSource propriedades (
DataMember separadamente ou por meio do SetDataBinding
método) ou a propriedade não terá nenhum efeito.
PreferredRowHeight A altura (em pixels) das linhas na grade. Defina essa propriedade
antes de redefinir as DataSource propriedades ( DataMember
separadamente ou por meio do SetDataBinding método) ou a
propriedade não terá nenhum efeito.
RowHeaderWidth A largura dos cabeçalhos de linha da grade.
SelectionBackColor Quando uma linha ou célula é selecionada, essa é a cor da tela de

fundo.
SelectionForeColor Quando uma linha ou célula é selecionada, essa é a cor de

primeiro plano.
７ Observação
Quando você está personalizando as cores dos controles, é possível tornar o

controle inacessível devido à escolha incorreta de cor (por exemplo, vermelho
e verde). Use as cores disponíveis na paleta de Cores do Sistema para evitar
esse problema.
O procedimento a seguir requer um DataGrid controle associado a uma tabela de

dados. Para obter mais informações, consulte Como associar o controle DataGrid
dos Windows Forms a uma fonte de dados.
Para definir o estilo de tabela e de coluna de uma tabela

de dados em tempo de design
1. Selecione o DataGrid controle em seu formulário.
2. Na janela Propriedades, selecione a TableStyles propriedade e clique nas
Reticências (
3. Na caixa de diálogo Editor de Coleção DataGridTableStyle, clique em Adicionar

para adicionar um estilo de tabela à coleção.
Com o Editor de Coleção DataGridTableStyle, você pode adicionar e remover

estilos de tabela, definir propriedades de layout e exibição e definir o nome de
mapeamento para os estilos de tabela.
4. Defina a MappingName propriedade como o nome de mapeamento para cada

estilo de tabela.
O nome do mapeamento é usado para especificar qual estilo de tabela deve ser
usado com cada tabela.
5. No Editor de Coleção DataGridTableStyle, selecione a GridColumnStyles

propriedade e clique no botão reticências ( ).
6. Na caixa de diálogo Editor de Coleção DataGridColumnStyle, adicione estilos de

coluna ao estilo de tabela que você criou.
Com o Editor de Coleção DataGridColumnStyle, você pode adicionar e remover

estilos de coluna, definir propriedades de layout e exibição e definir o nome de
mapeamento e cadeias de caracteres de formatação para as colunas de dados.
７ Observação
Para obter mais informações sobre as cadeias de caracteres de formatação,

consulte Tipos de formatação.
Confira também
GridTableStylesCollection
GridColumnStylesCollection
DataGrid
Controle DataGrid
Como: Responder a cliques no controle
Artigo • 21/06/2023
７ Observação

Depois que o Windows Forms DataGrid estiver conectado a um banco de dados, você
poderá monitorar qual célula o usuário clicou.
Para detectar quando o usuário do DataGrid seleciona

uma célula diferente
CurrentCellChanged No manipulador de eventos, escreva o código para responder
adequadamente.
C#
private void myDataGrid_CurrentCellChanged(object sender,

System.EventArgs e)
{
MessageBox.Show ("Col is " + myDataGrid.CurrentCell.ColumnNumber
+ ", Row is " + myDataGrid.CurrentCell.RowNumber
+ ", Value is " + myDataGrid[myDataGrid.CurrentCell] );
}
(Visual C#) Coloque o código a seguir no construtor do formulário para registrar o

C#
this.myDataGrid.CurrentCellChanged += new
System.EventHandler(this.myDataGrid_CurrentCellChanged);
Para determinar qual parte do DataGrid o usuário clicou

Chame o HitTest método em um manipulador de eventos apropriado, como para o
MouseDown evento ou Click .
O HitTest método retorna um DataGrid.HitTestInfo objeto que contém a linha e a

coluna de uma área clicada.
C#
private void myDataGrid_MouseDown(object sender,

System.Windows.Forms.MouseEventArgs e)
{
DataGrid myGrid = (DataGrid) sender;
System.Windows.Forms.DataGrid.HitTestInfo hti;
hti = myGrid.HitTest(e.X, e.Y);
string message = "You clicked ";
switch (hti.Type)
{
case System.Windows.Forms.DataGrid.HitTestType.None :
message += "the background.";
break;
case System.Windows.Forms.DataGrid.HitTestType.Cell :
message += "cell at row " + hti.Row + ", col " + hti.Column;
break;
case System.Windows.Forms.DataGrid.HitTestType.ColumnHeader :
message += "the column header for column " + hti.Column;
break;
case System.Windows.Forms.DataGrid.HitTestType.RowHeader :
message += "the row header for row " + hti.Row;
break;
case System.Windows.Forms.DataGrid.HitTestType.ColumnResize :
message += "the column resizer for column " + hti.Column;
break;
case System.Windows.Forms.DataGrid.HitTestType.RowResize :
message += "the row resizer for row " + hti.Row;
break;
case System.Windows.Forms.DataGrid.HitTestType.Caption :
message += "the caption";
break;
case System.Windows.Forms.DataGrid.HitTestType.ParentRows :
message += "the parent row";
break;
}
Console.WriteLine(message);
}

C#
this.myDataGrid.MouseDown += new
System.Windows.Forms.MouseEventHandler
(this.myDataGrid_MouseDown);
Confira também
Controle DataGrid
Windows Forms
Como: Validar a entrada com o controle
Artigo • 21/06/2023
７ Observação

Há dois tipos de validação de entrada disponíveis para o controle Windows

FormsDataGrid. Se o usuário tentar inserir um valor que é de um tipo de dados
inaceitável para a célula, por exemplo uma cadeia de caracteres em um número inteiro,
o valor inválido será substituído pelo valor anterior. Esse tipo de validação de entrada é
feita automaticamente e não pode ser personalizada.
O outro tipo de validação de entrada pode ser usado para rejeitar quaisquer dados
inaceitáveis, por exemplo, um valor 0 em um campo que deve ser maior ou igual a 1 ou
uma cadeia de caracteres inadequada. Isso é feito no conjunto de dados escrevendo um
manipulador de eventos para o ColumnChanging evento ou RowChanging . O exemplo
a seguir usa o ColumnChanging evento porque o valor inaceitável não é permitido para
a coluna "Product" em particular. Você pode usar o RowChanging evento para verificar
se o valor de uma coluna "Data de Término" é posterior à coluna "Data de Início" na
mesma linha.
Validando entrada do usuário

1. Escreva código para manipular o ColumnChanging evento para a tabela
apropriada. Quando uma entrada inadequada for detectada, chame o
SetColumnError método do DataRow objeto .
C#
//Handle column changing events on the Customers table

private void Customers_ColumnChanging(object sender,
System.Data.DataColumnChangeEventArgs e) {
//Only check for errors in the Product column

if (e.Column.ColumnName.Equals("Product")) {
//Do not allow "Automobile" as a product
if (e.ProposedValue.Equals("Automobile")) {
object badValue = e.ProposedValue;
e.ProposedValue = "Bad Data";
e.Row.RowError = "The Product column contains an error";
e.Row.SetColumnError(e.Column, "Product cannot be " +
badValue);
}
}
}
2. Conecte o manipulador de eventos ao evento.
Coloque o código a seguir dentro do evento do Load formulário ou de seu

construtor.
C#
// Assumes the grid is bound to a dataset called customersDataSet1

// with a table called Customers.
// Put this code in the form's Load event or its constructor.
customersDataSet1.Tables["Customers"].ColumnChanging += new
DataColumnChangeEventHandler(this.Customers_ColumnChanging);
Confira também
DataGrid
ColumnChanging
SetColumnError
Controle DataGrid
Atalhos de teclado para o controle
DataGrid dos Windows Forms
Artigo • 02/06/2023
７ Observação

A tabela a seguir lista os atalhos de teclado que podem ser usados para navegação no
controle Windows FormsDataGrid:
Ação Atalho
Concluir uma entrada de célula e avance para a próxima célula abaixo. Enter
Se o foco estiver em um link da tabela filho, navegue para essa tabela.
Cancelar a edição de célula se estiver no modo de edição de célula. ESC
Se estiver na seleção de letreiro, cancele a edição na linha.
Excluir o caractere antes do ponto de inserção ao editar uma célula. BACKSPACE
Excluir o caractere após o ponto de inserção ao editar uma célula. Delete (excluir)
Ir para a primeira célula na linha atual. HOME
Ir para a última célula na linha atual. END
Realçar caracteres na célula atual e posicionar o ponto de inserção no F2

final da linha. Mesmo comportamento que clicar duas vezes em uma
célula.
Ação Atalho
Se o foco estiver em uma célula, vá para a próxima célula na linha. TAB
Se o foco estiver na última célula em uma linha, vá para o primeiro link

da tabela filho da linha e expanda-o.
Se o foco estiver em um link filho, vá para o próximo link filho.
Se o foco estiver no último link filho, vá para a primeira célula da linha

seguinte.
Se o foco estiver em uma célula, vá para a célula anterior na linha. SHIFT+TAB
Se o foco estiver na primeira célula em uma linha, vá para o último link

da tabela filho expandida da linha anterior ou vá para a última célula
da linha anterior.
Se o foco estiver em um link filho, vá para o link filho anterior.
Se o foco estiver no primeiro link filho, vá para a última célula da linha

anterior.
Ir para o próximo controle na ordem de tabulação. CTRL+TAB
Ir para o controle anterior na ordem de tabulação. CTRL+SHIFT+TAB
Subir para a tabela pai se estiver em uma tabela filho. Mesmo ALT+SETA PARA A
comportamento que clicar no botão Voltar. ESQUERDA
Expandir links da tabela filho. ALT+SETA PARA BAIXO expande todos os ALT+SETA PARA BAIXO
links, não apenas os selecionados. ou CTRL+SINAL DE
ADIÇÃO
Recolher links da tabela filho. ALT+SETA PARA CIMA recolhe todos os ALT+SETA PARA CIMA
links, não apenas aqueles selecionados. ou CTRL+SINAL DE
SUBTRAÇÃO
Ir para a célula não vazia mais distante na direção da seta. CTRL+SETA
Estender a seleção uma linha na direção da seta (exceto links da tabela SHIFT+SETA PARA
filho). CIMA/SETA PARA BAIXO
Estender a seleção para a linha mais não vazia mais distante na direção CTRL+SHIFT+ SETA
da seta (exceto links da tabela filho). PARA CIMA/PARA
BAIXO
Mover para a célula superior esquerda. CTRL+HOME
Mover para a célula inferior direita. CTRL+END

Ação Atalho
Estender a seleção para a linha superior. CTRL+SHIFT+HOME
Estender a seleção para a linha inferior. CTRL+SHIFT+END
Selecionar a linha atual (exceto por links da tabela filho). SHIFT+BARRA DE

ESPAÇOS
Selecionar toda a grade (exceto por links da tabela filho). CTRL+A
Exibir a linha pai quando estiver em uma tabela filho. CTRL+PAGE DOWN
Ocultar a linha pai quando estiver em uma tabela filho. CTRL+PAGE UP
Estender a seleção para baixo uma tela (exceto por links da tabela SHIFT+PAGE DOWN
filho).
Estender a seleção para cima uma tela (exceto por links da tabela filho). SHIFT+PAGE UP
Chame o EndEdit método para a linha atual. CTRL+ENTER
Insira um DBNull.Value valor em uma célula quando estiver no modo CTRL+0

de edição.
Confira também
Controle DataGrid
Controle DataGridView (Windows
Forms)
Artigo • 02/06/2023
O controle de DataGridView fornece uma maneira poderosa e flexível para exibir dados
em um formato de tabela. Você pode usar o controle DataGridView para mostrar as
exibições somente leitura de uma pequena quantidade de dados ou pode ajustar a
escala para mostrar exibições editáveis de grandes conjuntos de dados.
Você pode estender o controle DataGridView de várias maneiras para compilar

comportamentos personalizados em seus aplicativos. Por exemplo, você pode
especificar seus próprios algoritmos de classificação com programação, podendo
também criar seus próprios tipos de células. É possível personalizar facilmente a
aparência do controle DataGridView escolhendo dentre várias propriedades. Muitos
tipos de armazenamentos de dados podem ser usados como uma fonte de dados ou o
controle DataGridView pode operar sem nenhuma fonte de dados associada a ele.
Os tópicos nesta seção descrevem os conceitos e técnicas que você pode usar para
compilar recursos DataGridView em seus aplicativos.
Nesta seção
Visão geral do controle DataGridView
Fornece tópicos que descrevem as arquitetura e os principais conceitos do controle
DataGridView do Windows Forms.
Funcionalidade padrão no controle DataGridView dos Windows Forms

Descreve a aparência padrão e o comportamento do controle DataGridView do
Windows Forms quando ele é associado a uma fonte de dados.
Tipos de coluna no controle DataGridView dos Windows Forms

Descreve os tipos de coluna no controle DataGridView do Windows Forms usado para
exibir dados e permitir que os usuários modifiquem ou adicionem dados.
Funcionalidades de coluna, linha e célula básicas no controle DataGridView dos

Windows Forms
Fornece tópicos que descrevem as propriedades da célula, linha e coluna mais usados.
Formatação básica e estilos no controle DataGridView dos Windows Forms

Fornece tópicos que descrevem como modificar a aparência básica do controle e a
formatação de exibição de dados da célula.
Exibindo dados no controle DataGridView dos Windows Forms

Fornece tópicos que descrevem como preencher o controle com os dados
manualmente ou de uma fonte de dados externa.
Redimensionando colunas e linhas no controle DataGridView dos Windows Forms

Fornece tópicos que descrevem como o tamanho de linhas e colunas pode ser ajustado
automaticamente para caber no conteúdo da célula ou para ajustar à largura do
controle disponível.
Classificando dados no controle DataGridView dos Windows Forms

Fornece tópicos que descrevem os recursos de classificação no controle.
Entrada de dados no controle DataGridView dos Windows Forms

Fornece tópicos que descrevem como alterar os maneira como os usuários adicionam e
modificam dados no controle.
Seleção e uso da Área de Transferência com o controle DataGridView dos Windows

Forms
Fornece tópicos que descrevem os recursos de seleção de célula, linha e coluna no
controle.
Programando com células, linhas e colunas no controle DataGridView dos Windows

Forms
Fornece tópicos que descrevem como programar com objetos de célula, linha e coluna.
Personalizando o controle DataGridView dos Windows Forms

Fornece tópicos que descrevem a pintura personalizada de células e linhas
DataGridView , bem como a criação de tipos de célula, coluna e linha derivados.
Ajuste de desempenho no controle DataGridView dos Windows Forms

Fornece tópicos que descrevem como usar o controle com eficiência para evitar
problemas de desempenho ao trabalhar com grandes volumes de dados.
Tratamento de teclado e mouse padrão no controle DataGridView dos Windows Forms

Descreve como os usuários podem interagir com o controle DataGridView por meio de
um teclado e mouse.
Diferenças entre os controles DataGridView e DataGrid dos Windows Forms

Descreve como o DataGridView controle é aprimorado e substitui o DataGrid controle .
Consulte também Usando o designer com o controle DataGridView do Windows Forms.

Referência
DataGridView
Fornece documentação de referência para o DataGridView controle .
BindingSource
Fornece documentação de referência para o BindingSource componente. O
DataGridView controle e o componente BindingSource foram projetados para trabalhar
em conjunto.
Confira também
Usando o designer com o controle
DataGridView dos Windows Forms
Artigo • 02/06/2023
O Visual Studio dá suporte de designer ao controle DataGridView que permite que você
execute várias tarefas de instalação sem escrever código. Essas tarefas incluem associar
o controle a uma fonte de dados, modificando as colunas usadas para exibir dados e
ajustando a aparência e o comportamento básico do controle.
Nesta seção
Como: Adicionar e remover colunas no controle DataGridView do Windows Forms
usando o designer
Descreve como usar as caixas de diálogo Adicionar colunas e Editar colunas para
popular e modificar a coleção de colunas.
Como associar dados ao controle DataGridView dos Windows Forms usando o designer
Descreve como usar a opção Escolher fonte de dados na smart tag do controle para se
conectar aos dados.
Como: Alterar a ordem de colunas no controle DataGridView do Windows Forms

usando o designer
Descreve como usar a caixa de diálogo Editar colunas para reorganizar as colunas.
Como alterar o tipo de uma coluna DataGridView dos Windows Forms usando o
designer
Descreve como usar a caixa de diálogo Editar colunas para alterar os tipos de coluna.
Como: Habilitar a reorganização da coluna no controle DataGridView do Windows

Forms usando o designer
Descreve como usar smart tag do controle para permitir aos usuários reorganizar
colunas.
Como: Congelar colunas no controle DataGridView do Windows Forms usando o

designer
Descreve como usar a caixa de diálogo Editar colunas para impedir a rolagem de
colunas específicas.
Como: Ocultar colunas no controle DataGridView do Windows Forms usando o designer

Descreve como usar a caixa de diálogo Editar colunas para ocultar colunas específicas.
Como: Deixar as colunas somente leitura no controle DataGridView do Windows Forms
usando o designer
Descreve como usar a caixa de diálogo Editar colunas para impedir que usuários editem
valores em colunas específicas.
Como: Evitar a adição e a exclusão de linha no controle DataGridView do Windows

Descreve como usar smart tag do controle para impedir que os usuários adicionem ou
excluam linhas.
Como: Definir estilos de linhas alternados para o controle DataGridView do Windows

Descreve como usar a caixa de diálogo Construtor CellStyle para criar uma aparência
semelhante à razão no controle.
Como definir estilos de célula e formatos de dados padrão para o controle

DataGridView dos Windows Forms usando o designer
Descreve como usar a caixa de diálogo Construtor CellStyle para configurar a aparência
básica e formatos de exibição de dados para o controle.
Referência
DataGridView
Fornece a documentação de referência para o DataGridView controle.
Confira também
Como: Adicionar e remover colunas no
controle DataGridView do Windows
Artigo • 02/06/2023
O controle Windows Forms DataGridView deve conter colunas para exibir dados. Para
preencher o controle manualmente é preciso adicionar as colunas. De forma alternativa,
é possível associar o controle a uma fonte de dados, que gera e preenche as colunas
automaticamente. Se a fonte de dados contém mais colunas do que se deseja exibir,
remova as colunas indesejadas.
Os procedimentos a seguir exigem um projeto de aplicativo do Windows com um

formulário que contém um DataGridView controle. Para obter informações sobre como
como adicionar controles a Windows Forms.
Para adicionar uma coluna usando o designer

1. Clique no glifo de ações do designer ( ) no canto superior direito do DataGridView
controle e selecione Adicionar Coluna.
2. Na caixa de diálogo Adicionar Coluna, escolha a opção Coluna de Associação de

Dados e selecione uma coluna da fonte de dados, ou escolha a opção Coluna Não
Associada e defina a coluna usando os campos fornecidos.
3. Clique no botão Adicionar para adicionar a coluna, fazendo com que ela apareça
no designer se as colunas existentes não preencherem ainda o controle da área de
exibição.
７ Observação
É possível modificar propriedades da coluna na caixa de diálogo Editar

Colunas, que pode ser acessada na marca inteligente do controle.
Para remover uma coluna usando o designer

1. Escolha Editar Colunas na marca inteligente do controle.
2. Selecione uma coluna na lista Colunas Selecionadas.
3. Clique no botão Remover para excluir a coluna, fazendo com que ela desapareça
do designer.
Confira também
DataGridView
Como criar um projeto de aplicativo Windows Forms
Como: Associar dados ao controle
DataGridView do Windows Forms
usando o designer
Artigo • 02/06/2023
Você pode usar o designer para conectar um DataGridView controle a fontes de dados
de várias variedades diferentes, incluindo bancos de dados, objetos de negócios ou
serviços Web. Quando você associa o controle a uma fonte de dados usando o designer,
o controle é automaticamente associado a um BindingSource componente que
representa a fonte de dados. Além disso, as colunas são automaticamente geradas no
controle para coincidir com as informações de esquema fornecidas pela fonte de dados.
Depois que as colunas tiverem sido geradas, você poderá modificá-las para atender às
suas necessidades. Por exemplo, você pode remover ou ocultar colunas que você não
queira exibir, pode reorganizar as colunas ou pode modificar os tipos de coluna. Para
obter mais informações sobre como modificar colunas, consulte os tópicos listados na
seção Consulte também.
Você também pode associar vários controles DataGridView a tabelas relacionadas para
criar relações mestre/detalhe. Nessa configuração, um controle exibe uma tabela pai e
outro controle exibe somente as linhas de uma tabela filho que estão relacionadas à
linha atual na tabela pai. Para obter mais informações, consulte Como exibir dados
relacionados em um aplicativo dos Windows Forms.

formulário que contém um DataGridView controle ou dois controles para uma relação
mestre/detalhe. Para obter informações sobre como iniciar esse projeto, consulte Como
criar um projeto de aplicativo Windows Forms e como adicionar controles a Windows
Forms.
Para associar o controle a uma fonte de dados

controle.
2. Clique na seta suspensa para a opção Escolher Fonte de Dados.
3. Se seu projeto ainda não tiver uma fonte de dados, clique em Adicionar Fonte de
Dados do Projeto e siga as etapas indicadas pelo assistente.
Para obter mais informações, consulte Assistente de Configuração da Fonte de
Dados. A nova fonte de dados aparecerá na janela suspensa Escolher Fonte de
Dados. Se a nova fonte de dados contiver apenas um membro, como uma única
tabela de banco de dados, o controle será associado automaticamente a esse
membro. Caso contrário, prossiga para a próxima etapa.
4. Expanda os nós Outras Fontes de Dados e Fontes de Dados do Projeto se eles

ainda não tiverem sido expandidos e, em seguida, selecione a fonte de dados à
qual associar o controle.
5. Se a fonte de dados contiver mais de um membro, como se você tivesse criado

uma System.Data.DataSet que contém várias tabelas, expanda a fonte de dados e
selecione o membro específico ao qual associar.
6. Para criar uma relação mestre/detalhe, na janela suspensa Escolher Fonte de

Dados para um segundo DataGridView controle, expanda o BindingSource criado
para a tabela pai e selecione a tabela filho relacionada na lista mostrada.
７ Observação
Se o projeto já tiver uma fonte de dados, você também poderá usar a janela
Fontes de Dados para criar um formulário de dados. Para obter mais
informações, consulte Janela de Fontes de Dados.
Confira também
DataGridView
BindingSource
DataGridView.DataMember
DataGridView.DataSource
Como conectar-se a dados em um banco de dados
usando o designer
usando o designer
Como alterar o tipo de uma coluna DataGridView dos Windows Forms usando o
designer
designer
Como: Ocultar colunas no controle DataGridView do Windows Forms usando o
designer
Como: Deixar as colunas somente leitura no controle DataGridView do Windows
Janela Fontes de Dados
Como exibir dados relacionados em um Aplicativo do Windows Forms
Como: Alterar a ordem de colunas no
Artigo • 02/06/2023
Quando você associa um controle de Windows Forms DataGridView a uma fonte de

dados, a ordem de exibição das colunas geradas automaticamente é ditada pela fonte
de dados. Se essa ordem não for a que preferir, você poderá alterar a ordem das
colunas usando o designer. Talvez deseje adicionar colunas não associadas ao controle e
alterar a ordem de exibição. Para obter informações sobre como alterar a ordem das
colunas programaticamente, consulte Como alterar a ordem de colunas no controle
DataGridView dos Windows Forms.

Para alterar a ordem das colunas usando o

designer
controle e selecione Editar Colunas.
3. Clique na seta para cima ou para baixo à direita da lista Colunas selecionadas até
que a coluna selecionada esteja na posição desejada.
Confira também
DataGridView
usando o designer
Como: Alterar o tipo de uma coluna
usando o designer
Artigo • 02/06/2023
Às vezes, você deseja alterar o tipo de uma coluna que já foi adicionada a um controle
Windows FormsDataGridView. Por exemplo, talvez deseje modificar os tipos de algumas
das colunas que são geradas automaticamente quando você associa o controle a uma
fonte de dados. Isso é útil quando a tabela exibida contém colunas com chaves
estrangeiras para linhas em uma tabela relacionada. Nesse caso, talvez você queira
substituir as colunas da caixa de texto que exibem essas chaves estrangeiras com
colunas de caixa de combinação que exibem os valores mais significativos da tabela
relacionada.

Para alterar o tipo de uma coluna usando o designer

3. Na grade Propriedades da coluna grade, defina a propriedade ColumnType como o

novo tipo de coluna.
７ Observação
A propriedade ColumnType é uma propriedade somente em tempo de design

que indica a classe que representa o tipo de coluna. Não é uma propriedade
real definida em uma classe de coluna.
Confira também
DataGridView
DataGridViewColumn
Como: Habilitar a reorganização da
coluna no controle DataGridView do
Windows Forms usando o designer
Artigo • 02/06/2023
Ao exibir dados exibidos em um controle Windows FormsDataGridView, os usuários às

vezes desejam comparar os valores em colunas específicas. Isso pode ser inconveniente
se as colunas estiverem amplamente separadas no controle, especialmente se os
usuários precisarem rolar horizontalmente para ver todas as colunas nas quais estão
interessados. Você pode facilitar a tarefa de comparar valores de coluna, permitindo que
os usuários reordenem as colunas. Quando você habilita a reordenação de coluna, os
usuários podem mover uma coluna para uma nova posição arrastando o cabeçalho da
coluna com o mouse.

formulário contendo um DataGridView controle. Para obter informações sobre como
Para habilitar a reordenação de coluna

Clique no glifo de ações do designer ( ) no canto superior direito do DataGridView
controle e selecione Habilitar Reordenação de Coluna.
Confira também
DataGridView
DataGridView.AllowUserToOrderColumns
designer
Como: Congelar colunas no controle
usando o designer
Artigo • 02/06/2023
Quando os usuários exibem dados exibidos em um controle Windows

FormsDataGridView, às vezes, eles precisam se referir a uma única coluna ou conjunto
de colunas com frequência. Por exemplo, quando você exibe uma tabela de informações
do cliente que contém várias colunas, é útil exibir o nome do cliente em todos os
momentos, enquanto permite que outras colunas rolem para fora da região visível.
Para obter esse comportamento, você pode congelar colunas no controle. Quando você
congela uma coluna, todas as colunas à esquerda (ou à direita em scripts de idioma da
direita para esquerda) são congeladas também. Colunas congeladas permanecerão no
local enquanto todas as outras colunas podem rolar. Se a reordenação de coluna estiver
habilitada, as colunas congeladas serão tratadas como um grupo diferente das colunas
não congeladas. Os usuários podem reposicionar colunas em um dos grupos, mas não
poderão mover uma coluna de um grupo para outro.

formulário contendo um DataGridView controle. Para obter informações sobre como
Para congelar uma coluna usando o designer

3. Na grade Propriedades da Coluna , defina a Frozen propriedade como true .
７ Observação
Você também pode congelar uma coluna ao adicioná-la selecionando a caixa

de seleção Congelada na caixa de diálogo Adicionar Coluna.
Confira também
DataGridView
DataGridViewColumn.Frozen
usando o designer
Como exibir texto da direita para a esquerda nos Windows Forms para
globalização
Como: Ocultar colunas no controle
usando o designer
Artigo • 02/06/2023
Às vezes, você deseja exibir apenas algumas das colunas disponíveis em um controle
Windows FormsDataGridView. Por exemplo, talvez você queira mostrar uma coluna de
salário de funcionários para usuários com credenciais de gerenciamento enquanto a
oculta de outros usuários. Como alternativa, talvez você queira associar o controle a
uma fonte de dados que contém várias colunas, sendo que você deseja exibir apenas
algumas delas. Nesse caso, você normalmente removerá as colunas que não está
interessado em exibir em vez de ocultá-las. Para saber mais, veja Como adicionar e
remover colunas no controle DataGridView dos Windows Forms usando o designer.

Para ocultar uma coluna usando o designer

3. Na grade Propriedades da Coluna , defina a Visible propriedade como false .
７ Observação
Você também pode ocultar uma coluna ao adicioná-la desmarcando a caixa

de seleção Visível na caixa de diálogo Adicionar Coluna.
Confira também
DataGridView
DataGridViewColumn.Visible
usando o designer
Como: Deixar as colunas somente
leitura no controle DataGridView do
Artigo • 02/06/2023
Por padrão, os usuários podem modificar o texto e os dados numéricos exibidos no

controle Windows FormsDataGridView. Se quiser exibir os dados que não são
destinados para modificação, você deverá tornar somente leitura as colunas que contêm
os dados. Para obter informações sobre como tornar o controle totalmente somente
leitura, veja Como evitar a adição e a exclusão de linha no controle no DataGridView dos
Windows Forms usando o Designer.

Para tornar a coluna somente leitura usando o

designer
3. Na grade Propriedades da Coluna , defina a ReadOnly propriedade como true .
７ Observação
Você também pode tornar uma coluna somente leitura ao adicioná-la

marcando a caixa de seleção Somente Leitura na caixa de diálogo Adicionar
Coluna.
Confira também
DataGridView
DataGridViewColumn.ReadOnly
usando o designer
Como: Evitar a adição e a exclusão de
linha no controle DataGridView do
Artigo • 02/06/2023
Às vezes, você deseja impedir que os usuários insiram novas linhas de dados ou
excluam linhas existentes em seu DataGridView controle. Novas linhas são inseridas na
linha especial para novos registros na parte inferior do controle. Quando você
desabilitar a adição de linha, a linha para novos registros não será exibida. Em seguida,
você pode deixar o controle totalmente somente leitura desabilitando a exclusão de
linha e a edição de célula.

Para evitar a exclusão e adição de linha

Clique no glifo de ações do designer ( ) no canto superior direito do DataGridView
controle e desmarque as caixas de seleção Habilitar Adicionar e Habilitar Exclusão
.
７ Observação
Para tornar o controle somente leitura inteiramente, desmarque também a

caixa de seleção Habilitar Edição.
Confira também
DataGridView
DataGridView.AllowUserToAddRows
Como: Definir estilos de linhas
alternados para o controle
usando o designer
Artigo • 02/06/2023
Dados tabulares geralmente são apresentados em um formato contábil no qual linhas

alternativas têm cores de tela de fundo diferente. Esse formato facilita para os usuários
saber quais células estão em cada linha, especialmente com tabelas largas com muitas
colunas.
Com o DataGridView controle, você pode especificar informações de estilo completas

para linhas alternadas. Você pode usar as características de estilo como fonte e cor de
primeiro plano, além da cor da tela de fundo, para diferenciar as linhas alternadas. Para
obter mais informações, consulte Estilos de célula no controle DataGridView dos
Windows Forms.

Defina estilos para linhas alternadas

1. Selecione o DataGridView controle no designer.
2. Na janela Propriedades, clique no botão reticências ( ) ao lado da

AlternatingRowsDefaultCellStyle propriedade.
3. Na caixa de diálogo Construtor CellStyle, defina o estilo configurando as

propriedades e use o painel Visualização para confirmar suas escolhas. Os estilos
que você especifica são usados para todas as outras linhas exibidas no controle,
começando com a segunda.
4. Para definir estilos para as linhas restantes, repita as etapas 2 e 3 usando a

RowsDefaultCellStyle propriedade.
７ Observação
Células são exibidas usando estilos herdados de várias propriedades. Para
obter mais informações sobre herança de estilo, consulte Estilos de célula no
controle DataGridView dos Windows Forms.
Confira também
DataGridView
Estilos de célula no controle DataGridView dos Windows Forms
Usando o designer com o controle DataGridView dos Windows Forms
Como: Definir estilos de célula padrão e
formatos de dados para o controle
usando o designer
Artigo • 02/06/2023
O DataGridView controle permite especificar estilos de célula padrão e formatos de

dados de célula para todo o controle, para colunas específicas, cabeçalhos de linha e
coluna e para linhas alternadas para criar um efeito razão. Os estilos padrão definidos
para todo o controle serão substituídos por estilos padrão definidos para colunas e
linhas alternadas. Além disso, os estilos definidos no código para as linhas e células
individuais substituem os estilos padrão.
Para obter mais informações sobre estilos de célula, consulte Estilos de Célula no
Controle DataGridView dos Windows Forms. Para definir estilos para linhas alternadas,
consulte Como Definir Estilos de Linha Alternada para o Controle DataGridView dos
Windows Forms Usando o Designer.
Você também pode definir estilos usando a RowTemplate propriedade para afetar todas
as linhas que serão adicionadas ao controle. Para obter mais informações sobre o
modelo de linha, consulte Como Usar o Modelo de Linha para Personalizar Linhas no
Controle DataGridView dos Windows Forms.
Os procedimentos a seguir exigem um projeto de aplicativo do Windows com um

Definir estilos padrão para todas as células no controle

1. Selecione o DataGridView controle no designer.
2. Na janela Propriedades, clique no botão de reticências ( ) ao lado da

DefaultCellStylepropriedade , ColumnHeadersDefaultCellStyleou
RowHeadersDefaultCellStyle . A caixa de diálogo Criador de CellStyle aparecerá.
3. Defina o estilo configurando as propriedades e use o painel Visualização para

confirmas suas escolhas.
７ Observação
Se os estilos visuais estiverem habilitados, os cabeçalhos de linha e coluna (exceto

o TopLeftHeaderCell) serão automaticamente estilizados pelo tema atual,
substituindo os valores de propriedade e RowHeadersDefaultCellStyle
linhaColumnHeadersDefaultCellStyle.
Você pode definir estilos de célula para vários controles selecionados

DataGridView usando o designer, mas somente se eles tiverem valores idênticos
para a propriedade de estilo de célula que você deseja modificar. Caso algum estilo
de célula seja diferente nessa propriedade, a janela Propriedades da caixa de
diálogo Criador de CellStyle ficará em branco.
Definir estilos padrão para células em colunas individuais

1. Clique com o botão direito do DataGridView mouse no controle no designer e
escolha Editar Colunas.
3. Na grade Propriedades da Coluna, clique no botão reticências ( ) ao lado da

DefaultCellStyle propriedade. A caixa de diálogo Criador de CellStyle aparecerá.
4. Defina o estilo configurando as propriedades e use o painel Visualização para

confirmas suas escolhas.
Formatar dados em células

1. Use um dos procedimentos anteriores para exibir uma caixa de diálogo Criador de
CellStyle relacionada a uma propriedade de estilo de célula padrão.
2. Na caixa de diálogo Construtor CellStyle, clique no botão de reticências ( ) ao

lado da Format propriedade. A caixa de diálogo Editar Cadeia de Caracteres será
exibida.
3. Selecione um tipo de formato e, em seguida, modifique os detalhes do tipo (como

o número de casas decimais a serem exibidas), usando a caixa Exemplo para
confirmar suas escolhas.
4. Se você estiver associando o DataGridView controle a uma fonte de dados que

provavelmente conterá valores nulos, preencha a caixa de texto Valor Nulo . Esse
valor é exibido quando o valor da célula é igual a uma referência nula ( Nothing no
Visual Basic) ou DBNull.Value.
Confira também
DataGridView
DataGridViewCellStyle
DataGridView.DefaultCellStyle
DataGridView.RowsDefaultCellStyle
DataGridViewColumn.DefaultCellStyle
DataGridViewCellStyle.Format
Como: Definir estilos de linhas alternados para o controle DataGridView do
(Windows Forms)
Artigo • 02/06/2023
７ Observação

Diferenças entre os controles DataGridView Windows Forms e DataGrid.
Com o DataGridView controle , você pode exibir e editar dados tabular de muitos tipos
diferentes de fontes de dados.
A associação de dados ao DataGridView controle é simples e intuitiva e, em muitos

casos, é tão simples quanto definir a DataSource propriedade. Quando você se vincula a
uma fonte de dados que contém várias listas ou tabelas, DataMember de definir a
propriedade como uma cadeia de caracteres que especifica a lista ou a tabela a ser
vinculada.
O DataGridView controle dá suporte ao modelo de associação de dados Windows

Forms padrão, portanto, ele será vinculado a instâncias de classes descritas na lista a
seguir:
Qualquer classe que implementa a IList interface, incluindo matrizes

unidimensionais.
Qualquer classe que implementa a IListSource interface, como as classes DataTable

e DataSet .
Qualquer classe que implemente a IBindingList interface, como a BindingList<T>

classe .
Qualquer classe que implemente a IBindingListView interface, como a

BindingSource classe .
O DataGridView controle dá suporte à associação de dados às propriedades públicas

dos objetos retornados por essas interfaces ICustomTypeDescriptor ou à coleção de
propriedades retornada por uma interface, se implementada nos objetos retornados.
Normalmente, você vai se vincular a um componente e vincular BindingSource o
componente a BindingSource outra fonte de dados ou populá-lo com objetos de
negócios. O BindingSource componente é a fonte de dados preferencial porque pode
ser vinculado a uma ampla variedade de fontes de dados e pode resolver vários
problemas de associação de dados automaticamente. Para obter mais informações,
consulte Componente BindingSource.
O DataGridView controle também pode ser usado no modo de desaconsução, sem

armazenamento de dados subjacente. Para ver um exemplo de código que usa um
controle DataGridView nãobound, consulte Passo a passo: criando um controle
DataGridView do Unbound Windows Forms.
O DataGridView controle é altamente configurável e extensível e fornece muitas

propriedades, métodos e eventos para personalizar sua aparência e comportamento.
Quando você quiser que seu aplicativo Windows Forms para exibir dados tabular,
DataGridView considere usar o controle antes de outros (por exemplo, DataGrid). Se
você estiver exibindo uma pequena grade de valores somente leitura ou se estiver
permitindo que um usuário edite uma tabela com milhões de registros, DataGridView o
controle fornecerá uma solução prontamente programável e com eficiência de memória.
Nesta seção
Resumo de tecnologia do controle DataGridView
Resume os DataGridView conceitos de controle e o uso de classes relacionadas.
Arquitetura de controle DataGridView

Descreve a arquitetura do controle, explicando DataGridView sua hierarquia de tipos e
estrutura de herança.
Cenários do controle DataGridView

Descreve os cenários mais comuns em que os controles DataGridView são usados.
Diretório de código do controle DataGridView

Fornece links para exemplos de código na documentação para várias DataGridView
tarefas. Esses exemplos são categorizados por tipo de tarefa.
Discute os tipos de coluna no controle Windows Forms DataGridView usado para exibir
informações e permitir que os usuários modifiquem ou adicionem informações.

DataGridView, bem como a criação de tipos de célula, coluna e linha derivados.

Fornece tópicos que descrevem como usar o controle com eficiência para evitar
problemas de desempenho ao trabalhar com grandes volumes de dados.
Confira também
DataGridView
BindingSource
Funcionalidade padrão no controle DataGridView dos Windows Forms
Tratamento de teclado e mouse padrão no controle DataGridView dos Windows
Forms
Resumo de tecnologia do controle
DataGridView (Windows Forms)
Artigo • 02/06/2023
Este tópico resume as informações sobre o controle DataGridView e as classes que dão
suporte ao seu uso.
Exibir dados em um formato tabular é uma tarefa que provavelmente será executada
com frequência. O controle DataGridView foi projetado para ser uma solução completa
para apresentar dados em uma grade.
Palavras-chave
DataGridView, BindingSource, tabela, célula, vinculação de dados, modo virtual
Namespaces
System.Windows.Forms
System.Data
Tecnologias relacionadas
BindingSource
Tela de fundo
Designers de interface do usuário com frequência consideram necessário exibir dados
tabulares para os usuários. O .NET Framework fornece várias maneiras de mostrar dados
em uma tabela ou grade. O controle DataGridView representa a mais recente evolução
dessa tecnologia para aplicativos dos Windows Forms.
O controle DataGridView pode exibir linhas de dados de um armazenamento de dados.

Há suporte para muitos tipos de armazenamentos de dados. O armazenamento de
dados pode conter dados simples e não tipados, como uma matriz unidimensional, ou
pode conter dados tipados, como um DataSet. Para obter mais informações, consulte
Como associar dados ao controle DataGridView dos Windows Forms.
O controle de DataGridView fornece uma maneira poderosa e flexível para exibir dados
em um formato de tabela. Você pode usar o controle para mostrar exibições editáveis
ou somente leitura de conjuntos de dados pequenos a muito grandes.
Você pode estender o controle DataGridView de várias maneiras para integrar

comportamento personalizado em seus aplicativos. Por exemplo, você pode especificar
seus próprios algoritmos de classificação com programação, podendo também criar
seus próprios tipos de células. É possível personalizar facilmente a aparência do controle
DataGridView escolhendo dentre várias propriedades. Muitos tipos de armazenamentos
de dados podem ser usados como uma fonte de dados ou o controle DataGridView
pode operar sem nenhuma fonte de dados associada.
Implementando classes de DataGridView

Há várias maneiras de aproveitar os recursos de extensibilidade do controle
DataGridView . Você pode personalizar vários aspectos do controle por meio de
propriedades e eventos, mas algumas personalizações requerem a criação de novas

classes derivadas de classes DataGridView existentes.
Em geral, as classes base mais usadas são DataGridViewCell e DataGridViewColumn . Você

pode derivar sua própria classe de célula de DataGridViewCell ou qualquer uma das
suas classes filho. Embora você possa adicionar qualquer tipo de célula a qualquer
coluna, normalmente também derivará uma classe de coluna complementar da
DataGridViewColumn que hospeda as células do seu tipo de célula personalizado por
padrão.
Você pode implementar a interface IDataGridViewEditingCell em sua classe de célula

derivada para criar um tipo de célula que tenha a funcionalidade de edição, mas que
não hospede um controle no modo de edição. Para criar um controle que você pode
hospedar em uma célula no modo de edição, você pode implementar a
IDataGridViewEditingControl interface em uma classe derivada de Control.
Para obter mais informações, consulte Como personalizar células e colunas no controle
DataGridView dos Windows Forms estendendo o comportamento e aparência e Como
hospedar controles em células DataGridView dos Windows Forms.
Visão geral das classes DataGridView

Área de Tecnologia Elementos de classes/interfaces/configuração
Associação de dados BindingSource
Apresentação de dados DataGridView
DataGridViewCell e classes derivadas
DataGridViewRow e classes derivadas
DataGridViewColumn e classes derivadas
DataGridView Extensibilidade DataGridViewCell e classes derivadas
DataGridViewColumn e classes derivadas
IDataGridViewEditingCell
IDataGridViewEditingControl
What's New
O DataGridView controle foi projetado para ser uma solução completa para exibir dados
tabulares com Windows Forms. Você deve considerar o uso do DataGridView controle
antes de outras soluções, como DataGrid, quando estiver criando um novo aplicativo.
Para obter mais informações, consulte Diferenças entre os controles Windows Forms
DataGridView e DataGrid.
O DataGridView controle pode funcionar em conjunto com o BindingSource

componente. Esse componente é projetado para ser a fonte de dados principal de um
formulário. Ele pode gerenciar a interação entre um DataGridView controle e sua fonte
de dados, independentemente do tipo de fonte de dados.
Confira também
Protegendo informações de conexão
Arquitetura do controle DataGridView
(Windows Forms)
Artigo • 02/06/2023
O DataGridView controle e suas classes relacionadas foram projetados para ser um

sistema flexível e extensível para exibir e editar dados tabulares. Todas essas classes
estão contidas no System.Windows.Forms namespace e são todas nomeadas com o
prefixo "DataGridView".
Elementos de arquitetura
As classes complementares primárias DataGridView derivam de DataGridViewElement. O
modelo de objeto a seguir ilustra a hierarquia de DataGridViewElement herança.
A DataGridViewElement classe fornece uma referência ao controle pai DataGridView e

tem uma State propriedade, que contém um valor que representa uma combinação de
valores da DataGridViewElementStates enumeração.
As seções a seguir descrevem as DataGridView classes complementares com mais

detalhes.
DataGridViewElementStates
A enumeração DataGridViewElementStates contém os seguintes valores:
None
Frozen
ReadOnly
Resizable
ResizableSet
Selected
Visible
Os valores dessa enumeração podem ser combinados com os operadores lógicos bit a
bit, de modo que a State propriedade possa expressar mais de um estado ao mesmo
tempo. Por exemplo, um DataGridViewElement pode ser simultaneamente Frozen,
Selectede Visible.
Células e faixas
O DataGridView controle é composto por dois tipos fundamentais de objetos: células e
bandas. Todas as células derivam da DataGridViewCell classe base. Os dois tipos de
bandas e DataGridViewColumnDataGridViewRowambos derivam da DataGridViewBand
classe base.
O DataGridView controle interopera com várias classes, mas as mais comumente

encontradas são DataGridViewCell, DataGridViewColumne DataGridViewRow.
DataGridViewCell
A célula é a unidade fundamental de interação para o DataGridView. A exibição é
centralizada das células e entrada de dados geralmente é realizada por meio das células.
Você pode acessar células usando a Cells coleção da DataGridViewRow classe e acessar
as células selecionadas usando a SelectedCells coleção do DataGridView controle. O
modelo de objeto a seguir ilustra esse uso e mostra a hierarquia de DataGridViewCell
herança.
O DataGridViewCell tipo é uma classe base abstrata, da qual todos os tipos de célula
derivam. DataGridViewCelle seus tipos derivados não são controles Windows Forms,
mas alguns controles de Windows Forms de host. Qualquer funcionalidade de edição
com suporte de uma célula normalmente é manipulada por um controle hospedado.
DataGridViewCellos objetos não controlam seus próprios recursos de aparência e

pintura da mesma forma que Windows Forms controles. Em vez disso, o DataGridView
responsável pela aparência de seus DataGridViewCell objetos. Você pode afetar
significativamente a aparência e o comportamento das células interagindo com as
propriedades e eventos DataGridView do controle. Quando você tem requisitos
especiais para personalizações que estão além dos recursos do DataGridView controle,
você pode implementar sua própria classe derivada ou de DataGridViewCell uma de
suas classes filho.
A lista a seguir mostra as classes derivadas de DataGridViewCell:
DataGridViewTextBoxCell
DataGridViewButtonCell
DataGridViewLinkCell
DataGridViewCheckBoxCell
DataGridViewComboBoxCell
DataGridViewImageCell
DataGridViewHeaderCell
DataGridViewRowHeaderCell
DataGridViewColumnHeaderCell
DataGridViewTopLeftHeaderCell
Seus tipos de célula personalizados
DataGridViewColumn
O esquema do armazenamento de DataGridView dados anexado do controle é expresso
nas DataGridView colunas do controle. Você pode acessar as DataGridView colunas do
controle usando a Columns coleção. Você pode acessar as colunas selecionadas usando
a SelectedColumns coleção. O modelo de objeto a seguir ilustra esse uso e mostra a
hierarquia de DataGridViewColumn herança.
Alguns dos principais tipos de células têm tipos de colunas correspondentes. Eles são
derivados da DataGridViewColumn classe base.
A lista a seguir mostra as classes derivadas de DataGridViewColumn:
DataGridViewButtonColumn
DataGridViewCheckBoxColumn
DataGridViewComboBoxColumn
DataGridViewImageColumn
DataGridViewTextBoxColumn
DataGridViewLinkColumn
Seus tipos de colunas personalizadas
Controles de edição de DataGridView

Células que dão suporte a recursos de edição avançados normalmente usam um
controle hospedado que é derivado de um controle dos Windows Forms. Esses
controles também implementam a IDataGridViewEditingControl interface. O modelo de
objeto a seguir ilustra o uso desses controles.
Os seguintes controles de edição são fornecidos com o DataGridView controle:
DataGridViewComboBoxEditingControl
DataGridViewTextBoxEditingControl
Para obter informações sobre como criar seus próprios controles de edição, consulte
Como hospedar controles em células DataGridView dos Windows Forms.
A tabela a seguir ilustra o relacionamento entre tipos de células, tipos de colunas e

controles de edição.
Tipo de célula Controle hospedado Tipo de coluna
DataGridViewButtonCell n/a DataGridViewButtonColumn
DataGridViewCheckBoxCell n/a DataGridViewCheckBoxColumn
DataGridViewComboBoxCell DataGridViewComboBoxEditingControl DataGridViewComboBoxColumn

Tipo de célula Controle hospedado Tipo de coluna
DataGridViewImageCell n/d DataGridViewImageColumn
DataGridViewLinkCell n/d DataGridViewLinkColumn
DataGridViewTextBoxCell DataGridViewTextBoxEditingControl DataGridViewTextBoxColumn
DataGridViewRow
A DataGridViewRow classe exibe os campos de dados de um registro do
armazenamento de dados ao qual o DataGridView controle está anexado. Você pode
acessar as DataGridView linhas do controle usando a Rows coleção. Você pode acessar
as linhas selecionadas usando a SelectedRows coleção. O modelo de objeto a seguir
ilustra esse uso e mostra a hierarquia de DataGridViewRow herança.
Você pode derivar seus próprios tipos da DataGridViewRow classe, embora isso
normalmente não seja necessário. O DataGridView controle tem vários eventos e
propriedades relacionados a linhas para personalizar o comportamento de seus
DataGridViewRow objetos.
Se você habilitar a DataGridView propriedade do AllowUserToAddRows controle, uma

linha especial para adicionar novas linhas será exibida como a última linha. Essa linha faz
parte da Rows coleção, mas tem uma funcionalidade especial que pode exigir sua
atenção. Para obter mais informações, consulte Usando a linha para novos registros no
Confira também
Usando a linha para novos registros no controle DataGridView dos Windows
Forms
Cenários do controle DataGridView
(Windows Forms)
Artigo • 02/06/2023
Com o DataGridView controle, você pode exibir dados tabulares de uma variedade de
fontes de dados. Para usos simples, você pode preencher manualmente e DataGridView
manipular os dados diretamente por meio do controle. Normalmente, no entanto, você
armazenará seus dados em uma fonte de dados externa e associará o controle a ele por
meio de um BindingSource componente.
Este tópico descreve alguns dos cenários comuns que envolvem o DataGridView
controle.
Cenário 1: Exibição de pequenas quantidades

de dados
Você não precisa armazenar seus dados em uma fonte de dados externa para exibi-los
no DataGridView controle. Se estiver trabalhando com uma pequena quantidade de
dados, você poderá preencher o controle por conta própria e manipular os dados por
meio do controle. Isso é chamado de modo não associado. Para obter mais informações,
consulte Como criar um controle DataGridView não associado dos Windows Forms.
Principais aspectos do cenário

No modo não associado, você preenche o controle manualmente.
O modo não associado é especialmente adequado para pequenas quantidades de

dados somente leitura.
O modo não associado também é adequado para tabelas preenchidas

escassamente ou semelhantes a planilhas.
Cenário 2: Exibindo e atualizando dados

armazenados em uma fonte de dados externa
Você pode usar o controle como interface do DataGridView usuário (interface do
usuário) por meio do qual os usuários podem acessar dados mantidos em uma fonte de
dados, como uma tabela de banco de dados ou uma coleção de objetos de negócios.
Para obter mais informações, consulte Como associar dados ao controle DataGridView
dos Windows Forms.

O modo associado lhe permite se conectar a uma fonte de dados, gerar colunas
automaticamente de acordo com as propriedades da fonte de dados ou colunas
de banco de dados e preencher automaticamente o controle.
O modo associado é adequado para quando há um alto nível de interação do

usuário com os dados. Os dados podem ser formatados para exibição e dados
especificados pelo usuário podem ser analisados para o formato esperado pela
fonte de dados. Erros de formatação de entrada de dados e erros de restrição de
banco de dados podem ser detectados para que os usuários possam ser avisados
e células com erros possam ser corrigidas.
Funcionalidades adicionais, como a classificação, o congelamento e a

reorganização de colunas permitem que os usuários exibam os dados da maneira
que for mais conveniente para seu fluxo de trabalho.
O suporte para a área de transferência permite que os usuários copiem dados de

seu aplicativo para outros aplicativos.
Cenário 3: Dados avançados

Se tiver necessidades especiais que o modelo de vinculação de dados padrão não
atende, você pode gerenciar a interação entre o controle e seus dados com a
implementação do modo virtual. Implementar o modo virtual significa implementar um
ou mais manipuladores de eventos que permitem que o controle solicite informações
sobre as células conforme essas informações forem necessárias.
Por exemplo, caso trabalhe com grandes quantidades de dados, você talvez queira
implementar o modo virtual para garantir a eficiência máxima. O modo virtual também
é útil para manter os valores das colunas não associadas que você exibe em conjunto
com colunas recuperadas de outra fonte de dados.
Para obter mais informações sobre o modo virtual, consulte Instruções passo a passo:
implementando o modo virtual no controle DataGridView dos Windows Forms.

O modo virtual é adequado para exibir grandes quantidades de dados quando
você precisar ajustar o desempenho.
Cenário 4: Redimensionar automaticamente

linhas e colunas
Quando exibe dados que são atualizados regularmente, você pode redimensionar
automaticamente as linhas e colunas para garantir que todo o conteúdo esteja visível. O
DataGridView controle fornece várias opções que permitem habilitar ou desabilitar o
redimensionamento manual, redimensionar programaticamente em horários específicos
ou redimensionar automaticamente sempre que o conteúdo for alterado. Para obter
mais informações, consulte Sizing Options in the Windows Forms DataGridView Control
(Opções de dimensionamento no controle DataGridView dos Windows Forms).

O redimensionamento manual permite que os usuários ajustem as larguras e as
alturas das células.
O redimensionamento automático permite que você mantenha os tamanhos das

células, de modo que o conteúdo da célula nunca seja recortado.
O redimensionando programático permite redimensionar células em momentos

específicos para evitar a degradação do desempenho decorrente do
redimensionamento automático contínuo.
Cenário 5: Personalização simples

O DataGridView controle fornece muitas maneiras de alterar sua aparência e
comportamento básicos. Para obter mais informações, consulte Estilos de célula no

DataGridViewCellStyle os objetos permitem fornecer informações de cor, fonte,
formatação e posicionamento em vários níveis e para elementos individuais do
controle.
Os estilos das células podem ser dispostos em camadas e compartilhados por

vários elementos, permitindo que você reutilize o código.
Cenário 6: Personalização avançada
O DataGridView controle fornece muitas maneiras de personalizar sua aparência e
comportamento.

Você pode fornecer seu próprio código de pintura da célula. Para obter mais
informações, consulte Como personalizar a aparência de células no controle
Você pode fornecer sua própria pintura de linhas. Isso é útil, por exemplo, para
criar linhas com conteúdo que se estende por várias colunas. Para obter mais
informações, consulte Como personalizar a aparência de linhas no controle
Você pode implementar suas próprias classes de célula e de coluna para

personalizar a aparência da célula. Para obter mais informações, consulte Como
personalizar células e colunas no controle DataGridView dos Windows Forms
estendendo o comportamento e a aparência.
Você pode implementar suas próprias classes de célula e de coluna para hospedar
controles diferentes daqueles fornecidos pelos tipos de coluna internos. Para obter
mais informações, consulte Como hospedar controles em células DataGridView
dos Windows Forms.
Confira também
DataGridView
Diretório de código do controle
DataGridView (Windows Forms)
Artigo • 02/06/2023
Este tópico fornece links para DataGridViewexemplos de código relacionados

disponíveis na documentação.
７ Observação
Um link sempre pula para a parte superior do tópico no qual o exemplo de código
é encontrado.
Exemplos adicionais estão disponíveis na documentação de referência da biblioteca de

classes. Para obter uma lista das classes principais e interfaces associadas DataGridView
ao controle, consulte a tabela no Resumo da Tecnologia de Controle DataGridView.
CodeList
Exemplos de dados não associados

Como: Adicionar uma coluna não associada a um controle DataGridView do
Windows Forms associado a dados
Como: Criar um controle não associado DataGridView do Windows Forms
Passo a passo: Criar um controle não associado DataGridView do Windows Forms
Exemplos de vinculação de dados

Como associar dados ao controle DataGridView do Windows Forms
Como: Gerar automaticamente colunas em um controle DataGridView associado a

dados do Windows Forms
Como: Remover colunas geradas automaticamente de um controle DataGridView

do Windows Forms
Como associar objetos a controles DataGridView dos Windows Forms

Como acessar objetos associados às linhas de DataGridView dos Windows Forms
Como: Criar um formulário mestre/de detalhes usando dois controles

Instruções passo a passo: criando um formulário mestre/detalhes usando dois

controles DataGridView do Windows Forms
Exemplos de formatação de dados

Como formatar dados no controle DataGridView dos Windows Forms
Como personalizar a formatação de dados no controle DataGridView dos Windows

Forms
Exemplos de validação de dados

Como: Validar dados no controle DataGridView do Windows Forms
Passo a passo: validando dados no controle DataGridView dos Windows Forms
Como: Identificar Erros que Ocorrem Durante a Entrada de Dados no Controle

Passo a passo: Identificando Erros que Ocorrem Durante a Entrada de Dados no

Controle DataGridView do Windows Forms
Exemplos de personalização de aparência

Como: Alterar a borda e os estilos da linha de grade no tempo de execução no
controle DataGridView do Windows Forms
Como definir estilos de fonte e cor no controle DataGridView do Windows Forms
Como: Definir estilos de célula padrão para o controle DataGridView do Windows

Forms
Como: Usar o modelo da linha para personalizar linhas no controle DataGridView

do Windows Forms
Como: Definir estilos de linha alternados para o controle DataGridView do

Windows Forms
Exemplos de personalização de
comportamento
Como: Especificar o modo de edição do controle DataGridView do Windows Forms
Como: Especificar valores padrão para novas linhas no controle DataGridView do

Windows Forms

Forms
Como: Realizar uma ação personalizada com base em alterações em uma célula do
Como: Habilitar usuários para copiarem várias células na Área de Transferência

usando o controle DataGridView do Windows Forms
Como adicionar ToolTips a células individuais em um controle DataGridView dos

Windows Forms
Como: Exibir imagens em células do controle DataGridView do Windows Forms
Como personalizar a classificação no controle DataGridView dos Windows Forms
Exemplos de manipulação de coluna

Como: Congelar colunas no controle DataGridView do Windows Forms

Forms
Como: Ocultar colunas no controle DataGridView do Windows Forms
Como: Ocultar cabeçalhos no controle DataGridView do Windows Forms
Como: Tornar colunas somente leitura no controle DataGridView do Windows

Forms
Como: Definir os modos de classificação para colunas no controle DataGridView

do Windows Forms
Como: Trabalhar com colunas de imagem no controle DataGridView do Windows

Forms
Como: Manipular colunas no controle DataGridView do Windows Forms
Exemplos de dimensionamento de linha e

coluna
Modo de preenchimento da coluna no controle DataGridView dos Windows Forms
Como definir os modos de dimensionamento do controle DataGridView dos

Windows Forms
Como: Redimensionar de forma programática as células para que o conteúdo

caiba no controle DataGridView do Windows Forms
Como redimensionar automaticamente células quando o conteúdo é alterado no

controle DataGridView dos Windows Forms
Exemplos de seleção
Como: Definir o modo de seleção do controle DataGridView do Windows Forms
Como: Obter as células, as linhas e as colunas selecionadas no controle

Como obter e definir a célula atual no controle DataGridView dos Windows Forms
Exemplos de personalização avançados

Forms
Como: Personalizar a aparência de linhas no controle DataGridView do Windows

Forms
Como: Personalizar células e colunas no controle DataGridView do Windows Forms

estendendo o comportamento e a aparência
Como: Desabilitar botões em uma coluna de botão no controle DataGridView do

Windows Forms
Como: Hospedar controles em células DataGridView do Windows Forms
Exemplos de dados avançados

Como: Implementar o modo virtual no controle DataGridView do Windows Forms
Passo a passo: Implementando o modo virtual no controle DataGridView do

Windows Forms
Implementando o modo virtual com carregamento de dados Just-In-Time no

Confira também
DataGridView
Funcionalidade padrão no controle
Artigo • 02/06/2023
O controle Windows Forms DataGridView fornece aos usuários uma quantidade

significativa de funcionalidade padrão.
Funcionalidade padrão
Por padrão, um DataGridView controle:
Exibe automaticamente os cabeçalhos de coluna e de linha que permanecem

visíveis enquanto a tabela rola verticalmente.
Tem um cabeçalho de linha que contém um indicador de seleção para a linha

atual.
Tem um retângulo de seleção na primeira célula.
Tem colunas que podem ser redimensionadas automaticamente quando o usuário

clicar duas vezes nos divisores de coluna.
Dá suporte automaticamente a estilos visuais no Windows XP e na família

Windows Server 2003 quando o EnableVisualStyles método é chamado do método
do Main aplicativo.
Além disso, o conteúdo de um DataGridView controle pode ser editado por padrão:
Se o usuário clica duas vezes ou pressiona F2 em uma célula, o controle

automaticamente coloca a célula no modo de edição e atualiza o conteúdo da
célula à medida que o usuário digita.
Se o usuário rolar até o final da grade, o usuário verá que existe uma linha para
adicionar novos registros. Quando o usuário clica nessa linha, uma nova linha é
adicionada ao DataGridView controle, com valores padrão. Quando o usuário
pressiona ESC, essa nova linha desaparece.
Se o usuário clicar em um cabeçalho de linha, a linha inteira será selecionada.
Quando você associa um DataGridView controle a uma fonte de dados definindo sua
DataSource propriedade, o controle:
Usa automaticamente os nomes das colunas da fonte de dados como o texto do
cabeçalho de coluna.
É populado com o conteúdo da fonte de dados. DataGridView as colunas são

criadas automaticamente para cada coluna na fonte de dados.
Cria uma linha para cada linha visível na tabela.
Classifica automaticamente as linhas com base nos dados subjacentes quando o

usuário clica em um cabeçalho de coluna.
Confira também
DataGridView
Tipos de coluna no controle
Artigo • 02/06/2023
O DataGridView controle usa vários tipos de coluna para exibir suas informações e
permitir que os usuários modifiquem ou adicionem informações.
Quando você associa um DataGridView controle e define a propriedade como true , as

AutoGenerateColumns colunas são geradas automaticamente usando tipos de coluna
padrão apropriados para os tipos de dados contidos na fonte de dados associada.
Você também pode criar instâncias de qualquer uma das classes de coluna por conta
própria e adicioná-las à coleção retornada pela Columns propriedade. Você pode criar
essas instâncias para uso como colunas não associadas ou você pode associá-las
manualmente. As colunas associadas manualmente são úteis, por exemplo, quando você
quiser substituir uma coluna gerada automaticamente de um tipo com uma coluna de
outro tipo.
A tabela a seguir descreve as várias classes de coluna disponíveis para uso no

DataGridView controle.
Classe Descrição
DataGridViewTextBoxColumn Usado com valores baseados em texto. Gerado

automaticamente ao associar a números e cadeias de
caracteres.
DataGridViewCheckBoxColumn Usado com Boolean e CheckState valores. Gerado

automaticamente ao associar a valores desses tipos.
DataGridViewImageColumn Usado para exibir imagens. Gerado automaticamente ao

associar matrizes, Image objetos ou Icon objetos de bytes.
DataGridViewButtonColumn Usado para exibir os botões nas células. Não gerado

automaticamente durante a associação. Normalmente usado
como colunas não associadas.
DataGridViewComboBoxColumn Usado para exibir listas suspensas nas células. Não gerado
automaticamente durante a associação. Normalmente,
associação manual de dados.
DataGridViewLinkColumn Usado para exibir links nas células. Não gerado

automaticamente durante a associação. Normalmente,
associação manual de dados.
Classe Descrição
Seu tipo de coluna Você pode criar sua própria classe de coluna herdando a
personalizada DataGridViewColumn classe ou qualquer uma de suas classes
derivadas para fornecer aparência, comportamento ou
controles hospedados personalizados. Para obter mais
informações, consulte Como personalizar células e colunas no
controle Windows Forms DataGridView estendendo seu
comportamento e aparência
Esses tipos de colunas são descritos mais detalhadamente nas seções a seguir.
É DataGridViewTextBoxColumn um tipo de coluna de uso geral para uso com valores
baseados em texto, como números e cadeias de caracteres. No modo de edição, um
TextBox controle é exibido na célula ativa, permitindo que os usuários modifiquem o
valor da célula.
Os valores da célula são convertidos automaticamente em cadeiras de caracteres para

exibição. Os valores inseridos ou modificados pelo usuário são automaticamente
analisados para criar um valor de célula do tipo de dados apropriado. Você pode
personalizar essas conversões manipulando os eventos e os CellFormatting eventos
CellParsing do DataGridView controle.
O tipo de dados de valor de célula de uma coluna é especificado na ValueType

propriedade da coluna.
O DataGridViewCheckBoxColumn valor é usado com e CheckState valoresBoolean.
Boolean os valores são exibidos como caixas de seleção de dois ou três estados,
dependendo do valor da ThreeState propriedade. Quando a coluna está associada a
CheckState valores, o valor da ThreeState propriedade é true por padrão.
Normalmente, os valores de célula da caixa de seleção destinam-se para

armazenamento, como qualquer outro dado ou para executar operações em massa. Se
você quiser responder imediatamente quando os usuários clicarem em uma célula de
caixa de seleção, você poderá manipular o CellClick evento, mas esse evento ocorrerá
antes que o valor da célula seja atualizado. Se você precisar do novo valor no momento
do clique, uma opção será calcular qual será o valor esperado com base no valor atual.
Outra abordagem é confirmar a alteração imediatamente e manipular o
CellValueChanged evento para responder a ela. Para confirmar a alteração quando a
célula é clicada, você deve manipular o CurrentCellDirtyStateChanged evento. No
manipulador, se a célula atual for uma célula de caixa de seleção, chame o CommitEdit
método e passe o Commit valor.
O DataGridViewImageColumn é usado para exibir imagens. As colunas de imagem
podem ser preenchidas automaticamente de uma fonte de dados, preenchidas
manualmente para colunas não associadas ou preenchidas dinamicamente em um
manipulador para o CellFormatting evento.
A população automática de uma coluna de imagem de uma fonte de dados funciona

com matrizes de bytes em uma variedade de formatos de imagem, incluindo todos os
formatos compatíveis com a Image classe e o formato de imagem OLE usado pelo
Microsoft® Access e o banco de dados de exemplo Northwind.
Preencher uma coluna de imagem manualmente é útil quando você deseja fornecer a
funcionalidade de um DataGridViewButtonColumn, mas com uma aparência
personalizada. Você pode manipular o DataGridView.CellClick evento para responder a
cliques em uma célula de imagem.
Preencher as células de uma coluna de imagem em um manipulador para o

CellFormatting evento é útil quando você deseja fornecer imagens para valores
calculados ou valores em formatos que não são de imagem. Por exemplo, você pode ter
uma coluna “Risco” com valores de cadeia de caracteres como "high" , "middle" e
"low" que você deseja exibir como ícones. Como alternativa, você pode ter uma coluna
"Imagem" que contém os locais de imagens que devem ser carregados em vez do
conteúdo binário das imagens.
Com o DataGridViewButtonColumn, você pode exibir uma coluna de células que
contêm botões. Isso é útil quando você deseja fornecer uma maneira fácil para os
usuários de executar ações em registros específicos, como fazer um pedido ou exibir
registros filho em uma janela separada.
As colunas de botão não são geradas automaticamente ao associar dados a um

DataGridView controle. Para usar colunas de botão, você deve criá-las manualmente e
adicioná-las à coleção retornada pela DataGridView.Columns propriedade.
Você pode responder aos cliques do usuário em células de botão manipulando o
DataGridView.CellClick evento.
Com o DataGridViewComboBoxColumn, você pode exibir uma coluna de células que
contêm caixas de listagem suspensas. Isso é útil para entrada de dados em campos que
podem conter apenas valores específicos, como a coluna Categoria da tabela Produtos
no banco de dados de exemplo Northwind.
Você pode preencher a lista suspensa usada para todas as células da mesma maneira
que preencheria uma ComboBox lista suspensa, manualmente por meio da coleção
retornada pela propriedade, ou associando-a Items a uma fonte de dados por meio do
e DisplayMemberValueMember das DataSourcepropriedades. Para saber mais, consulte
Controle ComboBox.
Você pode associar os valores reais da célula à fonte de dados usada pelo DataGridView
controle definindo a DataPropertyName propriedade do
System.Windows.Forms.DataGridViewComboBoxColumn.
As colunas de caixa de combinação não são geradas automaticamente ao associar

dados a um DataGridView controle. Para usar colunas de caixa de combinação, você
deve criá-las manualmente e adicioná-las à coleção retornada pela Columns
propriedade.
Com o DataGridViewLinkColumn, você pode exibir uma coluna de células que contêm
hiperlinks. Isso é útil para valores de URL na fonte de dados ou como uma alternativa
para a coluna de botão para comportamentos especiais, como abrir uma janela com
registros filho.
As colunas de link não são geradas automaticamente ao associar dados a um

DataGridView controle. Para usar colunas de link, você deve criá-las manualmente e
adicioná-las à coleção retornada pela Columns propriedade.
Você pode responder aos cliques do usuário em links manipulando o CellContentClick

evento. Esse evento é distinto dos CellClick eventos e CellMouseClick que ocorrem
quando um usuário clica em qualquer lugar em uma célula.
A DataGridViewLinkColumn classe fornece várias propriedades para modificar a

aparência dos links antes, durante e depois que eles são clicados.
Confira também
DataGridView
DataGridViewColumn
Como: Trabalhar com colunas de imagem no controle DataGridView do Windows
Forms
Funcionalidades de coluna, linha e
célula básicas no controle DataGridView
dos Windows Forms
Artigo • 02/06/2023
Várias funcionalidades básicas de DataGridView células, linhas e colunas podem ser

modificadas configurando propriedades individuais. Os tópicos nesta seção descrevem
vários dos recursos mais usados.
Nesta seção
Como: Ocultar colunas no controle DataGridView do Windows Forms
Descreve como impedir que colunas específicas apareçam no controle.
Como: Ocultar cabeçalhos no controle DataGridView do Windows Forms

Descreve como impedir que os cabeçalhos das colunas apareçam no controle.

Forms
Descreve como habilitar usuários para reorganizar colunas no controle.

Descreve como evitar que uma ou mais colunas adjacentes rolem.
Como: Tornar colunas somente leitura no controle DataGridView do Windows Forms

Descreve como evitar que os usuários editem colunas específicas no controle.

Forms
Descreve como remover a linha para novos registros na parte inferior do controle para
evitar que os usuários adicionem linhas. Também descreve como evitar que os usuários
apaguem linhas.
Como obter e definir a célula atual no controle DataGridView dos Windows Forms
Descreve como acessar a célula que tem foco no controle atualmente.

Descreve como criar uma coluna de imagem exibindo um ícone em cada célula.
Referência
DataGridView
Fornece documentação de referência para o controle.
Programando com células, linhas e colunas no controle DataGridView dos Windows

Forms
Fornece tópicos que descrevem como programar com objetos de célula, linha e coluna.
Confira também
Como: Ocultar colunas no controle
Artigo • 21/06/2023
Às vezes, você desejará exibir apenas algumas das colunas que estão disponíveis em um
controle Windows FormsDataGridView. Por exemplo, talvez você queira mostrar uma
coluna de salário de funcionário aos usuários com credenciais de gerenciamento
enquanto a oculta de outros usuários. Como alternativa, talvez você queira associar o
controle a uma fonte de dados que contenha muitas colunas, apenas algumas das quais
você deseja exibir. Nesse caso, você normalmente removerá as colunas que não está
interessado em exibi-las em vez de ocultá-las.
DataGridView No controle , o Visible valor da propriedade de uma coluna determina se

essa coluna é exibida.
Há suporte para esta tarefa no Visual Studio. Consulte também Como ocultar colunas no
Windows Forms controle DataGridView usando o Designer.
Para ocultar uma coluna programaticamente

Defina a propriedade DataGridViewColumn.Visible como false . Para ocultar uma
CustomerID coluna gerada automaticamente durante a associação de dados,
coloque o exemplo de código a seguir em um DataBindingComplete manipulador
de eventos.
C#
this.dataGridView1.Columns["CustomerID"].Visible = false;
Um DataGridView controle chamado dataGridView1 que contém uma coluna

chamada CustomerID .
Confira também
DataGridView
Windows Forms
do Windows Forms
Como: Ocultar cabeçalhos no controle
Artigo • 02/06/2023
Às vezes, você deseja exibir um DataGridView cabeçalho sem coluna. DataGridView No

controle, o valor da ColumnHeadersVisible propriedade determina se os cabeçalhos de
coluna são exibidos.
Para ocultar os cabeçalhos de coluna

Defina a propriedade DataGridView.ColumnHeadersVisible como false .
C#
dataGridView1.ColumnHeadersVisible = false;
Um controle DataGridView chamado dataGridView1 .
Confira também
DataGridView
DataGridView.ColumnHeadersVisible
Windows Forms
Como: Habilitar a reorganização da
coluna no controle DataGridView do
Windows Forms
Artigo • 02/06/2023
Quando você habilita a reordenação de coluna no DataGridView controle, os usuários

podem mover uma coluna para uma nova posição arrastando o cabeçalho da coluna
com o mouse. DataGridView No controle, o valor da
DataGridView.AllowUserToOrderColumns propriedade determina se os usuários podem
mover colunas para diferentes posições.
Há suporte para esta tarefa no Visual Studio. Veja também como habilitar a reordenação
de coluna no controle Windows Forms DataGridView usando o designer.
Para habilitar a reordenação de colunas

programaticamente
Defina a propriedade DataGridView.AllowUserToOrderColumns como true .
C#
dataGridView1.AllowUserToOrderColumns = true;
Confira também
DataGridView
DataGridView.AllowUserToOrderColumns
Windows Forms
Como: Congelar colunas no controle
Artigo • 02/06/2023
Quando os usuários exibem dados exibidos em um controle Windows

FormsDataGridView, às vezes, eles precisam se referir a uma única coluna ou conjunto
de colunas com frequência. Por exemplo, ao exibir uma tabela de informações do cliente
que contém muitas colunas, é útil exibir o nome do cliente o tempo todo, permitindo
que outras colunas rolem para fora da região visível.
Para obter esse comportamento, você pode congelar colunas no controle. Quando você
congela uma coluna, todas as colunas à esquerda (ou à direita em scripts de idioma da
direita para esquerda) são congeladas também. Colunas congeladas permanecerão no
local enquanto todas as outras colunas podem rolar.
７ Observação
Se a reordenação de coluna estiver habilitada, as colunas congeladas serão tratadas

como um grupo diferente das colunas não congeladas. Os usuários podem
reposicionar colunas em um dos grupos, mas não poderão mover uma coluna de
um grupo para outro.
A Frozen propriedade de uma coluna determina se a coluna está sempre visível dentro
da grade.
Há suporte para esta tarefa no Visual Studio. Veja também como congelar colunas no
controle Windows Forms DataGridView usando o designer.
Para congelar uma coluna programaticamente

Defina a propriedade DataGridViewColumn.Frozen como true .
C#
this.dataGridView1.Columns["AddToCartButton"].Frozen = true;
chamada AddToCartButton .
Confira também
DataGridViewColumn.Frozen
DataGridView
Windows Forms
Forms
Como: Tornar colunas somente leitura
no controle DataGridView do Windows
Forms
Artigo • 02/06/2023
Nem todos os dados são destinados à edição. DataGridView No controle, o valor da

propriedade da coluna ReadOnly determina se os usuários podem editar células nessa
coluna. Para obter informações sobre como tornar o controle totalmente somente
leitura, consulte Como evitar a adição e exclusão de linhas no controle Windows Forms
DataGridView.
Há suporte para esta tarefa no Visual Studio. Veja também como fazer colunas Read-
Only no controle Windows Forms DataGridView usando o designer.
Para fazer uma coluna somente leitura

programaticamente
Defina a propriedade DataGridViewColumn.ReadOnly como true .
C#
dataGridView1.Columns["CompanyName"].ReadOnly = true;
Um DataGridView controle nomeado dataGridView1 com uma coluna chamada

CompanyName .
Confira também
DataGridView
DataGridView.Columns
Windows Forms
Forms
Como: Evitar a adição e a exclusão de
linha no controle DataGridView do
Windows Forms
Artigo • 02/06/2023
Às vezes, você deseja impedir que os usuários insiram novas linhas de dados ou
excluam linhas existentes em seu DataGridView controle. A AllowUserToAddRows
propriedade indica se a linha para novos registros está presente na parte inferior do
controle, enquanto a propriedade indica se as AllowUserToDeleteRows linhas podem ser
removidas. O exemplo de código a seguir usa essas propriedades e também define a
ReadOnly propriedade para tornar o controle totalmente somente leitura.
Há suporte para esta tarefa no Visual Studio. Veja também como evitar a adição e a
exclusão de linha no controle datagridview Windows Forms usando o designer.
Exemplo
C#
private void MakeReadOnly()

{
dataGridView1.AllowUserToAddRows = false;
dataGridView1.AllowUserToDeleteRows = false;
dataGridView1.ReadOnly = true;
}
Confira também
DataGridView
DataGridView.ReadOnly
DataGridView.AllowUserToDeleteRows
Windows Forms
Como obter e definir a célula atual no
controle DataGridView dos Windows
Forms
Artigo • 02/06/2023
A interação com o DataGridView geralmente exige que você descubra

programaticamente qual célula está ativa no momento. Talvez você precise alterar a
célula atual. Você pode executar essas tarefas com a CurrentCell propriedade .
７ Observação
Não é possível definir a célula atual em uma linha ou coluna que tenha sua Visible
propriedade definida como false .
Dependendo do modo DataGridView de seleção do controle, alterar a célula atual pode

alterar a seleção. Para obter mais informações, veja Modos de seleção do controle
Para obter a célula atual de forma programática

Use a DataGridView propriedade do CurrentCell controle.
C#
private void getCurrentCellButton_Click(object sender, System.EventArgs

e)
{
string msg = String.Format("Row: {0}, Column: {1}",
dataGridView1.CurrentCell.RowIndex,
dataGridView1.CurrentCell.ColumnIndex);
MessageBox.Show(msg, "Current Cell");
}
Para definir a célula atual de forma programática

De definir CurrentCell a propriedade do DataGridView controle . No exemplo de
código a seguir, a célula atual é definida como linha 0, coluna 1.
C#
private void setCurrentCellButton_Click(object sender, System.EventArgs
e)
{
// Set the current cell to the cell in column 1, Row 0.
this.dataGridView1.CurrentCell = this.dataGridView1[1,0];
}
Button controles chamados getCurrentCellButton e setCurrentCellButton . No

Visual C#, você deve anexar os Click eventos de cada botão ao manipulador de
eventos associado no código de exemplo.
Confira também
DataGridView
DataGridView.CurrentCell
Windows Forms
Modos de seleção no controle DataGridView dos Windows Forms
Como: Exibir imagens em células do
Forms
Artigo • 02/06/2023
Uma imagem ou um gráfico é um dos valores que você pode exibir em uma linha de
dados. Frequentemente, esses elementos gráficos assumem a forma de foto do
funcionário ou um logotipo da empresa.
A incorporação de imagens é simples quando você exibe dados dentro do

DataGridView controle. O DataGridView controle manipula nativamente qualquer
formato de imagem compatível com a Image classe, bem como o formato de imagem
OLE usado por alguns bancos de dados.
Se a DataGridView fonte de dados do controle tiver uma coluna de imagens, elas serão
exibidas automaticamente pelo DataGridView controle.
O exemplo de código a seguir demonstra como extrair um ícone de um recurso inserido

e convertê-lo em um bitmap para exibição em cada célula de uma coluna de imagens.
Para obter outro exemplo que substitui os valores de célula textual por imagens
correspondentes, consulte Como personalizar a formatação de dados no controle
Exemplo
C#
private void createGraphicsColumn()

{
Icon treeIcon = new Icon(this.GetType(), "tree.ico");
DataGridViewImageColumn iconColumn = new DataGridViewImageColumn();
iconColumn.Image = treeIcon.ToBitmap();
iconColumn.Name = "Tree";
iconColumn.HeaderText = "Nice tree";
dataGridView1.Columns.Insert(2, iconColumn);
}
Um recurso de ícone incorporado denominado tree.ico .
Referências ao System, System.Windows.Formse System.Drawing assemblies.
Confira também
DataGridView
Windows Forms
Forms
Formatação básica e estilos no controle
Artigo • 02/06/2023
O controle DataGridView facilita a tarefa de definir a aparência básica de células e a

formatação da exibição dos valores de célula. Você pode definir os estilos de aparência
e formatação de células individuais, para células em linhas e colunas específicas ou para
todas as células no controle definindo as propriedades dos objetos
DataGridViewCellStyle acessados por meio de várias propriedades do controle
DataGridView . Além disso, é possível modificar esses estilos dinamicamente com base
em fatores como o valor da célula manipulando o evento CellFormatting .
Nesta seção
Como: Alterar a borda e os estilos da linha de grade no tempo de execução no controle
Descreve como configurar as propriedades DataGridView que definem a aparência da
borda do controle e as linhas de limite entre células.

Descreve a classe DataGridViewCellStyle e como propriedades desse tipo interagem
para definir como as células são exibidas no controle.
Como: Definir estilos de célula padrão para o controle DataGridView do Windows Forms
Descreve como usar propriedades DataGridViewCellStyle para definir a aparência
padrão de células em linhas e colunas específicas e em todo o controle.

Descreve como formatar valores de exibição de célula usando propriedades
DataGridViewCellStyle .

Descreve como usar a propriedade DefaultCellStyle para definir as características de
exibição básicas para todas as células no controle.
Como: Definir estilos de linha alternados para o controle DataGridView do Windows

Forms
Descreve como criar um efeito semelhante à razão no controle usando linhas alternadas
são exibidas de maneira diferente.
Como: Usar o modelo da linha para personalizar linhas no controle DataGridView do
Windows Forms
Descreve como usar a propriedade RowTemplate para definir as propriedades de linha
que serão usadas para todas as linhas no controle.
Referência
DataGridView
Fornece a documentação de referência para a DataGridViewCellStyle classe.
CellFormatting
Fornece a documentação de referência para o CellFormatting evento.
RowTemplate
Fornece a documentação de referência para a RowTemplate propriedade.
DataGridView, bem como a criação de tipos de célula, coluna e linha derivados.

Windows Forms
Confira também
Como: Alterar a borda e os estilos da
linha de grade no tempo de execução
no controle DataGridView do Windows
Forms
Artigo • 02/06/2023
Com o DataGridView controle, você pode personalizar a aparência da borda e das linhas
de grade do controle para melhorar a experiência do usuário. Você pode modificar a cor
da linha de grade e o estilo de borda do controle além os estilos de borda para as
células no controle. Você também pode aplicar diferentes estilos de borda da célula
para células comuns, células de cabeçalho de linha e células de cabeçalho de coluna.
７ Observação
A cor da linha de grade é usada apenas com os SingleSingleHorizontalvalores e

DataGridViewCellBorderStyle enumeração e SingleVertical o Single valor da
DataGridViewHeaderBorderStyle enumeração. Os outros valores dessas
enumerações usam cores especificadas pelo sistema operacional. Além disso,
quando os estilos visuais são habilitados no Windows XP e na família Windows
Server 2003 por meio do Application.EnableVisualStyles método, o valor da
GridColor propriedade não é usado.
Para alterar a cor da linha de grade de forma

programática
Definir a propriedade GridColor.
C#
this.dataGridView1.GridColor = Color.BlueViolet;
Para alterar o estilo da borda de todo o controle

DataGridView de forma programática
Defina a BorderStyle propriedade como um dos valores de BorderStyle
enumeração.
C#
this.dataGridView1.BorderStyle = BorderStyle.Fixed3D;
Para alterar os estilos de borda para células DataGridView

de forma programática
Defina as propriedades CellBorderStyle, RowHeadersBorderStylee
ColumnHeadersBorderStyle .
C#
this.dataGridView1.CellBorderStyle =
DataGridViewCellBorderStyle.None;
this.dataGridView1.RowHeadersBorderStyle =
DataGridViewHeaderBorderStyle.Single;
this.dataGridView1.ColumnHeadersBorderStyle =
Exemplo
C#
private void SetBorderAndGridlineStyles()

{
this.dataGridView1.GridColor = Color.BlueViolet;
this.dataGridView1.BorderStyle = BorderStyle.Fixed3D;
this.dataGridView1.RowHeadersBorderStyle =
this.dataGridView1.ColumnHeadersBorderStyle =
}
Referências ao System, System.Windows.Formse System.Drawing assemblies.

Confira também
BorderStyle
DataGridView.BorderStyle
DataGridView.CellBorderStyle
DataGridView.ColumnHeadersBorderStyle
DataGridView.GridColor
DataGridView.RowHeadersBorderStyle
DataGridViewCellBorderStyle
DataGridViewHeaderBorderStyle
Estilos de célula no controle
Artigo • 02/06/2023
Cada célula dentro do DataGridView controle pode ter seu próprio estilo, como formato
de texto, cor da tela de fundo, cor do primeiro plano e fonte. Normalmente, no entanto,
várias células compartilharão características de determinado estilo.
Os grupos de células que compartilham estilos podem incluir todas as células em

determinadas linhas ou colunas, todas as células que contêm valores específicos ou
todas as células no controle. Como esses grupos se sobrepõem, cada célula pode obter
as informações de estilo de mais de um lugar. Por exemplo, talvez você queira que cada
célula em um DataGridView controle use a mesma fonte, mas apenas células em colunas
de moeda usem o formato de moeda e apenas células de moeda com números
negativos para usar uma cor de primeiro plano vermelho.
A classe DataGridViewCellStyle
A DataGridViewCellStyle classe contém as seguintes propriedades relacionadas ao estilo
visual:
BackColor e ForeColor
SelectionBackColor e SelectionForeColor
Font
Essa classe também contém as seguintes propriedades relacionadas à formatação:
Format e FormatProvider
NullValue e DataSourceNullValue
WrapMode
Alignment
Padding
Para obter mais informações sobre essas propriedades e outras propriedades de estilo
de célula, consulte a DataGridViewCellStyle documentação de referência e os tópicos
listados na seção Veja Também abaixo.
Usando objetos DataGridViewCellStyle
Você pode recuperar DataGridViewCellStyle objetos de várias propriedades do
DataGridView, DataGridViewColumnDataGridViewRowe classes e DataGridViewCell suas
classes derivadas. Se uma dessas propriedades ainda não tiver sido definida, recuperar
seu valor criará um novo DataGridViewCellStyle objeto. Você também pode instanciar
seus próprios DataGridViewCellStyle objetos e atribuí-los a essas propriedades.
Você pode evitar a duplicação desnecessária de informações de estilo compartilhando

DataGridViewCellStyle objetos entre vários DataGridView elementos. Como o conjunto
de estilos nos níveis de controle, coluna e linha filtram através de cada nível até o nível
da célula, você também pode evitar a duplicação de estilos, configurando somente as
propriedades de estilo em cada nível, que são diferentes dos níveis acima. Isso é
descrito mais detalhadamente na seção de Herança de estilo que se segue.
A tabela a seguir lista as propriedades primárias que obtêm ou definem

DataGridViewCellStyle objetos.
Propriedade Classes Descrição
DefaultCellStyle DataGridView, Obtém ou define estilos padrão

DataGridViewColumne usados por todas as células em
DataGridViewRowclasses todo o controle (incluindo
derivadas células de cabeçalho), em uma
coluna ou em uma linha.
RowsDefaultCellStyle DataGridView Obtém ou define os estilos de

célula padrão usados por todas
as linhas no controle. Isso não
inclui as células de cabeçalho.
AlternatingRowsDefaultCellStyle DataGridView Obtém ou define os estilos de

célula padrão, alternando as
linhas no controle. Usado para
criar um efeito semelhante a
livro-razão.
RowHeadersDefaultCellStyle DataGridView Obtém ou define os estilos de

célula padrão usados por
cabeçalhos de linha do controle.
Substituídos pelo tema atual se
os estilos visuais estiverem
habilitados.
Propriedade Classes Descrição
ColumnHeadersDefaultCellStyle DataGridView Obtém ou define os estilos de

célula padrão usados por
cabeçalhos de coluna do
controle. Substituídos pelo tema
atual se os estilos visuais
estiverem habilitados.
Style DataGridViewCell e classes Obtém ou define estilos

derivadas especificados no nível da célula.
Esses estilos substituem aqueles
herdados de níveis superiores.
InheritedStyle DataGridViewCell, Obtém todos os estilos

DataGridViewRowe atualmente aplicados à célula,
DataGridViewColumnclasses linha ou coluna, inclusive estilos
derivadas herdados de níveis superiores.
Conforme mencionado acima, obter o valor de uma propriedade de estilo criará uma
instância automática de um novo DataGridViewCellStyle objeto se a propriedade não
tiver sido definida anteriormente. Para evitar a criação desses objetos
desnecessariamente, as classes de linha e coluna têm uma HasDefaultCellStyle
propriedade que você pode verificar para determinar se a DefaultCellStyle propriedade
foi definida. Da mesma forma, as classes de célula têm uma HasStyle propriedade que
indica se a Style propriedade foi definida.
Cada uma das propriedades de estilo tem um evento PropertyName Changed

correspondente no DataGridView controle. Para propriedades de linha, coluna e célula,
o nome do evento começa com " Row ", " Column " ou " Cell " (por exemplo,
RowDefaultCellStyleChanged). Cada um desses eventos ocorre quando a propriedade
de estilo correspondente é definida como um objeto diferente DataGridViewCellStyle .
Esses eventos não ocorrem quando você recupera um DataGridViewCellStyle objeto de
uma propriedade de estilo e modifica seus valores de propriedade. Para responder a
alterações nos próprios objetos de estilo de célula, manipule o
CellStyleContentChanged evento.
Herança de estilo
Cada um DataGridViewCell obtém sua aparência de sua InheritedStyle propriedade. O
DataGridViewCellStyle objeto retornado por essa propriedade herda seus valores de
uma hierarquia de propriedades do tipo DataGridViewCellStyle. Essas propriedades são
listadas abaixo na ordem na qual as InheritedStyle células não cabeçalho obtêm seus
valores.
1. DataGridViewCell.Style
2. DataGridViewRow.DefaultCellStyle
3. DataGridView.AlternatingRowsDefaultCellStyle (somente para células em linhas

com números de índice ímpares)
4. DataGridView.RowsDefaultCellStyle
5. DataGridViewColumn.DefaultCellStyle
6. DataGridView.DefaultCellStyle
Para células de cabeçalho de linha e coluna, a InheritedStyle propriedade é preenchida

por valores da seguinte lista de propriedades de origem na ordem fornecida.
1. DataGridViewCell.Style
2. DataGridView.ColumnHeadersDefaultCellStyle ou
DataGridView.RowHeadersDefaultCellStyle
O diagrama a seguir ilustra esse processo.
do tipo
Você também pode acessar os estilos herdados por colunas e linhas específicas. A
propriedade column InheritedStyle herda seus valores das propriedades a seguir.
1. DataGridViewColumn.DefaultCellStyle
A propriedade row InheritedStyle herda seus valores das propriedades a seguir.
1. DataGridViewRow.DefaultCellStyle
2. DataGridView.AlternatingRowsDefaultCellStyle (somente para células em linhas

com números de índice ímpares)
3. DataGridView.RowsDefaultCellStyle
Para cada propriedade em um DataGridViewCellStyle objeto retornado por uma

InheritedStyle propriedade, o valor da propriedade é obtido do primeiro estilo de
célula na lista apropriada que tem a propriedade correspondente definida como um

valor diferente dos padrões de DataGridViewCellStyle classe.
A tabela a seguir ilustra como o valor da ForeColor propriedade de uma célula de

exemplo é herdado de sua coluna que contém.
Propriedade do tipo DataGridViewCellStyle Valor ForeColor de exemplo de objeto

recuperado
DataGridViewCell.Style Color.Empty
DataGridViewRow.DefaultCellStyle Color.Red
DataGridView.AlternatingRowsDefaultCellStyle Color.Empty
DataGridView.RowsDefaultCellStyle Color.Empty
DataGridViewColumn.DefaultCellStyle Color.DarkBlue
DataGridView.DefaultCellStyle Color.Black
Nesse caso, o Color.Red valor da linha da célula é o primeiro valor real na lista. Isso se
torna o ForeColor valor da propriedade da célula InheritedStyle.
O diagrama a seguir ilustra como propriedades diferentes DataGridViewCellStyle podem

herdar seus valores de locais diferentes.
Diagrama
Ao tirar proveito da herança de estilo, você pode fornecer estilos apropriados para todo
o controle sem ter que especificar as mesmas informações em vários locais.
Embora as células de cabeçalho participem da herança de estilo, conforme descrito, os

objetos retornados pela propriedade e RowHeadersDefaultCellStyle pelas
ColumnHeadersDefaultCellStyle propriedades do controle têm valores de DataGridView
propriedade iniciais que substituem os valores de propriedade do objeto retornado pela
DefaultCellStyle propriedade. Se você quiser que as propriedades definidas para o
objeto retornado pela DefaultCellStyle propriedade sejam aplicadas aos cabeçalhos de
linha e coluna, defina as propriedades correspondentes dos objetos retornados pela
ColumnHeadersDefaultCellStyle propriedade e RowHeadersDefaultCellStyle as
propriedades para os padrões indicados para a DataGridViewCellStyle classe.
７ Observação
Se os estilos visuais estiverem habilitados, os cabeçalhos de linha e coluna (exceto

o TopLeftHeaderCell) serão estilizados automaticamente pelo tema atual,
substituindo todos os estilos especificados por essas propriedades.
Os DataGridViewButtonColumntipos e DataGridViewCheckBoxColumn os
DataGridViewImageColumntipos também inicializam alguns valores do objeto
retornados pela propriedade de colunaDefaultCellStyle. Para obter mais informações,
consulte a documentação de referência para esses tipos.
Configurando estilos dinamicamente

Para personalizar os estilos das células com valores específicos, implemente um
manipulador para o DataGridView.CellFormatting evento. Os manipuladores para esse
evento recebem um argumento do DataGridViewCellFormattingEventArgs tipo. Esse
objeto contém propriedades que permitem determinar o valor da célula que está sendo
formatada junto com sua localização no DataGridView controle. Esse objeto também
contém uma CellStyle propriedade inicializada para o valor da InheritedStyle
propriedade da célula que está sendo formatada. Você pode modificar as propriedades
de estilo da célula para especificar as informações de estilo apropriadas para o valor e o
local da célula.
７ Observação
Os RowPrePaint eventos e RowPostPaint eventos também recebem um

DataGridViewCellStyle objeto nos dados do evento, mas, no caso deles, ele é uma
cópia da propriedade de linha InheritedStyle para fins somente leitura e as
alterações nele não afetam o controle.
Você também pode modificar dinamicamente os estilos de células individuais em

resposta a eventos como e DataGridView.CellMouseEnterCellMouseLeave eventos. Por
exemplo, em um manipulador para o CellMouseEnter evento, você pode armazenar o
valor atual da cor da tela de fundo da célula (recuperada pela propriedade da Style
célula) e defini-la como uma nova cor que realçará a célula quando o mouse passar o
mouse sobre ela. Em um manipulador para o CellMouseLeave evento, você pode
restaurar a cor da tela de fundo para o valor original.
７ Observação
Armazenar em cache os valores armazenados na propriedade da Style célula é

importante, independentemente de um valor de estilo específico ser definido. Se
você substituir temporariamente uma configuração de estilo, restaurá-la ao seu
estado original de "não definido" garantirá que a célula voltará a herdar a
configuração de estilo de um nível mais alto. Se você precisar determinar o estilo
real em vigor para uma célula, independentemente de o estilo ser herdado, use a
propriedade da InheritedStyle célula.
Confira também
DataGridView
DataGridView.AlternatingRowsDefaultCellStyle
DataGridView.ColumnHeadersDefaultCellStyle
DataGridView.RowHeadersDefaultCellStyle
DataGridViewBand.InheritedStyle
DataGridViewRow.InheritedStyle
DataGridViewColumn.InheritedStyle
DataGridViewBand.DefaultCellStyle
DataGridViewCell.InheritedStyle
DataGridViewCell.Style
DataGridView.CellFormatting
DataGridView.CellStyleContentChanged
DataGridView.RowPrePaint
DataGridView.RowPostPaint
Forms
Formatação de dados no controle DataGridView dos Windows Forms
Como: Definir estilos de célula padrão
para o controle DataGridView do
Windows Forms
Artigo • 02/06/2023
Com o DataGridView controle, você pode especificar estilos de célula padrão para todo
o controle e para colunas e linhas específicas. Esses padrões filtram do nível do controle
até o nível de coluna e depois até o nível de linha e o nível da célula. Se uma
propriedade específica DataGridViewCellStyle não for definida no nível da célula, a
configuração de propriedade padrão no nível da linha será usada. Se a propriedade
também não estiver definida no nível de linha, a configuração de coluna padrão será
usada. Por fim, se a propriedade também não estiver definida no nível da coluna, a
configuração padrão DataGridView será usada. Com essa configuração, você pode evitar
precisar duplicar as configurações de propriedade em vários níveis. Em cada nível, basta
especifica os estilos que são diferentes dos níveis acima. Para obter mais informações,
consulte Estilos de célula no controle DataGridView dos Windows Forms.
Há um suporte abrangente para esta tarefa no Visual Studio. Consulte também Como
definir estilos de célula padrão e formatos de dados para o controle DataGridView dos
Windows Forms usando o designer.
Definir estilos de célula padrão com programação

1. Defina as propriedades do DataGridViewCellStyle recuperado por meio da
DataGridView.DefaultCellStyle propriedade.
C#
this.dataGridView1.DefaultCellStyle.BackColor = Color.Beige;
this.dataGridView1.DefaultCellStyle.Font = new Font("Tahoma", 12);
2. Crie e inicialize novos DataGridViewCellStyle objetos para uso por várias linhas e
colunas.
C#
DataGridViewCellStyle highlightCellStyle = new DataGridViewCellStyle();

highlightCellStyle.BackColor = Color.Red;
DataGridViewCellStyle currencyCellStyle = new DataGridViewCellStyle();

currencyCellStyle.Format = "C";
currencyCellStyle.ForeColor = Color.Green;
3. Defina a propriedade DefaultCellStyle de linhas e colunas específicas.
C#
this.dataGridView1.Rows[3].DefaultCellStyle = highlightCellStyle;
this.dataGridView1.Columns["UnitPrice"].DefaultCellStyle =
currencyCellStyle;
this.dataGridView1.Columns["TotalPrice"].DefaultCellStyle =
currencyCellStyle;
Exemplo
C#
private void SetDefaultCellStyles()

{
DataGridViewCellStyle highlightCellStyle = new DataGridViewCellStyle();

highlightCellStyle.BackColor = Color.Red;
DataGridViewCellStyle currencyCellStyle = new DataGridViewCellStyle();

currencyCellStyle.Format = "C";
currencyCellStyle.ForeColor = Color.Green;
this.dataGridView1.Columns["UnitPrice"].DefaultCellStyle =
currencyCellStyle;
this.dataGridView1.Columns["TotalPrice"].DefaultCellStyle =
currencyCellStyle;
}
Referências ao System, System.Drawinge System.Windows.Forms assemblies.

Para atingir a escalabilidade máxima quando você trabalha com conjuntos de dados
muito grandes, você deve compartilhar DataGridViewCellStyle objetos em várias linhas,
colunas ou células que usam os mesmos estilos, em vez de definir as propriedades de
estilo para elementos individuais separadamente. Além disso, você deve criar linhas
compartilhadas e acessá-las usando a DataGridViewRowCollection.SharedRow
propriedade. Para obter mais informações, consulte Práticas recomendadas para
colocação em escala do controle DataGridView dos Windows Forms.
Confira também
DataGridView
Práticas recomendadas para dimensionamento do controle DataGridView dos
Windows Forms
Como: Definir estilos de linha alternados para o controle DataGridView do
Windows Forms
Como: Formatar dados no controle
Artigo • 21/06/2023
Os procedimentos a seguir demonstram a formatação básica de valores de célula

usando a DefaultCellStyle propriedade de um DataGridView controle e de colunas
específicas em um controle. Para obter informações sobre a formatação de dados
avançados, consulte Como personalizar a formatação de dados no controle
Formatar os valores de moeda e datas

Defina a Format propriedade de um DataGridViewCellStyle. O exemplo de código
a seguir define o formato para colunas específicas usando a DefaultCellStyle
propriedade das colunas. Valores na coluna UnitPrice aparecem no formato de
moeda específico da cultura atual, com valores negativos entre parênteses. Valores
na coluna ShipDate aparecem no formato de data curto específico da cultura atual.
Para obter mais informações sobre Format valores, consulte Tipos de formatação.
C#
this.dataGridView1.Columns["UnitPrice"].DefaultCellStyle.Format = "c";
this.dataGridView1.Columns["ShipDate"].DefaultCellStyle.Format = "d";
Personalizar a exibição de valores nulos de banco de

dados
Defina a NullValue propriedade de um DataGridViewCellStyle. O exemplo de
código a seguir usa a DataGridView.DefaultCellStyle propriedade para exibir
"nenhuma entrada" em todas as células que contêm valores iguais a DBNull.Value.
C#
this.dataGridView1.DefaultCellStyle.NullValue = "no entry";
Habilitar quebra automática de linha nas células de texto

Defina a WrapMode propriedade de um DataGridViewCellStyle como um dos
valores de DataGridViewTriState enumeração. O exemplo de código a seguir usa a
DataGridView.DefaultCellStyle propriedade para definir o modo de
encapsulamento para todo o controle.
C#
this.dataGridView1.DefaultCellStyle.WrapMode =
DataGridViewTriState.True;
Especificar o alinhamento de texto de células

DataGridView
Defina a Alignment propriedade de um DataGridViewCellStyle como um dos
valores de DataGridViewContentAlignment enumeração. O exemplo de código a
seguir define o alinhamento de uma coluna específica usando a DefaultCellStyle
propriedade da coluna.
C#
this.dataGridView1.Columns["CustomerName"].DefaultCellStyle
.Alignment = DataGridViewContentAlignment.MiddleRight;
Exemplo
C#
private void SetFormatting()

{
this.dataGridView1.Columns["UnitPrice"].DefaultCellStyle.Format = "c";
this.dataGridView1.Columns["ShipDate"].DefaultCellStyle.Format = "d";
this.dataGridView1.Columns["CustomerName"].DefaultCellStyle
.Alignment = DataGridViewContentAlignment.MiddleRight;
this.dataGridView1.DefaultCellStyle.NullValue = "no entry";
this.dataGridView1.DefaultCellStyle.WrapMode =
DataGridViewTriState.True;
}
Esses exemplos precisam de:
chamada UnitPrice , uma coluna chamada ShipDate e uma coluna chamada
CustomerName .
Referências aos Systemassemblies , System.Drawinge System.Windows.Forms .
Para escalabilidade máxima, você deve compartilhar DataGridViewCellStyle objetos
entre várias linhas, colunas ou células que usam os mesmos estilos em vez de definir as
propriedades de estilo para cada elemento separadamente. Para obter mais
informações, consulte Práticas recomendadas para colocação em escala do controle
Confira também
Forms
Formatar tipos
Como: Definir estilos de fonte e cor no
Forms
Artigo • 02/06/2023
Você pode especificar a aparência visual das células dentro de um DataGridView

controle definindo as propriedades da DataGridViewCellStyle classe. Você pode
recuperar instâncias dessa classe de várias propriedades da DataGridView classe e suas
classes complementares, ou pode instanciar DataGridViewCellStyle objetos para
atribuição a essas propriedades.
Os procedimentos a seguir demonstram a personalização básica da aparência da célula

usando a DefaultCellStyle propriedade. Todas as células no controle herdam os estilos
especificados por essa propriedade, a menos que eles sejam substituídos no nível da
célula, linha ou coluna. Para obter um exemplo de herança de estilo, consulte Como
definir estilos de célula padrão para o controle DataGridView dos Windows Forms. Para
obter informações sobre usos adicionais da DataGridViewCellStyle classe, consulte os
tópicos listados na seção Consulte Também.
Há um suporte abrangente para esta tarefa no Visual Studio. Consulte também Como
definir estilos de célula padrão e formatos de dados para o controle DataGridView dos
Windows Forms usando o designer.
Para especificar a fonte usada pelas células DataGridView

Defina a Font propriedade de um DataGridViewCellStyle. O exemplo de código a
seguir usa a DataGridView.DefaultCellStyle propriedade para definir a fonte para
todo o controle.
C#
Para especificar as cores de primeiro plano e de tela de

fundo das células DataGridView
Defina as propriedades e BackColor as ForeColor propriedades de um
DataGridViewCellStyle. O exemplo de código a seguir usa a
DataGridView.DefaultCellStyle propriedade para definir esses estilos para todo o
controle.
C#
this.dataGridView1.DefaultCellStyle.ForeColor = Color.Blue;
Para especificar as cores de primeiro plano e de tela de

fundo das células DataGridView selecionadas
Defina as propriedades e SelectionBackColor as SelectionForeColor propriedades
de um DataGridViewCellStyle. O exemplo de código a seguir usa a
DataGridView.DefaultCellStyle propriedade para definir esses estilos para todo o
controle.
C#
this.dataGridView1.DefaultCellStyle.SelectionForeColor = Color.Yellow;
this.dataGridView1.DefaultCellStyle.SelectionBackColor = Color.Black;
Exemplo
C#
private void SetFontAndColors()

{
this.dataGridView1.DefaultCellStyle.ForeColor = Color.Blue;
this.dataGridView1.DefaultCellStyle.SelectionForeColor = Color.Yellow;
this.dataGridView1.DefaultCellStyle.SelectionBackColor = Color.Black;
}

Para obter escalabilidade máxima, você deve compartilhar DataGridViewCellStyle
objetos em várias linhas, colunas ou células que usam os mesmos estilos, em vez de
definir as propriedades de estilo para cada elemento separadamente. Para obter mais
Confira também
Como: Definir estilos de linha alternados
para o controle DataGridView do
Windows Forms
Artigo • 02/06/2023
Dados tabulares geralmente são apresentados aos usuários em um formato contábil no

qual linhas alternativas têm cores de tela de fundo diferente. Esse formato facilita para
os usuários saber quais células estão em cada linha, especialmente com tabelas largas
com muitas colunas.
Com o DataGridView controle, você pode especificar informações de estilo completas

para linhas alternadas. Isso permite usar as características de estilo como cor e fonte de
primeiro plano, além da cor da tela de fundo, para diferenciar as linhas alternadas.
Há suporte para esta tarefa no Visual Studio. Veja também Como definir estilos de linha
alternada para o controle DataGridView dos Windows Forms usando o designer.
Para definir estilos de linha alternada de forma

programática
Defina as propriedades dos DataGridViewCellStyle objetos retornados pela
RowsDefaultCellStyle propriedade do
AlternatingRowsDefaultCellStyleDataGridView.
C#
this.dataGridView1.RowsDefaultCellStyle.BackColor = Color.Bisque;
this.dataGridView1.AlternatingRowsDefaultCellStyle.BackColor =
Color.Beige;
７ Observação
Os estilos especificados usando e as

RowsDefaultCellStyleAlternatingRowsDefaultCellStyle propriedades
substituem os estilos especificados na coluna e DataGridView no nível, mas
são substituídos pelos estilos definidos na linha individual e no nível da célula.
Para obter mais informações, consulte Estilos de célula no controle
Para obter escalabilidade máxima, você deve compartilhar DataGridViewCellStyle
objetos em várias linhas, colunas ou células que usam os mesmos estilos, em vez de
definir as propriedades de estilo para cada elemento separadamente. Para obter mais
Confira também
DataGridView.AlternatingRowsDefaultCellStyle
DataGridView
Windows Forms
Como: Usar o modelo da linha para
personalizar linhas no controle
Artigo • 02/06/2023
O DataGridView controle usa o modelo de linha como base para todas as linhas que ele
adiciona ao controle por meio da associação de dados ou quando você chama o
DataGridViewRowCollection.Add método sem especificar uma linha existente a ser
usada.
O modelo de linha fornece maior controle sobre a aparência e o comportamento das

linhas do que a RowsDefaultCellStyle propriedade fornece. Com o modelo de linha, você
pode definir todas as DataGridViewRow propriedades, incluindo DefaultCellStyle.
Há algumas situações em que você deve usar o modelo de linha para obter um efeito
específico. Por exemplo, as informações de altura da linha não podem ser armazenadas
em um DataGridViewCellStyle, portanto, você deve usar um modelo de linha para alterar
a altura padrão usada por todas as linhas. O modelo de linha também é útil quando
você cria suas próprias classes derivadas DataGridViewRow e deseja que seu tipo
personalizado seja usado quando novas linhas forem adicionadas ao controle.
７ Observação
O modelo de linha é usado somente quando linhas são adicionadas. Você não
pode alterar as linhas existentes alterando o modelo de linha.
Para usar o modelo de linha

Defina as propriedades no objeto recuperado da DataGridView.RowTemplate
propriedade.
C#
DataGridViewRow row = this.dataGridView1.RowTemplate;

row.DefaultCellStyle.BackColor = Color.Bisque;
row.Height = 35;
row.MinimumHeight = 20;
Confira também
DataGridView
DataGridViewRow
DataGridView.RowTemplate
Exibindo dados no controle
Artigo • 02/06/2023
O controle DataGridView é usado para exibir dados de uma variedade de fontes de

dados externas. Como alternativa, você pode adicionar linhas e colunas ao controle e
populá-lo manualmente com os dados.
Ao associar o controle a uma fonte de dados, você pode gerar colunas

automaticamente com base no esquema da fonte de dados. Se essas colunas não
aparecerem como você deseja, você poderá ocultar, remover ou reorganizá-las. Também
é possível adicionar colunas desassociadas para exibir dados complementares que não
vêm da fonte de dados.
Além disso, você pode exibir seus dados usando os formatos padrão (como o formato
de moeda) ou personalizar a formatação da exibição para apresentar os dados como
desejar (como alterar a cor da tela de fundo para números negativos ou substituir os
valores de cadeia de caracteres por imagens correspondentes).
Nesta seção
Modos de exibição dos dados no controle DataGridView dos Windows Forms
Descreve as opções para popular o controle com os dados.

Descreve as opções de formatação de valores de exibição de célula.

Descreve como popular manualmente o controle com os dados.

Descreve como popular o controle com os dados associando-o a um BindingSource que
contém informações extraídas de um banco de dados.
Como: Gerar automaticamente colunas em um controle DataGridView associado a

dados do Windows Forms
Descreve como gerar automaticamente colunas com base em uma fonte de dados
associada.
Como: Remover colunas geradas automaticamente de um controle DataGridView do

Windows Forms
Descreve como ocultar ou excluir colunas geradas automaticamente de uma fonte de
dados associada.

Descreve como reorganizar colunas geradas automaticamente de uma fonte de dados
associada.
Como: Adicionar uma coluna não associada a um controle DataGridView do Windows

Forms associado a dados
Descreve como complementar dados de uma fonte de dados associada exibindo
colunas não associadas adicionais.

Descreve como associar o controle a uma coleção de objetos arbitrários para que cada
objeto seja exibido em sua própria linha.

Descreve como recuperar um objeto associado a uma linha específica do controle.
Instruções passo a passo: criando um formulário mestre/detalhes usando dois controles

Descreve como exibir dados de duas tabelas de banco de dados relacionadas para que
os valores mostrados em um controle DataGridView dependam da linha selecionada no
momento em um outro controle.

Forms
Descreve como manipular o evento para DataGridView.CellFormatting alterar a
aparência das células dependendo de seus valores.
Referência
DataGridView
Fornece documentação de referência para o DataGridView controle .
Fornece a documentação de referência para a DataSource propriedade .
BindingSource
Fornece documentação de referência para o BindingSource componente.
Fornece tópicos que descrevem como alterar os maneira como os usuários adicionam e
modificam dados no controle.
Confira também
Modos de exibição dos dados no
Forms
Artigo • 21/06/2023
O DataGridView controle pode exibir dados em três modos distintos: associado, não
associado e virtual. Escolha o modo mais adequado com base em suas necessidades.
Não Associado
O modo não associado é adequado para exibir quantidades de dados relativamente
pequenas que você gerencia programaticamente. Você não anexa o DataGridView
controle diretamente a uma fonte de dados como no modo associado. Em vez disso,
você deve preencher o controle por conta própria, normalmente usando o
DataGridViewRowCollection.Add método .
O modo não associado pode ser particularmente útil para dados estáticos, somente
leitura ou quando você desejar fornecer seu próprio código que interage com um
armazenamento de dados externo. Quando quiser que os usuários interajam com uma
fonte de dados externa, no entanto, você normalmente usará o modo associado.
Para obter um exemplo que usa um unbound DataGridViewsomente leitura, consulte

How to: Create an Unbound Windows Forms DataGridView Control.
Bound
O modo associado é adequado para gerenciar dados usando a interação automática
com o armazenamento de dados. Você pode anexar o DataGridView controle
diretamente à fonte de dados definindo a DataSource propriedade . Quando o controle
for associado aos dados, as linhas de dados serão enviadas e recebidas sem a
necessidade de gerenciamento explícito da sua parte. Quando a AutoGenerateColumns
propriedade for true , cada coluna na fonte de dados fará com que uma coluna
correspondente seja criada no controle . Se preferir criar suas próprias colunas, você
poderá definir essa propriedade como false e usar a DataPropertyName propriedade
para associar cada coluna ao configurá-la. Isso é útil quando você deseja usar um tipo
de coluna diferente dos tipos que são gerados por padrão. Para obter mais informações,
consulte Tipos de coluna no controle DataGridView dos Windows Forms.
Para obter um exemplo que usa um controle associadoDataGridView, consulte Passo a
passo: validando dados no controle DataGridView Windows Forms.
Você também pode adicionar colunas não associadas a um DataGridView controle no

modo associado. Isso é útil quando você deseja exibir uma coluna de botões ou links
que permitem aos usuários executar ações em linhas específicas. Também é útil exibir as
colunas com valores calculados de colunas associadas. Você pode preencher os valores
de célula para colunas calculadas em um manipulador para o CellFormatting evento. No
entanto, se você estiver usando um DataSet ou DataTable como a fonte de dados, talvez
queira usar a DataColumn.Expression propriedade para criar uma coluna calculada.
Nesse caso, o controle tratará a DataGridView coluna calculada como qualquer outra
coluna na fonte de dados.
Não há suporte para a classificação por colunas não associadas no modo associado. Se
criar uma coluna não associada no modo associado que contenha os valores editáveis
pelo usuário, você deverá implementar o modo virtual para manter esses valores
quando o controle for classificado por uma coluna associada.
Máquina
Com o modo virtual, você pode implementar suas próprias operações de
gerenciamento de dados. Isso é necessário para manter os valores das colunas não
associadas no modo associado quando o controle for classificado por colunas
associadas. No entanto, o uso principal do modo virtual é otimizar o desempenho ao
interagir com grandes quantidades de dados.
Você anexa o DataGridView controle a um cache gerenciado e seus controles de código

quando as linhas de dados são enviadas por push e efetuadas pull. Para manter o
volume de memória pequeno, o cache deve ser semelhante em tamanho ao número de
linhas exibidas atualmente. Quando o usuário rola novas linhas no modo de exibição,
seu código solicita novos dados do cache e, como alternativa, libera os dados antigos
da memória.
Quando estiver implementando o modo virtual, você precisará controlar quando uma
nova linha for necessária no modelo de dados e o momento para reverter a adição da
nova linha. A implementação dessa funcionalidade exata dependerá da implementação
do modelo de dados e da semântica de transação do modelo de dados; se o escopo de
confirmação está no nível da célula ou da linha.
Para obter mais informações sobre o modo virtual, consulte Como implementar o modo
virtual no controle DataGridView dos Windows Forms. Para obter um exemplo que
mostra como usar os eventos de modo virtual, consulte Instruções passo a passo:
implementando o modo virtual no controle DataGridView dos Windows Forms.
Confira também
DataGridView
DataGridView.VirtualMode
BindingSource
DataGridViewColumn.DataPropertyName
Modo virtual no controle DataGridView dos Windows Forms
Windows Forms
Formatação de dados no controle
Artigo • 02/06/2023
O DataGridView controle fornece conversão automática entre valores de célula e os

tipos de dados que as colunas pai exibem. Colunas da caixa de texto, por exemplo,
exibem representações de valores de data, hora, número e enumeração, e convertem
valores de cadeia de caracteres inseridos pelo usuário nos tipos necessários para o
armazenamento de dados.
Formatação com a classe

O DataGridView controle fornece formatação de dados básica de valores de célula por
meio da DataGridViewCellStyle classe. Você pode usar a Format propriedade para
formatar valores de data, hora, número e enumeração para a cultura padrão atual
usando os especificadores de formato descritos em Tipos de Formatação. Você também
pode formatar esses valores para culturas específicas usando a FormatProvider
propriedade. O formato especificado é usado para exibir dados e analisar dados
digitados pelo usuário no formato especificado.
A DataGridViewCellStyle classe fornece propriedades de formatação adicionais para o

wordwrap, o alinhamento de texto e a exibição personalizada de valores nulos de banco
de dados. Para obter mais informações, consulte Como formatar dados no controle
Formatação com o evento CellFormatting

Se a formatação básica não atender às suas necessidades, você poderá fornecer
formatação de dados personalizada em um manipulador para o
DataGridView.CellFormatting evento. O DataGridViewCellFormattingEventArgs
manipulador passado tem uma Value propriedade que inicialmente contém o valor da
célula. Normalmente, esse valor é automaticamente convertido no tipo de exibição. Para
converter o valor por conta própria, defina a Value propriedade como um valor do tipo
de exibição.
７ Observação
Se uma cadeia de caracteres de formato estiver em vigor para a célula, ela
substituirá a Value alteração do valor da propriedade, a menos que você defina a
FormattingApplied propriedade como true .
O CellFormatting evento também é útil quando você deseja definir

DataGridViewCellStyle propriedades para células individuais com base em seus valores.
Para obter mais informações, consulte Como personalizar a formatação de dados no
controle DataGridView do Windows Forms.
Se a análise padrão de valores especificados pelo usuário não atender às suas

necessidades, você poderá manipular o CellParsing evento do DataGridView controle
para fornecer análise personalizada.
Confira também
DataGridView
Forms
Passo a passo: Criar um controle não
associado DataGridView do Windows
Forms
Artigo • 21/06/2023
Você pode querer exibir com frequência dados tabulares que não se originam de um
banco de dados. Por exemplo, você talvez queira mostrar o conteúdo de uma matriz
bidimensional de cadeias de caracteres. A DataGridView classe fornece uma maneira
fácil e altamente personalizável de exibir dados sem associação a uma fonte de dados.
Este passo a passo mostra como preencher um DataGridView controle e gerenciar a
adição e exclusão de linhas no modo "não associado". Por padrão, o usuário pode
adicionar novas linhas. Para evitar a adição de linha, defina que a AllowUserToAddRows
propriedade é false .
Para copiar o código deste tópico como uma única lista, consulte Como criar um
controle DataGridView não associado do Windows Forms.
Criando o formulário
Para usar um controle DataGridView não associado

1. Crie uma classe que deriva de Form e contém as seguintes declarações de variável
e Main método.
C#
using System;

{
private Panel buttonPanel = new Panel();
private DataGridView songsDataGridView = new DataGridView();
private Button addNewRowButton = new Button();
private Button deleteRowButton = new Button();
C#
[STAThreadAttribute()]
static void Main()
{
}
}
2. Implemente um método SetupLayout na definição de classe do formulário para

configurar o layout do formulário.
C#
private void SetupLayout()

{
addNewRowButton.Text = "Add Row";

addNewRowButton.Location = new Point(10, 10);
addNewRowButton.Click += new EventHandler(addNewRowButton_Click);
deleteRowButton.Text = "Delete Row";

deleteRowButton.Location = new Point(100, 10);
deleteRowButton.Click += new EventHandler(deleteRowButton_Click);
buttonPanel.Controls.Add(addNewRowButton);
buttonPanel.Controls.Add(deleteRowButton);
buttonPanel.Height = 50;
buttonPanel.Dock = DockStyle.Bottom;
this.Controls.Add(this.buttonPanel);
}
3. Crie um SetupDataGridView método para configurar as DataGridView colunas e as

propriedades.
Esse método primeiro adiciona o DataGridView controle à coleção do Controls

formulário. Em seguida, o número de colunas a serem exibidas é definido usando a
ColumnCount propriedade . O estilo padrão para os cabeçalhos de coluna é
definido definindo as BackColorpropriedades , ForeColore Font do
DataGridViewCellStyle retornado pela ColumnHeadersDefaultCellStyle propriedade
.
Propriedades de aparência e layout são definidas e, em seguida, os nomes de

coluna são atribuídos. Quando esse método for encerrado, o DataGridView
controle estará pronto para ser preenchido.
C#
private void SetupDataGridView()
{
this.Controls.Add(songsDataGridView);
songsDataGridView.ColumnCount = 5;
songsDataGridView.ColumnHeadersDefaultCellStyle.BackColor =
Color.Navy;
songsDataGridView.ColumnHeadersDefaultCellStyle.ForeColor =
Color.White;
songsDataGridView.ColumnHeadersDefaultCellStyle.Font =
new Font(songsDataGridView.Font, FontStyle.Bold);
songsDataGridView.Name = "songsDataGridView";
songsDataGridView.Location = new Point(8, 8);
songsDataGridView.Size = new Size(500, 250);
songsDataGridView.AutoSizeRowsMode =
DataGridViewAutoSizeRowsMode.DisplayedCellsExceptHeaders;
songsDataGridView.ColumnHeadersBorderStyle =
songsDataGridView.CellBorderStyle =
DataGridViewCellBorderStyle.Single;
songsDataGridView.GridColor = Color.Black;
songsDataGridView.RowHeadersVisible = false;
songsDataGridView.Columns[0].Name = "Release Date";

songsDataGridView.Columns[1].Name = "Track";
songsDataGridView.Columns[2].Name = "Title";
songsDataGridView.Columns[3].Name = "Artist";
songsDataGridView.Columns[4].Name = "Album";
songsDataGridView.Columns[4].DefaultCellStyle.Font =
new Font(songsDataGridView.DefaultCellStyle.Font,
FontStyle.Italic);
songsDataGridView.SelectionMode =
DataGridViewSelectionMode.FullRowSelect;
songsDataGridView.MultiSelect = false;
songsDataGridView.Dock = DockStyle.Fill;
songsDataGridView.CellFormatting += new
DataGridViewCellFormattingEventHandler(
songsDataGridView_CellFormatting);
}
4. Crie um PopulateDataGridView método para adicionar linhas ao DataGridView

controle .
Cada linha representa uma música e suas informações associadas.
C#
private void PopulateDataGridView()
{
string[] row0 = { "11/22/1968", "29", "Revolution 9",

"Beatles", "The Beatles [White Album]" };
string[] row1 = { "1960", "6", "Fools Rush In",
"Frank Sinatra", "Nice 'N' Easy" };
string[] row2 = { "11/11/1971", "1", "One of These Days",
"Pink Floyd", "Meddle" };
string[] row3 = { "1988", "7", "Where Is My Mind?",
"Pixies", "Surfer Rosa" };
string[] row4 = { "5/1981", "9", "Can't Find My Mind",
"Cramps", "Psychedelic Jungle" };
string[] row5 = { "6/10/2003", "13",
"Scatterbrain. (As Dead As Leaves.)",
"Radiohead", "Hail to the Thief" };
string[] row6 = { "6/30/1992", "3", "Dress", "P J Harvey", "Dry" };
songsDataGridView.Rows.Add(row0);
songsDataGridView.Columns[0].DisplayIndex = 3;
}
5. Com os métodos de utilitário em vigor, você pode anexar manipuladores de

eventos.
Você manipulará os eventos dos Click botões Adicionar e Excluir, o evento do

Load formulário e o DataGridView evento do CellFormatting controle.
Quando o evento do Click botão Adicionar é acionado, uma nova linha vazia é
adicionada ao DataGridView.
Quando o evento do Click botão Excluir é acionado, a linha selecionada é excluída,

a menos que seja a linha para novos registros, o que permite que o usuário
adicione novas linhas. Essa linha é sempre a última linha no DataGridView controle.
Quando o evento do Load formulário é acionado, os SetupLayout métodos

utilitários , SetupDataGridView e PopulateDataGridView são chamados.
Quando o CellFormatting evento é gerado, cada célula na Date coluna é
formatada como uma data longa, a menos que o valor da célula não possa ser
analisado.
C#
public Form1()
{
}

{
SetupLayout();
SetupDataGridView();
PopulateDataGridView();
}
private void songsDataGridView_CellFormatting(object sender,

System.Windows.Forms.DataGridViewCellFormattingEventArgs e)
{
if (e != null)
{
if (this.songsDataGridView.Columns[e.ColumnIndex].Name ==
"Release Date")
{
if (e.Value != null)
{
try
{
e.Value = DateTime.Parse(e.Value.ToString())
.ToLongDateString();
e.FormattingApplied = true;
}
catch (FormatException)
{
Console.WriteLine("{0} is not a valid date.",
e.Value.ToString());
}
}
}
}
}
private void addNewRowButton_Click(object sender, EventArgs e)

{
this.songsDataGridView.Rows.Add();
}
private void deleteRowButton_Click(object sender, EventArgs e)

{
if (this.songsDataGridView.SelectedRows.Count > 0 &&
this.songsDataGridView.SelectedRows[0].Index !=
this.songsDataGridView.Rows.Count - 1)
{
this.songsDataGridView.Rows.RemoveAt(
this.songsDataGridView.SelectedRows[0].Index);
}
}
Testando o aplicativo
Agora, é possível testar o formulário para garantir que ele se comporta da forma
esperada.
Para testar o formulário

Pressione F5 para executar o aplicativo.
Você verá um DataGridView controle que exibe as músicas listadas em

PopulateDataGridView . Você pode adicionar novas linhas com o botão Adicionar
Linha e excluir linhas selecionadas com o botão Excluir Linha. O controle não
associado DataGridView é o armazenamento de dados e seus dados são
independentes de qualquer fonte externa, como uma DataSet matriz ou .
Próximas etapas
Esse aplicativo fornece uma compreensão básica dos DataGridView recursos do
controle. Você pode personalizar a aparência e o DataGridView comportamento do
controle de várias maneiras:
Alterar estilos de borda e cabeçalho. Para obter mais informações, consulte Como
alterar os estilos de borda e linha de grade no controle DataGridView dos
Windows Forms.
Habilite ou restrinja a entrada do usuário no DataGridView controle. Para obter

mais informações, consulte Como evitar a adição e a exclusão de linhas no
controle DataGridView dos Windows Forms e Como transformar colunas em
somente leitura no controle DataGridView dos Windows Forms.
Verifique a entrada do usuário para erros relacionados ao banco de dados. Para

obter mais informações, consulte Instruções passo a passo: identificando erros que
ocorrem durante a entrada de dados no controle DataGridView do Windows
Forms.
Manipule grandes conjuntos de dados usando o modo virtual. Para obter mais
informações, consulte Passo a passo: implementando o modo virtual no controle
Personalize a aparência das células. Para obter mais informações, consulte Como
personalizar a aparência de células no controle DataGridView dos Windows Forms
e Como definir estilos de célula padrão no controle DataGridView dos Windows
Forms.
Confira também
DataGridView
Como: Criar um controle não associado DataGridView do Windows Forms
Como: Criar um controle não associado
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como popular um controle DataGridView

programaticamente sem a associação dele a uma fonte de dados. Isso é útil quando
você tem uma pequena quantidade de dados que deseja exibir em um formato de
tabela.
Para ver uma explicação completa desse exemplo de código, consulte Passo a passo:
criando um controle DataGridView de Windows Forms não Windows.
Exemplo
C#
using System;

{
private Panel buttonPanel = new Panel();
private DataGridView songsDataGridView = new DataGridView();
private Button addNewRowButton = new Button();
private Button deleteRowButton = new Button();
public Form1()
{
}

{
SetupLayout();
SetupDataGridView();
}
private void songsDataGridView_CellFormatting(object sender,

{
if (e != null)
{
if (this.songsDataGridView.Columns[e.ColumnIndex].Name ==
"Release Date")
{
{
try
{
e.Value = DateTime.Parse(e.Value.ToString())
.ToLongDateString();
e.FormattingApplied = true;
}
catch (FormatException)
{
Console.WriteLine("{0} is not a valid date.",
e.Value.ToString());
}
}
}
}
}
private void addNewRowButton_Click(object sender, EventArgs e)

{
this.songsDataGridView.Rows.Add();
}
private void deleteRowButton_Click(object sender, EventArgs e)

{
if (this.songsDataGridView.SelectedRows.Count > 0 &&
this.songsDataGridView.SelectedRows[0].Index !=
this.songsDataGridView.Rows.Count - 1)
{
this.songsDataGridView.Rows.RemoveAt(
this.songsDataGridView.SelectedRows[0].Index);
}
}
private void SetupLayout()

{
addNewRowButton.Text = "Add Row";

addNewRowButton.Location = new Point(10, 10);
addNewRowButton.Click += new EventHandler(addNewRowButton_Click);
deleteRowButton.Text = "Delete Row";

deleteRowButton.Location = new Point(100, 10);
deleteRowButton.Click += new EventHandler(deleteRowButton_Click);
buttonPanel.Controls.Add(addNewRowButton);
buttonPanel.Controls.Add(deleteRowButton);
buttonPanel.Height = 50;
buttonPanel.Dock = DockStyle.Bottom;
this.Controls.Add(this.buttonPanel);
}
private void SetupDataGridView()

{
this.Controls.Add(songsDataGridView);
songsDataGridView.ColumnCount = 5;
songsDataGridView.ColumnHeadersDefaultCellStyle.BackColor =
Color.Navy;
songsDataGridView.ColumnHeadersDefaultCellStyle.ForeColor =
Color.White;
songsDataGridView.ColumnHeadersDefaultCellStyle.Font =
new Font(songsDataGridView.Font, FontStyle.Bold);
songsDataGridView.Name = "songsDataGridView";
songsDataGridView.Location = new Point(8, 8);
songsDataGridView.Size = new Size(500, 250);
songsDataGridView.AutoSizeRowsMode =
DataGridViewAutoSizeRowsMode.DisplayedCellsExceptHeaders;
songsDataGridView.ColumnHeadersBorderStyle =
songsDataGridView.CellBorderStyle =
DataGridViewCellBorderStyle.Single;
songsDataGridView.GridColor = Color.Black;
songsDataGridView.RowHeadersVisible = false;
songsDataGridView.Columns[0].Name = "Release Date";

songsDataGridView.Columns[1].Name = "Track";
songsDataGridView.Columns[2].Name = "Title";
songsDataGridView.Columns[3].Name = "Artist";
songsDataGridView.Columns[4].Name = "Album";
songsDataGridView.Columns[4].DefaultCellStyle.Font =
new Font(songsDataGridView.DefaultCellStyle.Font,
FontStyle.Italic);
songsDataGridView.SelectionMode =
songsDataGridView.MultiSelect = false;
songsDataGridView.Dock = DockStyle.Fill;
songsDataGridView.CellFormatting += new
DataGridViewCellFormattingEventHandler(
songsDataGridView_CellFormatting);
}

{
string[] row0 = { "11/22/1968", "29", "Revolution 9",

"Beatles", "The Beatles [White Album]" };
string[] row1 = { "1960", "6", "Fools Rush In",
"Frank Sinatra", "Nice 'N' Easy" };
string[] row2 = { "11/11/1971", "1", "One of These Days",
"Pink Floyd", "Meddle" };
string[] row3 = { "1988", "7", "Where Is My Mind?",
"Pixies", "Surfer Rosa" };
string[] row4 = { "5/1981", "9", "Can't Find My Mind",
"Cramps", "Psychedelic Jungle" };
string[] row5 = { "6/10/2003", "13",
"Scatterbrain. (As Dead As Leaves.)",
"Radiohead", "Hail to the Thief" };
string[] row6 = { "6/30/1992", "3", "Dress", "P J Harvey", "Dry" };
}
static void Main()
{
}
}
Confira também
DataGridView
Como associar dados ao controle
Windows Forms DataGridView
Artigo • 21/06/2023
O DataGridView controle dá suporte ao modelo de associação de dados Windows

Forms padrão, para que ele possa se associar a uma variedade de fontes de dados.
Normalmente, você associa a um BindingSource que gerencia a interação com a fonte
de dados. O BindingSource pode ser qualquer fonte de dados Windows Forms, o que
oferece grande flexibilidade ao escolher ou modificar a localização dos dados. Para
obter mais informações sobre fontes de dados compatíveis com o DataGridView
controle, consulte a Visão geral do controle DataGridView.
O Visual Studio tem amplo suporte para associação de dados ao controle DataGridView.
Para obter mais informações, consulte Como associar dados ao controle Windows
Forms DataGridView usando o Designer.
Para conectar um controle DataGridView aos dados:
1. Implemente um método para lidar com os detalhes da recuperação dos dados. O

exemplo de código a seguir implementa um GetData método que inicializa um
SqlDataAdaptere o usa para preencher um DataTable. Em seguida, ele associa o
DataTable ao BindingSource.
2. No manipulador de eventos do Load formulário, associe o DataGridView controle

ao BindingSourcee chame o GetData método para recuperar os dados.
Exemplo
Este exemplo de código completo recupera dados de um banco de dados para
preencher um controle DataGridView em um formulário do Windows. O formulário
também tem botões para recarregar dados e enviar alterações ao banco de dados.
Acesso a um banco de dados de exemplo do Northwind SQL Server. Para obter

mais informações sobre como instalar o banco de dados de exemplo Northwind,
consulte Obter os bancos de dados de exemplo para ADO.NET exemplos de
código.
Referências aos assemblies System, System.Windows.Forms, System.Data e

System.Xml.
Para compilar e executar este exemplo, cole o código no arquivo de código Form1 em
um novo projeto de Windows Forms. Para obter informações sobre como compilar a
partir da linha de comando do C# ou do Visual Basic, consulte Compilação de linha de
comando com csc.exe ou Compilar na linha de comando.
Preencha a connectionString variável no exemplo com os valores para a conexão de

banco de dados de exemplo SQL Server Northwind. A Autenticação do Windows,
também chamada de segurança integrada, é uma maneira mais segura de se conectar
ao banco de dados do que armazenar uma senha na cadeia de conexão. Para obter mais
informações sobre segurança de conexão, consulte Proteger informações de conexão.
C#
using System;
using System.Data;
using System.Globalization;
namespace WindowsFormsApp
{
{
public Form1()
{
}
}
}
{
private DataGridView dataGridView1 = new DataGridView();
private BindingSource bindingSource1 = new BindingSource();
private SqlDataAdapter dataAdapter = new SqlDataAdapter();
private Button reloadButton = new Button();
private Button submitButton = new Button();
[STAThread()]
{
}
// Initialize the form.

public Form1()
{
dataGridView1.Dock = DockStyle.Fill;
reloadButton.Text = "Reload";
submitButton.Text = "Submit";
reloadButton.Click += new EventHandler(ReloadButton_Click);
submitButton.Click += new EventHandler(SubmitButton_Click);
FlowLayoutPanel panel = new FlowLayoutPanel

{
Dock = DockStyle.Top,
AutoSize = true
};
panel.Controls.AddRange(new Control[] { reloadButton, submitButton
});
Controls.AddRange(new Control[] { dataGridView1, panel });

Load += new EventHandler(Form1_Load);
Text = "DataGridView data binding and updating demo";
}
private void GetData(string selectCommand)

{
try
{
// Specify a connection string.
// Replace <SQL Server> with the SQL Server for your Northwind
sample database.
// Replace "Integrated Security=True" with user login
information if necessary.
String connectionString =
"Data Source=<SQL Server>;Initial Catalog=Northwind;" +
"Integrated Security=True";
// Create a new data adapter based on the specified query.

dataAdapter = new SqlDataAdapter(selectCommand,
connectionString);
// Create a command builder to generate SQL update, insert, and

// delete commands based on selectCommand.
SqlCommandBuilder commandBuilder = new
SqlCommandBuilder(dataAdapter);
// Populate a new data table and bind it to the BindingSource.

DataTable table = new DataTable
{
Locale = CultureInfo.InvariantCulture
};
dataAdapter.Fill(table);
bindingSource1.DataSource = table;
// Resize the DataGridView columns to fit the newly loaded

content.
dataGridView1.AutoResizeColumns(
DataGridViewAutoSizeColumnsMode.AllCellsExceptHeader);
}
catch (SqlException)
{
MessageBox.Show("To run this example, replace the value of the "
+
"connectionString variable with a connection string that is
" +
"valid for your system.");
}
}

{
// Bind the DataGridView to the BindingSource
// and load the data from the database.
dataGridView1.DataSource = bindingSource1;
GetData("select * from Customers");
}
private void ReloadButton_Click(object sender, EventArgs e)

{
// Reload the data from the database.
GetData(dataAdapter.SelectCommand.CommandText);
}
private void SubmitButton_Click(object sender, EventArgs e)

{
// Update the database with changes.
dataAdapter.Update((DataTable)bindingSource1.DataSource);
}
}
Confira também
DataGridView
BindingSource
Exibir dados no controle Windows Forms DataGridView
Proteger informações de conexão
Como: Gerar automaticamente colunas
em um controle DataGridView
associado a dados do Windows Forms
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como exibir colunas de uma fonte de dados
associada em um DataGridView controle. Quando o valor da AutoGenerateColumns
propriedade é true (o padrão), um DataGridViewColumn é criado para cada coluna na
tabela de fonte de dados.
Se o DataGridView controle já tiver colunas quando você definir a DataSource

propriedade, as colunas associadas existentes serão comparadas com as colunas na
fonte de dados e preservadas sempre que houver uma correspondência. Colunas não
associadas sempre são preservadas. As colunas associadas para as quais não há
nenhuma correspondência na fonte de dados são removidas. As colunas na fonte de
dados para as quais não há correspondência no controle geram novos
DataGridViewColumn objetos, que são adicionados ao final da Columns coleção.
Exemplo
C#
private void BindData()

{
customersDataGridView.AutoGenerateColumns = true;
customersDataGridView.DataSource = customersDataSet;
customersDataGridView.DataMember = "Customers";
}
Um controle DataGridView chamado customersDataGridView .
Um DataSet objeto chamado customersDataSet que tem uma tabela chamada

Customers .
Referências a assembliesSystemSystem.Windows.FormsSystem.Data, e System.Xml

assemblies.
Confira também
DataGridView
DataGridView.AutoGenerateColumns
do Windows Forms
Como: Remover colunas geradas
automaticamente de um controle
Artigo • 02/06/2023
Quando o DataGridView controle é definido para gerar automaticamente suas colunas

com base em dados de sua fonte de dados, você pode omitir seletivamente
determinadas colunas. Você pode fazer isso chamando o Remove método na Columns
coleção. Como alternativa, você pode ocultar colunas do modo de exibição definindo a
Visible propriedade como false . Essa técnica é útil quando você deseja exibir as
colunas ocultas em determinadas condições ou quando você precisa acessar os dados
nas colunas sem exibi-lo.
Para remover colunas geradas automaticamente

Chame o Remove método na Columns coleção.
C#
dataGridView1.AutoGenerateColumns = true;
dataGridView1.DataSource = customersDataSet;
dataGridView1.Columns.Remove("Fax");
Para ocultar colunas geradas automaticamente

Defina a propriedade da Visible coluna como false .
C#
dataGridView1.Columns["CustomerID"].Visible = false;
Exemplo
C#
private void BindDataAndInitializeColumns()

{
dataGridView1.AutoGenerateColumns = true;
dataGridView1.DataSource = customersDataSet;
dataGridView1.Columns.Remove("Fax");
dataGridView1.Columns["CustomerID"].Visible = false;
}
Um DataGridView controle nomeado dataGridView1 associado a uma tabela que

contém Fax e CustomerID colunas, como a Customers tabela no banco de dados
de exemplo Northwind.
Confira também
DataGridView
DataGridView.AutoGenerateColumns
DataGridView.Columns
DataGridViewColumnCollection.Remove
Como: Alterar a ordem de colunas no
Forms
Artigo • 02/06/2023
Quando você usa um DataGridView para exibir dados de uma fonte de dados, as
colunas no esquema da fonte de dados às vezes não aparecem na ordem em que você
gostaria de exibi-los. Você pode alterar a ordem exibida das colunas usando a
DisplayIndex propriedade da DataGridViewColumn classe.
O exemplo de código a seguir reposiciona algumas das colunas geradas

automaticamente ao se associar à tabela Clientes no banco de dados de exemplo
Northwind. Para obter mais informações sobre como associar o DataGridView controle a
uma tabela de banco de dados, consulte Como associar dados ao controle Windows
Forms DataGridView.
Há suporte para esta tarefa no Visual Studio. Veja também como alterar a ordem das
colunas no controle Windows Forms DataGridView usando o designer.
Exemplo
C#
private void AdjustColumnOrder()

{
customersDataGridView.Columns["CustomerID"].Visible = false;
customersDataGridView.Columns["ContactName"].DisplayIndex = 0;
customersDataGridView.Columns["ContactTitle"].DisplayIndex = 1;
customersDataGridView.Columns["City"].DisplayIndex = 2;
customersDataGridView.Columns["Country"].DisplayIndex = 3;
customersDataGridView.Columns["CompanyName"].DisplayIndex = 4;
}
Um DataGridView controle nomeado customersDataGridView que está associado a

uma tabela com os nomes de coluna indicados, como a Customers tabela no
banco de dados de exemplo Northwind.
Referências a assembliesSystemSystem.Windows.FormsSystem.Data, e System.Xml
assemblies.
Confira também
DataGridView
DataGridViewColumn
DataGridViewColumn.DisplayIndex
Como: Adicionar uma coluna não
associada a um controle DataGridView
do Windows Forms associado a dados
Artigo • 21/06/2023
Os dados exibidos no DataGridView controle normalmente virão de uma fonte de dados

de algum tipo, mas talvez você queira exibir uma coluna de dados que não vem da
fonte de dados. Esse tipo de coluna é chamado de coluna não associada. Colunas não
associadas podem assumir várias formas. Frequentemente, elas são usadas para
fornecer acesso aos detalhes de uma linha de dados.
O exemplo de código a seguir demonstra como criar uma coluna não associada dos
botões de Detalhes para exibir uma tabela filho relacionada a uma linha específica em
uma tabela pai quando você implementa um cenário mestre/de detalhes. Para
responder a cliques de botão, implemente um DataGridView.CellClick manipulador de
eventos que exibe um formulário que contém a tabela filho.
Há suporte para esta tarefa no Visual Studio. Consulte também Como adicionar e
remover colunas no Windows Forms controle DataGridView usando o Designer.
Exemplo
C#
private void CreateUnboundButtonColumn()

{
// Initialize the button column.
DataGridViewButtonColumn buttonColumn =
new DataGridViewButtonColumn();
buttonColumn.Name = "Details";
buttonColumn.HeaderText = "Details";
buttonColumn.Text = "View Details";
// Use the Text property for the button text for all cells rather
// than using each cell's value as the text for its own button.
buttonColumn.UseColumnTextForButtonValue = true;
// Add the button column to the control.

dataGridView1.Columns.Insert(0, buttonColumn);
}
Confira também
DataGridView
Como associar objetos a controles
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como associar uma coleção de objetos a um

DataGridView controle para que cada objeto seja exibido como uma linha separada.
Este exemplo também ilustra como exibir uma propriedade com um tipo de
enumeração em um DataGridViewComboBoxColumn para que a lista suspensa caixa de
combinação contenha os valores de enumeração.
Exemplo
C#
using System;
public enum Title
{
King,
Sir
};
public class EnumsAndComboBox : Form
{
public EnumsAndComboBox()
{
this.Load += new System.EventHandler(EnumsAndComboBox_Load);
}
private void EnumsAndComboBox_Load(object sender, System.EventArgs e)

{
// Populate the data source.
bindingSource1.Add(new Knight(Title.King, "Uther", true));
bindingSource1.Add(new Knight(Title.King, "Arthur", true));
bindingSource1.Add(new Knight(Title.Sir, "Mordred", false));
bindingSource1.Add(new Knight(Title.Sir, "Gawain", true));
bindingSource1.Add(new Knight(Title.Sir, "Galahad", true));
// Initialize the DataGridView.

dataGridView1.AutoGenerateColumns = false;
dataGridView1.AutoSize = true;
dataGridView1.DataSource = bindingSource1;
dataGridView1.Columns.Add(CreateComboBoxWithEnums());
// Initialize and add a text box column.
DataGridViewColumn column = new DataGridViewTextBoxColumn();
column.DataPropertyName = "Name";
column.Name = "Knight";
dataGridView1.Columns.Add(column);
// Initialize and add a check box column.

column = new DataGridViewCheckBoxColumn();
column.DataPropertyName = "GoodGuy";
column.Name = "Good";

this.Controls.Add(dataGridView1);
this.AutoSize = true;
this.Text = "DataGridView object binding demo";
}
DataGridViewComboBoxColumn CreateComboBoxWithEnums()
{
DataGridViewComboBoxColumn combo = new DataGridViewComboBoxColumn();
combo.DataSource = Enum.GetValues(typeof(Title));
combo.DataPropertyName = "Title";
combo.Name = "Title";
return combo;
}
#region "business object"
private class Knight
{
private string hisName;
private bool good;
private Title hisTitle;
public Knight(Title title, string name, bool good)

{
hisTitle = title;
hisName = name;
this.good = good;
}
public Knight()
{
hisTitle = Title.Sir;
hisName = "<enter name>";
good = true;
}
public string Name

{
get
{
return hisName;
}
set
{
hisName = value;
}
}
public bool GoodGuy

{
get
{
return good;
}
set
{
good = value;
}
}
public Title Title

{
get
{
return hisTitle;
}
set
{
hisTitle = value;
}
}
}
#endregion
[STAThread]
{
Application.Run(new EnumsAndComboBox());
}
}
Confira também
DataGridView
Como acessar objetos associados a
linhas DataGridView dos Windows
Forms
Artigo • 21/06/2023
Às vezes, é útil exibir uma tabela de informações armazenadas em uma coleção de

objetos de negócios. Quando você associa um DataGridView controle a essa coleção,
cada propriedade pública é exibida em sua própria coluna, a menos que a propriedade
tenha sido marcada como não navegável com um BrowsableAttribute. Por exemplo,
uma coleção de objetos Customer teria colunas como Nome e Endereço.
Se esses objetos contiverem informações adicionais e o código que você deseja acessar,
será possível alcançá-lo por meio de objetos de linha. No exemplo de código a seguir,
os usuários podem selecionar várias linhas e clicar em um botão para enviar uma fatura
para cada um dos clientes correspondentes.
Para acessar objetos associados a linhas

Use a propriedade DataGridViewRow.DataBoundItem.
C#
void invoiceButton_Click(object sender, EventArgs e)

{
foreach (DataGridViewRow row in this.dataGridView1.SelectedRows)
{
Customer cust = row.DataBoundItem as Customer;
if (cust != null)
{
cust.SendInvoice();
}
}
}
Exemplo
O exemplo de código completo inclui uma implementação simples Customer e associa o
DataGridView a um ArrayList que contém alguns Customer objetos. O Click manipulador
de eventos do System.Windows.Forms.Button deve acessar os Customer objetos por
meio das linhas, pois a coleção de clientes não está acessível fora do manipulador de
Form.Load eventos.
C#
using System;
public class DataGridViewObjectBinding : Form

{
// These declarations and the Main() and New() methods
// below can be replaced with designer-generated code.
private Button invoiceButton = new Button();
// Entry point code.

{
Application.Run(new DataGridViewObjectBinding());
}
// Sets up the form.

public DataGridViewObjectBinding()
{
this.dataGridView1.Dock = DockStyle.Fill;
this.Controls.Add(this.dataGridView1);
this.invoiceButton.Text = "invoice the selected customers";

this.invoiceButton.Dock = DockStyle.Top;
this.invoiceButton.Click += new EventHandler(invoiceButton_Click);
this.Controls.Add(this.invoiceButton);
this.Load += new EventHandler(DataGridViewObjectBinding_Load);

this.Text = "DataGridView collection-binding demo";
}
void DataGridViewObjectBinding_Load(object sender, EventArgs e)

{
// Set up a collection of objects for binding.
System.Collections.ArrayList customers = new
System.Collections.ArrayList();
customers.Add(new Customer("Harry"));
customers.Add(new Customer("Sally"));
customers.Add(new Customer("Roy"));
customers.Add(new Customer("Pris"));
// Initialize and bind the DataGridView.

this.dataGridView1.SelectionMode =
this.dataGridView1.AutoGenerateColumns = true;
this.dataGridView1.DataSource = customers;
}
// Calls the SendInvoice() method for the Customer
// object bound to each selected row.
void invoiceButton_Click(object sender, EventArgs e)
{
foreach (DataGridViewRow row in this.dataGridView1.SelectedRows)
{
Customer cust = row.DataBoundItem as Customer;
if (cust != null)
{
cust.SendInvoice();
}
}
}
}
public class Customer

{
private String nameValue;
public Customer(String name)

{
nameValue = name;
}
public String Name

{
get
{
return nameValue;
}
set
{
nameValue = value;
}
}
public void SendInvoice()

{
MessageBox.Show(nameValue + " has been billed.");
}
}
Confira também
DataGridView
DataGridViewRow
DataGridViewRow.DataBoundItem
Como: Acessar objetos de acesso em
uma lista suspensa
DataGridViewComboBoxCell do
Windows Forms
Artigo • 02/06/2023
Assim como o ComboBox controle, os tipos e DataGridViewComboBoxCell os

DataGridViewComboBoxColumn tipos permitem adicionar objetos arbitrários às listas
suspensas. Com esse recurso, você pode representar estados complexos em uma lista
suspensa sem a necessidade de armazenar objetos correspondentes em uma coleção
separada.
Ao contrário do ComboBox controle, os DataGridView tipos não têm uma SelectedItem

propriedade para recuperar o objeto selecionado no momento. Em vez disso, você deve
definir a DataGridViewComboBoxColumn.ValueMember propriedade ou
DataGridViewComboBoxCell.ValueMember o nome de uma propriedade em seu objeto
comercial. Quando o usuário faz uma seleção, a propriedade indicada do objeto de
negócios define a propriedade da célula Value .
Para recuperar o objeto comercial por meio do valor de célula, a propriedade

ValueMember deve indicar uma propriedade que retorne uma referência ao objeto
comercial em si. Portanto, se o tipo de objeto comercial não estiver sob seu controle,
você deverá adicionar essa propriedade estendendo o tipo por meio de herança.
Os procedimentos a seguir demonstram como preencher uma lista suspensa com

objetos de negócios e recuperar os objetos por meio da propriedade da célula Value .
Para adicionar objetos comerciais à lista suspensa

1. Crie uma nova DataGridViewComboBoxColumn e preencha sua Items coleção.
Como alternativa, você pode definir a propriedade de coluna DataSource para a
coleção de objetos de negócios. Nesse caso, no entanto, você não pode adicionar
"não atribuído" à lista suspensa sem criar um objeto comercial correspondente em
sua coleção.
C#
DataGridViewComboBoxColumn assignedToColumn =
new DataGridViewComboBoxColumn();
// Populate the combo box drop-down list with Employee objects.
foreach (Employee e in employees) assignedToColumn.Items.Add(e);
// Add "unassigned" to the drop-down list and display it for

// empty AssignedTo values or when the user presses CTRL+0.
assignedToColumn.Items.Add("unassigned");
assignedToColumn.DefaultCellStyle.NullValue = "unassigned";
2. Definir as propriedades DisplayMember e ValueMember. DisplayMember indica a

propriedade do objeto de negócios a ser exibida na lista suspensa. ValueMember
indica a propriedade que retorna uma referência ao objeto de negócios.
C#
assignedToColumn.DisplayMember = "Name";
assignedToColumn.ValueMember = "Self";
3. Certifique-se de que o tipo de objeto de negócios contenha uma propriedade que

retorne uma referência à instância atual. Essa propriedade deve ser nomeada com
o valor atribuído ValueMember na etapa anterior.
C#
public Employee Self

{
get { return this; }
}
Para recuperar o objeto comercial selecionado no

momento
Obtenha a propriedade da célula Value e converta-a no tipo de objeto de
negócios.
C#
// Retrieve the Employee object from the "Assigned To" cell.

Employee assignedTo = dataGridView1.Rows[e.RowIndex]
.Cells["Assigned To"].Value as Employee;
Exemplo
O exemplo completo demonstra o uso de objetos de negócios em uma lista suspensa.
No exemplo, um DataGridView controle está associado a uma coleção de Task objetos.
Cada objeto Task tem uma propriedade AssignedTo que indica o objeto Employee
atualmente atribuído à tarefa. A coluna Assigned To exibe o de valor da propriedade
Name para cada funcionário atribuído ou "não atribuído", se o valor da propriedade
Task.AssignedTo for null .
Para exibir o comportamento deste exemplo, execute as seguintes etapas:
1. Altere as atribuições na coluna Assigned To selecionando valores diferentes nas

listas suspensas ou pressionando CTRL+0 em uma célula de caixa de combinação.
2. Clique em Generate Report para exibir as atribuições atuais. Isso demonstra que
uma alteração à coluna Assigned To atualiza automaticamente a coleção tasks .
3. Clique em um botão Request Status para chamar o método RequestStatus do

objeto Employee atual para aquela linha. Isso demonstra que o objeto selecionado
foi recuperado com êxito.
C#
using System;
using System.Text;

{
private List<Employee> employees = new List<Employee>();
private List<Task> tasks = new List<Task>();
private Button reportButton = new Button();
[STAThread]
{
}
public Form1()
{
dataGridView1.AutoSizeColumnsMode =
DataGridViewAutoSizeColumnsMode.AllCells;
reportButton.Text = "Generate Report";
reportButton.Dock = DockStyle.Top;
reportButton.Click += new EventHandler(reportButton_Click);
Controls.Add(dataGridView1);
Controls.Add(reportButton);
Load += new EventHandler(Form1_Load);
Text = "DataGridViewComboBoxColumn Demo";
}
// Initializes the data source and populates the DataGridView control.

{
PopulateLists();
dataGridView1.DataSource = tasks;
AddColumns();
}
// Populates the employees and tasks lists.

private void PopulateLists()
{
employees.Add(new Employee("Harry"));
employees.Add(new Employee("Sally"));
employees.Add(new Employee("Roy"));
employees.Add(new Employee("Pris"));
tasks.Add(new Task(1, employees[1]));
tasks.Add(new Task(2));
tasks.Add(new Task(3, employees[2]));
tasks.Add(new Task(4));
}
// Configures columns for the DataGridView control.

private void AddColumns()
{
DataGridViewTextBoxColumn idColumn =
new DataGridViewTextBoxColumn();
idColumn.Name = "Task";
idColumn.DataPropertyName = "Id";
idColumn.ReadOnly = true;
DataGridViewComboBoxColumn assignedToColumn =
new DataGridViewComboBoxColumn();
// Populate the combo box drop-down list with Employee objects.

foreach (Employee e in employees) assignedToColumn.Items.Add(e);
// Add "unassigned" to the drop-down list and display it for

// empty AssignedTo values or when the user presses CTRL+0.
assignedToColumn.Items.Add("unassigned");
assignedToColumn.DefaultCellStyle.NullValue = "unassigned";
assignedToColumn.Name = "Assigned To";

assignedToColumn.DataPropertyName = "AssignedTo";
assignedToColumn.AutoComplete = true;
assignedToColumn.DisplayMember = "Name";
assignedToColumn.ValueMember = "Self";
// Add a button column.

DataGridViewButtonColumn buttonColumn =
new DataGridViewButtonColumn();
buttonColumn.HeaderText = "";
buttonColumn.Name = "Status Request";
buttonColumn.Text = "Request Status";
buttonColumn.UseColumnTextForButtonValue = true;
dataGridView1.Columns.Add(idColumn);
dataGridView1.Columns.Add(assignedToColumn);
dataGridView1.Columns.Add(buttonColumn);
// Add a CellClick handler to handle clicks in the button column.

dataGridView1.CellClick +=
new DataGridViewCellEventHandler(dataGridView1_CellClick);
}
// Reports on task assignments.

private void reportButton_Click(object sender, EventArgs e)
{
StringBuilder report = new StringBuilder();
foreach (Task t in tasks)
{
String assignment =
t.AssignedTo == null ?
"unassigned" : "assigned to " + t.AssignedTo.Name;
report.AppendFormat("Task {0} is {1}.", t.Id, assignment);
report.Append(Environment.NewLine);
}
MessageBox.Show(report.ToString(), "Task Assignments");
}
// Calls the Employee.RequestStatus method.

void dataGridView1_CellClick(object sender, DataGridViewCellEventArgs e)
{
// Ignore clicks that are not on button cells.
if (e.RowIndex < 0 || e.ColumnIndex !=
dataGridView1.Columns["Status Request"].Index) return;
// Retrieve the task ID.

Int32 taskID = (Int32)dataGridView1[0, e.RowIndex].Value;
// Retrieve the Employee object from the "Assigned To" cell.

Employee assignedTo = dataGridView1.Rows[e.RowIndex]
.Cells["Assigned To"].Value as Employee;
// Request status through the Employee object if present.

if (assignedTo != null)
{
assignedTo.RequestStatus(taskID);
}
else
{
MessageBox.Show(String.Format(
"Task {0} is unassigned.", taskID), "Status Request");
}
}
}
public class Task

{
public Task(Int32 id)
{
idValue = id;
}
public Task(Int32 id, Employee assignedTo)

{
idValue = id;
assignedToValue = assignedTo;
}
private Int32 idValue;

public Int32 Id
{
get { return idValue; }
set { idValue = value; }
}
private Employee assignedToValue;

public Employee AssignedTo
{
get { return assignedToValue; }
set { assignedToValue = value; }
}
}
public class Employee

{
public Employee(String name)
{
nameValue = name;
}
private String nameValue;

public String Name
{
get { return nameValue; }
set { nameValue = value; }
}
public Employee Self

{
get { return this; }
}
public void RequestStatus(Int32 taskID)

{
MessageBox.Show(String.Format(
"Status for task {0} has been requested from {1}.",
taskID, nameValue), "Status Request");
}
}
Confira também
DataGridView
DataGridViewComboBoxColumn.Items
DataGridViewComboBoxColumn.DataSource
DataGridViewComboBoxColumn.ValueMember
DataGridViewComboBoxCell
DataGridViewComboBoxCell.Items
DataGridViewComboBoxCell.DataSource
DataGridViewComboBoxCell.ValueMember
DataGridViewCell.Value
ComboBox
Passo a passo: Criar um formulário
mestre/de detalhes usando dois
controles DataGridView do Windows
Forms
Artigo • 02/06/2023
Um dos cenários mais comuns para usar o DataGridView controle é o formulário

mestre/detalhe , no qual uma relação pai/filho entre duas tabelas de banco de dados é
exibida. Seleção de linhas na tabela mestra faz com que a tabela de detalhes sejam
atualizadas com os dados filho correspondentes.
Implementar um formulário mestre/detalhe é fácil usando a interação entre o

DataGridView controle e o BindingSource componente. Neste passo a passo, você criará
o formulário usando dois DataGridView controles e dois BindingSource componentes. O
formulário mostrará duas tabelas relacionadas no banco de dados de exemplo SQL
Server Northwind: Customers e Orders . Quando terminar, você terá um formulário que
mostra todos os clientes no banco de dados no mestre DataGridView e todos os
pedidos para o cliente selecionado nos detalhes DataGridView.
Para copiar o código neste tópico como uma única listagem, consulte Como criar um
formulário mestre/detalhes usando dois controles DataGridView dos Windows Forms.
Pré-requisitos
Para concluir este passo a passo, você precisará de:
Acesso a um servidor com o banco de dados de exemplo Northwind do SQL

Server.
Para criar um formulário mestre/detalhes

1. Crie uma classe que Form deriva e contenha dois DataGridView controles e dois
BindingSource componentes. O código a seguir fornece inicialização de formulário
básica e inclui um método Main . Se você usar o designer do Visual Studio para
criar seu formulário, poderá usar o código gerado pelo designer em vez desse
código, mas certifique-se de usar os nomes mostrados nas declarações de variável
aqui.
C#
using System;
using System.Data;

{
private DataGridView masterDataGridView = new DataGridView();
private BindingSource masterBindingSource = new BindingSource();
private DataGridView detailsDataGridView = new DataGridView();
private BindingSource detailsBindingSource = new BindingSource();
{
}
// Initializes the form.

public Form1()
{
masterDataGridView.Dock = DockStyle.Fill;
detailsDataGridView.Dock = DockStyle.Fill;
SplitContainer splitContainer1 = new SplitContainer();

splitContainer1.Dock = DockStyle.Fill;
splitContainer1.Orientation = Orientation.Horizontal;
splitContainer1.Panel1.Controls.Add(masterDataGridView);
splitContainer1.Panel2.Controls.Add(detailsDataGridView);
this.Controls.Add(splitContainer1);
this.Load += new System.EventHandler(Form1_Load);
this.Text = "DataGridView master/detail demo";
}
C#
2. Implemente um método na sua definição de classe do formulário para manipular

os detalhes da conexão ao banco de dados. Este exemplo usa um GetData método
que preenche um DataSet objeto, adiciona um DataRelation objeto ao conjunto de
dados e associa os BindingSource componentes. Certifique-se de definir a variável
de connectionString como um valor que seja apropriada para o base de dados.
） Importante
O armazenamento das informações confidenciais (tal como uma senha)

dentro da cadeia de conexão pode afetar a segurança do aplicativo. O uso da
Autenticação do Windows (também conhecida como segurança integrada) é
uma maneira mais segura de controlar o acesso a um banco de dados. Para
obter mais informações, consulte Protegendo informações de conexão.
C#
private void GetData()

{
try
{
// Specify a connection string. Replace the given value with a
// valid connection string for a Northwind SQL Server sample
// database accessible to your system.
SqlConnection connection = new SqlConnection(connectionString);
// Create a DataSet.
DataSet data = new DataSet();
data.Locale =
System.Globalization.CultureInfo.InvariantCulture;
// Add data from the Customers table to the DataSet.

SqlDataAdapter masterDataAdapter = new
SqlDataAdapter("select * from Customers", connection);
masterDataAdapter.Fill(data, "Customers");
// Add data from the Orders table to the DataSet.

SqlDataAdapter detailsDataAdapter = new
SqlDataAdapter("select * from Orders", connection);
detailsDataAdapter.Fill(data, "Orders");
// Establish a relationship between the two tables.

DataRelation relation = new DataRelation("CustomersOrders",
data.Tables["Customers"].Columns["CustomerID"],
data.Tables["Orders"].Columns["CustomerID"]);
data.Relations.Add(relation);
// Bind the master data connector to the Customers table.

masterBindingSource.DataSource = data;
masterBindingSource.DataMember = "Customers";
// Bind the details data connector to the master data

connector,
// using the DataRelation name to filter the information in the
// details table based on the current row in the master table.
detailsBindingSource.DataSource = masterBindingSource;
detailsBindingSource.DataMember = "CustomersOrders";
}
{
MessageBox.Show("To run this example, replace the value of the
" +
" +
}
}
3. Implemente um manipulador para o evento do Load formulário que associe os

DataGridView controles aos BindingSource componentes e chame o GetData
método. O exemplo a seguir inclui código que redimensiona DataGridView colunas
para se ajustar aos dados exibidos.
C#
private void Form1_Load(object sender, System.EventArgs e)

{
// Bind the DataGridView controls to the BindingSource
// components and load the data from the database.
masterDataGridView.DataSource = masterBindingSource;
detailsDataGridView.DataSource = detailsBindingSource;
GetData();
// Resize the master DataGridView columns to fit the newly loaded

data.
masterDataGridView.AutoResizeColumns();
// Configure the details DataGridView so that its columns

automatically
// adjust their widths when the data changes.
detailsDataGridView.AutoSizeColumnsMode =
}
esperada.

Compile e execute o aplicativo.
Você verá dois DataGridView controles, um acima do outro. Na parte superior
estão os clientes da tabela Customers Northwind e na parte inferior estão os
Orders correspondentes ao cliente selecionado. À medida que você seleciona
linhas diferentes na parte superior DataGridView, o conteúdo da parte inferior

DataGridView é alterado adequadamente.
Próximas etapas
Esse aplicativo fornece uma compreensão básica das DataGridView funcionalidades do
Windows Forms.

Valide a entrada do usuário no DataGridView controle. Para obter mais

informações, consulte Passo a passo: validando dados no controle DataGridView
dos Windows Forms.
Forms.
Confira também
DataGridView
BindingSource
Como: Criar um formulário mestre/de detalhes usando dois controles
Como: Criar um formulário mestre/de
detalhes usando dois controles
Artigo • 02/06/2023
O exemplo de código a seguir cria um formulário mestre/detalhe usando dois

DataGridView controles associados a dois BindingSource componentes. A fonte de
dados é uma DataSet que contém as tabelas e Orders o Customers banco de dados de
exemplo northwind SQL Server juntamente com um DataRelation que relaciona os dois
por meio da CustomerID coluna.
Um BindingSource deles está associado à tabela pai Customers no conjunto de dados.

Esses dados são exibidos no controle mestre DataGridView . O outro BindingSource está
associado ao primeiro conector de dados. A DataMember propriedade do segundo
BindingSource é definida como o DataRelation nome. Isso faz com que o controle de
detalhes DataGridView associado exiba as linhas da tabela filho Orders que
correspondem à linha atual no controle mestre DataGridView .
Para uma explicação completa desse código de exemplo, consulte Instruções passo a
passo: criando um formulário mestre/detalhes usando dois controles DataGridView dos
Windows Forms.
Exemplo
C#
using System;
using System.Data;

{
private DataGridView masterDataGridView = new DataGridView();
private BindingSource masterBindingSource = new BindingSource();
private DataGridView detailsDataGridView = new DataGridView();
private BindingSource detailsBindingSource = new BindingSource();
{
}
public Form1()
{
masterDataGridView.Dock = DockStyle.Fill;
detailsDataGridView.Dock = DockStyle.Fill;
SplitContainer splitContainer1 = new SplitContainer();

splitContainer1.Dock = DockStyle.Fill;
splitContainer1.Panel1.Controls.Add(masterDataGridView);
splitContainer1.Panel2.Controls.Add(detailsDataGridView);
this.Controls.Add(splitContainer1);
this.Load += new System.EventHandler(Form1_Load);
this.Text = "DataGridView master/detail demo";
}

{
// Bind the DataGridView controls to the BindingSource
// components and load the data from the database.
masterDataGridView.DataSource = masterBindingSource;
detailsDataGridView.DataSource = detailsBindingSource;
GetData();
// Resize the master DataGridView columns to fit the newly loaded

data.
masterDataGridView.AutoResizeColumns();
// Configure the details DataGridView so that its columns

automatically
// adjust their widths when the data changes.
detailsDataGridView.AutoSizeColumnsMode =
}
private void GetData()

{
try
{
// Create a DataSet.
DataSet data = new DataSet();
data.Locale = System.Globalization.CultureInfo.InvariantCulture;
// Add data from the Customers table to the DataSet.

SqlDataAdapter masterDataAdapter = new
SqlDataAdapter("select * from Customers", connection);
masterDataAdapter.Fill(data, "Customers");
// Add data from the Orders table to the DataSet.

SqlDataAdapter detailsDataAdapter = new
SqlDataAdapter("select * from Orders", connection);
detailsDataAdapter.Fill(data, "Orders");
// Establish a relationship between the two tables.

DataRelation relation = new DataRelation("CustomersOrders",
data.Tables["Customers"].Columns["CustomerID"],
data.Tables["Orders"].Columns["CustomerID"]);
data.Relations.Add(relation);
// Bind the master data connector to the Customers table.

masterBindingSource.DataSource = data;
masterBindingSource.DataMember = "Customers";
// Bind the details data connector to the master data connector,

// using the DataRelation name to filter the information in the
// details table based on the current row in the master table.
detailsBindingSource.DataSource = masterBindingSource;
detailsBindingSource.DataMember = "CustomersOrders";
}
{
MessageBox.Show("To run this example, replace the value of the "
+
" +
}
}
}
Referências aos assemblies System, System.Data, System.Windows.Forms e System.XML.
Segurança do .NET Framework

cadeia de conexão pode afetar a segurança do aplicativo. O uso da Autenticação do
Windows (também conhecida como segurança integrada) é uma maneira mais segura
de controlar o acesso a um banco de dados. Para obter mais informações, consulte
Protegendo informações de conexão.
Confira também
DataGridView
BindingSource
Instruções passo a passo: criando um formulário mestre/detalhes usando dois
controles DataGridView do Windows Forms
Como personalizar a formatação de
dados no controle DataGridView dos
Windows Forms
Artigo • 21/06/2023
O exemplo de código a seguir demonstra como implementar um manipulador para o

DataGridView.CellFormatting evento que altera como as células são exibidas
dependendo de suas colunas e valores.
As células na Balance coluna que contêm números negativos recebem um plano de

fundo vermelho. Você também pode formatar essas células como moeda para exibir
parênteses em torno de valores negativos. Para obter mais informações, consulte Como
formatar dados no controle DataGridView do Windows Forms.
As células na Priority coluna exibem imagens no lugar dos valores de célula textuais
correspondentes. A Value propriedade do é usada para obter o valor da célula textual e
para definir o valor de DataGridViewCellFormattingEventArgs exibição da imagem
correspondente.
Exemplo
C#
using System;

{
private Bitmap highPriImage;
private Bitmap mediumPriImage;
private Bitmap lowPriImage;
public Form1()
{
// Initialize the images.
try
{
highPriImage = new Bitmap("highPri.bmp");
mediumPriImage = new Bitmap("mediumPri.bmp");
lowPriImage = new Bitmap("lowPri.bmp");
}
catch (ArgumentException)
{
MessageBox.Show("The Priority column requires Bitmap images " +
"named highPri.bmp, mediumPri.bmp, and lowPri.bmp " +
"residing in the same directory as the executable file.");
}
// Initialize the DataGridView.

dataGridView1.Columns.AddRange(
new DataGridViewTextBoxColumn(),
new DataGridViewImageColumn());
dataGridView1.Columns[0].Name = "Balance";
dataGridView1.Columns[1].Name = "Priority";
dataGridView1.Rows.Add("-100", "high");
dataGridView1.Rows.Add("0", "medium");
dataGridView1.Rows.Add("100", "low");
dataGridView1.CellFormatting +=
new System.Windows.Forms.DataGridViewCellFormattingEventHandler(
this.dataGridView1_CellFormatting);
}
// Changes how cells are displayed depending on their columns and

values.
private void dataGridView1_CellFormatting(object sender,
{
// Set the background to red for negative values in the Balance
column.
if (dataGridView1.Columns[e.ColumnIndex].Name.Equals("Balance"))
{
Int32 intValue;
if (Int32.TryParse((String)e.Value, out intValue) &&
(intValue < 0))
{
e.CellStyle.BackColor = Color.Red;
e.CellStyle.SelectionBackColor = Color.DarkRed;
}
}
// Replace string values in the Priority column with images.

if (dataGridView1.Columns[e.ColumnIndex].Name.Equals("Priority"))
{
// Ensure that the value is a string.
String stringValue = e.Value as string;
if (stringValue == null) return;
// Set the cell ToolTip to the text value.

DataGridViewCell cell = dataGridView1[e.ColumnIndex,
e.RowIndex];
cell.ToolTipText = stringValue;
// Replace the string value with the image value.

switch (stringValue)
{
case "high":
e.Value = highPriImage;
break;
case "medium":
e.Value = mediumPriImage;
break;
case "low":
e.Value = lowPriImage;
break;
}
}
}

{
}
}
Bitmap imagens chamadas highPri.bmp , mediumPri.bmp e lowPri.bmp que residem

no mesmo diretório que o arquivo executável.
Confira também
DataGridView
Bitmap
Redimensionando colunas e linhas no
Forms
Artigo • 02/06/2023
O controle DataGridView fornece diversas opções para personalizar o comportamento

de dimensionamento de suas colunas e linhas. Normalmente, células DataGridView não
são redimensionados com base em seu conteúdo. Em vez disso, elas cortam qualquer
valor de exibição maior do que a célula. Se o conteúdo puder ser exibido como uma
cadeia de caracteres, a célula o exibirá em uma dica de ferramenta.
Por padrão, os usuários poderão arrastar os divisores de linha, coluna e cabeçalho com
o mouse para mostrar mais informações. Os usuários também podem clicar duas vezes
em um divisor para redimensionar automaticamente a faixa da linha, coluna ou
cabeçalho associado ao conteúdo.
O controle DataGridView fornece propriedades, métodos e eventos que permitem

personalizar ou desabilitar todos esses comportamentos causados voltados para o
usuário. Além disso, é possível redimensionar linhas, colunas e cabeçalhos com
programação para ajustar o conteúdo ou configurá-los para redimensionarem a si
próprios automaticamente sempre que seu conteúdo mudar. Você também pode
configurar colunas para dividir automaticamente a largura disponível do controle em
proporções especificadas.
Nesta seção
Dimensionando opções no controle DataGridView dos Windows Forms
Descreve as opções para dimensionar linhas, colunas e cabeçalhos. Também fornece
detalhes sobre os métodos e propriedades relacionados ao dimensionamento e
descreve os cenários comuns de uso.

Descreve o modo de preenchimento de coluna em detalhes e fornece código de
demonstração que pode ser usado para experimentar o modo de preenchimento de
coluna e outros modos.
Como definir os modos de dimensionamento do controle DataGridView dos Windows

Forms
Descreve como configurar os modos de dimensionamento para fins comuns.
Como: Redimensionar de forma programática as células para que o conteúdo caiba no
Fornece código de demonstração que pode ser usado para experimentar o
redimensionamento com programação.

Fornece código de demonstração que pode ser usado para experimentar os modos de
dimensionamento automáticos.
Referência
DataGridView
Fornece documentação de referência para o DataGridView controle.
Confira também
Dimensionando opções no controle
Artigo • 02/06/2023
DataGridView linhas, colunas e cabeçalhos podem alterar o tamanho como resultado de

muitas ocorrências diferentes. A tabela a seguir mostra essas ocorrências.
Ocorrência Descrição
Redimensionamento Os usuários podem fazer ajustes de tamanho arrastando ou clicando duas

do usuário vezes nos divisores de linha, coluna ou cabeçalho.
Redimensionamento No modo de preenchimento de coluna, as larguras de coluna são

do controle alteradas quando a largura do controle é alterada. Por exemplo, quando o
controle é encaixado em seu formulário pai e o usuário redimensiona o
formulário.
Alteração do valor Nos modos de dimensionamento automático baseado em conteúdo, os

da célula tamanhos são alterados para ajustar os novos valores de exibição.
Chamada de O redimensionamento programático baseado em conteúdo permite que

método você faça ajustes de tamanho oportunos com base nos valores de célula
no momento da chamada de método.
Configuração de Você também pode definir valores específicos de largura e altura.

propriedade
Por padrão, o redimensionamento do usuário está habilitado, o dimensionamento

automático está desabilitado e os valores de células são mais largos do que o recorte de
suas colunas.
A tabela a seguir mostra cenários que você pode usar para ajustar o comportamento
padrão ou para usar opções específicas de dimensionamento para atingir efeitos
específicos.
Cenário Implementação
Use o modo de Defina a propriedade AutoSizeColumnsMode como Fill.

preenchimento de
coluna para exibir
dados de tamanhos
semelhantes em um
número relativamente
pequeno de colunas
que ocupem toda a
largura do controle sem
exibir a barra de
rolagem horizontal.
Use o modo de Defina a propriedade AutoSizeColumnsMode como Fill. Inicialize

preenchimento de larguras de coluna relativas definindo as propriedades de coluna
coluna com valores de FillWeight ou chamando o método de controle AutoResizeColumns
exibição de tamanhos depois de preencher o controle com os dados.
variados.
Use o modo de Defina a propriedade AutoSizeColumnsMode como Fill. Defina valores

preenchimento de grandes MinimumWidth para colunas que sempre devem exibir alguns
coluna com valores de de seus dados ou usar uma opção de dimensionamento diferente do
importância variada. modo de preenchimento para colunas específicas.
Use o modo de Defina a AutoSizeMode propriedade da última coluna como Fill e use
preenchimento de outras opções de dimensionamento para as outras colunas. Se as
coluna para evitar a outras colunas usarem muito espaço disponível, defina a
exibição da tela de MinimumWidth propriedade da última coluna.
fundo do controle.
Exiba uma coluna de Defina AutoSizeMode como None e Resizable para False para a coluna.
largura fixa, como um Inicialize sua largura definindo a Width propriedade ou chamando o
ícone ou uma coluna de método de controle AutoResizeColumn depois de preencher o
ID. controle com os dados.
Ajuste os tamanhos Defina uma propriedade de dimensionamento automático para um

automaticamente valor que represente um modo de dimensionamento baseado em
sempre que o conteúdo conteúdo. Para evitar uma penalidade de desempenho ao trabalhar
da célula for alterado com grandes quantidades de dados, use um modo de
para evitar recorte e dimensionamento que calcule apenas as linhas exibidas.
otimizar o uso de
espaço.
Ajuste os tamanhos Use os valores de enumeração de modo de dimensionamento

para ajustar os valores apropriados com o redimensionamento automático ou programático.
nas linhas exibidas para Para ajustar os tamanhos para ajustar os valores nas linhas exibidas
evitar penalidades de recentemente durante a rolagem, chame um método de
desempenho ao redimensionamento em um Scroll manipulador de eventos. Para
trabalhar com várias personalizar o usuário clique duas vezes em redimensionamento para
linhas. que apenas os valores nas linhas exibidas determinem os novos
tamanhos, chame um método de redimensionamento em um
RowDividerDoubleClick manipulador de eventos ou
ColumnDividerDoubleClick .
Ajuste os tamanhos Chame um método de redimensionamento baseado em conteúdo em

para ajustar o conteúdo um manipulador de eventos. Por exemplo, use o DataBindingComplete
da célula apenas em evento para inicializar tamanhos após a associação e manipule o
momentos específicos evento ou CellValueChanged para ajustar os CellValidated tamanhos
para evitar penalidades para compensar as edições do usuário ou as alterações em uma fonte
de desempenho ou de dados associada.
permitir o
redimensionamento do
usuário.
Ajuste as alturas de Verifique se as larguras de coluna são apropriadas para a exibição de

linhas para conteúdo de parágrafos de texto e use o dimensionamento de linhas baseado em
célula multilinha. conteúdo automático ou programático para ajustar as alturas.
Verifique também se as células com conteúdo multilinha são exibidas
usando um WrapMode valor de estilo de célula de True .
Normalmente, você usará o modo de dimensionamento automático de

coluna para manter as larguras de coluna ou defini-las como larguras
específicas antes que as alturas das linhas sejam ajustadas.
Redimensionando com o mouse

Por padrão, os usuários podem redimensionar linhas, colunas e cabeçalhos que não
usam um modo de dimensionamento automático com base nos valores de célula. Para
impedir que os usuários redimensionem com outros modos, como o modo de
preenchimento de coluna, defina uma ou mais das seguintes DataGridView
Propriedades:
AllowUserToResizeColumns
AllowUserToResizeRows
ColumnHeadersHeightSizeMode
RowHeadersWidthSizeMode
Você também pode impedir que os usuários redimensionem linhas ou colunas

individuais definindo suas Resizable Propriedades. Por padrão, o valor da Resizable
propriedade é baseado no AllowUserToResizeColumns valor da propriedade para
colunas e no AllowUserToResizeRows valor da propriedade para linhas. Se você definir
Resizable explicitamente como True ou False , no entanto, o valor especificado
substituirá o valor de controle por essa linha ou coluna. Defina Resizable como NotSet
para restaurar a herança.
Como NotSet o restaura a herança de valor, a Resizable Propriedade nunca retornará

um NotSet valor, a menos que a linha ou coluna não tenha sido adicionada a um
DataGridView controle. Se você precisar determinar se o Resizable valor da propriedade
de uma linha ou coluna é herdado, examine sua State propriedade. Se o State valor
incluir o ResizableSet sinalizador, o valor da Resizable propriedade não será herdado.
Dimensionamento automático
Há dois tipos de dimensionamento automático no DataGridView controle: modo de
preenchimento de coluna e dimensionamento automático baseado em conteúdo.
O modo de preenchimento de coluna faz com que as colunas visíveis no controle

preencham a largura da área de exibição do controle. Para obter mais informações
sobre esse modo, consulte Modo de preenchimento da coluna no controle
Você também pode configurar as linhas, as colunas e os cabeçalhos para ajustar

automaticamente seus tamanhos a fim de ajustar o conteúdo de suas células. Nesse
caso, o ajuste de tamanho ocorre sempre que o conteúdo da célula é alterado.
７ Observação
Se você mantiver valores de célula em um cache de dados personalizado usando o

modo virtual, o dimensionamento automático ocorrerá quando o usuário editar um
valor de célula, mas não ocorrer quando você alterar um valor em cache fora de um
CellValuePushed manipulador de eventos. Nesse caso, chame o UpdateCellValue
método para forçar o controle a atualizar a exibição de célula e aplicar os modos
de dimensionamento automático atuais.
Se o dimensionamento automático baseado em conteúdo estiver habilitado apenas

para uma dimensão — ou seja, para linhas, mas não para colunas, ou para colunas, mas
não para linhas, e WrapMode também estiver habilitado, o ajuste de tamanho também
ocorrerá sempre que a outra dimensão for alterada. Por exemplo, se as linhas, mas não
as colunas estiverem configuradas para o dimensionamento automático e WrapMode
estiverem habilitadas, os usuários poderão arrastar separadores de colunas para alterar
a largura de uma coluna e as alturas das linhas serão ajustadas automaticamente para
que o conteúdo da célula ainda seja totalmente exibido.
Se você configurar linhas e colunas para o dimensionamento automático baseado em

conteúdo e WrapMode estiver habilitado, o controle ajustará os tamanhos sempre que
o DataGridView conteúdo da célula for alterado e usará uma proporção ideal de altura
para largura de célula ao calcular novos tamanhos.
Para configurar o modo de dimensionamento para cabeçalhos e linhas e colunas que

não substituem o valor de controle, defina uma ou mais das seguintes DataGridView
Propriedades:
ColumnHeadersHeightSizeMode
RowHeadersWidthSizeMode
AutoSizeColumnsMode
AutoSizeRowsMode
Para substituir o modo de dimensionamento de coluna do controle para uma coluna

individual, defina sua AutoSizeMode propriedade com um valor diferente de NotSet .
Na verdade, o modo de dimensionamento de uma coluna é determinado por sua
InheritedAutoSizeMode propriedade. O valor dessa propriedade é baseado no valor da
propriedade da AutoSizeMode coluna, a menos que esse valor seja NotSet ; nesse caso,
o valor do AutoSizeColumnsMode controle é herdado.
Use o redimensionamento automático baseado em conteúdo com cuidado ao trabalhar

com grandes quantidades de dados. Para evitar penalidades de desempenho, use os
modos de dimensionamento automático que calculam tamanhos base apenas nas linhas
exibidas em vez de analisar cada linha no controle. Para obter o desempenho máximo,
use o redimensionamento programático para que você possa redimensionar em
momentos específicos, como imediatamente depois que novos dados são carregados.
Os modos de dimensionamento automático baseados em conteúdo não afetam linhas,

colunas ou cabeçalhos que você ocultou definindo a propriedade de linha ou coluna
Visible ou o controle RowHeadersVisible ou ColumnHeadersVisible as propriedades para
false . Por exemplo, se uma coluna for ocultada depois de ser dimensionada
automaticamente para ajustar um valor de célula grande, a coluna oculta não mudará
seu tamanho se a linha que contém o valor da célula grande for excluída. O
dimensionamento automático não ocorre quando a visibilidade é alterada, portanto,
alterar a propriedade de coluna Visible de volta para true não irá forçá-la a recalcular
seu tamanho com base em seu conteúdo atual.
O redimensionamento programático baseado em conteúdo afeta colunas, linhas e

cabeçalhos independentemente da visibilidade.
Redimensionamento programático
Quando o dimensionamento automático está desabilitado, você pode definir
programaticamente a largura ou a altura exata de linhas, colunas ou cabeçalhos usando
as propriedades a seguir:
DataGridView.RowHeadersWidth
DataGridView.ColumnHeadersHeight
DataGridViewRow.Height
DataGridViewColumn.Width
Você também pode redimensionar de forma programática as linhas, as colunas e os

cabeçalhos para que se ajustem ao conteúdo usando os seguintes métodos:
AutoResizeColumn
AutoResizeColumns
AutoResizeColumnHeadersHeight
AutoResizeRow
AutoResizeRows
AutoResizeRowHeadersWidth
Esses métodos redimensionarão as linhas, as colunas ou os cabeçalhos uma única vez

em vez de configurá-los para redimensionamento contínuo. Os novos tamanhos são
calculados automaticamente para exibir todo o conteúdo da célula sem recorte. Quando
você redimensiona programaticamente colunas InheritedAutoSizeMode com valores de
propriedade de Fill , no entanto, as larguras baseadas em conteúdo calculadas são
usadas para ajustar proporcionalmente os valores de propriedade da coluna FillWeight ,
e a largura da coluna realmente é calculada de acordo com essas novas proporções
para que todas as colunas preencham a área de exibição disponível do controle.
O redimensionando programático é útil para evitar penalidades de desempenho com o
redimensionamento contínuo. Ele também é útil para fornecer os tamanhos inicias de
cabeçalhos, colunas e linhas redimensionáveis pelo usuário e para o modo de
preenchimento de coluna.
Normalmente, você chamará os métodos de redimensionamento programáticos em

momentos específicos. Por exemplo, você pode redimensionar de forma programática
todas as colunas imediatamente após o carregamento de dados ou redimensionar de
forma programática uma linha específica depois que um valor de célula específico foi
modificado.
Personalizando o comportamento de
dimensionamento baseado em conteúdo
Você pode personalizar comportamentos de dimensionamento ao trabalhar com tipos
de célula, linha e coluna derivadas DataGridView , substituindo os
DataGridViewCell.GetPreferredSize métodos, DataGridViewRow.GetPreferredHeight ou
DataGridViewColumn.GetPreferredWidth , ou chamando sobrecargas de método de
redimensionamento protegido em um controle derivado DataGridView . As sobrecargas
de método de redimensionamento protegidas são projetadas para funcionar em pares
para atingir uma razão ideal de altura para largura da célula, evitando células
excessivamente altas ou largas. Por exemplo, se você chamar a
AutoResizeRows(DataGridViewAutoSizeRowsMode,Boolean) sobrecarga do AutoResizeRows
método e passar um valor de false para o Boolean parâmetro, a sobrecarga calculará

as alturas e larguras ideais para as células na linha, mas ajustará apenas as alturas de
linha. Em seguida, você deve chamar o AutoResizeColumns método para ajustar as
larguras da coluna para o ideal calculado.
Opções de dimensionamento baseado em

conteúdo
As enumerações usadas pelos métodos e propriedades de dimensionamento têm
valores semelhantes para dimensionamento baseado em conteúdo. Com esses valores,
você pode limitar quais células são usadas para calcular o tamanho preferencial. Para
todas as enumerações de dimensionamento, valores com nomes que se referem a
células exibidas limitam seus cálculos para células em linhas exibidas. Excluir linhas é útil
para evitar uma penalidade de desempenho ao trabalhar com uma grande quantidade
de linhas. Você também pode restringir os cálculos para valores de célula nas células de
cabeçalho ou que não sejam de cabeçalho.
Confira também
DataGridView
DataGridView.AllowUserToResizeColumns
DataGridView.AllowUserToResizeRows
DataGridView.ColumnHeadersHeightSizeMode
DataGridView.RowHeadersWidthSizeMode
DataGridViewBand.Resizable
DataGridView.AutoSizeColumnsMode
DataGridView.AutoSizeRowsMode
DataGridViewColumn.AutoSizeMode
DataGridViewColumn.InheritedAutoSizeMode
DataGridView.RowHeadersWidth
DataGridView.ColumnHeadersHeight
DataGridViewRow.Height
DataGridView.AutoResizeColumn
DataGridView.AutoResizeColumns
DataGridView.AutoResizeColumnHeadersHeight
DataGridView.AutoResizeRow
DataGridView.AutoResizeRows
DataGridView.AutoResizeRowHeadersWidth
DataGridViewAutoSizeRowMode
DataGridViewAutoSizeRowsMode
DataGridViewAutoSizeColumnMode
DataGridViewAutoSizeColumnsMode
DataGridViewColumnHeadersHeightSizeMode
DataGridViewRowHeadersWidthSizeMode
Como definir os modos de dimensionamento do controle DataGridView dos
Windows Forms
Modo de preenchimento da coluna no
Forms
Artigo • 02/06/2023
No modo de preenchimento de coluna, o DataGridView controle redimensiona suas

colunas automaticamente para que elas preencham a largura da área de exibição
disponível. O controle não exibe a barra de rolagem horizontal, exceto quando é
necessário manter a largura de cada coluna igual ou maior que MinimumWidth o valor
da propriedade.
O comportamento de dimensionamento de cada coluna depende de sua

InheritedAutoSizeMode propriedade. O valor dessa propriedade será herdado da
propriedade da AutoSizeMode coluna ou da Propriedade do controle
AutoSizeColumnsMode se o valor da coluna for NotSet (o valor padrão).
Cada coluna pode ter um modo de tamanho diferente, mas todas as colunas com um
modo de tamanho de Fill irão compartilhar a largura da área de exibição que não é
usada pelas outras colunas. Essa largura é dividida entre as colunas de modo de
preenchimento em proporções relativas aos seus FillWeight valores de propriedade. Por
exemplo, se duas colunas tiverem FillWeight valores de 100 e 200, a primeira coluna
será metade de largura da segunda coluna.
Redimensionamento de usuário no modo de

preenchimento
Ao contrário dos modos de dimensionamento que redimensionam com base no
conteúdo da célula, o modo de preenchimento não impede que os usuários
redimensionem colunas Resizable com valores de propriedade de true . Quando um
usuário redimensiona uma coluna de modo de preenchimento, todas as colunas de
modo de preenchimento após a coluna redimensionada (à direita, se RightToLeft for
false ; caso contrário, à esquerda) também são redimensionadas para compensar a
alteração na largura disponível. Se não houver nenhuma coluna do modo de
preenchimento depois da coluna redimensionada, todas as outras colunas do modo de
preenchimento no controle serão redimensionadas para compensar. Se não houver
nenhuma outra coluna do modo de preenchimento no controle, o redimensionamento
será ignorado. Se uma coluna que não estiver no modo de preenchimento for
redimensionada, todas as colunas do modo de preenchimento no controle terão os
tamanhos alterados para compensar.
Depois de redimensionar uma coluna de modo de preenchimento, os FillWeight valores

de todas as colunas alteradas são ajustados proporcionalmente. Por exemplo, se quatro
colunas de modo de preenchimento tiverem FillWeight valores de 100, redimensionar a
segunda coluna para metade da largura original resultará em FillWeight valores de 100,
50, 125 e 125. O redimensionamento de uma coluna que não está no modo de
preenchimento não alterará nenhum FillWeight valor porque as colunas de modo de
preenchimento simplesmente serão redimensionadas para compensar enquanto retém
as mesmas proporções.
Ajuste de FillWeight baseado em conteúdo

Você pode inicializar FillWeight valores para colunas de modo de preenchimento
usando os DataGridView métodos de redimensionamento automático, como o
AutoResizeColumns método. Esse método primeiro calcula as larguras necessárias por
colunas para exibir seu conteúdo. Em seguida, o controle ajusta os FillWeight valores
para todas as colunas de modo de preenchimento para que suas proporções
correspondam às proporções das larguras calculadas. Por fim, o controle redimensiona
as colunas de modo de preenchimento usando as novas FillWeight proporções para que
todas as colunas no controle preencham o espaço horizontal disponível.
Exemplo
Descrição
Usando os valores apropriados para as AutoSizeMode Propriedades, MinimumWidth ,
FillWeightResizable e, você pode personalizar os comportamentos de dimensionamento
de coluna para vários cenários diferentes.
O código de demonstração a seguir permite que você experimente valores diferentes

para as AutoSizeMode Propriedades, FillWeight e MinimumWidth de colunas diferentes.
Neste exemplo, um DataGridView controle é associado a sua própria Columns coleção e
uma coluna é associada a cada uma das HeaderText Propriedades, AutoSizeMode ,
FillWeight , MinimumWidth e Width . Cada uma das colunas também é representada
por uma linha no controle e a alteração dos valores em uma linha atualizará as
propriedades da coluna correspondente para que você possa ver como os valores
interagem.
Código
C#
using System;
using System.Reflection;

{
[STAThread]
{
}
public Form1()
{
InitializeDataGridView();
Width *= 2;
Text = "Column Fill-Mode Demo";
}
private void InitializeDataGridView()

{
// Add columns to the DataGridView, binding them to the
// specified DataGridViewColumn properties.
AddReadOnlyColumn("HeaderText", "Column");
AddColumn("AutoSizeMode");
AddColumn("FillWeight");
AddColumn("MinimumWidth");
AddColumn("Width");
// Bind the DataGridView to its own Columns collection.

dataGridView1.DataSource = dataGridView1.Columns;
// Configure the DataGridView so that users can manually change

// only the column widths, which are set to fill mode.
dataGridView1.AllowUserToDeleteRows = false;
dataGridView1.AllowUserToResizeRows = false;
dataGridView1.RowHeadersWidthSizeMode =
DataGridViewRowHeadersWidthSizeMode.DisableResizing;
dataGridView1.ColumnHeadersHeightSizeMode =
DataGridViewColumnHeadersHeightSizeMode.DisableResizing;
DataGridViewAutoSizeColumnsMode.Fill;
// Configure the top left header cell as a reset button.
dataGridView1.TopLeftHeaderCell.Value = "reset";
dataGridView1.TopLeftHeaderCell.Style.ForeColor =
System.Drawing.Color.Blue;
// Add handlers to DataGridView events.

dataGridView1.ColumnWidthChanged += new
DataGridViewColumnEventHandler(dataGridView1_ColumnWidthChanged);
dataGridView1.CurrentCellDirtyStateChanged +=
new EventHandler(dataGridView1_CurrentCellDirtyStateChanged);
dataGridView1.DataError +=
new DataGridViewDataErrorEventHandler(dataGridView1_DataError);
dataGridView1.CellEndEdit +=
new DataGridViewCellEventHandler(dataGridView1_CellEndEdit);
dataGridView1.CellValueChanged +=
new
DataGridViewCellEventHandler(dataGridView1_CellValueChanged);
}
private void AddReadOnlyColumn(String dataPropertyName, String

columnName)
{
AddColumn(typeof(DataGridViewColumn), dataPropertyName, true,
columnName);
}
private void AddColumn(String dataPropertyName)

{
AddColumn(typeof(DataGridViewColumn), dataPropertyName, false,
dataPropertyName);
}
// Adds a column to the DataGridView control, binding it to specified

// property of the specified type and optionally making it read-only.
private void AddColumn(
Type type,
String dataPropertyName,
Boolean readOnly,
String columnName)
{
// Retrieve information about the property through reflection.
PropertyInfo property = type.GetProperty(dataPropertyName);
// Confirm that the property exists and is accessible.

if (property == null) throw new ArgumentException("No accessible " +
dataPropertyName + " property was found in the " + type.Name + "
type.");
// Confirm that the property is browsable.

BrowsableAttribute[] browsables = (BrowsableAttribute[])
property.GetCustomAttributes(typeof(BrowsableAttribute), false);
if (browsables.Length > 0 && !browsables[0].Browsable)
{
throw new ArgumentException("The " + dataPropertyName + "
property has a " +
"Browsable(false) attribute, and therefore cannot be bound.");
}
// Create and initialize a column, using a combo box column for

// enumeration properties, a check box column for Boolean
properties,
// and a text box column otherwise.
DataGridViewColumn column;
Type valueType = property.PropertyType;
if (valueType.IsEnum)
{
column = new DataGridViewComboBoxColumn();
// Populate the drop-down list with the enumeration values.

((DataGridViewComboBoxColumn)column).DataSource
= Enum.GetValues(valueType);
}
else if (valueType.Equals(typeof(Boolean)))
{
column = new DataGridViewCheckBoxColumn();
}
else
{
column = new DataGridViewTextBoxColumn();
}
// Initialize and bind the column.

column.ValueType = valueType;
column.Name = columnName;
column.DataPropertyName = dataPropertyName;
column.ReadOnly = readOnly;
// Add the column to the control.

}
private void ResetDataGridView()

{
dataGridView1.CancelEdit();
dataGridView1.Columns.Clear();
dataGridView1.DataSource = null;
}
private void dataGridView1_CellClick(

object sender, DataGridViewCellEventArgs e)
{
if (e.ColumnIndex == -1 && e.RowIndex == -1)
{
ResetDataGridView();
}
}
private void dataGridView1_ColumnWidthChanged(
object sender, DataGridViewColumnEventArgs e)
{
// Invalidate the row corresponding to the column that changed
// to ensure that the FillWeight and Width entries are updated.
dataGridView1.InvalidateRow(e.Column.Index);
}
private void dataGridView1_CurrentCellDirtyStateChanged(

object sender, EventArgs e)
{
// For combo box and check box cells, commit any value change as
soon
// as it is made rather than waiting for the focus to leave the
cell.
if (!dataGridView1.CurrentCell.OwningColumn.GetType()
.Equals(typeof(DataGridViewTextBoxColumn)))
{
dataGridView1.CommitEdit(DataGridViewDataErrorContexts.Commit);
}
}
private void dataGridView1_DataError(

object sender, DataGridViewDataErrorEventArgs e)
{
if (e.Exception == null) return;
// If the user-specified value is invalid, cancel the change

// and display the error icon in the row header.
if ((e.Context & DataGridViewDataErrorContexts.Commit) != 0 &&
(typeof(FormatException).IsAssignableFrom(e.Exception.GetType())
||
typeof(ArgumentException).IsAssignableFrom(e.Exception.GetType())))
{
dataGridView1.Rows[e.RowIndex].ErrorText =
"The specified value is invalid.";
e.Cancel = true;
}
else
{
// Rethrow any exceptions that aren't related to the user input.
e.ThrowException = true;
}
}
private void dataGridView1_CellEndEdit(

{
// Ensure that the error icon in the row header is hidden.
dataGridView1.Rows[e.RowIndex].ErrorText = "";
}
private void dataGridView1_CellValueChanged(

{
// Retrieve the property to change.
String nameOfPropertyToChange =
dataGridView1.Columns[e.ColumnIndex].Name;
PropertyInfo propertyToChange =
typeof(DataGridViewColumn).GetProperty(nameOfPropertyToChange);
// Retrieve the column to change.

String nameOfColumnToChange =
(String)dataGridView1["Column", e.RowIndex].Value;
DataGridViewColumn columnToChange =
dataGridView1.Columns[nameOfColumnToChange];
// Use reflection to update the value of the column property.

propertyToChange.SetValue(columnToChange,
dataGridView1[nameOfPropertyToChange, e.RowIndex].Value, null);
}
}
Comentários
Para usar esse aplicativo de demonstração:
Altere o tamanho do formulário. Observe como as colunas alteram suas larguras

enquanto retém as proporções indicadas pelos valores de FillWeight propriedade.
Altere os tamanhos das colunas, arrastando os divisores de coluna com o mouse.

Observe como os FillWeight valores são alterados.
Altere o MinimumWidth valor de uma coluna e arraste para redimensionar o

formulário. Observe como, quando você torna o formulário pequeno o suficiente,
os Width valores não ficam abaixo dos MinimumWidth valores.
Altere os MinimumWidth valores de todas as colunas para números grandes para

que os valores combinados excedam a largura do controle. Observe como a barra
de rolagem horizontal é exibida.
Altere os AutoSizeMode valores de algumas colunas. Observe o efeito quando

você redimensiona as colunas ou o formulário.

Confira também
DataGridView
DataGridViewColumn
DataGridViewColumn.FillWeight
DataGridViewColumn.MinimumWidth
DataGridViewColumn.Resizable
Control.RightToLeft
Como definir os modos de
dimensionamento do controle
Artigo • 02/06/2023
Os procedimentos a seguir demonstram alguns cenários comuns que personalizam ou

combinam as opções de dimensionamento disponíveis para o DataGridView controle e
para colunas específicas em um controle.
Para criar uma coluna de largura fixa

Defina a AutoSizeMode propriedade comoNone, a Resizable propriedade
comoFalse, a true ReadOnly propriedade e a Width propriedade como um valor
apropriado.
C#
idColumn.HeaderText = "ID";
idColumn.AutoSizeMode = DataGridViewAutoSizeColumnMode.None;
idColumn.Resizable = DataGridViewTriState.False;
idColumn.Width = 20;
Para criar uma coluna que ajusta seu tamanho para o

conteúdo
Defina a AutoSizeMode propriedade como um modo de dimensionamento
baseado em conteúdo.
C#
DataGridViewTextBoxColumn titleColumn =
titleColumn.HeaderText = "Title";
titleColumn.AutoSizeMode =
DataGridViewAutoSizeColumnMode.AllCellsExceptHeader;
Para criar colunas de modo de preenchimento para
valores de tamanho e importância variáveis
Defina a DataGridView.AutoSizeColumnsMode propriedade para Fill definir o
modo de dimensionamento para todas as colunas que não substituem esse valor.
Defina as FillWeight propriedades das colunas como valores proporcionais às
larguras médias de conteúdo. Defina as MinimumWidth propriedades de colunas
importantes para garantir a exibição parcial do conteúdo.
C#
DataGridViewTextBoxColumn subTitleColumn =
subTitleColumn.HeaderText = "Subtitle";
subTitleColumn.MinimumWidth = 50;
subTitleColumn.FillWeight = 100;
DataGridViewTextBoxColumn summaryColumn =
summaryColumn.HeaderText = "Summary";
summaryColumn.MinimumWidth = 50;
summaryColumn.FillWeight = 200;
DataGridViewTextBoxColumn contentColumn =
contentColumn.HeaderText = "Content";
contentColumn.MinimumWidth = 50;
contentColumn.FillWeight = 300;
Exemplo
O exemplo de código completo a seguir fornece um aplicativo de demonstração que
pode ajudá-lo a entender as opções de dimensionamento descritas neste tópico.
C#
using System;
using System.Data;
using System.Text;

{
{
}
public Form1()
{
Width *= 2;
Text = "DataGridView Sizing Scenarios";
}
protected override void OnLoad(EventArgs e)

{
idColumn.HeaderText = "ID";
idColumn.AutoSizeMode = DataGridViewAutoSizeColumnMode.None;
idColumn.Resizable = DataGridViewTriState.False;
idColumn.Width = 20;
DataGridViewTextBoxColumn titleColumn =
titleColumn.HeaderText = "Title";
titleColumn.AutoSizeMode =
DataGridViewAutoSizeColumnMode.AllCellsExceptHeader;
DataGridViewTextBoxColumn subTitleColumn =
subTitleColumn.HeaderText = "Subtitle";
subTitleColumn.MinimumWidth = 50;
subTitleColumn.FillWeight = 100;
DataGridViewTextBoxColumn summaryColumn =
summaryColumn.HeaderText = "Summary";
summaryColumn.MinimumWidth = 50;
summaryColumn.FillWeight = 200;
DataGridViewTextBoxColumn contentColumn =
contentColumn.HeaderText = "Content";
contentColumn.MinimumWidth = 50;
contentColumn.FillWeight = 300;
dataGridView1.Columns.AddRange(new DataGridViewTextBoxColumn[] {
idColumn, titleColumn, subTitleColumn,
summaryColumn, contentColumn });
dataGridView1.Rows.Add(new String[] { "1",
"A Short Title", "A Longer SubTitle",
"A short description of the main point.",
"The full contents of the topic, with detailed examples." });
base.OnLoad(e);
}
}
Para usar esse aplicativo de demonstração:
Altere o tamanho do formulário. Observe como as colunas de modo de

preenchimento alteram suas larguras mantendo as proporções indicadas pelos
valores de FillWeight propriedade. Observe como uma coluna impede
MinimumWidth que ela seja alterada quando o formulário é muito pequeno.
Altere os tamanhos das colunas, arrastando os divisores de coluna com o mouse.

Observe como algumas colunas não podem ser redimensionadas e como as
colunas redimensionáveis não podem ficar mais estreitas do que suas larguras
mínimas.
Confira também
DataGridView
DataGridViewColumn.Resizable
DataGridViewColumn.FillWeight
DataGridViewColumn.MinimumWidth
Como: Redimensionar de forma
programática as células para que o
conteúdo caiba no controle
Artigo • 02/06/2023
Você pode usar os DataGridView métodos de controle para redimensionar linhas,

colunas e cabeçalhos para que eles exibam valores inteiros sem truncamento. Você
pode usar esses métodos para redimensionar DataGridView elementos em momentos
de sua escolha. Como alternativa, você pode configurar o controle para redimensionar
esses elementos automaticamente sempre que o conteúdo é alterado. No entanto, isso
pode ser ineficiente quando você estiver trabalhando com grandes conjuntos de dados
ou quando seus dados forem alterados com frequência. Para obter mais informações,
consulte Sizing Options in the Windows Forms DataGridView Control (Opções de
dimensionamento no controle DataGridView dos Windows Forms).
Normalmente, você ajustará DataGridView os elementos programaticamente para

ajustar seu conteúdo somente quando carregar novos dados de uma fonte de dados ou
quando o usuário editar um valor. Isso é útil para otimizar o desempenho, mas também
é útil quando desejar permitir que os usuários redimensionem manualmente linhas e
colunas com o mouse.
O exemplo de código a seguir demonstra as opções disponíveis para o

redimensionamento programático.
Exemplo
C#
using System;
public class ProgrammaticSizing : System.Windows.Forms.Form

{
private FlowLayoutPanel flowLayoutPanel1;
public ProgrammaticSizing()
{
AddDirections();
this.Load += new EventHandler(InitializeDataGridView);
AddButton(button1, "Reset",
new EventHandler(ResetToDisorder));
AddButton(button2, "Change Column 3 Header",
new EventHandler(ChangeColumn3Header));
AddButton(button3, "Change Meatloaf Recipe",
new EventHandler(ChangeMeatloafRecipe));
AddButton(button10, "Change Restaurant 2",
new EventHandler(ChangeRestaurant));
AddButtonsForProgrammaticResizing();
}
#region form code

{
this.flowLayoutPanel1 = new FlowLayoutPanel();
this.flowLayoutPanel1.FlowDirection
= FlowDirection.TopDown;
this.flowLayoutPanel1.Location = new Point(492, 0);
this.flowLayoutPanel1.AutoSize = true;
this.Controls.Add(this.flowLayoutPanel1);
this.Text = this.GetType().Name;
}
private void AddDirections()

{
Label directions = new Label();
directions.AutoSize = true;
String newLine = Environment.NewLine;
directions.Text = "Press the buttons that start " + newLine
+ "with 'Change' to see how different sizing " + newLine
+ "modes deal with content changes.";
flowLayoutPanel1.Controls.Add(directions);
}
#endregion
[STAThread]
static void Main()
{
Application.Run(new ProgrammaticSizing());
}
private Size startingSize;

private string thirdColumnHeader = "Main Ingredients";
private string boringMeatloaf = "ground beef";
private string boringMeatloafRanking = "*";
private bool boringRecipe;
private bool shortMode;
private DataGridView dataGridView1;
private string otherRestaurant = "Gomes's Saharan Sushi";
private void InitializeDataGridView(Object sender,

EventArgs ignoredToo)
{
this.dataGridView1 = new DataGridView();
this.dataGridView1.Location = new Point(0, 0);
this.dataGridView1.Size = new Size(292, 266);
startingSize = new Size(450, 400);
dataGridView1.Size = startingSize;
AddColumns();
PopulateRows();
shortMode = false;
boringRecipe = true;
}
private void AddColumns()

{
dataGridView1.ColumnCount = 4;
dataGridView1.ColumnHeadersVisible = true;
DataGridViewCellStyle columnHeaderStyle =
new DataGridViewCellStyle();
columnHeaderStyle.BackColor = Color.Aqua;
columnHeaderStyle.Font = new Font("Verdana", 10,
FontStyle.Bold);
dataGridView1.ColumnHeadersDefaultCellStyle =
columnHeaderStyle;
dataGridView1.Columns[0].Name = "Recipe";
dataGridView1.Columns[1].Name = "Category";
dataGridView1.Columns[2].Name = thirdColumnHeader;
dataGridView1.Columns[3].Name = "Rating";
}
private void PopulateRows()

{
string[] row1 = {
"Meatloaf", "Main Dish",
boringMeatloaf, boringMeatloafRanking
};
string[] row2 = {
"Key Lime Pie", "Dessert",
"lime juice, evaporated milk", "****"
};
string[] row3 = {
"Orange-Salsa Pork Chops", "Main Dish",
"pork chops, salsa, orange juice", "****"
};
string[] row4 = {
"Black Bean and Rice Salad", "Salad",
"black beans, brown rice", "****"
};
string[] row5 = {
"Chocolate Cheesecake", "Dessert",
"cream cheese", "***"
};
string[] row6 = {
"Black Bean Dip",
"Appetizer", "black beans, sour cream", "***"
};
object[] rows = new object[] {
row1, row2, row3, row4, row5, row6
};
foreach (string[] row in rows)

dataGridView1.Rows.Add(row);
foreach (DataGridViewRow row in dataGridView1.Rows)
{
if (row.IsNewRow) break;
row.HeaderCell.Value = "Restaurant " + row.Index;
}
}
private void AddButton(Button button, string buttonLabel,

EventHandler handler)
{
button.Text = buttonLabel;
button.AutoSize = true;
flowLayoutPanel1.Controls.Add(button);
button.Click += handler;
}
private void ResetToDisorder(Object sender, EventArgs e)

{
Controls.Remove(dataGridView1);
dataGridView1.Dispose();
InitializeDataGridView(null, null);
}
private void ChangeColumn3Header(Object sender, EventArgs e)

{
Toggle(ref shortMode);
if (shortMode)
dataGridView1.Columns[2].HeaderText = "S";
else
dataGridView1.Columns[2].HeaderText =
thirdColumnHeader;
}
private static void Toggle(ref Boolean toggleThis)

{
toggleThis = !toggleThis;
}
private void ChangeMeatloafRecipe(Object sender,

EventArgs e)
{
Toggle(ref boringRecipe);
if (boringRecipe)
{
SetMeatloaf(boringMeatloaf, boringMeatloafRanking);
}
else
{
string greatMeatloafRecipe =
"1 lb. lean ground beef, "
+ "1/2 cup bread crumbs, 1/4 cup ketchup,"
+ "1/3 tsp onion powder, "
+ "1 clove of garlic, 1/2 pack onion soup mix "
+ " dash of your favorite BBQ Sauce";
SetMeatloaf(greatMeatloafRecipe, "***");
}
}
private void SetMeatloaf(string recipe, string rating)

{
dataGridView1.Rows[0].Cells[2].Value = recipe;
dataGridView1.Rows[0].Cells[3].Value = rating;
}
private void ChangeRestaurant(Object sender,

EventArgs ignored)
{
if (dataGridView1.Rows[2].HeaderCell.Value.Equals(otherRestaurant))
{
dataGridView1.Rows[2].HeaderCell.Value =
"Restaurant 2";
}
else
{
dataGridView1.Rows[2].HeaderCell.Value = otherRestaurant;
}
}
#region "programmatic resizing"

private void AddButtonsForProgrammaticResizing()
{
AddButton(button4, "Size Third Column",
new EventHandler(SizeThirdColumnHeader));
AddButton(button5, "Size Column Headers",
new EventHandler(SizeColumnHeaders));
AddButton(button6, "Size All Columns",
new EventHandler(SizeAllColumns));
AddButton(button7, "Size Third Row",
new EventHandler(SizeThirdRow));
AddButton(button8, "Size First Row Header Using All Headers",
new EventHandler(SizeFirstRowHeaderToAllHeaders));
AddButton(button9, "Size All Rows and Row Headers",
new EventHandler(SizeAllRowsAndTheirHeaders));
AddButton(button11, "Size All Rows ",
new EventHandler(SizeAllRows));
}
private void SizeThirdColumnHeader(Object sender,

EventArgs e)
{
dataGridView1.AutoResizeColumn(
2, DataGridViewAutoSizeColumnMode.ColumnHeader);
}
private void SizeColumnHeaders(Object sender, EventArgs e)

{
dataGridView1.AutoResizeColumnHeadersHeight(2);
}
private void SizeAllColumns(Object sender, EventArgs e)

{
dataGridView1.AutoResizeColumns(
DataGridViewAutoSizeColumnsMode.AllCells);
}
private void SizeThirdRow(Object sender, EventArgs e)

{
dataGridView1.AutoResizeRow(
2, DataGridViewAutoSizeRowMode.AllCellsExceptHeader);
}
private void SizeFirstRowHeaderToAllHeaders(Object sender, EventArgs e)

{
dataGridView1.AutoResizeRowHeadersWidth(
0, DataGridViewRowHeadersWidthSizeMode.AutoSizeToAllHeaders);
}
private void SizeAllRowsAndTheirHeaders(Object sender, EventArgs e)

{
dataGridView1.AutoResizeRows(
DataGridViewAutoSizeRowsMode.AllCells);
}
private void SizeAllRows(Object sender,
EventArgs e)
{
dataGridView1.AutoResizeRows(
DataGridViewAutoSizeRowsMode.AllCellsExceptHeaders);
}
#endregion
}
Confira também
DataGridView
DataGridView.AutoResizeColumn
DataGridView.AutoResizeColumnHeadersHeight
DataGridView.AutoResizeRow
DataGridView.AutoResizeRows
DataGridView.AutoResizeRowHeadersWidth
DataGridViewAutoSizeRowMode
Como redimensionar automaticamente
células quando o conteúdo é alterado
no controle DataGridView dos Windows
Forms
Artigo • 02/06/2023
Você pode configurar o DataGridView controle para redimensionar suas linhas, colunas
e cabeçalhos automaticamente sempre que o conteúdo for alterado, de modo que as
células sejam sempre grandes o suficiente para exibir seus valores sem recorte.
Você tem várias opções para restringir as células que são usadas para determinar os
novos tamanhos. Por exemplo, você pode configurar o controle para redimensionar
automaticamente a largura de suas colunas com base apenas nos valores de linhas
atualmente exibidas. Com isso, você pode evitar a ineficiência ao trabalhar com um
grande número de linhas, embora, nesse caso, você queira usar métodos de
dimensionamento, como AutoResizeColumns ajustar tamanhos em momentos de sua
escolha.
Para obter mais informações sobre redimensionamento automático, consulte Opções de

redimensionamento no controle DataGridView nos Windows Forms.
O exemplo de código a seguir demonstra as opções disponíveis para o

redimensionamento automático.
Exemplo
C#
using System;
public class AutoSizing : System.Windows.Forms.Form

{
public AutoSizing()
{
this.Load += new EventHandler(InitializeDataGridView);
AddDirections();
AddButton(button1, "Reset",
AddButton(button2, "Change Column 3 Header",
AddButton(button3, "Change Meatloaf Recipe",
AddButton(button4, "Change Restaurant 2",
new EventHandler(ChangeRestaurant));
AddButtonsForAutomaticResizing();
}
private void AddDirections()

{
Label directions = new Label();
directions.AutoSize = true;
String newLine = Environment.NewLine;
directions.Text = "Press the buttons that start " + newLine
+ "with 'Change' to see how different sizing " + newLine
+ "modes deal with content changes.";
flowLayoutPanel1.Controls.Add(directions);
}

{
flowLayoutPanel1 = new FlowLayoutPanel();
flowLayoutPanel1.FlowDirection = FlowDirection.TopDown;
flowLayoutPanel1.Location = new System.Drawing.Point(492, 0);
flowLayoutPanel1.AutoSize = true;
flowLayoutPanel1.TabIndex = 1;

Controls.Add(flowLayoutPanel1);
Text = this.GetType().Name;
AutoSize = true;
}
static void Main()
{
Application.Run(new AutoSizing());
}
private Size startingSize;

private string otherRestaurant = "Gomes's Saharan Sushi";
private void InitializeDataGridView(Object ignored,

EventArgs ignoredToo)
{
dataGridView1 = new System.Windows.Forms.DataGridView();
startingSize = new Size(450, 400);
dataGridView1.AutoSizeRowsModeChanged +=
new DataGridViewAutoSizeModeEventHandler
(WatchRowsModeChanges);
AddLabels();
SetUpColumns();
PopulateRows();
shortMode = false;
}
private void SetUpColumns()

{
dataGridView1.ColumnHeadersVisible = true;
columnHeaderStyle.Font = new Font("Verdana", 10,
FontStyle.Bold);
dataGridView1.ColumnHeadersDefaultCellStyle =
columnHeaderStyle;
dataGridView1.Columns[0].Name = "Recipe";
dataGridView1.Columns[1].Name = "Category";
dataGridView1.Columns[2].Name = thirdColumnHeader;
dataGridView1.Columns[3].Name = "Rating";
}
private void PopulateRows()

{
string[] row1 = {
"Meatloaf", "Main Dish", boringMeatloaf, boringMeatloafRanking
};
string[] row2 = {
"Key Lime Pie", "Dessert", "lime juice, evaporated milk", "****"
};
string[] row3 = {
"Orange-Salsa Pork Chops", "Main Dish",
"pork chops, salsa, orange juice", "****"
};
string[] row4 = {
"Black Bean and Rice Salad", "Salad",
"black beans, brown rice", "****"
};
string[] row5 = {
"Chocolate Cheesecake", "Dessert", "cream cheese", "***"
};
string[] row6 = {
"Black Bean Dip", "Appetizer", "black beans, sour cream", "***"
};
object[] rows = new object[] {
row1, row2, row3, row4, row5, row6
};
foreach (string[] row in rows)

dataGridView1.Rows.Add(row);

{
row.HeaderCell.Value = "Restaurant " + row.Index;
}
}

{
button.TabIndex = flowLayoutPanel1.Controls.Count;
flowLayoutPanel1.Controls.Add(button);
}
private void ResetToDisorder(Object sender, EventArgs e)

{
Controls.Remove(dataGridView1);
}
private void ChangeColumn3Header(Object sender, EventArgs e)

{
if (shortMode) dataGridView1.Columns[2].HeaderText = "S";
else
dataGridView1.Columns[2].HeaderText = thirdColumnHeader;
}
private static Boolean Toggle(ref Boolean toggleThis)
{
return toggleThis;
}
private void ChangeMeatloafRecipe(Object sender, EventArgs e)

{
if (boringRecipe)
{
}
else
{
string greatMeatloafRecipe = "1 lb. lean ground beef, "
+ "1/2 cup bread crumbs, 1/4 cup ketchup,"
+ "1/3 tsp onion powder, "
+ "1 clove of garlic, 1/2 pack onion soup mix,"
+ " dash of your favorite BBQ Sauce";
}
}
private void ChangeRestaurant(Object sender, EventArgs ignored)

{
if (dataGridView1.Rows[2].HeaderCell.Value.ToString() ==
otherRestaurant)
"Restaurant 2";
else
otherRestaurant;
}

{
dataGridView1.Rows[0].Cells[2].Value = recipe;
dataGridView1.Rows[0].Cells[3].Value = rating;
}
private string currentLayoutName =

"DataGridView.AutoSizeRowsMode is currently: ";
private void AddLabels()
{
Label current = (Label)
flowLayoutPanel1.Controls[currentLayoutName];
if (current == null)
{
current = new Label();
current.AutoSize = true;
current.Name = currentLayoutName;
current.Text = currentLayoutName +
dataGridView1.AutoSizeRowsMode.ToString();
flowLayoutPanel1.Controls.Add(current);
}
}
#region "Automatic Resizing"

private void AddButtonsForAutomaticResizing()
{
AddButton(button5, "Keep Column Headers Sized",
new EventHandler(ColumnHeadersHeightSizeMode));
AddButton(button6, "Keep Row Headers Sized",
new EventHandler(RowHeadersWidthSizeMode));
AddButton(button7, "Keep Rows Sized",
new EventHandler(AutoSizeRowsMode));
AddButton(button8, "Keep Row Headers Sized with RowsMode",
new EventHandler(AutoSizeRowHeadersUsingAllHeadersMode));
AddButton(button9, "Disable AutoSizeRowsMode",
new EventHandler(DisableAutoSizeRowsMode));
AddButton(button10, "AutoSize third column by rows",
new EventHandler(AutoSizeOneColumn));
AddButton(button11, "AutoSize third column by rows and headers",
new EventHandler(AutoSizeOneColumnIncludingHeaders));
}
private void ColumnHeadersHeightSizeMode(Object sender, EventArgs e)

{
dataGridView1.ColumnHeadersHeightSizeMode =
DataGridViewColumnHeadersHeightSizeMode.AutoSize;
}
private void RowHeadersWidthSizeMode(Object sender, EventArgs e)

{
dataGridView1.RowHeadersWidthSizeMode =
DataGridViewRowHeadersWidthSizeMode.AutoSizeToAllHeaders;
}
private void AutoSizeRowsMode(Object sender, EventArgs es)

{
dataGridView1.AutoSizeRowsMode =
DataGridViewAutoSizeRowsMode.AllCells;
}
private void AutoSizeRowHeadersUsingAllHeadersMode(

Object sender, System.EventArgs e)
{
dataGridView1.AutoSizeRowsMode =
DataGridViewAutoSizeRowsMode.AllHeaders;
}
private void WatchRowsModeChanges(object sender,

DataGridViewAutoSizeModeEventArgs modeEvent)
{
Label label =
(Label)flowLayoutPanel1.Controls[currentLayoutName];
if (modeEvent.PreviousModeAutoSized)
{
label.Text = "changed to a different " +
label.Name +
}
else
{
label.Text = label.Name +
}
}
private void DisableAutoSizeRowsMode(object sender,

EventArgs modeEvent)
{
dataGridView1.AutoSizeRowsMode = DataGridViewAutoSizeRowsMode.None;
}
private void AutoSizeOneColumn(object sender,

EventArgs theEvent)
{
DataGridViewColumn column = dataGridView1.Columns[2];
column.AutoSizeMode =
DataGridViewAutoSizeColumnMode.DisplayedCellsExceptHeader;
}
private void AutoSizeOneColumnIncludingHeaders(

object sender, EventArgs theEvent)
{
DataGridViewColumn column = dataGridView1.Columns[2];
column.AutoSizeMode = DataGridViewAutoSizeColumnMode.AllCells;
}
#endregion
}
Confira também
DataGridView
DataGridView.ColumnHeadersHeightSizeMode
DataGridView.RowHeadersWidthSizeMode
DataGridView.AutoSizeRowsMode
Como: Redimensionar de forma programática as células para que o conteúdo
caiba no controle DataGridView do Windows Forms
Classificando dados no controle
Windows Forms DataGridView
Artigo • 21/06/2023
Por padrão, os usuários podem classificar os dados em um DataGridView controle

clicando no cabeçalho de uma coluna de caixa de texto (ou pressionando F3 quando
uma célula de caixa de texto está focada em .NET Framework 4.7.2 e versões
posteriores). Você pode modificar a propriedade SortMode de colunas específicas para
permitir aos usuários classificar por outros tipos de coluna quando fizer sentido. Você
também pode classificar os dados de forma programática por qualquer coluna ou por
várias colunas.
Nesta seção
Modos de classificação da coluna no controle DataGridView dos Windows Forms
Descreve as opções para classificar os dados no controle.
Como: Definir os modos de classificação para colunas no controle DataGridView do

Windows Forms
Descreve como habilitar usuários para classificar por colunas que não são classificáveis
por padrão.
Como personalizar a classificação no controle DataGridView dos Windows Forms

Descreve como classificar dados programaticamente e como personalizar a classificação
usando o DataGridView.SortCompare evento ou implementando a IComparer interface .
Referência
DataGridView
DataGridView.Sort
Fornece documentação de referência para o Sort método .
DataGridViewColumn.SortMode
Fornece documentação de referência para a SortMode propriedade .
DataGridViewColumnSortMode
Fornece a documentação de referência para a DataGridViewColumnSortMode
enumeração .
Confira também
Modos de classificação da coluna no
Forms
Artigo • 02/06/2023
DataGridView as colunas têm três modos de classificação. O modo de classificação para

cada coluna é especificado por meio da SortMode propriedade da coluna, que pode ser
definida como um dos seguintes DataGridViewColumnSortMode valores de
enumeração.
DataGridViewColumnSortMode Descrição
valor
Automatic Padrão para colunas de caixa de texto. A menos que cabeçalhos de

coluna sejam usados para seleção, clicar no cabeçalho da coluna
classifica DataGridView automaticamente por esta coluna e exibe
um glifo indicando a ordem de classificação.
NotSortable Padrão para colunas sem caixa de texto. Você pode classificar essa
coluna programaticamente. No entanto, ela não se destina à
classificação, então nenhum espaço é reservado para o glifo de
classificação.
Programmatic Você pode classificar essa coluna programaticamente e o espaço é

reservado para o glifo de classificação.
Talvez você queira alterar o modo de classificação de uma coluna que usa o padrão
NotSortable se ela contiver valores que podem ser ordenados significativamente. Por
exemplo, se tiver uma coluna de banco de dados que contêm números que
representam os estados de item, você poderá exibir esses números como ícones
correspondentes ao associar uma coluna de imagem para a coluna de banco de dados.
Em seguida, você pode alterar os valores de célula numérica em valores de exibição de
imagem em um manipulador para o DataGridView.CellFormatting evento. Nesse caso,
definir a SortMode propriedade para Automatic permitir que os usuários classifiquem a
coluna. A classificação automática permitirá que os usuários agrupem itens que tenham
o mesmo estado, mesmo se os estados correspondentes aos números não tiverem uma
sequência natural. As colunas da caixa de seleção são outro exemplo no qual a
classificação automática é útil para agrupar itens no mesmo estado.
Você pode classificar um DataGridView programaticamente pelos valores em qualquer

coluna ou em várias colunas, independentemente das SortMode configurações. A
classificação programática é útil quando você deseja fornecer sua própria interface do
usuário para classificação ou quando você deseja implementar a classificação
personalizada. Fornecer sua própria interface do usuário de classificação é útil, por
exemplo, quando você define o DataGridView modo de seleção para habilitar a seleção
de cabeçalho de coluna. Nesse caso, embora os cabeçalhos de coluna não possam ser
usados para classificação, você ainda deseja que os cabeçalhos exibam o glifo de
classificação apropriado, para que você defina a SortMode propriedade como
Programmatic.
As colunas definidas como modo de classificação programática não exibem um glifo de

classificação automaticamente. Para essas colunas, você deve exibir o glifo por conta
própria definindo a DataGridViewColumnHeaderCell.SortGlyphDirection propriedade.
Isso é necessário se você quiser flexibilidade na classificação personalizada. Por
exemplo, se você classificar por DataGridView várias colunas, talvez queira exibir vários
glifos de classificação ou nenhum glifo de classificação.
Embora você possa classificar programaticamente por DataGridView qualquer coluna,

algumas colunas, como colunas de botão, podem não conter valores que podem ser
ordenados significativamente. Para essas colunas, uma SortMode configuração de
NotSortable propriedade indica que ela nunca será usada para classificação, portanto,
não é necessário reservar espaço no cabeçalho para o glifo de classificação.
Quando um DataGridView é classificado, você pode determinar a coluna de classificação

e a ordem de classificação verificando os valores das propriedades e SortOrder das
SortedColumn propriedades. Esses valores não são significativos após uma operação de
classificação personalizada. Para obter mais informações sobre classificação
personalizada, consulte a seção Classificação Personalizada neste tópico.
Quando um DataGridView controle que contém colunas associadas e não associadas é

classificado, os valores nas colunas não associadas não podem ser mantidos
automaticamente. Para manter esses valores, você deve implementar o modo virtual
definindo a VirtualMode propriedade true e tratando os eventos
eCellValuePushed.CellValueNeeded Para obter mais informações, consulte Como
implementar o modo virtual no controle DataGridView dos Windows Forms. Não há
suporte para a classificação por colunas não associadas no modo associado.
Classificação programática
Você pode classificar um DataGridView programaticamente chamando seu Sort método.
A Sort(DataGridViewColumn,ListSortDirection) sobrecarga do Sort método usa um e

um DataGridViewColumnListSortDirection valor de enumeração como parâmetros. Essa
sobrecarga é útil ao classificar por colunas com valores que podem ser ordenados
significativamente, mas que você não deseja configurar para a classificação automática.
Quando você chama essa sobrecarga e passa uma coluna com um SortMode valor de
propriedade, DataGridViewColumnSortMode.Automaticas propriedades e SortOrder as
SortedColumn propriedades são definidas automaticamente e o glifo de classificação
apropriado aparece no cabeçalho da coluna.
７ Observação
Quando o DataGridView controle é associado a uma fonte de dados externa

definindo a DataSource propriedade, a sobrecarga do
Sort(DataGridViewColumn,ListSortDirection) método não funciona para colunas
não associadas. Além disso, quando a VirtualMode propriedade é true , você pode
chamar essa sobrecarga apenas para colunas associadas. Para determinar se uma
coluna está associada a dados, verifique o valor da IsDataBound propriedade. Não
há suporte para a classificação por colunas não associadas no modo associado.
Classificação personalizada
Você pode personalizar DataGridView usando a Sort(IComparer) sobrecarga do Sort
método ou manipulando o SortCompare evento.
A Sort(IComparer) sobrecarga do método usa uma instância de uma classe que

implementa a IComparer interface como um parâmetro. Essa sobrecarga é útil quando
você deseja fornecer classificação personalizada. Por exemplo, quando os valores em
uma coluna não têm uma ordem de classificação natural ou quando a ordem de
classificação natural é inadequada. Nesse caso, você não pode usar a classificação
automática, mas talvez ainda queira que os usuários classifiquem clicando em
cabeçalhos de coluna. Você pode chamar essa sobrecarga em um manipulador para o
ColumnHeaderMouseClick evento se não usar cabeçalhos de coluna para seleção.
７ Observação
A sobrecarga do Sort(IComparer) método só funciona quando o DataGridView

controle não está associado a uma fonte de dados externa e o valor da
VirtualMode propriedade é false . Para personalizar a classificação para colunas
associadas a uma fonte de dados externa, você deve usar as operações de
classificação fornecidas pela fonte de dados. No modo virtual, você deve fornecer
suas próprias operações de classificação para colunas não associadas.
Para usar a sobrecarga do Sort(IComparer) método, você deve criar sua própria classe
que implementa a IComparer interface. Essa interface exige que sua classe implemente
o IComparer.Compare método, ao qual os DataGridView objetos passam
DataGridViewRow como entrada quando a sobrecarga do Sort(IComparer) método é
chamada. Com isso, você pode calcular a ordem correta da linha com base nos valores
em qualquer coluna.
A Sort(IComparer) sobrecarga do método não define as SortedColumn propriedades e

SortOrder , portanto, você deve sempre definir a
DataGridViewColumnHeaderCell.SortGlyphDirection propriedade para exibir o glifo de
classificação.
Como alternativa à sobrecarga do Sort(IComparer) método, você pode fornecer

classificação personalizada implementando um manipulador para o SortCompare
evento. Esse evento ocorre quando os usuários clicam nos cabeçalhos das colunas
configuradas para classificação automática ou quando você chama a
Sort(DataGridViewColumn,ListSortDirection) sobrecarga do Sort método. O evento
ocorre para cada par de linhas no controle, permitindo que você calcule a ordem
correta.
７ Observação
O SortCompare evento não ocorre quando a DataSource propriedade é definida

ou quando o valor da VirtualMode propriedade é true .
Confira também
DataGridView
DataGridView.Sort
DataGridView.SortedColumn
DataGridView.SortOrder
DataGridViewColumnHeaderCell.SortGlyphDirection
do Windows Forms
Como: Personalizar a classificação no controle DataGridView do Windows Forms
Como: Definir os modos de classificação
para colunas no controle DataGridView
do Windows Forms
Artigo • 02/06/2023
No controle, as DataGridView colunas de caixa de texto usam a classificação automática

por padrão, enquanto outros tipos de coluna não são classificados automaticamente. Às
vezes, você desejará substituir esses padrões. Por exemplo, você pode exibir imagens no
lugar de texto, números ou valores de célula de enumeração. Embora as imagens não
possam ser classificadas, os valores subjacentes que elas representam podem ser
classificados.
DataGridView No controle, o SortMode valor da propriedade de uma coluna determina

seu comportamento de classificação.
O procedimento a seguir mostra a coluna Priority de Como personalizar a formatação

de dados no controle DataGridView dos Windows Forms. Esta coluna é uma coluna de
imagem e não pode ser classificada por padrão. Ela contém valores de célula reais que
são cadeias de caracteres; no entanto, ela pode ser classificada automaticamente.
Para definir o modo de classificação da coluna

Definir a propriedade DataGridViewColumn.SortMode.
C#
this.dataGridView1.Columns["Priority"].SortMode =
DataGridViewColumnSortMode.Automatic;

chamada Priority .

Confira também
DataGridView
Como: Personalizar a classificação no controle DataGridView do Windows Forms
Como personalizar a classificação no
Forms
Artigo • 21/06/2023
O DataGridView controle fornece classificação automática, mas, dependendo de suas

necessidades, talvez seja necessário personalizar as operações de classificação. Por
exemplo, é possível usar a classificação programática para criar uma interface do usuário
(UI) alternativa. Como alternativa, você pode manipular o SortCompare evento ou
chamar a Sort(IComparer) sobrecarga do Sort método para maior flexibilidade de
classificação, como classificar várias colunas.
Os exemplos de código a seguir demonstram essas três abordagens da classificação

personalizada. Para mais informações, consulte Modos de classificação da coluna no
controle DataGridView do Windows Forms.
Classificação programática
O exemplo de código a seguir demonstra uma classificação programática usando as
SortOrder propriedades e SortedColumn para determinar a direção da classificação e a
SortGlyphDirection propriedade para definir manualmente o glifo de classificação. A
Sort(DataGridViewColumn,ListSortDirection) sobrecarga do Sort método é usada para
classificar dados apenas em uma única coluna.
C#
using System;
class Form1 : Form

{
private Button sortButton = new Button();

// You can replace this code with designer-generated code.
public Form1()
{
dataGridView1.SelectionMode =
DataGridViewSelectionMode.ColumnHeaderSelect;
dataGridView1.MultiSelect = false;
sortButton.Dock = DockStyle.Bottom;
sortButton.Text = "Sort";
Controls.Add(sortButton);
Text = "DataGridView programmatic sort demo";
}
// Establishes the main entry point for the application.

static void Main()
{
}
// Populates the DataGridView.

// Replace this with your own code to populate the DataGridView.
public void PopulateDataGridView()
{
// Add columns to the DataGridView.
dataGridView1.Columns[0].HeaderText = "Last Name";
dataGridView1.Columns[1].HeaderText = "City";
// Put the new columns into programmatic sort mode
dataGridView1.Columns[0].SortMode =
DataGridViewColumnSortMode.Programmatic;
dataGridView1.Columns[1].SortMode =
// Populate the DataGridView.

dataGridView1.Rows.Add(new string[] { "Parker", "Seattle" });
dataGridView1.Rows.Add(new string[] { "Watson", "Seattle" });
dataGridView1.Rows.Add(new string[] { "Osborn", "New York" });
dataGridView1.Rows.Add(new string[] { "Jameson", "New York" });
dataGridView1.Rows.Add(new string[] { "Brock", "New Jersey" });
}

{
sortButton.Click += new EventHandler(sortButton_Click);
base.OnLoad(e);
}
private void sortButton_Click(object sender, System.EventArgs e)

{
// Check which column is selected, otherwise set NewColumn to null.
DataGridViewColumn newColumn =
dataGridView1.Columns.GetColumnCount(
DataGridViewElementStates.Selected) == 1 ?
dataGridView1.SelectedColumns[0] : null;
DataGridViewColumn oldColumn = dataGridView1.SortedColumn;
ListSortDirection direction;
// If oldColumn is null, then the DataGridView is not currently

sorted.
if (oldColumn != null)
{
// Sort the same column again, reversing the SortOrder.
if (oldColumn == newColumn &&
dataGridView1.SortOrder == SortOrder.Ascending)
{
direction = ListSortDirection.Descending;
}
else
{
// Sort a new column and remove the old SortGlyph.
direction = ListSortDirection.Ascending;
oldColumn.HeaderCell.SortGlyphDirection = SortOrder.None;
}
}
else
{
direction = ListSortDirection.Ascending;
}
// If no column has been selected, display an error dialog box.

if (newColumn == null)
{
MessageBox.Show("Select a single column and try again.",
"Error: Invalid Selection", MessageBoxButtons.OK,
}
else
{
dataGridView1.Sort(newColumn, direction);
newColumn.HeaderCell.SortGlyphDirection =
direction == ListSortDirection.Ascending ?
SortOrder.Ascending : SortOrder.Descending;
}
}
}
Classificação personalizada usando o evento

SortCompare
O exemplo de código a seguir demonstra a classificação personalizada usando um
SortCompare manipulador de eventos. O selecionado DataGridViewColumn é
classificado e, se houver valores duplicados na coluna, a coluna ID será usada para
determinar a ordem final.
C#
#region Using directives
using System;
using System.Data;
#endregion
class Form1 : Form
{
// Establish the main entry point for the application.

static void Main()
{
}
public Form1()
{
// This code can be replaced with designer generated code.
dataGridView1.SortCompare += new
DataGridViewSortCompareEventHandler(
this.dataGridView1_SortCompare);
Controls.Add(this.dataGridView1);
this.Text = "DataGridView.SortCompare demo";
}
// Replace this with your own population code.

public void PopulateDataGridView()
{
// Set the properties of the DataGridView columns.

dataGridView1.Columns[0].Name = "ID";
dataGridView1.Columns[1].Name = "Name";
dataGridView1.Columns[2].Name = "City";
dataGridView1.Columns["ID"].HeaderText = "ID";
dataGridView1.Columns["Name"].HeaderText = "Name";
dataGridView1.Columns["City"].HeaderText = "City";
// Add rows of data to the DataGridView.

dataGridView1.Rows.Add(new string[] { "1", "Parker", "Seattle" });
dataGridView1.Rows.Add(new string[] { "2", "Parker", "New York" });
dataGridView1.Rows.Add(new string[] { "3", "Watson", "Seattle" });
dataGridView1.Rows.Add(new string[] { "4", "Jameson", "New Jersey"
});
dataGridView1.Rows.Add(new string[] { "5", "Brock", "New York" });
dataGridView1.Rows.Add(new string[] { "6", "Conner", "Portland" });
// Autosize the columns.

dataGridView1.AutoResizeColumns();
}
private void dataGridView1_SortCompare(object sender,

DataGridViewSortCompareEventArgs e)
{
// Try to sort based on the cells in the current column.
e.SortResult = System.String.Compare(
e.CellValue1.ToString(), e.CellValue2.ToString());
// If the cells are equal, sort based on the ID column.

if (e.SortResult == 0 && e.Column.Name != "ID")
{
e.SortResult = System.String.Compare(
dataGridView1.Rows[e.RowIndex1].Cells["ID"].Value.ToString(),
dataGridView1.Rows[e.RowIndex2].Cells["ID"].Value.ToString());
}
e.Handled = true;
}
}
Classificação personalizada usando a interface

IComparer
O exemplo de código a IComparer seguir demonstra a classificação personalizada
usando a Sort(IComparer) sobrecarga do Sort método , que usa uma implementação da
interface para executar uma classificação de várias colunas.
C#
using System;
#endregion
class Form1 : Form

{
private DataGridView DataGridView1 = new DataGridView();
private FlowLayoutPanel FlowLayoutPanel1 = new FlowLayoutPanel();
private Button Button1 = new Button();
private RadioButton RadioButton1 = new RadioButton();
private RadioButton RadioButton2 = new RadioButton();
// Establish the main entry point for the application.

{
}
public Form1()
{
// This code can be replaced with designer generated code.
AutoSize = true;
Text = "DataGridView IComparer sort demo";
FlowLayoutPanel1.FlowDirection = FlowDirection.TopDown;
FlowLayoutPanel1.Location = new System.Drawing.Point( 304, 0 );
FlowLayoutPanel1.AutoSize = true;
FlowLayoutPanel1.Controls.Add( RadioButton1 );
FlowLayoutPanel1.Controls.Add( RadioButton2 );
FlowLayoutPanel1.Controls.Add( Button1 );
Button1.Text = "Sort";
RadioButton1.Text = "Ascending";
RadioButton2.Text = "Descending";
RadioButton1.Checked = true;
Controls.Add( FlowLayoutPanel1 );
Controls.Add( DataGridView1 );
}
protected override void OnLoad( EventArgs e )

{
Button1.Click += new EventHandler(Button1_Click);
base.OnLoad( e );
}
// Replace this with your own code to populate the DataGridView.

{
DataGridView1.Size = new Size(300, 300);

DataGridView1.ColumnCount = 2;
// Set the properties of the DataGridView columns.
DataGridView1.Columns[0].Name = "First";
DataGridView1.Columns[1].Name = "Last";
DataGridView1.Columns["First"].HeaderText = "First Name";
DataGridView1.Columns["Last"].HeaderText = "Last Name";
DataGridView1.Columns["First"].SortMode =
DataGridView1.Columns["Last"].SortMode =
// Add rows of data to the DataGridView.

DataGridView1.Rows.Add(new string[] { "Peter", "Parker" });
DataGridView1.Rows.Add(new string[] { "James", "Jameson" });
DataGridView1.Rows.Add(new string[] { "May", "Parker" });
DataGridView1.Rows.Add(new string[] { "Mary", "Watson" });
DataGridView1.Rows.Add(new string[] { "Eddie", "Brock" });
}
private void Button1_Click( object sender, EventArgs e )

{
if ( RadioButton1.Checked == true )
{
DataGridView1.Sort( new RowComparer( SortOrder.Ascending ) );
}
else if ( RadioButton2.Checked == true )
{
DataGridView1.Sort( new RowComparer( SortOrder.Descending ) );
}
}
private class RowComparer : System.Collections.IComparer

{
private static int sortOrderModifier = 1;
public RowComparer(SortOrder sortOrder)

{
if (sortOrder == SortOrder.Descending)
{
sortOrderModifier = -1;
}
else if (sortOrder == SortOrder.Ascending)
{
sortOrderModifier = 1;
}
}
public int Compare(object x, object y)

{
DataGridViewRow DataGridViewRow1 = (DataGridViewRow)x;
DataGridViewRow DataGridViewRow2 = (DataGridViewRow)y;
// Try to sort based on the Last Name column.

int CompareResult = System.String.Compare(
DataGridViewRow1.Cells[1].Value.ToString(),
DataGridViewRow2.Cells[1].Value.ToString());
// If the Last Names are equal, sort based on the First Name.
if ( CompareResult == 0 )
{
CompareResult = System.String.Compare(
DataGridViewRow1.Cells[0].Value.ToString(),
DataGridViewRow2.Cells[0].Value.ToString());
}
return CompareResult * sortOrderModifier;
}
}
}
Esses exemplos precisam de:
Confira também
DataGridView
do Windows Forms
Entrada de dados no controle
Artigo • 02/06/2023
O controle DataGridView oferece vários recursos que permitem a você alterar como os
usuários adicionam ou modificam dados no controle. Por exemplo, é possível tornar a
entrada de dados mais eficiente fornecendo os valores padrão para novas linhas e
alertando usuários quando ocorrem erros.
Nesta seção
Como: Especificar o modo de edição do controle DataGridView do Windows Forms
Descreve como alterar a maneira como os usuários iniciam a edição de células.

Windows Forms
Descreve como preencher previamente a linha para novos registros para economizar
tempo de entrada de dados.
Usando a linha para novos registros no controle DataGridView dos Windows Forms
Descreve a linha para novos registros em detalhes, incluindo informações sobre como
escondê-lo, sobre a personalização de sua aparência e sobre como ele se relaciona com
a Rows coleção.

Descreve como validar a entrada do usuário para evitar erros de formatação de entrada
de dados.

Descreve como manipular erros de entrada de dados que se originam da fonte de
dados quando o usuário tentar confirmar um novo valor.
Referência
DataGridView
DataGridView.EditMode
Fornece documentação de referência para a EditMode propriedade.
DataGridView.DefaultValuesNeeded
Fornece documentação de referência para o DefaultValuesNeeded evento.
DataGridView.DataError
Fornece documentação de referência para o DataError evento.
DataGridView.CellValidating
Fornece documentação de referência para o CellValidating evento.
Confira também
Como: Especificar o modo de edição do
Forms
Artigo • 02/06/2023
Por padrão, os usuários podem editar o conteúdo da célula da caixa de texto atual
DataGridView digitando-a ou pressionando F2. Isso colocará a célula no modo de
edição se todas as condições a seguir forem atendidas:
A fonte de dados subjacente der suporte à edição.
O DataGridView controle está habilitado.
O valor da propriedade EditMode não é EditProgrammatically.
As propriedade ReadOnly de célula, linha, coluna e controle estiverem definidas

como false .
No modo de edição, o usuário pode alterar o valor da célula e pressionar ENTER para
confirmar a alteração ou ESC para reverter a célula para seu valor original.
Você pode configurar um DataGridView controle para que uma célula entre no modo de
edição assim que ela se tornar a célula atual. O comportamento das teclas ENTER e ESC
fica inalterado nesse caso, mas a célula permanece no modo de edição depois que o
valor é confirmado ou revertido. Você também pode configurar o controle para que as
células entrem no modo de edição somente quando os usuários digitam na célula ou
quando pressionam F2. Por fim, você pode impedir que as células entrem no modo de
edição, exceto quando você chama o BeginEdit método.
Para alterar o modo de edição de um controle

DataGridView
Defina a DataGridView.EditMode propriedade como a enumeração apropriada
DataGridViewEditMode .
C#
this.dataGridView1.EditMode = DataGridViewEditMode.EditOnEnter;
Confira também
DataGridView
DataGridView.EditMode
Como: Especificar valores padrão para
novas linhas no controle DataGridView
do Windows Forms
Artigo • 21/06/2023
Você pode tornar a entrada de dados mais conveniente quando o aplicativo preenche
valores padrão para linhas recém-adicionadas. Com a DataGridView classe , você pode
preencher valores padrão com o DefaultValuesNeeded evento . Esse evento é gerado
quando o usuário insere a linha para novos registros. Quando o código manipula esse
evento, você pode preencher as células desejadas com valores de sua escolha.
O exemplo de código a seguir demonstra como especificar valores padrão para novas
linhas usando o DefaultValuesNeeded evento .
Exemplo
C#
private void dataGridView1_DefaultValuesNeeded(object sender,

System.Windows.Forms.DataGridViewRowEventArgs e)
{
e.Row.Cells["Region"].Value = "WA";
e.Row.Cells["City"].Value = "Redmond";
e.Row.Cells["PostalCode"].Value = "98052-6399";
e.Row.Cells["Country"].Value = "USA";
e.Row.Cells["CustomerID"].Value = NewCustomerId();
}
Uma NewCustomerId função para gerar valores exclusivos CustomerID .
Confira também
DataGridView
Usando a linha para novos registros no controle DataGridView dos Windows
Forms
Usando a linha para novos registros no
Forms
Artigo • 02/06/2023
Ao usar um DataGridView para editar dados em seu aplicativo, você geralmente deseja
dar aos usuários a capacidade de adicionar novas linhas de dados ao armazenamento
de dados. O DataGridView controle dá suporte a essa funcionalidade fornecendo uma
linha para novos registros, que sempre é mostrada como a última linha. Ela é marcada
com um símbolo de asterisco (*) em seu cabeçalho de linha. As seções a seguir tratam
de algumas coisas que você deve considerar quando programar com a linha de novos
registros habilitada.
Exibindo a linha de novos registros

Use a AllowUserToAddRows propriedade para indicar se a linha para novos registros é
exibida. O valor padrão dessa propriedade é true .
Para o caso associado a dados, a linha para novos registros será mostrada se a
AllowUserToAddRows propriedade do controle e a IBindingList.AllowNew propriedade
da fonte de dados forem ambas true . Se uma delas for false , a linha não será exibida.
Preenchendo a linha de novos registros com os

dados padrão
Quando o usuário seleciona a linha para novos registros como a linha atual, o
DataGridView controle aciona o DefaultValuesNeeded evento.
Esse evento fornece acesso ao novo DataGridViewRow e permite que você preencha a
nova linha com dados padrão. Para obter mais informações, consulte Como especificar
valores padrão para novas linhas no controle DataGridView dos Windows Forms
A coleção de linhas
A linha para novos registros está contida na DataGridView coleção do Rows controle,
mas se comporta de forma diferente em dois aspectos:
A linha para novos registros não pode ser removida da Rows coleção
programaticamente. Um InvalidOperationException é lançado se isso for tentado.
O usuário também não pode excluir a linha de novos registros. O
DataGridViewRowCollection.Clear método não remove essa linha da Rows coleção.
Nenhuma linha pode ser adicionada após a linha de novos registros. Um

InvalidOperationException será gerado se isso for tentado. Como resultado, a linha
para novos registros é sempre a última linha no DataGridView controle. Os
métodos que DataGridViewRowCollection adicionam linhas e
AddCopyAddAddCopiestodos os métodos de inserção de chamadas internamente
quando a linha para novos registros está presente.
Personalização visual da linha de novos

registros
Quando a linha para novos registros é criada, ela é baseada na linha especificada pela
RowTemplate propriedade. Qualquer estilo de célula que não for especificado para essa
linha será herdado de outras propriedades. Para obter mais informações sobre herança
de estilo de célula, consulte Estilos de célula no controle DataGridView dos Windows
Forms.
Os valores iniciais exibidos pelas células na linha para novos registros são recuperados
da propriedade de DefaultNewRowValue cada célula. Para células do tipo
DataGridViewImageCell, essa propriedade retorna uma imagem de espaço reservado.
Caso contrário, essa propriedade retornará null . Você pode substituir essa propriedade
para retornar um valor personalizado. No entanto, esses valores iniciais podem ser
substituídos por um DefaultValuesNeeded manipulador de eventos quando o foco entra
na linha para novos registros.
Os ícones padrão do cabeçalho dessa linha, que são uma seta ou um asterisco, não são
expostos publicamente. Se você quiser personalizar os ícones, precisará criar uma classe
personalizada DataGridViewRowHeaderCell .
Os ícones padrão usam a ForeColor propriedade do DataGridViewCellStyle em uso pela

célula de cabeçalho de linha. Os ícones padrão não serão renderizados se não houver
espaço suficiente para exibi-los completamente.
Se a célula do cabeçalho de linha tiver um valor de cadeia de caracteres definido e, se

não houver espaço suficiente para o texto e o ícone, o ícone será descartado primeiro.
Classificação
No modo não associado, novos registros sempre serão adicionados ao final do
DataGridView mesmo se o usuário tiver classificado o conteúdo do DataGridView. O
usuário precisará aplicar a classificação novamente para classificar a linha para a posição
correta; esse comportamento é semelhante ao do ListView controle.
Em modos virtuais ou com associação de dados, o comportamento de inserção quando

uma classificação for aplicada dependerá da implementação do modelo de dados. Para
ADO.NET, a linha é imediatamente classificada na posição correta.
Outras observações sobre a linha de novos

registros
Não é possível definir a Visible propriedade dessa linha como false . Um
InvalidOperationException será gerado se isso for tentado.
A linha de novos registros sempre é criada no estado desmarcado.
Modo virtual
Se estiver implementando o modo virtual, você precisará monitorar quando uma linha
de novos registros é necessária no modelo de dados e o momento para reverter a
adição da linha. A implementação exata dessa funcionalidade depende da
implementação do modelo de dados e de sua semântica de transação, por exemplo, se
o escopo de confirmação está no nível da célula ou da linha. Para obter mais
informações, consulte Modo virtual no controle DataGridView dos Windows Forms.
Confira também
DataGridView
Windows Forms
Passo a passo: Validando dados no
Forms
Artigo • 21/06/2023
Ao exibir a funcionalidade de entrada de dados para usuários, frequentemente é

necessário validar os dados inseridos no formulário. A DataGridView classe fornece uma
maneira conveniente de executar a validação antes que os dados sejam confirmados no
armazenamento de dados. Você pode validar os dados manipulando o CellValidating
evento , que é gerado pelo DataGridView quando a célula atual é alterada.
Neste passo a passo, você recuperará linhas da Customers tabela no banco de dados de
exemplo Northwind e as exibirá em um DataGridView controle . Quando um usuário
edita uma célula na CompanyName coluna e tenta sair da célula, o CellValidating
manipulador de eventos examinará a nova cadeia de caracteres de nome da empresa
para garantir que ela não esteja vazia; se o novo valor for uma cadeia de caracteres
vazia, o DataGridView impedirá que o cursor do usuário saia da célula até que uma
cadeia de caracteres não vazia seja inserida.
Para copiar o código deste tópico como uma única lista, consulte Como Validar Dados
no Controle DataGridView do Windows Forms.
Pré-requisitos

Server.
Validar dados inseridos em um DataGridView

1. Crie uma classe que deriva de Form e contém um DataGridView controle e um
BindingSource componente.
O exemplo de código a seguir fornece inicialização básica e inclui um método

Main .
C#
using System;
using System.Data;

{
public Form1()
{
this.Text = "DataGridView validation demo (disallows empty
CompanyName)";
}
C#
[STAThread]
static void Main()
{
}
}
2. Implemente um método na definição de classe do formulário para manipular os

detalhes de conexão ao banco de dados.
Este exemplo de código usa um GetData método que retorna um objeto

preenchido DataTable . Verifique se a variável connectionString é definida como
um valor apropriado para o banco de dados.
） Importante

Autenticação do Windows, também conhecida como segurança integrada, é
C#
private static DataTable GetData(string selectCommand)

{
string connectionString =
"Initial Catalog=Northwind;Data Source=localhost;Packet
Size=4096";
// Connect to the database and fill a data table.

SqlDataAdapter adapter =
new SqlDataAdapter(selectCommand, connectionString);
DataTable data = new DataTable();
adapter.Fill(data);
return data;
}
3. Implemente um manipulador para o evento do Load formulário que inicializa e

DataGridViewBindingSource e configura a associação de dados.
C#

{
// Attach DataGridView events to the corresponding event handlers.
this.dataGridView1.CellValidating += new
DataGridViewCellValidatingEventHandler(dataGridView1_CellValidating);
this.dataGridView1.CellEndEdit += new
DataGridViewCellEventHandler(dataGridView1_CellEndEdit);
// Initialize the BindingSource and bind the DataGridView to it.

bindingSource1.DataSource = GetData("select * from Customers");
this.dataGridView1.DataSource = bindingSource1;
this.dataGridView1.AutoResizeColumns(
}
4. Implemente manipuladores para os DataGridView eventos e CellEndEdit do

CellValidating controle.
O CellValidating manipulador de eventos é onde você determina se o valor de uma

célula na CompanyName coluna está vazio. Se o valor da célula falhar na validação,
defina a Cancel propriedade da
System.Windows.Forms.DataGridViewCellValidatingEventArgs classe como true .
Isso faz com que o DataGridView controle impeça que o cursor saia da célula.
Defina a ErrorText propriedade na linha como uma cadeia de caracteres explicativa.
Isso exibirá um ícone de erro com uma ToolTip que contém o texto de erro.
CellEndEdit No manipulador de eventos, defina a ErrorText propriedade na linha
como a cadeia de caracteres vazia. O CellEndEdit evento ocorre somente quando a
célula sai do modo de edição, o que não pode ser feito se falhar na validação.
C#
private void dataGridView1_CellValidating(object sender,

DataGridViewCellValidatingEventArgs e)
{
string headerText =
dataGridView1.Columns[e.ColumnIndex].HeaderText;
// Abort validation if cell is not in the CompanyName column.

if (!headerText.Equals("CompanyName")) return;
// Confirm that the cell is not empty.

if (string.IsNullOrEmpty(e.FormattedValue.ToString()))
{
"Company Name must not be empty";
e.Cancel = true;
}
}
void dataGridView1_CellEndEdit(object sender, DataGridViewCellEventArgs

e)
{
// Clear the row error in case the user presses ESC.
dataGridView1.Rows[e.RowIndex].ErrorText = String.Empty;
}
esperada.

Você verá um DataGridView preenchido com dados da Customers tabela. Ao clicar

duas vezes em uma célula da coluna CompanyName , é possível editar o valor. Se você
excluir todos os caracteres e pressionar a tecla TAB para sair da célula, o
DataGridView impedirá que você saia. Quando você digita uma cadeia de
caracteres não vazia na célula, o DataGridView controle permite que você saia da
célula.
Próximas etapas
Esse aplicativo fornece uma compreensão básica dos DataGridView recursos do
Windows Forms.
Habilite ou restrinja a entrada do usuário para o DataGridView controle. Para obter

Verifique a entrada do usuário para erros relacionados ao banco de dados. Para

obter mais informações, consulte Instruções passo a passo: identificando erros que
ocorrem durante a entrada de dados no controle DataGridView do Windows
Forms.
Personalizar a Aparência de Células no Controle DataGridView do Windows Forms
e Como Definir Estilos de Fonte e Cor no Controle DataGridView do Windows
Forms.
Confira também
DataGridView
BindingSource
Como validar dados no controle Windows Forms DataGridView
Como: Validar dados no controle
Artigo • 21/06/2023
O exemplo de código a seguir demonstra como validar os dados inseridos por um

usuário em um DataGridView controle . Neste exemplo, o DataGridView é preenchido
com linhas da Customers tabela do banco de dados de exemplo Northwind. Quando o
usuário edita uma célula na coluna, seu CompanyName valor é testado quanto à validade
verificando se ele não está vazio. Se o manipulador de eventos do CellValidating evento
descobrir que o valor é uma cadeia de caracteres vazia, o DataGridView impedirá que o
usuário saia da célula até que uma cadeia de caracteres não vazia seja inserida.
Para obter uma explicação completa desse exemplo de código, consulte Passo a passo:
validando dados no controle Windows Forms DataGridView.
Exemplo
C#
using System;
using System.Data;

{
public Form1()
{
this.Text = "DataGridView validation demo (disallows empty
CompanyName)";
}

{
// Attach DataGridView events to the corresponding event handlers.
this.dataGridView1.CellValidating += new
DataGridViewCellValidatingEventHandler(dataGridView1_CellValidating);
this.dataGridView1.CellEndEdit += new
DataGridViewCellEventHandler(dataGridView1_CellEndEdit);

}
private void dataGridView1_CellValidating(object sender,

DataGridViewCellValidatingEventArgs e)
{
string headerText =
dataGridView1.Columns[e.ColumnIndex].HeaderText;
// Abort validation if cell is not in the CompanyName column.

if (!headerText.Equals("CompanyName")) return;
// Confirm that the cell is not empty.

if (string.IsNullOrEmpty(e.FormattedValue.ToString()))
{
"Company Name must not be empty";
e.Cancel = true;
}
}
void dataGridView1_CellEndEdit(object sender, DataGridViewCellEventArgs

e)
{
// Clear the row error in case the user presses ESC.
dataGridView1.Rows[e.RowIndex].ErrorText = String.Empty;
}

{
Size=4096";
// Connect to the database and fill a data table.

adapter.Fill(data);
return data;
}
[STAThread]
static void Main()
{
}
}
Referências aos assemblies System, System.Data, System.Windows.Forms e

System.XML.

Confira também
DataGridView
BindingSource
Passo a passo: Identificando Erros que
Ocorrem Durante a Entrada de Dados
no Controle DataGridView do Windows
Forms
Artigo • 02/06/2023
O tratamento de erros do armazenamento de dados subjacente é um recurso necessário

para um aplicativo de entrada de dados. O controle Windows Forms DataGridView
facilita a exposição do DataError evento, que é gerado quando o armazenamento de
dados detecta uma violação de restrição ou uma regra de negócios quebrada.
Neste passo a passo, você recuperará linhas da Customers tabela no banco de dados de
exemplo Northwind e as exibirá em um DataGridView controle. Quando um valor
duplicado CustomerID for detectado em uma nova linha ou em uma linha existente
editada, o DataError evento ocorrerá, que será tratado exibindo um MessageBox que
descreve a exceção.
Para copiar o código deste tópico como uma única lista, consulte Como tratar erros que
ocorrem durante a entrada de dados no controle DataGridView do Windows Forms.
Pré-requisitos

Server.
Tratar erros de entrada de dados no controle DataGridView
1. Crie uma classe que deriva Form e contenha um DataGridView controle e um

BindingSource componente.
O exemplo de código a seguir fornece inicialização básica e inclui um método

Main .
C#
using System;
using System.Data;

{
public Form1()
{
}
C#
[STAThread]
static void Main()
{
}
}
2. Implemente um método na definição de classe do formulário para manipular os

detalhes de conexão ao banco de dados.
Este exemplo de código usa um GetData método que retorna um objeto

preenchido DataTable . Verifique se a variável connectionString é definida como
um valor apropriado para o banco de dados.
） Importante

Autenticação do Windows (também conhecida como segurança integrada) é
C#
{
Size=4096";
// Connect to the database and fill a data table, including the

// schema information that contains the CustomerID column
// constraint.
adapter.Fill(data);
adapter.FillSchema(data, SchemaType.Source);
return data;
}
3. Implemente um manipulador para o evento do Load formulário que inicializa e

DataGridViewBindingSource configura a associação de dados.
C#

{
// Attach the DataError event to the corresponding event handler.
this.dataGridView1.DataError +=

}
4. Manipular o DataError evento no DataGridView.
Se o contexto do erro for uma operação de confirmação, exiba o erro em um

MessageBox.
C#
private void dataGridView1_DataError(object sender,

DataGridViewDataErrorEventArgs e)
{
// If the data source raises an exception when a cell value is
// commited, display an error message.
if (e.Exception != null &&
e.Context == DataGridViewDataErrorContexts.Commit)
{
MessageBox.Show("CustomerID value must be unique.");
}
}
esperada.

Você verá um DataGridView controle preenchido com dados da tabela Clientes. Se

você inserir um valor CustomerID duplicado e confirmar a edição, o valor da célula
será revertido automaticamente e você verá um MessageBox que exibe o erro de
entrada de dados.
Próximas etapas
Esse aplicativo fornece uma compreensão básica das DataGridView funcionalidades do
Windows Forms.

Validar a entrada do usuário no DataGridView controle. Para obter mais

informações, consulte Passo a passo: validando dados no controle DataGridView
dos Windows Forms.
Forms.
Confira também
DataGridView
BindingSource
Como: Identificar Erros que Ocorrem Durante a Entrada de Dados no Controle
Como: Identificar Erros que Ocorrem
Durante a Entrada de Dados no
Controle DataGridView do Windows
Forms
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como usar o DataGridView controle para

relatar erros de entrada de dados ao usuário.
Para obter uma explicação completa deste exemplo de código, consulte Passo a passo:
Manipulando erros que ocorrem durante a entrada de dados no controle datagridview
Windows Forms.
Exemplo
C#
using System;
using System.Data;

{
public Form1()
{
}

{
// Attach the DataError event to the corresponding event handler.
this.dataGridView1.DataError +=

}
private void dataGridView1_DataError(object sender,

DataGridViewDataErrorEventArgs e)
{
// If the data source raises an exception when a cell value is
// commited, display an error message.
if (e.Exception != null &&
e.Context == DataGridViewDataErrorContexts.Commit)
{
MessageBox.Show("CustomerID value must be unique.");
}
}

{
Size=4096";
// Connect to the database and fill a data table, including the

// schema information that contains the CustomerID column
// constraint.
adapter.Fill(data);
adapter.FillSchema(data, SchemaType.Source);
return data;
}
[STAThread]
static void Main()
{
}
}
Referências aos assemblies System, System.Data, System.Windows.Forms e

System.XML.
Confira também
DataGridView
BindingSource
Seleção e uso da Área de Transferência
com o controle DataGridView dos
Windows Forms
Artigo • 02/06/2023
O controle DataGridView oferece uma variedade de opções para configurar como os

usuários podem selecionar células, linhas e colunas. Por exemplo, você pode habilitar
uma ou várias seleções, seleção de todas as linhas ou colunas quando os usuários
clicam em células ou de todas as linhas ou colunas somente quando os usuários clicam
em seus cabeçalhos, o que permite a seleção da célula também. Se você quiser fornecer
sua própria interface do usuário para seleção, desabilite a seleção comum e gerencie
todas as seleções de forma programática. Além disso, você pode permitir que os
usuários copiem os valores selecionados para a área de transferência.
Nesta seção
Descreve as opções para seleção do usuário e programática no controle.

Descreve como configurar o controle para seleção única linha quando um usuário clica
em uma célula.
Como: Obter as células, as linhas e as colunas selecionadas no controle DataGridView do

Windows Forms
Descreve como trabalhar com as coleções selecionadas de célula, linha e coluna.
Como: Habilitar usuários para copiarem várias células na Área de Transferência usando o
Descreve como habilitar o suporte à área de transferência no controle.
Referência
DataGridView
DataGridView.SelectionMode
Fornece a documentação de referência para a SelectionMode propriedade.
ClipboardCopyMode
Fornece a documentação de referência para a ClipboardCopyMode propriedade.
DataGridViewSelectedCellCollection
Fornece a documentação de referência para a DataGridViewSelectedCellCollection
classe.
DataGridViewSelectedRowCollection
Fornece a documentação de referência para a DataGridViewSelectedRowCollection
classe.
DataGridViewSelectedColumnCollection
Fornece a documentação de referência para a DataGridViewSelectedColumnCollection
classe.
Confira também
Tratamento de teclado e mouse padrão no controle DataGridView dos Windows
Forms
Modos de seleção no controle
Artigo • 02/06/2023
Às vezes, você deseja que seu aplicativo execute ações com base em seleções de
usuário dentro de um DataGridView controle. Dependendo das ações, você talvez
queira restringir os tipos de seleção possíveis. Por exemplo, suponha que seu aplicativo
possa imprimir um relatório para o registro selecionado no momento. Nesse caso, talvez
você queira configurar o DataGridView controle para que clicar em qualquer lugar
dentro de uma linha sempre selecione a linha inteira e, portanto, apenas uma linha por
vez possa ser selecionada.
Você pode especificar as seleções permitidas definindo a DataGridView.SelectionMode

propriedade como um dos valores de enumeração a seguir DataGridViewSelectionMode
.
Valor de Descrição
DataGridViewSelectionMode
CellSelect Clicar em uma célula a seleciona. Cabeçalhos de linha e coluna

não podem ser usados para seleção.
ColumnHeaderSelect Clicar em uma célula a seleciona. Clicar em um cabeçalho de

coluna seleciona a coluna inteira. Cabeçalhos de coluna não
podem ser usados para classificação.
FullColumnSelect Clicar em um cabeçalho de coluna ou célula seleciona a coluna

inteira. Cabeçalhos de coluna não podem ser usados para
classificação.
FullRowSelect Clicar em um cabeçalho de linha ou célula seleciona toda a

linha.
RowHeaderSelect Modo de seleção padrão. Clicar em uma célula a seleciona.

Clicar em um cabeçalho de linha seleciona toda a linha.
７ Observação
Alterar o modo de seleção em tempo de execução automaticamente limpa a

seleção atual.
Por padrão, os usuários podem selecionar várias linhas, colunas ou células arrastando
com o mouse, pressionando CTRL ou SHIFT ao selecionar para estender ou modificar
uma seleção ou clicando na célula de cabeçalho do canto superior esquerdo para
selecionar todas as células no controle. Para evitar esse comportamento, defina a
MultiSelect propriedade como false .
Os FullRowSelect modos e os RowHeaderSelect modos permitem que os usuários

excluam linhas selecionando-as e pressionando a tecla DELETE. Os usuários só podem
excluir linhas quando a célula atual não está no modo de edição, a
AllowUserToDeleteRows propriedade é definida como , e a fonte de dados subjacente
dá suporte à true exclusão de linha controlada pelo usuário. Observe que essas
configurações não impedem a exclusão programática de linha.
Seleção programática
O modo de seleção atual restringe o comportamento de seleção programática, bem
como a seleção do usuário. Você pode alterar a seleção atual programaticamente
definindo a propriedade de todas as Selected células, linhas ou colunas presentes no
DataGridView controle. Você também pode selecionar todas as células no controle por
meio do SelectAll método, dependendo do modo de seleção. Para limpar a seleção, use
o ClearSelection método.
Se a MultiSelect propriedade estiver definida como true , você poderá adicionar

DataGridView elementos ou removê-los da seleção alterando a Selected propriedade
do elemento. Caso contrário, configurar a propriedade Selected como true para um
elemento remove automaticamente os outros elementos da seleção.
Observe que alterar o valor da CurrentCell propriedade não altera a seleção atual.
Você pode recuperar uma coleção das células, linhas ou colunas selecionadas no
momento por meio do SelectedCells, SelectedRowse SelectedColumns das propriedades
do DataGridView controle. O acesso a essas propriedades é ineficiente quando todas as
células no controle estão selecionadas. Para evitar uma penalidade de desempenho
nesse caso, use o AreAllCellsSelected método primeiro. Além disso, acessar essas
coleções para determinar o número de células, linhas ou colunas selecionadas pode ser
ineficiente. Em vez disso, você deve usar o GetCellCountmétodo, GetRowCountou
GetColumnCount o método, passando o Selected valor.
 Dica
Código de exemplo que demonstra o uso programático de células selecionadas

pode ser encontrado na visão geral da DataGridView classe.
Confira também
DataGridView
MultiSelect
SelectionMode
Forms
Como: Definir o modo de seleção do
Forms
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como configurar um DataGridView controle

para que clicar em qualquer lugar dentro de uma linha selecione automaticamente toda
a linha e, portanto, apenas uma linha por vez possa ser selecionada.
Exemplo
C#
this.dataGridView1.MultiSelect = false;
Confira também
DataGridView
MultiSelect
SelectionMode
Forms
Como: Obter as células, as linhas e as
colunas selecionadas no controle
Artigo • 21/06/2023
Você pode obter as células, linhas ou colunas selecionadas de um DataGridView

controle usando as propriedades correspondentes: SelectedCells, SelectedRowse
SelectedColumns. Nos procedimentos a seguir, você obterá as células selecionadas e
exibirá seus índices de linha e coluna em um MessageBox.
Para obter as células selecionadas em um controle

DataGridView
Use a propriedade SelectedCells.
７ Observação
Use o AreAllCellsSelected método para evitar mostrar um número

potencialmente grande de células.
C#
private void selectedCellsButton_Click(object sender, System.EventArgs

e)
{
Int32 selectedCellCount =
dataGridView1.GetCellCount(DataGridViewElementStates.Selected);
if (selectedCellCount > 0)
{
if (dataGridView1.AreAllCellsSelected(true))
{
MessageBox.Show("All cells are selected", "Selected
Cells");
}
else
{
System.Text.StringBuilder sb =
new System.Text.StringBuilder();
for (int i = 0;
i < selectedCellCount; i++)
{
sb.Append("Row: ");
sb.Append(dataGridView1.SelectedCells[i].RowIndex
.ToString());
sb.Append(", Column: ");
sb.Append(dataGridView1.SelectedCells[i].ColumnIndex
.ToString());
sb.Append(Environment.NewLine);
}
sb.Append("Total: " + selectedCellCount.ToString());

MessageBox.Show(sb.ToString(), "Selected Cells");
}
}
}
Para obter as linhas selecionadas em um controle

DataGridView
Use a propriedade SelectedRows. Para permitir que os usuários selecionem linhas,
defina a SelectionMode propriedade como FullRowSelect ou RowHeaderSelect.
C#
private void selectedRowsButton_Click(object sender, System.EventArgs

e)
{
Int32 selectedRowCount =
dataGridView1.Rows.GetRowCount(DataGridViewElementStates.Selected);
if (selectedRowCount > 0)
{
System.Text.StringBuilder sb = new System.Text.StringBuilder();
for (int i = 0; i < selectedRowCount; i++)

{
sb.Append("Row: ");
sb.Append(dataGridView1.SelectedRows[i].Index.ToString());
}
sb.Append("Total: " + selectedRowCount.ToString());

MessageBox.Show(sb.ToString(), "Selected Rows");
}
}
Para obter as colunas selecionadas em um controle

DataGridView
Use a propriedade SelectedColumns. Para permitir que os usuários selecionem
colunas, você deve definir a SelectionMode propriedade como FullColumnSelect
ou ColumnHeaderSelect.
C#
private void selectedColumnsButton_Click(object sender,

System.EventArgs e)
{
Int32 selectedColumnCount = dataGridView1.Columns
.GetColumnCount(DataGridViewElementStates.Selected);
if (selectedColumnCount > 0)
{
System.Text.StringBuilder sb = new System.Text.StringBuilder();
for (int i = 0; i < selectedColumnCount; i++)

{
sb.Append("Column: ");
sb.Append(dataGridView1.SelectedColumns[i].Index
.ToString());
}
sb.Append("Total: " + selectedColumnCount.ToString());

MessageBox.Show(sb.ToString(), "Selected Columns");
}
}
Button controles chamados selectedCellsButton , selectedRowsButton e

selectedColumnsButton , cada um com manipuladores para o Click evento anexado.
Referências aos Systemassemblies , System.Windows.Formse System.Text .
As coleções descritas neste tópico não são executadas com eficiência quando uma
grande quantidade de células, linhas ou colunas for selecionada. Para obter mais
informações sobre como usar essas coleções com grandes quantidades de dados,
consulte Práticas recomendadas para dimensionamento do controle DataGridView dos
Windows Forms.
Confira também
DataGridView
SelectionMode
AreAllCellsSelected
SelectedCells
SelectedRows
SelectedColumns
Forms
Como: Habilitar usuários para copiarem
várias células na Área de Transferência
usando o controle DataGridView do
Windows Forms
Artigo • 02/06/2023
Ao habilitar a cópia de célula, você torna os dados em seu DataGridView controle

facilmente acessíveis para outros aplicativos por meio do Clipboard. Os valores das
células selecionadas são convertidos em cadeias de caracteres e adicionados à área de
transferência como valores de texto delimitado por tabulação para colar em aplicativos
como Bloco de Notas e Excel, e como uma tabela formatada em HTML para colar em
aplicativos como Word.
É possível configurar a cópia de célula para copiar somente valores de célula, para
incluir texto de cabeçalho de linha e coluna nos dados da área de transferência ou para
incluir somente texto de cabeçalho quando os usuários selecionarem linhas ou colunas
inteiras.
Dependendo do modo de seleção, os usuários podem selecionar vários grupos de

células desconectados. Quando um usuário copia as células para a área de transferência,
linhas e colunas sem células selecionadas não são copiadas. Todas as outras linhas ou
colunas se tornam linhas e colunas na tabela de dados copiados para a área de
transferência. Células não selecionadas nessas linhas ou colunas são copiadas como
espaços reservados em branco para a área de transferência.
Habilitar cópia de célula

Definir a propriedade DataGridView.ClipboardCopyMode.
C#
this.DataGridView1.ClipboardCopyMode =
DataGridViewClipboardCopyMode.EnableWithoutHeaderText;
Exemplo
O exemplo de código completo a seguir demonstra como as células são copiadas para a
Área de Transferência. Este exemplo inclui um botão que copia as células selecionadas
para a Área de Transferência usando o DataGridView.GetClipboardContent método e
exibe o conteúdo da Área de Transferência em uma caixa de texto.
C#
using System;

{
private DataGridView DataGridView1 = new DataGridView();
private Button CopyPasteButton = new Button();
private TextBox TextBox1 = new TextBox();
{
}
public Form1()
{
this.DataGridView1.AllowUserToAddRows = false;
this.DataGridView1.Dock = DockStyle.Fill;
this.Controls.Add(this.DataGridView1);
this.CopyPasteButton.Text = "copy/paste selected cells";

this.CopyPasteButton.Dock = DockStyle.Top;
this.CopyPasteButton.Click += new
EventHandler(CopyPasteButton_Click);
this.Controls.Add(this.CopyPasteButton);
this.TextBox1.Multiline = true;
this.TextBox1.Height = 100;
this.TextBox1.Dock = DockStyle.Bottom;
this.Controls.Add(this.TextBox1);

this.Text = "DataGridView Clipboard demo";
}

{
// Initialize the DataGridView control.
this.DataGridView1.ColumnCount = 5;
this.DataGridView1.Rows.Add(new string[] { "A", "B", "C", "D", "E"
});
this.DataGridView1.Rows.Add(new string[] { "F", "G", "H", "I", "J"
});
this.DataGridView1.Rows.Add(new string[] { "K", "L", "M", "N", "O"
});
this.DataGridView1.Rows.Add(new string[] { "P", "Q", "R", "S", "T"
});
this.DataGridView1.Rows.Add(new string[] { "U", "V", "W", "X", "Y"
});
this.DataGridView1.AutoResizeColumns();
this.DataGridView1.ClipboardCopyMode =
DataGridViewClipboardCopyMode.EnableWithoutHeaderText;
}
private void CopyPasteButton_Click(object sender, System.EventArgs e)

{
if (this.DataGridView1
.GetCellCount(DataGridViewElementStates.Selected) > 0)
{
try
{
// Add the selection to the clipboard.
Clipboard.SetDataObject(
this.DataGridView1.GetClipboardContent());
// Replace the text box contents with the clipboard text.

this.TextBox1.Text = Clipboard.GetText();
}
catch (System.Runtime.InteropServices.ExternalException)
{
this.TextBox1.Text =
"The Clipboard could not be accessed. Please try
again.";
}
}
}
}
Este código requer:
Referências aos assemblies N:System e N:System.Windows.Forms.
Confira também
DataGridView
ClipboardCopyMode
GetClipboardContent
Forms
Programando com células, linhas e
colunas no controle DataGridView dos
Windows Forms
Artigo • 21/06/2023
Esta seção fornece tópicos que demonstram várias tarefas de programação envolvendo
objetos de célula, linha e coluna.
Nesta seção
Como adicionar ToolTips a células individuais em um controle DataGridView dos
Windows Forms
Descreve como manipular o CellFormatting evento para fornecer dicas de ferramenta
diferentes para células individuais.
Como: Realizar uma ação personalizada com base em alterações em uma célula do
Descreve como lidar com os CellValueChanged eventos e CellStateChanged .
Como: Manipular bandas no controle DataGridView do Windows Forms

Descreve como programar com objetos do tipo DataGridViewBand, que é o tipo base
para linhas e colunas.
Como: Manipular linhas no controle DataGridView do Windows Forms

Descreve como programar com objetos do tipo DataGridViewRow .
Como: Manipular colunas no controle DataGridView do Windows Forms

Descreve como programar com objetos do tipo DataGridViewColumn .
Como: Trabalhar com colunas de imagem no controle DataGridView do Windows Forms

Descreve como programar com a DataGridViewImageColumn classe .
Referência
DataGridView
DataGridViewCell
Fornece documentação de referência para a DataGridViewCell classe .
DataGridViewRow
Fornece documentação de referência para a DataGridViewRow classe .
DataGridViewColumn
Fornece documentação de referência para a DataGridViewColumn classe .
Windows Forms
Confira também
Como: Adicionar ToolTips a células
individuais em um controle
Artigo • 21/06/2023
Por padrão, as Dicas de Ferramenta são usadas para exibir os valores das DataGridView
células que são muito pequenas para mostrar todo o conteúdo. Contudo, é possível
substituir esse comportamento para definir valores de texto de dicas de ferramentas
para células individuais. Isso é útil para exibir aos usuários informações adicionais sobre
uma célula ou para fornecer aos usuários uma descrição alternativa do conteúdo da
célula. Por exemplo, se você tiver uma linha que exibe ícones de status, talvez seja
recomendável fornecer explicações de texto usando dicas de ferramenta.
Você também pode desabilitar a exibição de Dicas de Ferramenta no nível da célula

definindo a DataGridView.ShowCellToolTips propriedade como false .
Adicionar um ToolTip a uma célula

Definir a propriedade DataGridViewCell.ToolTipText.
C#
// Sets the ToolTip text for cells in the Rating column.

void dataGridView1_CellFormatting(object sender,
DataGridViewCellFormattingEventArgs e)
{
if ( (e.ColumnIndex == this.dataGridView1.Columns["Rating"].Index)
&& e.Value != null )
{
DataGridViewCell cell =
this.dataGridView1.Rows[e.RowIndex].Cells[e.ColumnIndex];
if (e.Value.Equals("*"))
{
cell.ToolTipText = "very bad";
}
else if (e.Value.Equals("**"))
{
cell.ToolTipText = "bad";
}
else if (e.Value.Equals("***"))
{
cell.ToolTipText = "good";
}
else if (e.Value.Equals("****"))
{
cell.ToolTipText = "very good";
}
}
}

chamada Rating para exibir valores de cadeia de caracteres de um a quatro
símbolos de asterisco ("*"). O CellFormatting evento do controle deve ser
associado ao método de manipulador de eventos mostrado no exemplo.
Ao associar o DataGridView controle a uma fonte de dados externa ou fornecer sua
própria fonte de dados implementando o modo virtual, você poderá encontrar
problemas de desempenho. Para evitar uma penalidade de desempenho ao trabalhar
com grandes quantidades de dados, manipule o CellToolTipTextNeeded evento em vez
de definir a ToolTipText propriedade de várias células. Quando você manipula esse
evento, obter o valor de uma propriedade de célula ToolTipText gera o evento e retorna
o valor da DataGridViewCellToolTipTextNeededEventArgs.ToolTipText propriedade
conforme especificado no manipulador de eventos.
Confira também
DataGridView
DataGridView.ShowCellToolTips
DataGridView.CellToolTipTextNeeded
DataGridViewCell
DataGridViewCell.ToolTipText
Programando com células, linhas e colunas no controle DataGridView dos
Windows Forms
Como: Realizar uma ação personalizada
com base em alterações em uma célula
do controle DataGridView do Windows
Forms
Artigo • 21/06/2023
O DataGridView controle tem vários eventos que você pode usar para detectar
alterações no estado das DataGridView células. Dois dos eventos mais usados são os
CellValueChanged eventos e CellStateChanged .
Para detectar alterações nos valores das células

DataGridView
Escreva um manipulador para o CellValueChanged evento.
C#
private void dataGridView1_CellValueChanged(object sender,

DataGridViewCellEventArgs e)
{
string msg = String.Format(
"Cell at row {0}, column {1} value changed",
e.RowIndex, e.ColumnIndex);
MessageBox.Show(msg, "Cell Value Changed");
}
Para detectar alterações nos estados das células

DataGridView
Escreva um manipulador para o CellStateChanged evento.
C#
private void dataGridView1_CellStateChanged(object sender,

DataGridViewCellStateChangedEventArgs e)
{
DataGridViewElementStates state = e.StateChanged;
string msg = String.Format("Row {0}, Column {1}, {2}",
e.Cell.RowIndex, e.Cell.ColumnIndex, e.StateChanged);
MessageBox.Show(msg, "Cell State Changed");
}
Um controle DataGridView chamado dataGridView1 . Para C#, os manipuladores de

eventos devem estar conectados aos eventos correspondentes.
Confira também
DataGridView
DataGridView.CellValueChanged
DataGridView.CellStateChanged
Windows Forms
Como: Manipular bandas no controle
Artigo • 02/06/2023
O exemplo de código a seguir mostra várias maneiras de manipular DataGridView linhas

e colunas usando propriedades DataGridViewBand da classe da qual as classes e
DataGridViewColumn as DataGridViewRow classes derivam.
Exemplo
C#
using System;
public class DataGridViewBandDemo : Form

{
#region "form setup"
public DataGridViewBandDemo()
{
AddButton(Button1, "Reset",
new EventHandler(Button1_Click));
AddButton(Button2, "Change Column 3 Header",
AddButton(Button3, "Change Meatloaf Recipe",
AddAdditionalButtons();
}
DataGridView dataGridView;
Button Button1 = new Button();
FlowLayoutPanel FlowLayoutPanel1 = new FlowLayoutPanel();

{
FlowLayoutPanel1.Location = new Point(454, 0);
AutoSize = true;
FlowLayoutPanel1.Name = "flowlayoutpanel";
Controls.Add(this.FlowLayoutPanel1);
}
#endregion
#region "setup DataGridView"


{
dataGridView = new System.Windows.Forms.DataGridView();
Controls.Add(dataGridView);
dataGridView.Size = new Size(300, 200);
// Create an unbound DataGridView by declaring a

// column count.
dataGridView.ColumnCount = 4;
AdjustDataGridViewSizing();
// Set the column header style.

columnHeaderStyle.Font =
new Font("Verdana", 10, FontStyle.Bold);
dataGridView.ColumnHeadersDefaultCellStyle =
columnHeaderStyle;
// Set the column header names.

dataGridView.Columns[0].Name = "Recipe";
dataGridView.Columns[1].Name = "Category";
dataGridView.Columns[2].Name = thirdColumnHeader;
dataGridView.Columns[3].Name = "Rating";
// Populate the rows.

string[] row1 = new string[]{"Meatloaf",
"Main Dish", boringMeatloaf,
boringMeatloafRanking};
string[] row2 = new string[]{"Key Lime Pie",
"Dessert", "lime juice, evaporated
milk", "****"};
string[] row3 = new string[]{"Orange-Salsa Pork Chops",
"Main Dish", "pork chops, salsa,
orange juice", "****"};
string[] row4 = new string[]{"Black Bean and Rice Salad",
"Salad", "black beans, brown rice",
"****"};
string[] row5 = new string[]{"Chocolate Cheesecake",
"Dessert", "cream cheese", "***"};
string[] row6 = new string[]{"Black Bean Dip", "Appetizer",
"black beans, sour cream", "***"};
object[] rows = new object[] { row1, row2, row3, row4, row5, row6 };
foreach (string[] rowArray in rows)

{
dataGridView.Rows.Add(rowArray);
}
PostRowCreation();
shortMode = false;
}
void AddButton(Button button, string buttonLabel,

{
FlowLayoutPanel1.Controls.Add(button);
button.TabIndex = FlowLayoutPanel1.Controls.Count;
}
// Reset columns to initial disorderly arrangement.

private void Button1_Click(object sender, System.EventArgs e)
{
Controls.Remove(dataGridView);
dataGridView.Dispose();
}
// Change the header in column three.

private void Button2_Click(object sender,
System.EventArgs e)
{
if (shortMode)
{ dataGridView.Columns[2].HeaderText = "S"; }
else
{ dataGridView.Columns[2].HeaderText = thirdColumnHeader; }
}
private static void Toggle(ref bool toggleThis)

{
}
// Change the meatloaf recipe.
System.EventArgs e)
{
if (boringRecipe)
{
}
else
{
"1 lb. lean ground beef, " +
"1/2 cup bread crumbs, 1/4 cup ketchup," +
"1/3 tsp onion powder, " +
"1 clove of garlic, 1/2 pack onion soup mix " +
" dash of your favorite BBQ Sauce";
}
}

{
dataGridView.Rows[0].Cells[2].Value = recipe;
dataGridView.Rows[0].Cells[3].Value = rating;
}
#endregion
#region "demonstration code"

private void AddAdditionalButtons()
{
AddButton(Button4, "Freeze First Row",
AddButton(Button5, "Freeze Second Column",
AddButton(Button6, "Hide Salad Row",
AddButton(Button7, "Disable First Column Resizing",
AddButton(Button8, "Make ReadOnly",
AddButton(Button9, "Style Using Tag",
}
private void AdjustDataGridViewSizing()

{
dataGridView.AutoSizeRowsMode =
DataGridViewAutoSizeRowsMode.AllCells;
dataGridView.ColumnHeadersHeightSizeMode =
}
// Freeze the first row.

{
FreezeBand(dataGridView.Rows[0]);
}

{
FreezeBand(dataGridView.Columns[1]);
}
private static void FreezeBand(DataGridViewBand band)

{
band.Frozen = true;
DataGridViewCellStyle style = new DataGridViewCellStyle();
style.BackColor = Color.WhiteSmoke;
band.DefaultCellStyle = style;
}
// Hide a band of cells.

{
DataGridViewBand band = dataGridView.Rows[3];

band.Visible = false;
}
// Turn off user's ability to resize a column.

private void Button7_Click(object sender, EventArgs e)
{
DataGridViewBand band = dataGridView.Columns[0];

band.Resizable = DataGridViewTriState.False;
}
// Make the entire DataGridView read only.

{
foreach (DataGridViewBand band in dataGridView.Columns)
{
band.ReadOnly = true;
}
}
private void PostRowCreation()

{
SetBandColor(dataGridView.Columns[0], Color.CadetBlue);
SetBandColor(dataGridView.Rows[1], Color.Coral);
SetBandColor(dataGridView.Columns[2], Color.DodgerBlue);
}
private static void SetBandColor(DataGridViewBand band, Color color)

{
band.Tag = color;
}
// Color the bands by the value stored in their tag.
{
foreach (DataGridViewBand band in dataGridView.Columns)

{
if (band.Tag != null)
{
band.DefaultCellStyle.BackColor = (Color)band.Tag;
}
}
foreach (DataGridViewBand band in dataGridView.Rows)

{
if (band.Tag != null)
{
band.DefaultCellStyle.BackColor = (Color)band.Tag;
}
}
}
#endregion
{
Application.Run(new DataGridViewBandDemo());
}
}
Confira também
DataGridView
DataGridViewBand
DataGridViewRow
DataGridViewColumn
Windows Forms
Como: Manipular linhas no controle
Artigo • 02/06/2023
O exemplo de código a seguir mostra as várias maneiras de manipular DataGridView

linhas usando propriedades da DataGridViewRow classe.
Exemplo
C#
using System;
public class DataGridViewRowDemo : Form

{
#region "form setup"
public DataGridViewRowDemo()
{
}
private DataGridView dataGridView;

private FlowLayoutPanel FlowLayoutPanel1 = new FlowLayoutPanel();

{
AutoSize = true;
}
#endregion
#region "setup DataGridView"


{

// column count.
dataGridView.ColumnHeadersVisible = true;

columnHeaderStyle;


"Dessert", "lime juice,
evaporated milk", "****"};
"Salad", "black beans, brown
rice", "****"};
"Dessert", "cream cheese",
"***"};
"black beans, sour cream",
"***"};

{
}
shortMode = false;
}

{
}
// Reset columns to initial disorderly arrangement.

{
}
// Change column 3 header.

System.EventArgs e)
{
if (shortMode)
else
}

{
}
// Change meatloaf recipe.
System.EventArgs e)
{
if (boringRecipe)
{
}
else
{
}
}

{
}
#endregion

{
AddButton(Button4, "Set Row Two Minimum Height",
AddButton(Button5, "Set Row One Height",
AddButton(Button6, "Label Rows",
AddButton(Button7, "Turn on Extra Edge",
AddButton(Button8, "Give Cheesecake an Excellent Rating",
}

{
dataGridView.Columns[ratingColumn].Width = 50;
}
// Set minimum height.

{
int secondRow = 1;
DataGridViewRow row = dataGridView.Rows[secondRow];
row.MinimumHeight = 40;
}
// Set height.
{
DataGridViewRow row = dataGridView.Rows[0];

row.Height = 15;
}
// Set row labels.

{
int rowNumber = 1;
foreach (DataGridViewRow row in dataGridView.Rows)
{
if (row.IsNewRow) continue;
row.HeaderCell.Value = "Row " + rowNumber;
rowNumber = rowNumber + 1;
}
dataGridView.AutoResizeRowHeadersWidth(
DataGridViewRowHeadersWidthSizeMode.AutoSizeToAllHeaders);
}
// Set a thick horizontal edge.

System.EventArgs e)
{
int secondRow = 1;
DataGridViewRow row = dataGridView.Rows[secondRow];
row.DividerHeight = 10;
}
// Give cheescake excellent rating.

System.EventArgs e)
{
UpdateStars(dataGridView.Rows[4], "******************");
}
int ratingColumn = 3;
private void UpdateStars(DataGridViewRow row, string stars)

{
row.Cells[ratingColumn].Value = stars;
// Resize the column width to account for the new value.

row.DataGridView.AutoResizeColumn(ratingColumn,
DataGridViewAutoSizeColumnMode.DisplayedCells);
}
#endregion
{
Application.Run(new DataGridViewRowDemo());
}
}
Confira também
DataGridView
DataGridViewBand
DataGridViewRow
DataGridViewColumn
Windows Forms
Como: Manipular colunas no controle
Artigo • 02/06/2023
O exemplo de código a seguir mostra as várias maneiras de manipular DataGridView

colunas usando propriedades da DataGridViewColumn classe.
Exemplo
C#
using System;
public class DataGridViewColumnDemo : Form

{
#region "set up form"
public DataGridViewColumnDemo()
{
}
FlowLayoutPanel FlowLayoutPanel1 = new FlowLayoutPanel();

{
AutoSize = true;
}
#endregion
#region "set up DataGridView"


{

// column count.

columnHeaderStyle;

PostColumnCreation();

"Dessert", "lime juice, evaporated
milk", "****"};
"Salad", "black beans, brown rice",
"****"};
"Dessert", "cream cheese", "***"};
"black beans, sour cream", "***"};

{
}
shortMode = false;
}

{
}
private void ResetToDisorder(object sender, System.EventArgs e)

{
}
private void ChangeColumn3Header(object sender,

System.EventArgs e)
{
if (shortMode)
else
}

{
}
private void ChangeMeatloafRecipe(object sender,

System.EventArgs e)
{
if (boringRecipe)
{
}
else
{
}
}

{
}
#endregion

private void PostColumnCreation()
{
AddContextLabel();
AddCriteriaLabel();
CustomizeCellsInThirdColumn();
AddContextMenu();
SetDefaultCellInFirstColumn();
ToolTips();
dataGridView.CellMouseEnter +=
dataGridView_CellMouseEnter;
dataGridView.AutoSizeColumnModeChanged +=
dataGridView_AutoSizeColumnModeChanged;
}
private string criteriaLabel = "Column 3 sizing criteria: ";

private void AddCriteriaLabel()
{
AddLabelToPanelIfNotAlreadyThere(criteriaLabel,
criteriaLabel +
dataGridView.Columns[2].AutoSizeMode.ToString() +
".");
}
private void AddContextLabel()

{
string labelName = "label";
AddLabelToPanelIfNotAlreadyThere(labelName,
"Use shortcut menu to change cell color.");
}
private void AddLabelToPanelIfNotAlreadyThere(
string labelName, string labelText)
{
Label label;
if (FlowLayoutPanel1.Controls[labelName] == null)
{
label = new Label();
label.AutoSize = true;
label.Name = labelName;
label.BackColor = Color.Bisque;
FlowLayoutPanel1.Controls.Add(label);
}
else
{
label = (Label)FlowLayoutPanel1.Controls[labelName];
}
label.Text = labelText;
}
private void CustomizeCellsInThirdColumn()

{
int thirdColumn = 2;
DataGridViewColumn column =
dataGridView.Columns[thirdColumn];
DataGridViewCell cell = new DataGridViewTextBoxCell();
cell.Style.BackColor = Color.Wheat;
column.CellTemplate = cell;
}
ToolStripMenuItem toolStripItem1 = new ToolStripMenuItem();
private void AddContextMenu()

{
toolStripItem1.Text = "Redden";
toolStripItem1.Click += new EventHandler(toolStripItem1_Click);
ContextMenuStrip strip = new ContextMenuStrip();
foreach (DataGridViewColumn column in dataGridView.Columns)
{
column.ContextMenuStrip = strip;
column.ContextMenuStrip.Items.Add(toolStripItem1);
}
}
private DataGridViewCellEventArgs mouseLocation;
// Change the cell's color.

private void toolStripItem1_Click(object sender, EventArgs args)
{
dataGridView.Rows[mouseLocation.RowIndex]
.Cells[mouseLocation.ColumnIndex].Style.BackColor
= Color.Red;
}
// Deal with hovering over a cell.
private void dataGridView_CellMouseEnter(object sender,
DataGridViewCellEventArgs location)
{
mouseLocation = location;
}
private void SetDefaultCellInFirstColumn()

{
DataGridViewColumn firstColumn = dataGridView.Columns[0];
DataGridViewCellStyle cellStyle =
cellStyle.BackColor = Color.Thistle;
firstColumn.DefaultCellStyle = cellStyle;
}
private void ToolTips()

{
DataGridViewColumn firstColumn = dataGridView.Columns[0];
DataGridViewColumn thirdColumn = dataGridView.Columns[2];
firstColumn.ToolTipText =
"This column uses a default cell.";
thirdColumn.ToolTipText =
"This column uses a template cell." +
" Style changes to one cell apply to all cells.";
}

{
AddButton(Button4, "Set Minimum Width of Column Two",
AddButton(Button5, "Set Width of Column One",
AddButton(Button6, "Autosize Third Column",
AddButton(Button7, "Add Thick Vertical Edge",
AddButton(Button8, "Style and Number Columns",
AddButton(Button9, "Change Column Header Text",
AddButton(Button10, "Swap First and Last Columns",
}

{
}
//Set the minimum width.

System.EventArgs e)
{
DataGridViewColumn column = dataGridView.Columns[1];
column.MinimumWidth = 40;
}
// Set the width.

{
column.Width = 60;
}
// AutoSize the third column.

System.EventArgs e)
{
column.AutoSizeMode = DataGridViewAutoSizeColumnMode.DisplayedCells;
}
// Set the vertical edge.

System.EventArgs e)
{
int thirdColumn = 2;
DataGridViewColumn column =
dataGridView.Columns[thirdColumn];
column.DividerWidth = 10;
}
// Style and number columns.

EventArgs args)
{
DataGridViewCellStyle style = new DataGridViewCellStyle();
style.Alignment =
DataGridViewContentAlignment.MiddleCenter;
style.ForeColor = Color.IndianRed;
style.BackColor = Color.Ivory;

{
column.HeaderCell.Value = column.Index.ToString();
column.HeaderCell.Style = style;
}
}
// Change the text in the column header.

EventArgs args)
{
{
column.HeaderText = String.Concat("Column ",
column.Index.ToString());
}
}
// Swap the last column with the first.

private void Button10_Click(object sender, EventArgs args)
{
DataGridViewColumnCollection columnCollection =
dataGridView.Columns;
DataGridViewColumn firstVisibleColumn =
columnCollection.GetFirstColumn(DataGridViewElementStates.Visible);
DataGridViewColumn lastVisibleColumn =
columnCollection.GetLastColumn(
DataGridViewElementStates.Visible,
DataGridViewElementStates.None);
int firstColumn_sIndex = firstVisibleColumn.DisplayIndex;

firstVisibleColumn.DisplayIndex = lastVisibleColumn.DisplayIndex;
lastVisibleColumn.DisplayIndex = firstColumn_sIndex;
}
// Updated the criteria label.

private void dataGridView_AutoSizeColumnModeChanged(object sender,
DataGridViewAutoSizeColumnModeEventArgs args)
{
args.Column.DataGridView.Parent.
Controls["flowlayoutpanel"].Controls[criteriaLabel].
Text = criteriaLabel
+ args.Column.AutoSizeMode.ToString();
}
#endregion
{
Application.Run(new DataGridViewColumnDemo());
}
}
Confira também
DataGridView
DataGridViewBand
DataGridViewRow
DataGridViewColumn
Windows Forms
Como: Trabalhar com colunas de
imagem no controle DataGridView do
Windows Forms
Artigo • 02/06/2023
O exemplo de código a seguir mostra como usar as DataGridView colunas de imagem

em uma interface do usuário (interface do usuário) interativa. O exemplo também
demonstra possibilidades de dimensionamento e layout de imagem com o
DataGridViewImageColumn.
Exemplo
C#
using System.IO;
using System;
public class TicTacToe : System.Windows.Forms.Form

{
public TicTacToe()
{
blank = new Bitmap(new MemoryStream(blankImage));
x = new Bitmap(new MemoryStream(xImage));
o = new Bitmap(new MemoryStream(oImage));
SetupButtons();
}

private Label turn = new Label();
private FlowLayoutPanel Panel1 = new FlowLayoutPanel();
#region "bitmaps"
private byte[] oImage = new byte[] {
0x42, 0x4D, 0xC6, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x76,
0x0, 0x0, 0x0, 0x28, 0x0, 0x0, 0x0, 0xB, 0x0, 0x0, 0x0, 0xA,
0x0, 0x0, 0x0, 0x1, 0x0, 0x4, 0x0, 0x0, 0x0, 0x0, 0x0, 0x50,
0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x10,
0x0, 0x0, 0x0, 0x10, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0,
0x0, 0x80, 0x0, 0x0, 0x80, 0x0, 0x0, 0x0, 0x80, 0x80, 0x0,
0x80, 0x0, 0x0, 0x0, 0x80, 0x0, 0x80, 0x0, 0x80, 0x80, 0x0,
0x0, 0xC0, 0xC0, 0xC0, 0x0, 0x80, 0x80, 0x80, 0x0, 0x0, 0x0,
0xFF, 0x0, 0x0, 0xFF, 0x0, 0x0, 0x0, 0xFF, 0xFF, 0x0, 0xFF,
0x0, 0x0, 0x0, 0xFF, 0x0, 0xFF, 0x0, 0xFF, 0xFF, 0x0, 0x0,
0xFF, 0xFF, 0xFF, 0x0, 0xFF, 0xFF, 0x0, 0xF, 0xFF, 0xF0,
0x0, 0x0, 0xFF, 0x0, 0xFF, 0xF0, 0xF, 0xF0, 0x0, 0x0, 0xF0,
0xFF, 0xFF, 0xFF, 0xF0, 0xF0, 0x0, 0x0, 0xF0, 0xFF, 0xFF,
0xFF, 0xF0, 0xF0, 0x0, 0x0, 0xF, 0xFF, 0xFF, 0xFF, 0xFF,
0x0, 0x0, 0x0, 0xF, 0xFF, 0xFF, 0xFF, 0xFF, 0x0, 0x0, 0x0,
0xF0, 0xFF, 0xFF, 0xFF, 0xF0, 0xF0, 0x0, 0x0, 0xF0, 0xFF,
0xFF, 0xFF, 0xF0, 0xF0, 0x0, 0x0, 0xFF, 0x0, 0xFF, 0xF0,
0xF, 0xF0, 0x0, 0x0, 0xFF, 0xFF, 0x0, 0xF, 0xFF, 0xF0, 0x0,
0x0};
private byte[] xImage = new byte[]{

0x42, 0x4D, 0xC6, 0x0, 0x0, 0x0, 0x0,
0x0, 0x0, 0x0, 0x76, 0x0, 0x0, 0x0, 0x28, 0x0, 0x0, 0x0,
0xB, 0x0, 0x0, 0x0, 0xA, 0x0, 0x0, 0x0, 0x1, 0x0, 0x4, 0x0,
0x0, 0x0, 0x0, 0x0, 0x50, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0,
0x0, 0x0, 0x0, 0x0, 0x10, 0x0, 0x0, 0x0, 0x10, 0x0, 0x0,
0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x80, 0x0, 0x0, 0x80,
0x0, 0x0, 0x0, 0x80, 0x80, 0x0, 0x80, 0x0, 0x0, 0x0, 0x80,
0x0, 0x80, 0x0, 0x80, 0x80, 0x0, 0x0, 0xC0, 0xC0, 0xC0, 0x0,
0x80, 0x80, 0x80, 0x0, 0x0, 0x0, 0xFF, 0x0, 0x0, 0xFF, 0x0,
0x0, 0x0, 0xFF, 0xFF, 0x0, 0xFF, 0x0, 0x0, 0x0, 0xFF, 0x0,
0xFF, 0x0, 0xFF, 0xFF, 0x0, 0x0, 0xFF, 0xFF, 0xFF, 0x0,
0xF0, 0xFF, 0xFF, 0xFF, 0xF0, 0xF0, 0x0, 0x0, 0xFF, 0xF,
0xFF, 0xFF, 0xF, 0xF0, 0x0, 0x0, 0xFF, 0xF0, 0xFF, 0xF0,
0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xFF, 0xF, 0xF, 0xFF, 0xF0, 0x0,
0x0, 0xFF, 0xFF, 0xF, 0xF, 0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xFF,
0xF, 0xF, 0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xF0, 0xFF, 0xF0,
0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xF, 0xFF, 0xFF, 0xF, 0xF0, 0x0,
0x0, 0xF0, 0xFF, 0xFF, 0xFF, 0xF0, 0xF0, 0x0, 0x0, 0xFF,
0xFF, 0xFF, 0xFF, 0xFF, 0xF0, 0x0, 0x0};
private byte[] blankImage = new byte[] {

0x42, 0x4D, 0xC6, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x76,
0x0, 0x0, 0x0, 0x28, 0x0, 0x0, 0x0, 0xB, 0x0, 0x0, 0x0, 0xA,
0x0, 0x0, 0x0, 0x1, 0x0, 0x4, 0x0, 0x0, 0x0, 0x0, 0x0, 0x50,
0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x10,
0x0, 0x0, 0x0, 0x10, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0,
0x0, 0x80, 0x0, 0x0, 0x80, 0x0, 0x0, 0x0, 0x80, 0x80, 0x0,
0x80, 0x0, 0x0, 0x0, 0x80, 0x0, 0x80, 0x0, 0x80, 0x80, 0x0,
0x0, 0xC0, 0xC0, 0xC0, 0x0, 0x80, 0x80, 0x80, 0x0, 0x0, 0x0,
0xFF, 0x0, 0x0, 0xFF, 0x0, 0x0, 0x0, 0xFF, 0xFF, 0x0, 0xFF,
0x0, 0x0, 0x0, 0xFF, 0x0, 0xFF, 0x0, 0xFF, 0xFF, 0x0, 0x0,
0xFF, 0xFF, 0xFF, 0x0, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xF0,
0x0, 0x0, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xF0, 0x0, 0x0,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xFF,
0xFF, 0xFF, 0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xFF, 0xFF, 0xFF,
0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xF0,
0x0, 0x0, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xF0, 0x0, 0x0,
0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xFF,
0xFF, 0xFF, 0xFF, 0xF0, 0x0, 0x0, 0xFF, 0xFF, 0xFF, 0xFF,
0xFF, 0xF0, 0x0, 0x0};
#endregion
private Bitmap blank;

private Bitmap x;
private Bitmap o;
private string xString = "X's turn";
private string oString = "O's turn";
private string gameOverString = "Game Over";
private int bitmapPadding = 6;
private void InitializeDataGridView(object sender,

EventArgs e)
{
this.Panel1.SuspendLayout();
ConfigureForm();
SizeGrid();
CreateColumns();
CreateRows();
this.Panel1.ResumeLayout(false);
}
private void ConfigureForm()

{
AutoSize = true;
turn.Size = new System.Drawing.Size(75, 34);
turn.TextAlign = ContentAlignment.MiddleLeft;
turn.Text = xString;
Panel1.Location = new System.Drawing.Point(0, 8);

Panel1.Size = new System.Drawing.Size(120, 196);
Panel1.FlowDirection = FlowDirection.TopDown;

Controls.Add(this.Panel1);
Text = "TicTacToe";
dataGridView1 = new System.Windows.Forms.DataGridView();

dataGridView1.Location = new Point(120, 0);
dataGridView1.CellClick += new
DataGridViewCellEventHandler(dataGridView1_CellClick);
dataGridView1.CellMouseEnter += new
DataGridViewCellEventHandler(dataGridView1_CellMouseEnter);
dataGridView1.CellMouseLeave += new
DataGridViewCellEventHandler(dataGridView1_CellMouseLeave);
}
private void SetupButtons()
{
Button1.AutoSize = true;
SetupButton(Button1, "Restart", new EventHandler(Reset));
Panel1.Controls.Add(turn);
SetupButton(Button2, "Increase Cell Size", new
EventHandler(MakeCellsLarger));
SetupButton(Button3, "Stretch Images", new EventHandler(Stretch));
SetupButton(Button4, "Zoom Images", new EventHandler(ZoomToImage));
SetupButton(Button5, "Normal Images", new
EventHandler(NormalImage));
}
private void SetupButton(Button button, string buttonLabel, EventHandler

handler)
{
Panel1.Controls.Add(button);
}
private void CreateColumns()

{
DataGridViewImageColumn imageColumn;
int columnCount = 0;
do
{
Bitmap unMarked = blank;
imageColumn = new DataGridViewImageColumn();
//Add twice the padding for the left and

//right sides of the cell.
imageColumn.Width = x.Width + 2 * bitmapPadding + 1;
imageColumn.Image = unMarked;
dataGridView1.Columns.Add(imageColumn);
columnCount = columnCount + 1;
}
while (columnCount < 3);
}
private void CreateRows()

{
dataGridView1.Rows.Add();
}
private void SizeGrid()

{
dataGridView1.ColumnHeadersVisible = false;
dataGridView1.RowHeadersVisible = false;
dataGridView1.AllowUserToResizeColumns = false;;
dataGridView1.AllowUserToResizeRows = false;
dataGridView1.BorderStyle = BorderStyle.None;
//Add twice the padding for the top of the cell

//and the bottom.
dataGridView1.RowTemplate.Height = x.Height +
2 * bitmapPadding + 1;
}
private void Reset(object sender, System.EventArgs e)

{
}
private void dataGridView1_CellClick(object sender,

{
if (turn.Text.Equals(gameOverString)) { return; }
DataGridViewImageCell cell = (DataGridViewImageCell)

dataGridView1.Rows[e.RowIndex].Cells[e.ColumnIndex];
if (cell.Value == blank)
{
if (IsOsTurn())
{
cell.Value = o;
}
else
{
cell.Value = x;
}
ToggleTurn();
}
if (IsAWin())
{
turn.Text = gameOverString;
}
}
private void dataGridView1_CellMouseEnter(object sender,

{
Bitmap markingUnderMouse = (Bitmap)dataGridView1.
Rows[e.RowIndex].
Cells[e.ColumnIndex].Value;
if (markingUnderMouse == blank)
{
dataGridView1.Cursor = Cursors.Default;
}
else if (markingUnderMouse == o || markingUnderMouse == x)
{
dataGridView1.Cursor = Cursors.No;
ToolTip(e, true);
}
}
private void ToolTip(DataGridViewCellEventArgs e, bool showTip)

{
DataGridViewImageCell cell = (DataGridViewImageCell)
dataGridView1
.Rows[e.RowIndex].Cells[e.ColumnIndex];
DataGridViewImageColumn imageColumn =
(DataGridViewImageColumn)
dataGridView1.Columns[cell.ColumnIndex];
if (showTip)
{
cell.ToolTipText = imageColumn.Description;
}
else { cell.ToolTipText = String.Empty; }
}
private void dataGridView1_CellMouseLeave(object sender,

{
ToolTip(e, false);
dataGridView1.Cursor = Cursors.Default;
}
private void Stretch(object sender, EventArgs e)

{
foreach (DataGridViewImageColumn column in
dataGridView1.Columns)
{
column.ImageLayout = DataGridViewImageCellLayout.Stretch;
column.Description = "Stretched";
}
}
private void ZoomToImage(object sender, EventArgs e)

{

{
column.ImageLayout = DataGridViewImageCellLayout.Zoom;
column.Description = "Zoomed";
}
}
private void NormalImage(object sender, EventArgs e)

{

{
column.ImageLayout = DataGridViewImageCellLayout.Normal;
column.Description = "Normal";
}
}
private void MakeCellsLarger(object sender, EventArgs e)

{
{
column.Width = column.Width * 2;
}
{
row.Height = (int)(row.Height * 1.5);
}
}
private bool IsAWin()

{
if (ARowIsSame() || AColumnIsSame() || ADiagonalIsSame())
return true;
else return false;
}
private bool ARowIsSame()

{
Bitmap marking = null;

{
marking = (Bitmap)row.Cells[0].Value;
if (marking != blank)
{
if (marking == row.Cells[1].Value &&
marking == row.Cells[2].Value) return true;
}
}
return false;
}
private bool AColumnIsSame()

{
int columnIndex = 0;
Bitmap marking;
do
{
marking = (Bitmap)
dataGridView1.Rows[0].Cells[columnIndex].Value;
if (marking != blank)
{
if (marking == (Bitmap)dataGridView1.Rows[1]
.Cells[columnIndex].Value
&& marking == (Bitmap)dataGridView1.Rows[2].
Cells[columnIndex].Value) return true;
}
columnIndex = columnIndex + 1;
}
while (columnIndex < dataGridView1.Columns.GetColumnCount(
DataGridViewElementStates.Visible));
return false;
}
private bool ADiagonalIsSame()

{
if (LeftToRightDiagonalIsSame()) { return true; }
if (RightToLeftDiagonalIsSame()) { return true; }
return false;
}
private bool LeftToRightDiagonalIsSame()

{
return IsDiagonalSame(0, 2);
}
private bool RightToLeftDiagonalIsSame()

{
return IsDiagonalSame(2, 0);
}
private bool IsDiagonalSame(int startingColumn, int lastColumn)

{
Bitmap marking = (Bitmap)dataGridView1.Rows[0]
.Cells[startingColumn].Value;
if (marking == blank) return false;

if (marking == dataGridView1.Rows[1].Cells[1]
.Value && marking == dataGridView1.Rows[2]
.Cells[lastColumn].Value) return true;
return false;
}
private void ToggleTurn()

{
if (turn.Text.Equals(xString)) { turn.Text = oString; }
else { turn.Text = xString; }
}
private bool IsOsTurn()

{
if (turn.Text.Equals(oString)) return true;
return false;
}
[STAThread]
{
Application.Run(new TicTacToe());
}
}
Confira também
DataGridView
Windows Forms
Personalizando o controle DataGridView
dos Windows Forms
Artigo • 02/06/2023
O controle DataGridView fornece várias propriedades que podem ser usadas para
ajustar a aparência e o comportamento básico (visual) das células, linhas e colunas. Se
você tiver necessidades especiais que vão além dos recursos da DataGridViewCellStyle
classe, no entanto, você também pode implementar o desenho do proprietário para o
controle ou estender seus recursos criando células, colunas e linhas personalizadas.
Para pintar linhas e células por conta própria, você pode manipular vários eventos de
pintura DataGridView . Para modificar a funcionalidade existente ou fornecer novas
funcionalidades, crie seus próprios tipos derivados dos tipos DataGridViewCell ,
DataGridViewColumn e DataGridViewRow existentes. Você também pode fornecer novos
recursos de edição criando tipos derivados que exibem um controle de sua escolha
quando uma célula está em modo de edição.
Nesta seção
Forms
Descreve como manipular o CellPainting evento para pintar as células manualmente.
Como: Personalizar a aparência de linhas no controle DataGridView do Windows Forms

Descreve como lidar com o e RowPostPaint os RowPrePaint eventos para pintar linhas
com um plano de fundo personalizado, gradiente e conteúdo que abrange várias
colunas.
Como: Personalizar células e colunas no controle DataGridView do Windows Forms

estendendo o comportamento e a aparência
Descreve como criar tipos personalizados derivados de DataGridViewCell e
DataGridViewColumn para realçar células ao posicionar o ponteiro do mouse sobre elas.
Como: Desabilitar botões em uma coluna de botão no controle DataGridView do

Windows Forms
Descreve como criar tipos personalizados derivados DataGridViewButtonCell e
DataGridViewButtonColumn para exibir botões desabilitados em uma coluna de botão.
Como: Hospedar controles em células DataGridView do Windows Forms

Descreve como implementar a IDataGridViewEditingControl interface e criar tipos
personalizados derivados DataGridViewCell e DataGridViewColumn para exibir um
DateTimePicker controle quando uma célula está no modo de edição.
Referência
DataGridView
DataGridViewCell
Fornece a documentação de referência para a DataGridViewCell classe.
DataGridViewRow
Fornece a documentação de referência para a DataGridViewRow classe.
DataGridViewColumn
Fornece a documentação de referência para a DataGridViewColumn classe.
Fornece a documentação de referência para a IDataGridViewEditingControl interface.
Confira também
Como personalizar a aparência de
células no controle DataGridView dos
Windows Forms
Artigo • 21/06/2023
Você pode personalizar a aparência de qualquer célula manipulando o DataGridView

evento do CellPainting controle. Você pode extrair os DataGridView controles da
GraphicsGraphics propriedade do DataGridViewCellPaintingEventArgs. Com esse
Graphics, você pode afetar a aparência de todo DataGridView o controle, mas
geralmente desejará afetar apenas a aparência da célula que está sendo pintada no
momento. A ClipBounds propriedade do DataGridViewCellPaintingEventArgs permite
que você restrinja suas operações de pintura à célula que está sendo pintada no
momento.
No exemplo de código a seguir, você pintará todas as células em uma ContactName

coluna usando o DataGridView esquema de cores do controle. O conteúdo de texto de
cada célula é pintado em Crimsone um retângulo de conjunto é desenhado na mesma
cor que a DataGridView propriedade do GridColor controle.
Exemplo
C#
private void dataGridView1_CellPainting(object sender,

System.Windows.Forms.DataGridViewCellPaintingEventArgs e)
{
if (this.dataGridView1.Columns["ContactName"].Index ==
e.ColumnIndex && e.RowIndex >= 0)
{
Rectangle newRect = new Rectangle(e.CellBounds.X + 1,
e.CellBounds.Y + 1, e.CellBounds.Width - 4,
e.CellBounds.Height - 4);
using (
Brush gridBrush = new SolidBrush(this.dataGridView1.GridColor),
backColorBrush = new SolidBrush(e.CellStyle.BackColor))
{
using (Pen gridLinePen = new Pen(gridBrush))
{
// Erase the cell.
e.Graphics.FillRectangle(backColorBrush, e.CellBounds);
// Draw the grid lines (only the right and bottom lines;
// DataGridView takes care of the others).
e.Graphics.DrawLine(gridLinePen, e.CellBounds.Left,
e.CellBounds.Bottom - 1, e.CellBounds.Right - 1,
e.CellBounds.Bottom - 1);
e.Graphics.DrawLine(gridLinePen, e.CellBounds.Right - 1,
e.CellBounds.Top, e.CellBounds.Right - 1,
e.CellBounds.Bottom);
// Draw the inset highlight box.

e.Graphics.DrawRectangle(Pens.Blue, newRect);
// Draw the text content of the cell, ignoring alignment.

{
e.Graphics.DrawString((String)e.Value, e.CellStyle.Font,
Brushes.Crimson, e.CellBounds.X + 2,
e.CellBounds.Y + 2, StringFormat.GenericDefault);
}
e.Handled = true;
}
}
}
}
Um DataGridView controle chamado dataGridView1 com uma ContactName coluna

como a da tabela Customers no banco de dados de exemplo Northwind.
Referências aos assemblies System, System.Windows.Forms e System.Drawing.
Confira também
DataGridView
CellPainting
Como: Personalizar a aparência de
linhas no controle DataGridView do
Windows Forms
Artigo • 21/06/2023
Você pode controlar a aparência das DataGridView linhas manipulando um ou ambos os

DataGridView.RowPrePaint eventos e DataGridView.RowPostPaint . Esses eventos são
projetados para que você possa pintar apenas o que deseja, deixando o DataGridView
controle pintar o resto. Por exemplo, se você quiser pintar uma tela de fundo
personalizada, poderá manipular o DataGridView.RowPrePaint evento e permitir que as
células individuais pintem seu próprio conteúdo em primeiro plano. Como alternativa,
você pode permitir que as células se pintem e adicionem conteúdo de primeiro plano
personalizado em um manipulador para o DataGridView.RowPostPaint evento. Você
também pode desabilitar a pintura de células e pintar tudo por conta própria em um
DataGridView.RowPrePaint manipulador de eventos.
O exemplo de código a seguir implementa manipuladores para ambos os eventos a fim

de fornecer uma tela de fundo de seleção do gradiente e algum conteúdo de primeiro
plano personalizado que abrange várias colunas.
Exemplo
C#
using System;
class DataGridViewRowPainting : Form

{
private Int32 oldRowIndex = 0;
private const Int32 CUSTOM_CONTENT_HEIGHT = 30;
{
Application.Run(new DataGridViewRowPainting());
}
public DataGridViewRowPainting()
{
this.Load += new EventHandler(DataGridViewRowPainting_Load);
this.Text = "DataGridView row painting demo";
}
void DataGridViewRowPainting_Load(object sender, EventArgs e)

{
// Set a cell padding to provide space for the top of the focus
// rectangle and for the content that spans multiple columns.
Padding newPadding = new Padding(0, 1, 0, CUSTOM_CONTENT_HEIGHT);
this.dataGridView1.RowTemplate.DefaultCellStyle.Padding =
newPadding;
// Set the selection background color to transparent so

// the cell won't paint over the custom selection background.
this.dataGridView1.RowTemplate.DefaultCellStyle.SelectionBackColor =
Color.Transparent;
// Set the row height to accommodate the content that

// spans multiple columns.
this.dataGridView1.RowTemplate.Height += CUSTOM_CONTENT_HEIGHT;
// Initialize other DataGridView properties.

this.dataGridView1.AllowUserToAddRows = false;
this.dataGridView1.EditMode =
DataGridViewEditMode.EditOnKeystrokeOrF2;

this.dataGridView1.ColumnCount = 4;
this.dataGridView1.Columns[0].Name = "Recipe";
this.dataGridView1.Columns[0].SortMode =
DataGridViewColumnSortMode.NotSortable;
this.dataGridView1.Columns[1].Name = "Category";
this.dataGridView1.Columns[2].Name = "Main Ingredients";
this.dataGridView1.Columns[3].Name = "Rating";
// Hide the column that contains the content that spans

// multiple columns.
this.dataGridView1.Columns[2].Visible = false;
// Populate the rows of the DataGridView.

string[] row1 = new string[]{"Meatloaf", "Main Dish",
"1 lb. lean ground beef, 1/2 cup bread crumbs, " +
"1/4 cup ketchup, 1/3 tsp onion powder, 1 clove of garlic, " +
"1/2 pack onion soup mix, dash of your favorite BBQ Sauce",
"****"};
string[] row2 = new string[]{"Key Lime Pie", "Dessert",
"lime juice, whipped cream, eggs, evaporated milk", "****"};
"Main Dish", "pork chops, salsa, orange juice, pineapple",
"****"};
"Salad", "black beans, brown rice", "****"};
"Dessert", "cream cheese, unsweetened chocolate", "***"};
"black beans, sour cream, salsa, chips", "***"};
{
this.dataGridView1.Rows.Add(rowArray);
}
// Adjust the row heights to accommodate the normal cell content.

this.dataGridView1.AutoResizeRows(
DataGridViewAutoSizeRowsMode.AllCellsExceptHeaders);
// Attach handlers to DataGridView events.

this.dataGridView1.ColumnWidthChanged += new
DataGridViewColumnEventHandler(dataGridView1_ColumnWidthChanged);
this.dataGridView1.RowPrePaint += new
DataGridViewRowPrePaintEventHandler(dataGridView1_RowPrePaint);
this.dataGridView1.RowPostPaint += new
DataGridViewRowPostPaintEventHandler(dataGridView1_RowPostPaint);
this.dataGridView1.CurrentCellChanged += new
EventHandler(dataGridView1_CurrentCellChanged);
this.dataGridView1.RowHeightChanged += new
DataGridViewRowEventHandler(dataGridView1_RowHeightChanged);
}
// Forces the control to repaint itself when the user

// manually changes the width of a column.
void dataGridView1_ColumnWidthChanged(object sender,
DataGridViewColumnEventArgs e)
{
this.dataGridView1.Invalidate();
}
// Forces the row to repaint itself when the user changes the
// current cell. This is necessary to refresh the focus rectangle.
void dataGridView1_CurrentCellChanged(object sender, EventArgs e)
{
if (oldRowIndex != -1)
{
this.dataGridView1.InvalidateRow(oldRowIndex);
}
oldRowIndex = this.dataGridView1.CurrentCellAddress.Y;
}
// Paints the custom selection background for selected rows.

void dataGridView1_RowPrePaint(object sender,
DataGridViewRowPrePaintEventArgs e)
{
// Do not automatically paint the focus rectangle.
e.PaintParts &= ~DataGridViewPaintParts.Focus;
// Determine whether the cell should be painted

// with the custom selection background.
if ((e.State & DataGridViewElementStates.Selected) ==
DataGridViewElementStates.Selected)
{
// Calculate the bounds of the row.
Rectangle rowBounds = new Rectangle(
this.dataGridView1.RowHeadersWidth, e.RowBounds.Top,
this.dataGridView1.Columns.GetColumnsWidth(
DataGridViewElementStates.Visible) -
this.dataGridView1.HorizontalScrollingOffset + 1,
e.RowBounds.Height);
// Paint the custom selection background.

using (Brush backbrush =
new System.Drawing.Drawing2D.LinearGradientBrush(rowBounds,
this.dataGridView1.DefaultCellStyle.SelectionBackColor,
e.InheritedRowStyle.ForeColor,
System.Drawing.Drawing2D.LinearGradientMode.Horizontal))
{
e.Graphics.FillRectangle(backbrush, rowBounds);
}
}
}
// Paints the content that spans multiple columns and the focus
rectangle.
void dataGridView1_RowPostPaint(object sender,
DataGridViewRowPostPaintEventArgs e)
{
// Calculate the bounds of the row.
Rectangle rowBounds = new Rectangle(
this.dataGridView1.RowHeadersWidth, e.RowBounds.Top,
this.dataGridView1.Columns.GetColumnsWidth(
DataGridViewElementStates.Visible) -
this.dataGridView1.HorizontalScrollingOffset + 1,
e.RowBounds.Height);
SolidBrush forebrush = null;

try
{
// Determine the foreground color.
if ((e.State & DataGridViewElementStates.Selected) ==
DataGridViewElementStates.Selected)
{
forebrush = new
SolidBrush(e.InheritedRowStyle.SelectionForeColor);
}
else
{
forebrush = new SolidBrush(e.InheritedRowStyle.ForeColor);
}
// Get the content that spans multiple columns.
object recipe =
this.dataGridView1.Rows.SharedRow(e.RowIndex).Cells[2].Value;
if (recipe != null)
{
String text = recipe.ToString();
// Calculate the bounds for the content that spans multiple

// columns, adjusting for the horizontal scrolling position
// and the current row height, and displaying only whole
// lines of text.
Rectangle textArea = rowBounds;
textArea.X -= this.dataGridView1.HorizontalScrollingOffset;
textArea.Width +=
this.dataGridView1.HorizontalScrollingOffset;
textArea.Y += rowBounds.Height -
e.InheritedRowStyle.Padding.Bottom;
textArea.Height -= rowBounds.Height -
e.InheritedRowStyle.Padding.Bottom;
textArea.Height = (textArea.Height /
e.InheritedRowStyle.Font.Height) *
e.InheritedRowStyle.Font.Height;
// Calculate the portion of the text area that needs

painting.
RectangleF clip = textArea;
clip.Width -= this.dataGridView1.RowHeadersWidth + 1 -
clip.X;
clip.X = this.dataGridView1.RowHeadersWidth + 1;
RectangleF oldClip = e.Graphics.ClipBounds;
e.Graphics.SetClip(clip);
// Draw the content that spans multiple columns.

e.Graphics.DrawString(
text, e.InheritedRowStyle.Font, forebrush, textArea);
e.Graphics.SetClip(oldClip);
}
}
finally
{
forebrush.Dispose();
}
if (this.dataGridView1.CurrentCellAddress.Y == e.RowIndex)
{
// Paint the focus rectangle.
e.DrawFocus(rowBounds, true);
}
}
// Adjusts the padding when the user changes the row height so that
// the normal cell content is fully displayed and any extra
// height is used for the content that spans multiple columns.
void dataGridView1_RowHeightChanged(object sender,
DataGridViewRowEventArgs e)
{
// Calculate the new height of the normal cell content.
Int32 preferredNormalContentHeight =
e.Row.GetPreferredHeight(e.Row.Index,
DataGridViewAutoSizeRowMode.AllCellsExceptHeader, true) -
e.Row.DefaultCellStyle.Padding.Bottom;
// Specify a new padding.

Padding newPadding = e.Row.DefaultCellStyle.Padding;
newPadding.Bottom = e.Row.Height - preferredNormalContentHeight;
e.Row.DefaultCellStyle.Padding = newPadding;
}
}
Confira também
DataGridView
DataGridView.RowPrePaint
DataGridView.RowPostPaint
Como: Personalizar células e colunas no
Forms estendendo o comportamento e
a aparência
Artigo • 02/06/2023
O DataGridView controle fornece várias maneiras de personalizar sua aparência e

comportamento usando propriedades, eventos e classes complementares.
Ocasionalmente, você pode ter requisitos para as suas células que ultrapassem o que
esses recursos podem fornecer. Você pode criar sua própria classe personalizada
DataGridViewCell para fornecer funcionalidade estendida.
Você cria uma classe personalizada DataGridViewCell derivando da DataGridViewCell

classe base ou de uma de suas classes derivadas. Embora você possa exibir qualquer
tipo de célula em qualquer tipo de coluna, normalmente você também criará uma classe
personalizada DataGridViewColumn especializada para exibir seu tipo de célula. As
classes de coluna derivam de DataGridViewColumn ou de um de seus tipos derivados.
No exemplo de código a seguir, você criará uma classe de célula personalizada chamada
DataGridViewRolloverCell que detecta quando o mouse entra e sai dos limites da
célula. Enquanto o mouse está dentro dos limites da célula, um retângulo de inserção é
desenhado. Esse novo tipo deriva DataGridViewTextBoxCell e se comporta em todos os
outros aspectos como sua classe base. A classe de coluna correspondente chama-se
DataGridViewRolloverColumn .
Para usar essas classes, crie um formulário contendo um DataGridView controle,

adicione um ou mais DataGridViewRolloverColumn objetos à Columns coleção e
preencha o controle com linhas que contêm valores.
７ Observação
Este exemplo não funcionará corretamente se você adicionar linhas vazias. Linhas
vazias são criadas, por exemplo, quando você adiciona linhas ao controle definindo
a RowCount propriedade. Isso ocorre porque as linhas adicionadas neste caso são
compartilhadas automaticamente, o que significa que objetos
DataGridViewRolloverCell não são instanciados até você clicar em células
individuais, fazendo, assim, com que as linhas associadas tornem-se não

compartilhadas.
Uma vez que esse tipo de personalização de célula requer linhas não compartilhadas,
ele não é adequado para uso com grandes conjuntos de dados. Para obter mais
informações sobre compartilhamento de linha, consulte Práticas recomendadas para
colocação em escala do controle DataGridView dos Windows Forms.
７ Observação
Ao derivar ou DataGridViewCellDataGridViewColumn adicionar novas

propriedades à classe derivada, certifique-se de substituir o Clone método para
copiar as novas propriedades durante as operações de clonagem. Você também
deve chamar o método Clone da classe base para que as propriedades da classe
base sejam copiadas para a nova célula ou coluna.
Para personalizar células e colunas no controle

DataGridView
1. Derivar uma nova classe de célula, chamada DataGridViewRolloverCell , do
DataGridViewTextBoxCell tipo.
C#
public class DataGridViewRolloverCell : DataGridViewTextBoxCell

{
C#
2. Substitua o Paint método na DataGridViewRolloverCell classe. Em uma

substituição, primeiro chame a implementação da classe base, que lida com a
funcionalidade de caixa de texto hospedada. Em seguida, use o método do
controle para transformar a posição do PointToClient cursor (em coordenadas de
tela) nas DataGridView coordenadas da área do cliente. Se as coordenadas do
mouse estiverem dentro dos limites da célula, desenhe o retângulo em baixo-
relevo.
C#
protected override void Paint(

Graphics graphics,
Rectangle clipBounds,
Rectangle cellBounds,
int rowIndex,
DataGridViewElementStates cellState,
object value,
object formattedValue,
string errorText,
DataGridViewCellStyle cellStyle,
DataGridViewAdvancedBorderStyle advancedBorderStyle,
DataGridViewPaintParts paintParts)
{
// Call the base class method to paint the default cell appearance.
base.Paint(graphics, clipBounds, cellBounds, rowIndex, cellState,
value, formattedValue, errorText, cellStyle,
advancedBorderStyle, paintParts);
// Retrieve the client location of the mouse pointer.

Point cursorPosition =
this.DataGridView.PointToClient(Cursor.Position);
// If the mouse pointer is over the current cell, draw a custom

border.
if (cellBounds.Contains(cursorPosition))
{
Rectangle newRect = new Rectangle(cellBounds.X + 1,
cellBounds.Y + 1, cellBounds.Width - 4,
cellBounds.Height - 4);
graphics.DrawRectangle(Pens.Red, newRect);
}
}
3. Substitua os OnMouseEnter métodos e OnMouseLeave a classe para forçar as

DataGridViewRolloverCell células a se repintarem quando o ponteiro do mouse
entrar ou os deixar.
C#
// Force the cell to repaint itself when the mouse pointer enters it.
protected override void OnMouseEnter(int rowIndex)
{
this.DataGridView.InvalidateCell(this);
}
// Force the cell to repaint itself when the mouse pointer leaves it.
protected override void OnMouseLeave(int rowIndex)
{
}
4. Derivar uma nova classe, chamada DataGridViewRolloverCellColumn , do

DataGridViewColumn tipo. No construtor, atribua um novo
DataGridViewRolloverCell objeto à sua CellTemplate propriedade.
C#
public class DataGridViewRolloverCellColumn : DataGridViewColumn

{
public DataGridViewRolloverCellColumn()
{
this.CellTemplate = new DataGridViewRolloverCell();
}
}
Exemplo
O exemplo de código completo inclui um pequeno formulário de teste que demonstra
o comportamento do tipo de célula personalizado.
C#
using System;
class Form1 : Form

{
{
}
public Form1()
{
DataGridView dataGridView1 = new DataGridView();
DataGridViewRolloverCellColumn col =
new DataGridViewRolloverCellColumn();
dataGridView1.Columns.Add(col);
dataGridView1.Rows.Add(new string[] { "" });
this.Text = "DataGridView rollover-cell demo";
}
}
public class DataGridViewRolloverCell : DataGridViewTextBoxCell

{
protected override void Paint(
Graphics graphics,
Rectangle clipBounds,
Rectangle cellBounds,
int rowIndex,
DataGridViewElementStates cellState,
object value,
object formattedValue,
string errorText,
{
// Call the base class method to paint the default cell appearance.
base.Paint(graphics, clipBounds, cellBounds, rowIndex, cellState,
value, formattedValue, errorText, cellStyle,
advancedBorderStyle, paintParts);
// Retrieve the client location of the mouse pointer.

Point cursorPosition =
this.DataGridView.PointToClient(Cursor.Position);
// If the mouse pointer is over the current cell, draw a custom

border.
if (cellBounds.Contains(cursorPosition))
{
Rectangle newRect = new Rectangle(cellBounds.X + 1,
cellBounds.Y + 1, cellBounds.Width - 4,
cellBounds.Height - 4);
graphics.DrawRectangle(Pens.Red, newRect);
}
}
// Force the cell to repaint itself when the mouse pointer enters it.
protected override void OnMouseEnter(int rowIndex)
{
}
// Force the cell to repaint itself when the mouse pointer leaves it.
protected override void OnMouseLeave(int rowIndex)
{
}
public class DataGridViewRolloverCellColumn : DataGridViewColumn

{
public DataGridViewRolloverCellColumn()
{
this.CellTemplate = new DataGridViewRolloverCell();
}
}
Referências aos assemblies System, System.Windows.Forms e System.Drawing.
Confira também
DataGridView
DataGridViewCell
DataGridViewColumn
Windows Forms
Como: Desabilitar botões em uma
coluna de botão no controle
Artigo • 02/06/2023
O DataGridView controle inclui a DataGridViewButtonCell classe para exibir células com

uma interface do usuário (interface do usuário) como um botão. No entanto,
DataGridViewButtonCell não fornece uma maneira de desabilitar a aparência do botão
exibido pela célula.
O exemplo de código a seguir demonstra como personalizar a DataGridViewButtonCell

classe para exibir botões que podem aparecer desabilitados. O exemplo define um novo
tipo de célula, DataGridViewDisableButtonCell que deriva de DataGridViewButtonCell.
Esse tipo de célula fornece uma nova propriedade Enabled que pode ser definida como
false para desenhar um botão desabilitado na célula. O exemplo também define um
novo tipo de coluna, DataGridViewDisableButtonColumn , que exibe objetos
DataGridViewDisableButtonCell . Para demonstrar esse novo tipo de célula e coluna, o
valor atual de cada DataGridViewCheckBoxCell um dos pais DataGridView determina se
a Enabled propriedade da DataGridViewDisableButtonCell mesma linha é true ou
false .
７ Observação
Ao derivar ou DataGridViewCellDataGridViewColumn adicionar novas

propriedades à classe derivada, substitua o Clone método para copiar as novas
propriedades durante as operações de clonagem. Você também deve chamar o
método Clone da classe base para que as propriedades da classe base sejam
copiadas para a nova célula ou coluna.
Exemplo
C#
using System;
using System.Windows.Forms.VisualStyles;
class Form1 : Form
{
[STAThread]
{
}
public Form1()
{
}
public void Form1_Load(object sender, EventArgs e)

{
DataGridViewCheckBoxColumn column0 =
new DataGridViewCheckBoxColumn();
DataGridViewDisableButtonColumn column1 =
new DataGridViewDisableButtonColumn();
column0.Name = "CheckBoxes";
column1.Name = "Buttons";
dataGridView1.Columns.Add(column0);
dataGridView1.Columns.Add(column1);
dataGridView1.RowCount = 8;
dataGridView1.ColumnHeadersDefaultCellStyle.Alignment =
DataGridViewContentAlignment.MiddleCenter;
// Set the text for each button.

for (int i = 0; i < dataGridView1.RowCount; i++)
{
dataGridView1.Rows[i].Cells["Buttons"].Value =
"Button " + i.ToString();
}
dataGridView1.CellValueChanged +=
new
DataGridViewCellEventHandler(dataGridView1_CellValueChanged);
dataGridView1.CurrentCellDirtyStateChanged +=
new EventHandler(dataGridView1_CurrentCellDirtyStateChanged);
}
// This event handler manually raises the CellValueChanged event

// by calling the CommitEdit method.
void dataGridView1_CurrentCellDirtyStateChanged(object sender,
EventArgs e)
{
if (dataGridView1.IsCurrentCellDirty)
{
dataGridView1.CommitEdit(DataGridViewDataErrorContexts.Commit);
}
}
// If a check box cell is clicked, this event handler disables

// or enables the button in the same row as the clicked cell.
public void dataGridView1_CellValueChanged(object sender,
{
if (dataGridView1.Columns[e.ColumnIndex].Name == "CheckBoxes")
{
DataGridViewDisableButtonCell buttonCell =
(DataGridViewDisableButtonCell)dataGridView1.
Rows[e.RowIndex].Cells["Buttons"];
DataGridViewCheckBoxCell checkCell =
(DataGridViewCheckBoxCell)dataGridView1.
Rows[e.RowIndex].Cells["CheckBoxes"];
buttonCell.Enabled = !(Boolean)checkCell.Value;
dataGridView1.Invalidate();
}
}
// If the user clicks on an enabled button cell, this event handler

// reports that the button is enabled.
void dataGridView1_CellClick(object sender,
{
if (dataGridView1.Columns[e.ColumnIndex].Name == "Buttons")
{
DataGridViewDisableButtonCell buttonCell =
(DataGridViewDisableButtonCell)dataGridView1.
Rows[e.RowIndex].Cells["Buttons"];
if (buttonCell.Enabled)
{
MessageBox.Show(dataGridView1.Rows[e.RowIndex].
Cells[e.ColumnIndex].Value.ToString() +
" is enabled");
}
}
}
}
public class DataGridViewDisableButtonColumn : DataGridViewButtonColumn

{
public DataGridViewDisableButtonColumn()
{
this.CellTemplate = new DataGridViewDisableButtonCell();
}
}
public class DataGridViewDisableButtonCell : DataGridViewButtonCell
{
private bool enabledValue;
public bool Enabled
{
get
{
return enabledValue;
}
set
{
enabledValue = value;
}
}
// Override the Clone method so that the Enabled property is copied.

public override object Clone()
{
DataGridViewDisableButtonCell cell =
(DataGridViewDisableButtonCell)base.Clone();
cell.Enabled = this.Enabled;
return cell;
}
// By default, enable the button cell.

public DataGridViewDisableButtonCell()
{
this.enabledValue = true;
}
protected override void Paint(Graphics graphics,

Rectangle clipBounds, Rectangle cellBounds, int rowIndex,
DataGridViewElementStates elementState, object value,
object formattedValue, string errorText,
{
// The button cell is disabled, so paint the border,
// background, and disabled button for the cell.
if (!this.enabledValue)
{
// Draw the cell background, if specified.
if ((paintParts & DataGridViewPaintParts.Background) ==
DataGridViewPaintParts.Background)
{
SolidBrush cellBackground =
new SolidBrush(cellStyle.BackColor);
graphics.FillRectangle(cellBackground, cellBounds);
cellBackground.Dispose();
}
// Draw the cell borders, if specified.

if ((paintParts & DataGridViewPaintParts.Border) ==
DataGridViewPaintParts.Border)
{
PaintBorder(graphics, clipBounds, cellBounds, cellStyle,
advancedBorderStyle);
}
// Calculate the area in which to draw the button.

Rectangle buttonArea = cellBounds;
Rectangle buttonAdjustment =
this.BorderWidths(advancedBorderStyle);
buttonArea.X += buttonAdjustment.X;
buttonArea.Y += buttonAdjustment.Y;
buttonArea.Height -= buttonAdjustment.Height;
buttonArea.Width -= buttonAdjustment.Width;
// Draw the disabled button.

ButtonRenderer.DrawButton(graphics, buttonArea,
PushButtonState.Disabled);
// Draw the disabled button text.

if (this.FormattedValue is String)
{
TextRenderer.DrawText(graphics,
(string)this.FormattedValue,
this.DataGridView.Font,
buttonArea, SystemColors.GrayText);
}
}
else
{
// The button cell is enabled, so let the base class
// handle the painting.
base.Paint(graphics, clipBounds, cellBounds, rowIndex,
elementState, value, formattedValue, errorText,
cellStyle, advancedBorderStyle, paintParts);
}
}
}
Referências aos assemblies System, System.Drawing, System.Windows.Forms e

System.Windows.Forms.VisualStyles.
Confira também
Como: Hospedar controles em células
Artigo • 02/06/2023
O DataGridView controle fornece vários tipos de coluna, permitindo que os usuários

insiram e editem valores de várias maneiras. No entanto, se esses tipos de coluna não
atenderem às suas necessidades de entrada de dados, será possível criar seus próprios
tipos de coluna com células que hospedam controles de sua escolha. Para fazer isso,
você deve definir classes que derivam de DataGridViewColumn e DataGridViewCell.
Você também deve definir uma classe que deriva de Control e implementa a
IDataGridViewEditingControl interface .
O exemplo de código a seguir mostra como criar uma coluna de calendário. As células
dessa coluna exibem datas em células comuns da caixa de texto, mas quando o usuário
edita uma célula, um DateTimePicker controle é exibido. Para evitar a implementação da
funcionalidade de exibição da caixa de texto novamente,
CalendarCell DataGridViewTextBoxCell a classe deriva da classe em vez de herdar a
DataGridViewCell classe diretamente.
７ Observação
Quando você derivar de DataGridViewCell ou DataGridViewColumn e adicionar

novas propriedades à classe derivada, Clone substitua o método para copiar as
novas propriedades durante as operações de clonagem. Você também deve
chamar o método Clone da classe base para que as propriedades da classe base
sejam copiadas para a nova célula ou coluna.
Exemplo
C#
using System;
public class CalendarColumn : DataGridViewColumn

{
public CalendarColumn() : base(new CalendarCell())
{
}
public override DataGridViewCell CellTemplate

{
get
{
return base.CellTemplate;
}
set
{
// Ensure that the cell used for the template is a CalendarCell.
if (value != null &&
!value.GetType().IsAssignableFrom(typeof(CalendarCell)))
{
throw new InvalidCastException("Must be a CalendarCell");
}
base.CellTemplate = value;
}
}
}
public class CalendarCell : DataGridViewTextBoxCell

{
public CalendarCell()
: base()
{
// Use the short date format.
this.Style.Format = "d";
}
public override void InitializeEditingControl(int rowIndex, object

initialFormattedValue, DataGridViewCellStyle dataGridViewCellStyle)
{
// Set the value of the editing control to the current cell value.
base.InitializeEditingControl(rowIndex, initialFormattedValue,
dataGridViewCellStyle);
CalendarEditingControl ctl =
DataGridView.EditingControl as CalendarEditingControl;
// Use the default row value when Value property is null.
if (this.Value == null)
{
ctl.Value = (DateTime)this.DefaultNewRowValue;
}
else
{
ctl.Value = (DateTime)this.Value;
}
}
public override Type EditType

{
get
{
// Return the type of the editing control that CalendarCell
uses.
return typeof(CalendarEditingControl);
}
}
public override Type ValueType

{
get
{
// Return the type of the value that CalendarCell contains.
return typeof(DateTime);
}
}
public override object DefaultNewRowValue

{
get
{
// Use the current date and time as the default value.
return DateTime.Now;
}
}
}
class CalendarEditingControl : DateTimePicker, IDataGridViewEditingControl

{
private bool valueChanged = false;
int rowIndex;
public CalendarEditingControl()
{
this.Format = DateTimePickerFormat.Short;
}
// Implements the
IDataGridViewEditingControl.EditingControlFormattedValue
// property.
public object EditingControlFormattedValue
{
get
{
return this.Value.ToShortDateString();
}
set
{
if (value is String)
{
try
{
// This will throw an exception of the string is
// null, empty, or not in the format of a date.
this.Value = DateTime.Parse((String)value);
}
catch
{
// In the case of an exception, just use the
// default value so we're not left with a null
// value.
this.Value = DateTime.Now;
}
}
}
}
// Implements the
// IDataGridViewEditingControl.GetEditingControlFormattedValue method.
public object GetEditingControlFormattedValue(
DataGridViewDataErrorContexts context)
{
return EditingControlFormattedValue;
}
// Implements the
// IDataGridViewEditingControl.ApplyCellStyleToEditingControl method.
public void ApplyCellStyleToEditingControl(
DataGridViewCellStyle dataGridViewCellStyle)
{
this.Font = dataGridViewCellStyle.Font;
this.CalendarForeColor = dataGridViewCellStyle.ForeColor;
this.CalendarMonthBackground = dataGridViewCellStyle.BackColor;
}
// Implements the IDataGridViewEditingControl.EditingControlRowIndex

// property.
public int EditingControlRowIndex
{
get
{
return rowIndex;
}
set
{
rowIndex = value;
}
}
// Implements the
IDataGridViewEditingControl.EditingControlWantsInputKey
// method.
public bool EditingControlWantsInputKey(
Keys key, bool dataGridViewWantsInputKey)
{
// Let the DateTimePicker handle the keys listed.
switch (key & Keys.KeyCode)
{
case Keys.Left:
case Keys.Up:
case Keys.Down:
case Keys.Right:
case Keys.Home:
case Keys.End:
case Keys.PageDown:
case Keys.PageUp:
return true;
default:
return !dataGridViewWantsInputKey;
}
}
// Implements the
IDataGridViewEditingControl.PrepareEditingControlForEdit
// method.
public void PrepareEditingControlForEdit(bool selectAll)
{
// No preparation needs to be done.
}
// Implements the IDataGridViewEditingControl

// .RepositionEditingControlOnValueChange property.
public bool RepositionEditingControlOnValueChange
{
get
{
return false;
}
}

// .EditingControlDataGridView property.
public DataGridView EditingControlDataGridView
{
get
{
return dataGridView;
}
set
{
dataGridView = value;
}
}

// .EditingControlValueChanged property.
public bool EditingControlValueChanged
{
get
{
return valueChanged;
}
set
{
valueChanged = value;
}
}

// .EditingPanelCursor property.
public Cursor EditingPanelCursor
{
get
{
return base.Cursor;
}
}
protected override void OnValueChanged(EventArgs eventargs)

{
// Notify the DataGridView that the contents of the cell
// have changed.
valueChanged = true;
this.EditingControlDataGridView.NotifyCurrentCellDirty(true);
base.OnValueChanged(eventargs);
}
}

{
{
}
public Form1()
{
this.Text = "DataGridView calendar column demo";
}

{
CalendarColumn col = new CalendarColumn();
this.dataGridView1.Columns.Add(col);
this.dataGridView1.RowCount = 5;
foreach (DataGridViewRow row in this.dataGridView1.Rows)
{
row.Cells[0].Value = DateTime.Now;
}
}
}
O exemplo a seguir requer:
Confira também
DataGridView
DataGridViewColumn
DataGridViewCell
DataGridViewTextBoxCell
DateTimePicker
Ajuste de desempenho no controle
Artigo • 02/06/2023
Ao trabalhar com grandes quantidades de dados, o controle DataGridView pode

consumir uma grande quantidade de memória em sobrecarga, a menos que você o
utilize com cuidado. Em clientes com memória limitada, é possível evitar um pouco
dessa sobrecarga, evitando recursos que têm um custo de memória alto. Você também
pode gerenciar alguns ou todas as tarefas de manutenção e recuperação de dados
usando o modo virtual para personalizar o uso de memória para seu cenário.
Nesta seção
Práticas recomendadas para dimensionamento do controle DataGridView dos Windows
Forms
Descreve como usar o controle DataGridView de uma maneira que evite penalidades no
desempenho e no uso de memória desnecessário ao trabalhar com grandes
quantidades de dados.

Descreve como usar o modo virtual para suplementar ou substituir o mecanismo de
associação de dados padrão.
Passo a passo: Implementando o modo virtual no controle DataGridView do Windows

Forms
Descreve como implementar manipuladores para vários eventos no modo virtual.
Também demonstra como implementar a reversão de nível de linha e confirmar as
edições do usuário.
Implementando o modo virtual com carregamento de dados Just-In-Time no controle

Descreve como carregar dados sob demanda, que é útil quando você tem mais dados
para exibir do que a memória de cliente disponível pode armazenar.
Referência
DataGridView
VirtualMode
Fornece a documentação de referência para a VirtualMode propriedade.
Confira também
Práticas recomendadas para
dimensionamento do controle
Artigo • 02/06/2023
O DataGridView controle foi projetado para fornecer escalabilidade máxima. Se você

precisa exibir grandes quantidades de dados, siga as diretrizes descritas neste tópico
para evitar o consumo de grandes quantidades de memória ou prejudicar a capacidade
de resposta da UI (interface do usuário). Este tópico discute os seguintes problemas:
Usando estilos de célula com eficiência
Usando menus de atalho com eficiência
Usando o redimensionamento automático com eficiência
Usando as coleções de células, linhas e colunas selecionadas com eficiência
Usando linhas compartilhadas
Impedindo as linhas de se tornarem não compartilhadas
Se você tiver necessidades de desempenho especiais, implemente o modo virtual e

forneça suas próprias operações de gerenciamento de dados. Para obter mais
informações, consulte Modos de exibição dos dados no controle DataGridView dos
Windows Forms.
Usando Estilos de Célula com Eficiência

Cada célula, linha e coluna pode ter suas próprias informações de estilo. As informações
de estilo são armazenadas em DataGridViewCellStyle objetos. A criação de objetos de
estilo de célula para muitos elementos individuais DataGridView pode ser ineficiente,
especialmente ao trabalhar com grandes quantidades de dados. Para evitar um impacto
no desempenho, use as seguintes diretrizes:
Evite definir propriedades de estilo de célula para objetos ou DataGridViewRow

individuaisDataGridViewCell. Isso inclui o objeto de linha especificado pela
RowTemplate propriedade. Cada nova linha que é clonada do modelo de linha
receberá sua própria cópia do objeto de estilo de célula do modelo. Para
escalabilidade máxima, defina as propriedades de estilo de célula no DataGridView
nível. Por exemplo, defina a DataGridView.DefaultCellStyle propriedade em vez da
DataGridViewCell.Style propriedade.
Se algumas células exigirem formatação diferente da formatação padrão, use a

mesma DataGridViewCellStyle instância entre grupos de células, linhas ou colunas.
Evite definir diretamente as propriedades do tipo DataGridViewCellStyle em
células, linhas e colunas individuais. Para obter um exemplo de compartilhamento
de estilo de célula, consulte Instruções: definir estilos de célula padrão para o
controle DataGridView dos Windows Forms. Você também pode evitar uma
penalidade de desempenho ao definir estilos de célula individualmente
manipulando o CellFormatting manipulador de eventos. Para obter um exemplo,
consulte Instruções: personalizar a formatação de dados no controle DataGridView
dos Windows Forms.
Ao determinar o estilo de uma célula, use a DataGridViewCell.InheritedStyle

propriedade em vez da DataGridViewCell.Style propriedade. Acessar a Style
propriedade criará uma nova instância da DataGridViewCellStyle classe se a
propriedade ainda não tiver sido usada. Além disso, esse objeto poderá não conter
as informações de estilo completas para a célula se alguns estilos forem herdados
da linha, da coluna ou do controle. Para obter mais informações sobre herança de
estilo de célula, consulte Estilos de célula no controle DataGridView dos Windows
Forms.
Usando Menus de Atalho com Eficiência

Cada célula, linha e coluna pode ter seu próprio menu de atalho. Os menus de atalho no
DataGridView controle são representados por ContextMenuStrip controles. Assim como
acontece com objetos de estilo de célula, a criação de menus de atalho para muitos
elementos individuais DataGridView afetará negativamente o desempenho. Para evitar
essa penalidade, use as seguintes diretrizes:
Evite criar menus de atalho para células e linhas individuais. Isso inclui o modelo
de linha, que é clonado juntamente com o menu de atalho quando novas linhas
são adicionadas ao controle. Para obter escalabilidade máxima, use apenas a
propriedade do ContextMenuStrip controle para especificar um único menu de
atalho para todo o controle.
Se você precisar de vários menus de atalho para várias linhas ou células, lide com
os eventos ou RowContextMenuStripNeeded as CellContextMenuStripNeeded
linhas. Esses eventos permitem gerenciar os objetos do menu de atalho por conta
própria, possibilitando ajustar o desempenho.
Usando o Redimensionamento Automático
com Eficiência
Cabeçalhos, colunas e linhas podem ser redimensionados automaticamente como
alterações de conteúdo da célula para que todo o conteúdo das células seja exibido
sem recorte. Alterar os modos de dimensionamento também pode redimensionar
linhas, colunas e cabeçalhos. Para determinar o tamanho correto, o DataGridView
controle deve examinar o valor de cada célula que deve acomodar. Ao trabalhar com
grandes conjuntos de dados, essa análise poderá afetar negativamente o desempenho
do controle quando o redimensionamento automático ocorrer. Para evitar penalidades
de desempenho, use as seguintes diretrizes:
Evite usar o dimensionamento automático em um DataGridView controle com um

grande conjunto de linhas. Se você usar o dimensionamento automático,
redimensione apenas com base nas linhas exibidas. Além disso, use apenas as
linhas exibidas no modo virtual.
Para linhas e colunas, use o DisplayedCells campo ou

DisplayedCellsExceptHeaders o DataGridViewAutoSizeRowsModecampo do ,
DataGridViewAutoSizeColumnsModee enumerações
DataGridViewAutoSizeColumnMode .
Para cabeçalhos de linha, use o AutoSizeToDisplayedHeaders campo ou

AutoSizeToFirstHeader a DataGridViewRowHeadersWidthSizeMode
enumeração.
Para obter escalabilidade máxima, desligue o dimensionamento automático e use

o redimensionamento programático.
Para obter mais informações, consulte Sizing Options in the Windows Forms
DataGridView Control (Opções de dimensionamento no controle DataGridView dos
Windows Forms).
Usando as Coleções de Células, Linhas e

Colunas Selecionadas com Eficiência
A SelectedCells coleção não tem um desempenho eficiente com seleções grandes. As
SelectedRows coleções e SelectedColumns as coleções também podem ser ineficientes,
embora em menor grau porque há muito menos linhas do que células em um controle
típico DataGridView , e muito menos colunas do que linhas. Para evitar penalidades de
desempenho ao trabalhar com essas coleções, use as seguintes diretrizes:
Para determinar se todas as células no DataGridView foram selecionadas antes de
acessar o conteúdo da SelectedCells coleção, verifique o valor retornado do
AreAllCellsSelected método. No entanto, observe que esse método pode fazer
com que as linhas se tornem não compartilhadas. Para obter mais informações,
consulte a próxima seção.
Evite usar a Count propriedade do

System.Windows.Forms.DataGridViewSelectedCellCollection para determinar o
número de células selecionadas. Em vez disso, use o DataGridView.GetCellCount
método e passe o DataGridViewElementStates.Selected valor. Da mesma forma,
use os métodos e DataGridViewColumnCollection.GetColumnCount os
DataGridViewRowCollection.GetRowCount métodos para determinar o número de
elementos selecionados, em vez de acessar as coleções de linhas e colunas
selecionadas.
Evite modos de seleção com base em célula. Em vez disso, defina a

DataGridView.SelectionMode propriedade como
DataGridViewSelectionMode.FullRowSelect ou
DataGridViewSelectionMode.FullColumnSelect.
Usando Linhas Compartilhadas

O uso eficiente de memória é obtido no DataGridView controle por meio de linhas
compartilhadas. As linhas compartilharão o máximo de informações sobre sua aparência
e comportamento possível compartilhando instâncias da DataGridViewRow classe.
Embora o compartilhamento de instâncias de linha poupe memória, as linhas podem

facilmente se tornar não compartilhadas. Por exemplo, sempre que um usuário interage
diretamente com uma célula, sua linha se torna não compartilhada. Como isso não pode
ser evitado, as diretrizes neste tópico são úteis somente ao trabalhar com grandes
quantidades de dados e somente quando os usuários forem interagir com uma parte
relativamente pequena dos dados sempre que o programa for executado.
Uma linha não poderá ser compartilhada em um controle não associado DataGridView
se qualquer uma de suas células contiver valores. Quando o DataGridView controle está
associado a uma fonte de dados externa ou quando você implementa o modo virtual e
fornece sua própria fonte de dados, os valores de célula são armazenados fora do
controle e não em objetos de célula, permitindo que as linhas sejam compartilhadas.
Um objeto de linha poderá ser compartilhado apenas se o estado de todas as suas

células puder ser determinado por meio do estado da linha e dos estados das colunas
que contêm as células. Se você alterar o estado de uma célula para que ela não possa
mais ser deduzida por meio do estado de sua linha e coluna, a linha não poderá ser
compartilhada.
Por exemplo, uma linha não pode ser compartilhada em nenhuma das seguintes
situações:
A linha contém uma única célula selecionada que não está em uma coluna
selecionada.
A linha contém uma célula com suas ToolTipText propriedades definidas

ContextMenuStrip .
A linha contém um DataGridViewComboBoxCell conjunto de propriedades.Items
No modo associado ou no modo virtual, você pode fornecer Dicas de Ferramentas e

menus de atalho para células individuais manipulando e
CellToolTipTextNeededCellContextMenuStripNeeded eventos.
O DataGridView controle tentará usar linhas compartilhadas automaticamente sempre

que as linhas forem adicionadas ao DataGridViewRowCollection. Use as diretrizes a
seguir para garantir que as linhas sejam compartilhadas:
Evite chamar a Add(Object[]) sobrecarga do Add método e a Insert(Object[])

sobrecarga do Insert método da DataGridView.Rows coleção. Essas sobrecargas
criam linhas não compartilhadas automaticamente.
Verifique se a linha especificada na DataGridView.RowTemplate propriedade pode

ser compartilhada nos seguintes casos:
Ao chamar ou Add() Add(Int32) sobrecarregar o Add método ou a

Insert(Int32,Int32) sobrecarga do Insert método da DataGridView.Rows
coleção.
Ao aumentar o valor da DataGridView.RowCount propriedade.
Ao definir a DataGridView.DataSource propriedade.
Certifique-se de que a linha indicada pelo indexSource parâmetro possa ser

compartilhada ao chamar o AddCopy, AddCopiese InsertCopyInsertCopies os
métodos da DataGridView.Rows coleção.
Certifique-se de que as linhas ou linhas especificadas possam ser compartilhadas

ao chamar a Add(DataGridViewRow) sobrecarga do Add método, o AddRange
método, a Insert(Int32,DataGridViewRow) sobrecarga do Insert método e o
InsertRange método da DataGridView.Rows coleção.
Para determinar se uma linha é compartilhada, use o
DataGridViewRowCollection.SharedRow método para recuperar o objeto de linha e
verifique a propriedade do Index objeto. As linhas compartilhadas sempre têm um Index
valor de propriedade de –1.
Impedindo as Linhas de se Tornarem Não

Compartilhadas
As linhas compartilhadas podem se tornar não compartilhadas como resultado da ação
de usuário ou de código. Para evitar um impacto no desempenho, evite fazer com que
as linhas se tornem não compartilhadas. Durante o desenvolvimento do aplicativo, você
pode lidar com o RowUnshared evento para determinar quando as linhas ficam sem
formatar. Isso é útil ao depurar problemas de compartilhamento de linhas.
Para impedir que as linhas se tornem não compartilhadas, use as seguintes diretrizes:
Evite indexar a Rows coleção ou iterar por meio dela com um foreach loop.
Normalmente não será necessário acessar as linhas diretamente. DataGridView
métodos que operam em linhas levam argumentos de índice de linha em vez de
instâncias de linha. Além disso, os manipuladores de eventos relacionados à linha
recebem objetos de argumento de evento com propriedades de linha que você
pode usar para manipular linhas sem fazer com que elas se tornem não
compartilhadas.
Se você precisar acessar um objeto de linha, use o

DataGridViewRowCollection.SharedRow método e passe o índice real da linha.
Observe, entretanto, que modificar um objeto de linha compartilhada recuperado
por esse método modificará todas as linhas que compartilham esse objeto. A linha
para novos registros não é compartilhada com outras linhas, no entanto, ela não
será afetada quando você modificar qualquer outra linha. Observe também que
diferentes linhas representadas por uma linha compartilhada podem ter menus de
atalho diferentes. Para recuperar o menu de atalho correto de uma instância de
linha compartilhada, use o GetContextMenuStrip método e passe o índice real da
linha. Se você acessar a propriedade da ContextMenuStrip linha compartilhada, ela
usará o índice de linha compartilhada de -1 e não recuperará o menu de atalho
correto.
Evite indexar a DataGridViewRow.Cells coleção. Acessar uma célula diretamente

fará com que sua linha pai se torne não compartilhada, instanciando uma nova
DataGridViewRow. Manipuladores de eventos relacionados à célula recebem
objetos de argumento de evento com propriedades de célula que você pode usar
para manipular células sem fazer com que as linhas se tornem não compartilhadas.
Você também pode usar a CurrentCellAddress propriedade para recuperar os
índices de linha e coluna da célula atual sem acessar a célula diretamente.
Evite modos de seleção com base em célula. Esses modos fazem com que as linhas
se tornem não compartilhadas. Em vez disso, defina a
DataGridView.SelectionMode propriedade como
DataGridViewSelectionMode.FullRowSelect ou
DataGridViewSelectionMode.FullColumnSelect.
Não manipule os eventos ou DataGridView.RowStateChanged os

DataGridViewRowCollection.CollectionChanged eventos. Esses eventos fazem com
que as linhas se tornem não compartilhadas. Além disso, não chame os métodos
ou DataGridView.OnRowStateChanged os
DataGridViewRowCollection.OnCollectionChanged quais geram esses eventos.
Não acesse a DataGridView.SelectedCells coleção quando o valor da

DataGridView.SelectionMode propriedade forFullColumnSelect,
FullRowSelectColumnHeaderSelectou RowHeaderSelect. Isso faz com que todas as
linhas selecionadas se tornem não compartilhadas.
Não chame o DataGridView.AreAllCellsSelected método. Esse método pode fazer

com que as linhas se tornem não compartilhadas.
Não chame o DataGridView.SelectAll método quando o valor da

DataGridView.SelectionMode propriedade for CellSelect. Isso faz com que todas as
linhas se tornem não compartilhadas.
Não defina a propriedade ou a ReadOnly propriedade de uma célula para false

quando a propriedade correspondente em sua coluna estiver definida como
true .Selected Isso faz com que todas as linhas se tornem não compartilhadas.
Não acesse a DataGridViewRowCollection.List propriedade. Isso faz com que todas

as linhas se tornem não compartilhadas.
Não chame a Sort(IComparer) sobrecarga do Sort método. Classificar com um

comparador personalizado faz com que todas as linhas se tornem não
compartilhadas.
Confira também
DataGridView
Forms
Modo virtual no controle DataGridView
dos Windows Forms
Artigo • 02/06/2023
Com o modo virtual, você pode gerenciar a interação entre o DataGridView controle e
um cache de dados personalizado. Para implementar o modo virtual, defina a
VirtualMode propriedade true como e manipule um ou mais dos eventos descritos
neste tópico. Você normalmente manipulará pelo menos o evento CellValueNeeded , que
permite os valores de consulta do controle no cache de dados.
Modo associado e modo virtual

O modo virtual é necessário somente quando você precisar suplementar ou substituir o
modo associado. No modo associado, você define a DataSource propriedade e o
controle carrega automaticamente os dados da fonte especificada e envia as alterações
de usuário de volta para ela. Você pode controlar quais colunas associadas são exibidas
e a fonte de dados que geralmente lida com operações como classificação.
Complementando o modo associado

Você pode complementar o modo associado exibindo colunas não associadas junto
com as colunas associadas. Isso, às vezes, é chamado de "modo misto" e é útil para
exibir coisas como controles de interface do usuário ou valores calculados.
Como as colunas não associadas estão fora da fonte de dados, elas são ignoradas por
operações de classificação da fonte de dados. Portanto, ao habilitar a classificação no
modo misto, você deve gerenciar os dados não associados em um cache local e
implementar o modo virtual para permitir que o DataGridView controle interaja com ele.
Para obter mais informações sobre como usar o modo virtual para manter os valores em
colunas não associadas, consulte os exemplos nos
DataGridViewCheckBoxColumn.ThreeState tópicos de referência de propriedade e
System.Windows.Forms.DataGridViewComboBoxColumn classe.
Substituindo o modo associado

Se o modo associado não atender às suas necessidades de desempenho, você poderá
gerenciar todos os seus dados em um cache personalizado por meio de manipuladores
de eventos de modo virtual. Por exemplo, você pode usar o modo virtual para
implementar um mecanismo de carregamento de dados Just-In-Time que recupera
apenas os dados necessários de um banco de dados para desempenho ideal. Esse
cenário é particularmente útil ao trabalhar com grandes quantidades de dados em uma
conexão de rede lenta ou com computadores cliente que têm uma quantidade limitada
de RAM ou espaço de armazenamento.
Para obter mais informações sobre como usar o modo virtual em um cenário Just-In-
Time, consulte Implementando o modo virtual com o carregamento de dados Just-In-
Time no controle DataGridView dos Windows Forms.
Eventos de modo virtual

Se seus dados são somente leitura, o evento CellValueNeeded pode ser o único com o
qual você precisará lidar. Eventos adicionais de modo virtual permitem que você habilite
uma funcionalidade específica como edições do usuário, adição de linha e exclusão e
transações de nível de linha.
Alguns eventos padrão DataGridView (como eventos que ocorrem quando os usuários
adicionam ou excluem linhas ou quando valores de célula são editados, analisados,
validados ou formatados) também são úteis no modo virtual. Você também pode
manipular eventos que lhe permitam manter valores que geralmente não são
armazenados em uma fonte de dados associada, como o texto de dica de ferramenta da
célula, texto de erro de linha e célula, célula e dados de menu de atalho da linha e
dados de altura de linha.
Para mais informações sobre como implementar o modo virtual para gerenciar os dados
de leitura/gravação com um escopo de confirmação de nível de linha, consulte Passo a
passo: implementando o modo virtual no controle DataGridView dos Windows Forms.
Para obter um exemplo que implementa o modo virtual com um escopo de confirmação
no nível da célula, consulte o tópico de referência da VirtualMode propriedade.
Os eventos a seguir ocorrem somente quando a VirtualMode propriedade é definida

como true .
Evento Descrição
CellValueNeeded Usado pelo controle para recuperar um valor de célula do cache de

dados para exibição. Esse evento ocorre somente para células em
colunas não associadas.
Evento Descrição
CellValuePushed Usado pelo controle para confirmar a entrada do usuário de uma célula
para o cache de dados. Esse evento ocorre somente para células em
colunas não associadas.
Chame o UpdateCellValue método ao alterar um valor armazenado em

cache fora de um CellValuePushed manipulador de eventos para garantir
que o valor atual seja exibido no controle e aplicar todos os modos de
dimensionamento automáticos atualmente em vigor.
NewRowNeeded Usado pelo controle para indicar a necessidade de uma nova linha no
cache de dados.
RowDirtyStateNeeded Usado pelo controle para determinar se uma linha tem alterações não
confirmadas.
CancelRowEdit Usado pelo controle para indicar que uma linha deve ser revertida para
seus valores armazenados em cache.
Os eventos a seguir são úteis no modo virtual, mas podem ser usados
independentemente da configuração da VirtualMode propriedade.
Eventos DESCRIÇÃO
UserDeletingRow Usado pelo controle para indicar quando as linhas são excluídas
ou adicionadas, permitindo a atualização do cache de dados
UserDeletedRow adequadamente.
RowsRemoved
RowsAdded
CellFormatting Usado pelo controle para formatar valores de célula para

exibição e para analisar e validar a entrada do usuário.
CellParsing
CellValidating
CellValidated
RowValidating
RowValidated
Eventos DESCRIÇÃO
CellToolTipTextNeeded Usado pelo controle para recuperar o texto tooltip da célula

quando a DataSource propriedade é definida ou a VirtualMode
propriedade é true .
As Dicas de Ferramenta de Célula são exibidas somente quando

o valor da ShowCellToolTips propriedade é true .
CellErrorTextNeeded Usado pelo controle para recuperar texto de erro de célula ou

linha quando a DataSource propriedade é definida ou a
RowErrorTextNeeded VirtualMode propriedade é true .
Chame o UpdateCellErrorText método ou o UpdateRowErrorText

método quando você alterar o texto de erro de célula ou linha
para garantir que o valor atual seja exibido no controle.
Os glifos de erro de célula e linha são exibidos quando os

valores e ShowRowErrors propriedade ShowCellErrors são true .
CellContextMenuStripNeeded Usado pelo controle para recuperar uma célula ou linha

ContextMenuStrip quando a propriedade de controle
RowContextMenuStripNeeded DataSource é definida ou a VirtualMode propriedade é true .
RowHeightInfoNeeded Usado pelo controle para recuperar ou armazenar informações

de altura de linha no cache de dados. Chame o
RowHeightInfoPushed UpdateRowHeightInfo método ao alterar as informações de
altura da linha armazenadas em cache fora de um
RowHeightInfoPushed manipulador de eventos para garantir que
o valor atual seja usado na exibição do controle.
Melhores práticas para o modo virtual

Se você estiver implementando o modo virtual para trabalhar com eficiência com
grandes quantidades de dados, também desejará garantir que esteja trabalhando com
eficiência com o DataGridView próprio controle. Para mais informações sobre o uso
eficiente dos estilos de célula, dimensionamento automático, seleções e
compartilhamento de linhas, consulte Melhores práticas para dimensionamento do
Confira também
DataGridView
VirtualMode
Windows Forms
Windows Forms
Passo a passo: Implementando o modo
virtual no controle DataGridView do
Windows Forms
Artigo • 02/06/2023
Quando quiser exibir grandes quantidades de dados tabulares em um DataGridView

controle, você pode definir a VirtualMode propriedade para true gerenciar
explicitamente a interação do controle com seu armazenamento de dados. Isso permite
ajustar o desempenho do controle nessa situação.
O DataGridView controle fornece vários eventos que você pode manipular para interagir
com um armazenamento de dados personalizado. Este passo a passo orienta você ao
longo do processo de implementar esses manipuladores de eventos. O exemplo de
código neste tópico usa uma fonte de dados muito simples para fins de ilustração. Em
uma configuração de produção, você normalmente carregará apenas as linhas que
precisa exibir em um cache e manipulará DataGridView eventos com os quais interagir e
atualizar o cache. Para obter mais informações, consulte Implementando o modo virtual
com carregamento de dados Just-In-Time no controle DataGridView dos Windows
Forms
Para copiar o código deste tópico como uma única lista, consulte Como implementar o
modo virtual no controle DataGridView dos Windows Forms.
Para implementar o modo virtual
1. Crie uma classe que Form deriva e contenha um DataGridView controle.
O código a seguir contém uma inicialização básica. Ele declara algumas variáveis
que serão usadas em etapas posteriores, fornece um método Main e fornece um
layout de formulário simples no construtor da classe.
C#
using System;

{
// Declare an ArrayList to serve as the data store.

private System.Collections.ArrayList customers =
new System.Collections.ArrayList();
// Declare a Customer object to store data for a row being edited.

private Customer customerInEdit;
// Declare a variable to store the index of a row being edited.

// A value of -1 indicates that there is no row currently in edit.
private int rowInEdit = -1;
// Declare a variable to indicate the commit scope.

// Set this value to false to use cell-level commit scope.
private bool rowScopeCommit = true;
{
}
public Form1()
{
this.Text = "DataGridView virtual-mode demo (row-level commit
scope)";
}
C#
2. Implemente um manipulador para o evento do Load formulário que inicializa o

DataGridView controle e popula o armazenamento de dados com valores de
exemplo.
C#

{
// Enable virtual mode.
this.dataGridView1.VirtualMode = true;
// Connect the virtual-mode events to event handlers.

this.dataGridView1.CellValueNeeded += new
DataGridViewCellValueEventHandler(dataGridView1_CellValueNeeded);
this.dataGridView1.CellValuePushed += new
DataGridViewCellValueEventHandler(dataGridView1_CellValuePushed);
this.dataGridView1.NewRowNeeded += new
DataGridViewRowEventHandler(dataGridView1_NewRowNeeded);
this.dataGridView1.RowValidated += new
DataGridViewCellEventHandler(dataGridView1_RowValidated);
this.dataGridView1.RowDirtyStateNeeded += new
QuestionEventHandler(dataGridView1_RowDirtyStateNeeded);
this.dataGridView1.CancelRowEdit += new
QuestionEventHandler(dataGridView1_CancelRowEdit);
this.dataGridView1.UserDeletingRow += new
DataGridViewRowCancelEventHandler(dataGridView1_UserDeletingRow);

DataGridViewTextBoxColumn companyNameColumn = new
DataGridViewTextBoxColumn();
companyNameColumn.HeaderText = "Company Name";
companyNameColumn.Name = "Company Name";
DataGridViewTextBoxColumn contactNameColumn = new
contactNameColumn.HeaderText = "Contact Name";
contactNameColumn.Name = "Contact Name";
this.dataGridView1.Columns.Add(companyNameColumn);
this.dataGridView1.Columns.Add(contactNameColumn);
this.dataGridView1.AutoSizeColumnsMode =
DataGridViewAutoSizeColumnsMode.DisplayedCells;
// Add some sample entries to the data store.

this.customers.Add(new Customer(
"Bon app'", "Laurence Lebihan"));
"Bottom-Dollar Markets", "Elizabeth Lincoln"));
"B's Beverages", "Victoria Ashworth"));
// Set the row count, including the row for new records.
}
3. Implemente um manipulador para o CellValueNeeded evento que recupera o valor

de célula solicitado do armazenamento de dados ou do Customer objeto
atualmente em edição.
Esse evento ocorre sempre que o DataGridView controle precisa pintar uma célula.
C#
private void dataGridView1_CellValueNeeded(object sender,

System.Windows.Forms.DataGridViewCellValueEventArgs e)
{
// If this is the row for new records, no values are needed.
if (e.RowIndex == this.dataGridView1.RowCount - 1) return;
Customer customerTmp = null;
// Store a reference to the Customer object for the row being

painted.
if (e.RowIndex == rowInEdit)
{
customerTmp = this.customerInEdit;
}
else
{
customerTmp = (Customer)this.customers[e.RowIndex];
}
// Set the cell value to paint using the Customer object retrieved.
switch (this.dataGridView1.Columns[e.ColumnIndex].Name)
{
case "Company Name":
e.Value = customerTmp.CompanyName;
break;
case "Contact Name":

e.Value = customerTmp.ContactName;
break;
}
}
4. Implemente um manipulador para o CellValuePushed evento que armazena um

valor de célula editado no Customer objeto que representa a linha editada. Esse
evento ocorre sempre que o usuário confirma uma alteração de valor da célula.
C#
private void dataGridView1_CellValuePushed(object sender,

{

edited.
if (e.RowIndex < this.customers.Count)
{
// If the user is editing a new row, create a new Customer
object.
this.customerInEdit ??= new Customer(
((Customer)this.customers[e.RowIndex]).CompanyName,
((Customer)this.customers[e.RowIndex]).ContactName);
this.rowInEdit = e.RowIndex;
}
else
{
}
// Set the appropriate Customer property to the cell value entered.

String newValue = e.Value as String;
{
customerTmp.CompanyName = newValue;
break;

customerTmp.ContactName = newValue;
break;
}
}
5. Implemente um manipulador para o NewRowNeeded evento que cria um novo

Customer objeto que representa uma linha recém-criada.
Esse evento ocorre sempre que o usuário insere a linha de novos registros.
C#
private void dataGridView1_NewRowNeeded(object sender,

{
// Create a new Customer object when the user edits
// the row for new records.
this.customerInEdit = new Customer();
this.rowInEdit = this.dataGridView1.Rows.Count - 1;
}
6. Implemente um manipulador para o RowValidated evento que salva linhas novas

ou modificadas no armazenamento de dados.
Esse evento ocorre sempre que o usuário altera a linha atual.
C#
private void dataGridView1_RowValidated(object sender,

System.Windows.Forms.DataGridViewCellEventArgs e)
{
// Save row changes if any were made and release the edited
// Customer object if there is one.
if (e.RowIndex >= this.customers.Count &&
e.RowIndex != this.dataGridView1.Rows.Count - 1)
{
// Add the new Customer object to the data store.
this.customers.Add(this.customerInEdit);
this.customerInEdit = null;
this.rowInEdit = -1;
}
else if (this.customerInEdit != null &&
e.RowIndex < this.customers.Count)
{
// Save the modified Customer object in the data store.
this.customers[e.RowIndex] = this.customerInEdit;
}
else if (this.dataGridView1.ContainsFocus)
{
}
}
7. Implemente um manipulador para o RowDirtyStateNeeded evento que indica se o

CancelRowEdit evento ocorrerá quando o usuário sinalizar a reversão de linha
pressionando ESC duas vezes no modo de edição ou uma vez fora do modo de
edição.
Por padrão, CancelRowEdit ocorre após a reversão de linha quando todas as

células na linha atual foram modificadas, a menos que a
QuestionEventArgs.Response propriedade esteja definida true como no
RowDirtyStateNeeded manipulador de eventos. Esse evento é útil quando o
escopo da confirmação é determinado em tempo de execução.
C#
private void dataGridView1_RowDirtyStateNeeded(object sender,

System.Windows.Forms.QuestionEventArgs e)
{
if (!rowScopeCommit)
{
// In cell-level commit scope, indicate whether the value
// of the current cell has been modified.
e.Response = this.dataGridView1.IsCurrentCellDirty;
}
}
8. Implemente um manipulador para o CancelRowEdit evento que descarta os valores

do Customer objeto que representa a linha atual.
Esse evento ocorre quando o usuário sinaliza a reversão da linha pressionando ESC
duas vezes no modo de edição ou uma vez fora do modo de edição. Esse evento
não ocorrerá se nenhuma célula na linha atual tiver sido modificada ou se o valor
da QuestionEventArgs.Response propriedade tiver sido definido false como em
um RowDirtyStateNeeded manipulador de eventos.
C#
private void dataGridView1_CancelRowEdit(object sender,

{
if (this.rowInEdit == this.dataGridView1.Rows.Count - 2 &&
this.rowInEdit == this.customers.Count)
{
// If the user has canceled the edit of a newly created row,
// replace the corresponding Customer object with a new, empty
one.
}
else
{
// If the user has canceled the edit of an existing row,
// release the corresponding Customer object.
}
}
9. Implemente um manipulador para o UserDeletingRow evento que exclui um

objeto existente Customer do armazenamento de dados ou descarta um objeto
não salvo Customer que representa uma linha recém-criada.
Esse evento ocorre sempre que o usuário exclui uma linha clicando em um
cabeçalho de linha e pressionando a tecla DELETE.
C#
private void dataGridView1_UserDeletingRow(object sender,

System.Windows.Forms.DataGridViewRowCancelEventArgs e)
{
if (e.Row.Index < this.customers.Count)
{
// If the user has deleted an existing row, remove the
// corresponding Customer object from the data store.
this.customers.RemoveAt(e.Row.Index);
}
if (e.Row.Index == this.rowInEdit)
{
// If the user has deleted a newly created row, release
// the corresponding Customer object.
}
}
10. Implemente uma classe Customers simples para representar os itens de dados
usados por este exemplo de código.
C#

{
private String companyNameValue;
private String contactNameValue;
public Customer()
{
// Leave fields empty.
}
public Customer(String companyName, String contactName)

{
companyNameValue = companyName;
contactNameValue = contactName;
}
public String CompanyName

{
get
{
return companyNameValue;
}
set
{
companyNameValue = value;
}
}
public String ContactName

{
get
{
return contactNameValue;
}
set
{
contactNameValue = value;
}
}
}
esperada.

Você verá um DataGridView controle preenchido com três registros de clientes. É

possível modificar os valores de várias células em uma linha e pressionar ESC duas
vezes no modo de edição e uma vez fora do modo de edição para reverter a linha
inteira para seus valores originais. Quando você modifica, adiciona ou exclui linhas
no controle, objetos Customer no armazenamento de dados também são
modificados, adicionados ou excluídos.
Próximas etapas
Este aplicativo fornece uma compreensão básica dos eventos que você deve tratar para
implementar o DataGridView modo virtual no controle. É possível aprimorar esse
aplicativo básico de várias maneiras:
Implemente um armazenamento de dados que armazena em cache os valores de

um banco de dados externo. O cache deve recuperar e descartar valores conforme
necessário, de modo que ele contenha apenas o que é necessário para exibição
enquanto consome uma quantidade pequena de memória no computador cliente.
Ajuste o desempenho do armazenamento de dados dependendo de seus

requisitos. Por exemplo, talvez você queira compensar conexões de rede lentas em
vez de limitações de memória do computador cliente usando um tamanho de
cache maior e minimizando o número de consultas ao banco de dados.
Para obter mais informações armazenar em cache valores de um banco de dados

externo, consulte Como implementar o modo virtual com carregamento de dados Just-
In-Time no controle DataGridView dos Windows Forms.
Confira também
DataGridView
VirtualMode
CellValueNeeded
CellValuePushed
NewRowNeeded
RowValidated
RowDirtyStateNeeded
CancelRowEdit
UserDeletingRow
Windows Forms
Como: Implementar o modo virtual no controle DataGridView do Windows Forms
Como: Implementar o modo virtual no
Forms
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como gerenciar grandes conjuntos de dados

usando um DataGridView controle com sua VirtualMode propriedade definida como
true .
Para obter uma explicação completa deste exemplo de código, consulte Passo a passo:
implementando o modo virtual no controle DataGridView Windows Forms.
Exemplo
C#
using System;

{
// Declare an ArrayList to serve as the data store.

private System.Collections.ArrayList customers =
new System.Collections.ArrayList();
// Declare a Customer object to store data for a row being edited.

private Customer customerInEdit;
// Declare a variable to store the index of a row being edited.

// A value of -1 indicates that there is no row currently in edit.
private int rowInEdit = -1;
// Declare a variable to indicate the commit scope.

// Set this value to false to use cell-level commit scope.
private bool rowScopeCommit = true;
{
}
public Form1()
{
this.Text = "DataGridView virtual-mode demo (row-level commit
scope)";
}

{
// Enable virtual mode.
// Connect the virtual-mode events to event handlers.

this.dataGridView1.CellValuePushed += new
DataGridViewCellValueEventHandler(dataGridView1_CellValuePushed);
this.dataGridView1.NewRowNeeded += new
DataGridViewRowEventHandler(dataGridView1_NewRowNeeded);
this.dataGridView1.RowValidated += new
DataGridViewCellEventHandler(dataGridView1_RowValidated);
this.dataGridView1.RowDirtyStateNeeded += new
QuestionEventHandler(dataGridView1_RowDirtyStateNeeded);
this.dataGridView1.CancelRowEdit += new
QuestionEventHandler(dataGridView1_CancelRowEdit);
this.dataGridView1.UserDeletingRow += new
DataGridViewRowCancelEventHandler(dataGridView1_UserDeletingRow);

DataGridViewTextBoxColumn companyNameColumn = new
companyNameColumn.HeaderText = "Company Name";
companyNameColumn.Name = "Company Name";
DataGridViewTextBoxColumn contactNameColumn = new
contactNameColumn.HeaderText = "Contact Name";
contactNameColumn.Name = "Contact Name";
this.dataGridView1.Columns.Add(companyNameColumn);
this.dataGridView1.Columns.Add(contactNameColumn);
this.dataGridView1.AutoSizeColumnsMode =
DataGridViewAutoSizeColumnsMode.DisplayedCells;
// Add some sample entries to the data store.

"Bon app'", "Laurence Lebihan"));
"Bottom-Dollar Markets", "Elizabeth Lincoln"));
"B's Beverages", "Victoria Ashworth"));
// Set the row count, including the row for new records.
}

{
// If this is the row for new records, no values are needed.
if (e.RowIndex == this.dataGridView1.RowCount - 1) return;

painted.
if (e.RowIndex == rowInEdit)
{
}
else
{
customerTmp = (Customer)this.customers[e.RowIndex];
}
// Set the cell value to paint using the Customer object retrieved.
{
e.Value = customerTmp.CompanyName;
break;

e.Value = customerTmp.ContactName;
break;
}
}
private void dataGridView1_CellValuePushed(object sender,

{

edited.
if (e.RowIndex < this.customers.Count)
{
// If the user is editing a new row, create a new Customer
object.
this.customerInEdit ??= new Customer(
((Customer)this.customers[e.RowIndex]).CompanyName,
((Customer)this.customers[e.RowIndex]).ContactName);
this.rowInEdit = e.RowIndex;
}
else
{
}
// Set the appropriate Customer property to the cell value entered.

String newValue = e.Value as String;
{
customerTmp.CompanyName = newValue;
break;

customerTmp.ContactName = newValue;
break;
}
}
private void dataGridView1_NewRowNeeded(object sender,

{
// Create a new Customer object when the user edits
// the row for new records.
this.rowInEdit = this.dataGridView1.Rows.Count - 1;
}
private void dataGridView1_RowValidated(object sender,

System.Windows.Forms.DataGridViewCellEventArgs e)
{
// Save row changes if any were made and release the edited
// Customer object if there is one.
if (e.RowIndex >= this.customers.Count &&
e.RowIndex != this.dataGridView1.Rows.Count - 1)
{
// Add the new Customer object to the data store.
this.customers.Add(this.customerInEdit);
}
else if (this.customerInEdit != null &&
e.RowIndex < this.customers.Count)
{
// Save the modified Customer object in the data store.
this.customers[e.RowIndex] = this.customerInEdit;
}
else if (this.dataGridView1.ContainsFocus)
{
}
}
private void dataGridView1_RowDirtyStateNeeded(object sender,

{
if (!rowScopeCommit)
{
// In cell-level commit scope, indicate whether the value
// of the current cell has been modified.
e.Response = this.dataGridView1.IsCurrentCellDirty;
}
}
private void dataGridView1_CancelRowEdit(object sender,

{
if (this.rowInEdit == this.dataGridView1.Rows.Count - 2 &&
this.rowInEdit == this.customers.Count)
{
// If the user has canceled the edit of a newly created row,
// replace the corresponding Customer object with a new, empty
one.
}
else
{
// If the user has canceled the edit of an existing row,
// release the corresponding Customer object.
}
}
private void dataGridView1_UserDeletingRow(object sender,

System.Windows.Forms.DataGridViewRowCancelEventArgs e)
{
if (e.Row.Index < this.customers.Count)
{
// If the user has deleted an existing row, remove the
// corresponding Customer object from the data store.
this.customers.RemoveAt(e.Row.Index);
}
if (e.Row.Index == this.rowInEdit)
{
// If the user has deleted a newly created row, release
// the corresponding Customer object.
}
}
}

{
private String companyNameValue;
private String contactNameValue;
public Customer()
{
// Leave fields empty.
}
public Customer(String companyName, String contactName)

{
companyNameValue = companyName;
contactNameValue = contactName;
}
public String CompanyName

{
get
{
return companyNameValue;
}
set
{
companyNameValue = value;
}
}
public String ContactName

{
get
{
return contactNameValue;
}
set
{
contactNameValue = value;
}
}
}
Confira também
DataGridView
VirtualMode
CellValueNeeded
CellValuePushed
NewRowNeeded
RowValidated
RowDirtyStateNeeded
CancelRowEdit
UserDeletingRow
Windows Forms
Implementando o modo virtual com
carregamento de dados Just-In-Time no
Forms
Artigo • 02/06/2023
Um motivo para implementar o DataGridView modo virtual no controle é recuperar

dados somente conforme necessário. Isso é chamado de carregamento de dados Just-In-
Time.
Se estiver trabalhando com uma tabela muito grande em um banco de dados remoto,
por exemplo, talvez você queira evitar atrasos de inicialização recuperando somente os
dados necessários para exibição e recuperando dados adicionais somente quando o
usuário rolar novas linhas para a área de exibição. Se os computadores cliente que estão
executando seu aplicativo tiverem uma quantidade limitada de memória disponível para
armazenar dados, você também pode querer descartar dados não utilizados quando
recuperar novos valores do banco de dados.
As seções a seguir descrevem como usar um DataGridView controle com um cache just-
in-time.
Para copiar o código neste tópico como uma única listagem, consulte Como
implementar o modo virtual com carregamento de dados Just-In-Time no controle
O formulário
O exemplo de código a seguir define um formulário que contém um controle somente
DataGridView leitura que interage com um Cache objeto por meio de um
CellValueNeeded manipulador de eventos. O objeto Cache gerencia os valores
armazenados localmente e usa um objeto DataRetriever para recuperar valores da
tabela Orders do banco de dados de exemplo Northwind. O DataRetriever objeto, que
implementa a IDataPageRetriever interface exigida pela Cache classe, também é usado
para inicializar as DataGridView linhas e colunas de controle.
Os tipos IDataPageRetriever , DataRetriever e Cache são descritos mais adiante neste

tópico.
７ Observação

C#
using System;
using System.Data;
public class VirtualJustInTimeDemo : System.Windows.Forms.Form

{
private Cache memoryCache;

private string connectionString =
"Initial Catalog=NorthWind;Data Source=localhost;" +
"Integrated Security=SSPI;Persist Security Info=False";
private string table = "Orders";

{
this.Text = "DataGridView virtual-mode just-in-time demo";
// Complete the initialization of the DataGridView.

this.dataGridView1.ReadOnly = true;
this.dataGridView1.AllowUserToOrderColumns = false;
// Create a DataRetriever and use it to create a Cache object

// and to initialize the DataGridView columns and rows.
try
{
DataRetriever retriever =
new DataRetriever(connectionString, table);
memoryCache = new Cache(retriever, 16);
foreach (DataColumn column in retriever.Columns)
{
dataGridView1.Columns.Add(
column.ColumnName, column.ColumnName);
}
this.dataGridView1.RowCount = retriever.RowCount;
}
{
MessageBox.Show("Connection could not be established. " +
"Verify that the connection string is valid.");
Application.Exit();
}
// Adjust the column widths based on the displayed values.

DataGridViewAutoSizeColumnsMode.DisplayedCells);
base.OnLoad(e);
}

DataGridViewCellValueEventArgs e)
{
e.Value = memoryCache.RetrieveElement(e.RowIndex, e.ColumnIndex);
}
{
Application.Run(new VirtualJustInTimeDemo());
}
}
A Interface IDataPageRetriever
O exemplo de código a seguir define a interface IDataPageRetriever , que é
implementada pela classe DataRetriever . O único método declarado nessa interface é o
método SupplyPageOfData , que requer um índice de linhas inicial e uma contagem do
número de linhas em uma única página de dados. Esses valores são usados pelo
implementador para recuperar um subconjunto de dados de uma fonte de dados.
Um objeto Cache usa uma implementação dessa interface durante a construção para
carregar duas páginas iniciais de dados. Sempre que um valor fora do cache é
necessário, o cache descarta uma dessas páginas e solicita uma nova página que
contém o valor do IDataPageRetriever .
C#
public interface IDataPageRetriever

{
DataTable SupplyPageOfData(int lowerPageBoundary, int rowsPerPage);
}
A classe DataRetriever
O exemplo de código a seguir define a classe DataRetriever , que implementa a
interface IDataPageRetriever para recuperar páginas de dados de um servidor. A
DataRetriever classe também fornece Columns e RowCount propriedades, que o
DataGridView controle usa para criar as colunas necessárias e para adicionar o número
apropriado de linhas vazias à Rows coleção. Adicionar as linhas vazias é necessário para
que o controle se comporte como se contivesse todos os dados na tabela. Isso significa
que a caixa de rolagem na barra de rolagem terá o tamanho apropriado e o usuário será
capaz de acessar qualquer linha na tabela. As linhas são preenchidas pelo
CellValueNeeded manipulador de eventos somente quando são roladas para exibição.
C#
public class DataRetriever : IDataPageRetriever

{
private string tableName;
private SqlCommand command;
public DataRetriever(string connectionString, string tableName)

{
connection.Open();
command = connection.CreateCommand();
this.tableName = tableName;
}
private int rowCountValue = -1;
public int RowCount

{
get
{
// Return the existing value if it has already been determined.
if (rowCountValue != -1)
{
return rowCountValue;
}
// Retrieve the row count from the database.

command.CommandText = "SELECT COUNT(*) FROM " + tableName;
rowCountValue = (int)command.ExecuteScalar();
}
}
private DataColumnCollection columnsValue;
public DataColumnCollection Columns

{
get
{
if (columnsValue != null)
{
return columnsValue;
}
// Retrieve the column information from the database.

command.CommandText = "SELECT * FROM " + tableName;
SqlDataAdapter adapter = new SqlDataAdapter();
adapter.SelectCommand = command;
DataTable table = new DataTable();
table.Locale =
adapter.FillSchema(table, SchemaType.Source);
columnsValue = table.Columns;
}
}
private string commaSeparatedListOfColumnNamesValue = null;
private string CommaSeparatedListOfColumnNames

{
get
{
if (commaSeparatedListOfColumnNamesValue != null)
{
return commaSeparatedListOfColumnNamesValue;
}
// Store a list of column names for use in the

// SupplyPageOfData method.
System.Text.StringBuilder commaSeparatedColumnNames =
bool firstColumn = true;
foreach (DataColumn column in Columns)
{
if (!firstColumn)
{
commaSeparatedColumnNames.Append(", ");
}
commaSeparatedColumnNames.Append(column.ColumnName);
firstColumn = false;
}
commaSeparatedListOfColumnNamesValue =
commaSeparatedColumnNames.ToString();
}
}
// Declare variables to be reused by the SupplyPageOfData method.

private string columnToSortBy;
private SqlDataAdapter adapter = new SqlDataAdapter();
public DataTable SupplyPageOfData(int lowerPageBoundary, int

rowsPerPage)
{
// Store the name of the ID column. This column must contain unique
// values so the SQL below will work properly.
columnToSortBy ??= this.Columns[0].ColumnName;
if (!this.Columns[columnToSortBy].Unique)
{
throw new InvalidOperationException(String.Format(
"Column {0} must contain unique values.", columnToSortBy));
}
// Retrieve the specified number of rows from the database, starting

// with the row specified by the lowerPageBoundary parameter.
command.CommandText = "Select Top " + rowsPerPage + " " +
CommaSeparatedListOfColumnNames + " From " + tableName +
" WHERE " + columnToSortBy + " NOT IN (SELECT TOP " +
lowerPageBoundary + " " + columnToSortBy + " From " +
tableName + " Order By " + columnToSortBy +
") Order By " + columnToSortBy;

table.Locale = System.Globalization.CultureInfo.InvariantCulture;
adapter.Fill(table);
return table;
}
}
A classe Cache
O exemplo de código a seguir define a classe Cache , que gerencia duas páginas de
dados preenchidas por meio de uma implementação de IDataPageRetriever . A Cache
classe define uma estrutura interna DataPage , que contém um DataTable para
armazenar os valores em uma única página de cache e que calcula os índices de linha
que representam os limites superior e inferior da página.
A classe Cache carrega duas páginas de dados no momento da construção. Sempre que
o CellValueNeeded evento solicita um valor, o Cache objeto determina se o valor está
disponível em uma de suas duas páginas e, se for o caso, o retorna. Se o valor não
estiver disponível localmente, o objeto Cache determinará qual das duas páginas está
mais distante das linhas exibidas atualmente e substituirá a página por uma nova, que
contém o valor solicitado que, então, é retornado.
Supondo que o número de linhas em uma página de dados seja igual ao número de
linhas que podem ser exibidas na tela de uma só vez, esse modelo permite que os
usuários que estão percorrendo a tabela por paginação retornem para a página exibida
mais recentemente.
C#
public class Cache

{
private static int RowsPerPage;
// Represents one page of data.

public struct DataPage
{
public DataTable table;
private int lowestIndexValue;
private int highestIndexValue;
public DataPage(DataTable table, int rowIndex)

{
this.table = table;
lowestIndexValue = MapToLowerBoundary(rowIndex);
highestIndexValue = MapToUpperBoundary(rowIndex);
System.Diagnostics.Debug.Assert(lowestIndexValue >= 0);
System.Diagnostics.Debug.Assert(highestIndexValue >= 0);
}
public int LowestIndex

{
get
{
return lowestIndexValue;
}
}
public int HighestIndex

{
get
{
return highestIndexValue;
}
}
public static int MapToLowerBoundary(int rowIndex)

{
// Return the lowest index of a page containing the given index.
return (rowIndex / RowsPerPage) * RowsPerPage;
}
private static int MapToUpperBoundary(int rowIndex)

{
// Return the highest index of a page containing the given
index.
return MapToLowerBoundary(rowIndex) + RowsPerPage - 1;
}
}
private DataPage[] cachePages;

private IDataPageRetriever dataSupply;
public Cache(IDataPageRetriever dataSupplier, int rowsPerPage)

{
dataSupply = dataSupplier;
Cache.RowsPerPage = rowsPerPage;
LoadFirstTwoPages();
}
// Sets the value of the element parameter if the value is in the cache.
private bool IfPageCached_ThenSetElement(int rowIndex,
int columnIndex, ref string element)
{
if (IsRowCachedInPage(0, rowIndex))
{
element = cachePages[0].table
.Rows[rowIndex % RowsPerPage][columnIndex].ToString();
return true;
}
else if (IsRowCachedInPage(1, rowIndex))
{
return true;
}
return false;
}
public string RetrieveElement(int rowIndex, int columnIndex)

{
string element = null;
if (IfPageCached_ThenSetElement(rowIndex, columnIndex, ref element))

{
return element;
}
else
{
return RetrieveData_CacheIt_ThenReturnElement(
rowIndex, columnIndex);
}
}
private void LoadFirstTwoPages()

{
cachePages = new DataPage[]{
new DataPage(dataSupply.SupplyPageOfData(
DataPage.MapToLowerBoundary(0), RowsPerPage), 0),
DataPage.MapToLowerBoundary(RowsPerPage),
RowsPerPage), RowsPerPage)};
}
private string RetrieveData_CacheIt_ThenReturnElement(

int rowIndex, int columnIndex)
{
// Retrieve a page worth of data containing the requested value.
DataTable table = dataSupply.SupplyPageOfData(
DataPage.MapToLowerBoundary(rowIndex), RowsPerPage);
// Replace the cached page furthest from the requested cell

// with a new page containing the newly retrieved data.
cachePages[GetIndexToUnusedPage(rowIndex)] = new DataPage(table,
rowIndex);
return RetrieveElement(rowIndex, columnIndex);

}
// Returns the index of the cached page most distant from the given
index
// and therefore least likely to be reused.
private int GetIndexToUnusedPage(int rowIndex)
{
if (rowIndex > cachePages[0].HighestIndex &&
rowIndex > cachePages[1].HighestIndex)
{
int offsetFromPage0 = rowIndex - cachePages[0].HighestIndex;
if (offsetFromPage0 < offsetFromPage1)
{
return 1;
}
return 0;
}
else
{
int offsetFromPage0 = cachePages[0].LowestIndex - rowIndex;
{
return 1;
}
return 0;
}
}
// Returns a value indicating whether the given row index is contained

// in the given DataPage.
private bool IsRowCachedInPage(int pageNumber, int rowIndex)
{
return rowIndex <= cachePages[pageNumber].HighestIndex &&
rowIndex >= cachePages[pageNumber].LowestIndex;
}
}
Considerações adicionais
Os exemplos de código anteriores são fornecidos como uma demonstração de
carregamento de dados Just-In-Time. Você precisará modificar o código de acordo com
suas necessidades alcançar a máxima eficiência. No mínimo, você precisará escolher um
valor apropriado para o número de linhas por página de dados no cache. Esse valor é
passado para o construtor Cache . O número de linhas por página não deve ser menor
do que o número de linhas que podem ser exibidas simultaneamente em seu
DataGridView controle.
Para obter melhores resultados, você precisará realizar testes de desempenho e testes
de usabilidade para determinar os requisitos do sistema e de seus usuários. Os diversos
fatores que você precisará levar em consideração incluem a quantidade de memória nas
máquinas cliente que executam seu aplicativo, a largura de banda disponível da
conexão de rede usada e a latência do servidor usado. A largura de banda e a latência
devem ser determinadas em momentos de pico.
Para melhorar o desempenho de rolagem do seu aplicativo, você pode aumentar a

quantidade de dados armazenados localmente. Para melhorar o tempo de inicialização,
no entanto, você deve evitar o carregamento de muitos dados inicialmente. Talvez você
queira modificar a classe Cache para aumentar o número de páginas de dados que ela
pode armazenar. Usar mais páginas de dados pode melhorar a eficiência de rolagem,
mas você precisará determinar o número ideal de linhas em uma página de dados,
dependendo da largura de banda disponível e da latência do servidor. Com páginas
menores, o servidor será acessado com mais frequência, mas levará menos tempo para
retornar os dados solicitados. Se a latência for mais importante que a largura de banda,
talvez você queira usar páginas de dados maiores.
Confira também
DataGridView
VirtualMode
Windows Forms
Windows Forms
Como: Implementar o modo virtual com carregamento de dados Just-In-Time no
Como: Implementar o modo virtual com
carregamento de dados Just-In-Time no
Forms
Artigo • 02/06/2023
O exemplo de código a seguir mostra como usar o DataGridView modo virtual no

controle com um cache de dados que carrega dados de um servidor somente quando
necessário. Este exemplo é descrito em detalhes na implementação do modo virtual
com o carregamento de dados just-in-time no controle Windows Forms DataGridView.
Exemplo
C#
using System;
using System.Data;
public class VirtualJustInTimeDemo : System.Windows.Forms.Form

{
private Cache memoryCache;

private string connectionString =
"Initial Catalog=NorthWind;Data Source=localhost;" +
"Integrated Security=SSPI;Persist Security Info=False";
private string table = "Orders";

{
this.Text = "DataGridView virtual-mode just-in-time demo";
// Complete the initialization of the DataGridView.

this.dataGridView1.AllowUserToOrderColumns = false;
// Create a DataRetriever and use it to create a Cache object

// and to initialize the DataGridView columns and rows.
try
{
DataRetriever retriever =
new DataRetriever(connectionString, table);
memoryCache = new Cache(retriever, 16);
foreach (DataColumn column in retriever.Columns)
{
dataGridView1.Columns.Add(
column.ColumnName, column.ColumnName);
}
this.dataGridView1.RowCount = retriever.RowCount;
}
{
MessageBox.Show("Connection could not be established. " +
"Verify that the connection string is valid.");
Application.Exit();
}
// Adjust the column widths based on the displayed values.

DataGridViewAutoSizeColumnsMode.DisplayedCells);
base.OnLoad(e);
}

DataGridViewCellValueEventArgs e)
{
e.Value = memoryCache.RetrieveElement(e.RowIndex, e.ColumnIndex);
}
{
Application.Run(new VirtualJustInTimeDemo());
}
}
public interface IDataPageRetriever

{
DataTable SupplyPageOfData(int lowerPageBoundary, int rowsPerPage);
}
public class DataRetriever : IDataPageRetriever
{
private string tableName;
private SqlCommand command;
public DataRetriever(string connectionString, string tableName)

{
connection.Open();
command = connection.CreateCommand();
this.tableName = tableName;
}
private int rowCountValue = -1;
public int RowCount

{
get
{
if (rowCountValue != -1)
{
}
// Retrieve the row count from the database.

command.CommandText = "SELECT COUNT(*) FROM " + tableName;
rowCountValue = (int)command.ExecuteScalar();
}
}
private DataColumnCollection columnsValue;
public DataColumnCollection Columns

{
get
{
if (columnsValue != null)
{
}
// Retrieve the column information from the database.

command.CommandText = "SELECT * FROM " + tableName;
SqlDataAdapter adapter = new SqlDataAdapter();
table.Locale =
adapter.FillSchema(table, SchemaType.Source);
columnsValue = table.Columns;
}
}
private string commaSeparatedListOfColumnNamesValue = null;
private string CommaSeparatedListOfColumnNames

{
get
{
if (commaSeparatedListOfColumnNamesValue != null)
{
}
// Store a list of column names for use in the

// SupplyPageOfData method.
System.Text.StringBuilder commaSeparatedColumnNames =
bool firstColumn = true;
foreach (DataColumn column in Columns)
{
if (!firstColumn)
{
commaSeparatedColumnNames.Append(", ");
}
commaSeparatedColumnNames.Append(column.ColumnName);
firstColumn = false;
}
commaSeparatedListOfColumnNamesValue =
commaSeparatedColumnNames.ToString();
}
}
// Declare variables to be reused by the SupplyPageOfData method.

private string columnToSortBy;
private SqlDataAdapter adapter = new SqlDataAdapter();
public DataTable SupplyPageOfData(int lowerPageBoundary, int

rowsPerPage)
{
// Store the name of the ID column. This column must contain unique
// values so the SQL below will work properly.
columnToSortBy ??= this.Columns[0].ColumnName;
if (!this.Columns[columnToSortBy].Unique)
{
throw new InvalidOperationException(String.Format(
"Column {0} must contain unique values.", columnToSortBy));
}
// Retrieve the specified number of rows from the database, starting

// with the row specified by the lowerPageBoundary parameter.
command.CommandText = "Select Top " + rowsPerPage + " " +
CommaSeparatedListOfColumnNames + " From " + tableName +
" WHERE " + columnToSortBy + " NOT IN (SELECT TOP " +
lowerPageBoundary + " " + columnToSortBy + " From " +
tableName + " Order By " + columnToSortBy +
") Order By " + columnToSortBy;

table.Locale = System.Globalization.CultureInfo.InvariantCulture;
adapter.Fill(table);
return table;
}
}
public class Cache

{
private static int RowsPerPage;
// Represents one page of data.

public struct DataPage
{
public DataTable table;
private int lowestIndexValue;
private int highestIndexValue;
public DataPage(DataTable table, int rowIndex)

{
this.table = table;
lowestIndexValue = MapToLowerBoundary(rowIndex);
highestIndexValue = MapToUpperBoundary(rowIndex);
System.Diagnostics.Debug.Assert(lowestIndexValue >= 0);
System.Diagnostics.Debug.Assert(highestIndexValue >= 0);
}
public int LowestIndex

{
get
{
return lowestIndexValue;
}
}
public int HighestIndex

{
get
{
return highestIndexValue;
}
}
public static int MapToLowerBoundary(int rowIndex)

{
// Return the lowest index of a page containing the given index.
return (rowIndex / RowsPerPage) * RowsPerPage;
}
private static int MapToUpperBoundary(int rowIndex)
{
// Return the highest index of a page containing the given
index.
return MapToLowerBoundary(rowIndex) + RowsPerPage - 1;
}
}
private DataPage[] cachePages;

private IDataPageRetriever dataSupply;
public Cache(IDataPageRetriever dataSupplier, int rowsPerPage)

{
dataSupply = dataSupplier;
Cache.RowsPerPage = rowsPerPage;
LoadFirstTwoPages();
}
// Sets the value of the element parameter if the value is in the cache.
private bool IfPageCached_ThenSetElement(int rowIndex,
int columnIndex, ref string element)
{
if (IsRowCachedInPage(0, rowIndex))
{
return true;
}
else if (IsRowCachedInPage(1, rowIndex))
{
return true;
}
return false;
}
public string RetrieveElement(int rowIndex, int columnIndex)

{
string element = null;
if (IfPageCached_ThenSetElement(rowIndex, columnIndex, ref element))

{
return element;
}
else
{
return RetrieveData_CacheIt_ThenReturnElement(
rowIndex, columnIndex);
}
}
private void LoadFirstTwoPages()

{
cachePages = new DataPage[]{
DataPage.MapToLowerBoundary(0), RowsPerPage), 0),
DataPage.MapToLowerBoundary(RowsPerPage),
RowsPerPage), RowsPerPage)};
}
private string RetrieveData_CacheIt_ThenReturnElement(

int rowIndex, int columnIndex)
{
// Retrieve a page worth of data containing the requested value.
DataTable table = dataSupply.SupplyPageOfData(
DataPage.MapToLowerBoundary(rowIndex), RowsPerPage);
// Replace the cached page furthest from the requested cell

// with a new page containing the newly retrieved data.
cachePages[GetIndexToUnusedPage(rowIndex)] = new DataPage(table,
rowIndex);
return RetrieveElement(rowIndex, columnIndex);

}
// Returns the index of the cached page most distant from the given
index
// and therefore least likely to be reused.
private int GetIndexToUnusedPage(int rowIndex)
{
if (rowIndex > cachePages[0].HighestIndex &&
rowIndex > cachePages[1].HighestIndex)
{
{
return 1;
}
return 0;
}
else
{
{
return 1;
}
return 0;
}
}
// Returns a value indicating whether the given row index is contained

// in the given DataPage.
private bool IsRowCachedInPage(int pageNumber, int rowIndex)
{
return rowIndex <= cachePages[pageNumber].HighestIndex &&
rowIndex >= cachePages[pageNumber].LowestIndex;
}
}
Referências aos assemblies System, System.Data, System.Xml e

Acesso a um servidor com o banco de dados de exemplo northwind SQL Server

instalado.

Confira também
DataGridView
VirtualMode
CellValueNeeded
Comportamento padrão de teclado e
mouse com o controle DataGridView
Artigo • 21/06/2023
As tabelas a seguir descrevem como os usuários podem interagir com o DataGridView

controle por meio de um teclado e um mouse.
７ Observação
Para personalizar o comportamento do teclado, você pode lidar com eventos de

teclado padrão, como KeyDown. No modo de edição, no entanto, o controle de
edição hospedado recebe a entrada do teclado e os eventos de teclado não
ocorrem para o DataGridView controle. Para lidar com eventos de controle de
edição, anexe seus manipuladores ao controle de edição em um
EditingControlShowing manipulador de eventos. Como alternativa, você pode
personalizar o comportamento do teclado em uma DataGridView subclasse
substituindo os ProcessDialogKey métodos e ProcessDataGridViewKey .
Manipulação de teclado padrão
Teclas básicas de navegação e de entrada
Tecla ou Descrição
combinação de
teclas
Seta para baixo Move o foco para a célula diretamente abaixo da célula atual. Se o foco
estiver na última linha, não fará nada.
Seta para a Move o foco para a célula anterior na linha. Se o foco estiver na primeira
esquerda
célula na linha, não fará nada.
Seta para a Move o foco para a próxima célula na linha. Se o foco estiver na última
direita
célula na linha, não fará nada.
Seta para cima Move o foco para a célula diretamente acima da célula atual. Se o foco
estiver na primeira linha, não fará nada.
Início Move o foco para a primeira célula na linha atual.
End Move o foco até a última célula na linha atual.

combinação de
teclas
Página para Rola o controle para baixo pelo número de linhas que são totalmente
baixo
exibidas. Move o foco para a última linha totalmente exibida sem alterar as
colunas.
Página para cima Rola o controle para cima pelo número de linhas que são totalmente
exibidas. Move o foco para a primeira linha exibida sem alterar as colunas.
Guia Se o valor da StandardTab propriedade for false , moverá o foco para a

próxima célula na linha atual. Se o foco já estiver na última célula da linha, o
foco moverá para a primeira célula da linha seguinte. Se o foco estiver na
última célula no controle, moverá o foco para o próximo controle na ordem
de tabulação do contêiner pai.
Se o valor da StandardTab propriedade for true , moverá o foco para o

próximo controle na ordem de tabulação do contêiner pai.
Shift + Tab Se o valor da StandardTab propriedade for false , moverá o foco para a
célula anterior na linha atual. Se o foco já estiver na primeira célula da linha,
moverá o foco para a última célula da linha anterior. Se o foco estiver na
primeira célula no controle, moverá o foco para o controle anterior na
ordem de tabulação do contêiner pai.
Se o valor da StandardTab propriedade for true , moverá o foco para o

controle anterior na ordem de tabulação do contêiner pai.
Ctrl + Tab Se o valor da StandardTab propriedade for false , moverá o foco para o
próximo controle na ordem de tabulação do contêiner pai.
Se o valor da StandardTab propriedade for true , moverá o foco para a

próxima célula na linha atual. Se o foco já estiver na última célula da linha, o
foco moverá para a primeira célula da linha seguinte. Se o foco estiver na
última célula no controle, moverá o foco para o próximo controle na ordem
de tabulação do contêiner pai.
Ctrl + Shift + Se o valor da StandardTab propriedade for false , moverá o foco para o
Tab controle anterior na ordem de tabulação do contêiner pai.
Se o valor da StandardTab propriedade for true , moverá o foco para a

célula anterior na linha atual. Se o foco já estiver na primeira célula da linha,
moverá o foco para a última célula da linha anterior. Se o foco estiver na
primeira célula no controle, moverá o foco para o controle anterior na
ordem de tabulação do contêiner pai.
Ctrl + Seta Move o foco para a célula mais distante na direção da seta.
Ctrl + Home Move o foco para a primeira célula no controle.

combinação de
teclas
Ctrl + End Move o foco para a última célula no controle.
Ctrl + O mesmo que Page down ou Page up .

Página para
baixo/para cima
F2 Coloca a célula atual no modo de edição da célula se o valor da EditMode

propriedade for EditOnF2 ou EditOnKeystrokeOrF2.
F3 Classifica a coluna atual se o valor da DataGridViewColumn.SortMode

propriedade for Automatic. É o mesmo que clicar no cabeçalho da coluna
atual. Disponível desde o .NET Framework 4.7.2. Para habilitar esse recurso,
os aplicativos devem ter como destino .NET Framework 4.7.2 ou versões
posteriores ou optar explicitamente por melhorias de acessibilidade usando
opções AppContext.
F4 Se a célula atual for , DataGridViewComboBoxCellcolocará a célula no modo

de edição e exibirá a lista suspensa.
Alt + Se a célula atual for , DataGridViewComboBoxCellcolocará a célula no modo

Seta para de edição e exibirá a lista suspensa.
cima/seta para
baixo
Alt + Aumenta ou diminui a largura da coluna da célula atual.

Seta para a
esquerda/direita
Space Se a célula atual for , DataGridViewButtonCellDataGridViewLinkCellou

DataGridViewCheckBoxCell, gerará os CellClick eventos e CellContentClick .
Se a célula atual for um DataGridViewButtonCell, também pressionará o
botão. Se a célula atual for um DataGridViewCheckBoxCell, também alterará
o estado marcar.
Enter Confirma as alterações feitas na célula e na linha atuais e move o foco para a
célula diretamente abaixo da célula atual. Se o foco estiver na última linha,
confirmará as alterações sem mover o foco.
Esc Se o controle estiver no modo de edição, cancelará a edição. Se o controle

não estiver no modo de edição, reverte as alterações que foram feitas na
linha atual se o controle estiver associado a uma fonte de dados que dá
suporte à edição ou se o modo virtual tiver sido implementado com escopo
de confirmação de nível de linha.
Backspace Exclui o caractere antes do ponto de inserção ao editar uma célula.
Excluir Exclui o caractere após o ponto de inserção ao editar uma célula.

combinação de
teclas
CTRL + ENTER Confirma as alterações na célula atual sem mover o foco. Também confirma
as alterações na linha atual se o controle estiver associado a uma fonte de
dados que dá suporte à edição ou se o modo virtual tiver sido
implementado com escopo de confirmação de nível de linha.
CTRL + 0 Insere um DBNull.Value valor na célula atual se a célula puder ser editada.
Por padrão, o valor de exibição de um DBNull valor de célula é o valor da
NullValue propriedade do DataGridViewCellStyle em vigor para a célula
atual.
Chaves de seleção
Se a MultiSelect propriedade estiver definida false como e a SelectionMode
propriedade estiver definida CellSelectcomo , alterar a célula atual usando as chaves de
navegação alterará a seleção para a nova célula. As teclas Shift , Ctrl e Alt não
afetam esse comportamento.
Se o SelectionMode estiver definido como RowHeaderSelect ou ColumnHeaderSelect, o

mesmo comportamento ocorrerá, mas com as adições a seguir.
Tecla ou combinação de Descrição

teclas
Shift + Seleciona a linha ou a coluna inteira (o mesmo que clicar no

Barra de espaços cabeçalho da linha ou da coluna).
tecla de navegação ( Se uma linha ou coluna inteira estiver selecionada, a alteração da

tecla de direção , célula atual para uma nova linha ou coluna moverá a seleção para
Página para cima/para a nova linha ou coluna inteira (dependendo do modo de seleção).
baixo
, Início , Fim )
Se MultiSelect estiver definido como false e SelectionMode estiver definido

FullRowSelect como ou FullColumnSelect, alterar a célula atual para uma nova linha ou
coluna usando o teclado moverá a seleção para a nova linha ou coluna completa. As
teclas Shift , Ctrl e Alt não afetam esse comportamento.
Se MultiSelect estiver definido como true , o comportamento de navegação não será

alterado, mas navegar com o teclado enquanto pressiona Shift (incluindo Ctrl +
Shift ) modificará uma seleção de várias células. Antes de iniciar a navegação, o
controle marca a célula atual como uma célula de âncora. Quando você navega
enquanto pressiona Shift , a seleção inclui todas as células entre a célula de âncora e a
célula atual. As outras células no controle permanecerão selecionadas se já tiverem sido
selecionadas, mas poderão ficar não selecionadas se a navegação do teclado colocá-las
temporariamente entre a célula âncora e a célula atual.
Se MultiSelect estiver definido como true e SelectionMode for definido FullRowSelect

como ou FullColumnSelect, o comportamento da célula de âncora e da célula atual será
o mesmo, mas apenas linhas ou colunas completas serão selecionadas ou não
selecionadas.
Manipulação padrão do mouse
Manipulação básica do mouse
７ Observação
Clicar em uma célula com o botão esquerdo do mouse sempre altera a célula atual.
Clicar em uma célula com o botão direito do mouse abre um menu de atalho,
quando disponível.
Ação do mouse Descrição
Botão esquerdo do mouse para Torna a célula clicada a célula atual e gera o
baixo DataGridView.CellMouseDown evento.
Botão esquerdo do mouse para Gera o DataGridView.CellMouseUp evento

cima
Clique com o botão esquerdo do Gera os DataGridView.CellClick eventos e

mouse DataGridView.CellMouseClick
Botão esquerdo do mouse para Se a DataGridView.AllowUserToOrderColumns propriedade

baixo e arrastar em uma célula de for true , moverá a coluna para que ela possa ser removida
cabeçalho de coluna para uma nova posição.
Seleção de mouse
Nenhum comportamento de seleção está associado com o botão do meio ou botão de
rolagem do mouse.
Se a MultiSelect propriedade estiver definida como false e a SelectionMode

propriedade estiver definida como CellSelect, o comportamento a seguir ocorrerá.
Ação do Descrição
mouse
Clique Selecionará apenas a célula atual se o usuário clicar em uma célula. Nenhum
comportamento de seleção se o usuário clicar em um cabeçalho de linha ou de
coluna.
Clique com o Exibe um menu de atalho, se estiver disponível.

botão direito
em
O mesmo comportamento ocorre quando o SelectionMode é definido RowHeaderSelect

como ou ColumnHeaderSelect, exceto que, dependendo do modo de seleção, clicar em
um cabeçalho de linha ou coluna selecionará a linha ou coluna completa e definirá a
célula atual como a primeira célula na linha ou coluna.
Se SelectionMode estiver definido como FullRowSelect ou FullColumnSelect, clicar em

qualquer célula em uma linha ou coluna selecionará a linha ou coluna completa.
Se MultiSelect estiver definido como true , clicar em uma célula enquanto pressiona
Ctrl ou Shift modificará uma seleção de várias células.
Quando você clica em uma célula enquanto pressiona Ctrl , a célula altera seu estado
de seleção enquanto todas as outras células mantêm o estado de seleção atual.
Quando você clica em uma célula ou em uma série de células enquanto pressiona Shift
, a seleção inclui todas as células entre a célula atual e uma célula âncora localizada na
posição da célula atual antes do primeiro clique. Quando você clica e arrasta o ponteiro
por várias células, a célula âncora é a célula clicada no início da operação de arrastar. Os
cliques subsequentes ao pressionar Shift alteram a célula atual, mas não a célula de
âncora. As outras células no controle permanecerão selecionadas se já tiverem sido
selecionadas, mas poderão ficar não selecionadas se a navegação do mouse colocá-las
temporariamente entre a célula âncora e a célula atual.
Se MultiSelect estiver definido true como e SelectionMode for definido

RowHeaderSelect como ou ColumnHeaderSelect, clicar em um cabeçalho de linha ou
coluna (dependendo do modo de seleção) ao pressionar Shift modificará uma seleção
existente de linhas ou colunas completas se essa seleção existir. Caso contrário, isso
limpará a seleção e iniciará uma nova seleção de colunas ou linhas inteiras. Clicar em um
cabeçalho de linha ou coluna ao pressionar Ctrl , no entanto, adicionará ou removerá a
linha ou coluna clicada da seleção atual sem modificar a seleção atual.
Se MultiSelect estiver definido true como e SelectionMode estiver definido

FullRowSelect como ou FullColumnSelect, clicar em uma célula enquanto pressiona
Shift ou Ctrl se comportará da mesma maneira, exceto que apenas linhas e colunas
completas serão afetadas.
Confira também
DataGridView
Diferenças entre os controles
DataGridView e DataGrid dos Windows
Forms
Artigo • 02/06/2023
O DataGridView controle é um novo controle que substitui o DataGrid controle . O

DataGridView controle fornece vários recursos básicos e avançados que estão ausentes
no DataGrid controle. Além disso, a arquitetura do controle DataGridView torna muito
mais fácil estender e personalizar do que o DataGrid controle.
A tabela a seguir descreve alguns dos principais recursos disponíveis no controle

DataGridView que estão ausentes do DataGrid controle.
Recurso de Descrição
controle
DataGridView
Vários tipos de O DataGridView controle fornece tipos de coluna mais integrados do que o
coluna DataGrid controle . Esses tipos de coluna atendem às necessidades dos
cenários mais comuns, mas também são mais fáceis de estender ou substituir
do que os tipos de coluna no DataGrid controle. Para obter mais informações,
consulte Tipos de coluna no controle DataGridView dos Windows Forms.
Várias maneiras O DataGrid controle está limitado a exibir dados de uma fonte de dados
de exibir dados externa. No DataGridView entanto, o controle pode exibir dados não
vinculados armazenados no controle, dados de uma fonte de dados vinculada
ou dados vinculados e não vinculados. Você também pode implementar o
modo virtual no controle DataGridView para fornecer gerenciamento de dados
personalizado. Para obter mais informações, consulte Modos de exibição dos
dados no controle DataGridView dos Windows Forms.
Várias maneiras O DataGridView controle fornece muitas propriedades e eventos que

de personalizar permitem especificar como os dados são formatados e exibidos. Por exemplo,
a exibição de você pode alterar a aparência de células, linhas e colunas dependendo dos
dados dados que elas contêm ou pode substituir os dados de um tipo de dados por
dados equivalente de outro tipo. Para obter mais informações, consulte
Formatação de dados no controle DataGridView dos Windows Forms.
Várias opções O DataGridView controle permite que você trabalhe com componentes de
para alterar o grade individuais de várias maneiras. Por exemplo, você pode congelar linhas e
comportamento colunas para evitar que elas rolem; ocultar linhas, colunas e cabeçalhos; alterar
e a aparência o modo como os tamanhos de linha, coluna e cabeçalho são ajustados; alterar
de célula, linha, a maneira como os usuários fazem seleções; e fornecer Dicas de Ferramentas e
coluna e menus de atalho para células, linhas e colunas individuais.
cabeçalho
O DataGrid controle é mantido para compatibilidade com backward e para
necessidades especiais. Para quase todas as finalidades, você deve usar o DataGridView
controle . O único recurso disponível DataGrid no controle que não está disponível no
controle é a DataGridView exibição hierárquica de informações de duas tabelas
relacionadas em um único controle. Você deve usar dois controles DataGridView para
exibir informações de duas tabelas que estão em uma relação mestre/detalhes.
Atualizando para o controle DataGridView

Se você tiver aplicativos DataGrid existentes que usam o controle em um cenário
simples de limite de dados sem personalizações, poderá simplesmente substituir o
controle antigo pelo novo controle. Ambos os controles usam a arquitetura de
associação de dados do Windows Forms padrão, DataGridView de modo que o controle
exibirá os dados vinculados sem necessidade de configuração adicional. No entanto,
talvez você queira considerar aproveitar as melhorias de associação de dados
vinculando seus dados a BindingSource um componente, que pode ser vinculado ao
DataGridView controle. Para obter mais informações, consulte Componente
BindingSource.
Como o DataGridView controle tem uma arquitetura totalmente nova, não há nenhum
caminho de conversão simples que permitirá que você use DataGrid personalizações
com o DataGridView controle . No DataGrid entanto, muitas personalizações são
DataGridView desnecessárias com o controle, devido aos recursos integrados
disponíveis no novo controle. Se você tiver criado tipos de coluna personalizados
DataGridDataGridView para o controle que deseja usar com o controle , será preciso
implementá-los novamente usando a nova arquitetura. Para obter mais informações,
consulte Personalizando o controle DataGridView dos Windows Forms.
Confira também
DataGridView
DataGrid
BindingSource
Controle DataGrid
Controle DateTimePicker (Windows
Forms)
Artigo • 02/06/2023
o controle de Windows Forms DateTimePicker permite que o usuário selecione um

único item de uma lista de datas ou horas. Quando usado para representar uma data,
ele aparece em duas partes: uma lista suspensa com uma data representada em texto e
uma grade exibida ao clicar na seta para baixo ao lado da lista.
Nesta seção
Visão geral do controle DateTimePicker
Apresenta os conceitos gerais do DateTimePicker controle, que permite aos usuários
selecionar um único item de uma lista de datas ou horas.
Como: Exibir uma data em um formato personalizado com o controle DateTimePicker

do Windows Forms
Explica como usar cadeias de caracteres de formato para exibir datas em um formato
preferencial.
Como: Definir e retornar datas com o controle DateTimePicker do Windows Forms

Fornece as etapas para definir a data no controle e acessar a data que o usuário
selecionou.
Como: Exibir a hora com o controle DateTimePicker

Mostra as etapas para para um DateTimePicker para exibir somente os horários.
Referência
DateTimePicker
MonthCalendar
Apresenta uma interface gráfica intuitiva para os usuários exibirem e definirem as
informações de data.
Visão geral do controle DateTimePicker
(Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms DateTimePicker permite que o usuário selecione um único

item em uma lista de datas ou horas. Quando usado para representar uma data, ele
aparece em duas partes: uma lista suspensa com uma data representada em texto e
uma grade exibida ao clicar na seta para baixo ao lado da lista. A grade se parece com o
MonthCalendar controle, que pode ser usado para selecionar várias datas. Para obter
mais informações sobre o MonthCalendar controle, consulte Visão geral do controle
MonthCalendar.
Se você quiser que ele DateTimePicker apareça como um controle para escolher ou
editar horários em vez de datas, defina a ShowUpDown propriedade true como e a
Format propriedade como Time. Para obter mais informações, consulte Como exibir a
hora com o controle DateTimePicker.
Quando a ShowCheckBox propriedade é definida como true , uma caixa de seleção é

exibida ao lado da data selecionada no controle. Quando a caixa de seleção é marcada,
é possível atualizar o valor de data e hora selecionado. Quando a caixa de seleção está
vazia, o valor aparece indisponível.
As propriedades e MinDate o MaxDate controle determinam o intervalo de datas e

horas. A Value propriedade contém a data e a hora atuais em que o controle está
definido. Para ver mais detalhes, consulte Como definir e retornar datas com o controle
DateTimePicker dos Windows Forms. Os valores podem ser exibidos em quatro
formatos, que são definidos pela Format propriedade: Long, , Short, Timeou Custom. Se
um formato personalizado for selecionado, você deverá definir a CustomFormat
propriedade como uma cadeia de caracteres apropriada. Para ver mais detalhes,
consulte Como exibir uma data em um formato personalizado com o controle
DateTimePicker dos Windows Forms.
Confira também
Como: Exibir uma data em um formato personalizado com o controle
DateTimePicker do Windows Forms
Como: Exibir uma data em um formato
personalizado com o controle
Artigo • 02/06/2023
o controle de Windows Forms DateTimePicker oferece flexibilidade na formatação da

exibição de datas e horas no controle. A Format propriedade permite que você
selecione formatos predefinidos, listados no DateTimePickerFormat . Se nenhuma delas
for adequada para suas finalidades, você poderá criar seu próprio estilo de formato
usando caracteres de formato listados em CustomFormat .
Para exibir um formato personalizado

1. Defina a propriedade Format como DateTimePickerFormat.Custom .
2. Defina a CustomFormat propriedade como uma cadeia de caracteres de formato.
C#
dateTimePicker1.Format = DateTimePickerFormat.Custom;
// Display the date as "Mon 27 Feb 2012".
dateTimePicker1.CustomFormat = "ddd dd MMM yyyy";
Para adicionar texto ao valor formatado

1. Use aspas simples para incluir qualquer caractere que não seja um caractere de
formato como "M" ou um delimitador como ":". Por exemplo, a cadeia de formato
a seguir exibe a data atual com o formato "hoje é: 05:30:31 sexta-feira 02 de março
de 2012" em inglês (Estados Unidos).
C#
dateTimePicker1.CustomFormat = "'Today is:' hh:mm:ss dddd MMMM dd,

yyyy";
Dependendo da configuração de cultura, todos os caracteres que não estiverem

entre aspas simples poderão ser alterados. Por exemplo, a cadeia de formato
acima exibe a data atual com o formato "hoje é: 05:30:31 sexta-feira 02 de março
de 2012" em inglês (Estados Unidos). Observe que a primeira vírgula é colocada
entre aspas simples, porque não se pretende que ela seja um caractere delimitador
como em "hh:mm:ss". Em outra cultura, o formato pode ser exibido como "hoje é:
05.30.31 sexta-feira, 02 de março de 2012".
Confira também
Como: Definir e retornar datas com o
controle DateTimePicker do Windows
Forms
Artigo • 21/06/2023
A data ou hora selecionada no momento no controle Windows Forms DateTimePicker é

determinada pela Value propriedade . Você pode definir a Value propriedade antes que
o controle seja exibido (por exemplo, em tempo de design ou no evento do Load
formulário) para determinar qual data será inicialmente selecionada no controle. Por
padrão, o do Value controle é definido como a data atual. Se você alterar o controle no
Value código, o controle será atualizado automaticamente no formulário para refletir a
nova configuração.
A Value propriedade retorna uma DateTime estrutura como seu valor. Há várias
propriedades da DateTime estrutura que retornam informações específicas sobre a data
exibida. Essas propriedades só podem ser usadas para retornar um valor; não as utilize
para definir um valor.
Para valores de data, as Monthpropriedades , Daye Year retornam valores inteiros

para essas unidades de hora da data selecionada. A DayOfWeek propriedade
retorna um valor que indica o dia selecionado da semana (os valores possíveis são
listados na DayOfWeek enumeração ).
Para valores de tempo, as Hourpropriedades , Minute, Seconde Millisecond

retornam valores inteiros para essas unidades de tempo. Para configurar o controle
para exibir horas, consulte Como exibir a hora com o controle DateTimePicker.
Definir o valor de data e hora do controle

Defina a Value propriedade como um valor de data ou hora.
C#
dateTimePicker1.Value = new DateTime(2001, 10, 20);
Retornar o valor de data e hora

Chame a Text propriedade para retornar o valor inteiro conforme formatado no
controle ou chame o método apropriado da Value propriedade para retornar uma
parte do valor. Use ToString para converter as informações em uma cadeia de
caracteres que pode ser exibida para o usuário.
C#
MessageBox.Show ("The selected value is " +

dateTimePicker1.Text);
MessageBox.Show ("The day of the week is " +
dateTimePicker1.Value.DayOfWeek.ToString());
MessageBox.Show("Millisecond is: " +
dateTimePicker1.Value.Millisecond.ToString());
Confira também
Como: Exibir uma data em um formato personalizado com o controle
Como: Exibir a hora com o controle
DateTimePicker
Artigo • 02/06/2023
Se você quiser que o aplicativo permita que os usuários selecionem uma data e hora e
exibam essa data e hora no formato especificado, use o DateTimePicker controle. O
procedimento a seguir mostra como usar o DateTimePicker controle para exibir a hora.
Para exibir a hora com o controle DateTimePicker

1. Defina a propriedade Format como Time
C#
timePicker.Format = DateTimePickerFormat.Time;
2. Defina a ShowUpDown propriedade para o DateTimePicker como true .
C#
timePicker.ShowUpDown = true;
Exemplo
O exemplo de código a seguir mostra como criar um DateTimePicker que permite que
os usuários escolham apenas um tempo.
C#
using System;
using System.Data;
using System.Text;
namespace TimePickerApplication
{
{
public Form1()
{
InitializeTimePicker();
}
private DateTimePicker timePicker;
private void InitializeTimePicker()

{
timePicker = new DateTimePicker();
timePicker.Format = DateTimePickerFormat.Time;
timePicker.ShowUpDown = true;
timePicker.Location = new Point(10, 10);
timePicker.Width = 100;
Controls.Add(timePicker);
}
[STAThread]
static void Main()
{
}
}
}

Confira também
Controles e componentes da caixa de
diálogo (Windows Forms)
Artigo • 02/06/2023
Os seguintes controles e componentes dos Windows Forms apresentam caixas de

diálogo padrão. Siga os links para obter mais informações sobre as funções disponíveis
em cada caixa de diálogo.
Referência
ColorDialog
Fornece informações de referência sobre a ColorDialog classe e seus membros.
FontDialog
Fornece informações de referência sobre a FontDialog classe e seus membros.
OpenFileDialog
Fornece informações de referência sobre a OpenFileDialog classe e seus membros.
PageSetupDialog
Fornece informações de referência sobre a PageSetupDialog classe e seus membros.
PrintDialog
Fornece informações de referência sobre a PrintDialog classe e seus membros.
PrintPreviewDialog
Fornece informações de referência sobre a PrintPreviewDialog classe e seus membros.
SaveFileDialog
Fornece informações de referência sobre a SaveFileDialog classe e seus membros.
Caixas de diálogo no Windows Forms
Descreve como criar uma caixa de diálogo para um Windows Form.

Permite que o usuário escolha uma cor de uma paleta em uma caixa de diálogo pré-
configurada e adicione cores personalizadas a essa paleta.
Visão geral do componente FolderBrowserDialog (Windows Forms)
Permite aos usuários navegar e selecionar pastas.
Visão geral do componente FontDialog

Expõe as fontes atualmente instaladas no sistema.
Visão geral do componente OpenFileDialog

Permite aos usuários abrir arquivos por meio de uma caixa de diálogo pré-configurada.
Visão geral do componente PageSetupDialog

Define detalhes de páginas para impressão por meio de uma caixa de diálogo pré-
configurada.
Visão geral do componente PrintDialog

Seleciona uma impressora, escolhe as páginas a serem impressas e determina as outras
configurações relacionadas à impressão.
Visão geral do controle PrintPreviewDialog

Exibe um documento como ele aparecerá quando for impresso.
Visão geral do componente SaveFileDialog

Seleciona os arquivos a serem salvos e onde salvá-los.
Veja também Caixas de diálogo nos Windows Forms.

Controle DomainUpDown (Windows
Forms)
Artigo • 02/06/2023
O controle Windows Forms DomainUpDown parece uma combinação de uma caixa de

texto e um par de botões para mover para cima ou para baixo através de uma lista. O
controle exibe e define uma sequências de texto em uma lista de escolhas. O usuário
pode selecionar a sequência clicando nos botões para cima e para baixo para mover a
lista, apertando as teclas de direção PARA BAIXO e PARA CIMA ou digitando uma cadeia
de caracteres que corresponda a um item na lista. Um possível uso para este controle é
selecionar itens de uma lista de nomes ordenada alfabeticamente. (Para classificar a
lista, defina a Sorted propriedade como true .) A função desse controle é muito
semelhante à caixa de listagem ou caixa de combinação, mas ocupa muito pouco
espaço.
As principais propriedades do controle são Items, ReadOnlye Wrap. A Items propriedade

contém a lista de objetos cujos valores de texto são exibidos no controle. Se ReadOnly
estiver definido como false , o controle concluirá automaticamente o texto que o
usuário digita e o corresponde a um valor na lista. Se Wrap estiver definido como true ,
rolar para além do último item levará você para o primeiro item da lista e vice-versa. Os
principais métodos do controle são UpButton e DownButton.
Este controle exibe somente sequências de texto. Se você quiser um controle que exiba
valores numéricos, use o NumericUpDown controle. Para obter mais informações,
consulte NumericUpDown Control .
Nesta seção
Visão geral do controle DomainUpDown
Apresenta os conceitos gerais do controle, que DomainUpDown permite que os
usuários naveguem e selecionem uma lista de cadeias de caracteres de texto.
Como adicionar itens a controles DomainUpDown dos Windows Forms de forma

programática
Descreve como especificar as cadeias de caracteres de texto que o DomainUpDown
controle deve exibir.
Como: Remover itens de controles DomainUpDown do Windows Forms

Descreve como excluir itens do DomainUpDown controle no código.
Referência
DomainUpDown
NumericUpDown
(Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms DomainUpDown é essencialmente uma combinação de uma

caixa de texto e um par de botões para mover para cima ou para baixo através de uma
lista. O controle exibe e define uma sequências de texto em uma lista de escolhas. O
usuário pode selecionar a sequência clicando nos botões para cima e para baixo para
mover a lista, apertando as teclas de direção PARA BAIXO e PARA CIMA ou digitando
uma cadeia de caracteres que corresponda a um item na lista. Um possível uso para este
controle é selecionar itens de uma lista de nomes ordenada alfabeticamente.
７ Observação
Para classificar a lista, defina a Sorted propriedade como true .
A função deste controle é bem parecida com a da caixa de listagem ou caixa de

combinação, mas ocupa muito pouco espaço.
As principais propriedades do controle são Items, ReadOnlye Wrap. A Items propriedade
contém a lista de objetos cujos valores de texto são exibidos no controle. Se ReadOnly
estiver definido como false , o controle concluirá automaticamente o texto que o
usuário digita e o corresponde a um valor na lista. Se Wrap estiver definido como true ,
rolar para além do último item levará você para o primeiro item da lista e vice-versa. Os
principais métodos do controle são UpButton e DownButton.
Este controle exibe somente sequências de texto. Se você quiser um controle que exiba
valores numéricos, use o NumericUpDown controle. Para mais informação, consulte
Visão geral do controle NumericUpDown.
Confira também
DomainUpDown
Como adicionar itens a controles
DomainUpDown dos Windows Forms de
forma programática
Artigo • 02/06/2023
Você pode adicionar itens ao controle Windows Forms DomainUpDown no código.

Chame o método ou Insert o Add método da
DomainUpDown.DomainUpDownItemCollection classe para adicionar itens à
propriedade do Items controle. O Add método adiciona um item ao final de uma
coleção, enquanto o Insert método adiciona um item em uma posição especificada.
Para adicionar um novo item

1. Use o Add método para adicionar um item ao final da lista de itens.
C#
domainUpDown1.Items.Add("noodles");
-ou-
2. Use o Insert método para inserir um item na lista em uma posição especificada.
C#
// Inserts an item at the third position in the list

domainUpDown1.Items.Insert(2, "rice");
Confira também
DomainUpDown
DomainUpDown.DomainUpDownItemCollection.Add
ArrayList.Insert
Como: Remover itens de controles
DomainUpDown do Windows Forms
Artigo • 02/06/2023
Você pode remover itens do controle Windows Forms DomainUpDown chamando o

método ou RemoveAt o Remove método da
DomainUpDown.DomainUpDownItemCollection classe. O Remove método remove um
item específico, enquanto o RemoveAt método remove um item por sua posição.
Para remover um item

Use o Remove método da DomainUpDown.DomainUpDownItemCollection classe
para remover um item por nome.
C#
domainUpDown1.Items.Remove("noodles");
-ou-
Use o RemoveAt método para remover um item por sua posição.
C#
// Removes the first item in the list.

domainUpDown1.Items.RemoveAt(0);
Confira também
DomainUpDown
DomainUpDown.DomainUpDownItemCollection.Remove
DomainUpDown.DomainUpDownItemCollection.RemoveAt
Componente ErrorProvider (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms ErrorProvider é usado para mostrar ao usuário de

forma não intrusiva que algo está errado. Ele é normalmente usado junto com a
validação de entrada do usuário em um formulário ou para exibir erros dentro de um
conjunto de dados.
Nesta seção
Visão geral do componente ErrorProvider
Explica o que é esse componente e seus principais recursos e propriedades.
Como: Exibir ícones de erro para validação de formulário com o componente

ErrorProvider do Windows Forms
Fornece instruções para validar a entrada do usuário com um componente do provedor
de erros.
Como: Exibir erros dentro de um DataSet com o componente ErrorProvider do Windows

Forms
Fornece instruções para usar um componente do provedor de erros para exibir erros de
dados.
Referência
ErrorProvider
ErrorProvider (Windows Forms)
Artigo • 02/06/2023
O componente ErrorProvider dos Windows Forms é usado para validar a entrada do

usuário em um formulário ou controle. Ele é normalmente usado junto com a validação
de entrada do usuário em um formulário ou para exibir erros dentro de um conjunto de
dados. Um provedor de erro é uma alternativa melhor que exibir uma mensagem de
erro em uma caixa de mensagem, pois depois que uma caixa de mensagem for
descartada, a mensagem de erro não estará mais visível. O ErrorProvider componente
exibe um ícone de erro ( ) ao lado do controle relevante, como uma caixa de texto;
quando o usuário posiciona o ponteiro do mouse sobre o ícone de erro, uma Dica de
Ferramenta é exibida, mostrando a cadeia de caracteres de mensagem de erro.
As ErrorProvider principais propriedades do componente são DataSource,
ContainerControle Icon. Ao usar ErrorProvider o componente com controles associados
a dados, a ContainerControl propriedade deve ser definida como o contêiner
apropriado (geralmente o Formulário do Windows) para que o componente exiba um
ícone de erro no formulário. Quando o componente é adicionado no designer, a
ContainerControl propriedade é definida como o formulário que contém; se você
adicionar o controle no código, você deverá defini-lo por conta própria.
A Icon propriedade pode ser definida como um ícone de erro personalizado em vez do
padrão. Quando a DataSource propriedade é definida, o ErrorProvider componente
pode exibir mensagens de erro para um conjunto de dados. O método chave do
ErrorProvider componente é o SetError método, que especifica a cadeia de caracteres
de mensagem de erro e onde o ícone de erro deve aparecer.
７ Observação
O ErrorProvider componente não fornece suporte interno para clientes de

acessibilidade. Para tornar seu aplicativo acessível ao usar esse componente, você
deve fornecer um mecanismo de comentários acessível adicional.
Confira também
ErrorProvider
Como: Exibir erros dentro de um DataSet com o componente ErrorProvider do
Windows Forms
Como: Exibir ícones de erro para
validação de formulário com o
componente ErrorProvider do Windows
Forms
Artigo • 02/06/2023
Você pode usar um componente Windows Forms ErrorProvider para exibir um ícone de
erro quando o usuário insere dados inválidos. Você deve ter pelo menos dois controles
no formulário para alternar entre eles e, portanto, invocar o código de validação.
Para exibir um ícone de erro quando o valor do controle é

inválido
1. Adicione dois controles, por exemplo, caixas de texto, a um Windows Form.
2. Adicione um ErrorProvider componente ao formulário.
3. Selecione o primeiro controle e adicione o código ao manipulador Validating de

eventos. Para que esse código seja executado corretamente, o procedimento deve
estar conectado ao evento. Para saber mais, veja Como criar manipuladores de
eventos em tempo de execução para formulários dos Windows Forms.
O código a seguir testa a validade dos dados que o usuário inseriu; se os dados
forem inválidos, o SetError método será chamado. O primeiro argumento do
SetError método especifica qual controle exibir o ícone ao lado. O segundo
argumento é o texto do erro a ser exibido.
C#
protected void textBox1_Validating (object sender,

System.ComponentModel.CancelEventArgs e)
{
try
{
int x = Int32.Parse(textBox1.Text);
errorProvider1.SetError(textBox1, "");
}
catch (Exception ex)
{
errorProvider1.SetError(textBox1, "Not an integer value.");
}
}
C#
this.textBox1.Validating += new
System.ComponentModel.CancelEventHandler(this.textBox1_Validating);
4. Execute o projeto. Digite dados inválidos (neste exemplo, não numéricos) no

primeiro controle e alterne para o segundo. Quando o ícone de erro for exibido,
aponte para ele com o ponteiro do mouse para ver o texto do erro.
Confira também
SetError
Como: Exibir erros dentro de um DataSet com o componente ErrorProvider do
Windows Forms
Como: Exibir erros dentro de um
DataSet com o componente
Artigo • 02/06/2023
Você pode usar o componente Windows Forms ErrorProvider para exibir erros de coluna
em um conjunto de dados ou em outra fonte de dados. Para que um ErrorProvider
componente exiba erros de dados em um formulário, ele não precisa ser associado
diretamente a um controle. Depois de associado a uma fonte de dados, ele pode exibir
um ícone de erro ao lado de qualquer controle que esteja associado à mesma fonte de
dados.
７ Observação
Se você alterar as propriedades e DataMember o provedor de DataSource erros

em tempo de execução, deverá usar o BindToDataAndErrors método para evitar
conflitos.
Para exibir os erros de dados

1. Associe o componente a uma coluna específica dentro de uma tabela de dados.
C#
// Assumes existence of DataSet1, DataTable1

textBox1.DataBindings.Add("Text", DataSet1, "Customers.Name");
errorProvider1.DataSource = DataSet1;
errorProvider1.DataMember = "Customers";
2. Defina a ContainerControl propriedade como o formulário.
C#
errorProvider1.ContainerControl = this;
3. Defina a posição do registro atual para uma linha que contém um erro de coluna.
C#
DataTable1.Rows[5].SetColumnError("Name", "Bad data in this row.");
this.BindingContext [DataTable1].Position = 5;
Confira também
Classe FileDialog
Artigo • 02/06/2023
A classe Windows Forms FileDialog é a classe base comum para os componentes e

SaveFileDialog os OpenFileDialog componentes. Você pode fazer alterações na
FileDialog classe que afetam a aparência e o comportamento dessas caixas de diálogo,
dependendo da versão do Windows em que o aplicativo está em execução.
Nesta seção
Como: Recusar a atualização automática da caixa de diálogo do arquivo
Descreve como recusar uma atualização automática de estilo para uma caixa de diálogo
de arquivo.
Como: Adicionar um local personalizado a uma caixa de diálogo Arquivo

Descreve como adicionar um local de arquivo personalizado a uma caixa de diálogo de
arquivo.
GUIDs de pasta conhecidas para locais personalizados da caixa de diálogo

Liste os nomes das pastas e seus GUIDs associados.
Referência
OpenFileDialog
SaveFileDialog
Como: Recusar a atualização automática
da caixa de diálogo do arquivo
Artigo • 02/06/2023
Quando as classes e SaveFileDialog as OpenFileDialog classes são usadas em um

aplicativo, sua aparência e comportamento dependem da versão do Windows em que o
aplicativo está sendo executado. Quando um aplicativo criado no .NET Framework 2.0
ou anterior é exibido no Windows Vista OpenFileDialog e SaveFileDialog é exibido
automaticamente com a aparência e o comportamento do Windows Vista. A partir do
.NET Framework 3.0, você pode recusar a atualização automática para exibir a aparência
e SaveFileDialog o OpenFileDialog comportamento do estilo XP do Windows.
Para recusar a atualização automática da caixa de diálogo

de arquivo
1. Defina a AutoUpgradeEnabled propriedade de ou SaveFileDialog para false antes
de OpenFileDialog exibir a caixa de diálogo.
Confira também
FileDialog
Como: Adicionar um local personalizado
a uma caixa de diálogo Arquivo
Artigo • 02/06/2023
As caixas de diálogo padrão abrir e salvar no Windows Vista têm uma área no lado
esquerdo da caixa de diálogo intitulada Links Favoritos. Essa área é chamada de locais
personalizados. As OpenFileDialog classes e as SaveFileDialog classes permitem que
você adicione pastas à CustomPlaces coleção.
７ Observação
Para que um local personalizado apareça no OpenFileDialog ou, a

AutoUpgradeEnabled propriedade deve ser definida true como (SaveFileDialogo
padrão).
Para adicionar um local personalizado a uma caixa de

diálogo de arquivo
Adicione um caminho, um GUID de Pasta Conhecida ou um FileDialogCustomPlace
objeto à CustomPlaces coleção da caixa de diálogo.
O exemplo de código a seguir mostra como adicionar um caminho:
C#
openFileDialog1.CustomPlaces.Add("C:\\MyCustomPlace");
Confira também
FileDialog
FileDialogCustomPlacesCollection.Add
GUIDs de pasta conhecidas para locais personalizados da caixa de diálogo
GUIDs de pasta conhecidas para locais
personalizados da caixa de diálogo
Artigo • 02/06/2023
Você usa um Guid para especificar uma Pasta Conhecida do Windows ao adicionar
pastas a uma CustomPlaces coleção. GUIDs de pasta conhecidas não diferenciam
maiúsculas de minúsculas e são definidas no arquivo KnownFolders.h no SDK do
Windows.
７ Observação
Em alguns casos, uma Pasta Conhecida adicionada à

FileDialogCustomPlacesCollection área de Links Favoritos não será mostrada. Por
exemplo, se a Pasta Conhecida especificada não estiver presente no computador
que está executando o aplicativo, a Pasta Conhecida não será mostrada.
Lista de GUIDs
A tabela a seguir lista pastas conhecidas do Windows e suas associadas Guid.
AddNewPrograms DE61D971-5EBC-4F02-A3A9-6C82895E5C04
AdminTools 724EF170-A42D-4FEF-9F26-B60E846FBA4F
AppDataLow A520A1A4-1780-4FF6-BD18-167343C5AF16
AppUpdates A305CE99-F527-492B-8B1A-7E76FA98D6E4
CDBurning 9E52AB10-F80D-49DF-ACB8-4330F5687855
ChangeRemovePrograms DF7266AC-9274-4867-8D55-3BD661DE872D
CommonAdminTools D0384E7D-BAC3-4797-8F14-CBA229B392B5
CommonOEMLinks C1BAE2D0-10DF-4334-BEDD-7AA20B227A9D
CommonPrograms 0139D44E-6AFE-49F2-8690-3DAFCAE6FFB8
CommonStartMenu A4115719-D62E-491D-AA7C-E74B8BE3B067
CommonStartup 82A5EA35-D9CD-47C5-9629-E15D2F714E6E
CommonTemplates B94237E7-57AC-4347-9151-B08C6C32D1F7
Computador 0AC0837C-BBF8-452A-850D-79D08E667CA7
Conflito 4BFEFB45-347D-4006-A5BE-AC0CB0567192
Conexões 6F0CD92B-2E97-45D1-88FF-B0D186B8DEDD
Contatos 56784854-C6CB-462B-8169-88E350ACB882
ControlPanel 82A74AEB-AEB4-465C-A014-D097EE346D63
Cookies 2B0F765D-C0E9-4171-908E-08A611B84FF6
Desktop B4BFCC3A-DB2C-424C-B029-7FE99A87C641
Documentos FDD39AD0-238F-46AF-ADB4-6C85480369C7
Downloads 374DE290-123F-4565-9164-39C4925E467B
Favoritos 1777F761-68AD-4D8A-87BD-30B759FA33DDD
Fontes FD228CB7-AE11-4AE3-864C-16F3910AB8FE
Jogos CAC52C1A-B53D-4EDC-92D7-6B2E8AC19434
GameTasks 054FAE61-4DD8-4787-80B6-090220C4B700
Histórico D9DC8A3B-B784-432E-A781-5A1130A75963
Internet 4D9F7874-4E0C-4904-967B-40B0D20C3E4B
InternetCache 352481E8-33BE-4251-BA85-6007CAEDCF9D
Links BFB9D5E0-C6A9-404C-B2B2-AE6DB6AF4968
LocalAppData F1B32785-6FBA-4FCF-9D55-7B8E7F157091
LocalizedResourcesDir 2A00375E-224C-49DE-B8D1-440DF7EF3DDC
Música 4BD8D571-6D19-48D3-BE97-422220080E43
NetHood C5ABBF53-E17F-4121-8900-86626FC2C973
Rede D20BEEC4-5CA8-4905-AE3B-BF251EA09B53
Objects3D 31C0DD25-9439-4F12-BF41-7FF4EDA38722
OriginalImages 2C36C0AA-5812-4B87-BFD0-4CD0DFB19B39
PhotoAlbums 69D2CF90-FC33-4FB7-9A0C-EBB0F0FCB43C
Imagens 33E28130-4E1E-4676-835A-98395C3BC3BB
Playlists DE92C1C7-837F-4F69-A3BB-86E631204A23
Impressoras 76FC4E2D-D6AD-4519-A663-37BD56068185
PrintHood 9274BD8D-CFD1-41C3-B35E-B13F55A758F4
Perfil 5E6C858F-0E22-4760-9AFE-EA3317B67173
ProgramData 62AB5D82-FDC1-4DC3-A9DD-070D1D495D97
ProgramFiles 905E63B6-C1BF-494E-B29C-65B732D3D21A
ProgramFilesCommon F7F1ED05-9F6D-47A2-AAAE-29D317C6F066
ProgramFilesCommonX64 6365D5A7-0F0D-45E5-87F6-0DA56B6A4F7D
ProgramFilesCommonX86 DE974D24-D9C6-4D3E-BF91-F4455120B917
ProgramFilesX64 6D809377-6AF0-444B-8957-A3773F02200E
ProgramFilesX86 7C5A40EF-A0FB-4BFC-874A-C0F2E0B9FA8E
Programas A77F5D77-2E2B-44C3-A6A2-ABA601054A51
Público DFDF76A2-C82A-4D63-906A-5644AC457385
PublicDesktop C4AA340D-F20F-4863-AFEF-F87EF2E6BA25
PublicDocuments ED4824AF-DCE4-45A8-81E2-FC7965083634
PublicDownloads 3D644C9B-1FB8-4F30-9B45-F670235F79C0
PublicGameTasks DEBF2536-E1A8-4C59-B6A2-414586476AEA
PublicMusic 3214FAB5-9757-4298-BB61-92A9DEAA44FF
PublicPictures B6EBFB86-6907-413C-9AF7-4FC2ABF07CC5
PublicVideos 2400183A-6185-49FB-A2D8-4A392A602BA3
QuickLaunch 52A4F021-7B75-48A9-9F6B-4B87A210BC8F
Recent AE50C081-EBD2-438A-8655-8A092E34987A
RecordedTV BD85E001-112E-431E-983B-7B15AC09FFF1
RecycleBin B7534046-3ECB-4C18-BE4E-64CD4CB7D6AC
ResourceDir 8AD10C31-2ADB-4296-A8F7-E4701232C972
RoamingAppData 3EB685DB-65F9-4CF6-A03A-E3EF65729F3D
SampleMusic B250C668-F57D-4EE1-A63C-290EE7D1AA1F
SamplePictures C4900540-2379-4C75-844B-64E6FAF8716B
SamplePlaylists 15CA69B3-30EE-49C1-ACE1-6B5EC372AFB5
SampleVideos 859EAD94-2E85-48AD-A71A-0969CB56A6CD
SavedGames 4C5C32FF-BB9D-43B0-B5B4-2D72E54EAAA4
SavedSearches 7D1D3A04-DEBB-4115-95CF-2F29DA2920DA
SEARCH_CSC EE32E446-31CA-4ABA-814F-A5EBD2FD6D5E
SEARCH_MAPI 98EC0E18-2098-4D44-8644-66979315A281
SearchHome 190337D1-B8CA-4121-A639-6D472D16972A
SendTo 8983036C-27C0-404B-8F08-102D10DCFD74
SidebarDefaultParts 7B396E54-9EC5-4300-BE0A-2482EBAE1A26
SidebarParts A75D362E-50FC-4FB7-AC2C-A8BEAA314493
StartMenu 625B53C3-AB48-4EC1-BA1F-A1EF4146FC19
Inicialização B97D20BB-F46A-4C97-BA10-5E3608430854
SyncManager 43668BF8-C14E-49B2-97C9-747784D784B7
SyncResults 289A9A43-BE44-4057-A41B-587A76D7E7F9
SyncSetup 0F214138-B1D3-4A90-BBA9-27CBC0C5389A
Sistema 1AC14E77-02E7-4E5D-B744-2EB1AE5198B7
SystemX86 D65231B0-B2F1-4857-A4CE-A8E7C6EA7D27
Modelos A63293E8-664E-48DB-A079-DF759E0509F7
TreeProperties 5B3749AD-B49F-49C1-83EB-15370FBD4882
UserProfiles 0762D272-C50A-4BB0-A382-697DCD729B80
UsersFiles F3CE0F7C-4901-4ACC-8648-D5D44B04EF8F
Vídeos 18989B1D-99B5-455B-841C-AB7C74E4DDDFC
Windows F38BF404-1D43-42F2-9305-67DE0B28FC23
Confira também
FileDialogCustomPlace
Como: Adicionar um local personalizado a uma caixa de diálogo Arquivo
Arquivo KnownFolders.h no SDK do Windows
Controle FlowLayoutPanel (Windows
Forms)
Artigo • 02/06/2023
O FlowLayoutPanel controle organiza seu conteúdo em uma direção de fluxo horizontal

ou vertical. Seu conteúdo pode ser encapsulado de uma linha à outra ou de uma coluna
à próxima. Como alternativa, seu conteúdo pode ser recortado, em vez de encapsulado.
Os tópicos desta seção descrevem os conceitos e técnicas que permitem criar

FlowLayoutPanel recursos em seus aplicativos.
Nesta seção
Visão geral do controle FlowLayoutPanel
Apresenta os conceitos gerais do controle, o FlowLayoutPanel que permite criar um
layout que flui horizontal ou verticalmente.

Explica como usar o e Dock as Anchor propriedades para ancorar e encaixar controles
filho em um FlowLayoutPanel controle.
Consulte também Explicação passo a passo: organizando controles nos Windows Forms
utilizando um FlowLayoutPanel.
Referência
FlowLayoutPanel
Fornece documentação de referência para o FlowLayoutPanel controle.
FlowLayoutPanel
Artigo • 02/06/2023
O FlowLayoutPanel controle organiza seu conteúdo em uma direção de fluxo horizontal

ou vertical. Você pode encapsular o conteúdo do controle de uma linha para outra ou
de uma coluna para a próxima. Como alternativa, você pode recortar, em vez de
encapsular seu conteúdo.
Você pode especificar a direção do fluxo definindo o valor da FlowDirection

propriedade. O FlowLayoutPanel controle inverte corretamente sua direção de fluxo em
layouts da direita para a esquerda (RTL). Você também pode especificar se o
FlowLayoutPanel conteúdo do controle é encapsulado ou recortado definindo o valor
da WrapContents propriedade.
O FlowLayoutPanel controle é dimensionado automaticamente para seu conteúdo

quando você define a AutoSize propriedade como true . Ele também fornece uma
propriedade FlowBreak para seus controles filho. Definir o valor da propriedade
FlowBreak faz true com que o FlowLayoutPanel controle pare de estabelecer controles
na direção do fluxo atual e encapsule para a próxima linha ou coluna.
Qualquer controle Windows Forms pode ser um filho do FlowLayoutPanel controle,

incluindo outras instâncias de FlowLayoutPanel. Com esse capacidade, você pode criar
layouts sofisticados que se adaptam às dimensões do formulário em tempo de
execução.
Consulte também Explicação passo a passo: organizando controles nos Windows Forms
utilizando um FlowLayoutPanel.
Confira também
FlowDirection
TableLayoutPanel
Controle FlowLayoutPanel
Como: Ancorar e encaixar controles
filho em um controle FlowLayoutPanel
Artigo • 02/06/2023
O FlowLayoutPanel controle dá suporte às propriedades e Dock aos Anchor controles

filho.
Ancorar e encaixar controles filho em um controle

FlowLayoutPanel
1. Crie um FlowLayoutPanel controle em seu formulário.
2. Defina o WidthFlowLayoutPanel controle como 300 e defina-o FlowDirection como

TopDown.
3. Crie dois Button controles e coloque-os no FlowLayoutPanel controle.
4. Defina o Width primeiro botão como 200.
5. Defina a Dock propriedade do segundo botão como Fill.
７ Observação
O segundo botão assume a mesma largura que o primeiro. Ele não se estende
pela largura do FlowLayoutPanel controle.
6. Defina a Dock propriedade do segundo botão como None . Isso faz com que o
botão assuma a largura original.
7. Defina a Anchor propriedade do segundo botão como Left, Right .
） Importante
O segundo botão assume a mesma largura que o primeiro. Ele não se estende
pela largura do FlowLayoutPanel controle. Essa é a regra geral para
ancoragem e encaixe no FlowLayoutPanel controle: para direções de fluxo
vertical, o FlowLayoutPanel controle calcula a largura de uma coluna implícita
do controle filho mais largo da coluna. Todos os outros controles nesta coluna
com Anchor ou Dock propriedades são alinhados ou estendidos para se
ajustar a esta coluna implícita. O comportamento funciona de maneira similar
a direções de fluxo horizontal. O FlowLayoutPanel controle calcula a altura de
uma linha implícita do controle filho mais alto da linha e todos os controles
filho encaixados ou ancorados nessa linha são alinhados ou dimensionados
para se ajustar à linha implícita.
Exemplo
A ilustração a seguir mostra quatro botões ancorados e encaixados em relação ao botão
azul em um FlowLayoutPanel. O FlowDirection é LeftToRight.
A ilustração a seguir mostra quatro botões ancorados e encaixados em relação ao botão

azul em um FlowLayoutPanel. O FlowDirection é TopDown.
O exemplo de código a seguir demonstra vários Anchor valores de propriedade para

um Button controle em um FlowLayoutPanel controle.
C#
using System;
using System.Data;

{
public Form1()
{
}

{
{
}
}

{
this.flowLayoutPanel3 = new System.Windows.Forms.FlowLayoutPanel();
this.flowLayoutPanel1 = new System.Windows.Forms.FlowLayoutPanel();
this.flowLayoutPanel3.SuspendLayout();
this.flowLayoutPanel1.SuspendLayout();
//
// flowLayoutPanel3
//
this.flowLayoutPanel3.Anchor = ((System.Windows.Forms.AnchorStyles)
((((System.Windows.Forms.AnchorStyles.Top |
System.Windows.Forms.AnchorStyles.Bottom)
| System.Windows.Forms.AnchorStyles.Left)
| System.Windows.Forms.AnchorStyles.Right)));
this.flowLayoutPanel3.BorderStyle =
System.Windows.Forms.BorderStyle.FixedSingle;
this.flowLayoutPanel3.Controls.Add(this.label2);
this.flowLayoutPanel3.Controls.Add(this.button11);
this.flowLayoutPanel3.Location = new System.Drawing.Point(12, 12);
this.flowLayoutPanel3.Name = "flowLayoutPanel3";
this.flowLayoutPanel3.Size = new System.Drawing.Size(631, 100);
this.flowLayoutPanel3.TabIndex = 2;
//
// label2
//
this.label2.Anchor = System.Windows.Forms.AnchorStyles.None;
this.label2.AutoSize = true;
this.label2.Name = "label2";
this.label2.TabIndex = 10;
this.label2.Text = "FlowDirection=LeftToRight";
//
// button11
//
this.button11.Anchor = System.Windows.Forms.AnchorStyles.Bottom;
this.button11.TabIndex = 5;
this.button11.Text = "Anchor=Bottom";
//
// button12
//
this.button12.Anchor = ((System.Windows.Forms.AnchorStyles)
((System.Windows.Forms.AnchorStyles.Top |
System.Windows.Forms.AnchorStyles.Bottom)));
this.button12.Text = "Anchor=Top, Bottom";
//
// button13
//
this.button13.Anchor = System.Windows.Forms.AnchorStyles.None;
this.button13.BackColor =
System.Drawing.SystemColors.GradientActiveCaption;
//
// button14
//
this.button14.Dock = System.Windows.Forms.DockStyle.Bottom;
this.button14.Text = "Dock=Bottom";
//
// button15
//
this.button15.Dock = System.Windows.Forms.DockStyle.Fill;
this.button15.Text = "Dock=Fill";
//
// flowLayoutPanel1
//
this.flowLayoutPanel1.Anchor = ((System.Windows.Forms.AnchorStyles)
(((System.Windows.Forms.AnchorStyles.Bottom |
System.Windows.Forms.AnchorStyles.Left)
this.flowLayoutPanel1.BorderStyle =
System.Windows.Forms.BorderStyle.FixedSingle;
this.flowLayoutPanel1.Controls.Add(this.label1);
this.flowLayoutPanel1.FlowDirection =
System.Windows.Forms.FlowDirection.TopDown;
this.flowLayoutPanel1.Location = new System.Drawing.Point(12, 118);
this.flowLayoutPanel1.Name = "flowLayoutPanel1";
this.flowLayoutPanel1.Size = new System.Drawing.Size(200, 209);
this.flowLayoutPanel1.TabIndex = 3;
//
// label1
//
this.label1.Text = "FlowDirection=TopDown";
//
// button1
//
this.button1.Anchor = System.Windows.Forms.AnchorStyles.Right;
this.button1.Text = "Anchor=Right";
//
// button2
//
((System.Windows.Forms.AnchorStyles.Left |
System.Windows.Forms.AnchorStyles.Right)));
this.button2.Text = "Anchor=Left, Right";
//
// button3
//
this.button3.BackColor =
System.Drawing.SystemColors.GradientActiveCaption;
//
// button4
//
this.button4.Dock = System.Windows.Forms.DockStyle.Right;
this.button4.Text = "Dock=Right";
//
// button5
//
this.button5.Dock = System.Windows.Forms.DockStyle.Fill;
this.button5.Text = "Dock=Fill";
//
// Form1
//
this.flowLayoutPanel3.ResumeLayout(false);
this.flowLayoutPanel3.PerformLayout();
this.flowLayoutPanel1.ResumeLayout(false);
this.flowLayoutPanel1.PerformLayout();
}
[STAThread]
static void Main()
{
}
}
VB
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Drawing
Imports System.Windows.Forms
Public Class Form1

Inherits Form
Public Sub New()

InitializeComponent()
End Sub
Private flowLayoutPanel3 As FlowLayoutPanel
Private label2 As Label
Private button11 As Button
Private flowLayoutPanel1 As FlowLayoutPanel
Private label1 As Label
Private components As System.ComponentModel.IContainer = Nothing
Protected Overrides Sub Dispose(disposing As Boolean)

If disposing AndAlso (components IsNot Nothing) Then
components.Dispose()
End If
MyBase.Dispose(disposing)
End Sub
Private Sub InitializeComponent()
Me.flowLayoutPanel3 = New System.Windows.Forms.FlowLayoutPanel()
Me.label2 = New System.Windows.Forms.Label()
Me.button11 = New System.Windows.Forms.Button()
Me.flowLayoutPanel1 = New System.Windows.Forms.FlowLayoutPanel()
Me.label1 = New System.Windows.Forms.Label()
Me.flowLayoutPanel3.SuspendLayout()
Me.flowLayoutPanel1.SuspendLayout()
Me.SuspendLayout()
'
' flowLayoutPanel3
'
Me.flowLayoutPanel3.Anchor =
CType(System.Windows.Forms.AnchorStyles.Top Or
System.Windows.Forms.AnchorStyles.Bottom Or
System.Windows.Forms.AnchorStyles.Left Or
System.Windows.Forms.AnchorStyles.Right, System.Windows.Forms.AnchorStyles)
Me.flowLayoutPanel3.BorderStyle =
System.Windows.Forms.BorderStyle.FixedSingle
Me.flowLayoutPanel3.Controls.Add(Me.label2)
Me.flowLayoutPanel3.Controls.Add(Me.button11)
Me.flowLayoutPanel3.Location = New System.Drawing.Point(12, 12)
Me.flowLayoutPanel3.Name = "flowLayoutPanel3"
Me.flowLayoutPanel3.Size = New System.Drawing.Size(631, 100)
Me.flowLayoutPanel3.TabIndex = 2
'
' label2
'
Me.label2.Anchor = System.Windows.Forms.AnchorStyles.None
Me.label2.AutoSize = True
Me.label2.Location = New System.Drawing.Point(3, 28)
Me.label2.Name = "label2"
Me.label2.Size = New System.Drawing.Size(138, 14)
Me.label2.TabIndex = 10
Me.label2.Text = "FlowDirection=LeftToRight"
'
' button11
'
Me.button11.Anchor = System.Windows.Forms.AnchorStyles.Bottom
Me.button11.AutoSize = True
Me.button11.Location = New System.Drawing.Point(147, 44)
Me.button11.Name = "button11"
Me.button11.Size = New System.Drawing.Size(86, 23)
Me.button11.TabIndex = 5
Me.button11.Text = "Anchor=Bottom"
'
' button12
'
Me.button12.Anchor = CType(System.Windows.Forms.AnchorStyles.Top Or
System.Windows.Forms.AnchorStyles.Bottom, System.Windows.Forms.AnchorStyles)
Me.button12.AutoSize = True
Me.button12.Text = "Anchor=Top, Bottom"
'
' button13
'
Me.button13.Anchor = System.Windows.Forms.AnchorStyles.None
Me.button13.BackColor =
System.Drawing.SystemColors.GradientActiveCaption
'
' button14
'
Me.button14.Dock = System.Windows.Forms.DockStyle.Bottom
Me.button14.Text = "Dock=Bottom"
'
' button15
'
Me.button15.Dock = System.Windows.Forms.DockStyle.Fill
Me.button15.Text = "Dock=Fill"
'
' flowLayoutPanel1
'
Me.flowLayoutPanel1.Anchor =
CType(System.Windows.Forms.AnchorStyles.Bottom Or
System.Windows.Forms.AnchorStyles.Left Or
Me.flowLayoutPanel1.BorderStyle =
System.Windows.Forms.BorderStyle.FixedSingle
Me.flowLayoutPanel1.Controls.Add(Me.label1)
Me.flowLayoutPanel1.FlowDirection =
System.Windows.Forms.FlowDirection.TopDown
Me.flowLayoutPanel1.Location = New System.Drawing.Point(12, 118)
Me.flowLayoutPanel1.Name = "flowLayoutPanel1"
Me.flowLayoutPanel1.Size = New System.Drawing.Size(200, 209)
Me.flowLayoutPanel1.TabIndex = 3
'
' label1
'
Me.label1.AutoSize = True
Me.label1.Location = New System.Drawing.Point(3, 3)
Me.label1.Name = "label1"
Me.label1.Size = New System.Drawing.Size(128, 14)
Me.label1.TabIndex = 11
Me.label1.Text = "FlowDirection=TopDown"
'
' button1
'
Me.button1.Anchor = System.Windows.Forms.AnchorStyles.Right
Me.button1.Text = "Anchor=Right"
'
' button2
'
Me.button2.Anchor = CType(System.Windows.Forms.AnchorStyles.Left Or
Me.button2.Text = "Anchor=Left, Right"
'
' button3
'
Me.button3.BackColor =
System.Drawing.SystemColors.GradientActiveCaption
'
' button4
'
Me.button4.Dock = System.Windows.Forms.DockStyle.Right
Me.button4.Text = "Dock=Right"
'
' button5
'
Me.button5.Dock = System.Windows.Forms.DockStyle.Fill
Me.button5.Text = "Dock=Fill"
'
' Form1
'
Me.ClientSize = New System.Drawing.Size(658, 341)
Me.Controls.Add(flowLayoutPanel1)
Me.Controls.Add(flowLayoutPanel3)
Me.Name = "Form1"
Me.Text = "Form1"
Me.flowLayoutPanel3.ResumeLayout(False)
Me.flowLayoutPanel3.PerformLayout()
Me.flowLayoutPanel1.ResumeLayout(False)
Me.flowLayoutPanel1.PerformLayout()
Me.ResumeLayout(False)
End Sub
<STAThread()> _
Shared Sub Main()
Application.EnableVisualStyles()
Application.Run(New Form1())
End Sub
End Class

Confira também
FlowLayoutPanel
Visão geral do controle FlowLayoutPanel
Passo a passo: Organizando controles
nos Windows Forms utilizando um
FlowLayoutPanel
Artigo • 21/06/2023
Alguns aplicativos exigem um formulário com um layout que se organiza

adequadamente à medida que o formulário é redimensionado ou conforme o tamanho
do conteúdo é alterado. Quando você precisar de um layout dinâmico e não quiser
manipular Layout eventos explicitamente em seu código, considere usar um painel de
layout.
O FlowLayoutPanel controle e o TableLayoutPanel controle fornecem maneiras intuitivas

de organizar controles em seu formulário. Ambos fornecem uma capacidade automática
e configurável de controlar as posições relativas dos controles filho contidos neles e
ambos oferecem recursos de layout dinâmico em tempo de execução, para que eles
possam redimensionar e reposicionar os controles filho conforme as dimensões do
formulário pai se alteram. Os painéis de layout podem ser aninhados em painéis de
layout, para permitir a realização de interfaces do usuário sofisticadas.
O TableLayoutPanel organiza seu conteúdo em uma grade, fornecendo funcionalidade

semelhante ao elemento de tabela> HTML<. Suas células são organizadas em linhas e
colunas, que podem ter diferentes tamanhos. Para obter mais informações, consulte
Passo a passo: organizando controles nos Windows Forms usando um TableLayoutPanel.
O FlowLayoutPanel organiza seu conteúdo em uma direção de fluxo específica:

horizontal ou vertical. Seu conteúdo pode ser encapsulado de uma linha à outra ou de
uma coluna à próxima. Como alternativa, seu conteúdo pode ser recortado, em vez de
encapsulado. As tarefas ilustradas neste passo a passo incluem:
Criação de um projeto dos Windows Forms
Organizando controles horizontalmente e verticalmente
Alterando a direção do fluxo
Inserindo quebras de fluxo
Organizando controles usando preenchimento e margens
Inserindo controles ao clicar duas vezes neles na caixa de ferramentas
Inserindo um controle ao desenhar seu contorno

Inserindo controles usando o sinal de interpolação
Reatribuição de controles existentes a um pai diferente
Quando terminar, você terá uma compreensão da função desempenhada por esses
recursos de layout importantes.
Criar o projeto
"FlowLayoutPanelExample" (Arquivo>Novo>Projeto>Visual C# ou Visual
Basic>Classic Desktop>Windows Forms Aplicativo).
2. Selecione o formulário no Designer de Formulários.
Organizando controles horizontalmente e

verticalmente
O FlowLayoutPanel controle permite que você coloque controles ao longo de linhas ou
colunas sem exigir que você especifique precisamente a posição de cada controle
individual.
O FlowLayoutPanel controle pode redimensionar ou refluxar seus controles filho à

medida que as dimensões do formulário pai mudam.
Para organizar controles horizontalmente e verticalmente

usando um FlowLayoutPanel
1. Arraste um FlowLayoutPanel controle da Caixa de Ferramentas para o formulário.
2. Arraste um Button controle da Caixa de Ferramentas para o FlowLayoutPanel.

Observe que ele é movido automaticamente para o canto superior esquerdo do
3. Arraste outro Button controle da Caixa de Ferramentas para o FlowLayoutPanel.

Observe que o Button controle é movido automaticamente para uma posição ao
lado do primeiro Button controle. Se for FlowLayoutPanel muito estreito para
ajustar os dois controles na mesma linha, o novo Button controle será movido
automaticamente para a próxima linha.
4. Arraste vários outros Button controles da Caixa de Ferramentas para o

FlowLayoutPanel. Continue colocando Button controles até que um seja
encapsulado para a próxima linha.
5. Altere o valor da propriedade FlowLayoutPanel do controle WrapContents para

false . Observe que os controles filho não fluem mais para a próxima linha. Em vez
disso, eles são movidos para a primeira linha e recortados.
6. Altere o valor da propriedade FlowLayoutPanel do controle WrapContents para

true . Observe que os controles filho quebram novamente para a próxima linha.
7. Diminua a largura do FlowLayoutPanel controle até que todos os Button controles

sejam movidos para a primeira coluna.
8. Aumente a largura do FlowLayoutPanel controle até que todos os Button controles

sejam movidos para a primeira linha. Você pode precisar redimensionar o
formulário para acomodar a largura maior.
Alterando a direção do fluxo

A FlowDirection propriedade permite que você altere a direção na qual os controles são
organizados. Você pode organizar os controles filho da esquerda para a direita, da
direita para a esquerda, de cima para baixo ou de baixo para cima.
Para alterar a direção do fluxo em um FlowLayoutPanel

1. Altere o valor da propriedade FlowLayoutPanel do controle FlowDirection para
TopDown. Observe que os controles filho são reorganizados em uma ou mais
colunas, dependendo da altura do controle.
2. Redimensione o FlowLayoutPanel para que sua altura seja menor que a coluna de
Button controles. Observe que o FlowLayoutPanel reorganiza os controles filho
para fluir para a próxima coluna. Continue a diminuir a altura e observe que os
controles filho fluem para colunas consecutivas. Altere o valor da propriedade
FlowLayoutPanel do controle FlowDirection para RightToLeft. Observe que as
posições dos controles filho são revertidas. Observe o layout quando você altera o
valor da FlowDirection propriedade para BottomUp.
Inserindo quebras de fluxo

O FlowLayoutPanel controle fornece uma propriedade FlowBreak para seus controles
filho. Definir o valor da propriedade FlowBreak como true faz com que o
FlowLayoutPanel controle pare de definir controles na direção do fluxo atual e
encapsule para a próxima linha ou coluna.
Para inserir quebras de fluxo

1. Altere o valor da propriedade FlowLayoutPanel do controle FlowDirection para
TopDown.
2. Selecione um dos Button controles no meio da coluna mais à esquerda.
3. Defina o valor da Button propriedade FlowBreak do controle como true . Observe

que a coluna está quebrada e os controles após o fluxo de controle selecionado
Button para a próxima coluna. Defina o valor da Button propriedade FlowBreak do
controle como para false retornar ao comportamento original.
Posicionando controles usando encaixe e

ancoragem
Os comportamentos de encaixe e ancoragem dos controles filho diferem dos
comportamentos em outras caixas de controles. O encaixe e a ancoragem são relativos
ao maior controle na direção do fluxo.
Para posicionar controles usando encaixe e ancoragem

1. Aumente o tamanho do até que FlowLayoutPanel todos os Button controles sejam
organizados em uma coluna.
2. Selecione o controle superior Button . Aumente sua largura para que ela tenha
cerca de duas vezes mais largura do que os outros Button controles.
3. Selecione o segundo Button controle. Altere o valor de sua Anchor propriedade

para Right. Observe que ele é movido para que sua borda direita seja alinhada
com a borda direita do primeiro Button controle.
4. Altere o valor de sua Anchor propriedade para Right e Left. Observe que ele é
dimensionado com a mesma largura que o primeiro Button controle.
5. Selecione o terceiro Button controle. Altere o valor de sua Dock propriedade para
Fill. Observe que ele é dimensionado com a mesma largura que o primeiro Button
controle.
Organizando controles usando preenchimento
e margens
Você também pode organizar controles em seu FlowLayoutPanel controle alterando as
Padding propriedades e Margin .
A Padding propriedade permite controlar o posicionamento de controles dentro da

célula de um FlowLayoutPanel controle. Ele especifica o espaçamento entre os controles
filho e a FlowLayoutPanel borda do controle.
A Margin propriedade permite controlar o espaçamento entre controles.
Para organizar controles usando as propriedades de

preenchimento e margem
1. Altere o valor da propriedade FlowLayoutPanel do controle Dock para Fill. Se o
formulário for grande o suficiente, os Button controles serão movidos para a
primeira coluna do FlowLayoutPanel controle.
2. Altere o valor da FlowLayoutPanel propriedade do Padding controle expandindo a

Padding entrada na janela Propriedades e definindo a All propriedade como 20.
Para obter mais informações, consulte Passo a passo: definindo o layout de
controles dos Windows Forms com preenchimento, margens e a propriedade
AutoSize. Observe que os controles filho são movidos para o centro do
FlowLayoutPanel controle. O valor aumentado para a Padding propriedade afasta
os controles filho das FlowLayoutPanel bordas do controle.
3. Selecione todos os Button controles no FlowLayoutPanel e defina o valor da

Margin propriedade como 20. Observe que o espaçamento entre os Button
controles aumenta, portanto, eles são movidos mais distantes. Talvez seja
necessário redimensionar o FlowLayoutPanel controle para ser maior para ver
todos os controles filho.
Inserindo controles ao clicar duas vezes neles

na caixa de ferramentas
Você pode preencher o FlowLayoutPanel controle clicando duas vezes em controles na
Caixa de Ferramentas.
Para inserir controles clicando duas vezes na caixa de
ferramentas
que um novo Button controle aparece no FlowLayoutPanel controle .
2. Clique duas vezes em vários outros controles na Caixa de ferramentas. Observe

que os novos controles aparecem sucessivamente no FlowLayoutPanel controle .
Inserindo um controle ao desenhar seu

contorno
Você pode inserir um controle em um FlowLayoutPanel controle e especificar seu
tamanho desenhando sua estrutura de tópicos em uma célula.
Para inserir um controle desenhando seu contorno

formulário.
2. Mova o ponteiro do mouse sobre o FlowLayoutPanel controle. Observe que o

ponteiro muda para uma mira com o Button ícone de controle anexado.
4. Arraste o ponteiro do mouse para desenhar a estrutura de tópicos do Button

controle. Quando estiver satisfeito com o tamanho, solte o botão do mouse.
Observe que o Button controle é criado no próximo local aberto do
Inserindo controles usando a barra de inserção

Você pode inserir controles em uma posição específica em um FlowLayoutPanel
controle . Quando você arrasta um controle para a FlowLayoutPanel área do cliente do
controle, uma barra de inserção é exibida para indicar onde o controle será inserido.
Para inserir um controle usando o sinal de interpolação

1. Arraste um Button controle da Caixa de Ferramentas para o FlowLayoutPanel
controle e aponte para o espaço entre dois Button controles. Observe que uma
barra de inserção é desenhada, indicando onde o Button será colocado quando for
solto no FlowLayoutPanel controle. Antes de soltar o novo Button controle no
FlowLayoutPanel controle, mova o ponteiro do mouse para observar como a barra
de inserção se move.
2. Solte o novo Button controle no FlowLayoutPanel controle . Observe que o novo

Button controle não está alinhado com os outros, pois sua Margin propriedade
tem um valor diferente.
Reatribuição de controles existentes a um pai

diferente
Você pode atribuir controles existentes em seu formulário a um novo FlowLayoutPanel
controle.
Para reassociar os controles existentes

1. Arraste três Button controles da Caixa de Ferramentas para o formulário.
Posicione-os próximo entre si, mas deixe-os desalinhados.
2. Na Caixa de Ferramentas, clique no ícone de FlowLayoutPanel controle. Não o

arraste para o formulário.
3. Mova o ponteiro do mouse para perto dos três Button controles. Observe que o
ponteiro muda para uma mira com o FlowLayoutPanel ícone de controle anexado.
5. Arraste o ponteiro do mouse para desenhar a estrutura de tópicos do

FlowLayoutPanel controle. Desenhe a estrutura de tópicos em torno dos três
Button controles.
6. Solte o botão do mouse. Observe que os três Button controles são inseridos no
FlowLayoutPanel controle .
Próximas etapas
Você pode obter um layout complexo usando uma combinação de controles e painéis
de layout. Sugestões para exploração adicional incluem:
Redimensione um dos Button controles para um tamanho maior e observe o efeito

no layout.
Os painéis de layout podem conter outros painéis de layout. Experimente remover
um TableLayoutPanel controle no controle existente.
Encaixe o FlowLayoutPanel controle no formulário pai. Redimensione o formulário

e observe o efeito no layout.
Defina a Visible propriedade de um dos controles como false e observe como o

FlowLayoutPanel refluxo é refluxo em resposta.
Confira também
FlowLayoutPanel
TableLayoutPanel
TableLayoutPanel
de alinhamento
(Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms FolderBrowserDialog exibe uma interface com a qual os

usuários podem procurar e selecionar uma pasta ou criar uma nova. Ele é um
complemento para o componente Componente OpenFileDialog , que é usado para
navegar e selecionar arquivos.
Nesta seção
Como: Escolher pastas com o componente FolderBrowserDialog do Windows Forms

Explica como extrair programaticamente a pasta selecionada da caixa de diálogo, bem
como trabalhar com algumas das outras propriedades opcionais do componente.
Referência
FolderBrowserDialog
Fornece uma lista de tarefas para caixas de diálogo, que geralmente exibem guias.

FolderBrowserDialog (Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms FolderBrowserDialog é uma caixa de diálogo modal

usada para navegar e selecionar pastas. Novas pastas também podem ser criadas de
dentro do FolderBrowserDialog componente.
７ Observação
Para selecionar arquivos, em vez de pastas, use o componente OpenFileDialog .
O FolderBrowserDialog componente é exibido em tempo de execução usando o

ShowDialog método. Defina a RootFolder propriedade para determinar a pasta mais alta
e todas as subpastas que aparecerão na exibição de árvore da caixa de diálogo. Depois
que a caixa de diálogo for mostrada, você poderá usar a SelectedPath propriedade para
obter o caminho da pasta que foi selecionada.
Quando ele é adicionado a um formulário, o FolderBrowserDialog componente aparece

na bandeja na parte inferior do Designer de Windows Forms no Visual Studio.
Confira também
FolderBrowserDialog
Como: Escolher pastas com o componente FolderBrowserDialog do Windows
Forms
Como: Escolher pastas com o
componente FolderBrowserDialog do
Windows Forms
Artigo • 02/06/2023
Muitas vezes, dentro de aplicativos do Windows que você criou, será necessário solicitar
que os usuários selecionem uma pasta e com mais frequência que eles salvem um
conjunto de arquivos. O componente Windows Forms FolderBrowserDialog permite que
você realize essa tarefa facilmente.
Escolher pastas com o componente FolderBrowserDialog

1. Em um procedimento, verifique a propriedade
FolderBrowserDialogDialogResultFolderBrowserDialog do componente para ver
como a caixa de diálogo foi fechada e obter o valor da propriedade do
SelectedPath componente.
2. Se você precisar definir a pasta mais alta que aparecerá na exibição de árvore da
caixa de diálogo, RootFolder de definir a propriedade , que recebe um membro da
Environment.SpecialFolder enumeração .
3. Além disso, você pode definir a propriedade Description , que especifica a cadeia
de caracteres de texto que aparece na parte superior do exibição de árvore do
navegador de pastas.
No exemplo a seguir, FolderBrowserDialog o componente é usado para selecionar

uma pasta, semelhante a quando você cria um projeto no Visual Studio e é
solicitado a selecionar uma pasta para salvá-la. Neste exemplo, o nome da pasta é
exibido em um controle TextBox no formulário. É uma boa ideia colocar o local em
uma área editável, como um controle, para que os usuários possam editar sua
TextBox seleção em caso de erro ou outros problemas. Este exemplo assume um
formulário com um componente FolderBrowserDialog e um TextBox controle .
C#
public void ChooseFolder()

{
if (folderBrowserDialog1.ShowDialog() == DialogResult.OK)
{
textBox1.Text = folderBrowserDialog1.SelectedPath;
}
}
） Importante
Para usar essa classe, o assembly requer um nível de privilégio concedido

PathDiscovery pela propriedade , que faz parte da FileIOPermissionAccess
enumeração . Se você estiver executando em um contexto de confiança
parcial, o processo poderá gerar uma exceção em razão dos privilégios
insuficientes. Para obter mais informações, consulte Noções Básicas da
Segurança de Acesso do Código.
Para obter informações sobre como salvar arquivos, consulte Como salvar arquivos
usando o componente SaveFileDialog.
Confira também
FolderBrowserDialog
Componente FontDialog (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms FontDialog é uma caixa de diálogo pré-configurada. É a

mesma caixa de diálogo Fonte exposta pelo sistema operacional Windows. O
componente herda da CommonDialog classe.
Nesta seção
Apresenta os conceitos gerais do FontDialog componente, que você usa para exibir uma
caixa de diálogo pré-configurada. Os usuários podem usar a caixa de diálogo para
manipular fontes e suas configurações.
Como: Mostrar uma lista de fontes ao componente FontDialog

Explica como escolher uma fonte em tempo de execução por meio de uma instância do
FontDialog componente.
Referência
FontDialog
Fornece informações de referência sobre a FontDialog classe e seus membros.
Descreve um conjunto de controles e componentes que permitem que os usuários
executem interações padrão com o aplicativo ou sistema.

Fornece uma lista completa de controles Windows Forms, com links para informações
sobre seu uso.
(Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms FontDialog é uma caixa de diálogo pré-configurada,

que é a caixa de diálogo padrão da Fonte do Windows usada para expor as fontes que
estão instaladas atualmente no sistema. Use-o em seu aplicativo baseado no Windows
como uma solução simples para seleção de fonte em vez de configurar sua própria caixa
de diálogo.
Por padrão, a caixa de diálogo mostra caixas de listagem de Fonte, Estilo da fonte e
Tamanho. Caixas de seleção para efeitos como Riscado e Sublinhado; uma lista suspensa
para Script e um exemplo de como a fonte aparecerá. (Script refere-se a scripts de
caracteres diferentes que estão disponíveis para uma determinada fonte, por exemplo,
hebraico ou japonês.) Para exibir a caixa de diálogo fonte, chame o ShowDialog método.
O componente tem inúmeras propriedades que configuram sua aparência. As
propriedades que definem as seleções da caixa de diálogo são Font e Color. A Font
propriedade define a fonte, o estilo, o tamanho, o script e os efeitos; por exemplo,
Arial, 10pt, style=Italic, Strikeout .
Confira também
FontDialog
Como: Mostrar uma lista de fontes ao
componente FontDialog
Artigo • 21/06/2023
O componente FontDialog permite aos usuários selecionar uma fonte, bem como
alterar seus aspectos de exibição, como peso e tamanho.
A fonte selecionada na caixa de diálogo é retornada na Font propriedade . Assim, tirar

proveito da fonte selecionada pelo usuário é tão fácil quanto ler uma propriedade.
Para selecionar as propriedades de fonte usando o

componente FontDialog
1. Exiba a caixa de diálogo usando o ShowDialog método .
2. Use a DialogResult propriedade para determinar como a caixa de diálogo foi

fechada.
3. Use a Font propriedade para definir a fonte desejada.
No exemplo a seguir, o Button manipulador de eventos do Click controle abre um

FontDialog componente . Quando uma fonte é escolhida e o usuário clica em OK,
a Font propriedade de um TextBox controle que está no formulário é definida
como a fonte escolhida. O exemplo pressupõe que seu formulário tenha um
Button controle, um TextBox controle e um FontDialog componente.
C#

{
if(fontDialog1.ShowDialog() == DialogResult.OK)
{
textBox1.Font = fontDialog1.Font;
}
}
(Visual C# e Visual C++) Coloque o código a seguir no construtor do formulário

C#

Confira também
FontDialog
Controle GroupBox (Windows Forms)
Artigo • 02/06/2023
GroupBox Windows Forms controles são usados para fornecer um agrupamento

identificável para outros controles. Normalmente, você usa caixas de grupo para
subdividir um formulário por função. Por exemplo, você pode ter um formulário de
pedido que especifica as opções de mala direta, como qual carrier noturna usar.
Agrupar todas as opções em uma caixa de grupo dá ao usuário uma indicação visual
lógica. O GroupBox controle é semelhante ao Panel controle; no entanto, apenas o
GroupBox controle exibe uma legenda e apenas o Panel controle pode ter barras de
rolagem.
Nesta seção
Visão geral do controle GroupBox
Como: Agrupar controles com o controle GroupBox do Windows Forms

Descreve como usar esse controle para agrupar controles.
Referência
GroupBox
Panel
(Windows Forms)
Artigo • 02/06/2023
GroupBox Windows Forms controles são usados para fornecer um agrupamento

identificável para outros controles. Normalmente, você usa caixas de grupo para
subdividir um formulário por função. Por exemplo, você pode ter um formulário de
pedido que especifica as opções de mala direta, como qual carrier noturna usar.
Agrupar todas as opções em uma caixa de grupo fornece ao usuário uma indicação
visual lógica e, em tempo de design, todos os controles podem ser movidos facilmente
– quando você move o controle único GroupBox , todos os controles contidos também
se movem.
A legenda da caixa de grupo é definida pela Text propriedade. Para obter mais
informações, consulte Como definir o texto exibido por um controle dos Windows
Forms.
GroupBox e Painel
O GroupBox controle é semelhante ao Panel controle; no entanto, apenas o GroupBox
controle exibe uma legenda e somente o Panel controle pode ter barras de rolagem.
Confira também
Controle GroupBox
Como: Agrupar controles com o
controle GroupBox do Windows Forms
Artigo • 02/06/2023
Windows forms GroupBox são usados para agrupar outros controles. Há três razões
para agrupar controles:
Para criar um agrupamento visual dos elementos de formulário relacionados para

uma interface do usuário clara.
Para criar um agrupamento programático (de botões de opção, por exemplo).
Para mover os controles como uma unidade em tempo de design.
Para criar um grupo de controles

1. Desenhar um GroupBox controle em um formulário.
2. Adicione outros controles à caixa de grupo desenhando cada um deles dentro da

caixa de grupo.
Se você tiver controles existentes que deseja incluir em uma caixa de grupo,
poderá selecionar todos os controles, recortá-los para a Área de Transferência,
GroupBox selecionar o controle e, em seguida, colar-los na caixa de grupo. Você
também pode arrastá-los para a caixa de grupo.
3. De definir Text a propriedade da caixa de grupo como uma legenda apropriada.
Confira também
GroupBox
Controle GroupBox
Componente HelpProvider (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms HelpProvider é usado para associar um arquivo de

ajuda html help 1.x (um arquivo .chm, produzido com o HTML Help Workshop ou um
arquivo .htm) ao seu aplicativo baseado no Windows.
Nesta seção
Visão geral do componente HelpProvider
Apresenta os conceitos gerais do componente, que HelpProvider permite associar um
arquivo de Ajuda HTML a um aplicativo baseado no Windows.
Consulte Sistemas de Ajuda em aplicativos Windows Forms.
Referência
HelpProvider
Help
Consulte também sistemas de ajuda em aplicativos Windows Forms.

HelpProvider (Windows Forms)
Artigo • 02/06/2023
O componente HelpProvider dos Windows Forms é usado para associar um arquivo da

Ajuda HTML 1.x (um arquivo .chm, produzido com o Workshop de Ajuda HTML ou um
arquivo .htm) ao seu aplicativo do Windows. É possível fornecer ajuda de várias
maneiras:
Fornece Ajuda contextual para controles nos Windows Forms.
Fornece Ajuda contextual em uma caixa de diálogo específica ou controles

específicos em uma caixa de diálogo.
Abra um arquivo de Ajuda para áreas específicas, como a página principal de um

sumário, índice ou uma função de pesquisa.
Usando o provedor de ajuda

A adição de um HelpProvider componente ao Formulário do Windows permite que os
outros controles no formulário exponham as propriedades de Ajuda do HelpProvider
componente. Isso habilita você a fornecer ajuda para os controles no seu Windows
Form. Você pode associar um arquivo de Ajuda ao HelpProvider componente usando a
HelpNamespace propriedade. Especifique o tipo de Ajuda fornecida chamando
SetHelpNavigator e fornecendo um valor da HelpNavigator enumeração para o controle
especificado. Você fornece a palavra-chave ou tópico para Ajuda chamando o
SetHelpKeyword método.
Opcionalmente, para associar uma cadeia de caracteres de Ajuda específica a outro

controle, use o SetHelpString método. A cadeia de caracteres associada a um controle
usando esse método é exibida em uma janela pop-up quando o usuário pressiona a
tecla F1 enquanto o controle tem o foco.
Se HelpNamespace não tiver sido definido, você deverá usar SetHelpString para
fornecer o texto da Ajuda. Se você tiver definido ambas as HelpNamespace cadeias de
caracteres de Ajuda, a Ajuda com base HelpNamespace terá precedência.
７ Observação
Você pode encontrar problemas ao usar o caminho relativo ao especificar o
caminho para o arquivo de Ajuda no ShowHelp método ou HelpNamespace na
propriedade do HelpProvider controle. Por isso, verifique se você usou o caminho
de arquivo absoluto para especificar o arquivo de Ajuda.
Confira também
Sistemas de Ajuda em aplicativos do Windows Forms
Controles HScrollBar e VScrollBar
(Windows Forms)
Artigo • 02/06/2023
Windows Forms controles de barra de rolagem são usados para fornecer navegação
fácil por meio de uma longa lista de itens ou uma grande quantidade de informações
rolando horizontal ou verticalmente dentro de um aplicativo ou controle. Barras de
rolagem são um elemento comum da interface do Windows.
Nesta seção
Visão geral dos controles HScrollBar e VScrollBar
Apresenta os conceitos gerais dos controles e VScrollBar dos HScrollBar controles, que
permitem que os usuários rolem horizontal e verticalmente por grandes quantidades de
informações.
Referência
HScrollBar
VScrollBar
Visão geral dos controles HScrollBar e
VScrollBar (Windows Forms)
Artigo • 21/06/2023
ScrollBar Windows Forms controles são usados para fornecer navegação fácil por meio
de uma longa lista de itens ou uma grande quantidade de informações rolando
horizontal ou verticalmente dentro de um aplicativo ou controle. As barras de rolagem
são um elemento comum da interface do Windows, portanto, o ScrollBar controle
geralmente é usado com controles que não derivam da ScrollableControl classe . Da
mesma forma, muitos desenvolvedores optam por incorporar o ScrollBar controle ao
criar seus próprios controles de usuário.
Os HScrollBar controles (horizontal) e VScrollBar (vertical) operam independentemente

de outros controles e têm seu próprio conjunto de eventos, propriedades e métodos.
ScrollBar os controles não são iguais às barras de rolagem internas anexadas a caixas de
texto, caixas de listagem, caixas de combinação ou formulários MDI (o TextBox controle
tem uma ScrollBars propriedade para mostrar ou ocultar barras de rolagem anexadas ao
controle).
Os ScrollBar controles usam o Scroll evento para monitorar o movimento da caixa de

rolagem (às vezes chamada de polegar) ao longo da barra de rolagem. O uso do Scroll
evento fornece acesso ao valor da barra de rolagem enquanto ele está sendo arrastado.
Propriedade Value
A Value propriedade (que, por padrão, é 0) é um integer valor correspondente à
posição da caixa de rolagem na barra de rolagem. Quando a posição da caixa de
rolagem é o valor mínimo, ela se move para a posição mais à esquerda (para barras de
rolagem horizontais) ou a posição superior (para barras de rolagem verticais). Quando a
caixa de rolagem está no valor máximo, ela se move para a posição mais à direita ou
para a posição inferior. Da mesma forma, um valor entre a parte inferior e superior do
intervalo coloca a borda esquerda da caixa de rolagem no meio da barra de rolagem.
Além de usar cliques do mouse para alterar o valor da barra de rolagem, um usuário
também pode arrastar a caixa de rolagem para qualquer ponto ao longo da barra. O
valor resultante depende da posição da caixa de rolagem, mas está sempre dentro do
intervalo das Minimum propriedades to Maximum definidas pelo usuário.
Propriedades de SmallChange e LargeChange

Quando o usuário pressiona a tecla PAGE UP ou PAGE DOWN ou clica na faixa da barra
de rolagem em ambos os lados da caixa de rolagem, a Value propriedade muda de
acordo com o valor definido na LargeChange propriedade .
Quando o usuário pressiona uma das teclas de direção ou clica em um dos botões da
barra de rolagem, a Value propriedade muda de acordo com o valor definido na
SmallChange propriedade .
Confira também
HScrollBar
VScrollBar
Componente ImageList (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms ImageList é usado para armazenar imagens, que

podem ser exibidas por controles. Uma lista de imagens permite escrever código para
um catálogo de imagens único e consistente.
Nesta seção
Visão geral do componente ImageList
Explica o que é esse componente e seus principais recursos e propriedades
Como: Adicionar ou remover imagens com o componente ImageList do Windows Forms

Fornece instruções para adicionar e remover imagens de uma lista de imagens.
Veja também como adicionar ou remover imagens imagelist com o Designer.
Referência
ImageList
(Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms ImageList é usado para armazenar imagens, que podem
ser exibidas por controles. Uma lista de imagens permite escrever código para um
catálogo de imagens único e consistente. Por exemplo, você pode girar imagens
exibidas por um Button controle simplesmente alterando a propriedade ou ImageKey o
ImageIndex botão. Você também pode associar a mesma lista de imagem a vários
controles. Por exemplo, se você estiver usando um ListView controle e um TreeView
controle para exibir a mesma lista de arquivos, alterar o ícone de um arquivo na lista de
imagens fará com que o novo ícone apareça em ambos os modos de exibição.
Usando ImageList com controles

Você pode usar uma lista de imagens com qualquer controle que tenha uma ImageList
propriedade – ou no caso do ListView controle SmallImageList e LargeImageList
propriedades. Os controles que podem ser associados a uma lista de imagens incluem:
os ListViewcontroles , , TreeView, ToolBar, TabControl, Button, CheckBoxRadioButtone
Label os controles. Para associar a lista de imagens a um controle, defina a propriedade
do ImageList controle como o nome do ImageList componente.
A propriedade chave do ImageList componente é Images, que contém as imagens a
serem usadas pelo controle associado. Cada imagem individual pode ser acessada pelo
seu valor de índice ou por sua chave. A ColorDepth propriedade determina o número de
cores com as quais as imagens são renderizadas. Todas as imagens serão exibidas no
mesmo tamanho, definidas pela ImageSize propriedade. Imagens maiores terão a escala
ajustada para caber.
Confira também
ImageList
Como: Adicionar ou remover imagens com o componente ImageList do Windows
Forms
Como: Adicionar ou remover imagens
com o componente ImageList do
Windows Forms
Artigo • 02/06/2023
O componente Windows Forms ImageList normalmente é preenchido com imagens

antes de ser associado a um controle. No entanto, você pode adicionar e remover
imagens depois de associar a lista de imagens a um controle.
７ Observação
Ao remover imagens, verifique se a ImageIndex propriedade de quaisquer

controles associados ainda é válida.
Para adicionar imagens de forma programática

Use o Add método da propriedade da lista de Images imagens.
No exemplo de código a seguir, o caminho definido para o local da imagem é a

pasta Meus documentos. Esse local é usado porque você pode supor que a
maioria dos computadores que executam o sistema operacional Windows inclui
essa pasta. Escolher esse local também permite que os usuários que têm níveis de
acesso ao sistema mínimos executem com mais segurança o aplicativo. O exemplo
de código a seguir requer que você tenha um formulário com um ImageList
controle já adicionado.
C#
public void addImage()

{
// Be sure that you use an appropriate escape sequence (such as the
// @) when specifying the location of the file.
System.Drawing.Image myImage =
Image.FromFile
(System.Environment.SpecialFolder.Personal)
+ @"\Image.gif");
imageList1.Images.Add(myImage);
}
Para adicionar imagens com um valor de chave.
Use um dos Add métodos da propriedade da lista de Images imagens que usa um
valor de chave.

maioria dos computadores que executam o sistema operacional Windows inclui
essa pasta. Escolher esse local também permite que os usuários que têm níveis de
acesso ao sistema mínimos executem com mais segurança o aplicativo. O exemplo
de código a seguir requer que você tenha um formulário com um ImageList
controle já adicionado.
VB
Public Sub LoadImage()

Dim myImage As System.Drawing.Image = _
Image.FromFile _
(System.Environment.GetFolderPath _
(System.Environment.SpecialFolder.Personal) _
& "\Image.gif")
ImageList1.Images.Add("myPhoto", myImage)
End Sub
C#
public void addImage()

{
// Be sure that you use an appropriate escape sequence (such as the
// @) when specifying the location of the file.
System.Drawing.Image myImage =
Image.FromFile
+ @"\Image.gif");
imageList1.Images.Add("myPhoto", myImage);
}
Para remover todas as imagens de forma programática

Usar o Remove método para remover uma única imagem
,-ou-
Use o Clear método para limpar todas as imagens na lista de imagens.

VB
' Removes the first image in the image list

ImageList1.Images.Remove(myImage)
' Clears all images in the image list
ImageList1.Images.Clear()
C#
// Removes the first image in the image list.

imageList1.Images.Remove(myImage);
// Clears all images in the image list.
imageList1.Images.Clear();
Para remover imagens por chave

Use o RemoveByKey método para remover uma única imagem por sua chave.
VB
' Removes the image named "myPhoto" from the list.

ImageList1.Images.RemoveByKey("myPhoto")
C#
// Removes the image named "myPhoto" from the list.

imageList1.Images.RemoveByKey("myPhoto");
Confira também
Imagens, bitmaps e metarquivos
Como: Adicionar ou remover imagens
ImageList com o Designer
Artigo • 02/06/2023
Você pode adicionar imagens a um ImageList componente de várias maneiras

diferentes. Você pode adicionar imagens muito rapidamente usando a marca inteligente
associada ImageListao , ou se você estiver definindo várias outras propriedades no
ImageList, você pode achar mais conveniente adicionar imagens com o janela
Propriedades. Também é possível adicionar imagens usando o código. Para obter mais
informações sobre como adicionar imagens com o código, consulte Como adicionar ou
remover imagens com o componente ImageList dos Windows Forms. Normalmente,
você preenche o ImageList componente com imagens antes que ele seja associado a
um controle, mas isso não é necessário.
Para adicionar ou remover imagens usando a janela

Propriedades
1. Selecione o ImageList componente ou adicione um ao formulário.
2. No janela Propriedades, clique no botão de reticências ( ) ao lado da Images

propriedade.
3. No Editor de coleção de imagens, clique em Adicionar ou Remover para adicionar

ou remover imagens da lista.
Para adicionar ou remover imagens usando a smart tag

1. Selecione o ImageList componente ou adicione um ao formulário.
2. Clique no glifo de ações do designer ( )
3. Na caixa de diálogo Tarefas ImageList, selecione Escolher imagens.
4. No Editor de coleção de imagens, clique em Adicionar ou Remover para adicionar

ou remover imagens da lista.
Confira também
Imagens, bitmaps e metarquivos
Passo a passo: executar tarefas comuns usando ações de designer
Controle Label (Windows Forms)
Artigo • 02/06/2023
） Importante
O ToolStripLabel controle substitui e adiciona funcionalidade ao Label controle.

Você pode usar com ToolStripLabel outros novos controles, como o
ToolStripDropDown. No entanto, o Label controle será retido para compatibilidade
com versões anteriores e uso futuro, se você escolher.
Label Windows Forms controles são usados para exibir texto ou imagens que não
podem ser editadas pelo usuário. Eles são usados para identificar objetos em um
formulário para fornecer uma descrição do que um determinado controle fará se
clicado, por exemplo, ou para exibir informações em resposta a um evento ou processo
em tempo de execução em seu aplicativo. Como o Label controle não pode receber o
foco, ele também pode ser usado para criar chaves de acesso para outros controles.
Nesta seção
Visão geral do controle de rótulo
Como: Criar chaves de acesso com controles de rótulo do Windows Forms

Descreve como usar um rótulo para definir uma chave de acesso para outro controle.
Como: Dimensionar um controle de rótulo do Windows Forms para encaixar o conteúdo

Explica como ajustar o tamanho de um controle de rótulo para sua legenda.
Referência
Label
(Windows Forms)
Artigo • 02/06/2023
Label Windows Forms controles são usados para exibir texto ou imagens que não
podem ser editadas pelo usuário. Eles são usados para identificar objetos em um
formulário — fornecendo uma descrição do que acontecerá se um determinado
controle for clicado, por exemplo ou exibindo informações em resposta a um evento em
tempo de execução ou processo em seu aplicativo. Por exemplo, você pode usar rótulos
para adicionar legendas descritivas em caixas de texto, caixas de listagem, caixas de
combinação e assim por diante. Também é possível escrever código para alterar o texto
exibido por um rótulo em resposta a eventos em tempo de execução. Por exemplo, se o
aplicativo leva alguns minutos para processar uma alteração, é possível exibir uma
mensagem de status de processamento em um rótulo.
Trabalhando com o controle de rótulo

Como o Label controle não pode receber o foco, ele também pode ser usado para criar
chaves de acesso para outros controles. Uma tecla de acesso permite que o usuário
selecione outro controle pressionando a tecla ALT com a tecla de acesso. Para obter
mais informações, consulte Criar teclas de acesso para controles dos Windows Forms e
Como criar teclas de acesso com controles de rótulo dos Windows Forms.
A legenda exibida no rótulo está contida na Text propriedade. A TextAlign propriedade

permite que você defina o alinhamento do texto dentro do rótulo. Para obter mais
informações, consulte Como definir o texto exibido por um controle dos Windows
Forms.
Confira também
Label
Como: Dimensionar um controle de rótulo do Windows Forms para encaixar o
conteúdo
Como: Criar chaves de acesso com
controles de rótulo do Windows Forms
Artigo • 02/06/2023
Label Windows Forms controles podem ser usados para definir chaves de acesso para
outros controles. Ao definir uma tecla de acesso em um controle de rótulo, o usuário
pode pressionar a tecla ALT mais o caractere designado para mover o foco para o
controle seguinte na ordem de tabulação. Como os rótulos não podem receber o foco,
este é movido automaticamente para o próximo controle na ordem de tabulação. Use
essa técnica para atribuir teclas de acesso a caixas de texto, caixas de combinação,
caixas de listagem e grades de dados.
Atribuir uma tecla de acesso a um controle com um

rótulo
1. Desenhe o rótulo primeiro e, em seguida, desenhe o outro controle.
-ou-
Desenhe os controles em qualquer ordem e defina a TabIndex propriedade do

rótulo como uma a menos que o outro controle.
2. Defina a propriedade do UseMnemonic rótulo como true .
3. Use uma ampersand (&) na propriedade do Text rótulo para atribuir a chave de
acesso para o rótulo. Para obter mais informações, consulte Criando teclas de
acesso para controles dos Windows Forms.
７ Observação
Pode ser útil exibir o E comercial em um controle de rótulo, em vez de usá-lo

para criar teclas de acesso. Isso poderá ocorrer se você associar um controle
de rótulo a um campo em um conjunto de registros em que os dados incluem
o E comercial. Para exibir escaras em um controle de rótulo, defina a
UseMnemonic propriedade como false . Se você quiser exibir escaras e
também ter uma chave de acesso, defina a UseMnemonic propriedade true
e indique a chave de acesso com uma ampersand (&) e a ampersand para
exibir com duas escarpas.
C#
label1.UseMnemonic = true;
label1.Text = "&Print";
label2.UseMnemonic = true;
label2.Text = "&Copy && Paste";
Confira também
Como: Dimensionar um controle de rótulo do Windows Forms para encaixar o
conteúdo
Controle de rótulo
Como: Dimensionar um controle de
rótulo do Windows Forms para encaixar
o conteúdo
Artigo • 02/06/2023
O controle Windows Forms Label pode ser de linha única ou de várias linhas e pode ser
corrigido em tamanho ou pode se redimensionar automaticamente para acomodar sua
legenda. A AutoSize propriedade ajuda você a dimensionar os controles para se ajustar
a legendas maiores ou menores, o que é particularmente útil se a legenda for alterada
em tempo de execução.
Para fazer um controle de rótulo redimensionar

dinamicamente para ajustar seu conteúdo
1. Defina sua AutoSize propriedade como true .
Se AutoSize for definido como false , as palavras especificadas na Text propriedade

serão encapsuladas para a próxima linha, se possível, mas o controle não aumentará.
Confira também
Controle de rótulo
Controle LinkLabel (Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms LinkLabel permite adicionar links no estilo Web a

aplicativos Windows Forms. Você pode usar o LinkLabel controle para tudo para o qual
você pode usar o Label controle; você também pode definir parte do texto como um
link para um objeto ou página da Web.
Nesta seção
Visão geral do controle LinkLabel
Como: Alterar a aparência do controle LinkLabel do Windows Forms

Lista maneiras de especificar a cor e a sublinhação de links no estilo Da Web em rótulos
de link.
Como: Vincular a um objeto ou página da Web com o controle LinkLabel do Windows

Forms
Fornece instruções de instruções para abrir um formulário ou página da Web quando
um link é clicado.
Como: Exibir uma página da Web com um controle LinkLabel do Windows Forms (Visual
Basic)
Mostra como exibir uma página da Web no navegador padrão quando um usuário clica
em um controle Windows Forms LinkLabel .
Referência
Classe LinkLabel
Fornece uma lista completa de controles Windows Forms, com links para informações
sobre seu uso.
(Windows Forms)
Artigo • 21/06/2023
O controle Windows Forms LinkLabel permite adicionar links de estilo da Web a

aplicativos Windows Forms. Você pode usar o LinkLabel controle para tudo para o qual
você pode usar o Label controle; você também pode definir parte do texto como um
link para um arquivo, pasta ou página da Web.
O que você pode fazer com o Controle

LinkLabel
Além de todas as propriedades, métodos e eventos do Label controle, o LinkLabel
controle tem propriedades para hiperlinks e cores de link. A LinkArea propriedade
define a área do texto que ativa o link. As LinkColorpropriedades , VisitedLinkColore
ActiveLinkColor definem as cores do link. O LinkClicked evento determina o que
acontece quando o texto do link é selecionado.
O uso mais simples do LinkLabel controle é exibir um único link usando a LinkArea
propriedade , mas você também pode exibir vários hiperlinks usando a Links
propriedade . A Links propriedade permite que você acesse uma coleção de links. Você
também pode especificar dados na LinkData propriedade de cada objeto individual
LinkLabel.Link . O valor da LinkData propriedade pode ser usado para armazenar o local
de um arquivo a ser exibido ou o endereço de um site da Web.
Confira também
LinkLabel
Como: Vincular a um objeto ou página da Web com o controle LinkLabel do
Windows Forms
Como: Alterar a aparência do controle
LinkLabel do Windows Forms
Artigo • 21/06/2023
Você pode alterar o texto exibido pelo LinkLabel controle para atender a uma variedade
de finalidades. Por exemplo, é uma prática comum para indicar ao usuário que o texto é
clicável configurando o texto a ser exibido em uma cor específica com um sublinhado.
Depois que o usuário clica no texto, a cor é alterada para uma cor diferente. Para
controlar esse comportamento, você pode definir cinco propriedades diferentes: as
LinkBehaviorpropriedades , LinkArea, LinkColor, VisitedLinkColore LinkVisited .
Alterar a aparência de um controle LinkLabel

1. Defina as LinkColor propriedades e VisitedLinkColor para as cores desejadas.
Isso pode ser feito por meio de programação ou no tempo de design na janela
Propriedades.
C#
// You can set the color using decimal values for red, green, and blue
linkLabel1.LinkColor = Color.FromArgb(0, 0, 255);
// Or you can set the color using defined constants
linkLabel1.VisitedLinkColor = Color.Purple;
2. Defina a Text propriedade como uma legenda apropriada.
Isso pode ser feito por meio de programação ou no tempo de design na janela
Propriedades.
C#
linkLabel1.Text = "Click here to see more.";
3. Defina a LinkArea propriedade para determinar qual parte do legenda será

indicada como um link.
O LinkArea valor é representado com um LinkArea que contém dois números, a

posição do caractere inicial e o número de caracteres. Isso pode ser feito por meio
de programação ou no tempo de design na janela Propriedades.
C#
linkLabel1.LinkArea = new LinkArea(6,4);
4. Defina a LinkBehavior propriedade como AlwaysUnderline, HoverUnderlineou

NeverUnderline.
Se estiver definido como HoverUnderline, a parte do legenda determinada por

LinkArea só será sublinhada quando o ponteiro se basear nele.
5. No manipulador de LinkClicked eventos, defina a LinkVisited propriedade como

true .
Quando um link foi visitado, é uma prática comum alterar sua aparência de alguma
maneira, geralmente a cor. O texto será alterado para a cor especificada pela
VisitedLinkColor propriedade .
C#
protected void LinkLabel1_LinkClicked(object sender, System.EventArgs

e)
{
// Change the color of the link text by setting LinkVisited
// to True.
linkLabel1.LinkVisited = true;
// Then do whatever other action is appropriate
}
Confira também
LinkArea
LinkColor
VisitedLinkColor
LinkVisited
Como: Vincular a um objeto ou página da Web com o controle LinkLabel do
Windows Forms
Controle LinkLabel
Como: Vincular a um objeto ou página
da Web com o controle LinkLabel do
Windows Forms
Artigo • 21/06/2023
O controle Windows Forms LinkLabel permite que você crie links no estilo da Web em
seu formulário. Ao clicar no link, é possível alterar sua cor para indicar que o link foi
visitado. Para obter mais informações sobre como alterar a cor, consulte Como alterar a
aparência do controle LinkLabel do Windows Forms.
Vinculando a outro formulário
Vincular a outro formulário com um controle LinkLabel


indicada como um link. Como isso é indicado depende das propriedades
relacionadas à aparência do rótulo do link. O LinkArea valor é representado por
um LinkArea objeto que contém dois números, a posição do caractere inicial e o
número de caracteres. A LinkArea propriedade pode ser definida no janela
Propriedades ou no código de maneira semelhante à seguinte:
C#
// In this code example, the link area has been set to begin
// at the first character and extend for eight characters.
// You may need to modify this based on the text entered in Step 1.
linkLabel1.LinkArea = new LinkArea(0,8);
3. LinkClicked No manipulador de eventos, invoque o Show método para abrir outro

formulário no projeto e defina a LinkVisited propriedade como true .
７ Observação
Uma instância da LinkLabelLinkClickedEventArgs classe carrega uma

referência ao LinkLabel controle que foi clicado, portanto, não há necessidade
de converter o sender objeto.
C#
protected void linkLabel1_LinkClicked(object sender, System.

Windows.Forms.LinkLabelLinkClickedEventArgs e)
{
// Show another form.
Form f2 = new Form();
f2.Show();
}
Vinculando a uma página da Web

O LinkLabel controle também pode ser usado para exibir uma página da Web com o
navegador padrão.
Abrir o Internet Explorer e vincular a uma página da Web com um

controle LinkLabel

indicada como um link.
3. LinkClicked No manipulador de eventos, no meio de um bloco de tratamento de

exceções, chame um segundo procedimento que define a LinkVisited propriedade
true como e usa o Start método para iniciar o navegador padrão com uma URL.
Para usar o Start método , você precisa adicionar uma referência ao

System.Diagnostics namespace .
） Importante
Se o código abaixo for executado em um ambiente de confiança parcial

(como em uma unidade compartilhada), o compilador JIT falhará quando o
método VisitLink for chamado. A System.Diagnostics.Process.Start
instrução causa uma demanda de link que falha. Ao capturar a exceção
quando o método VisitLink é chamado, o código a seguir garante que, se o
compilador JIT falhar, o erro será tratado normalmente.
C#
private void linkLabel1_LinkClicked(object sender,
System.Windows.Forms.LinkLabelLinkClickedEventArgs e)
{
try
{
VisitLink();
}
catch (Exception ex )
{
MessageBox.Show("Unable to open link that was clicked.");
}
}
private void VisitLink()

{
// Change the color of the link text by setting LinkVisited
// to true.
//Call the Process.Start method to open the default browser
//with a URL:
System.Diagnostics.Process.Start("http://www.microsoft.com");
}
Confira também
Process.Start
Controle LinkLabel
Como: Exibir uma página da Web com
um controle LinkLabel do Windows
Forms (Visual Basic)
Artigo • 02/06/2023
Este exemplo exibe uma página da Web no navegador padrão quando um usuário clica
em um controle de Windows FormsLinkLabel.
Exemplo
VB
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e _

As System.EventArgs) Handles MyBase.Load
LinkLabel1.Text = "Click here to get more info."
LinkLabel1.Links.Add(6, 4, "www.microsoft.com")
End Sub
Private Sub LinkLabel1_LinkClicked(ByVal sender As System.Object, ByVal _
e As System.Windows.Forms.LinkLabelLinkClickedEventArgs) Handles _
LinkLabel1.LinkClicked
System.Diagnostics.Process.Start(e.Link.LinkData.ToString())
End Sub
Um Formulário do Windows chamado Form1 .
Um controle LinkLabel chamado LinkLabel1 .
Uma conexão de Internet ativa.

A chamada para o Start método requer total confiança. Para obter mais informações,
consulte SecurityException.
Confira também
LinkLabel
Controle LinkLabel
Controle ListBox (Windows Forms)
Artigo • 02/06/2023
Um controle Windows Forms ListBox exibe uma lista de itens dos quais o usuário pode
selecionar um ou mais.
Nesta seção
Referência
Classe ListBox
(Windows Forms)
Artigo • 02/06/2023
Um controle Windows Forms ListBox exibe uma lista na qual o usuário pode selecionar
um ou mais itens. Se o número total de itens exceder o número que pode ser exibido,
uma barra de rolagem será adicionada automaticamente ao ListBox controle. Quando a
MultiColumn propriedade é definida como true , a caixa de listagem exibe itens em
várias colunas e uma barra de rolagem horizontal é exibida. Quando a MultiColumn
propriedade é definida como false , a caixa de listagem exibe itens em uma única
coluna e uma barra de rolagem vertical é exibida. Quando ScrollAlwaysVisible está
definida como true , a barra de rolagem é exibida independentemente do número de
itens. A SelectionMode propriedade determina quantos itens de lista podem ser
selecionados por vez.
Maneiras de alterar o controle ListBox

A SelectedIndex propriedade retorna um valor inteiro que corresponde ao primeiro item
selecionado na caixa de listagem. Você pode alterar programaticamente o item
selecionado alterando o SelectedIndex valor no código; o item correspondente na lista
aparecerá realçado no Formulário do Windows. Se nenhum item for selecionado, o
SelectedIndex valor será -1. Se o primeiro item da lista for selecionado, o SelectedIndex
valor será 0. Quando vários itens são selecionados, o SelectedIndex valor reflete o item
selecionado que aparece primeiro na lista. A SelectedItem propriedade é semelhante a
SelectedIndex, mas retorna o item em si, geralmente um valor de cadeia de caracteres. A
Count propriedade reflete o número de itens na lista e o valor da Count propriedade é
sempre um a mais do que o maior valor possível SelectedIndex porque SelectedIndex é
baseado em zero.
Para adicionar ou excluir itens em um ListBox controle, use o Addmétodo ou Remove o

ClearInsertmétodo. Como alternativa, você pode adicionar itens à lista usando a Items
propriedade em tempo de design.
Confira também
ListBox
Controle ListView (Windows Forms)
Artigo • 02/06/2023
O controle ListView do Windows Forms exibe uma lista de itens com ícones. É possível
usar uma exibição de lista para criar uma interface do usuário, como o painel direito do
Windows Explorer.
Nesta seção
Visão geral do controle ListView
Descreve esse controle e seus principais recursos e propriedades.
Como: Adicionar e remover itens com o controle ListView do Windows Forms

Descreve como adicionar ou remover itens de uma exibição de lista.
Como: Adicionar colunas ao controle ListView do Windows Forms

Descreve como criar colunas para exibir informações sobre cada item de lista.
Como: Exibir Ícones do Controle ListView do Windows Forms

Descreve como associar uma exibição de lista com uma lista de imagens apropriada
para exibir ícones grandes ou pequenos.
Como: Exibir Subitens em Colunas com o Controle ListView do Windows Forms

Descreve como exibir informações sobre cada item de lista nas colunas.
Como: Selecionar um item no controle ListView do Windows Forms

Descreve como selecionar um item com programação.
Como: Agrupar itens em um controle ListView do Windows Forms

Descreve como criar grupos para exibição categorizada e como atribuir itens a cada
grupo.
Como: Habilitar a exibição de bloco em um controle ListView do Windows Forms

Descreve como exibir os itens lado a lado, cada um deles composto por um ícone
grande e várias linhas de texto.
Como: Exibir uma marca de inserção em um controle ListView do Windows Forms

Descreve como implementar os comentários do usuário para operações do tipo
"arrastar e soltar" na qual uma marca de inserção indica o local de destino para cada
posição do ponteiro do mouse.
Como: Adicionar Recursos de Pesquisa a um Controle ListView
Descreve como localizar um item com programação usando as coordenadas de tela ou
pesquisa de texto.
Como: Habilitar exibição lado a lado em um controle ListView do Windows Forms

usando o designer

usando o Designer
Como: Adicionar colunas ao controle ListView do Windows Forms usando o

Designer
Como: Agrupar itens em um controle ListView do Windows Forms usando o

Designer
Passo a passo: Criar uma interface no estilo do Explorer com os controles ListView
e TreeView usando o Designer
Referência
Classe ListView
Como: Adicionar informações personalizadas a um controle TreeView ou ListView
(Windows Forms)
Descreve como herdar de um item em uma exibição de lista ou um nó em um modo de
exibição de árvore para adicionar os campos, métodos ou construtores de que você
precisa.
Explica o que é uma lista de imagens e seus principais recursos e propriedades.
Como: Criar uma Interface do Usuário com Vários Painéis nos Windows Forms
Fornece instruções para dispor um Windows Form com vários painéis.
Confira também
(Windows Forms)
Artigo • 02/06/2023
O controle ListView do Windows Forms exibe uma lista de itens com ícones. É possível
usar uma exibição de lista para criar uma interface do usuário, como o painel direito do
Windows Explorer. O controle tem quatro modos de exibição: LargeIcon, SmallIcon, Lista
e Detalhes.
O que você pode fazer com o Controle ListView
７ Observação
O “organizar lado a lado”, um modo de exibição adicional, está disponível apenas

nos sistemas operacionais Windows XP e Windows Server 2003. Para obter mais
informações, consulte Como Habilitar a Exibição Lado a Lado em um Controle
ListView dos Windows Forms.
O modo LargeIcon exibe ícones grandes ao lado do texto do item; os itens aparecerão
em várias colunas se o controle for grande o suficiente. O modo SmallIcon funciona da
mesma forma, mas exibe ícones pequenos. O modo de Lista exibe ícones pequenos,
mas sempre em uma única coluna. O modo de Detalhes exibe itens em várias colunas.
Para obter detalhes, consulte Como Adicionar Colunas ao Controle ListView dos
Windows Forms. O modo de exibição é determinado pela View propriedade. Todos os
modos de exibição podem exibir imagens de listas de imagens. Para obter detalhes,
consulte Como Exibir Ícones do Controle ListView dos Windows Forms.
A tabela a seguir lista alguns dos ListView membros e as exibições em que eles são
válidos.
Membro do ListView Exibir
Propriedade Alignment SmallIcon ou LargeIcon
Propriedade AutoArrange SmallIcon ou LargeIcon
Método AutoResizeColumn Details
Propriedade Columns Details ou Tile
Evento DrawSubItem Details

Membro do ListView Exibir
Método FindItemWithText Details, List ou Tile
Método FindNearestItem SmallIcon ou LargeIcon
Método GetItemAt Details ou Tile
Propriedade Groups Todos os modos de exibição, exceto List
Propriedade HeaderStyle Details.
Propriedade InsertionMark LargeIcon, SmallIcon ou Tile
A propriedade chave do ListView controle é Items, que contém os itens exibidos pelo
controle. A SelectedItems propriedade contém uma coleção dos itens atualmente
selecionados no controle. O usuário pode selecionar vários itens, por exemplo, para
arrastar e soltar vários itens de cada vez para outro controle, se a MultiSelect
propriedade estiver definida como true . O ListView controle pode exibir caixas de
seleção ao lado dos itens, se a CheckBoxes propriedade estiver definida como true .
A Activation propriedade determina que tipo de ação o usuário deve tomar para ativar
um item na lista: as opções são Standard, OneClicke TwoClick. OneClick A ativação
requer um único clique para ativar o item. TwoClick A ativação exige que o usuário
clique duas vezes para ativar o item; um único clique altera a cor do texto do item.
Standard A ativação exige que o usuário clique duas vezes para ativar um item, mas o
item não altera a aparência.
O ListView controle também dá suporte aos estilos visuais e outros recursos disponíveis
na plataforma Windows XP, incluindo agrupamento, exibição de bloco e marcas de
inserção.
Confira também
ListView
Controle ListView
Como: Selecionar um item no controle ListView do Windows Forms
Como: Exibir uma marca de inserção em um controle ListView do Windows Forms
(Windows Forms)
Como: Adicionar e remover itens com o
controle ListView do Windows Forms
Artigo • 02/06/2023
o processo de adicionar um item a um controle de Windows Forms ListView consiste

principalmente em especificar o item e atribuir propriedades a ele. A adição ou remoção
de itens de lista pode ser feita a qualquer momento.
Para adicionar itens programaticamente

1. Use o Add método da Items propriedade.
C#
// Adds a new item with ImageIndex 3

listView1.Items.Add("List item text", 3);
Para remover itens programaticamente

1. Use o RemoveAt método ou Clear da Items propriedade. O RemoveAt método
Remove um único item; o Clear método remove todos os itens da lista.
C#
// Removes the first item in the list.

listView1.Items.RemoveAt(0);
// Clears all the items.
listView1.Items.Clear();
Confira também
ListView
Controle ListView
Como: Adicionar e remover itens com o
controle ListView do Windows Forms
usando o Designer
Artigo • 02/06/2023
O processo de adicionar um item a um controle Windows Forms ListView consiste

principalmente em especificar o item e atribuir propriedades a ele. A adição ou remoção
de itens de lista pode ser feita a qualquer momento.

formulário contendo um ListView controle. Para obter informações sobre como
Para adicionar ou remover itens usando o designer

1. Selecione o controle ListView.
2. Na janela Propriedades, clique nas Reticências ( ) ao lado da Items propriedade.
O Editor de coleção de ListViewItem é exibido.
3. Para adicionar um item, clique no botão Adicionar. Em seguida, você pode definir
propriedades do novo item, como as propriedades e ImageIndex as Text
propriedades.
4. Para remover um item, selecione-o e clique no botão Remover.
Confira também
(Windows Forms)
Como: Adicionar colunas ao controle
ListView do Windows Forms
Artigo • 02/06/2023
Na exibição Detalhes, o ListView controle pode exibir várias colunas para cada item de
lista. Você pode usar as colunas para exibir ao usuário vários tipos de informações sobre
cada item de lista. Por exemplo, uma lista de arquivos pode exibir o nome do arquivo,
tipo de arquivo, tamanho e data da última modificação do arquivo. Para obter
informações sobre como preencher as colunas depois que elas são criadas, consulte
Como exibir subitens em colunas com o controle ListView Windows Forms.
Para adicionar colunas programaticamente

1. De definir a propriedade do View controle como Details.
2. Use o Add método da propriedade da exibição de Columns lista.
C#
// Set to details view.

listView1.View = View.Details;
// Add a column with width 20 and left alignment.
listView1.Columns.Add("File type", 20, HorizontalAlignment.Left);
Confira também
ListView
Controle ListView
Como: Adicionar colunas ao controle
ListView do Windows Forms usando o
Designer
Artigo • 02/06/2023
O controle Windows Forms ListView pode exibir várias colunas para cada item de lista
quando estiver na exibição Detalhes. Você pode usar as colunas para exibir vários tipos
de informações sobre cada item de lista. Por exemplo, uma lista de arquivos pode exibir
o nome do arquivo, tipo de arquivo, tamanho e data da última modificação do arquivo.
Para obter informações sobre como preencher as colunas depois que elas forem criadas,
consulte Como exibir subitens em colunas com o controle ListView dos Windows Forms.
O procedimento a seguir requer um projeto Windows Application com um formulário

que contém um ListView controle. Para obter informações sobre como configurar esse
projeto, consulte Como criar um projeto de aplicativo Windows Forms e como adicionar
controles a Windows Forms.
Para adicionar colunas no designer

1. Na janela Propriedades , defina a propriedade do View controle como Details.
2. Na janela Propriedades , clique no botão Reticências ( ) ao lado da Columns

propriedade.
O Editor de coleção ColumnHeader é exibido.
3. Use o botão Adicionar para adicionar novas colunas. Em seguida, você pode
selecionar o cabeçalho da coluna e definir seu texto (a legenda da coluna), o
alinhamento do texto e a largura.
Confira também
(Windows Forms)
Como: Adicionar Recursos de Pesquisa a
um Controle ListView
Artigo • 21/06/2023
Geralmente, ao trabalhar com uma grande lista de itens em um ListView controle, você
deseja oferecer recursos de pesquisa ao usuário. O ListView controle oferece essa
funcionalidade de duas maneiras diferentes: correspondência de texto e pesquisa de
localização.
O FindItemWithText método permite que você execute uma pesquisa de texto em uma
ListView exibição na lista ou detalhes, considerando uma cadeia de caracteres de
pesquisa e um índice inicial e final opcional. Por outro lado, o FindNearestItem método
permite que você encontre um item em um ListView ícone ou exibição de bloco,
considerando um conjunto de coordenadas x e y e uma direção a ser pesquisada.
Localizar um item usando texto

1. Crie um ListView com a View propriedade definida Details como ou Liste, em
seguida, preencha o ListView com itens.
2. Chame o FindItemWithText método , passando o texto do item que você gostaria

de encontrar.
3. O exemplo de código a seguir demonstra como criar um básico ListView,

preenchê-lo com itens e usar a entrada de texto do usuário para encontrar um
item na lista.
C#
private ListView textListView = new ListView();

private TextBox searchBox = new TextBox();
private void InitializeTextSearchListView()
{
searchBox.Location = new Point(10, 60);
textListView.Scrollable = true;
textListView.Width = 80;
textListView.Height = 50;
// Set the View to list to use the FindItemWithText method.

textListView.View = View.List;
// Populate the ListViewWithItems

textListView.Items.AddRange(new ListViewItem[]{
new ListViewItem("Amy Alberts"),
new ListViewItem("Amy Recker"),
new ListViewItem("Erin Hagens"),
new ListViewItem("Barry Johnson"),
new ListViewItem("Jay Hamlin"),
new ListViewItem("Brian Valentine"),
new ListViewItem("Brian Welker"),
new ListViewItem("Daniel Weisman") });
// Handle the TextChanged to get the text for our search.

searchBox.TextChanged += new EventHandler(searchBox_TextChanged);
// Add the controls to the form.

this.Controls.Add(textListView);
this.Controls.Add(searchBox);
}
private void searchBox_TextChanged(object sender, EventArgs e)

{
// Call FindItemWithText with the contents of the textbox.
ListViewItem foundItem =
textListView.FindItemWithText(searchBox.Text, false, 0, true);
if (foundItem != null)
{
textListView.TopItem = foundItem;
}
}
Localizar um item usando coordenadas x e y

1. Crie um ListView com a View propriedade definida SmallIcon como ou LargeIcone,
em seguida, preencha o ListView com itens.
2. Chame o FindNearestItem método, passando as coordenadas x e y desejadas e a

direção que você deseja pesquisar.
3. O exemplo de código a seguir demonstra como criar um ícone ListViewbásico,

preenchê-lo com itens e capturar o MouseDown evento para encontrar o item
mais próximo na direção de cima.
C#
ListView iconListView = new ListView();

TextBox previousItemBox = new TextBox();
private void InitializeLocationSearchListView()

{
previousItemBox.Location = new Point(150, 20);
// Create an image list for the icon ListView.

iconListView.LargeImageList = new ImageList();
iconListView.Height = 400;
// Add an image to the ListView large icon list.

iconListView.LargeImageList.Images.Add(
new Bitmap(typeof(Control), "Edit.bmp"));
// Set the view to large icon and add some items with the image
// in the image list.
iconListView.View = View.LargeIcon;
iconListView.Items.AddRange(new ListViewItem[]{
new ListViewItem("Amy Alberts", 0),
new ListViewItem("Amy Recker", 0),
new ListViewItem("Erin Hagens", 0),
new ListViewItem("Barry Johnson", 0),
new ListViewItem("Jay Hamlin", 0),
new ListViewItem("Brian Valentine", 0),
new ListViewItem("Brian Welker", 0),
new ListViewItem("Daniel Weisman", 0) });
this.Controls.Add(iconListView);
this.Controls.Add(previousItemBox);
// Handle the MouseDown event to capture user input.

iconListView.MouseDown +=
new MouseEventHandler(iconListView_MouseDown);
//iconListView.MouseWheel += new
MouseEventHandler(iconListView_MouseWheel);
}
void iconListView_MouseDown(object sender, MouseEventArgs e)

{
// Find the an item above where the user clicked.

ListViewItem foundItem =
iconListView.FindNearestItem(SearchDirectionHint.Up, e.X, e.Y);
// Display the results in a textbox..

if (foundItem != null)
previousItemBox.Text = foundItem.Text;
else
previousItemBox.Text = "No item found";
}
Confira também
ListView
FindItemWithText
FindNearestItem
Controle ListView
Como: Exibir Ícones do Controle
Artigo • 02/06/2023
O controle Windows Forms ListView pode exibir ícones de três listas de imagens. As
exibições Lista, Detalhes e SmallIcon exibem imagens da lista de imagens especificada
na SmallImageList propriedade. A exibição LargeIcon exibe imagens da lista de imagens
especificada na LargeImageList propriedade. Uma exibição de lista também pode exibir
um conjunto adicional de ícones, definido na StateImageList propriedade, ao lado dos
ícones grandes ou pequenos. Para obter mais informações sobre listas de imagens,
consulte Componente ImageList e Como adicionar ou remover imagens com o
componente ImageList dos Windows Forms.
Para exibir imagens em uma exibição de lista

1. Defina a propriedade apropriada ouSmallImageListLargeImageListStateImageList o
componente existente ImageList que você deseja usar.
Essas propriedades podem ser definidas no designer com a janela Propriedades ou

no código.
C#
listView1.SmallImageList = imageList1;
2. Defina a propriedade ou StateImageIndex a ImageIndex cada item de lista que

tenha um ícone associado.
Essas propriedades podem ser definidas no código ou no Editor de coleção

ListViewItem. Para abrir o Editor de Coleção ListViewItem, clique no botão
reticências ( ) ao lado da Items propriedade na janela Propriedades.
C#
// Sets the first list item to display the 4th image.

listView1.Items[0].ImageIndex = 3;
Confira também
(Windows Forms)
Como: Exibir Subitens em Colunas com
o Controle ListView do Windows Forms
Artigo • 02/06/2023
O controle Windows Forms ListView pode exibir texto adicional, ou subitens, para cada
item na exibição Detalhes. A primeira coluna exibe o texto do item, por exemplo, o
número de um funcionário. A segunda, terceira e colunas seguintes exibem o primeiro,
segundo e subitens associados seguintes.
Para adicionar subitens a um item de lista

1. Adicione as colunas necessárias. Como a primeira coluna exibirá a propriedade do
Text item, você precisará de mais uma coluna do que subitens. Para obter mais
informações sobre como adicionar colunas, veja Como adicionar colunas ao
controle ListView dos Windows Forms.
2. Chame o Add método da coleção retornado pela SubItems propriedade de um

item. O exemplo de código a seguir define o nome do funcionário e o
departamento para um item de lista.
C#
// Adds two subitems to the first list item.

listView1.Items[0].SubItems.Add("John Smith");
listView1.Items[0].SubItems.Add("Accounting");
Confira também
(Windows Forms)
Como: Habilitar a exibição de bloco em
um controle ListView do Windows
Forms
Artigo • 02/06/2023
Com o recurso de exibição de bloco do ListView controle, você pode fornecer um

equilíbrio visual entre informações gráficas e textuais. As informações textuais exibidas
para um item na exibição lado a lado são as mesmas que as informações de coluna
definidas para exibição de detalhes. O modo de exibição de bloco funciona em
combinação com os recursos de agrupamento ou marca de inserção no ListView
controle.
O modo de exibição lado a lado usa um ícone de 32 x 32 pixels e várias linhas de texto,
conforme mostrado nas imagens a seguir.
Para habilitar o modo de exibição de bloco, defina a View propriedade como Tile. Você
pode ajustar o tamanho dos blocos definindo a TileSize propriedade e o número de
linhas de texto exibidas no bloco ajustando a Columns coleção.
Para definir a exibição lado a lado programaticamente

1. Use a View enumeração do ListView controle.
C#
listView1.View = View.Tile;
Exemplo
O exemplo de código completo a seguir demonstra a exibição lado a lado com blocos
modificados para mostrar as três linhas de texto. O tamanho de bloco foi ajustado para
evitar encapsulamento de linha.
C#
using System;
public class ListViewTilingExample : Form

{
private ImageList myImageList;
public ListViewTilingExample()
{
// Initialize myListView.
ListView myListView = new ListView();
myListView.Dock = DockStyle.Fill;
myListView.View = View.Tile;
// Initialize the tile size.

myListView.TileSize = new Size(400, 45);
// Initialize the item icons.

myImageList = new ImageList();
using (Icon myIcon = new Icon("book.ico"))
{
myImageList.Images.Add(myIcon);
}
myImageList.ImageSize = new Size(32, 32);
myListView.LargeImageList = myImageList;
// Add column headers so the subitems will appear.

myListView.Columns.AddRange(new ColumnHeader[]
{new ColumnHeader(), new ColumnHeader(), new ColumnHeader()});
// Create items and add them to myListView.

ListViewItem item0 = new ListViewItem( new string[]
{"Programming Windows",
"Petzold, Charles",
"1998"}, 0 );
{"Code: The Hidden Language of Computer Hardware and Software",
"Petzold, Charles",
"2000"}, 0 );
{"Programming Windows with C#",
"Petzold, Charles",
"2001"}, 0 );
{"Coding Techniques for Microsoft Visual Basic .NET",
"Connell, John",
"2001"}, 0 );
{"C# for Java Developers",
"Jones, Allen & Freeman, Adam",
"2002"}, 0 );
{"Microsoft .NET XML Web Services Step by Step",
"Jones, Allen & Freeman, Adam",
"2002"}, 0 );
myListView.Items.AddRange(
new ListViewItem[] {item0, item1, item2, item3, item4, item5});

this.Controls.Add(myListView);
this.Size = new System.Drawing.Size(430, 330);
this.Text = "ListView Tiling Example";
}
// Clean up any resources being used.

{
if (disposing)
{
myImageList.Dispose();
}
}
[STAThread]
static void Main()
{
Application.Run(new ListViewTilingExample());
}
}
Um arquivo de ícone denominado book.ico no mesmo diretório do arquivo

executável.
Confira também
ListView
TileSize
Controle ListView
Como: Habilitar exibição lado a lado em
Artigo • 02/06/2023
O recurso de exibição de bloco do ListView controle permite que você forneça um

equilíbrio visual entre informações gráficas e textuais. As informações textuais exibidas
para um item na exibição lado a lado são as mesmas que as informações de coluna
definidas para exibição de detalhes. Funções de exibição de bloco em combinação com
os recursos de agrupamento ou marca de inserção no ListView controle.
O modo de exibição lado a lado usa um ícone de 32 x 32 e várias linhas de texto,

conforme mostrado na imagem a seguir.
Propriedades e métodos de exibição lado a lado permitem especificar quais campos de

coluna devem ser exibidos para cada item e controlar coletivamente o tamanho e a
aparência de todos os itens dentro de uma janela de exibição lado a lado. Para maior
clareza, a primeira linha do texto em uma exibição lado a lado é sempre o nome do
item; isso não pode ser alterado.

formulário que contém um ListView controle. Para obter informações sobre como
Para definir a exibição lado a lado no designer

1. No Visual Studio, selecione o ListView controle em seu formulário.
2. Na janela Propriedades , selecione a View propriedade e escolha Bloco.
Confira também
TileSize
Como: Agrupar itens em um controle
Artigo • 02/06/2023
Com o recurso de agrupamento do ListView controle, você pode exibir conjuntos

relacionados de itens em grupos. Esses grupos são separados na tela por cabeçalhos de
grupo horizontal que contêm os títulos do grupo. Você pode usar ListView grupos para
facilitar a navegação em listas grandes agrupando itens em ordem alfabética, por data
ou por qualquer outro agrupamento lógico. A imagem a seguir mostra alguns itens
agrupados.
Para habilitar o agrupamento, primeiro crie um ou mais grupos no designer ou de forma

programática. Depois que um grupo for definido, você poderá atribuir ListView itens a
grupos. Você também pode mover itens de um grupo para outro de forma
programática.
Para adicionar grupos

1. Use o Add método da Groups coleção.
C#
// Adds a new group that has a left-aligned header

listView1.Groups.Add(new ListViewGroup("List item text",
HorizontalAlignment.Left));
Para remover grupos

1. Use o método ou Clear o RemoveAt método da Groups coleção.
O RemoveAt método remove um único grupo; o Clear método remove todos os

grupos da lista.
７ Observação
A remoção de um grupo não remove os itens dentro desse grupo.
C#
// Removes the first group in the collection.

listView1.Groups.RemoveAt(0);
// Clears all groups.
listView1.Groups.Clear();
Para atribuir itens a grupos ou mover itens entre grupos

1. Defina a ListViewItem.Group propriedade de itens individuais.
C#
// Adds the first item to the first group

listView1.Items[0].Group = listView1.Groups[0];
Confira também
ListView
ListView.Groups
ListViewGroup
Controle ListView
Como: Agrupar itens em um controle
ListView do Windows Forms usando o
Designer
Artigo • 02/06/2023
O recurso de agrupamento do ListView controle permite exibir conjuntos relacionados

de itens em grupos. Esses grupos são separados na tela por cabeçalhos de grupo
horizontal que contêm os títulos do grupo. Você pode usar ListView grupos para facilitar
a navegação em listas grandes agrupando itens alfabéticos, por data ou por qualquer
outro agrupamento lógico. A imagem a seguir mostra alguns itens agrupados:

formulário contendo um ListView controle. Para obter informações sobre como
Para habilitar o agrupamento, primeiro você deve criar um ou mais ListViewGroup

objetos no designer ou programaticamente. Depois que um grupo tiver sido definido,
você poderá atribuir itens a ele.
Adicionar ou remover grupos no designer

1. Na janela Propriedades, clique nas Reticências ( ) ao lado da Groups
propriedade.
O Editor de coleção de ListViewGroup é exibido.
2. Para adicionar um grupo, clique no botão Adicionar. Em seguida, você pode

definir propriedades do novo grupo, como as propriedades e HeaderAlignment as
Header propriedades. Para remover um grupo, selecione-o e clique no botão
Remover.
Atribuir itens aos grupos no designer
1. Na janela Propriedades, clique nas Reticências ( ) ao lado da Items propriedade.
O Editor de coleção de ListViewItem é exibido.
2. Para adicionar um novo item, clique no botão Adicionar. Em seguida, você pode
definir propriedades do novo item, como as propriedades e ImageIndex as Text
propriedades.
3. Selecione a Group propriedade e escolha um grupo na lista suspensa.
Confira também
ListView
Groups
ListViewGroup
Controle ListView
Como: Exibir uma marca de inserção em
Forms
Artigo • 02/06/2023
A marca de inserção no controle mostra aos ListView usuários o ponto em que os itens
arrastados serão inseridos. Quando um usuário arrasta um item para um ponto entre
dois outros itens, a marca de inserção mostra o novo local esperado do item.
A imagem a seguir mostra uma marca de inserção:
O exemplo de código a seguir demonstra como usar esse recurso.
Exemplo
C#
using System;
public class ListViewInsertionMarkExample : Form

{
private ListView myListView;
public ListViewInsertionMarkExample()
{
// Initialize myListView.
myListView = new ListView();
myListView.Dock = DockStyle.Fill;
myListView.View = View.LargeIcon;
myListView.MultiSelect = false;
myListView.ListViewItemSorter = new ListViewIndexComparer();
// Initialize the insertion mark.

myListView.InsertionMark.Color = Color.Green;
// Add items to myListView.

myListView.Items.Add("zero");
myListView.Items.Add("one");
myListView.Items.Add("two");
myListView.Items.Add("three");
myListView.Items.Add("four");
myListView.Items.Add("five");
// Initialize the drag-and-drop operation when running

// under Windows XP or a later operating system.
if (OSFeature.Feature.IsPresent(OSFeature.Themes))
{
myListView.AllowDrop = true;
myListView.ItemDrag += new
ItemDragEventHandler(myListView_ItemDrag);
myListView.DragEnter += new
DragEventHandler(myListView_DragEnter);
myListView.DragOver += new
DragEventHandler(myListView_DragOver);
myListView.DragLeave += new EventHandler(myListView_DragLeave);
myListView.DragDrop += new
DragEventHandler(myListView_DragDrop);
}

this.Text = "ListView Insertion Mark Example";
this.Controls.Add(myListView);
}
[STAThread]
static void Main()
{
Application.Run(new ListViewInsertionMarkExample());
}
// Starts the drag-and-drop operation when an item is dragged.

private void myListView_ItemDrag(object sender, ItemDragEventArgs e)
{
myListView.DoDragDrop(e.Item, DragDropEffects.Move);
}
// Sets the target drop effect.

private void myListView_DragEnter(object sender, DragEventArgs e)
{
e.Effect = e.AllowedEffect;
}
// Moves the insertion mark as the item is dragged.

private void myListView_DragOver(object sender, DragEventArgs e)
{
// Retrieve the client coordinates of the mouse pointer.
Point targetPoint =
myListView.PointToClient(new Point(e.X, e.Y));
// Retrieve the index of the item closest to the mouse pointer.

int targetIndex =
myListView.InsertionMark.NearestIndex(targetPoint);
// Confirm that the mouse pointer is not over the dragged item.
if (targetIndex > -1)
{
// Determine whether the mouse pointer is to the left or
// the right of the midpoint of the closest item and set
// the InsertionMark.AppearsAfterItem property accordingly.
Rectangle itemBounds = myListView.GetItemRect(targetIndex);
if ( targetPoint.X > itemBounds.Left + (itemBounds.Width / 2) )
{
myListView.InsertionMark.AppearsAfterItem = true;
}
else
{
myListView.InsertionMark.AppearsAfterItem = false;
}
}
// Set the location of the insertion mark. If the mouse is

// over the dragged item, the targetIndex value is -1 and
// the insertion mark disappears.
myListView.InsertionMark.Index = targetIndex;
}
// Removes the insertion mark when the mouse leaves the control.
private void myListView_DragLeave(object sender, EventArgs e)
{
myListView.InsertionMark.Index = -1;
}
// Moves the item to the location of the insertion mark.

private void myListView_DragDrop(object sender, DragEventArgs e)
{
// Retrieve the index of the insertion mark;
int targetIndex = myListView.InsertionMark.Index;
// If the insertion mark is not visible, exit the method.

if (targetIndex == -1)
{
return;
}
// If the insertion mark is to the right of the item with

// the corresponding index, increment the target index.
if (myListView.InsertionMark.AppearsAfterItem)
{
targetIndex++;
}
// Retrieve the dragged item.

ListViewItem draggedItem =
(ListViewItem)e.Data.GetData(typeof(ListViewItem));
// Insert a copy of the dragged item at the target index.

// A copy must be inserted before the original item is removed
// to preserve item index values.
myListView.Items.Insert(
targetIndex, (ListViewItem)draggedItem.Clone());
// Remove the original copy of the dragged item.

myListView.Items.Remove(draggedItem);
}
// Sorts ListViewItem objects by index.

private class ListViewIndexComparer : System.Collections.IComparer
{
public int Compare(object x, object y)
{
return ((ListViewItem)x).Index - ((ListViewItem)y).Index;
}
}
}
Confira também
ListView
ListView.InsertionMark
ListViewInsertionMark
Controle ListView
Passo a passo: executar uma operação do tipo "arrastar e soltar" no Windows
Forms
Como: Selecionar um item no controle
Artigo • 02/06/2023
Este exemplo demonstra como selecionar programaticamente um item em um controle

Windows FormsListView. Selecionar um item programaticamente não altera
automaticamente o foco para o ListView controle. Por esse motivo, normalmente, você
também deseja definir o item como focado ao selecionar um item.
Exemplo
C#
this.listView1.Items[0].Focused = true;
this.listView1.Items[0].Selected = true;
Um ListView controle nomeado listView1 que contém pelo menos um item.
Referências aos namespaces System e System.Windows.Forms.
Confira também
ListView
ListViewItem.Selected
Passo a passo: Criar uma interface no
estilo do Explorer com os controles
ListView e TreeView usando o Designer
Artigo • 21/06/2023
Um dos benefícios do Visual Studio é a capacidade de criar aplicativos dos Windows

Forms com aparência profissional em pouco tempo. Um cenário comum é criar uma
interface do usuário (interface do usuário) com ListView controles e TreeView que se
assemelham ao recurso windows Explorer de sistemas operacionais Windows. O
Windows Explorer exibe uma estrutura hierárquica de arquivos e pastas no computador
do usuário.
Para criar o formulário contendo controles ListView e

TreeView
1. No menu Arquivo , aponte para Novoe clique em Projeto.
2. Na caixa de diálogo Novo Projeto , faça o seguinte:
a. Em categorias, escolha Visual Basic ou Visual C#.
b. Na lista de modelos, escolha Aplicativo dos Windows Forms.
3. Clique em OK. Um novo projeto dos Windows Forms é criado.
4. Adicione um SplitContainer controle ao formulário e defina sua Dock propriedade

como Fill.
5. Adicione um ImageList nomeado imageList1 ao formulário e use o janela

Propriedades para adicionar duas imagens: uma imagem de pasta e uma imagem
de documento, nessa ordem.
6. Adicione um TreeView controle chamado treeview1 ao formulário e posicione-o

no lado esquerdo do SplitContainer controle. Na janela Propriedades para
treeView1 , faça o seguinte:
a. Defina a propriedade Dock como Fill.
b. Defina a propriedade ImageList como imagelist1.

7. Adicione um ListView controle chamado listView1 ao formulário e posicione-o no
lado direito do SplitContainer controle. Na janela Propriedades para listview1 ,
faça o seguinte:
a. Defina a propriedade Dock como Fill.
b. Defina a propriedade View como Details.
c. Abra o Editor de Coleção ColumnHeader clicando nas reticências ( ) na

Columns propriedade**.** Adicionar três colunas e definir sua Text propriedade
como Name , Type e Last Modified , respectivamente. Clique em OK para fechar a
caixa de diálogo.
d. Defina a propriedade SmallImageList como imageList1.
8. Implemente o código para preencher o TreeView com nós e subnodos. Adicione

este código à classe Form1 .
C#
private void PopulateTreeView()

{
TreeNode rootNode;
DirectoryInfo info = new DirectoryInfo(@"../..");

if (info.Exists)
{
rootNode = new TreeNode(info.Name);
rootNode.Tag = info;
GetDirectories(info.GetDirectories(), rootNode);
treeView1.Nodes.Add(rootNode);
}
}
private void GetDirectories(DirectoryInfo[] subDirs,

TreeNode nodeToAddTo)
{
TreeNode aNode;
DirectoryInfo[] subSubDirs;
foreach (DirectoryInfo subDir in subDirs)
{
aNode = new TreeNode(subDir.Name, 0, 0);
aNode.Tag = subDir;
aNode.ImageKey = "folder";
subSubDirs = subDir.GetDirectories();
if (subSubDirs.Length != 0)
{
GetDirectories(subSubDirs, aNode);
}
nodeToAddTo.Nodes.Add(aNode);
}
}
9. Uma vez que o código anterior usa o namespace System.IO, adicione as instruções
using ou import adequadas na parte superior do formulário.
C#
using System.IO;
10. Chame o método de configuração da etapa anterior no construtor do formulário

ou Load no método de tratamento de eventos. Adicione este código ao construtor
de formulário.
C#
public Form1()
{
PopulateTreeView();
}
11. Manipule o NodeMouseClickevento para treeview1 e implemente listview1 o

código a ser preenchido com o conteúdo de um nó quando um nó for clicado.
Adicione este código à classe Form1 .
C#
void treeView1_NodeMouseClick(object sender,

TreeNodeMouseClickEventArgs e)
{
TreeNode newSelected = e.Node;
listView1.Items.Clear();
DirectoryInfo nodeDirInfo = (DirectoryInfo)newSelected.Tag;
ListViewItem.ListViewSubItem[] subItems;
ListViewItem item = null;
foreach (DirectoryInfo dir in nodeDirInfo.GetDirectories())

{
item = new ListViewItem(dir.Name, 0);
subItems = new ListViewItem.ListViewSubItem[]
{new ListViewItem.ListViewSubItem(item, "Directory"),
new ListViewItem.ListViewSubItem(item,
dir.LastAccessTime.ToShortDateString())};
item.SubItems.AddRange(subItems);
listView1.Items.Add(item);
}
foreach (FileInfo file in nodeDirInfo.GetFiles())
{
item = new ListViewItem(file.Name, 1);
subItems = new ListViewItem.ListViewSubItem[]
{ new ListViewItem.ListViewSubItem(item, "File"),
new ListViewItem.ListViewSubItem(item,
file.LastAccessTime.ToShortDateString())};
item.SubItems.AddRange(subItems);
listView1.Items.Add(item);
}
listView1.AutoResizeColumns(ColumnHeaderAutoResizeStyle.HeaderSize);
}
Se você estiver usando C#, verifique se você tem o NodeMouseClick evento

associado ao método de manipulação de eventos. Adicione este código ao
construtor de formulário.
C#
this.treeView1.NodeMouseClick +=
new TreeNodeMouseClickEventHandler(this.treeView1_NodeMouseClick);
esperada.
Você verá um formulário dividido contendo um TreeView controle que exibe o

diretório do projeto no lado esquerdo e um ListView controle no lado direito com
três colunas. Você pode percorrer o TreeView selecionando nós de diretório e o
ListView é preenchido com o conteúdo do diretório selecionado.
Próximas etapas
Este aplicativo fornece um exemplo de como você pode usar TreeView e ListView
controlar juntos. Para obter mais informações sobre esses controles, consulte os
seguintes tópicos:
(Windows Forms)
Como: Anexar um menu ShortCut a um nó TreeView
Confira também
ListView
TreeView
Controle ListView
Como: Adicionar e remover nós com o controle TreeView do Windows Forms
Componente MainMenu (Windows
Forms)
Artigo • 02/06/2023
７ Observação

controles e ContextMenu às MainMenu versões anteriores e ContextMenu MainMenu
sejam mantidos para compatibilidade com versões anteriores e uso futuro, se você
escolher.
O componente Windows Forms MainMenu exibe um menu em tempo de execução.
Nesta seção
Visão geral do componente MainMenu
Explica o que é esse componente e seus principais recursos e propriedades.
Referência
MainMenu
Confira também
MenuStrip
ContextMenuStrip
Visão geral do componente MainMenu
(Windows Forms)
Artigo • 02/06/2023
） Importante
Embora MenuStrip substitua e ContextMenuStrip adicione funcionalidades aos

controles e ContextMenu versões MainMenu anteriores e ContextMenu sejam
mantidos para compatibilidade com versões MainMenu anteriores e uso futuro, se
você escolher.
O componente Windows Forms MainMenu exibe um menu em tempo de execução.

Todos os submenus do menu principal e itens individuais são MenuItem objetos.
Um item de menu pode ser designado como o item padrão definindo a DefaultItem
propriedade como true . O item padrão aparece em negrito quando o menu é clicado.
A propriedade do item de Checked menu é true ou, false e indica se o item de menu
está selecionado. A propriedade do item de RadioCheck menu personaliza a aparência
do item selecionado: se RadioCheck estiver definido como true , um botão de opção
será exibido ao lado do item; se RadioCheck estiver definido como false , uma marca
de seleção será exibida ao lado do item.
Confira também
MainMenu
Menu
MenuItem
MenuStrip
ContextMenuStrip
Visão geral do controle MenuStrip
Controle MaskedTextBox (Windows
Forms)
Artigo • 02/06/2023
Este tópico se vincula a outras pessoas sobre o MaskedTextBox controle.
Nesta seção
Passo a passo: Trabalhando com o controle MaskedTextBox
Demonstra os principais recursos do MaskedTextBox controle.
Como: Associar dados ao controle MaskedTextBox

Demonstra como reformatar os dados quando os dados no banco de dados não
correspondem ao formato esperado pela definição de máscara.
Referência
MaskedTextBox
A classe primária para a implementação do controle de caixa de texto mascarada.
Passo a passo: Trabalhando com o
controle MaskedTextBox
Artigo • 21/06/2023
Inicializando o MaskedTextBox controle
Usando o MaskInputRejected manipulador de eventos para alertar o usuário

quando um caractere não está em conformidade com a máscara
Atribuir um tipo à ValidatingType propriedade e usar o TypeValidationCompleted

manipulador de eventos para alertar o usuário quando o valor que ele está
tentando confirmar não é válido para o tipo
Criar o projeto e adicionar um controle
Adicionar um controle MaskedTextBox ao seu formulário
1. Abra o formulário no qual você deseja colocar o MaskedTextBox controle.
2. Arraste um MaskedTextBox controle da Caixa de Ferramentas para o formulário.
3. Clique com o botão direito do mouse no controle e escolha Propriedades. Na

janela Propriedades, selecione a propriedade Máscara e clique no botão de
reticências ... ao lado do nome da propriedade.
4. Na caixa de diálogo Máscara de Entrada, selecione a máscara Data abreviada e

clique em OK.
5. Na janela Propriedades , defina a BeepOnError propriedade como true . Essa

propriedade faz com que um aviso sonoro curto soe sempre que o usuário tentar
inserir um caractere que viola a definição da máscara.
Para obter um resumo dos caracteres aos quais a propriedade Mask dá suporte,
consulte a seção Comentários da Mask propriedade .
Alertar o usuário de erros de entrada
Adicionar uma dica de balão para entrada de máscara rejeitada

1. Retorne à Caixa de Ferramentas e adicione um ToolTip ao formulário.
2. Crie um manipulador de eventos para o MaskInputRejected evento que gera o

ToolTip quando ocorre um erro de entrada. A dica de balão permanece visível por
cinco segundos ou até que o usuário clique nele.
C#
public void Form1_Load(Object sender, EventArgs e)

{
... // Other initialization code
maskedTextBox1.Mask = "00/00/0000";
maskedTextBox1.MaskInputRejected += new
MaskInputRejectedEventHandler(maskedTextBox1_MaskInputRejected)
}
void maskedTextBox1_MaskInputRejected(object sender,

MaskInputRejectedEventArgs e)
{
toolTip1.ToolTipTitle = "Invalid Input";
toolTip1.Show("We're sorry, but only digits (0-9) are allowed in
dates.", maskedTextBox1, maskedTextBox1.Location, 5000);
}
Alertar o usuário que um tipo que não é válido
Adicionar uma dica de balão para tipos de dados inválidos

1. No manipulador de eventos do Load formulário, atribua um Type objeto que
representa o DateTime tipo à MaskedTextBox propriedade do ValidatingType
controle:
C#
private void Form1_Load(Object sender, EventArgs e)

{
// Other code
maskedTextBox1.ValidatingType = typeof(System.DateTime);
maskedTextBox1.TypeValidationCompleted += new
TypeValidationEventHandler(maskedTextBox1_TypeValidationCompleted);
}
2. Adicione um manipulador de eventos ao evento TypeValidationCompleted:
C#
public void maskedTextBox1_TypeValidationCompleted(object sender,
TypeValidationEventArgs e)
{
if (!e.IsValidInput)
{
toolTip1.ToolTipTitle = "Invalid Date Value";
toolTip1.Show("We're sorry, but the value you entered is not a
valid date. Please change the value.", maskedTextBox1, 5000);
e.Cancel = true;
}
}
Confira também
MaskedTextBox
Controle MaskedTextBox
Como: Associar dados ao controle
MaskedTextBox
Artigo • 21/06/2023
Você pode associar dados a um MaskedTextBox controle da mesma forma que pode a
qualquer outro controle Windows Forms. No entanto, se o formato dos seus dados no
banco de dados não corresponder ao formato esperado pela sua definição de máscara,
será necessário reformatar os dados. O procedimento a seguir demonstra como fazer
isso usando os Format eventos e Parse da Binding classe para exibir campos separados
de número de telefone e banco de dados de extensão de telefone como um único
campo editável.
O procedimento a seguir requer que você tenha acesso a um banco de dados do SQL
Server com o banco de dados Northwind de exemplo instalado.
Associar dados ao controle MaskedTextBox

1. Criar um novo projeto dos Windows Forms.
2. Arraste dois TextBox controles para o formulário; nomeie-os FirstName e LastName .
3. Arraste um MaskedTextBox controle para o formulário; nomeie-o PhoneMask como .
4. Defina a Mask propriedade de PhoneMask como (000) 000-0000 x9999 .
5. Adicione as seguintes importações de namespace ao formulário.
C#
6. Clique com o botão direito do mouse no formulário e escolha Exibir Código.

Coloque esse código em qualquer lugar em sua classe de formulário.
C#
Binding currentBinding, phoneBinding;

DataSet employeesTable = new DataSet();
SqlConnection sc;
SqlDataAdapter dataConnect;

{
DoMaskBinding();
}
private void DoMaskBinding()

{
try
{
sc = new SqlConnection("Data Source=CLIENTUE;Initial
Catalog=NORTHWIND;Integrated Security=SSPI");
sc.Open();
}
{
MessageBox.Show(ex.Message);
return;
}
dataConnect = new SqlDataAdapter("SELECT * FROM Employees", sc);

dataConnect.Fill(employeesTable, "Employees");
// Now bind MaskedTextBox to appropriate field. Note that we must

create the Binding objects
// before adding them to the control - otherwise, we won't get a
Format event on the
// initial load.
try
{
currentBinding = new Binding("Text", employeesTable,
"Employees.FirstName");
firstName.DataBindings.Add(currentBinding);

"Employees.LastName");
lastName.DataBindings.Add(currentBinding);
phoneBinding =new Binding("Text", employeesTable,

"Employees.HomePhone");
// We must add the event handlers before we bind, or the Format
event will not get called
// for the first record.
phoneBinding.Format += new
ConvertEventHandler(phoneBinding_Format);
phoneBinding.Parse += new
ConvertEventHandler(phoneBinding_Parse);
phoneMask.DataBindings.Add(phoneBinding);
}
{
return;
}
}
7. Adicione manipuladores de eventos para os Format eventos e Parse para combinar
e separar os PhoneNumber campos e Extension do associado DataSet.
C#
private void phoneBinding_Format(Object sender, ConvertEventArgs e)

{
String ext;
DataRowView currentRow =
(DataRowView)BindingContext[employeesTable, "Employees"].Current;
if (currentRow["Extension"] == null)
{
ext = "";
} else
{
ext = currentRow["Extension"].ToString();
}
e.Value = e.Value.ToString().Trim() + " x" + ext;

}
private void phoneBinding_Parse(Object sender, ConvertEventArgs e)

{
String phoneNumberAndExt = e.Value.ToString();
int extIndex = phoneNumberAndExt.IndexOf("x");

String ext = phoneNumberAndExt.Substring(extIndex).Trim();
String phoneNumber = phoneNumberAndExt.Substring(0,
extIndex).Trim();
//Get the current binding object, and set the new extension
manually.
// Remove the "x" from the extension.
currentRow["Extension"] = ext.Substring(1);
//Return the phone number.

e.Value = phoneNumber;
}
8. Adicione dois Button controles ao formulário. Nomeie-os previousButton e

nextButton . Clique duas vezes em cada botão para adicionar um Click
manipulador de eventos e preencha os manipuladores de eventos, conforme

mostrado no exemplo de código a seguir.
C#
private void previousButton_Click(object sender, EventArgs e)

{
BindingContext[employeesTable, "Employees"].Position =
BindingContext[employeesTable, "Employees"].Position - 1;
}
private void nextButton_Click(object sender, EventArgs e)

{
BindingContext[employeesTable, "Employees"].Position + 1;
}
9. Execute o exemplo. Edite os dados e use os botões Anterior e Próximo para ver se
os dados são persistidos corretamente no DataSet.
Exemplo
O exemplo de código a seguir é a lista de código completa resultante da conclusão do
procedimento anterior.
C#
using System;
using System.Data;
#endregion
namespace MaskedTextBoxDataCSharp
{
partial class Form1 : Form
{
Binding currentBinding, phoneBinding;
DataSet employeesTable = new DataSet();
SqlConnection sc;
SqlDataAdapter dataConnect;
public Form1()
{
}

{
DoMaskBinding();
}
private void DoMaskBinding()
{
try
{
sc = new SqlConnection("Data Source=localhost;Initial
Catalog=NORTHWIND;Integrated Security=SSPI");
sc.Open();
}
{
return;
}
dataConnect = new SqlDataAdapter("SELECT * FROM Employees", sc);

dataConnect.Fill(employeesTable, "Employees");
// Now bind MaskedTextBox to appropriate field. Note that we

must create the Binding objects
// before adding them to the control - otherwise, we won't get a
Format event on the
// initial load.
try
{
"Employees.FirstName");
firstName.DataBindings.Add(currentBinding);

"Employees.LastName");
lastName.DataBindings.Add(currentBinding);
phoneBinding =new Binding("Text", employeesTable,

"Employees.HomePhone");
// We must add the event handlers before we bind, or the
Format event will not get called
// for the first record.
phoneBinding.Format += new
ConvertEventHandler(phoneBinding_Format);
phoneBinding.Parse += new
ConvertEventHandler(phoneBinding_Parse);
phoneMask.DataBindings.Add(phoneBinding);
}
{
return;
}
}
private void phoneBinding_Format(Object sender, ConvertEventArgs e)

{
String ext;
if (currentRow["Extension"] == null)
{
ext = "";
} else
{
ext = currentRow["Extension"].ToString();
}
e.Value = e.Value.ToString().Trim() + " x" + ext;

}
private void phoneBinding_Parse(Object sender, ConvertEventArgs e)

{
String phoneNumberAndExt = e.Value.ToString();
int extIndex = phoneNumberAndExt.IndexOf("x");

String ext = phoneNumberAndExt.Substring(extIndex).Trim();
String phoneNumber = phoneNumberAndExt.Substring(0,
extIndex).Trim();
//Get the current binding object, and set the new extension
manually.
// Remove the "x" from the extension.
currentRow["Extension"] = ext.Substring(1);
//Return the phone number.

e.Value = phoneNumber;
}
private void previousButton_Click(object sender, EventArgs e)

{
BindingContext[employeesTable, "Employees"].Position - 1;
}
private void nextButton_Click(object sender, EventArgs e)

{
BindingContext[employeesTable, "Employees"].Position + 1;
}
}
}
Crie um projeto do Visual C# ou do Visual Basic.
Adicione os TextBox controles e MaskedTextBox ao formulário, conforme descrito
no procedimento anterior.
Abra o arquivo de código-fonte para o formulário de padrão do projeto.
Substitua o código-fonte deste arquivo pelo código listado na seção “Código”

anterior.
Compile o aplicativo.
Confira também
Como: Definir a máscara de entrada
Artigo • 02/06/2023
O controle de caixa de texto mascarado é um controle de caixa de texto avançado que

dá suporte a uma sintaxe declarativa para aceitar ou rejeitar a entrada do usuário.
Definindo a propriedade Máscara, você pode especificar a entrada do usuário permitida
sem escrever qualquer lógica de validação personalizada no seu aplicativo. Para obter
mais informações, consulte a seção Comentários da MaskedTextBox classe.
Definindo definir a propriedade Máscara

manualmente
Se estiver familiarizado com os caracteres que a propriedade Máscara dá suporte, você
poderá inseri-los manualmente. Para obter um resumo dos caracteres compatíveis com
a propriedade Mask, consulte a seção Comentários da Mask propriedade.
Definir a propriedade Mask manualmente

1. No modo Design , selecione um MaskedTextBox.
2. Na janela Propriedades , localize a Mask propriedade.
3. Digite a máscara desejada. Por exemplo, digite ### .
Usando a caixa de diálogo Máscara de Entrada

A caixa de diálogo Máscara de Entrada fornece algumas máscaras de entrada
predefinidas. Você também pode alterar as máscaras predefinidas ou inserir sua própria
máscara manualmente.
Abrir a caixa de diálogo Máscara de Entrada

1. No modo Design , selecione um MaskedTextBox.
a. Clique na marca inteligente para abrir o painel Tarefas de MaskedTextBox.
b. Clique em Definir Máscara.
- ou -
a. Na janela Propriedades , selecione a Mask propriedade.
b. Clique no botão de reticências na coluna do valor da propriedade.
A caixa de diálogo Máscara de Entrada é exibida.
Usar a caixa de diálogo Máscara de Entrada

1. (Opcional) Clique em uma das máscaras predefinidas na lista.
2. (Opcional) Edite a máscara predefinida na caixa Máscara.
3. (Opcional) Digite uma nova máscara na caixa Máscara. Ou seja, não é necessário
usar uma das máscaras predefinidas.
７ Observação
A caixa Visualização exibe os caracteres que o usuário vê na MaskedTextBox.

Esses caracteres são um guia para ajudar o usuário a inserir os dados
corretamente.
4. Selecione ou desmarque a caixa de seleção Usar ValidatingType. A caixa de

seleção Usar ValidatingType especifica se um tipo de dados é usado para verificar
a entrada de dados pelo usuário. Para obter mais informações, consulte a
propriedade ValidatingType.
5. Clique em OK.
A máscara é inserida na propriedade Máscara na janela Propriedades.
Confira também
Controle MenuStrip (Windows Forms)
Artigo • 02/06/2023
Esse controle agrupa comandos do aplicativo e os torna facilmente acessíveis.
Nesta seção
Como: Adicionar melhorias a ToolStripMenuItems

Descreve como adicionar marcas de seleção, imagens, teclas de atalho, teclas de acesso
e barras separadoras aos menus e comandos de menu.
Como: Acrescentar um MenuStrip a uma janela pai MDI

Descreve como definir várias propriedades para acrescentar ao menu de interface MDI
pai (interface de vários documentos) ao menu MDI pai.
Como: Criar uma lista de janelas MDI com MenuStrip

Demonstra como criar uma lista de todos os formulários filho ativos no menu Janela pai.
Como: Desabilitar ToolStripMenuItems

Descreve como desabilitar todos os menus e comandos de menu individuais.
Como: Ocultar ToolStripMenuItems

Descreve como ocultar todos os menus e comandos de menu individuais.
Como: Inserir um MenuStrip em um menu suspenso MDI

Descreve como definir várias propriedades para inserir um grupo de itens de menu no
menu filho MDI na parte da lista suspensa do menu pai MDI.
Como: Remover um ToolStripMenuItem de um menu suspenso MDI

Descreve como definir várias propriedades para remover um item de menu da parte
suspensa do menu MDI pai.
Como: Configurar margens de imagem e margens de verificação MenuStrip

Descreve como personalizar uma MenuStrip configuração de propriedades de
verificação e margem de imagem de várias maneiras.
Como: Fornecer itens de menu padrão para um formulário

Descreve como usar um MenuStrip controle para criar um formulário com um menu
padrão.
Como: Exibir botões de opção em um MenuStrip
Descreve como implementar o comportamento de botão de opção (ou botão de opção)
em um ToolStripMenuItem.
Mesclando itens de menu no controle MenuStrip dos Windows Forms

Descreve os conceitos gerais e métodos para mesclagem de menu.
Como: Configurar a mesclagem de menu automática para aplicativos MDI

Descreve como mesclar itens de menu automaticamente no tempo de execução.
Editor de coleção de itens do MenuStrip
Como: Copiar ToolStripMenuItems
Como: Ocultar ToolStripMenuItems usando o designer
Como: Desabilitar ToolStripMenuItems usando o designer
Como: Mover ToolStripMenuItems
Passo a passo: Fornecer itens de menu padrão para um formulário
Caixa de diálogo de tarefas do MenuStrip
Referência
MenuStrip
Descreve os recursos da MenuStrip classe, que fornece um sistema de menus para um
formulário.
ContextMenuStrip
Descreve os recursos da ContextMenuStrip, que representa um menu de atalho.
ToolStripMenuItem
Descreve os recursos da ToolStripMenuItem classe, que representa uma opção
selecionável exibida em um MenuStrip ou ContextMenuStrip.
(Windows Forms)
Artigo • 02/06/2023
Os menus expõem funcionalidades para os usuários, mantendo os comandos que são

agrupados por um tema comum.
O MenuStrip controle foi introduzido na versão 2.0 do .NET Framework. Com o

MenuStrip controle, você pode criar facilmente menus como os encontrados no
Microsoft Office.
O MenuStrip controle dá suporte à MDI (interface de vários documentos) e à

mesclagem de menu, dicas de ferramenta e estouro. Você pode melhorar a usabilidade
e a legibilidade dos seus menus adicionando teclas de acesso, teclas de atalho, marcas
de seleção, imagens e barras separadoras.
O MenuStrip controle substitui e adiciona funcionalidade ao MainMenu controle; no

entanto, o MainMenu controle é retido para compatibilidade com versões anteriores e
uso futuro, se você escolher.
Maneiras de usar o controle MenuStrip

Use o MenuStrip controle para:
Crie facilmente menus personalizados e comumente usados que dão suporte a

recursos avançados de interface do usuário e layout, tais como ordenação e
alinhamento de texto e imagem, operações do tipo "arrastar e soltar", MDI,
estouro e modos alternativos de acessar os comandos de menu.
Suporte à aparência e comportamento típicos do sistema operacional.
Manipule eventos de forma consistente em todos os contêineres e os itens

contidos da mesma forma que você manipula eventos para outros controles.
A tabela a seguir mostra algumas propriedades particularmente importantes de

MenuStrip classes associadas e particularmente importantes.
MdiWindowListItem Obtém ou define o ToolStripMenuItem que é usado para exibir uma

lista de formulários filho MDI.
ToolStripItem.MergeAction Obtém ou define como os menus filho são mescladas com os menus
pai em aplicativos MDI.
ToolStripItem.MergeIndex Obtém ou define a posição de um item mesclado dentro de um

menu em aplicativos MDI.
Form.IsMdiContainer Obtém ou define um valor que indica se o formulário é um

contêiner para formulários MDI filho.
ShowItemToolTips Obtém ou define um valor que indica se as dicas de ferramenta são

mostradas para o MenuStrip.
CanOverflow Obtém ou define um valor que indica se o MenuStrip dá suporte à

funcionalidade de estouro.
ShortcutKeys Obtém ou define as teclas de atalho associadas ao

ToolStripMenuItem.
ShowShortcutKeys Obtém ou define um valor que indica se as teclas de atalho

associadas ao ToolStripMenuItem são exibidas ao lado do
ToolStripMenuItem.
A tabela a seguir mostra as classes complementares importantes MenuStrip .
Classe Descrição
ToolStripMenuItem Representa uma opção selecionável exibida em um MenuStrip ou

ContextMenuStrip.
ContextMenuStrip Representa um menu de atalho.
ToolStripDropDown Representa um controle que permite que o usuário selecione um único

item em uma lista exibida quando o usuário clica em um ou em um
ToolStripDropDownButton item de menu de nível superior.
ToolStripDropDownItem Fornece funcionalidade básica para controles derivados ToolStripItem

desse item suspenso de exibição quando clicado.
Confira também
ToolStrip
MenuStrip
ContextMenuStrip
StatusStrip
ToolStripItem
ToolStripDropDown
Como: Adicionar melhorias a
ToolStripMenuItems
Artigo • 02/06/2023
Você pode aprimorar a usabilidade e ContextMenuStrip os controles das MenuStrip

seguintes maneiras:
Adicione marcas de seleção para designar se um recurso está ativado ou

desativado, como se uma régua é exibida ao longo da margem de um aplicativo
de processamento de texto ou para indicar qual arquivo em uma lista de arquivos
está sendo exibido, como em um menu Janela.
Adicione imagens que representem visualmente os comandos de menu.
Exiba teclas de atalho para oferecer uma alternativa de teclado ao mouse para
executar comandos. Por exemplo, pressionar CTRL+C executa o comando Copiar.
Exiba chaves de acesso para oferecer uma alternativa de teclado ao mouse para
navegação de menu. Por exemplo, pressionar ALT+F escolhe o menu Arquivo.
Mostre barras de separação para agrupar comandos relacionados e tornar os

menus mais legíveis.
Para exibir uma marca de seleção em um comando de

menu
Defina sua Checked propriedade como true .
Isso também define a CheckState propriedade como true . Use este procedimento
somente se desejar que o comando de menu apareça como marcado por padrão,
independentemente de estar selecionado.
Para exibir uma marca de seleção que altere o estado de

cada clique
Defina a propriedade do comando de CheckOnClick menu como true .
Para adicionar uma imagem a um comando de menu

Defina a propriedade do comando de Image menu como o nome da imagem. Se a
ToolStripItemDisplayStyle propriedade desse comando de menu estiver definida
Text como ou None, a imagem não poderá ser exibida.
７ Observação
A margem de imagem também poderá mostrar uma marca de seleção se você

quiser. Além disso, você pode definir a Checked propriedade da imagem como
true , e a imagem aparecerá com uma borda eclodida em torno dela em tempo de
execução.
Para exibir uma tecla de atalho para um comando de

menu
Defina a propriedade do comando de ShortcutKeys menu para a combinação de
teclado desejada, como CTRL+O para o comando abrir menu, e defina a
ShowShortcutKeys propriedade como true .
Para exibir teclas de atalho personalizadas para um

comando de menu
Defina a propriedade do comando de ShortcutKeyDisplayString menu para a
combinação de teclado desejada, como CTRL+SHIFT+O em vez de
SHIFT+CTRL+O, e defina a ShowShortcutKeys propriedade como true .
Para exibir uma chave de acesso para um comando de

menu
Ao definir a Text propriedade para o comando de menu, insira uma escarpa (&)
antes da letra que você deseja que seja sublinhada como a chave de acesso. Por
exemplo, digitar &Open como propriedade Text de um item de menu resultará em
um comando de menu que aparece como caneta O.
Para navegar até este comando de menu, pressione ALT para dar foco à
MenuStriptecla de acesso e pressione a tecla de acesso do nome do menu.
Quando o menu é aberto e mostra os itens com chaves de acesso, basta
pressionar a tecla de acesso para selecionar o comando de menu.
７ Observação
Evite definir teclas de acesso duplicadas, como definir ALT+F duas vezes no mesmo
sistema de menu. Não é possível garantir a ordem de seleção das teclas de acesso
duplicadas.
Para exibir uma barra separadora entre os comandos de

menu
Depois de definir seu MenuStrip e os itens que ele conterá, use o método ou Add
o AddRange método para adicionar os comandos e ToolStripSeparator controles
de MenuStrip menu à ordem desejada.
C#
// This code adds a top-level File menu to the MenuStrip.

this.menuStrip1.Items.Add(new ToolStripItem[]_
{this.fileToolStripMenuItem});
// This code adds the New and Open menu commands, a separator bar,
// and the Save and Exit menu commands to the top-level File menu,
// in that order.
this.fileToolStripMenuItem.DropDownItems.AddRange(new _
ToolStripItem[] {
this.newToolStripMenuItem,
this.openToolStripMenuItem,
this.toolStripSeparator1,
this.saveToolStripMenuItem,
this.exitToolStripMenuItem});
Confira também
MenuStrip
ToolStripMenuItem
Como acrescentar um MenuStrip a uma
janela pai MDI (Windows Forms)
Artigo • 21/06/2023
Em alguns aplicativos, o tipo de uma janela filho MDI (interface de vários documentos)
pode ser diferente da janela MDI pai. Por exemplo, a MDI pai pode ser uma planilha e a
MDI filho pode ser um gráfico. Nesse caso, é recomendável atualizar o conteúdo do
menu do MDI pai com o conteúdo do menu do MDI filho, visto que janelas MDI filho de
tipos diferentes são ativadas.
O procedimento a seguir usa as IsMdiContainerpropriedades , MergeActionAllowMerge,

e MergeIndex para acrescentar o menu filho MDI ao menu pai da MDI. Fechar a janela
filho MDI remove o menu acrescentado do MDI pai.
Consulte também Aplicativos MDI (Interface de Vários Documentos).
Acrescentar um item de menu a um pai MDI

1. Crie um formulário e defina sua IsMdiContainer propriedade true como .
2. Adicione um MenuStrip a Form1 e defina a AllowMerge propriedade do MenuStrip

como true .
3. Defina a Visible propriedade do Form1 MenuStrip como false .
4. Adicione um item de menu de nível superior ao Form1 MenuStrip e defina sua Text
propriedade &File como .
5. Adicione um item de submenu ao &File item de menu e defina sua propriedade

&Open como Text .
6. Adicione um formulário ao projeto, adicione um MenuStrip ao formulário e defina

a AllowMerge propriedade do Form2 MenuStrip como true .
propriedade &Special como .
8. Adicione dois itens de submenu ao &Special item de menu e defina suas Text
propriedades como Command&1 e Command&2 , respectivamente.
9. Defina a MergeAction propriedade dos itens de &Special menu , Command&1 e
Command&2 como Append.
10. Crie um manipulador de eventos para o Click evento do &Open ToolStripMenuItem.
11. No manipulador de eventos, insira um código semelhante ao exemplo de código a

seguir para criar e exibir novas instâncias de Form2 como filhos MDI de Form1 .
C#
private void openToolStripMenuItem_Click(object sender, EventArgs e)

{
Form2 newMDIChild = new Form2();
// Set the parent form of the child window.
newMDIChild.MdiParent = this;
// Display the new form.
newMDIChild.Show();
}
12. Coloque um código semelhante ao exemplo de código a seguir no

&Open ToolStripMenuItem para registrar o manipulador de eventos.
C#
this.openToolStripMenuItem.Click += new
System.EventHandler(this.openToolStripMenuItem_Click);
Dois Form controles chamados Form1 e Form2 .
Um MenuStrip controle no Form1 chamado menuStrip1 e um MenuStrip controle

no Form2 chamado menuStrip2 .

Como: Copiar ToolStripMenuItems
Artigo • 02/06/2023
Em tempo de design, você pode copiar menus de nível superior inteiros e seus itens de
submenu para um lugar diferente no MenuStrip. Você também pode copiar itens de
menu individuais entre menus de nível superior ou alterar a posição dos itens de menu
dentro de um menu.
Copiar um menu de nível superior e seus itens de

submenu para outro local de nível superior
1. Clique com o botão esquerdo do mouse no menu que você deseja copiar e
pressione CTRL + X ou clique com o botão direito do mouse no menu e selecione
Copiar no menu de atalho.
2. Clique com o botão esquerdo do mouse no menu superior e posterior ao novo

local desejado e pressione CTRL + V ou clique com o botão direito do mouse no
item de menu superior e anterior ao novo local desejado e selecione Colar no
menu de atalho.
O menu que você copiou é inserido antes do menu de nível superior selecionado.
Copiar um menu de nível superior e seus itens de

submenu para outro local suspenso
1. Clique com o botão esquerdo do mouse no menu que você deseja mover e
pressione CTRL + C ou clique com o botão direito do mouse no menu e selecione
Copiar no menu de atalho.
2. No menu de nível superior de destino, clique com o botão esquerdo do mouse no

item de submenu acima do novo local desejado e pressione CTRL + V ou clique
com o botão direito do mouse no item de submenu acima do novo local desejado
e selecione Colar no menu de atalho.
O menu que você copiou é inserido antes do item de submenu selecionado.
Copiar um item de submenu para outro menu

1. Clique com o botão esquerdo do mouse no submenu que você deseja copiar e
pressione CTRL + C ou clique com o botão direito do mouse no item de submenu
e escolha Copiar no menu de atalho.
2. Clique com o botão esquerdo do mouse no menu que contém o item de submenu
que você recortou.
3. Clique com o botão esquerdo do mouse no item de submenu anterior ao novo

local desejado e pressione CTRL + V ou clique com o botão direito do mouse no
item de submenu anterior ao novo local desejado e selecione Colar no menu de
atalho.
O item de submenu que você copiou é inserido antes do item de submenu

selecionado.
Confira também
MenuStrip
ToolStripMenuItem
Como criar uma lista de janelas MDI
com MenuStrip (Windows Forms)
Artigo • 21/06/2023
Use a interface MDI para criar aplicativos que podem abrir vários documentos no
mesmo momento e copie e cole o conteúdo de um documento para outro.
Este procedimento mostra como criar uma lista de todos os formulários filho ativos no
menu Janela do pai.
Para criar uma lista de janelas MDI em um MenuStrip

1. Crie um formulário e defina sua IsMdiContainer propriedade true como .
2. Adicione um MenuStrip ao formulário.
3. Adicione dois itens de menu de nível superior ao MenuStrip e defina suas Text
propriedades como &File e &Window .
4. Adicione um item de submenu ao &File item de menu e defina sua propriedade

&Open como Text .
5. Defina a MdiWindowListItem propriedade do MenuStrip como o

&Window ToolStripMenuItem.
6. Adicione um formulário ao projeto e adicione o controle desejado a ele, como

outro MenuStrip.
7. Crie um manipulador de eventos para o Click evento do &New ToolStripMenuItem.
8. No manipulador de eventos, insira um código semelhante ao seguinte para criar e

exibir novas instâncias de Form2 como filhos MDI de Form1 .
C#
private void newToolStripMenuItem_Click(object sender, EventArgs e)

{
newMDIChild.Show();
}
9. Coloque o código como o seguinte no &New ToolStripMenuItem para registrar o
C#
this.newToolStripMenuItem.Click += new
System.EventHandler(this.newToolStripMenuItem_Click);

Confira também
Como: criar formulários pai MDI
Como: criar formulários filho MDI
Controle MenuStrip
Artigo • 02/06/2023
Você pode limitar ou ampliar os comandos que um usuário pode fazer ao habilitar e
desabilitar itens de menu em resposta a atividades do usuário. Os itens de menu são
habilitados por padrão quando são criados, mas isso pode ser ajustado por meio da
Enabled propriedade. Você pode manipular essa propriedade em tempo de design na
janela Propriedades ou programaticamente configurando ela no código.
Para desabilitar um item de menu programaticamente

Dentro do método em que você define as propriedades do item de menu,
adicione código para definir a Enabled propriedade como false .
C#
menuItem1.Enabled = false;
 Dica
Desabilitar o primeiro ou o item de menu de nível superior em um menu

oculta todos os itens de menu contidos no menu, mas não os desabilita. Da
mesma forma, desabilitar um item de menu que tenha itens de submenu
oculta os itens de submenu, mas não os desabilita. Se todos os comandos em
um determinado menu estiverem indisponíveis para o usuário, ocultar e
desabilitar todo o menu será considerado uma boa prática de programação,
pois isso apresenta uma interface do usuário mais enxuta. Você deve ocultar e
desabilitar o menu e desabilitar cada item e submenu item no menu, pois
ocultar sozinho não impede o acesso a um comando de menu por meio de
uma chave de atalho. Defina a Visible propriedade de um item de menu de
nível superior para false ocultar todo o menu.
Confira também
MenuStrip
ToolStripMenuItem
usando o designer
Artigo • 02/06/2023
Você pode limitar ou ampliar os comandos que um usuário pode fazer ao habilitar e
desabilitar itens de menu em resposta a atividades do usuário. Os itens de menu são
habilitados por padrão quando são criados, mas isso pode ser ajustado por meio da
Enabled propriedade. Você pode manipular essa propriedade em tempo de design na
janela Propriedades ou programaticamente configurando ela no código. Para obter
mais informações, consulte Como desabilitar ToolStripMenuItems.
Para desabilitar um item de menu em tempo

de design
1. Com o item de menu selecionado no formulário, defina a Enabled propriedade
como false .
 Dica
Desabilitar o primeiro item de menu ou o de nível superior em um menu

desabilita todos os itens de menu contidos no menu. Da mesma forma,
desabilitar um item de menu que tenha itens de submenu desabilita os itens
do submenu. Se todos os comandos em um determinado menu estiverem
indisponíveis para o usuário, ocultar e desabilitar todo o menu será
considerado uma boa prática de programação, pois isso apresenta uma
interface do usuário mais enxuta. Você deve ocultar e desabilitar o menu, pois
apenas ocultar não impede o acesso a um comando de menu por meio de
uma tecla de atalho. Defina a Visible propriedade de um item de menu de
nível superior para false ocultar todo o menu.
Confira também
MenuStrip
ToolStripMenuItem
Como exibir botões de opção em um
MenuStrip (Windows Forms)
Artigo • 21/06/2023
Botões de opção são semelhantes a caixas de seleção, exceto que os usuários podem
selecionar apenas um por vez. Embora, por padrão, a ToolStripMenuItem classe não
forneça comportamento de botão de opção, a classe fornece marcar comportamento de
caixa que você pode personalizar para implementar o comportamento do botão de
opção para itens de menu em um MenuStrip controle.
Quando a CheckOnClick propriedade de um item de menu é true , os usuários podem

clicar no item para alternar a exibição de uma marca de marcar. A Checked propriedade
indica o estado atual do item. Para implementar o comportamento básico do botão de
opção, você deve garantir que, quando um item for selecionado, defina a Checked
propriedade do item selecionado anteriormente como false .
Os procedimentos a seguir descrevem como implementar essa e funcionalidade

adicional em uma classe que herda a ToolStripMenuItem classe . A
ToolStripRadioButtonMenuItem classe substitui membros como OnCheckedChanged e
OnPaint para fornecer o comportamento de seleção e a aparência dos botões de opção.

Além disso, essa classe substitui a propriedade para que as Enabled opções em um
submenu sejam desabilitadas, a menos que o item pai esteja selecionado.
Implementar o comportamento de seleção do

botão de opção
1. Inicialize a CheckOnClick propriedade para para true habilitar a seleção de itens.
C#
// Called by all constructors to initialize CheckOnClick.

private void Initialize()
{
CheckOnClick = true;
}
2. Substitua o OnCheckedChanged método para limpar a seleção do item

selecionado anteriormente quando um novo item for selecionado.
C#
protected override void OnCheckedChanged(EventArgs e)
{
base.OnCheckedChanged(e);
// If this item is no longer in the checked state or if its

// parent has not yet been initialized, do nothing.
if (!Checked || this.Parent == null) return;
// Clear the checked state for all siblings.

foreach (ToolStripItem item in Parent.Items)
{
ToolStripRadioButtonMenuItem radioItem =
item as ToolStripRadioButtonMenuItem;
if (radioItem != null && radioItem != this &&
radioItem.Checked)
{
radioItem.Checked = false;
// Only one item can be selected at a time,

// so there is no need to continue.
return;
}
}
}
3. Substitua o OnClick método para garantir que clicar em um item que já foi
selecionado não limpará a seleção.
C#
protected override void OnClick(EventArgs e)

{
// If the item is already in the checked state, do not call
// the base method, which would toggle the value.
if (Checked) return;
base.OnClick(e);
}
Modificar a aparência dos itens do botão de

opção
1. Substitua o OnPaint método para substituir a marca de marcar padrão por um
botão de opção usando a RadioButtonRenderer classe .
C#
// Let the item paint itself, and then paint the RadioButton
// where the check mark is normally displayed.
protected override void OnPaint(PaintEventArgs e)
{
if (Image != null)
{
// If the client sets the Image property, the selection
behavior
// remains unchanged, but the RadioButton is not displayed and
the
// selection is indicated only by the selection rectangle.
base.OnPaint(e);
return;
}
else
{
// If the Image property is not set, call the base OnPaint
method
// with the CheckState property temporarily cleared to prevent
// the check mark from being painted.
CheckState currentState = this.CheckState;
this.CheckState = CheckState.Unchecked;
base.OnPaint(e);
this.CheckState = currentState;
}
// Determine the correct state of the RadioButton.

RadioButtonState buttonState = RadioButtonState.UncheckedNormal;
if (Enabled)
{
if (mouseDownState)
{
if (Checked) buttonState = RadioButtonState.CheckedPressed;
else buttonState = RadioButtonState.UncheckedPressed;
}
else if (mouseHoverState)
{
if (Checked) buttonState = RadioButtonState.CheckedHot;
else buttonState = RadioButtonState.UncheckedHot;
}
else
{
if (Checked) buttonState = RadioButtonState.CheckedNormal;
}
}
else
{
if (Checked) buttonState = RadioButtonState.CheckedDisabled;
else buttonState = RadioButtonState.UncheckedDisabled;
}
// Calculate the position at which to display the RadioButton.

Int32 offset = (ContentRectangle.Height -
RadioButtonRenderer.GetGlyphSize(
e.Graphics, buttonState).Height) / 2;
Point imageLocation = new Point(
ContentRectangle.Location.X + 4,
ContentRectangle.Location.Y + offset);
// Paint the RadioButton.

RadioButtonRenderer.DrawRadioButton(
e.Graphics, imageLocation, buttonState);
}
2. Substitua os OnMouseEntermétodos , OnMouseLeave, OnMouseDowne

OnMouseUp para acompanhar o estado do mouse e garantir que o OnPaint
método pinte o estado correto do botão de opção.
C#
private bool mouseHoverState = false;
protected override void OnMouseEnter(EventArgs e)

{
mouseHoverState = true;
// Force the item to repaint with the new RadioButton state.

Invalidate();
base.OnMouseEnter(e);
}
protected override void OnMouseLeave(EventArgs e)

{
mouseHoverState = false;
base.OnMouseLeave(e);
}
private bool mouseDownState = false;
protected override void OnMouseDown(MouseEventArgs e)

{
mouseDownState = true;

Invalidate();
base.OnMouseDown(e);
}
protected override void OnMouseUp(MouseEventArgs e)

{
mouseDownState = false;
base.OnMouseUp(e);
}
Desabilitar as opções em um submenu quando
o item pai não está selecionado
1. Substitua a Enabled propriedade para que o item seja desabilitado quando tiver
um item pai com um CheckOnClick valor de true e um Checked valor de false .
C#
// Enable the item only if its parent item is in the checked state
// and its Enabled property has not been explicitly set to false.
public override bool Enabled
{
get
{
ToolStripMenuItem ownerMenuItem =
OwnerItem as ToolStripMenuItem;
// Use the base value in design mode to prevent the designer

// from setting the base value to the calculated value.
if (!DesignMode &&
ownerMenuItem != null && ownerMenuItem.CheckOnClick)
{
return base.Enabled && ownerMenuItem.Checked;
}
else
{
return base.Enabled;
}
}
set
{
base.Enabled = value;
}
}
2. Substitua o OnOwnerChanged método para assinar o CheckedChanged evento do

item pai.
C#
// When OwnerItem becomes available, if it is a ToolStripMenuItem

// with a CheckOnClick property value of true, subscribe to its
// CheckedChanged event.
protected override void OnOwnerChanged(EventArgs e)
{
if (ownerMenuItem != null && ownerMenuItem.CheckOnClick)
{
ownerMenuItem.CheckedChanged +=
new EventHandler(OwnerMenuItem_CheckedChanged);
}
base.OnOwnerChanged(e);
}
3. No manipulador do evento pai-item CheckedChanged , invalide o item para

atualizar a exibição com o novo estado habilitado.
C#
// When the checked state of the parent item changes,

// repaint the item so that the new Enabled state is displayed.
private void OwnerMenuItem_CheckedChanged(
{
Invalidate();
}
Exemplo
O exemplo de código a seguir fornece a classe completa ToolStripRadioButtonMenuItem
e uma classe e Program classe Form para demonstrar o comportamento do botão de
opção.
C#
using System;
using System.Windows.Forms.VisualStyles;
public class ToolStripRadioButtonMenuItem : ToolStripMenuItem

{
public ToolStripRadioButtonMenuItem()
: base()
{
Initialize();
}
public ToolStripRadioButtonMenuItem(string text)

: base(text, null, (EventHandler)null)
{
Initialize();
}
public ToolStripRadioButtonMenuItem(Image image)

: base(null, image, (EventHandler)null)
{
Initialize();
}
public ToolStripRadioButtonMenuItem(string text, Image image)

: base(text, image, (EventHandler)null)
{
Initialize();
}
public ToolStripRadioButtonMenuItem(string text, Image image,

EventHandler onClick)
: base(text, image, onClick)
{
Initialize();
}

EventHandler onClick, string name)
: base(text, image, onClick, name)
{
Initialize();
}

params ToolStripItem[] dropDownItems)
: base(text, image, dropDownItems)
{
Initialize();
}

EventHandler onClick, Keys shortcutKeys)
: base(text, image, onClick)
{
Initialize();
this.ShortcutKeys = shortcutKeys;
}
// Called by all constructors to initialize CheckOnClick.

private void Initialize()
{
CheckOnClick = true;
}
protected override void OnCheckedChanged(EventArgs e)

{
base.OnCheckedChanged(e);
// If this item is no longer in the checked state or if its

// parent has not yet been initialized, do nothing.
if (!Checked || this.Parent == null) return;
// Clear the checked state for all siblings.

foreach (ToolStripItem item in Parent.Items)
{
ToolStripRadioButtonMenuItem radioItem =
item as ToolStripRadioButtonMenuItem;
if (radioItem != null && radioItem != this && radioItem.Checked)
{
radioItem.Checked = false;
// Only one item can be selected at a time,

// so there is no need to continue.
return;
}
}
}
protected override void OnClick(EventArgs e)

{
// If the item is already in the checked state, do not call
// the base method, which would toggle the value.
if (Checked) return;
base.OnClick(e);
}
// Let the item paint itself, and then paint the RadioButton
// where the check mark is normally displayed.
{
if (Image != null)
{
// If the client sets the Image property, the selection behavior
// remains unchanged, but the RadioButton is not displayed and
the
// selection is indicated only by the selection rectangle.
base.OnPaint(e);
return;
}
else
{
// If the Image property is not set, call the base OnPaint
method
// with the CheckState property temporarily cleared to prevent
// the check mark from being painted.
CheckState currentState = this.CheckState;
this.CheckState = CheckState.Unchecked;
base.OnPaint(e);
this.CheckState = currentState;
}
// Determine the correct state of the RadioButton.

RadioButtonState buttonState = RadioButtonState.UncheckedNormal;
if (Enabled)
{
if (mouseDownState)
{
if (Checked) buttonState = RadioButtonState.CheckedPressed;
else buttonState = RadioButtonState.UncheckedPressed;
}
else if (mouseHoverState)
{
if (Checked) buttonState = RadioButtonState.CheckedHot;
else buttonState = RadioButtonState.UncheckedHot;
}
else
{
if (Checked) buttonState = RadioButtonState.CheckedNormal;
}
}
else
{
if (Checked) buttonState = RadioButtonState.CheckedDisabled;
else buttonState = RadioButtonState.UncheckedDisabled;
}
// Calculate the position at which to display the RadioButton.

Int32 offset = (ContentRectangle.Height -
RadioButtonRenderer.GetGlyphSize(
e.Graphics, buttonState).Height) / 2;
Point imageLocation = new Point(
ContentRectangle.Location.X + 4,
ContentRectangle.Location.Y + offset);
// Paint the RadioButton.

RadioButtonRenderer.DrawRadioButton(
e.Graphics, imageLocation, buttonState);
}
private bool mouseHoverState = false;
protected override void OnMouseEnter(EventArgs e)

{
mouseHoverState = true;

Invalidate();
base.OnMouseEnter(e);
}
protected override void OnMouseLeave(EventArgs e)

{
mouseHoverState = false;
base.OnMouseLeave(e);
}
private bool mouseDownState = false;
protected override void OnMouseDown(MouseEventArgs e)

{
mouseDownState = true;

Invalidate();
}
protected override void OnMouseUp(MouseEventArgs e)

{
mouseDownState = false;
base.OnMouseUp(e);
}
// Enable the item only if its parent item is in the checked state
// and its Enabled property has not been explicitly set to false.
public override bool Enabled
{
get
{
// Use the base value in design mode to prevent the designer

// from setting the base value to the calculated value.
if (!DesignMode &&
ownerMenuItem != null && ownerMenuItem.CheckOnClick)
{
return base.Enabled && ownerMenuItem.Checked;
}
else
{
return base.Enabled;
}
}
set
{
base.Enabled = value;
}
}
// When OwnerItem becomes available, if it is a ToolStripMenuItem

// with a CheckOnClick property value of true, subscribe to its
// CheckedChanged event.
protected override void OnOwnerChanged(EventArgs e)
{
if (ownerMenuItem != null && ownerMenuItem.CheckOnClick)
{
ownerMenuItem.CheckedChanged +=
new EventHandler(OwnerMenuItem_CheckedChanged);
}
base.OnOwnerChanged(e);
}
// When the checked state of the parent item changes,

// repaint the item so that the new Enabled state is displayed.
private void OwnerMenuItem_CheckedChanged(
{
Invalidate();
}
}

{
private MenuStrip menuStrip1 = new MenuStrip();
private ToolStripMenuItem mainToolStripMenuItem = new
ToolStripMenuItem();
private ToolStripMenuItem toolStripMenuItem1 = new ToolStripMenuItem();
private ToolStripRadioButtonMenuItem toolStripRadioButtonMenuItem1 =
new ToolStripRadioButtonMenuItem();
public Form1()
{
mainToolStripMenuItem.Text = "main";
toolStripRadioButtonMenuItem1.Text = "option 1";
toolStripRadioButtonMenuItem2.Text = "option 2";
toolStripRadioButtonMenuItem3.Text = "option 2-1";
toolStripMenuItem1.Text = "toggle";
toolStripMenuItem1.CheckOnClick = true;
mainToolStripMenuItem.DropDownItems.AddRange(new ToolStripItem[] {
toolStripRadioButtonMenuItem1, toolStripRadioButtonMenuItem2,
toolStripMenuItem1});
toolStripRadioButtonMenuItem2.DropDownItems.AddRange(
new ToolStripItem[] {toolStripRadioButtonMenuItem3,
toolStripRadioButtonMenuItem4});
toolStripMenuItem1.DropDownItems.AddRange(new ToolStripItem[] {
toolStripRadioButtonMenuItem5, toolStripRadioButtonMenuItem6});
menuStrip1.Items.AddRange(new ToolStripItem[]
{mainToolStripMenuItem});
Controls.Add(menuStrip1);
MainMenuStrip = menuStrip1;
Text = "ToolStripRadioButtonMenuItem demo";
}
}

{
[STAThread]
static void Main()
{
Application.SetCompatibleTextRenderingDefault(false);
}
}
Confira também
MenuStrip
ToolStripMenuItem
ToolStripMenuItem.CheckOnClick
ToolStripMenuItem.Checked
ToolStripMenuItem.OnCheckedChanged
ToolStripMenuItem.OnPaint
ToolStripMenuItem.Enabled
RadioButtonRenderer
Controle MenuStrip
Como: Implementar um ToolStripRenderer personalizado
Artigo • 02/06/2023
Ocultar itens de menu é uma maneira de controlar a interface do usuário do aplicativo e

restringir os comandos do usuário. Geralmente, é recomendável ocultar um menu
inteiro quando todos os itens de menu estão indisponíveis. Isso apresenta menos
distrações para o usuário. Além disso, pode ser útil ocultar e desabilitar o menu ou item
de menu, visto que apenas ocultar não impede que o usuário acesse um comando de
menu usando uma tecla de atalho.
Para ocultar qualquer item de menu programaticamente

Dentro do método em que você define as propriedades do item de menu,
adicione o código para definir a Visible propriedade como false .
C#
menuItem3.Visible = false;
Confira também
Visible
MenuStrip
usando o designer
Artigo • 02/06/2023
Ocultar itens de menu é uma maneira de controlar a interface do usuário (IU) do seu
aplicativo e restringir comandos do usuário. Geralmente, é recomendável ocultar um
menu inteiro quando todos os itens de menu estão indisponíveis. Isso apresenta menos
distrações para o usuário. Além disso, pode ser útil ocultar e desabilitar o menu ou item
de menu, visto que apenas ocultar não impede que o usuário acesse um comando de
menu usando uma tecla de atalho. Para obter mais informações sobre como desabilitar
itens de menu, consulte Como desabilitar ToolStripMenuItems usando o Designer.
Ocultar um menu de nível superior e seus itens

de submenu
1. Selecione o item de menu de nível superior e defina sua Visible propriedade
false como Available .
Quando você oculta o item de menu de nível superior, todos os itens de menu
dentro desse menu também são ocultos. Se você clicar em outro lugar que não
seja na configuração Visible após, MenuStrip false todo o item de menu de nível
superior e seus itens de submenu desaparecerão do formulário, mostrando assim
o efeito de tempo de execução de sua ação. Para exibir o item de menu de nível
superior oculto no momento do design, clique na Bandeja de
MenuStripComponentes, na Estrutura de Tópicos do Documento ou na parte
superior da grade de propriedades.
７ Observação
Você raramente ocultará um menu inteiro, exceto por menus filho MDI (interface
de vários documentos) em um cenário de mesclagem.
Ocultar um item de submenu

1. Selecione o item de submenu e defina sua Visible propriedade como false .
Quando você oculta um item de submenu, ele permanece visível no formulário no

tempo de design para que você pode selecioná-lo facilmente para continuar
trabalhando nele. Ele será ocultado efetivamente no tempo de execução.
Confira também
Visible
MenuStrip
Enabled
Available
Overflow
Como: Desabilitar ToolStripMenuItems usando o designer
Como inserir um MenuStrip um menu
suspenso MDI (Windows Forms)
Artigo • 21/06/2023
O procedimento a seguir usa as IsMdiContainerpropriedades , AllowMerge,

MergeActione MergeIndex para inserir um grupo de itens de menu do menu filho MDI
na parte suspensa do menu pai do MDI. Fechar a janela MDI filho remove os itens de
menu inseridos do MDI pai.
Como inserir um MenuStrip em um menu suspenso MDI

1. Crie um formulário e defina sua IsMdiContainer propriedade como true .

como true .
propriedade como &File .
4. Adicione três itens de submenu ao item de &File menu e defina suas Text
propriedades como &Open , &Import from e E&xit .
5. Adicione dois itens de submenu ao &Import from item submenu e defina suas Text
propriedades como &Word e &Excel .

8. Adicione itens de submenu ao &File menu de Form2 na seguinte ordem: um

ToolStripSeparator, &Save , Save and &Close e outro ToolStripSeparator.
9. Defina as MergeAction propriedades e MergeIndex dos itens de Form2 menu,
conforme mostrado na tabela a seguir.
Item de menu Form2 Valor de MergeAction Valor de MergeIndex
Arquivo MatchOnly -1
Separador Inserir 2
Salvar Inserir 3
Salvar e Fechar Inserir 4
Separador Inserir 5
10. Crie um manipulador de eventos para o Click evento do &Open ToolStripMenuItem.

seguir para criar e exibir novas instâncias de Form2 como filhos MDI de Form1 .
C#

{
newMDIChild.Show();
}

C#
this.openToolStripMenuItem.Click += new

Confira também
Como remover um ToolStripMenuItem
de um menu suspenso MDI (Windows
Forms)
Artigo • 21/06/2023
O procedimento a seguir usa as IsMdiContainerpropriedades , AllowMerge,

MergeActione MergeIndex para remover um item de menu da parte suspensa do menu
pai da MDI. Fechar a janela filho MDI restaura os itens de menu removidos para o menu
pai da MDI.
Para remover um MenuStrip de um menu suspenso MDI

1. Crie um formulário e defina sua IsMdiContainer propriedade como true .

como true .
4. Adicione três itens de submenu ao item de &File menu e defina suas Text
propriedades como &Open , &Import from e E&xit .
5. Adicione dois itens de submenu ao &Import from item submenu e defina suas Text
propriedades como &Word e &Excel .

8. Adicione um &Import from item de submenu ao &File menu de Form2 e adicione

um &Word item de submenu ao &File menu.
9. Defina as MergeAction propriedades e MergeIndex dos itens de Form2 menu,
conforme mostrado na tabela a seguir.
Item de menu Form2 Valor de MergeAction Valor de MergeIndex
Arquivo MatchOnly -1
Importar do MatchOnly -1
Word Remover -1
10. No Form1 , crie um manipulador de eventos para o Click evento do

&Open ToolStripMenuItem.

seguir para criar e exibir novas instâncias de Form2 como filhos MDI de Form1 :
C#

{
newMDIChild.Show();
}

C#
this.openToolStripMenuItem.Click += new _

Confira também
Como: Mover ToolStripMenuItems
Artigo • 02/06/2023
Em tempo de design, você pode mover menus de nível superior inteiros e seus itens de
menu para um lugar diferente no MenuStrip. Você também pode mover itens de menu
individuais entre menus de nível superior ou alterar a posição dos itens de menu dentro
de um menu.
Mover um menu de nível superior e seus itens

de menu para outro local de nível superior
1. Clique e mantenha pressionado o botão esquerdo do mouse no menu que você
deseja mover.
2. Arraste o ponto de inserção para o menu de nível superior que está antes do novo
local desejado e solte o botão esquerdo do mouse.
O menu selecionado se move para a direita do ponto de inserção.
Mover um menu de nível superior e seus itens

de menu para outro local suspenso
1. Clique com o botão esquerdo do mouse no menu que você deseja mover e
pressione CTRL + X ou clique com o botão direito do mouse no menu e selecione
Recortar no menu de atalho.
2. No menu de nível superior de destino, clique com o botão esquerdo do mouse no

item de menu acima do novo local desejado e pressione CTRL + V, ou clique com
o botão direito do mouse no item de menu acima do novo local desejado e
selecione Colar no menu de atalho.
O menu que você recorta é inserido após o item de menu selecionado.
Mover um item de menu de dentro de um

menu usando o Editor de coleção de itens
1. Clique com o botão direito do mouse no menu que contém o item de menu que
você deseja mover.
2. No menu de atalho, escolha Editar DropDownItems.
3. No Editor de Coleção de Itens, clique com o botão esquerdo do mouse no item

de menu que você deseja mover.
4. Clique nas teclas de direção para cima e para baixo para mover o item de menu no
menu.
5. Clique em OK.
Mover um item de menu de dentro de um

menu usando o teclado
1. Pressione e mantenha a tecla ALT pressionada.
2. Clique e mantenha pressionado o botão esquerdo do mouse no item de menu que

você deseja mover.
3. Arraste o item de menu para o novo local e solte o botão esquerdo do mouse.
Mover um item de menu para outro menu

1. Clique com o botão esquerdo do mouse no item de menu que você deseja mover
e pressione CTRL + X ou clique com o botão direito do mouse no item de menu e
escolha Recortar no menu de atalho.
2. Clique com o botão esquerdo do mouse no menu que contém o item de menu
que você recortou.
3. Clique com o botão esquerdo do mouse no item de menu anterior ao novo local
desejado e pressione CTRL + V, ou clique com o botão direito do mouse no item
de menu anterior ao novo local desejado e selecione Colar no menu de atalho.
O item de menu que você recortou é inserido após o item de menu selecionado.
Confira também
MenuStrip
ToolStripMenuItem
Como: Configurar margens de imagem
e margens de verificação MenuStrip
Artigo • 02/06/2023
Você pode personalizar um MenuStrip definindo as propriedades e ShowCheckMargin

as ShowImageMargin propriedades em várias combinações.
Exemplo
O exemplo de código a seguir demonstra como definir e personalizar as margens de
verificação e as ContextMenuStrip margens de imagem. O procedimento é o mesmo
para um ContextMenuStrip ou um MenuStrip.
C#

class Form5 : Form
{
public Form5()
{
this.Width = 500;




false;

false;




}

{

{
p.Width = 4;

new Point(4,14),
new Point(16,24),
new Point(28,14)};
// Draw the mouth.

// Draw the eyes.

3)));
3)));
}
}

{
ContextMenuStrip();





}
}
Confira também
MenuStrip
ContextMenuStrip
ToolStripDropDown
Controle ToolStrip
Como: Habilitar margens de verificação e de imagem em controles
ContextMenuStrip
Como: Fornecer itens de menu padrão
para um formulário
Artigo • 02/06/2023
Você pode fornecer um menu padrão para seus formulários com o MenuStrip controle.
Há um amplo suporte para esse recurso no Visual Studio.
Confira também passo a passo: fornecendo itens de menu padrão para um formulário.
Exemplo
O exemplo de código a seguir demonstra como usar um MenuStrip controle para criar
um formulário com um menu padrão. As seleções de item de menu são exibidas em um
StatusStrip controle.
C#
using System;
namespace StandardMenuFormCS
{
{
private StatusStrip statusStrip1;
private ToolStripStatusLabel toolStripStatusLabel1;
/// <summary>
/// </summary>
public Form1()
{
}

{
{
}
}
// This utility method assigns the value of a ToolStripItem

// control's Text property to the Text property of the
// ToolStripStatusLabel.
private void UpdateStatus(ToolStripItem item)
{
if (item != null)
{
string msg = String.Format("{0} selected", item.Text);
this.statusStrip1.Items[0].Text = msg;
}
}
// This method is the DropDownItemClicked event handler.

// It passes the ClickedItem object to a utility method
// called UpdateStatus, which updates the text displayed
// in the StatusStrip control.
private void fileToolStripMenuItem_DropDownItemClicked(
object sender, ToolStripItemClickedEventArgs e)
{
this.UpdateStatus(e.ClickedItem);
}
/// <summary>
/// </summary>
{
System.ComponentModel.ComponentResourceManager resources = new
this.menuStrip1 = new System.Windows.Forms.MenuStrip();
this.fileToolStripMenuItem = new
this.newToolStripMenuItem = new
this.openToolStripMenuItem = new
this.toolStripSeparator = new
this.saveToolStripMenuItem = new
this.saveAsToolStripMenuItem = new
this.toolStripSeparator1 = new
this.printToolStripMenuItem = new
this.printPreviewToolStripMenuItem = new
this.exitToolStripMenuItem = new
this.editToolStripMenuItem = new
this.undoToolStripMenuItem = new
this.redoToolStripMenuItem = new
this.cutToolStripMenuItem = new
this.copyToolStripMenuItem = new
this.pasteToolStripMenuItem = new
this.selectAllToolStripMenuItem = new
this.toolsToolStripMenuItem = new
this.customizeToolStripMenuItem = new
this.optionsToolStripMenuItem = new
this.helpToolStripMenuItem = new
this.contentsToolStripMenuItem = new
this.indexToolStripMenuItem = new
this.searchToolStripMenuItem = new
this.aboutToolStripMenuItem = new
this.statusStrip1 = new System.Windows.Forms.StatusStrip();
this.toolStripStatusLabel1 = new
System.Windows.Forms.ToolStripStatusLabel();
this.menuStrip1.SuspendLayout();
this.statusStrip1.SuspendLayout();
//
// menuStrip1
//
this.menuStrip1.Items.AddRange(new
this.fileToolStripMenuItem,
this.editToolStripMenuItem,
this.toolsToolStripMenuItem,
this.helpToolStripMenuItem});
this.menuStrip1.Location = new System.Drawing.Point(0, 0);
this.menuStrip1.Name = "menuStrip1";
this.menuStrip1.Size = new System.Drawing.Size(292, 24);
this.menuStrip1.TabIndex = 0;
this.menuStrip1.Text = "menuStrip1";
//
// fileToolStripMenuItem
//
this.fileToolStripMenuItem.DropDownItems.AddRange(new
this.newToolStripMenuItem,
this.openToolStripMenuItem,
this.toolStripSeparator,
this.saveToolStripMenuItem,
this.saveAsToolStripMenuItem,
this.printToolStripMenuItem,
this.printPreviewToolStripMenuItem,
this.exitToolStripMenuItem});
this.fileToolStripMenuItem.Name = "fileToolStripMenuItem";
this.fileToolStripMenuItem.Size = new System.Drawing.Size(35,
20);
this.fileToolStripMenuItem.Text = "&File";
this.fileToolStripMenuItem.DropDownItemClicked += new
System.Windows.Forms.ToolStripItemClickedEventHandler(this.fileToolStripMenu
Item_DropDownItemClicked);
//
// newToolStripMenuItem
//
this.newToolStripMenuItem.Image = ((System.Drawing.Image)
(resources.GetObject("newToolStripMenuItem.Image")));
this.newToolStripMenuItem.ImageTransparentColor =
this.newToolStripMenuItem.Name = "newToolStripMenuItem";
this.newToolStripMenuItem.ShortcutKeys =
((System.Windows.Forms.Keys)((System.Windows.Forms.Keys.Control |
System.Windows.Forms.Keys.N)));
this.newToolStripMenuItem.Size = new System.Drawing.Size(152,
22);
this.newToolStripMenuItem.Text = "&New";
//
// openToolStripMenuItem
//
this.openToolStripMenuItem.Image = ((System.Drawing.Image)
(resources.GetObject("openToolStripMenuItem.Image")));
this.openToolStripMenuItem.ImageTransparentColor =
this.openToolStripMenuItem.Name = "openToolStripMenuItem";
this.openToolStripMenuItem.ShortcutKeys =
System.Windows.Forms.Keys.O)));
this.openToolStripMenuItem.Size = new System.Drawing.Size(152,
22);
this.openToolStripMenuItem.Text = "&Open";
//
// toolStripSeparator
//
this.toolStripSeparator.Name = "toolStripSeparator";
this.toolStripSeparator.Size = new System.Drawing.Size(149, 6);
//
// saveToolStripMenuItem
//
this.saveToolStripMenuItem.Image = ((System.Drawing.Image)
(resources.GetObject("saveToolStripMenuItem.Image")));
this.saveToolStripMenuItem.ImageTransparentColor =
this.saveToolStripMenuItem.Name = "saveToolStripMenuItem";
this.saveToolStripMenuItem.ShortcutKeys =
System.Windows.Forms.Keys.S)));
this.saveToolStripMenuItem.Size = new System.Drawing.Size(152,
22);
this.saveToolStripMenuItem.Text = "&Save";
//
// saveAsToolStripMenuItem
//
this.saveAsToolStripMenuItem.Name = "saveAsToolStripMenuItem";
this.saveAsToolStripMenuItem.Size = new System.Drawing.Size(152,
22);
this.saveAsToolStripMenuItem.Text = "Save &As";
//
// toolStripSeparator1
//
this.toolStripSeparator1.Name = "toolStripSeparator1";
this.toolStripSeparator1.Size = new System.Drawing.Size(149, 6);
//
// printToolStripMenuItem
//
this.printToolStripMenuItem.Image = ((System.Drawing.Image)
(resources.GetObject("printToolStripMenuItem.Image")));
this.printToolStripMenuItem.ImageTransparentColor =
this.printToolStripMenuItem.Name = "printToolStripMenuItem";
this.printToolStripMenuItem.ShortcutKeys =
System.Windows.Forms.Keys.P)));
this.printToolStripMenuItem.Size = new System.Drawing.Size(152,
22);
this.printToolStripMenuItem.Text = "&Print";
//
// printPreviewToolStripMenuItem
//
this.printPreviewToolStripMenuItem.Image =
(resources.GetObject("printPreviewToolStripMenuItem.Image")));
this.printPreviewToolStripMenuItem.ImageTransparentColor =
this.printPreviewToolStripMenuItem.Name =
"printPreviewToolStripMenuItem";
this.printPreviewToolStripMenuItem.Size = new
this.printPreviewToolStripMenuItem.Text = "Print Pre&view";
//
//
//
// exitToolStripMenuItem
//
this.exitToolStripMenuItem.Name = "exitToolStripMenuItem";
this.exitToolStripMenuItem.Size = new System.Drawing.Size(152,
22);
this.exitToolStripMenuItem.Text = "E&xit";
//
// editToolStripMenuItem
//
this.editToolStripMenuItem.DropDownItems.AddRange(new
this.undoToolStripMenuItem,
this.redoToolStripMenuItem,
this.cutToolStripMenuItem,
this.copyToolStripMenuItem,
this.pasteToolStripMenuItem,
this.selectAllToolStripMenuItem});
this.editToolStripMenuItem.Name = "editToolStripMenuItem";
this.editToolStripMenuItem.Size = new System.Drawing.Size(37,
20);
this.editToolStripMenuItem.Text = "&Edit";
//
// undoToolStripMenuItem
//
this.undoToolStripMenuItem.Name = "undoToolStripMenuItem";
this.undoToolStripMenuItem.ShortcutKeys =
System.Windows.Forms.Keys.Z)));
this.undoToolStripMenuItem.Size = new System.Drawing.Size(150,
22);
this.undoToolStripMenuItem.Text = "&Undo";
//
// redoToolStripMenuItem
//
this.redoToolStripMenuItem.Name = "redoToolStripMenuItem";
this.redoToolStripMenuItem.ShortcutKeys =
System.Windows.Forms.Keys.Y)));
this.redoToolStripMenuItem.Size = new System.Drawing.Size(150,
22);
this.redoToolStripMenuItem.Text = "&Redo";
//
//
//
// cutToolStripMenuItem
//
this.cutToolStripMenuItem.Image = ((System.Drawing.Image)
(resources.GetObject("cutToolStripMenuItem.Image")));
this.cutToolStripMenuItem.ImageTransparentColor =
this.cutToolStripMenuItem.Name = "cutToolStripMenuItem";
this.cutToolStripMenuItem.ShortcutKeys =
System.Windows.Forms.Keys.X)));
this.cutToolStripMenuItem.Size = new System.Drawing.Size(150,
22);
this.cutToolStripMenuItem.Text = "Cu&t";
//
// copyToolStripMenuItem
//
this.copyToolStripMenuItem.Image = ((System.Drawing.Image)
(resources.GetObject("copyToolStripMenuItem.Image")));
this.copyToolStripMenuItem.ImageTransparentColor =
this.copyToolStripMenuItem.Name = "copyToolStripMenuItem";
this.copyToolStripMenuItem.ShortcutKeys =
System.Windows.Forms.Keys.C)));
this.copyToolStripMenuItem.Size = new System.Drawing.Size(150,
22);
this.copyToolStripMenuItem.Text = "&Copy";
//
// pasteToolStripMenuItem
//
this.pasteToolStripMenuItem.Image = ((System.Drawing.Image)
(resources.GetObject("pasteToolStripMenuItem.Image")));
this.pasteToolStripMenuItem.ImageTransparentColor =
this.pasteToolStripMenuItem.Name = "pasteToolStripMenuItem";
this.pasteToolStripMenuItem.ShortcutKeys =
System.Windows.Forms.Keys.V)));
this.pasteToolStripMenuItem.Size = new System.Drawing.Size(150,
22);
this.pasteToolStripMenuItem.Text = "&Paste";
//
//
//
// selectAllToolStripMenuItem
//
this.selectAllToolStripMenuItem.Name =
"selectAllToolStripMenuItem";
this.selectAllToolStripMenuItem.Size = new
this.selectAllToolStripMenuItem.Text = "Select &All";
//
// toolsToolStripMenuItem
//
this.toolsToolStripMenuItem.DropDownItems.AddRange(new
this.customizeToolStripMenuItem,
this.optionsToolStripMenuItem});
this.toolsToolStripMenuItem.Name = "toolsToolStripMenuItem";
this.toolsToolStripMenuItem.Size = new System.Drawing.Size(44,
20);
this.toolsToolStripMenuItem.Text = "&Tools";
//
// customizeToolStripMenuItem
//
this.customizeToolStripMenuItem.Name =
"customizeToolStripMenuItem";
this.customizeToolStripMenuItem.Size = new
this.customizeToolStripMenuItem.Text = "&Customize";
//
// optionsToolStripMenuItem
//
this.optionsToolStripMenuItem.Name = "optionsToolStripMenuItem";
this.optionsToolStripMenuItem.Size = new
this.optionsToolStripMenuItem.Text = "&Options";
//
// helpToolStripMenuItem
//
this.helpToolStripMenuItem.DropDownItems.AddRange(new
this.contentsToolStripMenuItem,
this.indexToolStripMenuItem,
this.searchToolStripMenuItem,
this.aboutToolStripMenuItem});
this.helpToolStripMenuItem.Name = "helpToolStripMenuItem";
this.helpToolStripMenuItem.Size = new System.Drawing.Size(40,
20);
this.helpToolStripMenuItem.Text = "&Help";
//
// contentsToolStripMenuItem
//
this.contentsToolStripMenuItem.Name =
"contentsToolStripMenuItem";
this.contentsToolStripMenuItem.Size = new
this.contentsToolStripMenuItem.Text = "&Contents";
//
// indexToolStripMenuItem
//
this.indexToolStripMenuItem.Name = "indexToolStripMenuItem";
this.indexToolStripMenuItem.Size = new System.Drawing.Size(129,
22);
this.indexToolStripMenuItem.Text = "&Index";
//
// searchToolStripMenuItem
//
this.searchToolStripMenuItem.Name = "searchToolStripMenuItem";
this.searchToolStripMenuItem.Size = new System.Drawing.Size(129,
22);
this.searchToolStripMenuItem.Text = "&Search";
//
//
//
// aboutToolStripMenuItem
//
this.aboutToolStripMenuItem.Name = "aboutToolStripMenuItem";
this.aboutToolStripMenuItem.Size = new System.Drawing.Size(129,
22);
this.aboutToolStripMenuItem.Text = "&About...";
//
// statusStrip1
//
this.statusStrip1.Items.AddRange(new
this.toolStripStatusLabel1});
this.statusStrip1.Location = new System.Drawing.Point(0, 251);
this.statusStrip1.Name = "statusStrip1";
this.statusStrip1.Size = new System.Drawing.Size(292, 22);
this.statusStrip1.TabIndex = 1;
this.statusStrip1.Text = "statusStrip1";
//
// toolStripStatusLabel1
//
this.toolStripStatusLabel1.Name = "toolStripStatusLabel1";
this.toolStripStatusLabel1.Size = new System.Drawing.Size(109,
17);
this.toolStripStatusLabel1.Text = "toolStripStatusLabel1";
//
// Form1
//
this.Controls.Add(this.statusStrip1);
this.Controls.Add(this.menuStrip1);
this.MainMenuStrip = this.menuStrip1;
this.menuStrip1.ResumeLayout(false);
this.menuStrip1.PerformLayout();
this.statusStrip1.ResumeLayout(false);
this.statusStrip1.PerformLayout();
}
#endregion
private System.Windows.Forms.MenuStrip menuStrip1;

private System.Windows.Forms.ToolStripMenuItem
fileToolStripMenuItem;
private System.Windows.Forms.ToolStripMenuItem newToolStripMenuItem;
openToolStripMenuItem;
private System.Windows.Forms.ToolStripSeparator toolStripSeparator;
saveToolStripMenuItem;
saveAsToolStripMenuItem;
private System.Windows.Forms.ToolStripSeparator toolStripSeparator1;
printToolStripMenuItem;
printPreviewToolStripMenuItem;
exitToolStripMenuItem;
editToolStripMenuItem;
undoToolStripMenuItem;
redoToolStripMenuItem;
private System.Windows.Forms.ToolStripMenuItem cutToolStripMenuItem;
copyToolStripMenuItem;
pasteToolStripMenuItem;
selectAllToolStripMenuItem;
toolsToolStripMenuItem;
customizeToolStripMenuItem;
optionsToolStripMenuItem;
helpToolStripMenuItem;
contentsToolStripMenuItem;
indexToolStripMenuItem;
searchToolStripMenuItem;
aboutToolStripMenuItem;
}

{
/// <summary>
/// </summary>
[STAThread]
static void Main()
{
}
}
}
Confira também
MenuStrip
ToolStrip
StatusStrip
Controle MenuStrip
Como: Configurar a mesclagem de
menu automática para aplicativos MDI
Artigo • 02/06/2023
O procedimento a seguir fornece as etapas básicas para configurar a mesclagem

automática em um aplicativo MDI (interface de vários documentos) com MenuStrip.
Para configurar a mesclagem de menu automática

1. Crie o formulário pai do MDI definindo sua IsMdiContainer propriedade como
true .
2. Adicione um MenuStrip ao pai MDI, definindo sua MainMenuStrip propriedade

para isso MenuStrip.
3. Crie um formulário filho MDI e defina sua MdiParent propriedade como o nome
do formulário pai.
4. Adicione um MenuStrip ao formulário filho MDI.
5. No formulário filho, defina a Visible propriedade como MenuStrip false .
6. Adicione itens de menu aos formulários MenuStrip filho que você deseja mesclar
no formulário MenuStrip pai quando o formulário filho for ativado.
7. Use a MergeAction propriedade nos itens de menu no formulário MenuStrip filho

para controlar como eles se mesclam no formulário pai.
Confira também
MenuStrip
ToolStripMenuItem
Mesclando itens de menu no controle
MenuStrip dos Windows Forms
Artigo • 02/06/2023
Se tiver um aplicativo de interface MDI, você poderá mesclar os itens de menu ou os

menus inteiros do formulário filho com os menus do formulário pai.
Este tópico descreve os conceitos básicos associados aos itens de menu de mesclagem
em um aplicativo MDI.
Conceitos gerais
Os procedimentos de mesclagem envolvem um controle do código-fonte e de destino:
O destino é o MenuStrip controle no formulário pai principal ou MDI no qual você

está mesclando itens de menu.
A origem é o MenuStrip controle no formulário filho MDI que contém os itens de

menu que você deseja mesclar no menu de destino.
A MdiWindowListItem propriedade identifica o item de menu cuja lista suspensa você

preencherá com os títulos dos filhos MDI do formulário pai do MDI atual. Por exemplo,
você normalmente lista o filho MDI que está aberto no momento no menu Janela.
A IsMdiWindowListEntry propriedade identifica quais itens de menu vêm de um

MenuStrip formulário filho MDI.
Você pode mesclar itens de menu de forma manual ou automática. Os itens de menu
são mesclados da mesma maneira para os dois métodos, mas a mesclagem é ativada de
forma diferente, conforme discutido nas seções "Mesclagem manual" e "Mesclagem
automática" neste tópico. Tanto na mesclagem manual quanto na automática, cada ação
de mesclagem afeta a próxima.
MenuStrip A mesclagem move os itens de menu de um ToolStrip para outro em vez de

cloná-los, como foi o caso com MainMenu.
Valores de MergeAction
Você define a ação de mesclagem em itens de menu na origem MenuStrip usando a
MergeAction propriedade.
A tabela a seguir descreve o significado e o uso típico das ações de mesclagem
disponíveis.
Valor de Descrição Usos comum

MergeAction
Append (Padrão) Adiciona o item de origem Adicionar itens de menu no final do

ao final da coleção do item de menu quando alguma parte do
destino. programa é ativada.
Insert Adiciona o item de origem à coleção Adicionar itens de menu no início ou no

do item de destino, no local meio do menu quando alguma parte do
especificado pela MergeIndex programa é ativada.
propriedade definida no item de
origem. Se o valor for MergeIndex o mesmo para
ambos os itens de menu, eles serão
adicionados na ordem inversa. Defina
MergeIndex adequadamente para
preservar a ordem original.
Replace Localiza uma correspondência de Substituir um item de menu de destino

texto ou usa o MergeIndex valor se por um item de menu de origem de
nenhuma correspondência de texto mesmo nome que faz algo diferente.
for encontrada e, em seguida,
substitui o item de menu de destino
correspondente pelo item de menu
de origem.
MatchOnly Localiza uma correspondência de Criar uma estrutura de menu que insere
texto ou usa o MergeIndex valor se ou adiciona itens de menu em um
nenhuma correspondência de texto submenu ou remove itens de menu de
for encontrada e, em seguida, um submenu. Por exemplo, você pode
adiciona todos os itens suspensos da adicionar um item de menu de um filho
origem ao destino. MDI a um menu Salvar como
principalMenuStrip.
MatchOnly permite que você navegue

pela estrutura do menu sem tomar
nenhuma ação. Ele fornece uma maneira
de avaliar os itens subsequentes.
Remove Localiza uma correspondência de Removendo um item de menu do

texto ou usa o MergeIndex valor se destino MenuStrip.
nenhuma correspondência de texto
for encontrada e, em seguida,
remove o item do destino.
Manual de mesclagem
Somente MenuStrip os controles participam da mesclagem automática. Para combinar
os itens de outros controles, como ToolStrip e StatusStrip controles, você deve mesclar
manualmente, chamando o código e RevertMerge os Merge métodos conforme
necessário.
Mesclagem automática
Você pode usar a mesclagem automática para aplicativos MDI, ativando o formulário de
origem. Para usar um MenuStrip aplicativo MDI, defina a MainMenuStrip propriedade
como o destino MenuStrip para que as ações de mesclagem executadas na origem
MenuStrip sejam refletidas no destino MenuStrip.
Você pode disparar a mesclagem automática ativando a MenuStrip origem do MDI.

Após a ativação, a origem MenuStrip é mesclada no destino MDI. Quando um novo
formulário se torna ativo, a mesclagem é revertida no último formulário e acionada no
novo formulário. Você pode controlar esse comportamento definindo a MergeAction
propriedade conforme necessário em cada ToolStripIteme definindo a AllowMerge
propriedade em cada MenuStrip.
Confira também
ToolStripManager
MenuStrip
Controle MenuStrip
Como: Criar uma lista de janelas MDI com MenuStrip
Como: Configurar a mesclagem de menu automática para aplicativos MDI
Passo a passo: Fornecer itens de menu
padrão para um formulário
Artigo • 02/06/2023
Você pode fornecer um menu padrão para seus formulários com o MenuStrip controle.
Este passo a passo demonstra como usar um MenuStrip controle para criar um menu
padrão. O formulário também responde quando um usuário seleciona um item de
menu. As seguintes tarefas são ilustradas nesta explicação passo a passo:
Criando um menu padrão.
Criando um StatusStrip controle.
Manipulação da seleção de item de menu.
Quando terminar, você terá um formulário com um menu padrão que exibe seleções de
item de menu em um StatusStrip controle.
Para copiar o código deste tópico como uma única lista, consulte Como fornecer itens
de menu padrão para um formulário.
Pré-requisitos
Criar o projeto
1. No Visual Studio, crie um projeto de aplicativo do Windows chamado
StandardMenuForm (File>New>Project>Visual C# ou Visual Basic>Classic
2. No Designer de Formulários do Windows, selecione o formulário.
Criar um menu padrão

O Designer de Windows Forms pode preencher automaticamente um MenuStrip
controle com itens de menu padrão.
1. Na Caixa de Ferramentas, arraste um MenuStrip controle para o formulário.
2. Clique no MenuStrip glifo de ações do designer do controle ( ) e selecione Inserir

Itens Padrão.
O MenuStrip controle é preenchido com os itens de menu padrão.
3. Clique no item de menu Arquivo para ver seus itens de menu padrão e ícones
correspondentes.
Criar um controle StatusStrip

Use o controle para exibir o StatusStrip status de seus aplicativos Windows Forms. No
exemplo atual, os itens de menu selecionados pelo usuário são exibidos em um
StatusStrip controle.
1. Na Caixa de Ferramentas, arraste um StatusStrip controle para o formulário.
O StatusStrip controle encaixa automaticamente na parte inferior do formulário.
2. Clique no StatusStrip botão suspenso do controle e selecione StatusLabel para

adicionar um ToolStripStatusLabel controle ao StatusStrip controle.
Manipular seleção de item

Manipule o DropDownItemClicked evento para responder quando o usuário selecionar
um item de menu.
1. Clique no item de menu Arquivo que você criou na seção Criando um menu
padrão.
2. Na janela Propriedades, clique em Eventos.
3. Clique duas vezes no DropDownItemClicked evento.
O designer de Windows Forms gera um manipulador de eventos para o

DropDownItemClicked evento.
4. Adicione o seguinte código ao manipulador de eventos.
C#
// This method is the DropDownItemClicked event handler.

// It passes the ClickedItem object to a utility method
// called UpdateStatus, which updates the text displayed
// in the StatusStrip control.
private void fileToolStripMenuItem_DropDownItemClicked(
object sender, ToolStripItemClickedEventArgs e)
{
this.UpdateStatus(e.ClickedItem);
}
5. Inserir a definição de método de utilitário UpdateStatus ao formulário.
C#
// This utility method assigns the value of a ToolStripItem

// control's Text property to the Text property of the
// ToolStripStatusLabel.
private void UpdateStatus(ToolStripItem item)
{
if (item != null)
{
string msg = String.Format("{0} selected", item.Text);
this.statusStrip1.Items[0].Text = msg;
}
}
Ponto de verificação – testar seu formulário

1. Pressione F5 para compilar e executar seu formulário.
2. Clique no item de menu Arquivo para abrir o menu.
3. No menu Arquivo, clique em um dos itens para selecioná-lo.
O StatusStrip controle exibe o item selecionado.
Próximas etapas
Neste passo a passo, você criou um formulário com um menu padrão. Você pode usar a
ToolStrip família de controles para muitas outras finalidades:
Crie menus de atalho para seus controles com ContextMenuStrip. Para obter mais
informações, consulte Visão geral do componente ContextMenu.
Crie um formulário MDI (interface de documento múltiplo) com controles de

ToolStrip encaixe. Para obter mais informações, consulte Instruções passo a passo:
criando um formulário MDI com mesclagem de menu e controles ToolStrip.
Dê aos seus ToolStrip controles uma aparência profissional. Para obter mais
informações, consulte Como definir o renderizador ToolStrip para um aplicativo.
Confira também
MenuStrip
ToolStrip
StatusStrip
Controle MenuStrip
Controle MonthCalendar (Windows
Forms)
Artigo • 02/06/2023
O controle MonthCalendar dos Windows Forms apresenta uma interface gráfica intuitiva
para os usuários exibirem e definirem as informações de data. O controle exibe uma
grade que contém os dias numerados do mês, organizados em colunas abaixo dos dias
da semana. Você pode selecionar um outro mês clicando nos botões de seta em um dos
lados da legenda do mês. Ao contrário do controle semelhante DateTimePicker , você
pode selecionar um intervalo de datas com esse controle; no entanto, o DateTimePicker
controle permite que você defina horários e datas.
Nesta seção
Visão geral do controle MonthCalendar
Apresenta os conceitos gerais do controle MonthCalendar , que permite que usuários
exibam e definam as informações de data para um aplicativo.
Como alterar a aparência do controle MonthCalendar dos Windows Forms

Descreve como personalizar a aparência do controle MonthCalendar .
Como exibir mais de um mês no controle MonthCalendar dos Windows Forms

Descreve como configurar o controle MonthCalendar para exibir vários meses
simultaneamente.
Como exibir dados específicos em negrito com o controle MonthCalendar dos Windows
Forms
Explica como configurar determinadas datas em negrito.
Como selecionar um intervalo de datas no controle MonthCalendar dos Windows Forms

Explica como selecionar programaticamente um intervalo de datas do controle
MonthCalendar .
Referência
MonthCalendar
Fornece informações de referência sobre a classe e seus membros.
Descreve um controle semelhante a MonthCalendar, embora o DateTimePicker controle
também permita que você selecione uma hora e não permita que você selecione um
intervalo de datas.
Visão geral do controle MonthCalendar
(Windows Forms)
Artigo • 02/06/2023
O controle MonthCalendar dos Windows Forms apresenta uma interface gráfica intuitiva
para os usuários exibirem e definirem as informações de data. O controle exibe um
calendário: uma grade que contém os dias numerados do mês, organizados em colunas
abaixo dos dias da semana, com o intervalo selecionado de datas realçado. Você pode
selecionar um outro mês clicando nos botões de seta em um dos lados da legenda do
mês. Ao contrário do controle semelhante DateTimePicker , você pode selecionar mais
de uma data com esse controle. Para obter mais informações sobre o DateTimePicker
controle, consulte Controle DateTimePicker.
Configurar o controle MonthCalendar

A MonthCalendar aparência do controle é altamente configurável. Por padrão, a data do
dia atual é exibida dentro de um círculo e também está disponível na parte inferior da
grade. Você pode alterar esse recurso definindo as propriedades e ShowTodayCircle as
ShowToday propriedades como false . Você também pode adicionar números de
semana ao calendário definindo a ShowWeekNumbers propriedade como true . Ao
definir a CalendarDimensions propriedade, você pode ter vários meses exibidos
horizontal e verticalmente. Por padrão, o domingo é mostrado como o primeiro dia da
semana, mas qualquer dia pode ser designado usando a FirstDayOfWeek propriedade.
Você também pode definir determinadas datas a serem exibidas em negrito uma vez,
anualmente ou mensalmente, adicionando DateTime objetos ao BoldedDates,
AnnuallyBoldedDatese MonthlyBoldedDates propriedades. Para obter mais informações,
consulte Como exibir dados específicos em negrito com o controle MonthCalendar dos
Windows Forms.
A propriedade chave do MonthCalendar controle é SelectionRangeo intervalo de datas

selecionado no controle. O SelectionRange valor não pode exceder o número máximo
de dias que podem ser selecionados, definido na MaxSelectionCount propriedade. As
datas mais antigas e mais recentes que o usuário pode selecionar são determinadas
pelas propriedades e MinDate pelas MaxDate propriedades.
Confira também
MonthCalendar
Como alterar a aparência do controle
MonthCalendar dos Windows Forms
Artigo • 02/06/2023
O controle Windows Forms MonthCalendar permite personalizar a aparência do

calendário de várias maneiras. Por exemplo, você pode definir o esquema de cores e
optar por exibir ou ocultar os números de semana e a data atual.
Alterar o esquema de cores do calendário do mês

Definir propriedades como TitleBackColor, TitleForeColor e TrailingForeColor. A
TitleBackColor propriedade também determina a cor da fonte para os dias da
semana. A TrailingForeColor propriedade determina a cor das datas que precedem
e seguem o mês ou meses exibidos.
C#
monthCalendar1.TitleBackColor = System.Drawing.Color.Blue;
monthCalendar1.TrailingForeColor = System.Drawing.Color.Red;
monthCalendar1.TitleForeColor = System.Drawing.Color.Yellow;
７ Observação
Desde o Windows Vista e dependendo do tema, definir algumas propriedades

pode não mudar a aparência do calendário. Por exemplo, se o Windows
estiver definido para usar o tema Aero, definir o
BackColorTitleBackColorTitleForeColor, ou TrailingForeColor propriedades
não terá efeito. Isso ocorre porque uma versão atualizada do calendário é
renderizada com uma aparência derivada no tempo de execução do tema
atual do sistema operacional. Se quiser usar essas propriedades e habilitar a
versão anterior do calendário, desabilite os estilos visuais para o aplicativo.
Desabilitar os estilos visuais pode afetar a aparência e o comportamento de
outros controles no seu aplicativo. Para desabilitar estilos visuais no Visual
Basic, abra o Designer de Projeto e desmarque a caixa de seleção Habilitar
estilos visuais XP . Para desabilitar estilos visuais em C#, abra Program.cs e
comente Application.EnableVisualStyles(); . Para obter mais informações
sobre estilos visuais, consulte Habilitando estilos visuais.
Exibir a data atual na parte inferior do controle
Defina a propriedade ShowToday como true . O exemplo abaixo alterna entre
exibir e omitir a data atual ao clicar duas vezes no formulário.
C#
private void Form1_DoubleClick(object sender, System.EventArgs e)

{
// Toggle between True and False.
monthCalendar1.ShowToday = !monthCalendar1.ShowToday;
}

C#
this.DoubleClick += new System.EventHandler(this.Form1_DoubleClick);
Exibir números de semana

Defina a propriedade ShowWeekNumbers como true . Você pode definir essa
propriedade no código ou na janela Propriedades.
Números de semana são exibidos em uma coluna separada à esquerda do

primeiro dia da semana.
C#
monthCalendar1.ShowWeekNumbers = true;
Confira também
Como selecionar um intervalo de datas no controle MonthCalendar dos Windows
Forms
Como exibir dados específicos em negrito com o controle MonthCalendar dos
Windows Forms
Como exibir mais de um mês no
controle MonthCalendar dos Windows
Forms
Artigo • 02/06/2023
O controle Windows Forms MonthCalendar pode exibir até 12 meses por vez. Por
padrão, o controle exibe apenas um mês, mas você pode especificar quantos meses são
exibidos e como eles são organizados dentro do controle. Quando você altera as
dimensões do calendário, o controle é redimensionado, portanto, certifique-se de que
há espaço suficiente no formulário para as novas dimensões.
Para exibir vários meses

Defina a CalendarDimensions propriedade como o número de meses a serem
exibidos horizontal e verticalmente.
C#
monthCalendar1.CalendarDimensions = new System.Drawing.Size (3,2);
Confira também
Forms
Como exibir dados específicos em
negrito com o controle MonthCalendar
dos Windows Forms
Artigo • 02/06/2023
O controle Windows Forms MonthCalendar pode exibir dias em negrito, como datas
singulares ou em uma base repetida. Você pode fazer isso para chamar atenção para
datas especiais, como feriados e fins de semana.
Três propriedades controlam esse recurso. A BoldedDates propriedade contém datas

simples. A AnnuallyBoldedDates propriedade contém datas que aparecem em negrito a
cada ano. A MonthlyBoldedDates propriedade contém datas que aparecem em negrito
todos os meses. Cada uma dessas propriedades contém uma matriz de DateTime
objetos. Para adicionar ou remover uma data de uma dessas listas, você deve adicionar
ou remover um DateTime objeto.
Para exibir uma data em negrito

1. Crie os DateTime objetos.
C#
DateTime myVacation1 = new DateTime(2001, 6, 10);

DateTime myVacation2 = new DateTime(2001, 6, 17);
2. Torne uma única data em negrito chamando o

AddBoldedDateAddAnnuallyBoldedDatemétodo , ou AddMonthlyBoldedDate o
método do MonthCalendar controle.
C#
monthCalendar1.AddBoldedDate(myVacation1);
monthCalendar1.AddBoldedDate(myVacation2);
–ou–
Torne um conjunto de datas em negrito de uma só vez criando uma matriz de

DateTime objetos e atribuindo-o a uma das propriedades.
C#
DateTime[] VacationDates = {myVacation1, myVacation2};
monthCalendar1.BoldedDates = VacationDates;
Para exibir uma data na fonte normal

1. Faça com que uma única data em negrito apareça na fonte regular chamando o
RemoveBoldedDatemétodo ou RemoveMonthlyBoldedDate o
RemoveAnnuallyBoldedDatemétodo.
C#
monthCalendar1.RemoveBoldedDate(myVacation1);
monthCalendar1.RemoveBoldedDate(myVacation2);
–ou–
Remova todas as datas em negrito de uma das três listas chamando o

RemoveAllBoldedDatesmétodo ou RemoveAllMonthlyBoldedDates o
RemoveAllAnnuallyBoldedDatesmétodo.
C#
monthCalendar1.RemoveAllBoldedDates();
2. Atualize a aparência da fonte chamando o UpdateBoldedDates método.
C#
monthCalendar1.UpdateBoldedDates();
Confira também
Forms
Como selecionar um intervalo de datas
no controle MonthCalendar dos
Windows Forms
Artigo • 02/06/2023
Um recurso importante do controle Windows Forms MonthCalendar é que o usuário

pode selecionar um intervalo de datas. Esse recurso é uma melhoria em relação ao
recurso de seleção de data do controle, que DateTimePicker só permite que o usuário
selecione um único valor de data/hora. Você pode definir um intervalo de datas ou
obter um intervalo de seleção definido pelo usuário usando propriedades do
MonthCalendar controle. O exemplo de código a seguir demonstra como definir um
intervalo de seleção.
Para selecionar um intervalo de datas

1. Crie DateTime objetos que representam as primeiras e últimas datas em um
intervalo.
C#
DateTime projectStart = new DateTime(2001, 2, 13);

DateTime projectEnd = new DateTime(2001, 2, 28);
2. Definir a propriedade SelectionRange.
C#
monthCalendar1.SelectionRange = new SelectionRange(projectStart,

projectEnd);
–ou–
Definir as propriedades SelectionStart e SelectionEnd.
C#
monthCalendar1.SelectionStart = projectStart;
monthCalendar1.SelectionEnd = projectEnd;
Confira também
Como exibir dados específicos em negrito com o controle MonthCalendar dos
Windows Forms
Componente NotifyIcon (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms NotifyIcon exibe ícones na área de notificação de

status da barra de tarefas para processos executados em segundo plano e, de outra
forma, não teria interfaces de usuário. Por exemplo, um programa de proteção contra
vírus que pode ser acessado clicando em um ícone na área de notificação de status da
barra de tarefas.
Nesta seção
Visão geral do componente NotifyIcon
Apresenta os conceitos gerais do componente, que NotifyIcon permite que os usuários
vejam ícones para processos em execução em segundo plano que não têm uma
interface do usuário.
Como: Adicionar ícones do aplicativo à TaskBar com o componente NotifyIcon do

Windows Forms
Fornece etapas para definir o ícone exibido pelo NotifyIcon componente.
Como: Associar um menu de atalho a um componente NotifyIcon do Windows Forms

Fornece etapas para adicionar um menu de atalho a um NotifyIcon componente.
Referência
NotifyIcon
(Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms NotifyIcon normalmente é usado para exibir ícones para
processos executados em segundo plano e não mostram uma interface do usuário na
maior parte do tempo. Por exemplo, um programa de proteção contra vírus que pode
ser acessado clicando em um ícone na área de notificação de status da barra de tarefas.
Propriedades chave do NotifyIcons

Cada NotifyIcon componente exibe um único ícone na área de status. Se você tiver três
processos em segundo plano e quiser exibir um ícone para cada um, deverá adicionar
três NotifyIcon componentes ao formulário. As principais propriedades do NotifyIcon
componente são Icon e Visible. A Icon propriedade define o ícone que aparece na área
de status. Para que o ícone apareça, a Visible propriedade deve ser definida como true .
Opções do NotifyIcons
Você pode associar dicas de balão, menus de atalho e Dicas de Ferramenta a um
NotifyIcon para ajudar o usuário.
Você pode exibir dicas de balão para um NotifyIcon chamando o ShowBalloonTip

método especificando o período de tempo que deseja exibir a dica de balão. Você
também pode especificar o texto, o ícone e o título da ponta do balão com o
BalloonTipTexte BalloonTipIconBalloonTipTitle, respectivamente. NotifyIcon os
componentes também podem ter dicas de ferramenta associadas e menus de atalho.
Para mais informação, consulte Visão geral do componente ToolTip e Visão geral do
componente ContextMenu.
Confira também
NotifyIcon
Como: Adicionar ícones do aplicativo à
TaskBar com o componente NotifyIcon
do Windows Forms
Artigo • 21/06/2023
O componente Windows Forms NotifyIcon exibe um único ícone na área de notificação

status da barra de tarefas. Para exibir vários ícones na área status, você deve ter vários
NotifyIcon componentes em seu formulário. Para definir o ícone exibido para um
controle, use a Icon propriedade . Você também pode escrever código no DoubleClick
manipulador de eventos para que algo aconteça quando o usuário clicar duas vezes no
ícone. Por exemplo, você pode fazer com que uma caixa de diálogo apareça para o
usuário configurar o processo em segundo plano representado pelo ícone.
７ Observação
O NotifyIcon componente é usado apenas para fins de notificação, para alertar os

usuários de que ocorreu uma ação ou evento ou que houve uma alteração no
status de algum tipo. Você deve usar os menus, barras de ferramentas e outros
elementos de interface do usuário para interação padrão com aplicativos.
Definir o ícone
1. Atribua um valor à Icon propriedade . O valor deve ser do tipo
System.Drawing.Icon e pode ser carregados de um arquivo .ico. Você pode
especificar o arquivo de ícone no código ou clicando no botão de reticências ( )
ao lado da Icon propriedade na janela Propriedades e selecionando o arquivo na
caixa de diálogo Abrir exibida.
2. Defina a propriedade Visible como true .
3. Defina a Text propriedade como uma cadeia de caracteres tooltip apropriada.
No exemplo de código a seguir, o caminho definido para o local do ícone é a

pasta Meus Documentos. Esse local é usado porque você pode supor que a
maioria dos computadores que executam o sistema operacional Windows incluem
essa pasta. Escolher esse local também permite que os usuários com níveis
mínimos de acesso ao sistema executem o aplicativo com mais segurança. O
exemplo a seguir requer um formulário com um NotifyIcon controle já adicionado.
Ele também requer um arquivo de ícone denominado Icon.ico .
C#
// You should replace the bold icon in the sample below

// with an icon of your own choosing.
notifyIcon1.Icon =
new System.Drawing.Icon (System.Environment.GetFolderPath
+ @"\Icon.ico");
notifyIcon1.Visible = true;
notifyIcon1.Text = "Antivirus program";
Confira também
NotifyIcon
Icon
Como: Associar um menu de atalho a um componente NotifyIcon do Windows
Forms
Como: Associar um menu de atalho a
um componente NotifyIcon do
Windows Forms
Artigo • 21/06/2023
７ Observação
Embora MenuStrip substitua ContextMenuStrip e adicione funcionalidade aos

MainMenu controles e ContextMenu das versões anteriores e
MainMenuContextMenu sejam mantidos para compatibilidade com versões
O NotifyIcon componente exibe um ícone na área de notificação status da barra de

tarefas. Normalmente, aplicativos permitem clicar com o botão direito do mouse nesse
ícone para enviar comandos para o aplicativo que ele representa. Ao associar um
ContextMenu componente ao NotifyIcon componente, você pode adicionar essa
funcionalidade aos seus aplicativos.
７ Observação
Se você quiser que seu aplicativo seja minimizado na inicialização ao exibir uma
instância do NotifyIcon componente na barra de tarefas, defina a propriedade
Minimized do WindowState formulário main como e verifique se a NotifyIcon
propriedade do Visible componente está definida como true .
Associar um menu de atalho ao componente NotifyIcon

no tempo de design
1. Adicione um NotifyIcon componente ao formulário e defina as propriedades
importantes, como as Icon propriedades e Visible .
Para obter mais informações, consulte Como adicionar ícones de aplicativo ao

TaskBar com o componente NotifyIcon do Windows Forms.
2. Adicione um ContextMenu componente ao Formulário do Windows.

Adicione itens de menu ao menu de atalho que representam os comandos que
você deseja disponibilizar no tempo de execução. Esse também é um bom
momento para adicionar melhorias de menu a esses itens de menu, como teclas
de acesso.
3. Defina a ContextMenu propriedade do NotifyIcon componente para o menu de

atalho que você adicionou.
Com essa propriedade definida, o menu de atalho será exibido ao clicar no ícone
da barra de tarefas.
Associar um menu de atalho ao componente NotifyIcon

com programação
1. Crie uma instância da NotifyIcon classe e uma ContextMenu classe, com quaisquer
configurações de propriedade necessárias para o aplicativo (Icon e Visible
propriedades para o NotifyIcon componente, itens de menu para o ContextMenu
componente).
2. Defina a ContextMenu propriedade do NotifyIcon componente para o menu de

atalho que você adicionou.
Com essa propriedade definida, o menu de atalho será exibido ao clicar no ícone
da barra de tarefas.
７ Observação
O exemplo de código a seguir cria uma estrutura de menu básica. Você

precisará personalizar as opções do menu para que se ajustem ao aplicativo
que você está desenvolvendo. Além disso, você desejará escrever código para
lidar com os Click eventos desses itens de menu.
VB
Public ContextMenu1 As New ContextMenu

Public NotifyIcon1 As New NotifyIcon
Public Sub CreateIconMenuStructure()

' Add menu items to shortcut menu.
ContextMenu1.MenuItems.Add("&Open Application")
ContextMenu1.MenuItems.Add("S&uspend Application")
ContextMenu1.MenuItems.Add("E&xit")
' Set properties of NotifyIcon component.

NotifyIcon1.Icon = New System.Drawing.Icon _
& "\Icon.ico")
NotifyIcon1.Text = "Right-click me!"
NotifyIcon1.Visible = True
NotifyIcon1.ContextMenu = ContextMenu1
End Sub
C#
public NotifyIcon notifyIcon1 = new NotifyIcon();

public ContextMenu contextMenu1 = new ContextMenu();
public void createIconMenuStructure()

{
// Add menu items to shortcut menu.
contextMenu1.MenuItems.Add("&Open Application");
contextMenu1.MenuItems.Add("S&uspend Application");
contextMenu1.MenuItems.Add("E&xit");
// Set properties of NotifyIcon component.

notifyIcon1.Icon = new System.Drawing.Icon
+ @"\Icon.ico");
notifyIcon1.Text = "Right-click me!";
notifyIcon1.ContextMenu = contextMenu1;
}
７ Observação
Você deve inicializar notifyIcon1 e contextMenu1, , o que pode ser feito incluindo a
instrução a seguir no construtor do formulário:
C++
notifyIcon1 = gcnew System::Windows::Forms::NotifyIcon();

contextMenu1 = gcnew System::Windows::Forms::ContextMenu();
Confira também
NotifyIcon
Icon
Como: Adicionar ícones do aplicativo à TaskBar com o componente NotifyIcon do
Windows Forms
Controle NumericUpDown (Windows
Forms)
Artigo • 02/06/2023
O controle NumericUpDown dos Windows Forms parece com a combinação de uma caixa
de texto e um par de setas em que o usuário pode clicar para ajustar um valor. O
controle exibe e define um único valor numérico de uma lista de opções. O usuário
pode aumentar e diminuir o número clicando nos botões para cima e para baixo,
pressionando as teclas de seta para CIMA e para BAIXO ou digitando um número. Clicar
na tecla de seta para CIMA move o valor até seu máximo; clicar na tecla de seta para
BAIXO move a posição para o mínimo. Um exemplo de onde esse tipo de controle pode
ser útil é para controle de volume em um reprodutor de música. Controles numéricos
para cima e para baixo são usados em alguns aplicativos do painel de controle do
Windows.
Nesta seção
Visão geral do controle NumericUpDown
Apresenta os conceitos gerais do controle NumericUpDown , que permite que os usuários
procurem e selecionem de uma lista de valores numéricos.
Como: Definir e retornar valores numéricos com o controle NumericUpDown do

Windows Forms
Descreve como testar o valor do controle.
Como: Definir o formato para o controle NumericUpDown do Windows Forms

Descreve como configurar como os valores são exibidos no controle.
Referência
NumericUpDown
Fornece informações de referência sobre a NumericUpDown classe e seus membros.
Introduz um controle semelhante a NumericUpDown, exceto que o DomainUpDown
controle exibe cadeia de caracteres em vez de valores numéricos.
NumericUpDown (Windows Forms)
Artigo • 02/06/2023
O NumericUpDown controle parece uma combinação de uma caixa de texto e um par

de setas que o usuário pode clicar para ajustar um valor. O controle exibe e define um
único valor numérico de uma lista de opções fixas. O usuário pode aumentar e diminuir
o número clicando nas setas para cima e para baixo, pressionando as teclas de direção
para cima ou para baixo ou digitando um número na parte de caixa de texto do
controle. Clicar na seta para cima move o número em direção ao máximo; clicar na seta
para baixo move o número em direção ao mínimo.
Devido à sua funcionalidade versátil, esse controle é uma opção óbvia, por exemplo, se
você quiser criar um controle de volume para aplicativo de player de música. O
NumericUpDown controle é usado em muitos aplicativos do Windows Painel de
Controle.
Propriedades e métodos de tecla

Os números exibidos na caixa de texto do controle podem estar em uma variedade de
formatos, incluindo hexadecimais. Para obter mais informações, consulte Como definir o
formato para o controle NumericUpDown dos Windows Forms. As principais
propriedades do controle são Value, Maximum (valor padrão 100), Minimum (valor
padrão 0) e Increment (valor padrão 1). A Value propriedade define o número atual
selecionado no controle. A Increment propriedade define o valor pelo qual o número é
ajustado quando o usuário clica em uma seta para cima ou para baixo. Quando o foco é
movido para fora do controle, qualquer entrada digitada será validada em relação aos
valores numéricos mínimo e máximo. Você pode aumentar a velocidade que o controle
move através de números, quando o usuário pressiona continuamente a seta para cima
ou para baixo, com a Accelerations propriedade. Os principais métodos do controle são
UpButton e DownButton.
Confira também
NumericUpDown
Como: Definir o formato para o controle NumericUpDown do Windows Forms
Controle TextBox
Como: Definir e retornar valores
numéricos com o controle
NumericUpDown do Windows Forms
Artigo • 02/06/2023
O valor numérico do controle Windows Forms NumericUpDown é determinado por sua

Value propriedade. Você pode escrever testes condicionais para o valor do controle da
mesma forma que com qualquer outra propriedade. Depois que a Value propriedade
estiver definida, você poderá ajustá-la diretamente escrevendo o código para executar
operações nela ou pode chamar o método eDownButton.UpButton
Para definir o valor numérico

1. Atribua um valor à Value propriedade no código ou no janela Propriedades.
C#
numericUpDown1.Value = 55;
-ou-
2. Chame o método ou DownButton o UpButton método para aumentar ou diminuir

o valor pelo valor especificado na Increment propriedade.
C#
numericUpDown1.UpButton();
Para retornar o valor numérico

Acesse a Value propriedade no código.
C#
if(numericUpDown1.Value >= 65)

{
MessageBox.Show("Age is: " + numericUpDown1.Value.ToString());
}
else
{
MessageBox.Show("The customer is ineligible for a senior citizen
discount.");
}
Confira também
NumericUpDown
NumericUpDown.Value
NumericUpDown.Increment
NumericUpDown.UpButton
NumericUpDown.DownButton
Como: Definir o formato para o controle
NumericUpDown do Windows Forms
Artigo • 02/06/2023
Você pode configurar como os valores são exibidos no controle Windows

FormsNumericUpDown. A DecimalPlaces propriedade determina quantos números
aparecem após o ponto decimal; o padrão é 0. A ThousandsSeparator propriedade
determina se um separador será inserido entre cada três dígitos decimais; o padrão é
false . O controle pode exibir valores em hexadecimal em vez de formato decimal, se a
Hexadecimal propriedade estiver definida como true ; o padrão é false .
Para formatar o valor numérico

Exiba um valor decimal definindo a DecimalPlaces propriedade como um inteiro e
definindo a ThousandsSeparator propriedade como true ou false .
C#
numericUpDown1.DecimalPlaces = 2;
numericUpDown1.ThousandsSeparator = true;
-ou-
Exibir um valor hexadecimal definindo a Hexadecimal propriedade como true .
C#
numericUpDown1.Hexadecimal = true;
７ Observação
Mesmo que o valor seja exibido no formulário como hexadecimal, todos os

testes que você executar na propriedade testarão seu Value valor decimal.
Confira também
NumericUpDown
Componente OpenFileDialog (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms OpenFileDialog é uma caixa de diálogo pré-

configurada. É a mesma caixa de diálogo Abrir arquivo exposta pelo sistema
operacional Windows. Herda da CommonDialog classe.
Nesta seção
Visão geral do componente OpenFileDialog
Apresenta os conceitos gerais do componente, o OpenFileDialog que permite exibir
uma caixa de diálogo pré-configurada que os usuários podem usar para abrir arquivos.
Como: Como abrir arquivos usando o componente OpenFileDialog

Explica como abrir um arquivo em tempo de execução por meio de uma instância do
OpenFileDialog componente.
Referência
OpenFileDialog
Fornece informações de referência sobre a OpenFileDialog classe e seus membros.

OpenFileDialog (Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms OpenFileDialog é uma caixa de diálogo pré-

configurada. É a mesma caixa de diálogo Abrir arquivo exposta pelo sistema
operacional Windows. Herda da CommonDialog classe.
Usar este componente

Use esse componente em seu aplicativo baseado no Windows como uma solução
simples para seleção de arquivos em vez de configurar sua própria caixa de diálogo.
Com base nas caixas de diálogo padrão do Windows, crie aplicativos cuja
funcionalidade básica é imediatamente familiar aos usuários. No entanto, lembre-se de
que, ao usar o OpenFileDialog componente, você deve escrever sua própria lógica de
abertura de arquivo.
Use o ShowDialog método para exibir a caixa de diálogo em tempo de execução. Você
pode permitir que os usuários selecionem vários arquivos para serem abertos com a
Multiselect propriedade. Além disso, você pode usar a ShowReadOnly propriedade para
determinar se uma caixa de seleção somente leitura aparece na caixa de diálogo. A
ReadOnlyChecked propriedade indica se a caixa de seleção somente leitura está
selecionada. Por fim, a Filter propriedade define a cadeia de caracteres de filtro de nome
de arquivo atual, que determina as opções que aparecem na caixa "Arquivos do tipo" na
caixa de diálogo.
Quando ele é adicionado a um formulário, o OpenFileDialog componente aparece na

bandeja na parte inferior do Designer de Windows Forms no Visual Studio.
Confira também
OpenFileDialog
Como abrir arquivos com o
OpenFileDialog
Artigo • 21/06/2023
O System.Windows.Forms.OpenFileDialog componente abre a caixa de diálogo do

Windows para navegar e selecionar arquivos. Para abrir e ler os arquivos selecionados,
você pode usar o OpenFileDialog.OpenFile método ou criar uma instância da
System.IO.StreamReader classe . Os exemplos a seguir mostram as duas abordagens.
Em .NET Framework, para obter ou definir a FileName propriedade requer um nível de

privilégio concedido pela System.Security.Permissions.FileIOPermission classe . Os
exemplos executam uma FileIOPermission permissão marcar e podem gerar uma
exceção devido a privilégios insuficientes se executados em um contexto de confiança
parcial. Para obter mais informações, consulte Noções básicas de segurança de acesso
ao código.
Você pode criar e executar esses exemplos como .NET Framework aplicativos na linha de
comando C# ou Visual Basic. Para obter mais informações, consulte Compilação de linha
de comando com csc.exe ou Compilar na linha de comando.
A partir do .NET Core 3.0, você também pode compilar e executar os exemplos como
aplicativos .NET Core do Windows de uma pasta que tem um arquivo de projeto
name.csproj da pasta> do .NET Core Windows Forms<.
Exemplo: ler um arquivo como um fluxo com

StreamReader
O exemplo a seguir usa o manipulador de eventos do controle Windows Forms Button
para abrir o OpenFileDialog com o ShowDialogClick método . Depois que o usuário
escolhe um arquivo e seleciona OK, uma instância da StreamReader classe lê o arquivo e
exibe seu conteúdo na caixa de texto do formulário. Para obter mais informações sobre
a leitura de fluxos de arquivos, consulte FileStream.BeginRead e FileStream.Read.
C#
using System;
using System.IO;
using System.Security;
public class OpenFileDialogForm : Form
{
[STAThread]
{
Application.Run(new OpenFileDialogForm());
}
private Button selectButton;

private OpenFileDialog openFileDialog1;
public OpenFileDialogForm()
{
openFileDialog1 = new OpenFileDialog();
selectButton = new Button
{
Size = new Size(100, 20),
Location = new Point(15, 15),
Text = "Select file"
};
selectButton.Click += new EventHandler(SelectButton_Click);
textBox1 = new TextBox
{
Multiline = true,
ScrollBars = ScrollBars.Vertical
};
ClientSize = new Size(330, 360);
Controls.Add(selectButton);
Controls.Add(textBox1);
}
private void SetText(string text)
{
textBox1.Text = text;
}
private void SelectButton_Click(object sender, EventArgs e)
{
if (openFileDialog1.ShowDialog() == DialogResult.OK)
{
try
{
var sr = new StreamReader(openFileDialog1.FileName);
SetText(sr.ReadToEnd());
}
catch (SecurityException ex)
{
MessageBox.Show($"Security error.\n\nError message:
{ex.Message}\n\n" +
$"Details:\n\n{ex.StackTrace}");
}
}
}
}
Exemplo: abrir um arquivo de uma seleção

filtrada com OpenFile
O exemplo a seguir usa o Button manipulador de eventos do Click controle para abrir o
OpenFileDialog com um filtro que mostra apenas arquivos de texto. Depois que o
usuário escolhe um arquivo de texto e seleciona OK, o OpenFile método é usado para
abrir o arquivo no Bloco de Notas.
C#
using System;
using System.IO;
using System.Security;
public class OpenFileDialogForm : Form

{
[STAThread]
{
Application.Run(new OpenFileDialogForm());
}
private Button selectButton;

private OpenFileDialog openFileDialog1;
public OpenFileDialogForm()
{
openFileDialog1 = new OpenFileDialog()
{
FileName = "Select a text file",
Filter = "Text files (*.txt)|*.txt",
Title = "Open text file"
};
selectButton = new Button()

{
Text = "Select file"
};
selectButton.Click += new EventHandler(selectButton_Click);
Controls.Add(selectButton);
}
private void selectButton_Click(object sender, EventArgs e)

{
if (openFileDialog1.ShowDialog() == DialogResult.OK)
{
try
{
var filePath = openFileDialog1.FileName;
using (Stream str = openFileDialog1.OpenFile())
{
Process.Start("notepad.exe", filePath);
}
}
catch (SecurityException ex)
{
MessageBox.Show($"Security error.\n\nError message:
{ex.Message}\n\n" +
$"Details:\n\n{ex.StackTrace}");
}
}
}
}
Confira também
OpenFileDialog
(Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms PageSetupDialog é uma caixa de diálogo pré-

configurada usada para definir detalhes da página para impressão em aplicativos
baseados no Windows. Use-o em seu aplicativo baseado no Windows como uma
solução simples para os usuários definirem preferências de página em vez de configurar
sua própria caixa de diálogo. Você pode permitir que os usuários definam ajustes de
borda e margem, cabeçalhos e rodapés e orientação retrato versus paisagem. Com base
nas caixas de diálogo padrão do Windows, crie aplicativos cuja funcionalidade básica é
imediatamente familiar aos usuários.
Nesta seção
Visão geral do componente PageSetupDialog
Apresenta os conceitos gerais do PageSetupDialog componente, que você pode usar
para exibir uma caixa de diálogo pré-configurada que os usuários podem usar para
manipular as configurações de página.
Como: Determinar propriedades de página usando o componente PageSetupDialog

Explica como definir propriedades de página usando uma instância do PageSetupDialog
componente em tempo de execução.
Referência
PageSetupDialog

PageSetupDialog (Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms PageSetupDialog é uma caixa de diálogo pré-

configurada usada para definir detalhes da página para impressão em aplicativos
baseados no Windows. Use-o em seu aplicativo baseado no Windows como uma
solução simples para os usuários definirem preferências de página em vez de configurar
sua própria caixa de diálogo. Você pode permitir que os usuários definam ajustes de
borda e margem, cabeçalhos e rodapés e orientação retrato ou paisagem. Com base nas
caixas de diálogo padrão do Windows, crie aplicativos cuja funcionalidade básica é
imediatamente familiar aos usuários.

Use o ShowDialog método para exibir a caixa de diálogo em tempo de execução. Esse
componente tem propriedades que podem ser definidas relacionadas a uma única
página (PrintDocument classe) ou a qualquer documento (PageSettings classe). Além
disso, o PageSetupDialog componente pode ser usado para determinar as
configurações específicas da impressora, que são armazenadas na PrinterSettings classe.
Quando ele é adicionado a um formulário, o PageSetupDialog componente aparece na

Confira também
PageSetupDialog
Como: Determinar propriedades de
página usando o componente
PageSetupDialog
Artigo • 21/06/2023
O componente PageSetupDialog apresenta o layout, tamanho do papel e outras opções

de layout da página ao usuário para um documento.
Você precisa especificar uma instância da PrintDocument classe , este é o documento a

ser impresso. Além disso, os usuários devem ter uma impressora instalada em seu
computador, localmente ou por meio de uma rede, pois é em parte como o
PageSetupDialog componente determina as opções de formatação de página
apresentadas ao usuário.
Um aspecto importante do trabalho com o PageSetupDialog componente é como ele

interage com a PageSettings classe . A PageSettings classe é usada para especificar
configurações que modificam a maneira como uma página será impressa, como
orientação de papel, o tamanho da página e as margens. Cada uma dessas
configurações é representada como uma propriedade da PageSettings classe . A
PageSetupDialog classe modifica esses valores de propriedade para uma determinada
instância da PageSettings classe associada ao documento (e é representada como uma
DefaultPageSettings propriedade).
Para determinar propriedades de página usando o

componente PageSetupDialog
1. Use o ShowDialog método para exibir a caixa de diálogo, especificando o
PrintDocument a ser usado.
No exemplo a seguir, o Button manipulador de eventos do Click controle abre uma

instância do PageSetupDialog componente. Um documento existente é
especificado na Document propriedade e sua PageSettings.Color propriedade é
definida false como .
O exemplo pressupõe que seu formulário tenha um Button controle, um

PrintDocument componente chamado myDocument e um PageSetupDialog
componente .
C#
{
// The print document 'myDocument' used below
// is merely for an example.
// You will have to specify your own print document.
pageSetupDialog1.Document = myDocument;
// Sets the print document's color setting to false,
// so that the page will not be printed in color.
pageSetupDialog1.Document.DefaultPageSettings.Color = false;
pageSetupDialog1.ShowDialog();
}

C#
Confira também
PageSetupDialog
Como: criar trabalhos de impressão padrão do Windows Forms
Controle de painel (Windows Forms)
Artigo • 02/06/2023
Windows forms Panel são usados para fornecer um grupo identificável para outros
controles. Normalmente, você usa painéis para subdividir um formulário por função. O
Panel controle é semelhante ao controle GroupBox ; no entanto, somente Panel o
controle pode ter barras de rolagem e GroupBox apenas o controle exibe uma legenda.
Nesta seção
Visão geral do controle de painel
Como: Agrupar controles com o controle de painel do Windows Forms usando o

Designer
Descreve como agrupar controles com um painel usando o designer.
Como: Definir a tela de fundo de um painel do Windows Forms usando o Designer

Descreve como exibir uma cor da tela de fundo e uma imagem de tela de fundo em um
painel usando o designer.
Como: Definir a tela de fundo de um painel

Descreve como exibir uma cor da tela de fundo e uma imagem de tela de fundo em um
painel.
Referência
Panel
Como: Adicionar a ou remover de uma coleção de controles em tempo de execução

Descreve como adicionar controles a e remover controles de qualquer controle de
contêiner em seus formulários.
(Windows Forms)
Artigo • 02/06/2023
Panel Windows Forms controles são usados para fornecer um agrupamento identificável
para outros controles. Normalmente, você usa painéis para subdividir um formulário por
função. Por exemplo, você pode ter um formulário de pedido que especifica as opções
de mala direta, como qual carrier noturna usar. Agrupar todas as opções em um painel
fornece ao usuário uma indicação visual lógica. Em tempo de design, todos os controles
podem ser movidos facilmente – quando você move o Panel controle, todos os
controles contidos também se movem. Os controles agrupados em um painel podem
ser acessados por meio de sua Controls propriedade. Essa propriedade retorna uma
coleção de Control instâncias, portanto, você normalmente precisará converter um
controle recuperado dessa forma para seu tipo específico.
Painel Versus GroupBox

O Panel controle é semelhante ao GroupBox controle; no entanto, somente o Panel
controle pode ter barras de rolagem e apenas o GroupBox controle exibe uma legenda.
Para exibir barras de rolagem, defina a AutoScroll propriedade como true . Você
também pode personalizar a aparência do painel definindo o , BackgroundImagee
BorderStyle as BackColorpropriedades. Para obter mais informações sobre as
propriedades e BackgroundImage as BackColor propriedades, consulte Como definir o
plano de fundo de um painel. A BorderStyle propriedade determina se o painel está
descrito sem borda visível (None), uma linha simples (FixedSingle) ou uma linha
sombreada (Fixed3D).
Confira também
Panel
Controle GroupBox
Designer
Como: Definir a tela de fundo de um painel do Windows Forms usando o Designer
Como: Agrupar controles com o
controle de painel do Windows Forms
usando o Designer
Artigo • 02/06/2023
Panel Windows Forms controles são usados para agrupar outros controles. Há três
razões para agrupar controles. Uma delas é o agrupamento visual de elementos de
formulários relacionados para uma interface do usuário clara; a outra é o agrupamento
programático dos botões de opção, por exemplo; a última é para mover os controles
como uma unidade em tempo de design.
Para criar um grupo de controles

1. Arraste um Panel controle da guia Windows Forms da Caixa de Ferramentas para
um formulário.
2. Adicione outros controles ao painel desenhando cada um deles dentro do painel.
Se você tiver controles existentes que deseja colocar em um painel, poderá

selecionar todos os controles, cortá-los na Área de Transferência, selecionar o
Panel controle e colá-los no painel. Você também pode arrastá-los para o painel.
3. (Opcional) Se você quiser adicionar uma borda a um painel, defina sua BorderStyle
propriedade. Há três opções: Fixed3D, e FixedSingleNone.
Confira também
Controle do painel
Como: Definir a tela de fundo de um painel
Como definir a tela de fundo de um
painel Windows Forms
Artigo • 02/06/2023
um controle de Windows Forms Panel pode exibir uma cor de plano de fundo e uma
imagem de tela de fundo. A BackColor propriedade define a cor do plano de fundo para
os controles contidos, como rótulos e botões de opção. Se a BackgroundImage
propriedade não for definida, a BackColor seleção preencherá o painel inteiro. Se a
BackgroundImage propriedade for definida, a imagem será exibida atrás dos controles
contidos.
Para definir o plano de fundo programaticamente

1. Defina a propriedade do BackColor painel como um valor do tipo
System.Drawing.Color .
C#
panel1.BackColor = Color.AliceBlue;
2. Defina a propriedade do BackgroundImage painel usando o FromFile método da

System.Drawing.Image classe.
C#
// You should replace the bolded image

// in the sample below with an image of your own choosing.
panel1.BackgroundImage = Image.FromFile
+ @"\Image.gif");
Confira também
BackColor
BackgroundImage
Controle do painel
Como definir a tela de fundo de um
painel Windows Forms usando o
Designer
Artigo • 02/06/2023
Um controle Windows Forms Panel pode exibir uma cor de tela de fundo e uma imagem
de plano de fundo. A BackColor propriedade define a cor da tela de fundo para
controles contidos no painel, como rótulos e botões de opção. Se a BackgroundImage
propriedade não estiver definida, a BackColor seleção preencherá todo o painel. Se a
BackgroundImage propriedade estiver definida, a imagem será exibida atrás dos
controles contidos no painel.

formulário que contém um Panel controle. Para obter informações sobre como
configurar esse projeto no Visual Studio, consulte Como criar um projeto de aplicativo
Windows Forms e como adicionar controles a Windows Forms.
Definir a tela de fundo no Designer Windows

Forms
1. Abra o projeto no Visual Studio e selecione o Panel controle.
2. Na janela Propriedades , clique no botão de seta ao lado da BackColor

propriedade para exibir uma janela com três guias.
3. Selecione a guia Personalizado para exibir uma paleta de cores.
4. Selecione a guia Web ou Sistema para exibir uma lista de nomes predefinidos para
cores e, em seguida, selecione uma cor.
5. Na janela Propriedades , clique no botão de seta ao lado da BackgroundImage

propriedade.
6. Na caixa de diálogo Abrir, selecione o arquivo que deseja exibir.
Confira também
BackColor
BackgroundImage
Controle do painel
Designer
Controle PictureBox (Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms PictureBox é usado para exibir gráficos no formato bitmap,
GIF, JPEG, metafile ou ícone.
Nesta seção
Visão geral do controle PictureBox
Como: Modificar o tamanho ou o posicionamento de uma imagem em tempo de

execução
Explica o que a SizeMode propriedade faz e como defini-la.
Como: Definir imagens em tempo de execução

Descreve como exibir e limpar uma imagem em tempo de execução.
Como: Carregar uma imagem usando o designer

Descreve como carregar e exibir uma imagem em um formulário em tempo de design.
Referência
PictureBox
(Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms PictureBox é usado para exibir gráficos no formato bitmap,
GIF, JPEG, metafile ou ícone.

A imagem exibida é determinada pela Image propriedade, que pode ser definida em
tempo de execução ou em tempo de design. Como alternativa, você pode especificar a
imagem definindo a ImageLocation propriedade e, em seguida, carregar a imagem de
forma síncrona usando o Load método ou de forma assíncrona usando o LoadAsync
método. A SizeMode propriedade controla como a imagem e o controle se ajustam
entre si. Para obter mais informações, consulte Como modificar o tamanho ou o
posicionamento de uma imagem em tempo de execução.
Confira também
PictureBox
execução
Controle PictureBox
Como carregar uma imagem usando o
designer (Windows Forms)
Artigo • 02/06/2023
Com o Windows FormsPictureBox, você pode carregar e exibir uma imagem em um

formulário em tempo de design Image definindo a propriedade como uma imagem
válida. A tabela a seguir mostra os tipos de arquivo disponíveis.
Tipo Extensão de nome de arquivo
Bitmap .bmp
Ícone .ico
GIF .gif
Metarquivo .wmf
JPEG .jpg
Para exibir uma imagem em tempo de design

1. Desenhar um PictureBox controle em um formulário.
2. Na janela Propriedades , selecione a propriedade Image e, em seguida, selecione o

botão de reellipse para exibir a caixa de diálogo Abrir.
3. Se você estiver procurando um tipo de arquivo específico (por exemplo, .gif

arquivos), selecione-o na caixa Arquivos do tipo .
4. Selecione o arquivo que você deseja exibir.
Para limpar a imagem em tempo de design

1. Na janela Propriedades , selecione a Image propriedade . Clique com o botão
direito do mouse na imagem em miniatura pequena que aparece à esquerda do
nome do objeto de imagem e escolha Redefinir.
Confira também
PictureBox
execução
Controle PictureBox
Como modificar o tamanho ou a
colocação de uma imagem em tempo
de execução (Windows Forms)
Artigo • 02/06/2023
Se você usar o controle Windows Forms PictureBox em um formulário, poderá definir a

SizeMode propriedade nele como:
Alinhe o canto superior esquerdo da imagem com o canto superior esquerdo do

controle
Centralize a imagem no controle
Ajuste o tamanho do controle para se adaptar à imagem exibida
Alongue qualquer imagem exibida para se ajustar ao controle
Ampliar uma imagem (especialmente em formato bitmap) pode causar perda na

qualidade. Metarquivos, que são listas de instruções gráficas para desenho de imagens
em tempo de execução, são mais adequados para ampliar do que os bitmaps.
Para definir a propriedade SizeMode em tempo de

execução
1. Definido SizeMode como Normal (o padrão), AutoSizeou
CenterImageStretchImage. Normal significa que a imagem é colocada no canto
superior esquerdo do controle; se a imagem for maior que o controle, suas bordas
inferior e direita serão cortadas. CenterImage significa que a imagem está
centralizada dentro do controle; se a imagem for maior que o controle, as bordas
externas da imagem serão cortadas. AutoSize significa que o tamanho do controle
é ajustado para o tamanho da imagem. StretchImage é o inverso e significa que o
tamanho da imagem é ajustado para o tamanho do controle.
No exemplo abaixo, o caminho definido para o local da imagem é a pasta Meus

Documentos. Isso acontece porque presumimos que a maioria dos computadores
rodando o sistema operacional Windows vai incluir este diretório. Isso também
permite que usuários com níveis mínimos de acesso ao sistema executem com
segurança o aplicativo. O exemplo a seguir pressupõe um formulário com um
PictureBox controle já adicionado.
C#
private void StretchPic(){

// Stretch the picture to fit the control.
PictureBox1.SizeMode = PictureBoxSizeMode.StretchImage;
// Load the picture into the control.
// You should replace the bold image
// in the sample below with an icon of your own choosing.
PictureBox1.Image = Image.FromFile _
+ @"\Image.gif")
}
Confira também
PictureBox
Controle PictureBox
Como definir imagens em tempo de
execução (Windows Forms)
Artigo • 02/06/2023
Você pode definir programaticamente a imagem exibida por um controle Windows

FormsPictureBox.
Para definir uma imagem programaticamente

Defina a Image propriedade usando o FromFile método da Image classe.
No exemplo abaixo, o caminho definido para o local da imagem é a pasta Meus

Documentos. Isso acontece porque presumimos que a maioria dos computadores
rodando o sistema operacional Windows vai incluir este diretório. Isso também
permite que usuários com níveis mínimos de acesso ao sistema executem com
segurança o aplicativo. O exemplo a seguir pressupõe um formulário com um
PictureBox controle já adicionado.
C#
private void LoadNewPict(){

pictureBox1.Image = Image.FromFile
+ @"\Image.gif");
}
Para limpar um gráfico

Primeiro, libere a memória que está sendo usada pela imagem e desmarque o
gráfico. A coleta de lixo liberará a memória posteriormente se o gerenciamento de
memória se tornar um problema.
C#
if (pictureBox1.Image != null)
{
pictureBox1.Image.Dispose();
pictureBox1.Image = null;
}
７ Observação
Para obter mais informações sobre por que você deve usar o Dispose método
dessa forma, consulte Limpar Recursos Não Gerenciados.
Esse código limpará a imagem mesmo que um gráfico tenha sido carregado no
controle no momento do design.
Confira também
PictureBox
Image.FromFile
execução
Controle PictureBox
Componente PrintDialog (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms PrintDialog é uma caixa de diálogo pré-configurada

usada para selecionar uma impressora, escolher as páginas a serem impressas e
determinar outras configurações relacionadas à impressão em aplicativos baseados no
Windows. Use-o como uma solução simples para seleção de impressora e de
configurações relacionadas à impressão em vez de configurar sua própria caixa de
diálogo. Você pode permitir que os usuários imprimam muitas partes de seus
documentos: imprimir todos, imprimir um intervalo de páginas especificado ou imprimir
uma seleção. Com base nas caixas de diálogo padrão do Windows, crie aplicativos cuja
funcionalidade básica é imediatamente familiar aos usuários.
Nesta seção
Apresenta os conceitos gerais do componente, que PrintDialog permite exibir uma
caixa de diálogo pré-configurada que os usuários podem usar para selecionar uma
impressora, escolher páginas para imprimir e determinar as configurações relacionadas
à impressão.
Como: Exibir o componente PrintDialog

Explica como exibir a caixa de diálogo e onde ela salva as propriedades.
Referência
PrintDialog
(Windows Forms)
Artigo • 02/06/2023
O componente PrintDialog dos Windows Forms é uma caixa de diálogo pré-configurada

usada para selecionar uma impressora, escolher as páginas a serem impressas e
determinar outras configurações relacionadas à impressão em aplicativos baseados no
Windows. Use-o como uma solução simples para seleção de impressora e de
configurações relacionadas à impressão em vez de configurar sua própria caixa de
diálogo. Você pode habilitar os usuários a imprimir muitas partes de seus documentos:
imprimir tudo, imprimir um intervalo de páginas selecionadas ou uma seleção. Com
base nas caixas de diálogo padrão do Windows, crie aplicativos cuja funcionalidade
básica é imediatamente familiar aos usuários. O PrintDialog componente herda da
CommonDialog classe.
Como trabalhar com o componente

Use o ShowDialog método para exibir a caixa de diálogo em tempo de execução. Esse
componente tem propriedades relacionadas a um único trabalho de impressão
(PrintDocument classe) ou às configurações de uma impressora individual
(PrinterSettings classe). Um deles, por sua vez, pode ser compartilhado por várias
impressoras.
Quando ele é adicionado a um formulário, o PrintDialog componente aparece na

Confira também
PrintDialog
Como exibir o componente PrintDialog
Artigo • 02/06/2023
O PrintDialog componente é a caixa de diálogo de impressão padrão do Windows com

a qual muitos de seus usuários estarão familiarizados. Como os usuários estarão
imediatamente confortáveis com ele, seria benéfico para você usar o PrintDialog
componente.
Para exibir o componente PrintDialog

Chame o ShowDialog método de dentro do código do aplicativo.
Depois que o componente for mostrado, os usuários interagirão com ele,

definindo as propriedades do trabalho de impressão. Elas serão salvas na
PrinterSettings classe (e na PageSettings classe, se o usuário acessar o
Componente PageSetupDialog por meio do PrintDialog componente) associado a
esse trabalho de impressão. Em seguida, você pode fazer chamadas para as
propriedades definidas para determinar as especificidades do trabalho de
impressão.
Confira também
Como: criar trabalhos de impressão padrão do Windows Forms
Como: capturar a entrada do usuário de um PrintDialog em tempo de execução
Suporte à impressão no Windows Forms
Componente PrintDocument (Windows
Forms)
Artigo • 02/06/2023
O componente PrintDocument dos Windows Forms é usado para definir as propriedades

que descrevem o que imprimir e, em seguida, imprime o documento em aplicativos
baseados no Windows. Ele pode ser usado em conjunto com o PrintDialog componente
para estar no comando de todos os aspectos da impressão de documentos.
Nesta seção
Visão geral do componente PrintDocument
Apresenta os conceitos gerais do componente PrintDocument , que permite definir
propriedades que descrevem o que imprimir e inicia a impressão em um aplicativo
baseado em Windows.
Referência
PrintDocument
Apresenta uma lista de tópicos de impressão relacionados ao Windows Forms.
Apresenta os conceitos gerais do componente, que PrintDialog permite exibir uma caixa
de diálogo pré-configurada que os usuários podem usar para selecionar uma
impressora, escolher páginas para imprimir e determinar configurações relacionadas à
impressão.
Apresenta os conceitos gerais do PrintPreviewControl, que você pode usar para criar sua
própria caixa de diálogo ou componente de visualização de impressão.
Apresenta os conceitos gerais do controle, o PrintPreviewDialog que permite exibir uma
caixa de diálogo pré-configurada que os usuários podem usar para ver uma versão do
documento como ele será exibido quando ele for impresso.
PrintDocument (Windows Forms)
Artigo • 21/06/2023
O componente PrintDocument dos Windows Forms é usado para definir as

propriedades que descrevem o que imprimir e a capacidade de imprimir o documento
em aplicativos baseados no Windows. Pode ser usado junto com o componente
PrintDialog para controlar todos os aspectos da impressão de documentos.
Trabalhando com o componente

PrintDocument
Dois dos cenários de main que envolvem o PrintDocument componente são:
Trabalhos de impressão simples, como a impressão de um único arquivo de texto.

Nesse caso, você adicionaria o PrintDocument componente a um Formulário do
Windows e, em seguida, adicionaria uma lógica de programação que imprime um
arquivo no PrintPage manipulador de eventos. A lógica de programação deve
culminar com o Print método para imprimir o documento. Esse método envia um
Graphics objeto, contido na Graphics propriedade da PrintPageEventArgs classe ,
para a impressora. Para obter um exemplo que mostra como imprimir um
documento de texto usando o PrintDocument componente, consulte Como
imprimir um arquivo de texto de várias páginas em Windows Forms.
Trabalhos de impressão mais complexos, como quando é preciso reutilizar lógica

de impressão já escrita. Nesse caso, você derivaria um novo componente do
PrintDocument componente e substituiria (consulte Substituições para Visual Basic
ou substituir para C#) o PrintPage evento.
Quando ele é adicionado a um formulário, o PrintDocument componente aparece na

bandeja na parte inferior do Windows Forms Designer no Visual Studio.
Confira também
Graphics
PrintDocument
Controle PrintPreviewControl (Windows
Forms)
Artigo • 02/06/2023
O Windows Forms PrintPreviewControl é usado para exibir um documento, pois ele

será exibido quando impresso. Esse controle não tem botões nem outros elementos de
interface do usuário, portanto, normalmente você usa o PrintPreviewControl único se
quiser escrever sua própria interface do usuário de visualização de impressão. Se você
quiser a interface do usuário padrão, use um PrintPreviewDialog controle.
Nesta seção
Visão geral do controle PrintPreviewControl
Apresenta os conceitos gerais do PrintPreviewControl , que você pode usar para criar
sua própria caixa de diálogo ou componente de visualização de impressão.
Referência
PrintPreviewControl
Descreve uma maneira alternativa de criar a funcionalidade de visualização de
impressão.

PrintPreviewControl (Windows Forms)
Artigo • 02/06/2023
O Windows Forms PrintPreviewControl é usado para exibir um PrintDocument, pois será

exibido quando impresso. Esse controle não tem botões nem outros elementos de
interface do usuário, portanto, normalmente você usa o PrintPreviewControl único se
quiser escrever sua própria interface de usuário de visualização de impressão. Se você
quiser a interface do usuário padrão, use um PrintPreviewDialog controle; consulte a
visão geral do controle PrintPreviewDialog para obter uma visão geral.
A propriedade chave do controle é Document, que define o documento a ser
visualizado. O documento deve ser um PrintDocument objeto. Para obter uma visão
geral da criação de documentos para impressão, confira Visão geral do componente
PrintDocument e Suporte à impressão nos Windows Forms. As Columns propriedades e
Rows as propriedades determinam o número de páginas exibidas horizontal e
verticalmente no controle. A suavização pode fazer com que o texto pareça mais suave,
mas também pode tornar a exibição mais lenta; para usá-la, defina a UseAntiAlias
propriedade como true .
Confira também
PrintPreviewControl
Controle PrintPreviewDialog (Windows
Forms)
Artigo • 02/06/2023
O controle Windows Forms PrintPreviewDialog é uma caixa de diálogo pré-configurada

usada para exibir como um documento será exibido quando impresso. Use-a em seu
aplicativo baseado no Windows como uma solução simples em vez de configurar sua
própria caixa de diálogo. O controle contém botões para imprimir, aumentar o zoom,
exibir uma ou várias páginas e fechar a caixa de diálogo.
Nesta seção
Apresenta os conceitos gerais do controle, que PrintPreviewDialog permite exibir uma
caixa de diálogo pré-configurada que os usuários podem usar para ver uma versão do
documento como ele será exibido quando ele for impresso.
Como: Exibir visualização de impressão em aplicativos do Windows Forms

Explica como exibir uma página que deve ser impressa usando uma instância do
PrintPreviewDialog controle em tempo de execução.
Referência
PrintPreviewDialog

Lista os diferentes controles de caixa de diálogo para Windows Forms.

Descreve como criar uma caixa de diálogo para um Windows Form.
PrintPreviewDialog (Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms PrintPreviewDialog é uma caixa de diálogo pré-configurada

usada para exibir como um PrintDocument será exibido quando impresso. Use-o em seu
aplicativo baseado no Windows como uma solução simples em vez de configurar sua
própria caixa de diálogo. O controle contém botões para imprimir, aumentar o zoom,
exibir uma ou várias páginas e fechar a caixa de diálogo.
Principais propriedades e métodos

A propriedade de chave do controle é Document, que define o documento a ser
visualizado. O documento deve ser um PrintDocument objeto . Para exibir a caixa de
diálogo, você deve chamar seu ShowDialog método. O anti-aliasing pode fazer com que
o texto pareça mais suave, mas também pode tornar a exibição mais lenta; para usá-lo,
defina a UseAntiAlias propriedade como true .
Determinadas propriedades estão disponíveis por meio do PrintPreviewControl que o

PrintPreviewDialog contém. (Você não precisa adicionar isso PrintPreviewControl ao
formulário; ele é automaticamente contido no PrintPreviewDialog quando você adiciona
a caixa de diálogo ao formulário.) Exemplos de propriedades disponíveis por meio das
PrintPreviewControlColumns propriedades e Rows , que determinam o número de
páginas exibidas horizontal e verticalmente no controle. Você pode acessar a Columns
propriedade como PrintPreviewDialog1.PrintPreviewControl.Columns no Visual Basic,
printPreviewDialog1.PrintPreviewControl.Columns no Visual C#ou
printPreviewDialog1->PrintPreviewControl->Columns no Visual C++.
Desempenho do PrintPreviewDialog
Sob as seguintes condições, o PrintPreviewDialog controle inicializa muito lentamente:
Uma impressora de rede é usada.

As preferências do usuário para essa impressora, como configurações duplex, são
modificadas.
Para aplicativos em execução no .NET Framework 4.5.2, você pode adicionar a seguinte
chave à <seção appSettings> do arquivo de configuração para melhorar o desempenho
da inicialização de PrintPreviewDialog controle:
XML
<appSettings>
<add key="EnablePrintPreviewOptimization" value="true" />
</appSettings>
Se a EnablePrintPreviewOptimization chave estiver definida como qualquer outro valor

ou se a chave não estiver presente, a otimização não será aplicada. Essa chave não terá
efeito se o aplicativo estiver em execução no .NET Framework 4.6 ou posterior.
Para aplicativos em execução no .NET Framework 4.6 ou versões posteriores, você pode
adicionar a seguinte opção ao <elemento AppContextSwitchOverrides> na <seção
runtime> do arquivo de configuração do aplicativo:
XML
<runtime >

<AppContextSwitchOverrides value =
"Switch.System.Drawing.Printing.OptimizePrintPreview=true" />
</runtime >
Se a opção não estiver presente ou se estiver definida como qualquer outro valor, a
otimização não será aplicada.
Se você usar o QueryPageSettings evento para modificar as configurações da

impressora, o desempenho do PrintPreviewDialog controle não melhorará mesmo se
uma opção de configuração de otimização estiver definida.
Confira também
PrintPreviewDialog
Visão geral do controle PrintPreviewControl
Como: Exibir visualização de impressão
em aplicativos do Windows Forms
Artigo • 21/06/2023
Você pode usar o PrintPreviewDialog controle para permitir que os usuários exibam um
documento, muitas vezes antes que ele seja impresso.
Para fazer isso, você precisa especificar uma instância da PrintDocument classe ; este é o
documento a ser impresso. Para obter mais informações sobre como usar a visualização
de impressão com o PrintDocument componente, consulte Como imprimir em Windows
Forms usando a visualização de impressão.
７ Observação
Para usar o PrintPreviewDialog controle em tempo de execução, os usuários

devem ter uma impressora instalada em seu computador, localmente ou por meio
de uma rede, pois é em parte como o PrintPreviewDialog componente determina
a aparência de um documento quando impresso.
O PrintPreviewDialog controle usa a PrinterSettings classe . Além disso, o

PrintPreviewDialog controle usa a PageSettings classe , assim como o
PrintPreviewDialog componente usa. O documento de impressão especificado na
PrintPreviewDialog propriedade do Document controle refere-se a instâncias das
PrinterSettings classes e PageSettings , e elas são usadas para renderizar o documento
na janela de visualização.
Para exibir páginas usando o controle PrintPreviewDialog

Use o ShowDialog método para exibir a caixa de diálogo, especificando o
PrintDocument a ser usado.
No exemplo de código a seguir, o Button manipulador de eventos do Click

controle abre uma instância do PrintPreviewDialog controle . O documento de
impressão é especificado na Document propriedade . No exemplo a seguir,
nenhum documento de impressão é especificado.
O exemplo requer que seu formulário tenha um Button controle, um

PrintDocument componente chamado myDocument e um PrintPreviewDialog
controle .
C#

{
// The print document 'myDocument' used below
// is merely for an example.
// You will have to specify your own print document.
printPreviewDialog1.Document = myDocument;
printPreviewDialog1.ShowDialog();
}

C#
Confira também
Windows Forms
Controle ProgressBar (Windows Forms)
Artigo • 02/06/2023
） Importante
O controle ToolStripProgressBar substitui e adiciona funcionalidade ao controle

ProgressBar, no entanto, o controle ProgressBar é mantido para compatibilidade
com versões anteriores e para uso futuro, se desejado.
O controle Windows Forms ProgressBar indica o progresso de uma ação exibindo um

número apropriado de retângulos organizados em uma barra horizontal. Quando a ação
é concluída, a barra é preenchida. As barras de progresso geralmente são usadas para
dar ao usuário uma indicação de quanto tempo aguardar a conclusão de uma ação
prolongada, por exemplo, quando um arquivo grande está sendo carregado.
Nesta seção
Visão geral do controle ProgressBar
Apresenta os conceitos gerais do controle, o ProgressBar que permite exibir
graficamente o progresso de uma operação.
Como: Definir o valor exibido pelo controle ProgressBar do Windows Forms

Discute várias maneiras diferentes de aumentar o valor exibido pelo ProgressBar
controle.
Referência
ProgressBar
(Windows Forms)
Artigo • 02/06/2023
） Importante

O controle Windows Forms ProgressBar indica o progresso de um processo exibindo

um número apropriado de retângulos organizados em uma barra horizontal. Quando o
processo for concluído, a barra será preenchida. Barras de progresso são normalmente
usadas para conceder ao usuário uma ideia de quanto tempo levará para um processo
ser concluído, como por exemplo, quando um arquivo grande está sendo carregado.
７ Observação
O ProgressBar controle só pode ser orientado horizontalmente no formulário.

As principais propriedades do ProgressBar controle são Value, Minimume Maximum. As
Minimum propriedades e Maximum os valores máximos e mínimos que a barra de
progresso pode exibir. A Value propriedade representa o progresso que foi feito para
concluir a operação. Como a barra exibida no controle é composta de blocos, o valor
exibido pelo ProgressBar controle só aproxima o Value valor atual da propriedade. Com
base no tamanho do ProgressBar controle, a Value propriedade determina quando
exibir o próximo bloco.
A maneira mais comum de atualizar o valor de progresso atual é escrever código para
definir a Value propriedade. No exemplo de carregamento de um arquivo grande, você
pode definir o máximo para o tamanho do arquivo em quilobytes. Por exemplo, se a
Maximum propriedade for definida como 100, a Minimum propriedade será definida
como 10 e a Value propriedade será definida como 50, cinco retângulos serão exibidos.
Isso é metade do número que pode ser exibido.
No entanto, há outras maneiras de modificar o valor exibido pelo ProgressBar controle,
além de definir a Value propriedade diretamente. A Step propriedade pode ser usada
para especificar um valor para incrementar a Value propriedade. Em seguida, chamar o
PerformStep método aumentará o valor. Para variar o valor de incremento, você pode
usar o Increment método e especificar um valor com o qual incrementar a Value
propriedade.
Outro controle que informa graficamente o usuário sobre uma ação atual é o StatusBar
controle.
） Importante
Os StatusStrip controles e ToolStripStatusLabel os controles substituem e

adicionam funcionalidade aos controles eStatusBarPanel, StatusBar no entanto, os
controles e StatusBarPanel os StatusBar controles são mantidos para
compatibilidade com versões anteriores e uso futuro, se você escolher.
Confira também
ProgressBar
Como: Definir o valor exibido pelo
controle ProgressBar do Windows
Forms
Artigo • 02/06/2023
） Importante

o .NET Framework fornece várias maneiras diferentes de exibir um determinado valor

dentro do ProgressBar controle. A abordagem que você escolher dependerá da tarefa
em mãos ou do problema que está resolvendo. A tabela a seguir mostra as abordagens
que você pode escolher.
Abordagem Descrição
Defina o Essa abordagem é útil para as tarefas em que você sabe que o total do item
valor do medido será envolvido, como ler os registros de uma fonte de dados. Além disso,
ProgressBar se você precisar definir o valor uma ou duas vezes, esta será uma maneira fácil de
controle realizar esta tarefa. Por fim, use esse processo se você precisar diminuir o valor
diretamente. exibido pela barra de progresso.
Aumente a Essa abordagem será útil quando você estiver exibindo uma contagem simples
ProgressBar entre o mínimo e máximo, como o tempo decorrido ou o número de arquivos que
exibição por foram processados de um total conhecido.
um valor
fixo.
Aumente a Essa abordagem será útil quando você precisar alterar o valor exibido várias vezes
ProgressBar em volumes diferentes. Um exemplo seria mostrar a quantidade de espaço em
exibição por disco consumida durante a gravação de uma série de arquivos no disco.
um valor
que varia.
A maneira mais direta de definir o valor exibido por uma barra de progresso é definindo
a Value propriedade. Isso pode ser feito no tempo de design ou no tempo de execução.
Para definir o valor de ProgressBar diretamente

1. Defina os ProgressBar valores e Maximum do controle Minimum .
2. No código, defina a propriedade do Value controle como um valor inteiro entre os

valores mínimo e máximo que você estabeleceu.
７ Observação
Se você definir a Value Propriedade fora dos limites estabelecidos pelas

Minimum Propriedades e Maximum , o controle lançará uma
ArgumentException exceção.
O exemplo de código a seguir ilustra como definir o ProgressBar valor

diretamente. O código lerá os registros de uma fonte de dados e atualizará a barra
de progresso e o rótulo sempre que um registro de dados for lido. Este exemplo
requer que o formulário tenha um Label controle, um ProgressBar controle e uma
tabela de dados com uma linha chamada CustomerRow com FirstName campos e
LastName .
C#
public void createNewRecords()

{
// Sets the progress bar's Maximum property to
// the total number of records to be created.
progressBar1.Maximum = 20;
// Creates a new record in the dataset.

// NOTE: The code below will not compile, it merely
// illustrates how the progress bar would be used.
CustomerRow anyRow = DatasetName.ExistingTable.NewRow();
anyRow.FirstName = "Stephen";
anyRow.LastName = "James";
ExistingTable.Rows.Add(anyRow);
// Increases the value displayed by the progress bar.

progressBar1.Value += 1;
// Updates the label to show that a record was read.
label1.Text = "Records Read = " + progressBar1.Value.ToString();
}
Se você estiver exibindo o progresso que prossegue por um intervalo fixo, poderá
definir o valor e, em seguida, chamar um método que aumenta o ProgressBar valor
do controle por esse intervalo. Isso é útil para temporizadores e outros cenários
em que você não esteja medindo o andamento como um percentual do todo.
Para aumentar a barra de progresso com um valor fixo
2. Defina a propriedade do Step controle como um inteiro que representa o valor

para aumentar o valor exibido da barra de progresso.
3. Chame o PerformStep método para alterar o valor exibido pelo valor definido na
Step propriedade.
O exemplo de código a seguir ilustra como uma barra de progresso pode manter
uma contagem de arquivos em uma operação de cópia.
No exemplo a seguir, como cada arquivo é lido na memória, a barra de progresso

e o rótulo são atualizados para refletir a quantidade total de arquivos lidos. Este
exemplo requer que o formulário tenha um Label controle e um ProgressBar
controle.
C#
public void loadFiles()

{
// Sets the progress bar's minimum value to a number representing
// no operations complete -- in this case, no files read.
progressBar1.Minimum = 0;
// Sets the progress bar's maximum value to a number representing
// all operations complete -- in this case, all five files read.
progressBar1.Maximum = 5;
// Sets the Step property to amount to increase with each iteration.
// In this case, it will increase by one with every file read.
progressBar1.Step = 1;
// Uses a for loop to iterate through the operations to be

// completed. In this case, five files are to be copied into memory,
// so the loop will execute 5 times.
for (int i = 0; i <= 4; i++)
{
// Inserts code to copy a file
progressBar1.PerformStep();
// Updates the label to show that a file was read.
label1.Text = "# of Files Read = " +
progressBar1.Value.ToString();
}
}
Por fim, você pode aumentar o valor exibido por uma barra de progresso para que
cada aumento seja um valor exclusivo. Isso será útil quando você estiver
controlando uma série de operações exclusivas, como gravar arquivos de
tamanhos diferentes em um disco rígido ou medir o progresso como um
percentual do todo.
Para aumentar a barra de progresso com um valor

dinâmico
2. Chame o Increment método para alterar o valor exibido por um inteiro

especificado por você.
O exemplo de código a seguir ilustra como uma barra de progresso pode calcular
a quantidade de espaço em disco usado durante uma operação de cópia.
No exemplo a seguir, como cada arquivo é gravado no disco rígido, a barra de

progresso e o rótulo são atualizados para refletir a quantidade de espaço em disco
disponível. Este exemplo requer que o formulário tenha um Label controle e um
ProgressBar controle.
C#
public void readFiles()

{
// Sets the progress bar's minimum value to a number
// representing the hard disk space before the files are read in.
// You will most likely have to set this using a system call.
// NOTE: The code below is meant to be an example and
// will not compile.
progressBar1.Minimum = AvailableDiskSpace();
// Sets the progress bar's maximum value to a number
// representing the total hard disk space.
// You will most likely have to set this using a system call.
// NOTE: The code below is meant to be an example
// and will not compile.
progressBar1.Maximum = TotalDiskSpace();
// Uses a for loop to iterate through the operations to be

// completed. In this case, five files are to be written
// to the disk, so it will execute the loop 5 times.
for (int i = 1; i<= 5; i++)
{
// Insert code to read a file into memory and update file size.
// Increases the progress bar's value based on the size of
// the file currently being written.
progressBar1.Increment(FileSize);
// Updates the label to show available drive space.
label1.Text = "Current Disk Space Used = " +
progressBar1.Value.ToString();
}
}
Confira também
ProgressBar
ToolStripProgressBar
Controle RadioButton (Windows Forms)
Artigo • 02/06/2023
RadioButton Windows Forms controles apresentam um conjunto de duas ou mais

opções mutuamente exclusivas para o usuário. Embora os botões de opção e caixas de
seleção pareçam funcionar da mesma forma, há uma diferença importante: quando um
usuário seleciona um botão de opção, os outros botões de opção no mesmo grupo não
podem ser selecionados juntamente.
Nesta seção
Visão geral do controle RadioButton
Como: Agrupar controles RadioButton do Windows Forms para funcionarem como um

conjunto
Explica como agrupar botões de opção como um conjunto, dos quais apenas um pode
ser selecionado.
Referência
Classe RadioButton
(Windows Forms)
Artigo • 21/06/2023
RadioButton Windows Forms controles apresentam um conjunto de duas ou mais

opções mutuamente exclusivas para o usuário. Embora os botões de opção e caixas de
seleção pareçam funcionar da mesma forma, há uma diferença importante: quando um
usuário seleciona um botão de opção, os outros botões de opção no mesmo grupo não
podem ser selecionados juntamente. Por outro lado, qualquer número de caixas de
seleção pode ser selecionado. Definir um grupo de botões de opção informa ao usuário:
“Esse é um conjunto de opções, dentre as quais você pode escolher uma e apenas uma”.
Usando o controle
Quando um RadioButton controle é clicado, sua Checked propriedade é definida true
como e o Click manipulador de eventos é chamado. O CheckedChanged evento é
gerado quando o valor da Checked propriedade é alterado. Se a AutoCheck
propriedade estiver definida true como (o padrão), quando o botão de opção for
selecionado, todas as outras pessoas no grupo serão desmarcadas automaticamente.
Essa propriedade normalmente é definida apenas como false quando o código de
validação é usado para verificar se o botão de opção selecionado é uma opção
permitida. O texto exibido dentro do controle é definido com a Text propriedade , que
pode conter atalhos de tecla de acesso. Uma tecla de acesso permite a um usuário
“clicar” no controle pressionando a tecla ALT com a tecla de acesso. Para obter mais
informações, consulte Como criar teclas de acesso para controles dos Windows Forms e
Como definir o texto exibido por um controle dos Windows Forms.
O RadioButton controle pode aparecer como um botão de comando, que parece ter
sido deprimido se selecionado, se a Appearance propriedade estiver definida
Buttoncomo . Os botões de opção também podem exibir imagens usando as Image
propriedades e ImageList . Para obter mais informações, consulte Como definir a
imagem exibida por um controle dos Windows Forms.
Confira também
RadioButton
Como: Agrupar controles RadioButton do Windows Forms para funcionarem como
um conjunto
Como: Agrupar controles RadioButton
do Windows Forms para funcionarem
como um conjunto
Artigo • 02/06/2023
os controles de Windows Forms RadioButton são projetados para fornecer aos usuários
uma opção entre duas ou mais configurações, das quais apenas uma pode ser atribuída
a um procedimento ou objeto. Por exemplo, um grupo de RadioButton controles pode
exibir uma opção de operadoras de pacote para um pedido, mas apenas uma das
operadoras será usada. Portanto, somente um RadioButton de cada vez pode ser
selecionado, mesmo que ele faça parte de um grupo funcional.
Agrupe os botões de opção desenhando-os dentro de um contêiner, como um Panel

controle, um GroupBox controle ou um formulário. Todos os botões de opção que
forem adicionados diretamente a um formulário se tornam um grupo. Para adicionar
grupos separados, você deve inseri-los em painéis ou caixas de grupo. Para obter mais
informações sobre painéis ou caixas de grupo, consulte Visão geral do controle Panel ou
Visão geral do controle GroupBox.
Para agrupar controles RadioButton como um conjunto

para funcionar independentemente dos outros conjuntos
1. arraste um GroupBox controle ou Panel da guia Windows Forms na caixa de
ferramentas para o formulário.
2. Desenhe RadioButton controles no GroupBox controle ou Panel .
Confira também
RadioButton
Controle RichTextBox (Windows Forms)
Artigo • 02/06/2023
O controle RichTextBox dos Windows Forms é usado para exibir, inserir e manipular
texto com formatação. O RichTextBox controle faz tudo o que o TextBox controle faz,
mas também pode exibir fontes, cores e links; carregar texto e imagens inseridas de um
arquivo; desfazer e refazer operações de edição; e localizar caracteres especificados. O
controle RichTextBox normalmente é usado para fornecer manipulação de texto e exibir
recursos semelhantes aos aplicativos de processamento de texto como o Microsoft
Word. Assim como o TextBox controle, o RichTextBox controle pode exibir barras de
rolagem; mas, ao contrário do TextBox controle, ele exibe barras de rolagem horizontal
e vertical por padrão e tem configurações de barra de rolagem adicionais.
Nesta seção
Visão geral do controle RichTextBox
Apresenta os conceitos gerais do controle RichTextBox , que permite aos usuários
inserir, exibir e manipular texto com opções de formatação.
Como: Determinar quando os atributos de formatação mudam no controle RichTextBox

do Windows Forms
Explica como manter o controle de alterações na formatação de fonte e parágrafo no
controle RichTextBox .
Como: Exibir barras de rolagem no controle RichTextBox do Windows Forms

Descreve as várias opções disponíveis para barras de rolagem no controle RichTextBox .
Como: Exibir links em estilo da Web com o controle RichTextBox do Windows Forms
Explica como vincular a sites da Web do controle RichTextBox .
Como: Habilitar operações do tipo "arrastar e soltar" com o controle RichTextBox do

Windows Forms
Fornece instruções para arrastar os dados no controle RichTextBox .
Como: Carregar arquivos no controle RichTextBox do Windows Forms

Fornece instruções para carregar um arquivo existente para o controle RichTextBox .
Como: Salvar arquivos com o controle RichTextBox do Windows Forms

Fornece instruções para salvar o conteúdo do controle RichTextBox em um arquivo.
Como: Definir atributos de fonte para o controle RichTextBox do Windows Forms
Descreve como definir a família de fontes, tamanho, estilo e cor do texto no controle
RichTextBox .
Como: Definir recuos definidos, recuos deslocados e parágrafos com marcadores com o
controle RichTextBox do Windows Forms
Descreve como formatar parágrafos no controle RichTextBox .
Referência
Classe RichTextBox
Controle TextBox
Apresenta os conceitos gerais do controle, que TextBox permite a entrada editável de
várias linhas do usuário.
Visão geral do controle RichTextBox
(Windows Forms)
Artigo • 21/06/2023
O controle RichTextBox dos Windows Forms é usado para exibir, inserir e manipular
texto com formatação. O RichTextBox controle faz tudo o que o TextBox controle faz,
mas também pode exibir fontes, cores e links; carregar texto e imagens inseridas de um
arquivo e localizar caracteres especificados. O controle RichTextBox normalmente é
usado para fornecer manipulação de texto e exibir recursos semelhantes aos aplicativos
de processamento de texto como o Microsoft Word. Assim como o TextBox controle, o
RichTextBox controle pode exibir barras de rolagem, mas ao contrário do TextBox
controle, sua configuração padrão é exibir barras de rolagem horizontais e verticais
conforme necessário e tem configurações de barra de rolagem adicionais.
Trabalhando com o controle RichTextBox

Assim como acontece com o TextBox controle , o texto exibido é definido pela Text
propriedade . O RichTextBox controle tem várias propriedades para formatar texto. Para
obter detalhes sobre essas propriedades, consulte Como definir atributos de fonte para
o controle RichTextBox do Windows Forms e Como definir recuos, recuos deslocados e
parágrafos com marcadores com o controle RichTextBox do Windows Forms. Para
manipular arquivos, os LoadFile métodos e SaveFile podem exibir e gravar vários
formatos de arquivo, incluindo texto sem formatação, texto sem formatação Unicode e
FORMATO rich text (RTF). Os possíveis formatos de arquivo estão listados em
RichTextBoxStreamType. Você pode usar o Find método para localizar cadeias de
caracteres de texto ou caracteres específicos.
Você também pode usar um RichTextBox controle para links de estilo da Web definindo
a DetectUrls propriedade true como e escrevendo código para manipular o LinkClicked
evento. Para obter mais informações, consulte Como exibir links em estilo da Web com
o controle RichTextBox do Windows Forms. Você pode impedir que o usuário manipule
parte ou todo o texto no controle definindo a SelectionProtected propriedade
true como .
Você pode desfazer e refazer a maioria das operações de edição em um RichTextBox

controle chamando os Undo métodos e Redo . O CanRedo método permite que você
determine se a última operação que o usuário desfeito pode ser reaplicada ao controle.
Confira também
RichTextBox
Visão geral do controle TextBox
Como: Determinar quando os atributos
de formatação mudam no controle
RichTextBox do Windows Forms
Artigo • 21/06/2023
Um uso comum do controle Windows Forms RichTextBox é formatar texto com

atributos como opções de fonte ou estilos de parágrafo. Seu aplicativo pode precisar
controlar as alterações no texto de formatação para fins de exibição de uma barra de
ferramentas, como muitos aplicativos de processamento de texto.
Para responder a alterações em atributos de formatação

1. Escreva código no SelectionChanged manipulador de eventos para executar uma
ação apropriada dependendo do valor do atributo. O exemplo a seguir altera a
aparência de um botão de barra de ferramentas dependendo do valor da
SelectionBullet propriedade. O botão de barra de ferramentas será atualizado
somente quando o ponto de inserção for movido no controle.
O exemplo a seguir pressupõe um formulário com um RichTextBox controle e um

ToolBar controle que contém um botão de barra de ferramentas. Para obter mais
informações sobre barras de ferramentas e botões de barra de ferramentas, veja
Como adicionar botões a um controle de barra de ferramentas.
C#
// The following code assumes the existence of a toolbar control

// with at least one toolbar button.
private void richTextBox1_SelectionChanged(object sender,
System.EventArgs e)
{
if (richTextBox1.SelectionBullet == true)
{
// Bullet button on toolbar should appear pressed
toolBarButton1.Pushed = true;
}
else
{
// Bullet button on toolbar should appear unpressed
toolBarButton1.Pushed = false;
}
}
Confira também
SelectionChanged
RichTextBox
Como: Exibir barras de rolagem no
controle RichTextBox do Windows
Forms
Artigo • 02/06/2023
Por padrão, o controle Windows Forms RichTextBox exibe barras de rolagem horizontais
e verticais conforme necessário. Há sete valores possíveis para a ScrollBars propriedade
do RichTextBox controle, que são descritos na tabela abaixo.
Exibir barras de rolagem em um controle RichTextBox

1. Defina a propriedade Multiline como true . Nenhum tipo de barra de rolagem,
incluindo horizontal, será exibido se a Multiline propriedade estiver definida como
false .
2. Defina a ScrollBars propriedade como um valor apropriado da

RichTextBoxScrollBars enumeração.
Valor Descrição
Both (padrão) Exibe barras de rolagem horizontal, vertical ou ambas, mas apenas
quando o texto excede a largura ou o comprimento do controle.
None Nunca exibe nenhum tipo de barra de rolagem.
Horizontal Exibe uma barra de rolagem horizontal somente quando o texto excede
a largura do controle. (Para que isso ocorra, a WordWrap propriedade
deve ser definida como false .)
Vertical Exibe uma barra de rolagem vertical somente quando o texto excede a
altura do controle.
ForcedHorizontal Exibe uma barra de rolagem horizontal quando a WordWrap

propriedade é definida como false . A barra de rolagem aparece
esmaecida quando o texto não excede a largura do controle.
ForcedVertical Sempre exibe uma barra de rolagem vertical. A barra de rolagem

aparece esmaecida quando o texto não excede o tamanho do controle.
ForcedBoth Sempre exibe uma barra de rolagem vertical. Exibe uma barra de
rolagem horizontal quando a WordWrap propriedade é definida como
false . A barra de rolagem aparece esmaecida quando o texto não
excede a largura ou altura do controle.
3. Defina a propriedade WordWrap com um valor apropriado.
Valor DESCRIÇÃO
false O texto do controle não é ajustado automaticamente para caber na largura do

controle, por isso rolará para a direita até atingir uma quebra de linha. Use esse
valor se você escolher barras de rolagem horizontal ou ambas acima.
true O texto do controle é ajustado automaticamente para caber na largura do

(padrão) controle. A barra de rolagem horizontal não será exibida. Use esse valor se você
escolher as barras de rolagem vertical ou nenhuma acima para exibir um ou
mais parágrafos acima.
Confira também
RichTextBoxScrollBars
RichTextBox
Como: Exibir links em estilo da Web
com o controle RichTextBox do
Windows Forms
Artigo • 02/06/2023
O controle Windows Forms RichTextBox pode exibir links da Web como coloridos e
sublinhados. Você pode gravar o código que abre uma janela do navegador mostrando
o site da Web especificado no texto do link quando o link é clicado.
Para vincular a uma página da Web com o controle

RichTextBox
1. Defina a Text propriedade como uma cadeia de caracteres que inclui uma URL
válida (por exemplo, https://www.microsoft.com/ ).
2. Verifique se a DetectUrls propriedade está definida true como (o padrão).
3. Crie uma nova instância global do Process objeto .
4. Escreva um manipulador de eventos para o LinkClicked evento que envia ao

navegador o texto desejado.
No exemplo a seguir, o LinkClicked evento abre uma instância da Internet Explorer

para a URL especificada na Text propriedade do RichTextBox controle. Este
exemplo pressupõe um formulário com um RichTextBox controle .
） Importante
Ao chamar o Process.Start método , você encontrará uma SecurityException

exceção se estiver executando o código em um contexto de confiança parcial
devido a privilégios insuficientes. Para obter mais informações, consulte
Noções Básicas da Segurança de Acesso do Código.
C#
public System.Diagnostics.Process p = new System.Diagnostics.Process();
private void richTextBox1_LinkClicked(object sender,

System.Windows.Forms.LinkClickedEventArgs e)
{
// Call Process.Start method to open a browser
// with link text as URL.
p = System.Diagnostics.Process.Start("IExplore.exe", e.LinkText);
}
(Visual C++) Você deve inicializar o processo p , o que pode ser feito incluindo a
seguinte instrução no construtor do formulário:
C++
p = gcnew System::Diagnostics::Process();

C#
this.richTextBox1.LinkClicked += new
System.Windows.Forms.LinkClickedEventHandler
(this.richTextBox1_LinkClicked);
É importante parar imediatamente o processo que você criou quando terminar de

trabalhar com ele. No que se refere ao código apresentado acima, o código para
interromper o processo pode se parecer com isso:
C#
public void StopWebProcess()

{
p.Kill();
}
Confira também
DetectUrls
LinkClicked
RichTextBox
Como: Habilitar operações do tipo
"arrastar e soltar" com o controle
Artigo • 21/06/2023
As operações de arrastar e soltar com o controle Windows Forms RichTextBox são feitas
manipulando os DragEnter eventos e DragDrop . Portanto, as operações de arrastar e
soltar são extremamente simples com o RichTextBox controle .
Habilitar operações de arrastar em um controle

RichTextBox
1. Defina a AllowDrop propriedade do RichTextBox controle como true .
2. Escreva código no manipulador de eventos do DragEnter evento. Use uma

instrução if para garantir que os dados que são arrastados pertencem a um tipo
aceitável (neste caso, texto). A DragEventArgs.Effect propriedade pode ser definida
como qualquer valor da DragDropEffects enumeração.
C#
private void richTextBox1_DragEnter(object sender,

System.Windows.Forms.DragEventArgs e)
{
if (e.Data.GetDataPresent(DataFormats.Text))
e.Effect = DragDropEffects.Copy;
else
e.Effect = DragDropEffects.None;
}

C#
this.richTextBox1.DragEnter += new
System.Windows.Forms.DragEventHandler
(this.richTextBox1_DragEnter);
3. Escreva o código para manipular o DragDrop evento. Use o DataObject.GetData

método para recuperar os dados que estão sendo arrastados.
No exemplo abaixo, o código define a Text propriedade do RichTextBox controle
igual aos dados que estão sendo arrastados. Se já houver texto no RichTextBox
controle, o texto arrastado será inserido no ponto de inserção.
C#
private void richTextBox1_DragDrop(object sender,

System.Windows.Forms.DragEventArgs e)
{
int i;
String s;
// Get start position to drop the text.

i = richTextBox1.SelectionStart;
s = richTextBox1.Text.Substring(i);
richTextBox1.Text = richTextBox1.Text.Substring(0,i);
// Drop the text on to the RichTextBox.

richTextBox1.Text = richTextBox1.Text +
e.Data.GetData(DataFormats.Text).ToString();
richTextBox1.Text = richTextBox1.Text + s;
}

C#
this.richTextBox1.DragDrop += new
System.Windows.Forms.DragEventHandler
(this.richTextBox1_DragDrop);
Testar a funcionalidade do tipo "arrastar e soltar" no seu

aplicativo
1. Salve e compile o aplicativo. Enquanto estiver em execução, execute o WordPad.
O WordPad é um editor de texto instalado pelo Windows que permite realizar

operações do tipo "arrastar e soltar". Ele pode ser acessado clicando no botão
Iniciar, selecionando Executar, digitando WordPad na caixa de texto da caixa de
diálogo Executar e clicando em OK.
2. Após abrir o WordPad, digite uma cadeia de texto nele. Usando o mouse, selecione
o texto e arraste o texto selecionado para o RichTextBox controle em seu aplicativo
do Windows.
Observe que quando você aponta o mouse para o RichTextBox controle (e,
consequentemente, aciona o DragEnter evento), o ponteiro do mouse muda e
você pode soltar o texto selecionado no RichTextBox controle.
Quando você libera o botão do mouse, o texto selecionado é removido (ou seja, o
DragDrop evento é gerado) e é inserido dentro do RichTextBox controle .
Confira também
RichTextBox
Como: executar operações de do tipo "arrastar e soltar" entre aplicativos
Como: Carregar arquivos no controle
Artigo • 02/06/2023
O controle Windows Forms RichTextBox pode exibir um texto sem formatação, texto
sem formatação Unicode ou um arquivo RTF (Rich-Text-Format). Para fazer isso, chame
o LoadFile método. Você também pode usar o LoadFile método para carregar dados de
um fluxo. Para obter mais informações, consulte LoadFile(Stream,
RichTextBoxStreamType).
Para carregar um Arquivo no controle RichTextBox

1. Determine o caminho do arquivo a ser aberto usando o OpenFileDialog
componente. Para obter uma visão geral, consulte Visão geral do componente
OpenFileDialog.
2. Chame o LoadFile método do RichTextBox controle, especificando o arquivo a ser

carregado e, opcionalmente, um tipo de arquivo. No exemplo abaixo, o arquivo a
ser carregado é retirado da OpenFileDialog propriedade do FileName
componente. Se você chamar o método com um nome de arquivo como seu único
argumento, o tipo de arquivo será considerado como RTF. Para especificar outro
tipo de arquivo, chame o método com um valor da RichTextBoxStreamType
enumeração como seu segundo argumento.
No exemplo abaixo, o OpenFileDialog componente é mostrado quando um botão

é clicado. O arquivo selecionado é aberto e exibido no RichTextBox controle. Este
exemplo supõe que um formulário tem um botão, btnOpenFile .
C#
private void btnOpenFile_Click(object sender, System.EventArgs e)

{
if(openFileDialog1.ShowDialog() == DialogResult.OK)
{
richTextBox1.LoadFile(openFileDialog1.FileName,
RichTextBoxStreamType.RichText);
}
}

C#
this.btnOpenFile.Click += new System.EventHandler(this.

btnOpenFile_Click);
） Importante
Para executar esse processo, o assembly pode exigir um nível de privilégio

concedido pela System.Security.Permissions.FileIOPermission classe. Se você
estiver executando em um contexto de confiança parcial, o processo poderá
gerar uma exceção em razão dos privilégios insuficientes. Para obter mais
informações, consulte Noções Básicas da Segurança de Acesso do Código.
Confira também
RichTextBox.LoadFile
RichTextBox
Como: Salvar arquivos com o controle
Artigo • 02/06/2023
O controle Windows Forms RichTextBox pode gravar as informações exibidas em um

dos vários formatos:
Texto sem formatação
Texto sem formatação Unicode
RTF (Formato Rich Text)
RTF com espaços em vez de objetos OLE
Texto sem formatação com uma representação textual de objetos OLE
Para salvar um arquivo, chame o SaveFile método. Você também pode usar o método
SaveFile para salvar dados em um fluxo. Para obter mais informações, consulte
SaveFile(Stream, RichTextBoxStreamType).
Para salvar o conteúdo do controle em um arquivo

1. Determine o caminho do arquivo a ser salvo.
Para fazer isso em um aplicativo do mundo real, você normalmente usaria o

SaveFileDialog componente. Para obter uma visão geral, consulte Visão geral do
componente SaveFileDialog.
2. Chame o SaveFile método do RichTextBox controle, especificando o arquivo para

salvar e, opcionalmente, um tipo de arquivo. Se você chamar o método com um
nome de arquivo como seu único argumento, o arquivo será salvo como RTF. Para
especificar outro tipo de arquivo, chame o método com um valor da
RichTextBoxStreamType enumeração como seu segundo argumento.
No exemplo de código a seguir, o caminho definido para o do arquivo rich-text é a

mínimos de acesso ao sistema executem com mais segurança o aplicativo. O
exemplo a seguir pressupõe um formulário com um RichTextBox controle já
adicionado.
C#
public void SaveFile()

{
// You should replace the bold file name in the
// sample below with a file name of your own choosing.
richTextBox1.SaveFile(System.Environment.GetFolderPath
+ @"\Testdoc.rtf",
RichTextBoxStreamType.RichNoOleObjs);
}
） Importante
Este exemplo cria um novo arquivo, se o arquivo ainda não existe. Se um

aplicativo precisar criar um arquivo, essa aplicativo precisará de acesso Criar
para a pasta. As permissões são definidas usando listas de controle de acesso.
Se o arquivo já existir, o aplicativo precisará apenas de acesso Gravar, um
privilégio menor. Sempre que possível, é mais seguro criar o arquivo durante
a implantação e somente conceder acesso de leitura a um único arquivo, em
vez de acesso Criar a uma pasta. Além disso, é mais seguro gravar dados em
pastas de usuário do que na pasta raiz ou na pasta Arquivos de Programas.
Confira também
RichTextBox.SaveFile
RichTextBox
Como: Definir atributos de fonte para o
controle RichTextBox do Windows
Forms
Artigo • 02/06/2023
O controle Windows Forms RichTextBox tem várias opções para formatar o texto
exibido. Você pode tornar os caracteres selecionados em negrito, sublinhado ou itálico,
usando a SelectionFont propriedade. Você também pode usar essa propriedade para
alterar o tamanho e a face de tipo dos caracteres selecionados. A SelectionColor
propriedade permite alterar a cor dos caracteres selecionados.
Para alterar a aparência dos caracteres

1. Defina a SelectionFont propriedade como uma fonte apropriada.
Para permitir que os usuários definam a família de fontes, o tamanho e a face de

tipo em um aplicativo, você normalmente usaria o FontDialog componente. Para
obter uma visão geral, consulte Visão geral do componente FontDialog.
2. Defina a SelectionColor propriedade como uma cor apropriada.
Para permitir que os usuários definam a cor em um aplicativo, você normalmente

usaria o ColorDialog componente. Para obter uma visão geral, consulte Visão geral
do componente ColorDialog.
C#
richTextBox1.SelectionFont = new Font("Tahoma", 12, FontStyle.Bold);

richTextBox1.SelectionColor = System.Drawing.Color.Red;
７ Observação
Essas propriedades afetam apenas o texto selecionado ou, se nenhum texto

estiver selecionado, o texto que é digitado no local atual do ponto de
inserção. Para obter informações sobre como selecionar texto
programaticamente, consulte Select.
Confira também
RichTextBox
Como: Definir recuos definidos, recuos
deslocados e parágrafos com
marcadores com o controle RichTextBox
do Windows Forms
Artigo • 02/06/2023
O controle Windows Forms RichTextBox tem várias opções para formatar o texto
exibido. Você pode formatar parágrafos selecionados como listas com marcadores
definindo a SelectionBullet propriedade. Você também pode usar o SelectionIndent,
SelectionRightIndente SelectionHangingIndent as propriedades para definir o recuo de
parágrafos em relação às bordas esquerda e direita do controle, e a borda esquerda de
outras linhas de texto.
Formatar um parágrafo como uma lista com marcadores

1. Defina a propriedade SelectionBullet como true .
C#
richTextBox1.SelectionBullet = true;
Para recuar um parágrafo

1. Defina a SelectionIndent propriedade como um inteiro que representa a distância
em pixels entre a borda esquerda do controle e a borda esquerda do texto.
2. Defina a SelectionHangingIndent propriedade como um inteiro que representa a

distância em pixels entre a borda esquerda da primeira linha de texto no parágrafo
e a borda esquerda das linhas subsequentes no mesmo parágrafo. O valor da
SelectionHangingIndent propriedade só se aplica a linhas em um parágrafo que
foram encapsuladas abaixo da primeira linha.
3. Defina a SelectionRightIndent propriedade como um inteiro que representa a

distância em pixels entre a borda direita do controle e a borda direita do texto.
C#
richTextBox1.SelectionIndent = 8;
richTextBox1.SelectionHangingIndent = 3;
richTextBox1.SelectionRightIndent = 12;
７ Observação
Todas essas propriedades afetam todos os parágrafos que contêm o texto

selecionado, bem como o texto digitado após o ponto de inserção atual. Por
exemplo, quando um usuário seleciona uma palavra em um parágrafo e ajusta
o recuo, as novas configurações serão aplicadas a todo o parágrafo que
contém a palavra, bem como aos parágrafos subsequentemente inseridos
depois do parágrafo selecionado. Para obter informações sobre como
selecionar texto programaticamente, consulte Select.
Confira também
RichTextBox
Componente SaveFileDialog (Windows
Forms)
Artigo • 02/06/2023
O componente Windows Forms SaveFileDialog é uma caixa de diálogo pré-configurada.

É o mesmo que a caixa de diálogo Salvar Arquivo padrão usada pelo Windows. Herda
da CommonDialog classe.
Nesta seção
Visão geral do componente SaveFileDialog
Apresenta os conceitos gerais do componente, o SaveFileDialog que permite exibir uma
caixa de diálogo pré-configurada que os usuários podem usar para salvar um arquivo
em um local especificado.
Como: Salvar arquivos usando o componente SaveFileDialog

Explica como salvar um arquivo por meio de uma instância do SaveFileDialog
componente em tempo de execução.
Referência
Classe SaveFileDialog

SaveFileDialog (Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms SaveFileDialog é uma caixa de diálogo pré-configurada.

É o mesmo que a caixa de diálogo Salvar Arquivo padrão usada pelo Windows. Herda
da CommonDialog classe.
Trabalhando com o componente SaveFileDialog

Use-o como uma solução simples para permitir que os usuários salvem arquivos em vez
de configurar sua própria caixa de diálogo. Ao contar com caixas de diálogo padrão do
Windows, a funcionalidade básica dos aplicativos que você cria é imediatamente familiar
para os usuários. No entanto, lembre-se de que, ao usar o SaveFileDialog componente,
você deve escrever sua própria lógica de salvamento de arquivos.
Você pode usar o ShowDialog método para exibir a caixa de diálogo em tempo de
execução. Você pode abrir um arquivo no modo de leitura/gravação usando o OpenFile
método.
Quando ele é adicionado a um formulário, o SaveFileDialog componente aparece na

Confira também
SaveFileDialog
Como: Salvar arquivos usando o
componente SaveFileDialog
Artigo • 02/06/2023
O SaveFileDialog componente permite que os usuários naveguem pelo sistema de

arquivos e selecionem os arquivos a serem salvos. A caixa de diálogo retorna o caminho
e o nome do arquivo que o usuário selecionou na caixa de diálogo. No entanto, você
deve escrever o código para efetivamente gravar os arquivos no disco.
Salvar arquivos usando o componente SaveFileDialog

Exiba a caixa de diálogo Salvar Arquivo e chame um método para salvar o arquivo
selecionado pelo usuário.
Use o SaveFileDialog método do componente OpenFile para salvar o arquivo. Esse

método fornece um objeto Stream que você pode gravar.
O exemplo a seguir usa a DialogResult propriedade para obter o nome do arquivo

e o OpenFile método para salvar o arquivo. O OpenFile método fornece um fluxo
para gravar o arquivo.
No exemplo a seguir, há um Button controle com uma imagem atribuída a ele.

Quando você clica no botão, SaveFileDialog um componente é instariado com um
filtro que permite arquivos do tipo .gif, .jpeg e .bmp. Se um arquivo desse tipo for
selecionado na caixa de diálogo Salvar Arquivo, a imagem do botão será salva.
） Importante
Para obter ou definir a FileName propriedade, o assembly requer um nível de

privilégio concedido pela System.Security.Permissions.FileIOPermission
classe . Se você estiver executando em um contexto de confiança parcial, o
processo poderá gerar uma exceção em razão dos privilégios insuficientes.
Para obter mais informações, consulte Noções Básicas da Segurança de
Acesso do Código.
O exemplo presume que seu formulário tem um controle com sua ButtonImage
propriedade definida como um arquivo do tipo .gif, .jpeg ou .bmp.
７ Observação
A FileDialog propriedade da classe FilterIndex (que, devido à herança,
SaveFileDialog faz parte da classe ) usa um índice baseado em um. Isso será
importante se você estiver escrevendo código para salvar dados em um
formato específico (por exemplo, salvar um arquivo como texto sem
formatação em vez de formato binário). Essa propriedade é apresentada no
exemplo abaixo.
C#

{
// Displays a SaveFileDialog so the user can save the Image
// assigned to Button2.
SaveFileDialog saveFileDialog1 = new SaveFileDialog();
saveFileDialog1.Filter = "JPeg Image|*.jpg|Bitmap Image|*.bmp|Gif
Image|*.gif";
saveFileDialog1.Title = "Save an Image File";
saveFileDialog1.ShowDialog();
// If the file name is not an empty string open it for saving.

if(saveFileDialog1.FileName != "")
{
// Saves the Image via a FileStream created by the OpenFile
method.
System.IO.FileStream fs =
(System.IO.FileStream)saveFileDialog1.OpenFile();
// Saves the Image in the appropriate ImageFormat based upon the
// File type selected in the dialog box.
// NOTE that the FilterIndex property is one-based.
switch(saveFileDialog1.FilterIndex)
{
case 1 :
this.button2.Image.Save(fs,
System.Drawing.Imaging.ImageFormat.Jpeg);
break;
case 2 :
System.Drawing.Imaging.ImageFormat.Bmp);
break;
case 3 :
System.Drawing.Imaging.ImageFormat.Gif);
break;
}
fs.Close();
}
}
C#
Para obter mais informações sobre como escrever fluxos de arquivos, consulte
BeginWrite e Write.
７ Observação
Determinados controles, como o RichTextBox controle , têm a capacidade de

salvar arquivos.
Confira também
SaveFileDialog
Classe SoundPlayer
Artigo • 02/06/2023
A classe SoundPlayer permite que você inclua facilmente sons em seus aplicativos.
Você também pode usar a SystemSounds classe para reproduzir sons comuns do
sistema, incluindo um bipe.
Nesta seção
Visão geral da classe SoundPlayer
Apresenta a classe e suas propriedades, métodos e eventos mais usados.
Como: Reproduzir um som de um Windows Form

Fornece código para reproduzir um som especificado por meio de um caminho de
arquivo, caminho UNC ou caminho HTTP.
Como: Reproduzir um aviso sonoro de um Windows Form

Fornece código para reproduzir o som de aviso sonoro do computador.
Como: Reproduzir um som inserido em um recurso de um Windows Form

Fornece código para tocar um som de um recurso.
Como: Reproduzir um som do sistema de um Windows Form

Fornece código para reproduzir um dos sons do sistema.
Como: Carregar um som de forma assíncrona dentro de um Windows Form

Fornece código para carregar um som de forma assíncrona de uma URL e reproduzi-lo.
Como: Fazer Loop de um Som Tocado em um Formulário do Windows

Fornece código que toca um som repetidamente.
Referência
SoundPlayer
Fornece links para tópicos sobre os controles projetados especificamente para funcionar
com o Windows Forms.

Confira também
Objeto My.Computer
Artigo • 21/06/2023
A classe SoundPlayer permite que você inclua facilmente sons em seus aplicativos.
A SoundPlayer classe pode reproduzir arquivos de som no formato .wav, seja de um

recurso ou de locais UNC ou HTTP. Além disso, a SoundPlayer classe permite que você
carregue ou reproduza sons de forma assíncrona.
Você também pode usar a SystemSounds classe para reproduzir sons comuns do
sistema, incluindo um bipe.
Propriedades, métodos e eventos normalmente

usados
Nome Descrição
Propriedade O caminho do arquivo ou o endereço Web do som. Os valores aceitáveis

SoundLocation podem ser HTTP ou UNC.
Propriedade O número de milissegundos que o programa irá esperar para carregar um

LoadTimeout som antes que ele gere uma exceção. O padrão é 10 segundos.
Propriedade Um valor booliano que indica se o som terminou de ser carregado.

IsLoadCompleted
Método Load Carrega um som de forma síncrona.
Método Começa a carregar um som de forma assíncrona. Quando o carregamento é

LoadAsync concluído, ele aciona o OnLoadCompleted evento.
Método Play Reproduz o som especificado na SoundLocation propriedade ou Stream em

um novo thread.
Método PlaySync Reproduz o som especificado na SoundLocation propriedade ou Stream no

thread atual.
Método Stop Interrompe qualquer som que está em reprodução no momento.
Evento Gerado depois que o carregamento de um som é tentado.

LoadCompleted
Confira também
SoundPlayer
SystemSounds
Como: Reproduzir um som de um
Windows Form
Artigo • 02/06/2023
Este exemplo reproduz um som em um determinado caminho em tempo de execução.
Exemplo
C#
private void playSimpleSound()

{
SoundPlayer simpleSound = new
SoundPlayer(@"c:\Windows\Media\chimes.wav");
simpleSound.Play();
}
Se você substituir o nome "c:\Windows\Media\chimes.wav" do arquivo por um

nome de arquivo válido.
C# Uma referência ao System.Media namespace.
As operações de arquivo devem ser colocadas entre os blocos de manipulação de
exceção estruturada apropriados.
As seguintes condições podem causar uma exceção:
O nome do caminho está malformado. Por exemplo, ele contém caracteres

inválidos ou é somente um espaço em branco (classe ArgumentException).
O caminho é somente leitura ( IOException classe).
O nome do caminho é null ( ArgumentNullException classe).
O nome do caminho é muito longo ( PathTooLongException classe).

O caminho é inválido ( DirectoryNotFoundException classe).
O caminho é apenas um sinal de dois-pontos, ":" ( NotSupportedException classe).

Não tome decisões sobre o conteúdo do arquivo com base no nome do arquivo. por
exemplo, o arquivo Form1.vb pode não ser um arquivo de origem Visual Basic. Verifique
todas as entradas antes de usar os dados no seu aplicativo.
Confira também
SoundPlayer
Como: Carregar um som de forma assíncrona dentro de um Windows Form
Como: Reproduzir um aviso sonoro de
um Windows Form
Artigo • 02/06/2023
Este exemplo reproduz um bipe no tempo de execução.
Exemplo
C#
public void onePing()

{
SystemSounds.Beep.Play();
}
７ Observação
O som reproduzido no exemplo de código C# é determinado pela configuração de

som do Beep sistema. Para obter mais informações, consulte SystemSounds.
Para C#, este exemplo requer uma referência ao System.Media namespace.
Confira também
Beep
SoundPlayer
Como: Reproduzir um som do sistema de um Windows Form
Como: Reproduzir um som inserido em
um recurso de um Windows Form
Artigo • 02/06/2023
Você pode usar a SoundPlayer classe para reproduzir um som de um recurso inserido.
Exemplo
C#
private void playSoundFromResource(object sender, EventArgs e)

{
System.Reflection.Assembly a =
System.Reflection.Assembly.GetExecutingAssembly();
System.IO.Stream s = a.GetManifestResourceStream("
<AssemblyName>.chimes.wav");
SoundPlayer player = new SoundPlayer(s);
player.Play();
}
Importando o System.Media namespace.
Incluindo o arquivo de som como um recurso inserido em seu projeto.
Substituindo "<AssemblyName>" pelo nome do assembly no qual o arquivo de som

está inserido. Não inclua o sufixo ".dll".
Confira também
SoundPlayer
Como: Fazer Loop de um Som Tocado em um Formulário do Windows
Como: Reproduzir um som do sistema
de um Windows Form
Artigo • 02/06/2023
O exemplo de código a seguir reproduz o som do Exclamation sistema em tempo de

execução. Para obter mais informações sobre sons do sistema, consulte SystemSounds.
Exemplo
C#
public void playExclamation()

{
SystemSounds.Exclamation.Play();
}
Uma referência ao System.Media namespace.
Confira também
SoundPlayer
SystemSounds
Como: Reproduzir um aviso sonoro de um Windows Form
Como: Carregar um som de forma
assíncrona dentro de um Windows Form
Artigo • 02/06/2023
O exemplo de código a seguir carrega de forma assíncrona um som de uma URL e o

reproduz em um novo thread.
Exemplo
C#
using System;
using System.Media;
namespace SoundPlayerLoadAsyncExample
{
{
private SoundPlayer Player = new SoundPlayer();
public Form1()
{
this.Player.LoadCompleted += new
AsyncCompletedEventHandler(Player_LoadCompleted);
}
private void playSoundButton_Click(object sender, EventArgs e)

{
this.LoadAsyncSound();
}
public void LoadAsyncSound()

{
try
{
this.Player.SoundLocation =
"http://www.tailspintoys.com/sounds/stop.wav";
this.Player.LoadAsync();
}
{
MessageBox.Show(ex.Message, "Error loading sound");
}
}
// This is the event handler for the LoadCompleted event.

void Player_LoadCompleted(object sender, AsyncCompletedEventArgs e)
{
if (Player.IsLoadCompleted)
{
try
{
this.Player.Play();
}
{
MessageBox.Show(ex.Message, "Error playing sound");
}
}
}
private Button playSoundButton;
/// <summary>
/// </summary>
/// <summary>
/// </summary>
{
{
}
}
/// <summary>
/// </summary>
{
this.playSoundButton = new System.Windows.Forms.Button();
//
// playSoundButton
//
this.playSoundButton.Location = new System.Drawing.Point(106,
112);
this.playSoundButton.Name = "playSoundButton";
this.playSoundButton.Size = new System.Drawing.Size(75, 23);
this.playSoundButton.TabIndex = 0;
this.playSoundButton.Text = "Play Sound";
this.playSoundButton.Click += new
System.EventHandler(this.playSoundButton_Click);
//
// Form1
//
this.Controls.Add(this.playSoundButton);
}
#endregion

{
/// <summary>
/// </summary>
[STAThread]
static void Main()
{
}
}
}
Que você substitua o nome "http://www.tailspintoys.com/sounds/stop.wav" do

arquivo por um nome de arquivo válido.
As operações de arquivo devem ser colocadas em blocos de tratamento de exceção
apropriados.
O nome do caminho está malformado. Por exemplo, ele contém caracteres que
não são válidos ou são apenas espaço em branco (ArgumentException classe).
O caminho é somente leitura (IOException classe).
O nome do caminho é Nothing (ArgumentNullException classe).
O nome do caminho é muito longo (PathTooLongException classe).
O caminho não é válido (DirectoryNotFoundException classe).
O caminho é apenas dois-pontos ":" (NotSupportedException classe).

Não tome decisões sobre o conteúdo do arquivo com base no nome do arquivo. Por
exemplo, o arquivo Form1.vb pode não ser um arquivo de origem do Visual Basic.
Verifique todas as entradas antes de usar os dados no seu aplicativo.
Confira também
LoadAsync
LoadCompleted
Play
Como: Fazer Loop de um Som Tocado
em um Formulário do Windows
Artigo • 02/06/2023
O exemplo de código a seguir reproduz um som repetidamente. Quando o código no

stopPlayingButton_Click manipulador de eventos é executado, qualquer som que está
sendo reproduzido para. Se nenhum som está tocando, nada acontece.
Exemplo
C#
using System;
using System.Media;
namespace SoundPlayerPlayLoopingExample
{
{
private SoundPlayer Player = new SoundPlayer();
public Form1()
{
}
private void playLoopingButton_Click(object sender, EventArgs e)

{
try
{
// Note: You may need to change the location specified based
on
// the sounds loaded on your computer.
this.Player.SoundLocation = @"C:\Windows\Media\chimes.wav";
this.Player.PlayLooping();
}
{
MessageBox.Show(ex.Message, "Error playing sound");
}
}
private void stopPlayingButton_Click(object sender, EventArgs e)

{
this.Player.Stop();
}
/// <summary>
/// </summary>
/// <summary>
/// </summary>
{
{
}
}
/// <summary>
/// </summary>
{
this.playLoopingButton = new System.Windows.Forms.Button();
this.stopPlayingButton = new System.Windows.Forms.Button();
//
// playLoopingButton
//
this.playLoopingButton.Location = new System.Drawing.Point(12,
12);
this.playLoopingButton.Name = "playLoopingButton";
this.playLoopingButton.Size = new System.Drawing.Size(87, 23);
this.playLoopingButton.TabIndex = 0;
this.playLoopingButton.Text = "Play Looping";
this.playLoopingButton.UseVisualStyleBackColor = true;
this.playLoopingButton.Click += new
System.EventHandler(this.playLoopingButton_Click);
//
// stopPlayingButton
//
this.stopPlayingButton.Location = new System.Drawing.Point(105,
12);
this.stopPlayingButton.Name = "stopPlayingButton";
this.stopPlayingButton.Size = new System.Drawing.Size(75, 23);
this.stopPlayingButton.TabIndex = 1;
this.stopPlayingButton.Text = "Stop";
this.stopPlayingButton.UseVisualStyleBackColor = true;
this.stopPlayingButton.Click += new
System.EventHandler(this.stopPlayingButton_Click);
//
// Form1
//
this.Controls.Add(this.stopPlayingButton);
this.Controls.Add(this.playLoopingButton);
}
#endregion
private System.Windows.Forms.Button playLoopingButton;

private System.Windows.Forms.Button stopPlayingButton;
}

{
/// <summary>
/// </summary>
[STAThread]
static void Main()
{
}
}
}
Que você substitua o nome "c:\Windows\Media\chimes.wav" do arquivo por um

nome de arquivo válido.
As operações de arquivo devem ser colocadas em blocos apropriados de tratamento de
exceções.
O nome do caminho está malformado. Por exemplo, ele contém caracteres que
não são válidos ou que são apenas espaço em branco (ArgumentException classe).
O caminho é somente leitura (IOException classe).
O nome do caminho é Nothing (ArgumentNullException classe).
O nome do caminho é muito longo (PathTooLongException classe).
O caminho é inválido (DirectoryNotFoundException classe).
O caminho é apenas um dois-pontos ":" (NotSupportedException classe).

Não tome decisões sobre o conteúdo do arquivo com base no nome do arquivo. Por
exemplo, o arquivo Form1.vb pode não ser um arquivo de código-fonte do Visual Basic.
Verifique todas as entradas antes de usar os dados no seu aplicativo.
Confira também
PlayLooping
Controle SplitContainer (Windows
Forms)
Artigo • 02/06/2023
O controle SplitContainer dos Windows Forms pode ser considerado uma composição;
são dois painéis separados por uma barra móvel. Quando o ponteiro do mouse passa
sobre a barra, ele muda de forma para mostrar que a barra é móvel.
７ Observação
Na Caixa de Ferramentas, esse controle substitui o Splitter controle que estava lá

na versão anterior do Visual Studio. O SplitContainer controle é muito preferencial
sobre o Splitter controle. A Splitter classe ainda está incluída no .NET Framework
para compatibilidade com aplicativos existentes, mas incentivamos fortemente
você a usar o SplitContainer controle para novos projetos.
O controle SplitContainer permite que você crie interfaces do usuário complexas;

muitas vezes, uma seleção em um painel determina quais objetos são mostrados no
outro painel. Essa disposição é muito eficiente para exibir e procurar informações. Ter
dois painéis permite que você agregue informações em áreas e a barra, ou "splitter",
torna mais fácil para os usuários redimensionar os painéis.
Nesta seção
Visão geral do controle SplitContainer
Apresenta o controle SplitContainer e descreve as propriedades, métodos e eventos
mais usados.
Como: Definir o comportamento de redimensionamento e posicionamento em uma

janela dividida
Descreve como controlar o separador dentro do controle SplitContainer .
Como: Dividir uma janela horizontalmente

Descreve como controlar a orientação do separador dentro do controle SplitContainer .
Cria uma interface do usuário em vários painéis que é semelhante à usada no Microsoft
Outlook.
Consulte também Como dividir uma janela horizontalmente usando o Designer, Como
criar uma Interface no estilo Windows Explorer em um Windows Form, Como criar uma
Interface do usuário multipainéis com Windows Forms usando o Designer.
Referência
Classe SplitContainer
Fornece links para tópicos sobre os controles projetados especificamente para funcionar
com o Windows Forms.

Visão geral do controle SplitContainer
(Windows Forms)
Artigo • 21/06/2023
O controle SplitContainer dos Windows Forms pode ser considerado uma composição;
são dois painéis separados por uma barra móvel. Quando o ponteiro do mouse passa
sobre a barra, ele muda de forma para mostrar que a barra é móvel.
） Importante
Na Caixa de Ferramentas, SplitContainer o controle substitui o Splitter controle

que estava lá na versão anterior do Visual Studio. O SplitContainer controle é
muito preferencial sobre o Splitter controle. A Splitter classe ainda está incluída no
.NET Framework para compatibilidade com aplicativos existentes, mas incentivamos
você a usar o SplitContainer controle para novos projetos.
Com o SplitContainer controle, você pode criar interfaces de usuário complexas;

geralmente, uma seleção em um painel determina quais objetos são mostrados no
outro painel. Essa disposição é muito eficiente para exibir e procurar informações. Ter
dois painéis permite agregar as informações em áreas e a barra, ou “divisor”, tornando
mais fácil para os usuários redimensionar os painéis.
Mais de um SplitContainer controle também pode ser aninhado, com o segundo

SplitContainer controle orientado horizontalmente, para criar painéis superiores e
inferiores.
Lembre-se de que o SplitContainer controle é acessível pelo teclado por padrão; os

usuários podem pressionar as teclas ARROW para mover o divisor se a IsSplitterFixed
propriedade estiver definida false como .
A Orientation propriedade do SplitContainer controle determina a direção do divisor,

não do controle em si. Portanto, quando essa propriedade é definida como Vertical, o
divisor é executado de cima para baixo, criando painéis esquerdo e direito.
Além disso, lembre-se de que o valor da SplitterRectangle propriedade varia

dependendo do valor da Orientation propriedade. Para obter mais informações,
consulte SplitterRectangle property.
Você também pode restringir o tamanho e o movimento do SplitContainer controle. A

FixedPanel propriedade determina qual painel permanecerá do mesmo tamanho após o
SplitContainer controle ser redimensionado e a IsSplitterFixed propriedade determina se
o divisor é móvel pelo teclado ou mouse.
７ Observação
Mesmo se a IsSplitterFixed propriedade estiver definida como true , o divisor ainda

poderá ser movido programaticamente; por exemplo, usando a SplitterDistance
propriedade .
Por fim, cada painel do SplitContainer controle tem propriedades para determinar seu
tamanho individual.
Propriedades, métodos e eventos normalmente

usados
Nome Descrição
Propriedade Determina qual painel permanecerá do mesmo tamanho depois que o

FixedPanel SplitContainer controle for redimensionado.
Propriedade Determina se o divisor pode ser movido com o teclado ou mouse.

IsSplitterFixed
Propriedade Determina se o separador é disposto na vertical ou horizontal.

Orientation
Propriedade Determina a distância em pixels da borda esquerda ou superior para o

SplitterDistance divisor móvel.
Propriedade Determina a distância mínima, em pixels, que o divisor pode ser movido
SplitterIncrement pelo usuário.
Propriedade Determina a espessura, em pixels, do separador.

SplitterWidth
Evento Ocorre quando o separador está sendo movido.

SplitterMoving
Evento Ocorre quando o separador foi movido.

SplitterMoved
Confira também
SplitContainer
Exemplo do controle SplitContainer
Como: Criar uma Interface do Usuário
com Vários Painéis nos Windows Forms
Artigo • 02/06/2023
Ao organizar controles em um formulário, você pode criar uma interface de usuário de

vários painéis semelhante à usada no Microsoft Outlook, com uma lista de pastas, um
painel Mensagens e um painel De visualização. Essa organização é obtida
principalmente por meio de controles de encaixe com o formulário.
Ao encaixar um controle, você determina a qual borda do contêiner pai um controle é

fixado. Se você definir a Dock propriedade como Right, a borda direita do controle será
encaixada na borda direita de seu controle pai. Além disso, a borda encaixada do
controle será redimensionada para corresponder à borda de sua caixa de controles. Para
obter mais informações sobre como a Dock propriedade funciona, consulte How to:
Dock Controls on Windows Forms.
Este procedimento se concentra em organizar o SplitContainer e os outros controles no

formulário, não em adicionar funcionalidade para fazer o aplicativo imitar o Microsoft
Outlook.
Para criar essa interface do usuário, coloque todos os controles dentro de um

SplitContainer controle. O SplitContainer contém um TreeView controle no painel
esquerdo e outro SplitContainer no painel direito. O segundo SplitContainer contém
um ListView controle na parte superior e um RichTextBox controle na parte inferior.
Esses SplitContainer controles permitem o redimensionamento independente dos

outros controles no formulário. Você pode adaptar as técnicas neste procedimento para
criar interfaces do usuário personalizadas.
Layout de controle
A tabela a seguir descreve como os controles são configurados para imitar o Microsoft
Outlook:
Control Propriedade Valor
Splitcontainer Nome splitContainer1
Dock Fill
TabIndex 4
Splitterwidth 4
Splitterdistance 100
Panel1.Controls Adicione o treeView1 controle a este painel.
Panel2.Controls Adicione o splitContainer2 controle a este painel.
TreeView Nome treeView1
Dock Fill
TabIndex 0
Nós Adicionar um novo nó chamado Node0
Splitcontainer Nome splitContainer2
Dock Fill
TabIndex 1
Splitterwidth 4
Splitterdistance 150
Orientação Horizontal
Panel1.Controls Adicione o listView1 controle a este painel.

Panel2.Controls Adicione o richTextBox1 controle a este painel.
ListView Nome listView1
Dock Fill
TabIndex 2
Itens Adicione um novo item e defina o texto como item1 .
RichTextBox Nome richTextBox1
Dock Fill
TabIndex 3
Texto richTextBox1
Confira também
SplitContainer
Como: Criar uma interface do usuário com vários painéis com o Windows Forms
usando o designer
Como: Criar uma interface do usuário
com vários painéis com o Windows
Artigo • 02/06/2023
No procedimento a seguir, você vai criar uma interface do usuário com vários painéis
semelhante à que é usada no Microsoft Outlook, com uma lista Pasta, um painel
Mensagens e um painel Visualização. Essa organização é obtida principalmente por
meio de controles de encaixe com o formulário.
Ao encaixar um controle, você determina a qual borda do contêiner pai um controle é

fixado. Portanto, se você definir a Dock propriedade como Right, a borda direita do
controle será encaixada na borda direita de seu controle pai. Além disso, a borda
encaixada do controle será redimensionada para corresponder à borda de sua caixa de
controles. Para obter mais informações sobre como a Dock propriedade funciona,
consulte How to: Dock Controls on Windows Forms.
Este procedimento se concentra em organizar o SplitContainer e os outros controles no

formulário, não em adicionar funcionalidade para fazer o aplicativo imitar o Microsoft
Outlook.
Para criar essa interface do usuário, coloque todos os controles dentro de um

SplitContainer controle, que contém um TreeView controle no painel esquerdo. O painel
direito do SplitContainer controle contém um segundo SplitContainer controle com um
ListView controle acima de um RichTextBox controle. Esses SplitContainer controles
permitem o redimensionamento independente dos outros controles no formulário. Você
pode adaptar as técnicas neste procedimento para criar interfaces do usuário
personalizadas.
Para criar uma interface do usuário no estilo

Outlook no tempo de design
1. Criar um novo projeto de aplicativo do Windows (Arquivo>Novo>Projeto>Visual
C# ou Visual Basic>Classic Desktop>Windows Forms Aplicativo).
2. Arraste um SplitContainer controle da Caixa de Ferramentas para o formulário. Na

janela Propriedades , defina a Dock propriedade como Fill.
3. Arraste um TreeView controle da Caixa de Ferramentas para o painel esquerdo do
SplitContainer controle. Na janela Propriedades , defina a Dock propriedade
clicando no painel esquerdo no editor de valores mostrado quando a seta para
Left baixo é clicada.
4. Arraste outro SplitContainer controle da Caixa de Ferramentas; coloque-o no

painel direito do SplitContainer controle que você adicionou ao formulário. Na
janela Propriedades, defina a Dock propriedade como Fill .OrientationHorizontal
5. Arraste um ListView controle da Caixa de Ferramentas para o painel superior do

segundo SplitContainer controle que você adicionou ao formulário. Defina a Dock
propriedade do ListView controle como Fill.
6. Arraste um RichTextBox controle da Caixa de Ferramentas para o painel inferior do

segundo SplitContainer controle. Defina a Dock propriedade do RichTextBox
controle como Fill.
Neste ponto, se você pressionar F5 para executar o aplicativo, o formulário exibirá

uma interface do usuário de três partes, semelhante àquela do Microsoft Outlook.
７ Observação
Quando você coloca o ponteiro do mouse sobre qualquer um dos divisores

dentro dos SplitContainer controles, você pode redimensionar as dimensões
internas.
Neste ponto no desenvolvimento de aplicativos, você criou uma interface do usuário

sofisticada. A próxima etapa é prosseguir com a programação do próprio aplicativo,
talvez conectando o controle e ListView os TreeView controles a algum tipo de fonte de
dados. Para obter mais informações sobre como conectar controles a dados, consulte
Vinculação de dados e Windows Forms.
Confira também
SplitContainer
Como: Criar uma interface no estilo do
Windows Explorer em Windows Forms
Artigo • 02/06/2023
O Windows Explorer é uma opção de interface do usuário comum para aplicativos

devido à sua familiaridade pronta.
O Windows Explorer é, essencialmente, um TreeView controle e um ListView controle em

painéis separados. Os painéis são redimensionáveis por um divisor. Essa disposição de
controles é muito eficiente para exibir e procurar informações.
As etapas a seguir mostram como organizar controles em um formato semelhante ao

Windows Explorer. Elas não mostram como adicionar a funcionalidade de localização de
arquivos do aplicativo Windows Explorer.
Para criar um Windows Form no estilo do

Windows Explorer
1. Criar um novo projeto de aplicativo do Windows (Arquivo>Novo>Projeto>Visual
C# ou Visual Basic>Classic Desktop>Windows Forms Aplicativo).
2. Na Caixa de Ferramentas:
a. Arraste um SplitContainer controle para o formulário.
b. Arraste um TreeView controle para SplitterPanel1 (o painel do SplitContainer

controle marcado como Painel1).
c. Arraste um ListView controle para SplitterPanel2 (o painel do SplitContainer

controle marcado como Painel2).
3. Selecione os três controles pressionando a tecla CTRL e clicando neles. Ao

selecionar o SplitContainer controle, clique na barra de divisores, em vez dos
painéis.
７ Observação
Não use o comando Selecionar Tudo no menu Editar. Se você fizer isso, a
propriedade necessária na próxima etapa não aparecerá na janela
Propriedades.
4. Na janela Propriedades , defina a Dock propriedade como Fill.
5. Pressione F5 para executar o aplicativo.
O formulário exibe uma interface do usuário de duas partes, semelhante à do

Windows Explorer.
７ Observação
Quando você arrasta o divisor, os painéis são redimensionados.
Confira também
SplitContainer
Como: Definir o comportamento de redimensionamento e posicionamento em
uma janela dividida
Como: Dividir uma janela horizontalmente
Como: Definir o comportamento de
redimensionamento e posicionamento
em uma janela dividida
Artigo • 21/06/2023
Os painéis do SplitContainer controle se prestam bem a serem redimensionados e

manipulados pelos usuários. No entanto, há momentos em que é útil controlar o divisor
com programação, onde ele está posicionado e em que grau pode ser movido.
A SplitterIncrement propriedade e as outras propriedades no SplitContainer controle

fornecem controle preciso sobre o comportamento da interface do usuário para atender
às suas necessidades. Tais propriedades são listadas na tabela a seguir.
Nome Descrição
Propriedade Determina se o divisor pode ser movido com o teclado ou mouse.

IsSplitterFixed
Propriedade Determina a distância em pixels da borda esquerda ou superior para o

SplitterDistance divisor móvel.
Propriedade Determina a distância mínima, em pixels, que o divisor pode ser

SplitterIncrement movido pelo usuário.
O exemplo a seguir modifica a SplitterIncrement propriedade para criar um efeito

"divisor de encaixe"; quando o usuário arrasta o divisor, ele incrementa em unidades de
10 pixels em vez do padrão 1.
Definir o comportamento de redimensionamento do

SplitContainer
1. Em um procedimento, defina a SplitterIncrement propriedade como o tamanho
desejado, para que o comportamento de "encaixe" do divisor seja alcançado.
No exemplo de código a seguir, dentro do evento do Load formulário, o divisor

dentro do SplitContainer controle é definido para saltar 10 pixels quando
arrastado.
C#

{
SplitContainer splitSnapper = new SplitContainer();
splitSnapper.SplitterIncrement = 10;
splitSnapper.Dock = DockStyle.Fill;
splitSnapper.Parent = this;
}

C#
this.Load += new System.EventHandler(this.Form1_Load);
Mover o divisor ligeiramente para a esquerda ou direita não terá nenhum efeito;
no entanto, quando o ponteiro do mouse se move em 10 pixels em qualquer
direção, o divisor se ajustará à nova posição.
Confira também
SplitContainer
SplitterIncrement
Como: Dividir uma janela
horizontalmente
Artigo • 02/06/2023
O exemplo de código a seguir torna o divisor que divide o SplitContainer controle

horizontalmente.
７ Observação
A Orientation propriedade do SplitContainer controle determina a direção do

divisor, não do controle em si.
Para dividir uma janela horizontalmente

1. Dentro de um procedimento, defina a Orientation propriedade do SplitContainer
controle como Horizontal.
C#
public void showSplitContainer()

{
SplitContainer splitContainer1 = new SplitContainer ();
splitContainer1.BorderStyle = BorderStyle.Fixed3D;
splitContainer1.Location = new System.Drawing.Point (74, 20);
splitContainer1.Name = "DemoSplitContainer";
splitContainer1.Size = new System.Drawing.Size (212, 435);
splitContainer1.TabIndex = 0;
this.Controls.Add (splitContainer1);
Confira também
SplitContainer
Como: Dividir uma janela
horizontalmente o designer
Artigo • 02/06/2023
Este exemplo faz com que o divisor que divide o SplitContainer controle horizontal.
７ Observação
A Orientation propriedade do SplitContainer controle determina a direção do

divisor, não do controle em si.
Para dividir uma janela horizontalmente

Na janela Propriedades , defina a Orientation propriedade do SplitContainer controle
como Horizontal.
Confira também
SplitContainer
Controle de separador (Windows Forms)
Artigo • 02/06/2023
Splitter Windows Forms controles são usados para redimensionar controles

encaixados em tempo de execução. O Splitter controle geralmente é usado em
formulários com controles que têm diferentes comprimentos de dados para apresentar,
como o Windows Explorer, cujos painéis de dados contêm informações de larguras
variadas em momentos diferentes.
７ Observação
Embora SplitContainer substitua e adicione funcionalidade ao controle Splitter

de versões anteriores, Splitter é mantido para compatibilidade com versões
anteriores e uso futuro, se desejado.
Nesta seção
Visão geral do controle Divisor
Referência
Classe Splitter
Visão geral do controle divisor
(Windows Forms)
Artigo • 02/06/2023
） Importante
Embora SplitContainer substitua e adicione funcionalidade ao controle Splitter de

versões anteriores, Splitter é mantido para compatibilidade com versões anteriores
e uso futuro, se desejado.
Splitter Windows Forms controles são usados para redimensionar controles encaixados
em tempo de execução. O Splitter controle geralmente é usado em formulários com
controles que têm diferentes comprimentos de dados para apresentar, como o
Windows Explorer, cujos painéis de dados contêm informações de larguras variadas em
momentos diferentes.
Trabalhando com o controle Splitter

Quando o usuário aponta o ponteiro do mouse na borda não encaixada de um controle
que pode ser redimensionado por um controle splitter, o ponteiro muda de aparência
para indicar que o controle pode ser redimensionado. Com o controle Splitter, o usuário
pode redimensionar o controle encaixado que esteja imediatamente antes dele.
Portanto, para permitir que o usuário redimensione um controle encaixado em tempo
de execução, encaixe o controle a ser redimensionado em uma borda de um contêiner
e, em seguida, encaixe um controle Splitter no mesmo lado do contêiner.
Confira também
SplitContainer
Controle StatusBar (Windows Forms)
Artigo • 02/06/2023
７ Observação
O controle ToolStripStatusLabel substitui e adiciona funcionalidade ao controle

StatusBar, no entanto, o controle StatusBar é mantido para compatibilidade com
versões anteriores e para uso futuro, se desejado.
O controle Windows Forms StatusBar é usado em formulários como uma área,

geralmente exibido na parte inferior de uma janela, na qual um aplicativo pode exibir
vários tipos de informações de status. StatusBar os controles podem ter painéis de barra
de status neles que exibem ícones para indicar o estado ou uma série de ícones em uma
animação que indicam que um processo está funcionando; por exemplo, Microsoft
Word indicando que o documento está sendo salvo.
Nesta seção
Visão geral do controle StatusBar
Apresenta os conceitos gerais do controle, que StatusBar permite que os usuários vejam
informações relevantes para o controle que tem foco.
Como: Adicionar painéis a um controle StatusBar

Explica como adicionar painéis programáveis ao StatusBar controle.
Como: Determinar qual painel no controle StatusBar do Windows Forms foi clicado
Explica como lidar com Click eventos gerados do StatusBar controle.
Como: Definir o tamanho de painéis da barra de status

Fornece detalhes sobre as propriedades que controlam a largura e redimensionam o
comportamento dos painéis da barra de status em tempo de execução.
Passo a passo: Atualizando informações da barra de status em tempo de execução

Explica como controlar programaticamente os dados dentro de painéis da barra de
status.
Referência
StatusBar
ToolStripStatusLabel
Substitui e adiciona funcionalidade ao StatusBar controle.
(Windows Forms)
Artigo • 02/06/2023
） Importante

O Controle StatusBar dos Windows Forms é usado em formulários como uma área,
normalmente exibido na parte inferior de uma janela, na qual um aplicativo pode exibir
diversos tipos de informações de status. StatusBar os controles podem ter painéis de
barras de status neles que exibem texto ou ícones para indicar o estado ou uma série de
ícones em uma animação que indicam que um processo está funcionando; por exemplo,
Microsoft Word indicando que o documento está sendo salvo.
Usando o controle StatusBar

O Internet Explorer usa uma barra de status para indicar a URL de uma página quando o
mouse rola sobre o hiperlink; O Microsoft Word fornece informações sobre o local da
página, o local da seção e os modos de edição, como controle de supertipo e revisão; e
o Visual Studio usa a barra de status para fornecer informações confidenciais de
contexto, como dizer como manipular janelas encaixadas como encaixadas ou
flutuantes.
Você pode exibir uma única mensagem na barra de status definindo a ShowPanels
propriedade como false (o padrão) e definindo a Text propriedade da barra de status
como o texto que você deseja exibir na barra de status. Você pode dividir a barra de
status em painéis para exibir mais de um tipo de informação definindo a ShowPanels
propriedade true como e usando o Add método de StatusBar.StatusBarPanelCollection.
Confira também
StatusBar
Como: Adicionar painéis a um controle
StatusBar
Artigo • 02/06/2023
） Importante

A área programável dentro de um controle de controle StatusBar consiste em instâncias

da StatusBarPanel classe. Eles são adicionados por meio de adições à
StatusBar.StatusBarPanelCollection classe.
Para adicionar painéis a uma barra de status

1. Em um procedimento, crie painéis de barra de status adicionando-os ao
StatusBar.StatusBarPanelCollection. Especifique as configurações de propriedade
para painéis individuais usando seu índice passado pela Panels propriedade.
No exemplo de código a seguir, o caminho definido para o local do ícone é a

pasta Meus Documentos. Esse local é usado porque você pode supor que a
mínimos de acesso ao sistema executem com mais segurança o aplicativo. O
exemplo a seguir requer um formulário com um StatusBar controle já adicionado.
７ Observação
É StatusBar.StatusBarPanelCollection uma coleção baseada em zero,

portanto, o código deve continuar de acordo.
C#
public void CreateStatusBarPanels()

{
// Create panels and set text property.
statusBar1.Panels.Add("One");
statusBar1.Panels.Add("Two");
statusBar1.Panels.Add("Three");
// Set properties of StatusBar panels.
// Set AutoSize property of panels.
statusBar1.Panels[0].AutoSize = StatusBarPanelAutoSize.Spring;
statusBar1.Panels[1].AutoSize = StatusBarPanelAutoSize.Contents;
statusBar1.Panels[2].AutoSize = StatusBarPanelAutoSize.Contents;
// Set BorderStyle property of panels.
statusBar1.Panels[0].BorderStyle =
StatusBarPanelBorderStyle.Raised;
statusBar1.Panels[1].BorderStyle = StatusBarPanelBorderStyle.Sunken;
statusBar1.Panels[2].BorderStyle = StatusBarPanelBorderStyle.Raised;
// Set Icon property of third panel. You should replace the bolded
// icon in the sample below with an icon of your own choosing.
statusBar1.Panels[2].Icon =
new System.Drawing.Icon (System.Environment.GetFolderPath _
+ @"\Icon.ico");
statusBar1.ShowPanels = true;
}
Confira também
StatusBar
Caixa de diálogo Editor de Coleção
Como: Determinar qual painel no
controle StatusBar do Windows Forms
foi clicado
Artigo • 21/06/2023
） Importante
Os StatusStrip controles e ToolStripStatusLabel substituem e adicionam

funcionalidade aos StatusBar controles e StatusBarPanel ; no entanto, os StatusBar
controles e StatusBarPanel são mantidos para compatibilidade com versões
Para programar o controle StatusBar Control para responder a cliques do usuário, use
uma instrução case dentro do PanelClick evento. O evento contém um argumento (o
argumento panel), que contém uma referência ao clicado StatusBarPanel. Usando essa
referência, determine o índice do painel clicado e programe adequadamente.
７ Observação
Verifique se a StatusBar propriedade do ShowPanels controle está definida

true como .
Para determinar qual painel foi clicado

1. PanelClick No manipulador de eventos, use uma Select Case instrução (no Visual
Basic) ou switch case (Visual C# ou Visual C++) para determinar qual painel foi
clicado examinando o índice do painel clicado nos argumentos do evento.
O exemplo de código a seguir requer a presença, no formulário, de um StatusBar

controle, StatusBar1 e dois StatusBarPanel objetos, StatusBarPanel1 e
StatusBarPanel2 .
C#
private void statusBar1_PanelClick(object sender,

System.Windows.Forms.StatusBarPanelClickEventArgs e)
{
switch (statusBar1.Panels.IndexOf(e.StatusBarPanel))
{
case 0 :
MessageBox.Show("You have clicked Panel One.");
break;
case 1 :
MessageBox.Show("You have clicked Panel Two.");
break;
}
}

C#
this.statusBar1.PanelClick += new
System.Windows.Forms.StatusBarPanelClickEventHandler
(this.statusBar1_PanelClick);
Confira também
StatusBar
Como: Definir o tamanho de painéis da
barra de status
Artigo • 02/06/2023
７ Observação
O controle ToolStripStatusLabel substitui e adiciona funcionalidade ao controle

StatusBar, no entanto, o controle StatusBar é mantido para compatibilidade com
versões anteriores e para uso futuro, se desejado.
Cada instância da StatusBarPanel classe dentro de um controle de controle StatusBar

tem várias propriedades dinâmicas que determinam sua largura e redimensionam o
comportamento em tempo de execução.
Para definir o tamanho de um painel

1. Em um procedimento, defina as AutoSizeMinWidthpropriedades e Width
propriedades (ou qualquer subconjunto) para os painéis da barra de status usando
seu índice passado pela Panels propriedade da StatusBarPanel coleção.
C#
public void SetStatusBarPanelSize()

{
// Create panel and set text property.
statusBar1.Panels.Add("One");
// Set properties of panels.
statusBar1.Panels[0].AutoSize = StatusBarPanelAutoSize.Spring;
statusBar1.Panels[0].Width = 200;
statusBar1.ShowPanels = true;
}
Confira também
StatusBar
Passo a passo: Atualizando informações
da barra de status em tempo de
execução
Artigo • 02/06/2023
） Importante

Geralmente, um programa solicitará que você atualize o conteúdo dos painéis da barra
de status dinamicamente no tempo de execução, dependendo das alterações de estado
do aplicativo ou outra interação do usuário. Essa é uma maneira comum de indicar aos
usuários que teclas como CAPS LOCK, NUM LOCK ou SCROLL LOCK estão habilitadas ou
de fornecer uma data ou um relógio como uma referência conveniente.
No exemplo a seguir, você usará uma instância da StatusBarPanel classe para hospedar
um relógio.
Preparar a barra de status para atualização

1. Crie um novo formulário do Windows.
2. Adicione um controle StatusBar ao seu formulário. Para ver mais detalhes, consulte
Como adicionar controles ao Windows Forms.
3. Adicione um painel de barras de status ao seu StatusBar controle. Para ver mais
detalhes, consulte Como adicionar painéis a um controle StatusBar.
4. Para o StatusBar controle que você adicionou ao formulário, defina a ShowPanels

propriedade como true .
5. Adicione um componente Windows Forms Timer ao formulário.
７ Observação
O componente Windows Forms System.Windows.Forms.Timer foi projetado
para um ambiente de Windows Forms. Se você precisar de um temporizador
que seja adequado para um ambiente de servidor, consulte Introdução a
temporizadores baseados em servidor.
6. Defina a propriedade Enabled como true .
7. Defina a Interval propriedade de Timer 30000.
７ Observação
A Interval propriedade do Timer componente é definida como 30 segundos

(30.000 milissegundos) para garantir que um tempo preciso seja refletido no
tempo exibido.
Implementar o temporizador para atualizar a barra de

status
1. Insira o código a seguir no manipulador de eventos do Timer componente para
atualizar o painel do StatusBar controle.
C#
private void timer1_Tick(object sender, System.EventArgs e)

{
statusBar1.Panels[0].Text = DateTime.Now.ToShortTimeString();
}
Neste ponto, você está pronto para executar o aplicativo e observar o relógio em
execução no painel da barra de status.
Para testar o aplicativo

1. Depure o aplicativo e pressione F5 para executá-lo. Para ver mais detalhes sobre
depuração, consulte Depuração no Visual Studio.
７ Observação
Levará cerca de 30 segundos para o relógio aparecer na barra de status. Isso

serve para obter a hora mais precisa possível. Por outro lado, para fazer o
relógio aparecer mais cedo, você pode reduzir o valor da Interval propriedade
definida na etapa 7 no procedimento anterior.
Confira também
StatusBar
Como: Adicionar painéis a um controle StatusBar
Artigo • 02/06/2023
O controle Windows Forms StatusStrip é usado em formulários como uma área,

geralmente exibido na parte inferior de uma janela, na qual um aplicativo pode exibir
vários tipos de informações de status. StatusStrip os controles normalmente têm
ToolStripStatusLabel controles neles que exibem texto ou ícones para indicar o estado
ou um ToolStripProgressBar que exibe graficamente o estado de conclusão de um

processo.
Nesta seção
Visão geral do controle StatusStrip
Como: Usar a propriedade Spring de forma interativa em um StatusStrip

Demonstra o uso da Spring propriedade para centralizar interativamente um
ToolStripStatusLabel em um StatusStrip .
Consulte também o Editor de Coleção de Itens statusStrip e a caixa de diálogo Tarefas

statusStrip.
Referência
StatusStrip
Confira também
Visão geral do controle StatusStrip
Artigo • 02/06/2023
Um StatusStrip controle exibe informações sobre um objeto que está sendo exibido em
um Formcomponente do objeto ou informações contextuais relacionadas à operação
desse objeto em seu aplicativo. Normalmente, um controle consiste em
ToolStripStatusLabel objetos, cada um StatusStrip deles exibe texto, um ícone ou ambos.
O StatusStrip também pode conter ToolStripDropDownButton, ToolStripSplitButtone
ToolStripProgressBar controles.
O padrão StatusStrip não tem painéis. Para adicionar painéis a um StatusStrip, use o
ToolStripItemCollection.AddRange método.
Há um amplo suporte para manipulação de StatusStrip itens e comandos comuns no

Visual Studio.
Consulte também o Editor de Coleção de Itens statusStrip e a caixa de diálogo Tarefas

statusStrip.
Embora o StatusStrip substitua e estenda o controle StatusBar de versões anteriores,

StatusBar é mantido para compatibilidade com versões anteriores e uso futuro, se
desejado.
Membros StatusStrip importantes
Nome Descrição
CanOverflow Obtém ou define um valor que indica se o StatusStrip dá suporte à funcionalidade

de estouro.
Stretch Obtém ou define um valor que indica se o StatusStrip trecho se estende de ponta
a ponta em seu ToolStripContainer.
Classes complementares importantes do StatusStrip
Nome Descrição
ToolStripStatusLabel Representa um painel em um controle StatusStrip.
ToolStripDropDownButton Exibe um associado ToolStripDropDown do qual o usuário pode

selecionar um único item.
Nome Descrição
ToolStripSplitButton Representa um controle de duas partes que é um botão padrão e

um menu suspenso.
ToolStripProgressBar Exibe o estado de conclusão de um processo.
Confira também
StatusStrip
Spring
Como: Usar a propriedade Spring de
forma interativa em um StatusStrip
Artigo • 21/06/2023
Você pode usar a Spring propriedade para posicionar um ToolStripStatusLabel controle

em um StatusStrip controle . A Spring propriedade determina se o ToolStripStatusLabel
controle preenche automaticamente o espaço disponível no StatusStrip controle.
Exemplo
O exemplo de código a seguir demonstra como usar a Spring propriedade para
posicionar um ToolStripStatusLabel controle em um StatusStrip controle . O Click
manipulador de eventos executa uma operação exclusiva ou (XOR) para alternar o valor
da Spring propriedade.
Para usar esse exemplo de código, compile e execute o aplicativo e clique em Meio
(Spring) no StatusStrip controle para alternar o valor da Spring propriedade.
C#
using System;
C#
// This code example demonstrates using the Spring property

// to interactively center a ToolStripStatusLabel in a StatusStrip.
class Form4 : Form
{
// Declare the ToolStripStatusLabel.
ToolStripStatusLabel middleLabel;
public Form4()
{
// Create a new StatusStrip control.
StatusStrip ss = new StatusStrip();
// Add the leftmost label.

ss.Items.Add("Left");
// Handle middle label separately -- action will occur

// when the label is clicked.
middleLabel = new ToolStripStatusLabel("Middle (Spring)");
middleLabel.Click += new EventHandler(middleLabel_Click);
ss.Items.Add(middleLabel);
// Add the rightmost label

ss.Items.Add("Right");
// Add the StatusStrip control to the controls collection.

this.Controls.Add(ss);
}
// This event hadler is invoked when the

// middleLabel control is clicked. It toggles
// the value of the Spring property.
void middleLabel_Click(object sender, EventArgs e)
{
// Toggle the value of the Spring property.
middleLabel.Spring ^= true;
// Set the Text property according to the

// value of the Spring property.
middleLabel.Text =
middleLabel.Spring ? "Middle (Spring - True)" : "Middle (Spring
- False)";
}
}

Confira também
StatusStrip
ToolStrip
ToolStripItem
ToolStripMenuItem
Controle ToolStrip
Controle TabControl (Windows Forms)
Artigo • 02/06/2023
O Windows Forms TabControl exibe várias guias, como divisores em um bloco de

anotações ou rótulos em um conjunto de pastas em um gabinete de arquivamento. As
guias podem conter imagens e outros controles. Use as TabControl páginas de
propriedade para criar.
Nesta seção
Visão geral do controle TabControl
Como: Adicionar um controle a uma página da guia

Fornece instruções para exibir controles em páginas de guia.
Como: Adicionar e remover guias com o controle TabControl do Windows Forms

Fornece instruções para adicionar e remover guias no designer ou no código.
Como: Alterar a aparência do TabControl do Windows Forms

Fornece instruções para ajustar propriedades que afetam a aparência de guias
individuais.
Como: Desabilitar páginas de guia

Explica como restringir o acesso a uma página de guia, possivelmente com base nas
credenciais do usuário.
Veja também como adicionar e remover guias com o Windows Forms TabControl
usando o designer, como adicionar um controle a uma página tab usando o designer
Referência
Classe TabControl
Fornece uma lista de tarefas para caixas de diálogo, que geralmente exibem guias.
(Windows Forms)
Artigo • 21/06/2023
O Windows Forms TabControl exibe várias guias, como divisores em um bloco de

anotações ou rótulos em um conjunto de pastas em um gabinete de arquivamento. As
guias podem conter imagens e outros controles. Você pode usar o controle guia para
produzir o tipo de caixa de diálogo de várias páginas que aparece em muitos locais no
sistema operacional Windows, como o Painel de Controle Propriedades de Exibição.
Além disso, o TabControl pode ser usado para criar páginas de propriedades, que são
usadas para definir um grupo de propriedades relacionadas.
Trabalhando com TabControl

A propriedade mais importante do TabControl é TabPages, que contém as guias
individuais. Cada guia individual é um TabPage objeto . Quando uma guia é clicada, ela
aciona o Click evento para esse TabPage objeto.
Confira também
TabControl
Controle TabControl
Como: Adicionar um controle a uma
página da guia
Artigo • 02/06/2023
Você pode usar o Windows Forms TabControl para exibir outros controles de forma
organizada. O procedimento a seguir mostra como adicionar um botão à primeira guia.
Para obter informações sobre como adicionar um ícone à parte de rótulo de uma página
de guia, consulte Como alterar a aparência do Windows Forms TabControl.
Para adicionar um controle programaticamente

1. Use o Add método da coleção retornado pela Controls propriedade de TabPage:
C#
tabPage1.Controls.Add(new Button());
Confira também
Controle TabControl
Como: Adicionar um controle a uma
página de guia usando o Designer
Artigo • 02/06/2023
O uso da Windows Forms TabControl é exibir outros controles de forma organizada.

Você pode usar essas instruções para exibir uma imagem na parte principal de uma
página da guia. Para obter informações sobre como adicionar um ícone à parte do
rótulo de uma página da guia, veja Como alterar a aparência do TabControl dos
Windows Forms.

formulário que contém um TabControl controle. Para obter informações sobre como
Para adicionar um controle usando o designer

1. Clique na página da guia apropriada para que ele apareça na parte superior.
2. Desenhe o controle na página da guia.
Confira também
Controle TabControl
Como: Adicionar e remover guias com o
controle TabControl do Windows Forms
Artigo • 02/06/2023
Por padrão, um controle TabControl contém dois controles TabPage . Você pode acessar
essas guias por meio da TabPages propriedade .
Para adicionar uma guia programaticamente

Use o Add método da TabPages propriedade .
C#
string title = "TabPage " + (tabControl1.TabCount + 1).ToString();

TabPage myTabPage = new TabPage(title);
tabControl1.TabPages.Add(myTabPage);
Para remover uma guia programaticamente

Para remover as guias selecionadas, use o Remove método da TabPages
propriedade .
-ou-
Para remover todas as guias, use o Clear método da TabPages propriedade .
C#
// Removes the selected tab:

tabControl1.TabPages.Remove(tabControl1.SelectedTab);
// Removes all the tabs:
tabControl1.TabPages.Clear();
Confira também
Como: Adicionar e remover guias com o
TabControl do Windows Forms usando
o designer
Artigo • 02/06/2023
Quando você coloca um TabControl controle em seu formulário, ele contém duas guias
por padrão. Você pode adicionar ou remover guias usando o designer.
O procedimento a seguir requer um projeto Windows Application com um formulário

que contém um TabControl controle. Para obter informações sobre como configurar
esse projeto, consulte Como criar um projeto de aplicativo Windows Forms e como
adicionar controles a Windows Forms.
Para adicionar ou remover uma guia usando o

designer
Na marca inteligente do controle, clique em Adicionar Guia ou Remover Guia
-ou-
Na janela Propriedades , clique no botão Reticências ( ) ao lado da TabPages

propriedade para abrir o Editor de Coleção TabPage. Clique no botão Adicionar
ou Remover .
Confira também
Controle TabControl
Como: Alterar a aparência do
TabControl do Windows Forms
Artigo • 02/06/2023
Você pode alterar a aparência das guias em Windows Forms usando propriedades
TabControl do e dos TabPage objetos que compõem as guias individuais no controle. Ao
configurar essas propriedades, é possível exibir imagens em guias, exibir guias
verticalmente em vez de horizontalmente, exibir várias linhas de guias e habilitar ou
desabilitar guias com programação.
Exibir um ícone na parte de rótulo de uma guia

1. Adicione um ImageList controle ao formulário.
2. Adicione imagens à lista de imagens.
Para obter mais informações sobre listas de imagens, consulte Componente

ImageList e Como adicionar ou remover imagens com o componente ImageList
dos Windows Forms.
3. Defina a ImageList propriedade do TabControl controle ImageList .
4. Defina a ImageIndex propriedade do TabPage índice de uma imagem apropriada

na lista.
Criar várias linhas de guias

1. Adicione o número de páginas de guia desejado.
2. Defina a Multiline propriedade como TabControl true .
3. Se as guias ainda não aparecerem em várias linhas, defina a Width propriedade

como TabControl mais estreita do que todas as guias.
Organizar as guias na lateral do controle

Defina a Alignment propriedade do TabControl para Left ou Right.
Habilitar ou desabilitar todos os controles em uma guia

usando programação
1. Defina a Enabled propriedade do TabPage para true ou false .
C#
tabPage1.Enabled = false;
Exibir guias como botões

Defina a Appearance propriedade do TabControl para Buttons ou FlatButtons.
Confira também
Controle TabControl
Artigo • 21/06/2023
Em algumas ocasiões, pode ser útil restringir o acesso aos dados que estão disponíveis
no seu Aplicativo do Windows Forms. Um exemplo disso seria quando você tem dados
exibidos nas páginas da guia de um controle guia. Os administradores poderiam ter
informações em uma página da guia que você gostaria de proibir para convidados ou
usuários de nível inferior.
Desabilitar páginas de guia com programação

1. Escreva o código para manipular o evento do controle guia SelectedIndexChanged
. Esse é o evento que é gerado quando o usuário alterna de uma guia para a
próxima.
2. Verifique as credenciais. Dependendo das informações apresentadas, pode ser útil

verificar o nome de usuário com que o usuário fez logon ou alguma outra
credencial antes de permitir que o usuário exiba a guia.
3. Se o usuário tiver as credenciais apropriadas, exiba a guia que foi clicada. Se o

usuário não tiver as credenciais apropriadas, exibirá uma caixa de mensagem ou
alguma outra interface do usuário indicando que eles não têm acesso e retorne à
guia inicial.
７ Observação
Ao implementar essa funcionalidade em seus aplicativos de produção, você

pode executar essa credencial marcar durante o evento do Load formulário.
Isso permitirá que você oculte a guia antes de exibir qualquer interface do
usuário, que é uma abordagem muito mais simples do que programação. A
metodologia usada abaixo (verificando credenciais e desabilitando a guia
durante o SelectedIndexChanged evento) é para fins ilustrativos.
4. Opcionalmente, se você tiver mais de duas páginas da guia, exiba uma página da
guia diferente da original.
No exemplo abaixo, um CheckBox controle é usado em vez de verificar as

credenciais, pois os critérios de acesso à guia variam de acordo com o aplicativo.
Quando o SelectedIndexChanged evento é gerado, se a credencial marcar for
verdadeira (ou seja, a caixa marcar será marcada) e a guia selecionada for
TabPage2 (a guia com as informações confidenciais, neste exemplo), será TabPage2
exibida. Caso contrário, TabPage3 será exibido e uma caixa de mensagem será
exibida para o usuário, indicando que ele não tem os privilégios de acesso
apropriados. O código a seguir pressupõe um formulário com um CheckBox
controle ( CredentialCheck ) e um TabControl controle com três páginas guias.
C#
private void tabControl1_SelectedIndexChanged(object sender,

System.EventArgs e)
{
// Check Credentials Here
if ((CredentialCheck.Checked == true) && (tabControl1.SelectedTab

== tabPage2))
{
tabControl1.SelectedTab = tabPage2;
}
else if ((CredentialCheck.Checked == false) &&
(tabControl1.SelectedTab == tabPage2))
{
MessageBox.Show("Unable to load tab. You have insufficient
access privileges.");
tabControl1.SelectedTab = tabPage3;
}
}

C#
this.tabControl1.SelectedIndexChanged +=
new System.EventHandler(this.tabControl1_SelectedIndexChanged);
Confira também
Como: Exibir guias alinhadas
lateralmente com TabControl
Artigo • 21/06/2023
A Alignment propriedade de TabControl dá suporte à exibição de guias verticalmente

(ao longo da borda esquerda ou direita do controle), em vez de horizontalmente (na
parte superior ou inferior do controle). Por padrão, essa exibição vertical resulta em uma
experiência de usuário ruim, pois a Text propriedade do TabPage objeto não é exibida
na guia quando os estilos visuais estão habilitados. Também não há nenhuma maneira
direta de controlar a direção do texto dentro da guia. Você pode usar o desenho do
TabControl proprietário para melhorar essa experiência.
O procedimento a seguir mostra como renderizar guias alinhadas à direita, com o texto
da guia indo da esquerda para a direita, usando o recurso de “desenho do proprietário”.
Exibir guias alinhadas à direita

1. Adicione um TabControl ao formulário.
2. Defina a propriedade Alignment como Right.
3. Defina a SizeMode propriedade como , para Fixedque todas as guias sejam da

mesma largura.
4. Defina a ItemSize propriedade como o tamanho fixo preferido para as guias. Tenha
em mente que a ItemSize propriedade se comporta como se as guias estivessem
na parte superior, embora estejam alinhadas à direita. Como resultado, para
aumentar as guias, você deve alterar a Height propriedade e, para torná-las mais
altas, você deve alterar a Width propriedade.
Para obter o melhor resultado com o exemplo de código abaixo, defina o Width
das guias como 25 e o Height como 100.
5. Defina a propriedade DrawMode como OwnerDrawFixed.
6. Defina um manipulador para o DrawItem evento de TabControl que renderiza o

texto da esquerda para a direita.
C#
public Form1()
{
// Remove this call if you do not program using Visual Studio.
tabControl1.DrawItem += new
DrawItemEventHandler(tabControl1_DrawItem);
}
private void tabControl1_DrawItem(Object sender,

System.Windows.Forms.DrawItemEventArgs e)
{
Graphics g = e.Graphics;
Brush _textBrush;
// Get the item from the collection.

TabPage _tabPage = tabControl1.TabPages[e.Index];
// Get the real bounds for the tab rectangle.

Rectangle _tabBounds = tabControl1.GetTabRect(e.Index);
if (e.State == DrawItemState.Selected)
{
// Draw a different background color, and don't paint a focus

rectangle.
_textBrush = new SolidBrush(Color.Red);
g.FillRectangle(Brushes.Gray, e.Bounds);
}
else
{
_textBrush = new System.Drawing.SolidBrush(e.ForeColor);
e.DrawBackground();
}
// Use our own font.

Font _tabFont = new Font("Arial", 10.0f, FontStyle.Bold,
GraphicsUnit.Pixel);
// Draw string. Center the text.

StringFormat _stringFlags = new StringFormat();
_stringFlags.Alignment = StringAlignment.Center;
_stringFlags.LineAlignment = StringAlignment.Center;
g.DrawString(_tabPage.Text, _tabFont, _textBrush, _tabBounds, new
StringFormat(_stringFlags));
}
Confira também
Controle TabControl
Controle TableLayoutPanel (Windows
Forms)
Artigo • 02/06/2023
O TableLayoutPanel controle organiza seu conteúdo em uma grade. Como o layout é

executado tanto em tempo de design quanto em tempo de execução, ele pode ser
alterado dinamicamente à medida que o ambiente do aplicativo muda. Assim, os
controles no painel têm a capacidade de redimensionar proporcionalmente, portanto
ele pode responder a alterações como o redimensionamento do controle pai ou à
alteração de comprimento do texto devido à localização.
Nesta seção
Visão geral do controle TableLayoutPanel
Apresenta os conceitos gerais do controle, que TableLayoutPanel permite criar um
layout com linhas e colunas.
Práticas recomendadas para o controle TableLayoutPanel

Descreve as recomendações para ajudá-lo a aproveitar ao máximo os recursos de layout
do TableLayoutPanel controle.
Comportamento de AutoSize no controle TableLayoutPanel

Explica as maneiras pelas quais o controle dá suporte ao TableLayoutPanel
comportamento de dimensionamento automático.

Mostra como ancorar e encaixar controles filho em um TableLayoutPanel controle.
Como criar um layout dos Windows Forms que responda bem à localização
Demonstra o uso de um TableLayoutPanel controle para criar um formulário que
responde bem à localização.
Como criar um Windows Form redimensionável para entrada de dados

Demonstra o uso de um TableLayoutPanel controle para criar um formulário que
responde bem ao redimensionamento.
1. Como alinhar e alongar um controle em um controle TableLayoutPanel
2. Como abranger linhas e colunas em um controle TableLayoutPanel
3. Como editar colunas e linhas em um controle TableLayoutPanel

4. Passo a passo: organizando controles nos Windows Forms usando um
TableLayoutPanel
Referência
TableLayoutPanel
Fornece a documentação de referência para o TableLayoutPanel controle.
TableLayoutSettings
Fornece a documentação de referência para o TableLayoutSettings tipo.
FlowLayoutPanel
Fornece a documentação de referência para o FlowLayoutPanel controle.
Localização
Fornece uma visão geral dos tópicos relacionados à localização.
Veja também a Localização de Aplicativos.

TableLayoutPanel
Artigo • 02/06/2023
O TableLayoutPanel controle organiza seu conteúdo em uma grade. Como o layout é

executado tanto em tempo de design quanto em tempo de execução, ele pode ser
alterado dinamicamente à medida que o ambiente do aplicativo muda. Assim, os
controles no painel têm a capacidade de redimensionar proporcionalmente, portanto
ele pode responder a alterações como o redimensionamento do controle pai ou à
alteração de comprimento do texto devido à localização.
Qualquer controle Windows Forms pode ser um filho do TableLayoutPanel controle,

incluindo outras instâncias de TableLayoutPanel. Isso permite criar layouts sofisticados
que se adaptam às alterações no tempo de execução.
O TableLayoutPanel controle pode ser expandido para acomodar novos controles

quando eles são adicionados, dependendo do valor do , ColumnCounte GrowStyle das
RowCountpropriedades. Definir a propriedade ou ColumnCount a RowCount
propriedade como um valor de 0 especifica que ela TableLayoutPanel será desvinculada
na direção correspondente.
Você também pode controlar a direção da expansão (horizontal ou vertical) depois que
o TableLayoutPanel controle estiver cheio de controles filho. Por padrão, o
TableLayoutPanel controle se expande para baixo adicionando linhas.
Se você quiser linhas e colunas que se comportem de forma diferente do

comportamento padrão, você poderá controlar as propriedades de linhas e colunas
usando as propriedades e ColumnStyles as RowStyles propriedades. É possível definir as
propriedades de linhas ou colunas individualmente.
O TableLayoutPanel controle adiciona as seguintes propriedades aos controles filho:

Cell , Column , , Row e RowSpan ColumnSpan .
Você pode mesclar células no TableLayoutPanel controle definindo as propriedades ou

RowSpan propriedades ColumnSpan em um controle filho.

TableLayoutPanel
Confira também
FlowLayoutPanel
TableLayoutSettings
Como criar um Windows Form redimensionável para entrada de dados
Comportamento de AutoSize no
controle TableLayoutPanel
Artigo • 02/06/2023
Comportamentos distintos de AutoSize

O TableLayoutPanel controle dá suporte ao comportamento de dimensionamento
automático das seguintes maneiras:
Por meio da AutoSize propriedade;
Por meio da SizeType propriedade nos TableLayoutPanel estilos de coluna e linha

do controle.
A propriedade AutoSize com estilos de coluna e linha

A tabela a seguir descreve a interação entre a AutoSize propriedade e os
TableLayoutPanel estilos de coluna e linha do controle.
Configuração Interação de estilo

de AutoSize
false O TableLayoutPanel controle prossegue da esquerda para a direita e aloca

espaço para a coluna ou linha ou na ordem a seguir.
1. Se a SizeType propriedade estiver definida como Absolute, o número de pixels

especificados ou WidthHeight alocados.
2. Se a SizeType propriedade estiver definida como AutoSize, o número de pixels
retornados pelo método do GetPreferredSize controle filho será alocado.
3. Depois que o espaço para todas Absolute e AutoSize colunas ou linhas é
alocado, todas as colunas ou linhas com SizeType conjunto a Percent serem
usadas para alocar proporcionalmente o espaço livre restante
true Semelhante à interação anterior, com a exceção de que Percent colunas ou

linhas adquirem um aspecto de dimensionamento automático.
O TableLayoutPanel controle expande a coluna ou a linha para criar espaço livre

adequado, de modo que nenhuma coluna ou linha com Percent estilo corta seu
conteúdo. O TableLayoutPanel controle aloca o novo espaço proporcionalmente
de acordo com a propriedade ou Height a Width propriedade.
Confira também
TableLayoutPanel
Visão geral do controle TableLayoutPanel
Práticas recomendadas para o controle
TableLayoutPanel
Artigo • 02/06/2023
O TableLayoutPanel controle fornece recursos de layout avançados que você deve

considerar cuidadosamente antes de usar em seu Windows Forms.
Recomendações
As recomendações a seguir ajudarão você a usar o TableLayoutPanel controle para sua
melhor vantagem.
Uso direcionado
Use o TableLayoutPanel controle com moderação. Você não deve usá-lo em todas as
situações que exigem um layout redimensionável. A lista a seguir descreve layouts que
mais se beneficiam do uso do TableLayoutPanel controle:
Layouts em que há várias partes do formulário redimensionadas

proporcionalmente umas para outras.
Layouts que serão modificados ou gerados dinamicamente no tempo de execução,

como formulários de entrada de dados que têm campos personalizáveis pelo
usuário adicionados ou subtraídos com base nas preferências.
Layouts que devem permanecer em um tamanho fixo geral. Por exemplo, você
pode ter uma caixa de diálogo que deve permanecer menor do que 800 x 600,
mas você precisa dar suporte a cadeias de caracteres localizadas.
A lista a seguir descreve layouts que não se beneficiam muito do uso do

TableLayoutPanel controle:
Formulários de entrada de dados simples com uma única coluna de rótulos e uma
única coluna de áreas de entrada de texto.
Formulários com uma única área de exibição grande que deve preencher o espaço
disponível quando ocorre um redimensionamento. Um exemplo disso é um
formulário que exibe um único PropertyGrid controle. Nesse caso, use ancoragem,
pois nada mais deve expandir quando o formulário é redimensionado.
Escolha cuidadosamente quais controles precisam estar em um TableLayoutPanel
controle. Se você tiver espaço para seu texto crescer 30% usando ancoragem, considere
usar apenas a Anchor propriedade. Se você puder estimar o espaço exigido pelo layout,
use Dock e Anchor seja mais fácil do que estimar os detalhes do espaço e AutoSize do
comportamento restantes.
Em geral, ao projetar seu layout com o TableLayoutPanel controle, mantenha o design o

mais simples possível.
Usar a janela Estrutura de Tópicos de Documento

A janela Estrutura de Tópicos de Documento fornece um modo de exibição de árvore do
layout, que pode ser usada para manipular as relações pai-filho e de ordem z dos
controles. No menu Exibir, selecione Outras Janelas e escolha Estrutura de Tópicos de
Documento.
Evitar aninhamento
Evite aninhar outros TableLayoutPanel controles dentro de um TableLayoutPanel
controle. Pode ser difícil depurar layouts aninhados.
Evitar herança visual

O TableLayoutPanel controle não dá suporte à herança visual no Designer de Windows
Forms no Visual Studio. Um TableLayoutPanel controle em uma classe derivada aparece
como "bloqueado" no momento do design.
Confira também
TableLayoutPanel
FlowLayoutPanel
Como: Alinhar e alongar um controle
em um controle TableLayoutPanel
Artigo • 02/06/2023
Você pode alinhar e alongar controles em um TableLayoutPanel com as propriedades

eDock.Anchor
Alinhar e esticar um controle

1. No Visual Studio, arraste um TableLayoutPanel controle da Caixa de Ferramentas
para o formulário.
2. Arraste um Button controle da Caixa de Ferramentas para a célula superior

esquerda do TableLayoutPanel controle. O Button controle é centralizado na célula.
3. Defina o valor da Button propriedade do Anchor controle como Left,Right . O

Button controle se estende para corresponder à largura da célula.
4. Defina o valor da Button propriedade do Anchor controle como Top,Bottom . O

Button controle se estende para corresponder à altura da célula.
5. Defina o valor da Button propriedade do Dock controle como Fill. O Button

controle se expande para preencher a célula.
6. Defina o valor da Button propriedade do Dock controle como None. O Button

controle retorna ao seu tamanho original e se move para o canto superior
esquerdo da célula. O designer de Windows Forms definiu a Anchor propriedade
como Top, Left .
7. Defina o valor da Button propriedade do Anchor controle como Bottom,Right . O

Button controle se move para o canto inferior direito da célula.
8. Defina o valor da Button propriedade do Anchor controle como None. O Button

controle se move para o centro da célula.
Confira também
Como ancorar e encaixar controles filho
em um controle TableLayoutPanel
Artigo • 02/06/2023
O TableLayoutPanel controle dá suporte às propriedades e Dock aos Anchor controles

filho.
Alinhar um controle filho a uma célula TableLayoutPanel

1. Crie um TableLayoutPanel controle em seu formulário.
2. Defina o valor das TableLayoutPanel propriedades e RowCount do ColumnCount

controle como 1.
3. Crie um Button controle no TableLayoutPanel controle. O Button ocupa o canto

superior esquerdo da célula.
4. Altere o valor da propriedade Button do controle Anchor para Left . O Button

controle se move para alinhar com a borda esquerda da célula.
７ Observação
Esse comportamento difere do comportamento de outras caixas de controles.

Em outros controles de contêiner, o controle filho não se move quando a
Anchor propriedade é definida e a distância entre o controle ancorado e o
limite do contêiner pai é fixada no momento em que a Anchor propriedade é
definida.
5. Altere o valor da propriedade Button do controle Anchor para Top, Left . O Button
controle se move para ocupar o canto superior esquerdo da célula.
6. Repita a etapa 5 com um valor de Top, Right mover o Button controle para o
canto superior direito da célula. Repita com valores de Bottom, Left e Bottom,
Right .
Alongar um controle filho em uma célula

TableLayoutPanel
1. Altere o valor da propriedade Button do controle Anchor para Left, Right . O
Button controle é redimensionado para se estender pela célula.
７ Observação
Esse comportamento difere do comportamento de outras caixas de controles.

Em outros controles de contêiner, o controle filho não é redimensionado
quando a Anchor propriedade é definida Left, Right como ou Top, Bottom .
2. Altere o valor da propriedade Button do controle Anchor para Top, Bottom . O

Button controle é redimensionado para alongar da parte superior até a parte
inferior da célula.
3. Altere o valor da propriedade Button do controle Anchor para Top, Bottom, Left,
Right . O Button controle é redimensionado para preencher a célula.
4. Altere o valor da propriedade Button do controle Anchor para None . O Button

controle é redimensionado e centralizado na célula.
5. Altere o valor da propriedade Button do controle Dock para Left. O Button

controle se move para alinhar com a borda esquerda da célula. O Button controle
mantém sua largura, mas sua altura é redimensionada para preencher a célula
verticalmente.
７ Observação
Esse é o mesmo comportamento que ocorre em outras caixas de controle.
6. Altere o valor da propriedade Button do controle Dock para Fill. O Button controle
é redimensionado para preencher a célula.
Exemplo
A ilustração a seguir mostra cinco botões ancorados em cinco células separadas
TableLayoutPanel .
A ilustração a seguir mostra quatro botões ancorados nos cantos de quatro células
separadas TableLayoutPanel .
A ilustração a seguir mostra três botões estendidos por ancoragem em três células
separadas TableLayoutPanel .
O exemplo de código a seguir demonstra todas as combinações de valores de Anchor

propriedade para um Button controle em um TableLayoutPanel controle.
C#
using System;
using System.Data;

{
public Form1()
{
}
private System.Windows.Forms.TableLayoutPanel tableLayoutPanel1;

private System.Windows.Forms.Button button1;

{
{
}
}

{
this.tableLayoutPanel1 = new
System.Windows.Forms.TableLayoutPanel();
this.tableLayoutPanel1.SuspendLayout();
//
// tableLayoutPanel1
//
this.tableLayoutPanel1.Anchor = ((System.Windows.Forms.AnchorStyles)
this.tableLayoutPanel1.CellBorderStyle =
System.Windows.Forms.TableLayoutPanelCellBorderStyle.Single;
this.tableLayoutPanel1.ColumnCount = 5;
this.tableLayoutPanel1.ColumnStyles.Add(new
System.Windows.Forms.ColumnStyle(System.Windows.Forms.SizeType.Percent,
20F));
20F));
20F));
20F));
20F));
this.tableLayoutPanel1.Controls.Add(this.button1, 0, 0);
this.tableLayoutPanel1.Location = new System.Drawing.Point(12, 12);
this.tableLayoutPanel1.Name = "tableLayoutPanel1";
this.tableLayoutPanel1.RowCount = 1;
this.tableLayoutPanel1.RowStyles.Add(new
System.Windows.Forms.RowStyle(System.Windows.Forms.SizeType.Percent, 50F));
this.tableLayoutPanel1.Size = new System.Drawing.Size(731, 100);
this.tableLayoutPanel1.TabIndex = 0;
//
// button1
//
this.button1.Anchor = System.Windows.Forms.AnchorStyles.None;
this.button1.Text = "Anchor=None";
//
// button2
//
this.button2.Anchor = System.Windows.Forms.AnchorStyles.Left;
this.button2.Text = "Anchor=Left";
//
// button3
//
this.button3.Anchor = System.Windows.Forms.AnchorStyles.Top;
this.button3.Text = "Anchor=Top";
//
// button4
//
this.button4.Anchor = System.Windows.Forms.AnchorStyles.Right;
this.button4.Text = "Anchor=Right";
//
// button5
//
this.button5.Anchor = System.Windows.Forms.AnchorStyles.Bottom;
this.button5.Text = "Anchor=Bottom";
//
//
25F));
25F));
25F));
25F));
//
// button6
//
this.button6.Text = "Top, Left";
//
// button7
//
this.button7.Text = "Top, Right";
//
// button8
//
((System.Windows.Forms.AnchorStyles.Bottom |
this.button8.Text = "Bottom, Right";
//
// button9
//
System.Windows.Forms.AnchorStyles.Left)));
this.button9.Text = "Bottom, Left";
//
//
33.33333F));
33.33333F));
33.33333F));
//
// button10
//
this.button10.Text = "Left, Right";
//
// button11
//
System.Windows.Forms.AnchorStyles.Bottom)));
this.button11.Text = "Top, Bottom";
//
// button12
//
this.button12.Text = "Top, Bottom, Left, Right";
//
// Form1
//
this.Controls.Add(this.tableLayoutPanel3);
this.tableLayoutPanel1.ResumeLayout(false);
this.tableLayoutPanel1.PerformLayout();
}
[STAThread]
static void Main()
{
}
}
Confira também
TableLayoutPanel
Como criar um Windows Form
redimensionável para entrada de dados
Artigo • 02/06/2023
Um bom layout responde bem a alterações nas dimensões de seu formulário pai. Você
pode usar o TableLayoutPanel controle para organizar o layout do formulário para
redimensionar e posicionar seus controles de forma consistente à medida que as
dimensões do formulário mudam. O TableLayoutPanel controle também é útil quando
alterações no conteúdo de seus controles causam alterações no layout. O processo
abordado neste procedimento pode ser realizado no ambiente do Visual Studio.
Consulte também Instruções passo a passo: criando um Windows Form redimensionável
para entrada de dados.
Exemplo
O exemplo a seguir demonstra como usar um TableLayoutPanel controle para criar um
layout que responde bem quando o usuário redimensiona o formulário. Ele também
demonstra um layout que responde bem à localização.
C#
using System;
using System.Data;
using System.Text;
// This form demonstrates how to build a form layout that adjusts well
// when the user resizes the form. It also demonstrates a layout that
// responds well to localization.
class BasicDataEntryForm : System.Windows.Forms.Form
{
public BasicDataEntryForm()
{
}

{
{
}
}
public override string ToString()

{
return "Basic Data Entry Form";
}
private void okBtn_Click(object sender, EventArgs e)

{
this.Close();
}

{
this.Close();
}

{
this.maskedTextBox1 = new System.Windows.Forms.MaskedTextBox();
this.maskedTextBox2 = new System.Windows.Forms.MaskedTextBox();
this.comboBox1 = new System.Windows.Forms.ComboBox();
this.richTextBox1 = new System.Windows.Forms.RichTextBox();
this.cancelBtn = new System.Windows.Forms.Button();
this.okBtn = new System.Windows.Forms.Button();
//
//
System.Windows.Forms.ColumnStyle());
50F));
50F));
this.tableLayoutPanel1.Controls.Add(this.label1, 0, 0);
this.tableLayoutPanel1.Controls.Add(this.textBox2, 1, 1);
this.tableLayoutPanel1.Controls.Add(this.maskedTextBox1, 1, 4);
this.tableLayoutPanel1.Controls.Add(this.maskedTextBox2, 3, 4);
this.tableLayoutPanel1.Controls.Add(this.comboBox1, 3, 3);
this.tableLayoutPanel1.Controls.Add(this.richTextBox1, 1, 5);
System.Windows.Forms.RowStyle(System.Windows.Forms.SizeType.Absolute, 28F));
//
// label1
//
this.label1.Anchor = System.Windows.Forms.AnchorStyles.Right;
this.label1.Text = "First Name";
//
// label2
//
this.label2.Text = "Last Name";
//
// label3
//
this.label3.Text = "Address1";
//
// label4
//
this.label4.Text = "Address 2";
//
// label5
//
this.label5.Text = "City";
//
// label6
//
this.label6.Text = "State";
//
// label9
//
this.label9.Text = "Phone (H)";
//
// textBox2
//
this.textBox2.Anchor = ((System.Windows.Forms.AnchorStyles)
this.tableLayoutPanel1.SetColumnSpan(this.textBox2, 3);
//
// textBox3
//
this.tableLayoutPanel1.SetColumnSpan(this.textBox3, 3);
//
// textBox4
//
//
// textBox5
//
//
// maskedTextBox1
//
this.maskedTextBox1.Anchor = System.Windows.Forms.AnchorStyles.Left;
this.maskedTextBox1.Location = new System.Drawing.Point(68, 116);
this.maskedTextBox1.Mask = "(999)000-0000";
this.maskedTextBox1.Name = "maskedTextBox1";
this.maskedTextBox1.TabIndex = 6;
//
// maskedTextBox2
//
this.maskedTextBox2.Anchor = System.Windows.Forms.AnchorStyles.Left;
this.maskedTextBox2.Location = new System.Drawing.Point(388, 116);
this.maskedTextBox2.Mask = "(999)000-0000";
this.maskedTextBox2.Name = "maskedTextBox2";
this.maskedTextBox2.TabIndex = 7;
//
// comboBox1
//
this.comboBox1.Anchor = System.Windows.Forms.AnchorStyles.Left;
this.comboBox1.FormattingEnabled = true;
this.comboBox1.Items.AddRange(new object[] {
"AK - Alaska",
"WA - Washington"});
this.comboBox1.Location = new System.Drawing.Point(388, 87);
this.comboBox1.Name = "comboBox1";
this.comboBox1.Size = new System.Drawing.Size(100, 21);
this.comboBox1.TabIndex = 5;
//
// textBox1
//
//
// label7
//
this.label7.Anchor = ((System.Windows.Forms.AnchorStyles)
this.label7.Text = "Notes";
//
// label8
//
this.label8.Text = "Phone (W)";
//
// richTextBox1
//
this.tableLayoutPanel1.SetColumnSpan(this.richTextBox1, 3);
this.richTextBox1.Dock = System.Windows.Forms.DockStyle.Fill;
this.richTextBox1.Location = new System.Drawing.Point(68, 143);
this.richTextBox1.Name = "richTextBox1";
this.richTextBox1.Size = new System.Drawing.Size(552, 140);
this.richTextBox1.TabIndex = 8;
this.richTextBox1.Text = "";
//
// cancelBtn
//
this.cancelBtn.Anchor = ((System.Windows.Forms.AnchorStyles)
this.cancelBtn.DialogResult =
System.Windows.Forms.DialogResult.Cancel;
this.cancelBtn.Location = new System.Drawing.Point(558, 306);
this.cancelBtn.Name = "cancelBtn";
this.cancelBtn.TabIndex = 1;
this.cancelBtn.Text = "Cancel";
this.cancelBtn.Click += new
System.EventHandler(this.cancelBtn_Click);
//
// okBtn
//
this.okBtn.Anchor = ((System.Windows.Forms.AnchorStyles)
this.okBtn.DialogResult = System.Windows.Forms.DialogResult.OK;
this.okBtn.Location = new System.Drawing.Point(476, 306);
this.okBtn.Name = "okBtn";
this.okBtn.TabIndex = 0;
this.okBtn.Text = "OK";
this.okBtn.Click += new System.EventHandler(this.okBtn_Click);
//
// BasicDataEntryForm
//
this.Controls.Add(this.okBtn);
this.Controls.Add(this.cancelBtn);
this.Name = "BasicDataEntryForm";
this.Padding = new System.Windows.Forms.Padding(9);
this.StartPosition = System.Windows.Forms.FormStartPosition.Manual;
this.Text = "Basic Data Entry";
}

private System.Windows.Forms.Label label1;
private System.Windows.Forms.Button cancelBtn;
private System.Windows.Forms.Button okBtn;
private System.Windows.Forms.TextBox textBox1;
private System.Windows.Forms.MaskedTextBox maskedTextBox1;
private System.Windows.Forms.MaskedTextBox maskedTextBox2;
private System.Windows.Forms.ComboBox comboBox1;
private System.Windows.Forms.RichTextBox richTextBox1;
[STAThread]
static void Main()
{
Application.Run(new BasicDataEntryForm());
}
}

Confira também
FlowLayoutPanel
TableLayoutPanel
Como criar um layout dos Windows
Forms que responda bem à localização
Artigo • 02/06/2023
Criar formulários prontos para serem localizados acelera muito o desenvolvimento para
os mercados internacionais. Você pode usar o TableLayoutPanel controle para
implementar layouts que respondem normalmente como controles redimensionam
devido a alterações em seus Text valores de propriedade.
Exemplo
Esse formulário demonstra como criar um layout que se ajusta proporcionalmente
quando você converte valores de cadeia de caracteres exibidos em outras linguagens.
Esse processo de tradução é chamado de localização. Para obter mais informações,
confira Localização.
Há um suporte abrangente para esta tarefa no Visual Studio. Veja também passo a
passo: criando um layout que ajusta a proporção para localização.
C#
using System;
using System.Data;
using System.Text;
namespace TableLayoutPanelSample
{
public class LocalizableForm : Form
{
private System.Windows.Forms.ListView listView1;
private System.Windows.Forms.Panel panel1;

public LocalizableForm()
{
}
private void AddText(object sender, EventArgs e)

{
((Button)sender).Text += "x";
}

{
{
}
}

{
System.Windows.Forms.ListViewGroup listViewGroup16 = new
System.Windows.Forms.ListViewGroup("First Group",
System.Windows.Forms.HorizontalAlignment.Left);
System.Windows.Forms.ListViewGroup("Second Group",
System.Windows.Forms.ListViewGroup("Third Group",
System.Windows.Forms.ListViewItem listViewItem26 = new
System.Windows.Forms.ListViewItem("Item 1");
this.listView1 = new System.Windows.Forms.ListView();
this.panel1 = new System.Windows.Forms.Panel();
this.panel1.SuspendLayout();
//
//
100F));
this.tableLayoutPanel1.Controls.Add(this.listView1, 1, 0);
this.tableLayoutPanel1.Controls.Add(this.panel1, 0, 0);
this.tableLayoutPanel1.Location = new System.Drawing.Point(2,
52);
//
// listView1
//
this.listView1.Dock = System.Windows.Forms.DockStyle.Fill;
listViewGroup16.Header = "First Group";
listViewGroup16.Name = null;
listViewGroup17.Header = "Second Group";
listViewGroup18.Header = "Third Group";
this.listView1.Groups.AddRange(new
System.Windows.Forms.ListViewGroup[] {
listViewGroup16,
listViewGroup17,
listViewGroup18});
//this.listView1.IsBackgroundImageTiled = false;
listViewItem26.Group = listViewGroup16;
this.listView1.Items.AddRange(new
System.Windows.Forms.ListViewItem[] {
listViewItem26,
listViewItem27,
listViewItem28,
listViewItem29,
listViewItem30});
this.listView1.Location = new System.Drawing.Point(90, 3);
this.listView1.Name = "listView1";
this.listView1.Size = new System.Drawing.Size(431, 264);
this.listView1.TabIndex = 1;
//
// panel1
//
this.panel1.Anchor = System.Windows.Forms.AnchorStyles.Top;
this.panel1.AutoSize = true;
this.panel1.AutoSizeMode =
System.Windows.Forms.AutoSizeMode.GrowAndShrink;
this.panel1.Controls.Add(this.button3);
this.panel1.Location = new System.Drawing.Point(3, 3);
this.panel1.Name = "panel1";
this.panel1.Size = new System.Drawing.Size(81, 86);
this.panel1.TabIndex = 2;
//
// button3
//
this.button3.Text = "Add Text";
this.button3.Click += new System.EventHandler(this.AddText);
//
// button2
//
//
// button1
//
//
//
this.tableLayoutPanel2.Anchor =
((System.Windows.Forms.AnchorStyles)
this.tableLayoutPanel2.AutoSize = true;
33.33333F));
33.33333F));
33.33333F));
328);
System.Windows.Forms.RowStyle());
//
// button4
//
//
// button5
//
//
// button6
//
//
// label1
//
this.label1.Text = "Click on any button to add text to the
button. This simulates localizing strings," +
" and provides a good demonstration of how the dialog will
automatically adjust w" +
"hen those longer strings are added to the UI.";
//
// LocalizableForm
//
this.FormBorderStyle =
System.Windows.Forms.FormBorderStyle.FixedSingle;
this.Name = "LocalizableForm";
this.Text = "Localizable Dialog";
this.panel1.ResumeLayout(false);
this.panel1.PerformLayout();
}
[STAThread]
static void Main()
{
Application.Run(new LocalizableForm());
}
}
}
Recursos adicionais
2. Passo a passo: Organizando controles nos Windows Forms utilizando um
FlowLayoutPanel
5. Passo a passo: executar tarefas comuns usando ações de designer

TableLayoutPanel
7. Passo a passo: Definir o layout de controles do Windows Forms com

8. Como dar suporte à localização nos Windows Forms usando AutoSize e o controle
TableLayoutPanel
9. Passo a passo: criando um Windows Form redimensionável para entrada de dados

Confira também
TableLayoutPanel
FlowLayoutPanel
Localização
Como: Editar colunas e linhas em um
Artigo • 27/09/2022
Você pode usar o editor de coleção do TableLayoutPanel controle, chamado de coluna e

caixa de diálogo estilos de linha, para editar as linhas e colunas de seus controles.
７ Observação
Se você quiser que um controle ocupe várias linhas ou colunas, defina as

propriedades RowSpan e ColumnSpan do controle. Para obter mais informações,
consulte Passo a passo: organizando controles nos Windows Forms usando um
TableLayoutPanel.
Se você quiser alinhar um controle dentro de uma célula ou se desejar que um

controle seja ampliado dentro de uma célula, use a propriedade do Anchor
controle. Para obter mais informações, consulte Passo a passo: organizando
controles nos Windows Forms usando um TableLayoutPanel.
Editar linhas e colunas

1. Arraste um TableLayoutPanel controle da caixa de ferramentas para seu
formulário.
2. Clique no TableLayoutPanel glifo ações do designer do controle ( ) e selecione

Editar linhas e colunas para abrir a caixa de diálogo estilos de coluna e linha .
Você também pode clicar com o TableLayoutPanel botão direito do mouse no
controle e selecionar Editar linhas e colunas no menu de atalho.
3. Para adicionar ou remover colunas, selecione Colunas da caixa de listagem

suspensa Tipo de membro.
4. Para adicionar ou remover linhas, selecione Linhas da caixa de listagem suspensa

Tipo de membro.
5. Clique no botão Adicionar para adicionar uma linha ou coluna ao final da linha
Membro.
6. Clique no botão Inserir para adicionar uma linha ou coluna antes do item
atualmente selecionado na lista.
7. Se você estiver adicionando uma linha ou coluna, selecione o Tipo de tamanho
para a nova linha ou coluna. Para obter mais informações, consulte SizeType.
8. Para remover uma linha ou coluna, clique no botão Remover para excluir o item
selecionado no momento na lista Membro.
Confira também
SizeType
Como: Abranger linhas e colunas em um
Artigo • 02/06/2023
Controles em um TableLayoutPanel controle podem abranger linhas e colunas

adjacentes.
Para abranger colunas e linhas

2. Arraste um Button controle da Caixa de Ferramentas para a célula superior

esquerda do TableLayoutPanel controle.
3. Defina a Button propriedade ColumnSpan do controle como 2. Observe que o

Button controle abrange a primeira e a segunda colunas.
4. Defina a Button propriedade RowSpan do controle como 2. Observe que o Button

controle abrange a primeira e a segunda linhas.
5. Defina a Button propriedade ColumnSpan do controle como 1. Observe que o

Button controle se move para a primeira coluna e abrange a primeira e a segunda
linhas.
Confira também
Passo a passo: Organizar controles nos
Windows Forms usando um
TableLayoutPanel
Artigo • 02/06/2023
Alguns aplicativos exigem um formulário com um layout que se organiza

adequadamente à medida que o formulário é redimensionado ou conforme o tamanho
do conteúdo é alterado. Quando você precisar de um layout dinâmico e não quiser lidar
com Layout eventos explicitamente em seu código, considere usar um painel de layout.
O FlowLayoutPanel controle e o TableLayoutPanel controle fornecem maneiras intuitivas

de organizar controles em seu formulário. Ambos fornecem uma capacidade automática
e configurável de controlar as posições relativas dos controles filho contidos neles e
ambos oferecem recursos de layout dinâmico em tempo de execução, para que eles
possam redimensionar e reposicionar os controles filho conforme as dimensões do
formulário pai se alteram. Os painéis de layout podem ser aninhados em painéis de
layout, para permitir a realização de interfaces do usuário sofisticadas.
O FlowLayoutPanel organiza seu conteúdo em uma direção de fluxo específica:

horizontal ou vertical. Seu conteúdo pode ser encapsulado de uma linha à outra ou de
uma coluna à próxima. Como alternativa, seu conteúdo pode ser recortado, em vez de
encapsulado. Para obter mais informações, consulte Passo a passo: organizando
controles nos Windows Forms usando um FlowLayoutPanel.
O TableLayoutPanel organiza seu conteúdo em uma grade, fornecendo funcionalidade

semelhante ao elemento de tabela> HTML<. O TableLayoutPanel controle permite que
você coloque controles em um layout de grade sem exigir que você especifique com
precisão a posição de cada controle individual. Suas células são organizadas em linhas e
colunas, que podem ter diferentes tamanhos. As células podem ser mescladas entre
linhas e colunas. As células podem conter qualquer coisa que um formulário pode
conter e se comportam, na maioria de outros aspectos, como contêineres.
O TableLayoutPanel controle também fornece uma funcionalidade de

redimensionamento proporcional em tempo de execução, para que seu layout possa
mudar sem problemas à medida que o formulário for redimensionado. Isso torna o
TableLayoutPanel controle adequado para fins como formulários de entrada de dados e
aplicativos localizados. Para obter mais informações, consulte Passo a passo: criando um
Windows Form redimensionável para entrada de dados e Passo a passo: criando um
Windows Form localizável.
Em geral, você não deve usar um TableLayoutPanel controle como um contêiner para
todo o layout. Use TableLayoutPanel controles para fornecer recursos de
redimensionamento proporcional para partes do layout.
Criação de um projeto dos Windows Forms
Organização de controles em linhas e colunas
Configuração de propriedades de linha e coluna
Extensão de linhas e colunas com um controle
Manipulação automática de estouros
Inserindo controles ao clicar duas vezes neles na caixa de ferramentas
Inserindo um controle ao desenhar seu contorno
Reatribuição de controles existentes a um pai diferente
Ao terminar, você terá um entendimento da função desempenhada por esses

importantes recursos de layout.
Criando o Projeto
A primeira etapa é criar o projeto e configurar o formulário.
Para criar o projeto
1. Crie um projeto de aplicativo do Windows chamado "TableLayoutPanelExample".

Para obter mais informações, consulte Como criar um projeto de aplicativo
Windows Forms.
2. Selecione o formulário no Designer de Formuláriosdo Windows.
Organização de controles em linhas e colunas

O TableLayoutPanel controle permite organizar controles facilmente em linhas e colunas.
Para organizar controles em linhas e colunas utilizando um

TableLayoutPanel
Observe que, por padrão, o TableLayoutPanel controle tem quatro células.
2. Arraste um Button controle da Caixa de Ferramentas para o controle e solte-o

TableLayoutPanel em uma das células. Observe que o Button controle é criado
dentro da célula selecionada.
3. Arraste mais Button três controles da Caixa de Ferramentas para o

TableLayoutPanel controle, para que cada célula contenha um botão.
4. Pegue na alça de dimensionamento vertical entre as duas colunas e mova-a para a

esquerda. Observe que os Button controles na primeira coluna são
redimensionados para uma largura menor, enquanto o Button tamanho dos
controles na segunda coluna não é alterado.
5. Pegue na alça de dimensionamento vertical entre as duas colunas e mova-a para a

direita. Observe que os Button controles na primeira coluna retornam ao seu
tamanho original, enquanto os Button controles na segunda coluna são movidos
para a direita.
6. Mova a alça de dimensionamento horizontal para cima e para baixo para ver o
efeito sobre os controles no painel.
Posicionando controles dentro de células

usando o encaixe e a ancoragem
O comportamento de ancoragem dos controles filho em um TableLayoutPanel difere do
comportamento em outros controles de contêiner. O comportamento de ancoragem de
controles filho é igual a outras caixas de controles.
Posicionando controles em células

1. Selecione o primeiro Button controle. Altere o valor de sua Dock propriedade para
Fill. Observe que o Button controle se expande para preencher sua célula.
2. Selecione um dos outros Button controles. Altere o valor de sua Anchor

propriedade para Right. Observe que ele é movido para que sua borda direita
fique próxima à borda direita da célula. A distância entre as bordas é a soma da
Button propriedade do Margin controle e da propriedade do Padding painel.
3. Altere o valor da Button propriedade do Anchor controle para Right e Left.

Observe que o controle é dimensionado para a largura da célula, com os valores e
Padding os Margin valores levados em conta.
4. Repita as etapas 2 e 3 com o estilo eBottom.Top
Configuração de propriedades de linha e

coluna
Você pode definir propriedades individuais de linhas e colunas usando as coleções e
ColumnStyles as RowStyles linhas.
Para definir as propriedades de linha e coluna
1. Selecione o TableLayoutPanel controle no Designer Windows Forms.
2. Nas janelas Propriedades , abra a ColumnStyles coleção clicando no botão

reticências ( ) ao lado da entrada Colunas .
3. Selecione a primeira coluna e altere o valor de sua SizeType propriedade para

AutoSize. Clique em OK para aceitar a alteração. Observe que a largura da primeira
coluna é reduzida para se ajustar ao Button controle. Observe também que a
largura da coluna não é redimensionável.
4. Na janela Propriedades , abra a ColumnStyles coleção e selecione a primeira

coluna. Altere o valor de sua SizeType propriedade para Percent. Clique em OK
para aceitar a alteração. Redimensione o TableLayoutPanel controle para uma
largura maior e observe que a largura da primeira coluna se expande.
Redimensione o TableLayoutPanel controle para uma largura menor e observe que
os botões na primeira coluna são dimensionados para se ajustarem à célula.
Observe também que a largura da coluna é redimensionável.
5. Na janela Propriedades , abra a ColumnStyles coleção e selecione todas as colunas

listadas. Defina o valor de cada SizeType propriedade como Percent. Clique em OK
para aceitar a alteração. Repita com a RowStyles coleção.
6. Pegue uma das alças de redimensionamento de canto e redimensione a largura e a

altura do TableLayoutPanel controle. Observe que as linhas e colunas são
redimensionadas conforme o TableLayoutPanel tamanho do controle muda.
Observe também que as linhas e colunas são redimensionáveis com as alças de
dimensionamento horizontal e vertical.
Extensão de linhas e colunas com um controle

O TableLayoutPanel controle adiciona várias novas propriedades aos controles em
tempo de design. Duas dessas propriedades são a RowSpan e ColumnSpan . Você pode
usar essas propriedades para fazer um controle estender-se por mais de uma linha ou
coluna.
Para estender linhas e colunas com um controle
1. Selecione o Button controle na primeira linha e na primeira coluna.
2. Na janela Propriedades, altere o valor da propriedade ColumnSpan para 2. Observe

que o Button controle preenche a primeira coluna e a segunda coluna. Observe
também que uma linha extra foi adicionada para acomodar essa alteração.
3. Repita a etapa 2 para a propriedade RowSpan .
Inserindo controles ao clicar duas vezes neles

na caixa de ferramentas
Você pode preencher seu TableLayoutPanel controle clicando duas vezes em controles
na Caixa de Ferramentas.
Para inserir controles clicando duas vezes na caixa de ferramentas


que um novo controle de botão aparece na TableLayoutPanel primeira célula do
controle.
3. Clique duas vezes em vários outros controles na Caixa de ferramentas. Observe

que os novos controles aparecem sucessivamente nas TableLayoutPanel células
desocupadas do controle. Observe também que o TableLayoutPanel controle se
expande para acomodar os novos controles se nenhuma célula aberta estiver
disponível.
Manipulação automática de estouros

Ao inserir controles no TableLayoutPanel controle, você pode ficar sem células vazias
para seus novos controles. O TableLayoutPanel controle lida com essa situação
automaticamente aumentando o número de células.
Observar a manipulação automática de estouros
1. Se ainda houver células vazias no TableLayoutPanel controle, continue inserindo
novos Button controles até que o TableLayoutPanel controle esteja cheio.
2. Quando o TableLayoutPanel controle estiver cheio, clique duas vezes no Button

ícone na Caixa de Ferramentas para inserir outro Button controle. Observe que o
TableLayoutPanel controle cria novas células para acomodar o novo controle. Insira
mais alguns controles e observe o comportamento de redimensionamento.
3. Altere o valor da propriedade TableLayoutPanel do controle GrowStyle para

FixedSize. Clique duas vezes no Button ícone na Caixa de Ferramentas para inserir
Button controles até que o TableLayoutPanel controle esteja cheio. Clique duas
vezes no Button ícone na Caixa de Ferramentas novamente. Observe que você
receberá uma mensagem de erro do Designer de Formulários do Windows,
informando que não possível criar mais linhas e colunas.
Inserindo um controle ao desenhar seu

contorno
Você pode inserir um controle em um TableLayoutPanel controle e especificar seu
tamanho desenhando sua estrutura de tópicos em uma célula.
Para inserir um controle desenhando seu contorno


formulário.
3. Mova o ponteiro do mouse sobre o TableLayoutPanel controle. Observe que o

ponteiro muda para uma mira com o ícone de Button controle anexado.
5. Arraste o ponteiro do mouse para desenhar a estrutura de tópicos do Button

controle. Quando estiver satisfeito com o tamanho, solte o botão do mouse.
Observe que o Button controle é criado na célula na qual você desenhou a
estrutura de tópicos do controle.
Vários controles dentro de células não são
permitidos
O TableLayoutPanel controle pode conter apenas um controle filho por célula.
Para demonstrar que vários controles dentro de células não são

permitidos
Arraste um Button controle da Caixa de Ferramentas para o controle e solte-o
TableLayoutPanel em uma das células ocupadas. Observe que o TableLayoutPanel
controle não permite que você solte o Button controle na célula ocupada.
Trocando controles
O TableLayoutPanel controle permite que você troque os controles que ocupam duas
células diferentes.
Para trocar controles

Arraste um dos Button controles de uma célula ocupada e solte em outra célula
ocupada. Observe que os dois controles são movidos de uma célula para a outra.
Próximas etapas
Você pode obter um layout complexo usando uma combinação de controles e painéis
de layout. Sugestões para exploração adicional incluem:
Tente redimensionar um dos Button controles para um tamanho maior e observe o

efeito no layout.
Cole uma seleção de vários controles no TableLayoutPanel controle e observe

como os controles são inseridos.
Os painéis de layout podem conter outros painéis de layout. Experimente soltar

um TableLayoutPanel controle no controle existente.
Encaixe o TableLayoutPanel controle no formulário pai. Redimensione o formulário

e observe o efeito no layout.
Confira também
FlowLayoutPanel
TableLayoutPanel
FlowLayoutPanel
de alinhamento
Passo a passo: criando um Windows Form redimensionável para entrada de dados
Passo a passo: criando um Windows Form localizável
Controle TextBox (Windows Forms)
Artigo • 02/06/2023
Caixas de texto dos Windows Forms são usadas para obter entradas do usuário ou para
exibir texto. O controle TextBox geralmente é usado para texto editável, embora
também possa ser tornado somente leitura. Caixas de texto podem exibir várias linhas,
quebrar o texto para o tamanho do controle e adicionar formatação básica. O controle
TextBox permite um único formato de texto exibido ou inserido no controle.
Nesta seção
Como: Controlar o ponto de inserção em um controle TextBox do Windows Forms

Fornece instruções para especificar onde o ponto de inserção aparece quando um
controle de edição obtém o foco primeiro.
Como: Criar uma caixa de texto de senha com o controle TextBox do Windows Forms
Explica como ocultar o que for digitado em uma caixa de texto.
Como: Criar uma caixa de texto somente leitura

Descreve como impedir que o conteúdo de uma caixa de texto seja alterado.
Como: Inserir aspas em uma cadeia de caracteres

Explica a adição de aspas a uma cadeia de caracteres em uma caixa de texto.
Como: Selecionar texto no controle TextBox do Windows Forms

Explica como realçar texto em uma caixa de texto.
Como: Exibir várias linhas no controle TextBox do Windows Forms

Descreve como criar uma caixa de texto rolável.
Referência
Classe TextBox
(Windows Forms)
Artigo • 02/06/2023
Caixas de texto dos Windows Forms são usadas para obter entradas do usuário ou para
exibir texto. O controle TextBox geralmente é usado para texto editável, embora
também possa ser tornado somente leitura. Caixas de texto podem exibir várias linhas,
quebrar o texto para o tamanho do controle e adicionar formatação básica. O TextBox
controle fornece um estilo de formato único para texto exibido ou inserido no controle.
Para exibir vários tipos de texto formatado, use o RichTextBox controle. Para obter mais
informações, consulte Visão geral do controle RichTextBox.
Trabalhando com o controle TextBox

O texto exibido pelo controle está contido na Text propriedade. Por padrão, você pode
inserir até 2048 caracteres em uma caixa de texto. Se você definir a Multiline
propriedade como true , poderá inserir até 32 KB de texto. A Text propriedade pode ser
definida em tempo de design com a Janela Propriedades, em tempo de execução no
código ou pela entrada do usuário em tempo de execução. O conteúdo atual de uma
caixa de texto pode ser recuperado em tempo de execução lendo a Text propriedade.
O exemplo de código a seguir define o texto no controle no tempo de execução. O

InitializeMyControl procedimento não será executado automaticamente; ele deve ser
chamado.
C#
private void InitializeMyControl() {

// Put some text into the control first.
textBox1.Text = "This is a TextBox control.";
}
Confira também
TextBox
Como: Criar uma caixa de texto de senha com o controle TextBox do Windows
Forms
Controle TextBox
Como: Controlar o ponto de inserção
em um controle TextBox do Windows
Forms
Artigo • 02/06/2023
Quando um controle Windows Forms TextBox recebe o foco pela primeira vez, a
inserção padrão dentro da caixa de texto é à esquerda de qualquer texto existente. O
usuário pode mover o ponto de inserção com o teclado ou o mouse. Se a caixa de texto
perder e recuperar o foco, o ponto de inserção será sempre o ponto em que o usuário o
colocou por último.
Em alguns casos, esse comportamento pode ser desconcertante para o usuário. Em um

aplicativo de processamento de texto, o usuário pode esperar que novos caracteres
apareçam após o texto existente. Em um aplicativo de entrada de dados, o usuário pode
esperar que novos caracteres substituam a entrada existente. As SelectionStart
propriedades e as SelectionLength propriedades permitem que você modifique o
comportamento de acordo com sua finalidade.
Controlar o ponto de inserção em um controle TextBox

1. Defina a propriedade SelectionStart com um valor apropriado. Zero coloca o ponto
de inserção imediatamente à esquerda do primeiro caractere.
2. (Opcional) Defina a SelectionLength propriedade com o comprimento do texto

que você deseja selecionar.
O código abaixo sempre retorna o ponto de inserção para 0. O manipulador de

eventos TextBox1_Enter deve ser associado ao controle; para obter mais
informações, consulte Criando manipuladores de eventos no Windows Forms.
C#
private void textBox1_Enter(Object sender, System.EventArgs e) {

textBox1.SelectionStart = 0;
textBox1.SelectionLength = 0;
}
Tornando o ponto de inserção visível por

padrão
O TextBox ponto de inserção fica visível por padrão em um novo formulário somente se
o TextBox controle for o primeiro na ordem de tabulação. Caso contrário, o ponto de
inserção será exibido somente se você fornecer o TextBox foco com o teclado ou o
mouse.
Tornar a o ponto de inserção da caixa de texto visível por padrão

em um novo formulário
Defina a TextBox propriedade do TabIndex controle como 0 .
Confira também
TextBox
Forms
Controle TextBox
Como: Criar uma caixa de texto de
senha com o controle TextBox do
Windows Forms
Artigo • 02/06/2023
Uma caixa de senha é uma caixa de texto do Windows Forms que exibe caracteres de
espaço reservado enquanto um usuário digita uma cadeia de caracteres.
Criar uma caixa de texto de senha

1. De definir PasswordChar a propriedade do controle TextBox como um caractere
específico.
A PasswordChar propriedade especifica o caractere exibido na caixa de texto. Por

exemplo, se você quiser asteriscos exibidos na caixa de senha, especifique *
PasswordChar para a propriedade no janela Propriedades. Em seguida,
independentemente de qual caractere de um usuário digita na caixa de texto, será
exibido um asterisco.
2. (Opcional) De acordo com a MaxLength propriedade . A propriedade determina

quantos caracteres podem ser digitado na caixa de texto. Se o tamanho máximo
for excedido, o sistema emitirá um aviso sonoro e a caixa de texto não aceitará
mais caracteres. Observe que isso pode não ser recomendável, visto que o
tamanho máximo de uma senha pode ser útil para os hackers que estão tentando
adivinhá-la.
O exemplo de código a seguir mostra como inicializar uma caixa de texto que
aceita uma cadeia de até 14 caracteres e exibir os asteriscos no lugar da cadeia de
caracteres. O InitializeMyControl procedimento não será executado
automaticamente; ele deve ser chamado.
） Importante
O uso PasswordChar da propriedade em uma caixa de texto pode ajudar a

garantir que outras pessoas não possam determinar a senha de um usuário se
observarem o usuário inserindo-a. Essa medida de segurança não abrange
nenhum tipo de armazenamento e transmissão de senha que pode ocorrer
devido a lógica do aplicativo. Como o texto inserido não é criptografado de
nenhuma forma, você deve tratá-lo como qualquer outro dado confidencial.
Mesmo que ela não apareça como tal, a senha é ainda está sendo tratada
como uma cadeia de caracteres de texto sem formatação (a menos que você
implemente alguma outra medida de segurança adicional).
C#
private void InitializeMyControl()

{
// Set to no text.
textBox1.Text = "";
// The password character is an asterisk.
textBox1.PasswordChar = '*';
// The control will allow no more than 14 characters.
textBox1.MaxLength = 14;
}
Confira também
TextBox
Controle TextBox
Como criar uma caixa de texto somente
leitura (Windows Forms)
Artigo • 02/06/2023
você pode transformar uma caixa de texto Windows Forms editável em um controle
somente leitura. Por exemplo, a caixa de texto pode exibir um valor que geralmente é
editado, mas pode não estar no momento, devido ao estado do aplicativo.
Para criar uma caixa de texto somente leitura

1. Defina a TextBox Propriedade do ReadOnly controle como true . Com a
propriedade definida como true , os usuários ainda podem rolar e realçar o texto
em uma caixa de texto sem permitir alterações. Um comando de cópia é funcional
em uma caixa de texto, mas os comandos recortar e colar não são.
７ Observação
A propriedade afeta apenas a ReadOnly interação do usuário em tempo de

execução. Você ainda pode alterar o conteúdo da caixa de texto
programaticamente em tempo de execução alterando a Text propriedade da
caixa de texto.
Confira também
TextBox
Forms
Controle TextBox
Como inserir aspas em uma cadeia de
caracteres (Windows Forms)
Artigo • 21/06/2023
Às vezes, você pode querer colocar aspas (" ") em uma cadeia de caracteres de texto.
Por exemplo:
Ela disse: "Você merece um agrado!"
Como alternativa, você também pode usar o Quote campo como uma constante.
Para colocar as aspas em uma cadeia de caracteres no

código
1. No Visual Basic, insira duas aspas em uma linha como aspas inseridas. No Visual
C# e no Visual C++, insira a sequência de escape \" como uma aspa inserida. Por
exemplo, para criar a cadeia de caracteres anterior, use o código a seguir.
C#
private void InsertQuote(){

textBox1.Text = "She said, \"You deserve a treat!\" ";
}
-ou-
2. Insira o caractere ASCII ou Unicode para aspas. No Visual Basic, use o caractere
ASCII (34). No Visual C#, use o caractere Unicode (\u0022).
C#
private void InsertAscii(){

textBox1.Text = "She said, " + '\u0022' + "You deserve a treat!" +
'\u0022';
}
７ Observação
Neste exemplo, não é possível usar \u0022 porque você não pode usar um
nome de caractere universal que designa um caractere no conjunto de
caracteres básicos. Caso contrário, você produz C3851. Para obter mais
informações, consulte Erro do compilador C3851.
-ou-
3. Você também pode definir uma constante para o caractere e usá-la quando
necessário.
C#
const string quote = "\"";

textBox1.Text = "She said, " + quote + "You deserve a treat!"+ quote ;
Confira também
TextBox
Quote
Forms
Controle TextBox
Como: Selecionar texto no controle
TextBox do Windows Forms
Artigo • 21/06/2023
Você pode selecionar texto programaticamente no controle Windows FormsTextBox. Por

exemplo, se você criar uma função que pesquisa de texto de uma determinada cadeia
de caracteres, poderá selecionar o texto para alertar visualmente o leitor da posição da
cadeia de caracteres encontrada.
Selecionar texto com programação

1. Defina a SelectionStart propriedade como o início do texto que você deseja
selecionar.
A SelectionStart propriedade é um número que indica o ponto de inserção dentro

da cadeia de caracteres de texto, sendo 0 a posição mais à esquerda. Se a
SelectionStart propriedade for definida como um valor igual ou maior que o
número de caracteres na caixa de texto, o ponto de inserção será colocado após o
último caractere.
2. Defina a SelectionLength propriedade com o comprimento do texto que você

deseja selecionar.
A SelectionLength propriedade é um valor numérico que define a largura do ponto

de inserção. Definir o SelectionLength como um número maior que 0 faz com que
esse número de caracteres seja selecionado, começando do ponto de inserção
atual.
3. (Opcional) Acesse o texto selecionado por meio da SelectedText propriedade .
O código a seguir seleciona o conteúdo de uma caixa de texto quando o evento

do Enter controle ocorre. Este exemplo verifica se a caixa de texto tem um valor
para a Text propriedade que não null é ou uma cadeia de caracteres vazia.
Quando a caixa de texto recebe o foco, o texto presente nela é selecionado. O
manipulador de eventos TextBox1_Enter deve ser associado ao controle; para
obter mais informações, consulte Como criar manipuladores de eventos no tempo
de execução para Windows Forms.
Para testar esse exemplo, pressione a tecla Tab até que a caixa de texto receber o
foco. Se você clicar na caixa de texto, a seleção dele será cancelada.
C#
private void textBox1_Enter(object sender, System.EventArgs e){

if (!String.IsNullOrEmpty(textBox1.Text))
{
textBox1.SelectionStart = 0;
textBox1.SelectionLength = textBox1.Text.Length;
}
}
Confira também
TextBox
Forms
Controle TextBox
Como: Exibir várias linhas no controle
TextBox do Windows Forms
Artigo • 02/06/2023
por padrão, o controle de Windows Forms TextBox exibe uma única linha de texto e não
exibe barras de rolagem. Se o texto for maior que o espaço disponível, apenas parte do
texto ficará visível. Você pode alterar esse comportamento padrão definindo as Multiline
Propriedades, WordWrap e ScrollBars com os valores apropriados.
Exibir um retorno de carro no controle TextBox

Para exibir um retorno de carro em uma linha TextBox múltipla, use a NewLine
propriedade.
Lembre-se de que a interpretação de caracteres de escape (\) é específica a um

idioma. O Visual Basic usa Chr$(13) & Chr$(10) para a combinação de retorno de
carro e caracteres de avanço de linha.
Exibir várias linhas no controle TextBox

1. Defina a propriedade Multiline como true . Se WordWrap for true (o padrão), o
texto no controle aparecerá como um ou mais parágrafos; caso contrário, ele será
exibido como uma lista, na qual algumas linhas podem ser recortadas na borda do
controle.
2. Defina a propriedade ScrollBars com um valor apropriado.
Valor Descrição
None Use esse valor se o texto será um parágrafo que quase sempre se ajusta ao
controle. O usuário poderá usar o ponteiro do mouse para mover-se dentro
do controle se o texto for grande demais para ser exibido totalmente ao
mesmo tempo.
Horizontal Use esse valor se desejar exibir uma lista de linhas, algumas das quais podem
ser maiores que a largura do TextBox controle.
Both Use esse valor se a lista pode ser maior que a altura do controle.
3. Defina a propriedade WordWrap com um valor apropriado.
Valor Descrição
Valor Descrição
false O texto no controle não será encapsulado automaticamente, portanto ele rolará
para a direita até atingir uma quebra de linha. Use esse valor se você escolher
Horizontal barras de rolagem ou Both , acima.
true A barra de rolagem horizontal não será exibida. Use esse valor se você escolher
(padrão) Vertical barras de rolagem ou None , acima, para exibir um ou mais parágrafos.
Confira também
TextBox
Forms
Controle TextBox
Componente Temporizador (Windows
Forms)
Artigo • 02/06/2023
O Windows Forms Timer é um componente que gera um evento em intervalos

regulares. Esse componente foi projetado para um ambiente do Windows Forms.
Nesta seção
Visão geral do componente de temporizador
Apresenta os conceitos gerais do componente, que Timer permite que você configure
seu aplicativo para responder a eventos periódicos.
Limitações da propriedade de intervalo do componente de temporizador dos Windows

Forms
Descreve as limitações conhecidas do intervalo do temporizador que podem afetar a
forma como você pode usá-lo.
Como: Executar procedimentos em intervalos definidos com o componente de

temporizador do Windows Forms
Descreve como reagir a intervalos cronometrados em seus aplicativos baseados no
Windows.
Referência
Classe System.Windows.Forms.Timer
Fornece informações de referência sobre a classe, usadas para Windows Forms
temporizadores e seus membros.
Classe System.Timers.Timer
Fornece informações de referência sobre a System.Timers.Timer classe usada por
temporizadores baseados em servidor.
Visão geral do componente de
temporizador (Windows Forms)
Artigo • 21/06/2023
O Windows Forms Timer é um componente que gera um evento em intervalos

regulares. Esse componente foi projetado para um ambiente do Windows Forms. Se
você precisar de um temporizador que seja adequado para um ambiente de servidor,
consulte Introdução a temporizadores baseados em servidor.
Propriedades, métodos e eventos de chave

O comprimento dos intervalos é definido pela Interval propriedade , cujo valor está em
milissegundos. Quando o componente está habilitado, o Tick evento é gerado a cada
intervalo. É aqui que você adicionaria o código a ser executado. Para obter mais
informações, consulte Como executar procedimentos em intervalos definidos com o
componente temporizador Windows Forms. Os principais métodos do Timer
componente são Start e Stop, que ativam e desativam o temporizador. Quando o
temporizador é desligado, ele é redefinido; não há como pausar um Timer componente.
Confira também
Timer
Limitações da propriedade de intervalo do componente de temporizador dos
Windows Forms
Limitações da propriedade de intervalo
do componente de temporizador dos
Windows Forms
Artigo • 21/06/2023
O componente Windows Forms Timer tem uma Interval propriedade que especifica o
número de milissegundos que passam entre um evento de temporizador e o próximo. A
menos que o componente esteja desabilitado, um temporizador continuará recebendo
o Tick evento em intervalos aproximadamente iguais de tempo.
Esse componente foi projetado para um ambiente do Windows Forms. Se você precisar
de um temporizador que seja adequado para um ambiente de servidor, consulte
Introdução a temporizadores baseados em servidor.
A propriedade Interval
A Interval propriedade tem algumas limitações a serem consideradas ao programar um
Timer componente:
Se o aplicativo ou outro aplicativo estiver fazendo demandas pesadas no sistema ,

como loops longos, cálculos intensivos ou acesso à unidade, rede ou porta , seu
aplicativo pode não receber eventos de temporizador com tanta frequência
quanto a Interval propriedade especifica.
Não há garantia de que o intervalo decorra exatamente na hora. Para garantir a

precisão, o temporizador deve verificar o relógio do sistema conforme necessário,
em vez de tentar manter o controle de tempo acumulado internamente.
A precisão da Interval propriedade está em milissegundos. Alguns computadores

fornecem um contador de alta resolução que tem uma resolução maior do que
milissegundos. A disponibilidade desse contador depende do hardware do
processador do computador.
Confira também
Timer
Como: Executar procedimentos em
intervalos definidos com o componente
de temporizador do Windows Forms
Artigo • 21/06/2023
Às vezes, pode ser útil criar um procedimento que é executado em intervalos de tempo
específicos até que um loop termine ou que seja executado quando um determinado
período tiver decorrido. O Timer componente possibilita esse procedimento.
Esse componente foi projetado para um ambiente do Windows Forms. Se você precisar
de um temporizador que seja adequado para um ambiente de servidor, consulte
Introdução a temporizadores baseados em servidor.
７ Observação
Há algumas limitações ao usar o Timer componente . Para obter mais informações,

consulte Limitações da propriedade de intervalo do componente de
temporizador do Windows Forms.
Executar um procedimento em intervalos

definidos com o componente Timer
1. Adicione um Timer ao formulário. Consulte a seção Exemplo a seguir para obter
ver como fazer isso com programação. O Visual Studio também tem suporte para
adicionar componentes a um formulário. Consulte também: Como adicionar
controles sem uma interface do usuário ao Windows Forms.
2. Defina a Interval propriedade (em milissegundos) para o temporizador. Essa

propriedade determina quanto tempo passará antes do procedimento ser
executado novamente.
７ Observação
Quanto maior a frequência do evento do temporizador, mais tempo do

processador é usado em resposta ao evento. Isso pode diminuir o
desempenho geral. Não defina um intervalo menor do que o necessário.
3. Escreva o código apropriado no Tick manipulador de eventos. O código que você
escreve nesse evento será executado no intervalo especificado na Interval
propriedade .
4. Defina a Enabled propriedade como true para iniciar o temporizador. O Tick

evento começará a ocorrer, executando o procedimento no intervalo definido.
5. No momento apropriado, defina a Enabled propriedade como false para impedir

que o procedimento seja executado novamente. Definir o intervalo como 0 não
faz o temporizador parar.
Primeiro exemplo de código

Esse primeiro exemplo de código rastreia a hora do dia em incrementos de um
segundo. Ele usa um Button, um Labele um Timer componente em um formulário. A
Interval propriedade é definida como 1000 (igual a um segundo). Tick No caso, o
legenda do rótulo é definido como a hora atual. Quando o botão é clicado, a Enabled
propriedade é definida false como , impedindo que o temporizador atualize o legenda
do rótulo. O exemplo de código a seguir exige que você tenha um formulário com um
controle chamado Button1 , um Timer controle chamado Timer1 e um Label controle
chamado Label1 .Button
C#
private void InitializeTimer()

{
// Call this procedure when the application starts.
// Set to 1 second.
Timer1.Interval = 1000;
Timer1.Tick += new EventHandler(Timer1_Tick);
// Enable timer.
Timer1.Enabled = true;
Button1.Text = "Stop";
Button1.Click += new EventHandler(Button1_Click);
}
private void Timer1_Tick(object Sender, EventArgs e)

{
// Set the caption to the current time.
Label1.Text = DateTime.Now.ToString();
}

{
if ( Button1.Text == "Stop" )
{
Button1.Text = "Start";
Timer1.Enabled = false;
}
else
{
Button1.Text = "Stop";
Timer1.Enabled = true;
}
}
Segundo exemplo de código

Este segundo exemplo de código executa um procedimento a cada 600 milissegundos
até que um loop seja concluído. O exemplo de código a seguir exige que você tenha um
formulário com um controle chamado Button1 , um Timer controle chamado Timer1 e
um Label controle chamado Label1 .Button
C#
// This variable will be the loop counter.

private int counter;
private void InitializeTimer()

{
// Run this procedure in an appropriate event.
counter = 0;
timer1.Interval = 600;
timer1.Enabled = true;
// Hook up timer's tick event handler.
this.timer1.Tick += new System.EventHandler(this.timer1_Tick);
}
private void timer1_Tick(object sender, System.EventArgs e)

{
if (counter >= 10)
{
// Exit loop code.
timer1.Enabled = false;
counter = 0;
}
else
{
// Run your procedure here.
// Increment counter.
counter = counter + 1;
label1.Text = "Procedures Run: " + counter.ToString();
}
}
Confira também
Timer
Controle ToolBar (Windows Forms)
Artigo • 02/06/2023
７ Observação
O controle ToolStrip substitui e adiciona funcionalidade ao controle ToolBar , no

entanto, o controle ToolBar é mantido para compatibilidade com versões
anteriores e para uso futuro, se desejado.
O controle ToolBar dos Windows Forms é usado em formulários como uma barra de
controle que exibe uma linha de menus suspensos e botões de bitmap que ativam
comandos. Portanto, clicar em um botão de barra de ferramentas é equivalente a
escolher um comando de menu. Os botões podem ser configurados para parecer e se
comportar como botões de push, menus suspensos ou separadores. Normalmente, uma
barra de ferramentas contém botões e menus que correspondem aos itens na estrutura
do menu do aplicativo, fornecendo acesso rápido às funções e comandos do aplicativo
usados com mais frequência.
７ Observação
A ToolBar propriedade do DropDownMenu controle usa uma instância da

ContextMenu classe como referência. Considere cuidadosamente a referência que
você passa ao implementar esse tipo de botão em barras de ferramentas em seu
aplicativo, pois a propriedade aceitará qualquer objeto herdado da Menu classe.
Nesta seção
Visão geral do controle ToolBar
Apresenta os conceitos gerais do controle ToolBar , o que permite a criação de barras
de ferramentas personalizadas com que seus usuários podem trabalhar.
Como: Adicionar botões a um controle ToolBar

Descreve como adicionar botões a um controle ToolBar .
Como: Definir um ícone para um botão de barra de ferramentas

Descreve como exibir ícones nos botões de um controle ToolBar .
Como: Disparar eventos de menu para botões da barra de ferramentas
Fornece instruções sobre como escrever o código para interpretar em qual botão o
usuário clica em um controle ToolBar .
Consulte também Como definir um ícone para um botão de barra de ferramentas

usando o Designer, Como adicionar botões a um controle de barra de ferramentas
usando o Designer.
Referência
Classe ToolBar
Controle ToolStrip
Descreve as barras de ferramentas que podem hospedar menus, controles e controles
de usuário em aplicativos dos Windows Forms.
(Windows Forms)
Artigo • 21/06/2023
７ Observação
O controle ToolStrip substitui e adiciona funcionalidade ao controle ToolBar, no

O controle ToolBar dos Windows Forms é usado em formulários como uma barra de
controle que exibe uma linha de menus suspensos e botões de bitmap que ativam
comandos. Portanto, clicar em um botão de barra de ferramentas pode ser equivalente
a escolher um comando de menu. Os botões podem ser configurados para parecerem e
se comportarem como botões de pressão, menus suspensos ou separadores.
Normalmente, uma barra de ferramentas contém botões e menus que correspondem
aos itens na estrutura do menu do aplicativo, fornecendo acesso rápido às funções e
comandos do aplicativo usados com mais frequência.
Trabalhando com o controle ToolBar

Um ToolBar controle geralmente é "encaixado" na parte superior da janela pai, mas
também pode ser encaixado em qualquer lado da janela. Uma barra de ferramentas
pode exibir dicas de ferramenta quando o usuário apontar o ponteiro do mouse para
um botão de barra de ferramentas. Uma ToolTip é uma pequena janela pop-up que
descreve resumidamente a finalidade do botão ou do menu. Para exibir Dicas de
Ferramenta, a ShowToolTips propriedade deve ser definida true como .
７ Observação
Alguns aplicativos apresentam controles muito semelhantes à barra de ferramentas

que têm a capacidade de “flutuar” acima da janela do aplicativo e ser
reposicionado. O controle ToolBar do Windows Forms não é capaz de realizar essas
ações.
Quando a Appearance propriedade é definida ToolBarAppearancecomo , os botões da

barra de ferramentas aparecem gerados e tridimensionais. Você pode definir a
Appearance propriedade da barra de ferramentas como para ToolBarAppearance dar à
barra de ferramentas e seus botões uma aparência plana. Quando o ponteiro do mouse
passa sobre um botão plano, a aparência do botão muda para tridimensional. Botões de
barra de ferramentas podem ser divididos em grupos lógicos usando separadores. Um
separador é um botão de barra de ferramentas com a Style propriedade definida
ToolBarButtonStylecomo . Ele aparece como um espaço vazio na barra de ferramentas.
Quando a barra de ferramentas tem uma aparência plana, os separadores de botões
aparecem como linhas em vez de espaços entre os botões.
O ToolBar controle permite que você crie barras de ferramentas adicionando Button
objetos a uma Buttons coleção. Você pode usar o Editor de Coleção para adicionar
botões a um ToolBar controle; cada Button objeto deve ter texto ou uma imagem
atribuída, embora você possa atribuir ambos. A imagem é fornecida por um
componente ImageList associado. Em tempo de execução, você pode adicionar ou
remover botões do ToolBar.ToolBarButtonCollection usando os Add métodos e Remove
. Para programar os botões de um ToolBar, adicione código aos ButtonClick eventos do
ToolBar, usando a Button propriedade da ToolBarButtonClickEventArgs classe para
determinar qual botão foi clicado.
Confira também
ToolBar
Controle ToolBar
Como: Adicionar botões a um controle
ToolBar
Artigo • 02/06/2023
７ Observação

Uma parte integral do ToolBar controle são os botões que você adiciona a ele. Eles
podem ser usados para fornecer acesso fácil aos comandos de menu ou, como
alternativa, podem ser colocados em outra área da interface do usuário do seu
aplicativo para expor comandos para os usuários que não estão disponíveis na estrutura
do menu.
Os exemplos a seguir pressupõem que um ToolBar controle foi adicionado a um

Formulário do Windows ( Form1 ).
Para adicionar botões programaticamente

1. Em um procedimento, crie botões da barra de ferramentas adicionando-os
ToolBar.Buttons à coleção.
2. Especifique as configurações de propriedade para um botão individual passando o

índice do botão por meio da Buttons propriedade.
O exemplo a seguir pressupõe um formulário com um ToolBar controle já

adicionado.
７ Observação
A ToolBar.Buttons coleção é uma coleção baseada em zero, portanto, o

código deve continuar de acordo.
C#
public void CreateToolBarButtons()

{
// Create buttons and set text property.
toolBar1.Buttons.Add("One");
toolBar1.Buttons.Add("Two");
toolBar1.Buttons.Add("Three");
toolBar1.Buttons.Add("Four");
// Set properties of StatusBar panels.

// Set Style property.
toolBar1.Buttons[0].Style = ToolBarButtonStyle.PushButton;
toolBar1.Buttons[1].Style = ToolBarButtonStyle.Separator;
toolBar1.Buttons[2].Style = ToolBarButtonStyle.ToggleButton;
toolBar1.Buttons[3].Style = ToolBarButtonStyle.DropDownButton;
// Set the ToggleButton's PartialPush property.

toolBar1.Buttons[2].PartialPush = true;
// Instantiate a ContextMenu component and menu items.

// Set the DropDownButton's DropDownMenu property to
// the context menu.
ContextMenu cm = new ContextMenu();
MenuItem miOne = new MenuItem("One");
MenuItem miTwo = new MenuItem("Two");
MenuItem miThree = new MenuItem("Three");
cm.MenuItems.Add(miOne);
cm.MenuItems.Add(miTwo);
cm.MenuItems.Add(miThree);
toolBar1.Buttons[3].DropDownMenu = cm;
// Set the PushButton's Pushed property.
toolBar1.Buttons[0].Pushed = true;
// Set the ToolTipText property of 1 of the buttons.
toolBar1.Buttons[1].ToolTipText = "Button 2";
}
Confira também
ToolBar
Controle ToolBar
Como: Adicionar botões a um controle
ToolBar usando o designer
Artigo • 02/06/2023
７ Observação

Uma parte integral do ToolBar controle são os botões que você adiciona a ele. Eles
podem ser usados para fornecer acesso fácil aos comandos de menu ou, como
alternativa, podem ser colocados em outra área da interface do usuário do seu
aplicativo para expor comandos para os usuários que não estão disponíveis na estrutura
do menu.

formulário contendo um ToolBar controle. Para obter informações sobre como
Adicionar botões no tempo de design

1. Selecione o controle ToolBar.
2. Na janela Propriedades, clique na Buttons propriedade para selecioná-la e clique

nas Reticências ( ) para abrir o Editor de Coleção ToolBarButton.
3. Use os botões Adicionar e Remover para adicionar e remover botões do ToolBar

controle.
4. Configure as propriedades dos botões individuais na janela Propriedades que

aparece no painel à direita do editor. A tabela a seguir mostra algumas
propriedades importantes a considerar.
DropDownMenu Define o menu a ser exibido no botão de barra de ferramentas da lista

suspensa. A propriedade do botão da barra de Style ferramentas deve
ser definida como DropDownButton. Essa propriedade usa uma
instância da ContextMenu classe como referência.
PartialPush Define se um botão de alternância de barra de ferramentas é

parcialmente pressionado. A propriedade do botão da barra de Style
ferramentas deve ser definida como ToggleButton.
Pushed Define se um botão de alternância da barra de ferramentas está no

estado pressionado. A propriedade do botão da barra de Style
ferramentas deve ser definida ToggleButton como ou PushButton.
Style Define o estilo do botão de barra de ferramentas. Deve ser um dos

valores na ToolBarButtonStyle enumeração.
Text A cadeia de caracteres de texto exibida pelo botão.
ToolTipText O texto que aparece como uma ToolTip para o botão.
5. Clique em OK para fechar a caixa de diálogo e criar os painéis que você

especificou.
Confira também
ToolBar
Controle ToolBar
Como: Definir um ícone para um botão
de barra de ferramentas
Artigo • 02/06/2023
７ Observação

ToolBar os botões são capazes de exibir ícones dentro deles para facilitar a identificação
dos usuários. Isso é obtido por meio da adição de imagens ao componente ImageList
Component e, em seguida, associando o ImageList componente ao ToolBar controle.
Para definir um ícone para um botão de barra de

ferramentas programaticamente
1. Em um procedimento, instancie um ImageList componente e um ToolBar controle.
2. No mesmo procedimento, atribua uma imagem ao ImageList componente.
3. No mesmo procedimento, atribua o ImageList controle ao ToolBar controle e

atribua a ImageIndex propriedade dos botões individuais da barra de ferramentas.

pasta Meus documentos. Isso acontece porque presumimos que a maioria dos
computadores rodando o sistema operacional Windows vai incluir este diretório.
Isso também permite que usuários com níveis mínimos de acesso ao sistema
executem com segurança o aplicativo. O exemplo a seguir pressupõe um
formulário com um PictureBox controle já adicionado.
Seguindo as etapas acima, você deve ter escrito um código semelhante ao exibido
abaixo.
C#
public void InitializeMyToolBar()

{
// Instantiate an ImageList component and a ToolBar control.
ToolBar toolBar1 = new ToolBar();
ImageList imageList1 = new ImageList();
// Assign an image to the ImageList component.
Image myImage = Image.FromFile
+ @"\Image.gif");
imageList1.Images.Add(myImage);
// Create a ToolBarButton.
ToolBarButton toolBarButton1 = new ToolBarButton();
// Add the ToolBarButton to the ToolBar.
toolBar1.Buttons.Add(toolBarButton1);
// Assign an ImageList to the ToolBar.
toolBar1.ImageList = imageList1;
// Assign ImageIndex property of the ToolBarButton.
toolBarButton1.ImageIndex = 0;
}
Confira também
ToolBar
Controle ToolBar
Como: Definir um ícone para um botão
de barra de ferramentas usando o
Designer
Artigo • 02/06/2023
７ Observação

ToolBar os botões são capazes de exibir ícones dentro deles para facilitar a identificação
dos usuários. Isso é obtido por meio da adição de imagens ao ImageList componente e
da associação dele ao ToolBar controle.

formulário contendo um ToolBar controle e um ImageList componente. Para obter
informações sobre como configurar esse projeto, consulte Como criar um projeto de
aplicativo Windows Forms e como adicionar controles a Windows Forms.
Para definir um ícone para um botão de barra de

ferramentas em tempo de design
1. Adicione imagens ao ImageList componente. Para obter mais informações,
consulte Como adicionar ou remover imagens ImageList com o designer.
2. Selecione o ToolBar controle em seu formulário.
3. Na janela Propriedades , defina a ToolBar propriedade do ImageList controle como

o ImageList componente.
4. Clique na ToolBar propriedade do Buttons controle para selecioná-lo e clique nas

reticências ( ) para abrir o Editor de Coleção ToolBarButton.
5. Use o botão Adicionar para adicionar botões ao ToolBar controle.
6. Na janela Propriedades exibida no painel no lado direito do Editor de Coleção

ToolBarButton, defina a ImageIndex propriedade de cada botão da barra de
ferramentas como um dos valores da lista, que é extraído das imagens adicionadas
ao ImageList componente.
Confira também
ToolBar
Controle ToolBar
Como: Disparar eventos de menu para
botões da barra de ferramentas
Artigo • 21/06/2023
７ Observação

Se o Windows Form tiver um ToolBar controle com botões da barra de ferramentas,

você desejará saber em qual botão o usuário clica.
ButtonClick No evento do ToolBar controle, você pode avaliar a Button propriedade da

ToolBarButtonClickEventArgs classe . No exemplo a seguir, uma caixa de mensagem é
exibida, indicando qual botão foi clicado. Para obter detalhes, consulte MessageBox.
O exemplo a seguir pressupõe que um ToolBar controle foi adicionado a um Windows

Form.
Para manipular o evento de Clique na barra de

ferramentas
1. Em um procedimento, adicione botões da barra de ferramentas ao ToolBar
controle .
C#
public void ToolBarConfig()

{
toolBar1.Buttons.Add(new ToolBarButton("One"));
toolBar1.Buttons.Add(new ToolBarButton("Two"));
toolBar1.Buttons.Add(new ToolBarButton("Three"));
toolBar1.ButtonClick +=
new ToolBarButtonClickEventHandler(this.toolBar1_ButtonClick);
}
2. Adicione um manipulador de eventos para o ToolBar evento do ButtonClick

controle. Use uma instrução de troca de maiúsculas e minúsculas e a
ToolBarButtonClickEventArgs classe para determinar o botão da barra de
ferramentas clicado. Com base nisso, exiba a caixa de mensagem apropriada.
７ Observação
Uma caixa de mensagem está sendo usada apenas como um espaço

reservado neste exemplo. Fique à vontade para adicionar outro código para
ser executado quando os botões da barra de ferramentas forem clicados.
C#
protected void toolBar1_ButtonClick(object sender,

ToolBarButtonClickEventArgs e)
{
// Evaluate the Button property of the ToolBarButtonClickEventArgs
// to determine which button was clicked.
switch (toolBar1.Buttons.IndexOf(e.Button))
{
case 0 :
MessageBox.Show("First toolbar button clicked");
break;
case 1 :
MessageBox.Show("Second toolbar button clicked");
break;
case 2 :
MessageBox.Show("Third toolbar button clicked");
break;
}
}
Confira também
ToolBar
Controle ToolBar
Controle ToolStrip (Windows Forms)
Artigo • 02/06/2023
ToolStripos controles são barras de ferramentas que podem hospedar menus, controles
e controles de usuário em seus aplicativos Windows Forms.
Nesta seção
Visão geral do controle ToolStrip
Como: Gerenciar o estouro de ToolStrip

Demonstra como habilitar a funcionalidade de estouro e controlar tal comportamento.
Como: Habilitar a reorganização de itens ToolStrip no tempo de execução

Demonstra como habilitar a reorganização de controles em tempo de ToolStripItem
execução.
Como: Habilitar AutoComplete em controles ToolStrip

Demonstra a funcionalidade de conclusão automática em um ToolStripComboBox.
Como: Alterar o espaçamento e o alinhamento de itens ToolStrip no Windows Forms

Descreve várias maneiras de organizar ToolStripItems no ToolStrip.
Como: Alterar a aparência de texto e imagens de ToolStrip nos Windows Forms

Descreve como definir e modificar a disposição de texto e imagens em ToolStripItem
controles.
Como: Encapsular um controle do Windows Forms com ToolStripControlHost

Demonstra a hospedagem de um MonthCalendar controle em um ToolStripControlHost.

Windows Forms
Descreve como alcançar a pintura padrão e personalizada em ToolStrip controles.
Como: Personalizar o desenho de um controle ToolStrip

Descreve vários aspectos do desenho personalizado (proprietário) em ToolStrip
controles.
Como: Criar botões de alternância em controles ToolStrip

Descreve a criação de uma alternação ToolStripButton.
Como: Usar ToolTips em controles ToolStrip
Descreve a definição de dicas de ferramenta para ToolStrip itens.
Como: Remover um ToolStrip de um ToolStripContainer para um formulário

Descreve como ter um ToolStrip sem contêiner, mas um formulário.
Como: Posicionar um ToolStripItem em um ToolStrip

Descreve como posicionar um ToolStripButton on na extremidade mais à esquerda ou à
direita de um ToolStrip.
Como: Habilitar a tecla TAB para deixar um controle ToolStrip

Descreve como fazer a tabulação dentro de uma ToolStrip guia para o próximo controle
na ordem de tabulação.
Como: Detectar quando o ponteiro do mouse passa sobre um ToolStripItem

Descreve como configurar ToolStrip itens para que eles detectem quando o mouse está
sobre eles sem precisar sincronizar vários eventos do mouse.
Como: Criar um formulário MDI com controles ToolStripPanel

Descreve como criar um formulário MDI (interface de documento múltiplo) com
ToolStripPanel controles.
Como: Criar um formulário MDI com mesclagem de menu e controles ToolStrip

Descreve como criar um formulário MDI que dá suporte a controles e mesclagem
ToolStrip de menu.
Como: Criar um controle ToolStrip com estilo profissional

Descreve como usar a ToolStripProfessionalRenderer classe para criar um controle
composto que imita o Painel de Navegação fornecido pelo Microsoft® Outlook®.
Como: Implementar um ToolStripRenderer personalizado

Descreve como personalizar a aparência de um ToolStrip controle implementando uma
classe que deriva de ToolStripRenderer.
Como criar um ToolStrip básico dos Windows Forms com itens padrão usando o
designer
Como: Remover um ToolStrip de um ToolStripContainer para um formulário
Passo a passo: Criar um controle ToolStrip com estilo profissional
Passo a passo: Criar um formulário MDI com mesclagem de menu e controles

ToolStrip
Referência
Classe ToolStrip
ToolStrip
Descreve a classe ToolStrip e tem links a todos os seus membros.
ToolStripItem
Descreve a classe ToolStripItem e tem links a todos os seus membros.
(Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms ToolStrip e suas classes associadas fornecem uma estrutura
comum para combinar elementos de interface do usuário em barras de ferramentas,
barras de status e menus. ToolStrip os controles oferecem uma experiência avançada em
tempo de design que inclui ativação e edição in-loco, layout personalizado e rafting,
que é a capacidade das barras de ferramentas de compartilhar espaço horizontal ou
vertical.
Embora ToolStrip substitua e adicione funcionalidade ao controle em versões anteriores,

ToolBar é mantido para compatibilidade com versões anteriores e uso futuro, se
desejado.
Recursos dos controles ToolStrip

Use o ToolStrip controle para:
Apresente uma interface do usuário comum entre contêineres.
Crie barras de ferramentas facilmente personalizadas e comumente empregadas

que dão suporte a recursos avançados de interface do usuário e layout, como
encaixe, rafting, botões com texto e imagens, botões e controles suspensos,
botões de estouro e reordenação de itens em tempo de ToolStrip execução.
Dê suporte a reordenação de item de tempo de execução e estouro. O recurso de

estouro move os itens para um menu suspenso quando não há espaço suficiente
para exibi-los em um ToolStrip.
Dê suporte à aparência e ao comportamento típicos do sistema operacional por

meio de um modelo comum de renderização.
Manipule eventos de forma consistente em todos os contêineres e os itens

contidos da mesma forma que você manipula eventos para outros controles.
Arraste itens de um ToolStrip para outro ou dentro de um ToolStrip.
Crie controles suspensos e editores de tipo de interface do usuário com layouts

avançados em um ToolStripDropDown.
Use a ToolStripControlHost classe para usar outros controles em um ToolStrip e obter
ToolStrip funcionalidade para eles.
Você pode estender a funcionalidade e modificar a aparência e o comportamento

usando o ToolStripRenderer, ToolStripProfessionalRenderere ToolStripManager junto
com as ToolStripRenderMode enumerações.ToolStripManagerRenderMode
O ToolStrip controle é altamente configurável e extensível e fornece muitas

propriedades, métodos e eventos para personalizar a aparência e o comportamento.
Abaixo estão alguns membros importantes:
Membros importantes do ToolStrip
Nome Descrição
Dock Obtém ou define a qual borda do contêiner pai a ToolStrip está encaixada.
AllowItemReorder Obtém ou define um valor que indica se a operação do tipo "arrastar e

soltar" e a reordenação de itens são manipulados pela classe ToolStrip de
forma privada.
LayoutStyle Obtém ou define um valor que indica como os ToolStrip itens são
configurados.
Overflow Obtém ou define se um ToolStripItem está anexado ao ToolStrip ou

ToolStripOverflowButton pode flutuar entre os dois.
IsDropDown Obtém um valor que indica se um ToolStripItem exibe outros itens em uma
lista suspensa quando ele ToolStripItem é clicado.
OverflowButton Obtém o ToolStripItem que é o botão de estouro para um ToolStrip com o

estouro habilitado.
Renderer Obtém ou define um ToolStripRenderer usado para personalizar a aparência

e o comportamento (aparência) de um ToolStrip.
RenderMode Obtém ou define os estilos de pintura a serem aplicados ao ToolStrip.
RendererChanged Gerado quando a propriedade Renderer é alterada.
A ToolStrip flexibilidade do controle é obtida por meio do uso de várias classes

complementares. Abaixo estão algumas das mais importantes:
Classes complementares importantes do ToolStrip
Nome Descrição
Nome Descrição
MenuStrip Substitui e adiciona funcionalidade à MainMenu classe.
StatusStrip Substitui e adiciona funcionalidade à StatusBar classe.
ContextMenuStrip Substitui e adiciona funcionalidade à ContextMenu classe.
ToolStripItem Classe base abstrata que gerencia eventos e layout para todos
os elementos que um ToolStrip, ToolStripControlHostou
ToolStripDropDown pode conter.
ToolStripContainer Fornece um contêiner com um painel em cada lado do

formulário em que os controles podem ser organizados de
várias maneiras.
ToolStripRenderer Manipula a funcionalidade de pintura para objetos ToolStrip.
ToolStripProfessionalRenderer Fornece a aparência no estilo do Microsoft Office.
ToolStripManager Controla a renderização e o reposicionamento de ToolStrip e a

mesclagem de objetos MenuStrip, ToolStripDropDownMenu e
ToolStripMenuItem.
ToolStripManagerRenderMode Especifica o estilo de pintura (personalizado, Windows XP ou

Microsoft Office Professional) aplicado a vários ToolStrip objetos
contidos em um formulário.
ToolStripRenderMode Especifica o estilo de pintura (personalizado, Windows XP ou

Microsoft Office Professional) aplicado a um ToolStrip objeto
contido em um formulário.
ToolStripControlHost Hospeda outros controles que não são especificamente

ToolStrip controles, mas para os quais você deseja ToolStrip
funcionalidade.
ToolStripItemPlacement Especifica se um ToolStripItem deve ser disposto no principal

ToolStrip, no estouro ToolStripou nenhum dos dois.
Para obter mais informações, consulte Resumo da tecnologia de ToolStrip e Arquitetura

de controle ToolStrip.
Confira também
ToolStrip
MenuStrip
ContextMenuStrip
StatusStrip
ToolStripItem
ToolStripDropDown
Resumo da tecnologia de ToolStrip
Artigo • 21/06/2023
Este tópico resume as informações sobre o controle ToolStrip e as classes que dão
suporte ao seu uso.
O controle ToolStrip e suas classes associadas fornecem uma solução completa para a
criação de menus, barras de ferramentas e barras de status.
Namespaces
Segundo plano
Com o controle ToolStrip e suas classes associadas, você pode criar a funcionalidade
de ferramentas avançada com aparência e comportamento profissional e consistente. O
controle ToolStrip e as classes oferecem os seguintes aperfeiçoamentos em relação
aos controles anteriores:
Um modelo de evento mais consistente.
Um comportamento de tempo de design mais consistente que contém listas de

tarefas e editores de coleção de item.
Renderização personalizada com ToolStripManager e ToolStripRenderer .
Reposicionamento interno (compartilhamento de espaço horizontal ou vertical

dentro da área de ferramenta quando encaixado) com ToolStripContainer e
ToolStripPanel .
Tempo de design e reordenação em tempo de execução de itens com a

AllowItemReorder propriedade .
Realocação de itens para um menu de estouro com a CanOverflow propriedade .
Local do controle completamente configurável com ToolStripContainer ,

ToolStripPanel e ToolStripContentPanel .
Hospedagem controles ToolStrip , tradicionais ou personalizados usando

ToolStripControlHost .
Mesclagem de controles ToolStrip usando ToolStripPanel .
ToolStrip é a classe base extensível para MenuStrip , ContextMenuStrip e StatusStrip .

Esses controles são ToolStripItem contêineres que herdam o comportamento comum e
o tratamento de eventos, estendidos para que cada implementação lide com o
comportamento apropriado para ele. Os controles que derivam de ToolStripItem são
listados na tabela a seguir. A classe ToolStrip base manipula eventos do tipo "arrastar e
soltar", entrada do usuário e pintura para esses controles.
Os controles ToolStrip , MenuStrip , ContextMenuStrip e StatusStrip substituem a barra

de ferramentas anterior, menu, menu de atalho e controles da barra de status, embora
esses controles sejam mantidos para compatibilidade com versões anteriores.
Visão geral das classes de ToolStrip

A tabela a seguir mostra as classes de ToolStrip agrupadas por área de tecnologia.
Área de tecnologia Classe
Contêineres de Menu, status e barra de ferramentas ToolStrip
MenuStrip
ContextMenuStrip
StatusStrip
ToolStripDropDownMenu
Área de tecnologia Classe
Itens de ToolStrip ToolStripLabel
ToolStripDropDownItem
ToolStripMenuItem
ToolStripButton
ToolStripSeparator
ToolStripControlHost
ToolStripComboBox
ToolStripTextBox
ToolStripDropDownButton
ToolStripSplitButton
Localização ToolStripContainer
ToolStripContentPanel
ToolStripPanel
Apresentação e renderização ToolStripManager
ToolStripRenderer
ToolStripProfessionalRenderer
ToolStripRenderMode
ToolStripManagerRenderMode
Recursos de tempo de design de ToolStrip

A ToolStrip família de controles fornece um conjunto avançado de ferramentas e
modelos para edição in-loco e definição da base da interface do usuário para que você
possa criar rapidamente um aplicativo em funcionamento.
Caixas de diálogo da tarefa
No Visual Studio, clicar na smart tag em um controle no designer exibe uma lista de
tarefas para ter acesso fácil a muitos comandos usados com frequência.
Caixa de diálogo de tarefas do MenuStrip
Caixa de diálogo de tarefas ToolStrip
Caixa de diálogo de tarefas do ContextMenuStrip
StatusStrip (caixa de diálogo Tarefas)
Caixa de diálogo de tarefas do ToolStripContainer
Editores de coleção de itens

No Visual Studio, quando você clica em Editar itens na lista de tarefas ou clica com o
botão direito do mouse no controle e seleciona Editar Itens no menu de atalho, o editor
de coleção para o controle é exibido. Editores de coleção permitem adicionar, remover e
reordenar os itens que o controle contém. Você também pode exibir e alterar as
propriedades para o controle e os itens do controle.
Editor de coleção de itens do MenuStrip
StatusStrip (Editor de Coleção de Itens)
Editor de coleção de itens ContextMenuStrip
Editor de Coleção de Itens de ToolStrip
Hospedagem de controles
A ToolStripControlHost classe fornece wrappers internos para
ToolStripComboBoxcontroles , ToolStripTextBoxe ToolStripProgressBar . Você também
pode hospedar qualquer outro controle COM ou existente em um ToolStripControlHost.
Para um exemplo de hospedagem de controle, consulte Como encapsular um controle

dos Windows Forms com ToolStripControlHost.
Renderização
ToolStripas classes implementam um esquema de renderização que é significativamente
diferente de outros controles Windows Forms. Com esse esquema, você pode
facilmente aplicar estilos e temas.
Para aplicar um estilo a um ToolStrip e a todos os ToolStripItem objetos que ele contém,
você não precisa manipular o Paint evento para cada item. Em vez disso, você pode
definir a RenderMode propriedade como um dos ToolStripRenderMode valores
diferentes de Custom. Como alternativa, você pode definir o Renderer diretamente para
qualquer classe que herde da ToolStripRenderer classe . Definir essa propriedade define
automaticamente o RenderMode.
Você pode aplicar o mesmo estilo a vários ToolStrip objetos no mesmo aplicativo
definindo como RenderModeManagerRenderMode e definindo a RenderMode
propriedade ou Renderer como ToolStripManagerRenderMode que você deseja ou
ToolStripRenderer valor, respectivamente.
Para exemplos de renderização, consulte Como criar e definir um renderizador

personalizado para o controle ToolStrip nos Windows Forms.
Estilos e temas
ToolStrip E as classes associadas fornecem uma maneira fácil de dar suporte a estilos
visuais e aparência personalizada que não exigem a substituição dos OnPaint métodos
para cada item. Use as DisplayStyleRenderMode propriedades e e Renderer .
Reposicionamento e encaixe
Você pode fazer raft, encaixar ou posicionar ToolStrip controles absolutamente. ToolStrip
os itens são dispostos pelo LayoutEngine do contêiner.
O reposicionamento é a capacidade das barras de ferramenta de compartilhar espaço

horizontal ou vertical. Um formulário do Windows pode ter um ToolStripContainer que,
por sua vez, tem painéis nos lados esquerdo, direito, superior e inferior do formulário
para posicionamento e rafting ToolStripde controles , MenuStripe StatusStrip . Vários
ToolStrip controles são empilhados verticalmente se você colocá-los à esquerda ou à
direita ToolStripContainer. Eles são empilhados horizontalmente se você colocá-los na
parte superior ou inferior ToolStripContainer. Você pode usar a central
ToolStripContentPanel do para posicionar controles ToolStripContainer tradicionais no
formulário.
Todos ou todos os ToolStripContainer controles podem ser selecionados diretamente

em tempo de design e podem ser excluídos. Um ToolStripContainer é expansível e
recolhível e redimensiona com os controles que ele contém.
O encaixe é a especificação do local simples de um controle no lado esquerdo, direito,
superior ou inferior do formulário.
A vantagem do rafting sobre o encaixe é que ToolStripos controles , MenuStripe

StatusStrip podem compartilhar espaço horizontal ou vertical com outros controles.
A maioria dos ToolStrip controles pode ser encaixada no formulário, como outros
controles, em vez de usar rafting. Você também pode especificar que um ToolStrip
controle seja posicionado livremente no formulário removendo-o de sua
ToolStripContainer propriedade e definindo sua Dock propriedade None como ou pode
especificar sua posição absoluta definindo a respectiva Location propriedade. Consulte
Como remover um ToolStrip de um ToolStripContainer para um formulário.
Use um ou mais ToolStripPanel controles para obter mais flexibilidade, especialmente

para aplicativos MDI (Interface de Vários Documentos) ou se você não precisar de um
ToolStripContainer. Um ToolStripPanel fornece um espaço encaixável para localizar e
colocar controles de rafting ToolStrip , mas não controles tradicionais. Por padrão, o
ToolStripPanel não aparece na Caixa de Ferramentas do designer, mas você pode
colocá-lo lá clicando com o botão direito do mouse na Caixa de Ferramentas e clicando
em Escolher Itens. Você também pode acessar programaticamente o ToolStripPanel
como qualquer outra classe.
Os ToolStripitens , MenuStripe StatusStrip permitem estouro de itens. Isso é semelhante

à forma como esses itens se comportam em barras de ferramentas do Microsoft Office.
Confira também
Arquitetura de controle ToolStrip
Artigo • 21/06/2023
As ToolStrip classes e ToolStripItem fornecem um sistema flexível e extensível para exibir itens
de barra de ferramentas, status e menu. Todas essas classes estão contidas no
System.Windows.Forms namespace e normalmente são nomeadas com o prefixo "ToolStrip"
(como ToolStripOverflow) ou com o sufixo "Strip" (como MenuStrip).
ToolStrip
Os tópicos a seguir descrevem ToolStrip e os controles que derivam dele.
ToolStrip é a classe base abstrata para MenuStrip, StatusStripe ContextMenuStrip. O modelo

de objeto a seguir mostra a hierarquia de ToolStrip herança.
Você pode acessar todos os itens em um ToolStrip por meio da Items coleção. Você pode
acessar todos os itens em um ToolStripDropDownItem por meio da DropDownItems coleção.
Em uma classe derivada de ToolStrip, você também pode usar a DisplayedItems propriedade
para acessar apenas os itens exibidos no momento. Estes são os itens que não estão
atualmente em um menu de estouro.
Os itens a seguir foram projetados especificamente para funcionar perfeitamente com e

ToolStripSystemRendererToolStripProfessionalRenderer em todas as orientações. Eles estão
disponíveis por padrão em tempo de design para o ToolStrip controle:
ToolStripButton
ToolStripSeparator
ToolStripLabel
ToolStripTextBox
ToolStripComboBox
MenuStrip
MenuStrip é o contêiner de nível superior que substitui MainMenu. Ele também oferece os
recursos de manipulação de chaves e MDI (interface de múltiplos documentos).
Funcionalmente e ToolStripDropDownItemToolStripMenuItem funcionam junto com
MenuStrip, embora sejam derivados de ToolStripItem.

disponíveis por padrão em tempo de design para o MenuStrip controle:
ToolStripMenuItem
ToolStripTextBox
ToolStripComboBox
StatusStrip
StatusStrip substitui o StatusBar controle . Os recursos especiais de incluem um layout de
StatusStrip tabela personalizado, suporte para dimensionamento e movimentação de alças do
formulário e a Spring propriedade , que permite que um ToolStripStatusLabel preencha o
espaço disponível automaticamente.

disponíveis por padrão em tempo de design para o StatusStrip controle:
ContextMenuStrip
O ContextMenuStrip substitui o ContextMenu. Você pode associar um ContextMenuStrip a
qualquer controle e um clique com o botão direito do mouse exibe automaticamente o menu
de contexto (ou menu de atalho). Você pode mostrar um ContextMenuStrip
programaticamente usando o Show método . ContextMenuStripdá suporte a eventos e
Closing canceláveis Opening para lidar com a população dinâmica e cenários de vários cliques.
ContextMenuStripdá suporte a imagens, item de menu marcar estado, texto, teclas de acesso,
atalhos e menus em cascata.
disponíveis por padrão em tempo de design para o ContextMenuStrip controle:
ToolStripMenuItem
ToolStripSeparator
ToolStripTextBox
ToolStripComboBox
Recursos genéricos de ToolStrip

Os tópicos a seguir descrevem recursos e comportamentos genéricos para os ToolStrip
controles derivados e .
Pintura
Você pode fazer pintura personalizada em ToolStrip controles de várias maneiras. Assim como
acontece com outros controles Windows Forms, e ToolStripToolStripItem ambos têm métodos
e Paint eventos substituíveis OnPaint . Assim como ocorre com pintura regular, o sistema de
coordenadas é relativo à área de cliente do controle, ou seja, o canto superior esquerdo do
controle é 0, 0. O Paint evento e OnPaint o método para um ToolStripItem se comportam
como outros eventos de pintura de controle.
Os ToolStrip controles também fornecem acesso mais fino à renderização dos itens e do
contêiner por meio da classe , que tem métodos substituíveis para pintar a tela de fundo, o
plano de fundo do item, a imagem do item, a seta do item, o ToolStripRenderer texto do item
e a borda do ToolStrip. Os argumentos de evento para esses métodos expõem várias
propriedades como retângulos, cores e formatos de texto que você pode ajustar conforme
desejado.
Para ajustar apenas alguns aspectos de como um item é pintado, você normalmente substitui
o ToolStripRenderer.
Se você estiver escrevendo um novo item e desejar controlar todos os aspectos de pintura,
substitua o método OnPaint . De dentro OnPaint do , você pode usar métodos do
ToolStripRenderer.
Por padrão, o ToolStrip é armazenado em buffer duplo, aproveitando a

OptimizedDoubleBuffer configuração.
Gerenciamento do domínio pai

O conceito de propriedade e criação de contêiner é mais complexo em ToolStrip controles do
que em outros controles de contêiner Windows Forms. Isso é necessário para dar suporte a
cenários dinâmicos, como estouro, compartilhamento de itens suspensos em vários ToolStrip
itens e para dar suporte à geração de um ContextMenuStrip de um controle.
A lista a seguir descreve os membros relacionados ao gerenciamento do domínio pai e explica

o seu uso.
OwnerItem acessa o item que é a origem do item suspenso. Isso é semelhante a

SourceControl, mas em vez de retornar um controle , ele retorna um ToolStripItem.
SourceControl determina qual controle é a origem do ContextMenuStrip quando vários

controles compartilham o mesmo ContextMenuStrip.
GetCurrentParent é um acessador somente leitura para a Parent propriedade . Um pai

difere de um proprietário em que um pai denota a corrente ToolStrip retornada na qual o
item é exibido, que pode estar na área de estouro.
Owner retorna o ToolStrip cuja coleção Items contém o atual ToolStripItem. Essa é a
melhor maneira de referenciar ImageList ou outras propriedades no nível ToolStrip
superior sem escrever código especial para lidar com o estouro.
Comportamento de controles herdados

Os seguintes controles são bloqueados sempre que eles são usados em herança:
ToolStrip
MenuStrip
ContextMenuStrip
StatusStrip
ToolStripPanel que inclui os painéis em um ToolStripContainer e também controles

individuais ToolStripPanel .
Por exemplo, crie um novo aplicativo dos Windows Forms usando um ou mais dos controles
na lista anterior. Defina o modificador de acesso de um ou mais controles para public ou
protected e, em seguida, compile o projeto. Adicione um formulário que herda do primeiro
formulário e, em seguida, selecione um controle herdado. O controle aparece bloqueado,

comportando-se como se o seu modificador de acesso fosse private .
Suporte Herança de ToolStripContainer
O ToolStripContainer controle dá suporte a cenários herdados limitados, semelhantes ao

exemplo a seguir:
1. Crie um novo aplicativo Windows Forms.
2. Adicione um ToolStripContainer ao formulário.
3. Defina o modificador de acesso do ToolStripContainer como public ou protected .
4. Adicione qualquer combinação de ToolStripcontroles , MenuStripe ContextMenuStrip às

ToolStripPanel regiões do ToolStripContainer.
6. Adicione um formulário que herda do primeiro formulário.
7. Selecione o herdado ToolStripContainer no formulário.
Comportamento herdado de controles filho

Depois de você concluir as etapas anteriores, ocorre o seguinte comportamento herdado:
No designer, o controle aparece com um ícone herdado.
Os ToolStripPanel controles estão bloqueados; você não pode selecionar ou reorganizar

seu conteúdo.
Você pode adicionar controles ao ToolStripContentPanel, mover os controles e torná-los

controles filho do ToolStripContentPanel.
Suas alterações persistem após compilar o formulário.
７ Observação
Remova os modificadores de acesso de todos os ToolStripPanel controles que

fazem parte de um ToolStripContainer. O modificador de acesso do
ToolStripContainer controla todo o controle.
Confiança parcial
As limitações de ToolStrip s sob confiança parcial são projetadas para impedir entrada
acidental de informações pessoais que possam ser usadas por pessoas ou serviços não
autorizados. As medidas de proteção são as seguintes:
ToolStripDropDown os controles exigem AllWindows a exibição de itens em um
ToolStripControlHost. Isso se aplica a controles intrínsecos, como ToolStripTextBox,

ToolStripComboBoxe ToolStripProgressBar , bem como a controles criados pelo usuário.
Se esse requisito não for atendido, esses itens não serão exibidos. Nenhuma exceção é
gerada.
A configuração da AutoClose propriedade false como não é permitida e o parâmetro
de evento cancelável Closing é ignorado. Isso torna impossível realizar mais de um
pressionamento da tecla sem fechar o item suspenso. Se esse requisito não for atendido,
esses itens não serão exibidos. Nenhuma exceção é gerada.
Muitos eventos de manipulação de pressionamento de tecla não serão gerados se

ocorrerem em contextos de confiança parcial diferentes de AllWindows.
As chaves de acesso não são processadas quando AllWindows não é concedida.
Uso
Os seguintes padrões de uso têm uma influência no layout, na interação do teclado e no

ToolStrip comportamento do usuário final:
Ingressado em um ToolStripPanel
O ToolStrip pode ser reposicionado dentro do ToolStripPanel e entre ToolStripPanels. A

Dock propriedade é ignorada e, se a Stretch propriedade for false , o tamanho do
ToolStrip aumenta à medida que os itens são adicionados ao ToolStripPanel.

Normalmente, o ToolStrip não participa da ordem de tabulação.
Encaixado
O ToolStrip é colocado em um lado de um contêiner em uma posição fixa e seu tamanho

se expande sobre toda a borda à qual está encaixado. Normalmente, o ToolStrip não
participa da ordem de tabulação.
Posição absoluta
O ToolStrip é como outros controles, pois é colocado pela Location propriedade , tem
um tamanho fixo e normalmente participa da ordem de tabulação.
Interação do teclado
Teclas de acesso
Combinadas com ou após a tecla ALT, as teclas de acesso são uma maneira de ativar um
controle usando o teclado. ToolStrip dá suporte a chaves de acesso explícitas e implícitas. A
definição explícita usa um caractere de e comercial (&) anterior à letra. A definição implícita
usa um algoritmo que tenta encontrar um item correspondente com base na ordem de
caracteres em uma determinada propriedade Text .
Teclas de Atalho
As teclas de atalho usadas por um MenuStrip usam uma combinação da Keys enumeração
(que não é específica da ordem) para definir a tecla de atalho. Você também pode usar a
ShortcutKeyDisplayString propriedade para exibir uma tecla de atalho somente com texto,
como exibir "Del" em vez de "Excluir".
Navegação
A chave ALT ativa o MenuStrip apontado por MainMenuStrip. A partir daí, CTRL+TAB navega
entre ToolStrip controles dentro ToolStripPanel de s. A tecla TAB e as teclas de direção no
teclado numérico navegam entre itens em um ToolStrip. Um algoritmo especial manipula a
navegação na região de estouro. A BARRA DE ESPAÇOS seleciona um ToolStripButton,
ToolStripDropDownButtonou ToolStripSplitButton.
Foco e validação
Quando ativado pela tecla ALT, o MenuStrip ou ToolStrip normalmente não leva nem remove o
foco do controle que atualmente tem o foco. Se houver um controle hospedado no MenuStrip
ou uma lista suspensa do MenuStrip, o controle ganhará foco quando o usuário pressionar a
tecla TAB. Em geral, os GotFocuseventos , LostFocus, Entere Leave de MenuStrip podem não
ser gerados quando são ativados pelo teclado. Nesses casos, use os MenuActivate eventos e
MenuDeactivate .
Por padrão, CausesValidation é false . Chame Validate explicitamente em seu formulário para
executar a validação.
Layout
Você controla ToolStrip o layout escolhendo um dos membros do ToolStripLayoutStyle com a

LayoutStyle propriedade .
Layouts de pilha
O empilhamento é a organização de itens um ao lado do outro nas duas extremidades do

ToolStrip. A lista a seguir descreve os layouts de pilha.
StackWithOverflow é o padrão. Essa configuração faz com que o ToolStrip altere seu
layout automaticamente de acordo com a Orientation propriedade para lidar com
cenários de arrastar e encaixar.
VerticalStackWithOverflow renderiza os ToolStrip itens um ao lado do outro

verticalmente.
HorizontalStackWithOverflow renderiza os ToolStrip itens um ao lado do outro

horizontalmente.
Outros recursos de layouts de pilha
Alignment determina o final do ToolStrip ao qual o item está alinhado.
Quando os itens não cabem no ToolStrip, um botão de estouro é exibido automaticamente. A

Overflow configuração da propriedade determina se um item aparece na área de estouro
sempre, conforme necessário, ou nunca.
LayoutCompleted No caso, você pode inspecionar a Placement propriedade para determinar

se um item foi colocado no main ToolStrip, no estouro ToolStripou se ele não está sendo
exibido no momento. Os motivos típicos pelos quais um item não é exibido são que o item
não se encaixava no main ToolStrip e sua Overflow propriedade foi definida Nevercomo .
Torne um ToolStrip móvel colocando-o em um ToolStripPanel e definindo-o GripStyle como

Visible.
Outras opções de layout
As outras opções de layout são Flow e Table.
Layout de fluxo
Flow layout é o padrão para ContextMenuStrip, ToolStripDropDownMenue ToolStripOverflow.

É semelhante ao FlowLayoutPanel. Os recursos de Flow layout são os seguintes:
Todos os recursos de FlowLayoutPanel são expostos pela LayoutSettings propriedade .

Você deve converter a LayoutSettings classe em uma FlowLayoutSettings classe.
Você pode usar as Dock propriedades e Anchor no código para alinhar os itens dentro
da linha.
A propriedade Alignment é ignorada.
LayoutCompleted No caso, você pode inspecionar a Placement propriedade para

determinar se um item foi colocado no main ToolStrip ou não se encaixava.
A alça não é renderizada e, portanto, um ToolStrip no Flow estilo de layout em um

ToolStripPanel não pode ser movido.
O ToolStrip botão de estouro não é renderizado e Overflow é ignorado.
Layout da tabela
Table layout é o padrão para StatusStrip. É semelhante a TableLayoutPanel. Os recursos de

Flow layout são os seguintes:
Todos os recursos de TableLayoutPanel são expostos pela LayoutSettings propriedade .
Você deve converter a LayoutSettings classe em uma TableLayoutSettings classe.
Você pode usar as Dock propriedades e Anchor no código para alinhar os itens dentro
da célula da tabela.
A propriedade Alignment é ignorada.
LayoutCompleted No caso, você pode inspecionar a Placement propriedade para

determinar se um item foi colocado no main ToolStrip ou não se encaixava.
A alça não é renderizada e, portanto, um ToolStrip no Table estilo de layout em um

ToolStripPanel não pode ser movido.
O ToolStrip botão de estouro não é renderizado e Overflow é ignorado.
ToolStripItem
Os tópicos a seguir descrevem ToolStripItem e os controles que derivam dele.
ToolStripItem é a classe base abstrata para todos os itens que entram em um ToolStrip. O
modelo de objeto a seguir mostra a hierarquia de ToolStripItem herança.
ToolStripItemas classes herdam diretamente de ToolStripItemou herdam indiretamente de por

meio ToolStripControlHost de ToolStripItem ou ToolStripDropDownItem.
ToolStripItem os controles devem estar contidos em um ToolStrip, MenuStrip, StatusStripou

ContextMenuStrip e não podem ser adicionados diretamente a um formulário. As várias
classes de contêiner foram projetadas para conter um subconjunto apropriado de
ToolStripItem controles.
A tabela a seguir lista os controles de estoque ToolStripItem e os contêineres nos quais eles
têm a melhor aparência. Embora qualquer ToolStrip item possa ser hospedado em qualquer
ToolStripcontêiner derivado, esses itens foram projetados para ter a melhor aparência nos
seguintes contêineres:
７ Observação
ToolStripDropDown não aparece na caixa de ferramentas do designer.
Item contido ToolStrip MenuStrip ContextMenuStrip StatusStrip ToolStripDropDown
ToolStripButton Sim Não Não Não Sim
ToolStripComboBox Sim Sim Sim Não Sim
ToolStripSplitButton Sim Não Não Sim Sim
ToolStripLabel Sim Não Não Sim Sim
ToolStripSeparator Sim Sim Sim Não Sim
ToolStripDropDownButton Sim Não Não Sim Sim
ToolStripTextBox Sim Sim Sim Não Sim
ToolStripMenuItem Não Sim Sim Não Não
ToolStripStatusLabel Não Não Não Sim Não
ToolStripProgressBar Sim Não Não Sim Não
ToolStripControlHost Sim Sim Não Sim Sim
ToolStripButton
ToolStripButton é o item de botão para ToolStrip. Você pode exibi-lo com vários estilos de
borda e pode usá-lo para representar e ativar estados operacionais. Você também pode
defini-lo para ter o foco por padrão.
ToolStripLabel
O ToolStripLabel fornece funcionalidade de rótulo em ToolStrip controles. O ToolStripLabel é
como um ToolStripButton que não obtém o foco por padrão e que não é renderizado como
enviado por push ou realçado.
ToolStripLabel como um item hospedado dá suporte a chaves de acesso.

Use as LinkColorpropriedades , LinkVisitede LinkBehavior em um ToolStripLabel para dar
suporte ao controle de link em um ToolStrip.
ToolStripStatusLabel é uma versão do ToolStripLabel projetada especificamente para uso no
StatusStrip. Os recursos especiais incluem BorderStyle, BorderSidese Spring.
ToolStripSeparator
O ToolStripSeparator adiciona uma linha vertical ou horizontal a uma barra de ferramentas ou
menu, dependendo da orientação. Ele fornece o agrupamento de ou a distinção entre itens,
assim como aqueles em um menu.
Você pode adicionar um ToolStripSeparator em tempo de design escolhendo-o em uma lista

suspensa. No entanto, você também pode criar automaticamente um ToolStripSeparator
digitando um hífen (-) no nó de modelo do designer ou no Add método .
ToolStripControlHost é a classe base abstrata para ToolStripComboBox, ToolStripTextBoxe
ToolStripProgressBar. ToolStripControlHost pode hospedar outros controles, incluindo
controles personalizados, de duas maneiras:
Construa um ToolStripControlHost com uma classe derivada de Control. Para acessar

totalmente o controle e as propriedades hospedados, você deve converter a Control
propriedade de volta para a classe real que ela representa.
Estenda ToolStripControlHoste, no construtor sem parâmetros da classe herdada, chame

o construtor de classe base passando uma classe derivada de Control. Essa opção
permite encapsular métodos e propriedades de controle comuns para facilitar o acesso
em um ToolStrip.
ToolStripComboBox
ToolStripComboBox é o ComboBox otimizado para hospedagem em um ToolStrip. Um
subconjunto das propriedades e eventos do controle hospedado são expostos no
ToolStripComboBox nível, mas o controle subjacente ComboBox é totalmente acessível por
meio da ComboBox propriedade .
ToolStripTextBox
ToolStripTextBox é o TextBox otimizado para hospedagem em um ToolStrip. Um subconjunto
das propriedades e eventos do controle hospedado são expostos no ToolStripTextBox nível,
mas o controle subjacente TextBox é totalmente acessível por meio da TextBox propriedade .
ToolStripProgressBar é o ProgressBar otimizado para hospedagem em um ToolStrip. Um
subconjunto das propriedades e eventos do controle hospedado são expostos no
ToolStripProgressBar nível, mas o controle subjacente ProgressBar é totalmente acessível por
meio da ProgressBar propriedade .
ToolStripDropDownItem
ToolStripDropDownItem é a classe base abstrata para ToolStripMenuItem,
ToolStripDropDownButtone ToolStripSplitButton, que pode hospedar itens diretamente ou
hospedar itens adicionais em um contêiner suspenso. Faça isso definindo a DropDown
propriedade como um ToolStripDropDown e definindo a Items propriedade do
ToolStripDropDown. Acesse esses itens suspensos diretamente por meio da DropDownItems
propriedade .
ToolStripMenuItem
ToolStripMenuItem é um ToolStripDropDownItem que funciona com ToolStripDropDownMenu
e ContextMenuStrip para manipular o realce especial, o layout e a disposição de coluna para
menus.
ToolStripDropDownButton se parece ToolStripButtoncom , mas mostra uma área suspensa
quando o usuário clica nela. Ocultar ou mostrar a seta suspensa definindo a
ShowDropDownArrow propriedade . ToolStripDropDownButton hospeda um
ToolStripOverflowButton que exibe itens que transbordam o ToolStrip.
ToolStripSplitButton combina a funcionalidade do botão e do botão suspenso.
Use a DefaultItem propriedade para sincronizar o Click evento do item suspenso escolhido
com o item mostrado no botão.
Recursos genéricos de ToolStripItem

ToolStripItem fornece os seguintes recursos genéricos e opções para herdar controles:
Eventos principais
Tratamento de imagem
Alinhamento
Relação de texto e imagem
Estilo de exibição
Eventos Principais
ToolStripItem os controles recebem seus próprios eventos de clique, mouse e pintura e

também podem executar alguns pré-processamentos de teclado.
Tratamento de Imagem
As Imagepropriedades , ImageAlign, ImageIndex, ImageKeye ImageScaling pertencem a vários
aspectos do tratamento de imagem. Use imagens em ToolStrip controles definindo essas
propriedades diretamente ou definindo a propriedade somente ImageList em tempo de
execução.
O dimensionamento de imagens é determinado pela interação das propriedades em ToolStrip

e ToolStripItem, da seguinte maneira:
ImageScalingSize é a escala da imagem final, conforme determinado pela combinação da

configuração da ImageScaling imagem e da configuração do AutoSize contêiner.
Se AutoSize for true (o padrão) e ToolStripItemImageScaling for SizeToFit, nenhum

dimensionamento de imagem ocorrerá e o ToolStrip tamanho for o do maior item ou
um tamanho mínimo prescrito.
Se AutoSize for false e ToolStripItemImageScaling for None, nem a imagem nem

ToolStrip o dimensionamento ocorrerão.
Alinhamento
O valor da Alignment propriedade determina o final do ToolStrip no qual um item é exibido. A

Alignment propriedade funciona somente quando o estilo de layout do ToolStrip é definido
como um dos valores de estouro de pilha.
Os itens são colocados no ToolStrip na ordem em que os itens aparecem na coleção Items.
Para alterar programaticamente onde um item é disposto, use o Insert método para mover o
item na coleção. Esse método move o item, mas não o duplica.
Relação de Texto e Imagem

A TextImageRelation propriedade define o posicionamento relativo da imagem em relação ao
texto em um ToolStripItem. Itens que não têm uma imagem, texto ou ambos são tratados
como casos especiais para que o ToolStripItem não exiba um ponto em branco para o
elemento ou elementos ausentes.
Estilo de Exibição
DisplayStyle permite que você defina os valores das propriedades Text e Image de um item
enquanto exibe apenas o que você deseja. Isso normalmente é usado para alterar o estilo de
exibição ao mostrar o mesmo item em um contexto diferente.
Classes acessórias
Classes que fornecem várias outras funcionalidades incluem:
ToolStripManager dá suporte a tarefas relacionadas a aplicativos inteiros, como

mesclagem ToolStrip, configurações e opções de renderizador.
ToolStripRenderer permite que você aplique um estilo ou tema específico a um ToolStrip

facilmente.
ToolStripProfessionalRenderer cria canetas e pincéis com base em uma tabela de cores

substituível (ProfessionalColorTable).
ToolStripSystemRenderer aplica cores do sistema e um estilo visual simples aos ToolStrip

aplicativos.
ToolStripContainer é semelhante a SplitContainer. Ele usa quatro painéis laterais

encaixados (instâncias de ToolStripPanel) e um painel central (uma instância de
ToolStripContentPanel) para criar uma organização típica. Não é possível remover os
painéis laterais, mas você pode ocultá-los. Não é possível remover nem ocultar o painel
central. Você pode organizar um ou mais ToolStripcontroles , MenuStripou StatusStrip
nos painéis laterais e pode usar o painel central para outros controles. O
ToolStripContentPanel também fornece uma maneira de obter suporte ao renderizador
no corpo do formulário para uma aparência consistente. ToolStripContainer não dá
suporte a MDI (interface de vários documentos).
ToolStripPanel fornece espaço para mover e organizar ToolStrip controles. Você só

poderá usar um painel se assim escolher e ToolStripPanel funcionar bem em cenários de
MDI.
Confira também
Controle ToolStrip
Controle MenuStrip
Como: Adicionar itens do ToolStrip de
forma dinâmica
Artigo • 21/06/2023
Você pode preencher dinamicamente a coleção de itens de menu de um ToolStrip

controle quando o menu for aberto.
Exemplo
O exemplo de código a seguir demonstra como adicionar dinamicamente itens a um
ContextMenuStrip controle. O exemplo também mostra como reutilizar o mesmo
ContextMenuStrip para três controles diferentes no formulário.
No exemplo, um Opening manipulador de eventos preenche a coleção de itens de

menu. O Opening manipulador de eventos examina as ContextMenuStrip.SourceControl
propriedades e ToolStripItem.OwnerItem e adiciona um ToolStripItem que descreve o
controle do código-fonte.
C#
using System;
C#
// This code example demonstrates how to handle the Opening event.

// It also demonstrates dynamic item addition and dynamic
// SourceControl determination with reuse.
class Form3 : Form
{
// Declare the ContextMenuStrip control.
private ContextMenuStrip fruitContextMenuStrip;
public Form3()
{
fruitContextMenuStrip = new ContextMenuStrip();
// Attach an event handler for the

// ContextMenuStrip control's Opening event.
fruitContextMenuStrip.Opening += new
System.ComponentModel.CancelEventHandler(cms_Opening);
// Create a new ToolStrip control.
ToolStrip ts = new ToolStrip();
// Create a ToolStripDropDownButton control and add it

// to the ToolStrip control's Items collections.
ToolStripDropDownButton fruitToolStripDropDownButton = new
ToolStripDropDownButton("Fruit", null, null, "Fruit");
ts.Items.Add(fruitToolStripDropDownButton);
// Dock the ToolStrip control to the top of the form.

ts.Dock = DockStyle.Top;
// Assign the ContextMenuStrip control as the

// ToolStripDropDownButton control's DropDown menu.
fruitToolStripDropDownButton.DropDown = fruitContextMenuStrip;
// Create a new MenuStrip control and add a ToolStripMenuItem.

ToolStripMenuItem fruitToolStripMenuItem = new
ToolStripMenuItem("Fruit", null, null, "Fruit");
ms.Items.Add(fruitToolStripMenuItem);

// Assign the MenuStrip control as the

// ToolStripMenuItem's DropDown menu.
fruitToolStripMenuItem.DropDown = fruitContextMenuStrip;
// Assign the ContextMenuStrip to the form's

// ContextMenuStrip property.
this.ContextMenuStrip = fruitContextMenuStrip;
// Add the ToolStrip control to the Controls collection.

this.Controls.Add(ts);
//Add a button to the form and assign its ContextMenuStrip.

Button b = new Button();
b.Location = new System.Drawing.Point(60, 60);
this.Controls.Add(b);
b.ContextMenuStrip = fruitContextMenuStrip;
// Add the MenuStrip control last.

}
// This event handler is invoked when the ContextMenuStrip

// control's Opening event is raised. It demonstrates
// dynamic item addition and dynamic SourceControl
// determination with reuse.
void cms_Opening(object sender, System.ComponentModel.CancelEventArgs e)
{
// Acquire references to the owning control and item.
Control c = fruitContextMenuStrip.SourceControl as Control;
ToolStripDropDownItem tsi = fruitContextMenuStrip.OwnerItem as
ToolStripDropDownItem;
// Clear the ContextMenuStrip control's Items collection.

fruitContextMenuStrip.Items.Clear();
// Check the source control first.

if (c != null)
{
// Add custom item (Form)
c.GetType().ToString());
}
else if (tsi != null)
{
// Add custom item (ToolStripDropDownButton or
ToolStripMenuItem)
tsi.GetType().ToString());
}
// Populate the ContextMenuStrip control with its default items.

fruitContextMenuStrip.Items.Add("-");
fruitContextMenuStrip.Items.Add("Apples");
fruitContextMenuStrip.Items.Add("Oranges");
fruitContextMenuStrip.Items.Add("Pears");
// Set Cancel to false.

// It is optimized to true based on empty entry.
e.Cancel = false;
}
}
Referências aos assemblies System.Drawing e System.Windows.Forms.
Confira também
ContextMenuStrip
MenuStrip
ToolStrip
ToolStripItem
ToolStripMenuItem
Controle ToolStrip
Como criar um ToolStrip básico dos
Windows Forms com itens padrão
usando o designer
Artigo • 02/06/2023
O procedimento a seguir demonstra como criar e ToolStrip adicionar sete

ToolStripButton controles que representam tarefas típicas.
Para adicionar itens padrão no designer

1. Crie um ToolStrip controle.
2. No canto superior direito da ToolStripseta de tarefa inteligente para exibir o painel

Tarefas do ToolStrip .
3. No painel Tarefas do ToolStrip , escolha Inserir Itens Padrão.
Confira também
ToolStrip
Controle ToolStrip
Como: Criar um controle ToolStrip com
estilo profissional
Artigo • 02/06/2023
Você pode dar aos controles do ToolStrip seu aplicativo uma aparência profissional e um
comportamento (aparência) escrevendo sua própria classe derivada do
ToolStripProfessionalRenderer tipo.
Há amplo suporte para esse recurso no Visual Studio.
Confira passo a passo: criando um controle ToolStrip com estilo profissional.
Exemplo
O exemplo de código a seguir demonstra como usar ToolStrip controles para criar um
controle composto que imita o Painel de Navegação fornecido pelo Microsoft®
Outlook®.
C#
using System;
using System.Drawing.Drawing2D;
using System.IO;
namespace StackViewCS
{
public class StackView : UserControl
{
private ToolStrip stackStrip;
private ToolStripButton mailStackButton;
private ToolStripButton calendarStackButton;
private ToolStripButton contactsStackButton;
private ToolStripButton tasksStackButton;
private static Bitmap mailBmp;

private static Bitmap calendarBmp;
private static Bitmap contactsBmp;
private static Bitmap tasksBmp;
private static string mailBmpEnc = @"Qk32BgAAAAAAADYAAAAoAAAA"+

"GAAAABgAAAABABgAAAAAAAAAAADEDgAAxA4AAAAAAAAAAAAA7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7uv4yFvouE"+
"vYmDu4eBuYV/t4N9tYB7s355sXt3tntxsnhwsHZurXNsrHFrp21pomln"+
"oGdlnmVjnWNi7u7u7u7u7u7u7u7u7u7uwY6H9N3C/vDa/ejM+tSp+cye"+
"98OS9bqI87F/87KA8qt68KRy76Bu7phl7ZVi7JVi54xb0ntSoGVj7u7u"+
"7u7u7u7u7u7u7u7uwo+Ix6WZ9ujb//bn/u/b/OfL++HA+9iv+tev+tSr"+
"+tKo+cyg+Mic9b+S9LqM8al35ZZmoXBSoWdk7u7u7u7u7u7u7u7u7u7u"+
"xZSN9ejayaOY9uvh//js/vXo/e/a/evS/OfL/OTF+927+9u1+tSq+tKl"+
"+cqW8buFqHZa7JVdn2hm7u7u7u7u7u7u7u7u7u7uxZSN//ns9ercxqKV"+
"+O7k//nw//fu//fr/vTl/u/c/uvU/eLB/N+7+tev8b6Hq3pe+Lh6/69q"+
"oWpp7u7u7u7u7u7u7u7u7u7ux5eP//vv//vw9OncxKOX9+7m//v1//nz"+
"//jx//bs/+7Z/erQ/eTC8syiqntg+M6a/9Oh/8CFom1s7u7u7u7u7u7u"+
"7u7u7u7uypqS//z4//v28ebYza2evp6V7+Lb8uzl8+3l8uvk9Ore9ejZ"+
"6NO/poVyt4xx5b2T/9ap/8ybpXFw7u7u7u7u7u7u7u7u7u7uzJ2V///8"+
"7uPbzaye/fv6/fv5v6GTvKCQvJ+Nu5qIupmJt5uKsZWE+u3e+unYo4Jq"+
"572O/9KjqHd17u7u7u7u7u7u7u7u7u7uzqCX7OHbzKud/fr58url5tnQ"+
"5dfO5dfN5dfM5NbM49TI3Mq+3Mm93Mm8382/+unbrIJp57WGrH597u7u"+
"7u7u7u7u7u7u7u7uz6GZ0LGj6uHa/fv67OLc6+Hb7eTd7ePd7eLb7eLb"+
"7uPb9e7l9evk9uvj9+zh/PHlzr61r4VtsoWC7u7u7u7u7u7u7u7u7u7u"+
"0aKXfdb/8uzn///////////////////////+//37/Pn3+fXv9fHp8+vl"+
"8enk7uXe1si/L6f3tYeC7u7u7u7u7u7u7u7u7u7uy6mkdM3/+vf1////"+
"/////////////////fz8/Pv69fPx7vDw7O/w2OfvxN/swt/thMXnK6ft"+
"r4SC7u7u7u7u7u7u7u7u7u7u1KeevuX6nNf2rN/7nNz9h9X+b8z+VMb/"+
"RsT/RsT/PsP/Obz7NLT2MbL0K6vuJ6XpKKfrLqrvr4J/7u7u7u7u7u7u"+
"7u7u7u7u28jC0rSo0O36yOv7x+r7v+f8suP9o97+jtj+idn+htX/e83/"+
"a8f/XcD/Tbn/SLf/R7b/rJKJ7u7u7u7u7u7u7u7u7u7u7u7u7u7u6ePi"+
"07ew29zd1e/61O/60e77y+z8vun9reH+mNn+gdH/ccj/ZMP/Vr3/t7/C"+
"uKCX7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u6uXk2b621rux1fH6"+
"3fL61/L7y+/8u+f9pt7+jNT+cMn/XcH/rZyW1c3L7u7u7u7u7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u6N/d07Op3d7f2/P60vD7xez8"+
"r+H9k9X+kr/cv6Wb7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u6uXk2L612cG31e73yOv7seL8uKWezLex7u7u"+
"7u7u7u7u7u7u6eHg1LOpzaeayaqh4dvb7u7u7u7u7u7u7u7u7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u";
private static string calendarBmpEnc = @"Qk32BgAAAAAAADYAAAAo"+

"AAAAGAAAABgAAAABABgAAAAAAAAAAADEDgAAxA4AAAAAAAAAAAAA7u7u"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7uuKOUkXxqemNO"+
"alM8YEgwYEgwYkoxYUgwYEgwY0szYkoxYEgwYEgwYEgwYEgwZEszYUgw"+
"YEgwY0oyYUgwYEgwYEgw7u7u7u7uuqWW6tPE27qlxKCLu5d837OUzKGC"+
"t41xsYpt37OUzKGCt41xrodq37OUzKGCt41xrodq37OUzKGCt41xrodq"+
"Zk447u7u7u7uvKaX//fz/+3i/NvFwJl6/+nb/d3H+c+1vJV2/+HP/tW8"+
"/MWluZJz/9vG/9Gw+8OfuJFy/86y/sKf97eSuJFyYEgw7u7u7u7uvaiZ"+
"//j2//Hq/OTY0qiL/+7h/+TR/N3J0KWI/+TU/9vE/9S4zqOF/+LR/9zE"+
"/sywzaKE/9e//8yt/sWizaKEYEgw7u7u7u7uv6qb//v5//j1//bx5Lug"+
"//Ho//Dl/+nb5Lqg/+fZ/+LQ/97I5Lqf/+XU/+HN/9zF5Lqf/9bC/9S7"+
"/9C05LqfYEgw7u7u7u7uwauc4bib1ayOxZyBvpd74LaY0qiKwJd7uJF1"+
"4LWWz6WGvJJ2D0XuBTnjBjXQAiy8ACm137OUzKGCt41xrodqYEgw7u7u"+
"7u7uxK6f//v6/Ozg/eHQx6CC/+/m+uHQ+tjDwpt9/+re/+DM/9O4I1Tz"+
"/9zG/9O5/86wASu4/9fC98Sm87uYuJFyYEgw7u7u7u7uxrCh//39//n0"+
"/One1qyQ//v4/vHn+uHR06mM//Pt/+rc/+HMPGr0/+TU/93H/9i/AzHJ"+
"/+LP/9i++curzaKEYEgw7u7u7u7ux7Kj//39//38/fbw5Luh//z7/vj1"+
"/uzh5Lug//fx//bv/+vgWoH2/+/m/+vd/+PQAzTa/+XU/+XU/97J5Lqf"+
"YUkx7u7u7u7uybOk47yh3rab1q2SzaWL4bqe2a+SzKKHwpqA4bmd1q2O"+
"x52CbY/5WYD3OWb0IFP0Aj3t4Lib06iJwJV5sopwYEgw7u7u7u7uzbep"+
"//39//n1//Dn1a2S/vv6+uvh9+DPyqKG//Tt+eXX+eDSxJx//One+tzH"+
"+dC3v5d6/9/K+9C1+8akuI9yalM97u7u7u7u0Lyu//39//r3//f03bWa"+
"//7+/vXx+urg1q2R//f0/O3i+eTV06mM//fy/+7i+NfCz6WI/+zg/+DM"+
"/9CzyZ6Adl5I7u7u7u7u0sCy//38//39//395L2j//7+//79/vn45L2j"+
"//38//n2/vLr5L2j//37//n2/unf5L2j/+/l/+nc/+DN5L2jf2dS7u7u"+
"7u7u6KaG6KaG6KSE56OB56B+55565pt25phy5ZVt5ZJp5I5k5Itf5Iha"+
"44RV44FR4n5M4ntI4XhE23I812w00mkzyGAo7u7u7u7u6amK/93L/dfD"+
"/9a+/s+2/syy/sis/sSl/cGh/byb/LeV+7SO+rCJ+auC+ad9+KN3+KBx"+
"95xu95pq9pdn9pVkyGAo7u7u7u7u662P/+LQ/t/M/t3K/drG/dfC/dK8"+
"/c63/Mqx/Mer+sKk+r6f+bqY+LaT+LGM96yG9qmA9aV69aB19J1w9Jps"+
"yGAo7u7u7u7u7LKV7LKV662P6aeG56F/559855x45pp05pdw5ZRs5ZFo"+
"5I5j5Itf5Ihb44VW44JS4n9O4nxK4XpG4XdC4XU/2Ws27u7u7u7upJqU"+
"////pJqU////n5aQ////mZCL////kYmF////iIJ+////fnp2////dXJv"+
"////bGpo////ZGNi////XV5c////7u7u7u7u7u7uICUg6enpICUg6enp"+
"ICUg6enpICUg6enpICUg6enpICUg6enpICUg3t7eICUg0NDQICUgvb29"+
"ICUguLi4ICUg7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u"+
"7u7u";
private static string contactsBmpEnc = @"Qk32BgAAAAAAADYAAAAo"+

"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7uuqWWh3FeeWJN"+
"alM8YEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgw"+
"YEgwYEgwYEgwYEgwYEgw7u7u7u7uuqWW//bx7t3T7trO7tfI79LB7865"+
"8Mqy8MWq8cCi8buZ8raR8rKJ862C86l69KV09KFt9Z5o9Zxk9Zph9Zph"+
"YEgw7u7u7u7uu6aX//n2//fy//Xv//Lr//Dn/+3j/+re/+ja/+XW/+LR"+
"/+DN/93J/9rF/9jB/9W9/9O5/9G2/8+z/86x9ZphYEgw7u7u7u7uvKiZ"+
"//z6//r30M/SGlmtA0uuA0WfAz+RATmHADV9zr23/+PTs4t1roRuqX1m"+
"pHhgoXRcoXRcoXRc/9C09Z1mYEgw7u7u7u7uvqqb//79//z7FFe3N3rV"+
"SYrkQ4XeA0OaGW3eC02nGkF4/+fZ/+TV/+LQ/9/M/9zI/9rE/9fA/9W8"+
"/9O59KFtYEgw7u7u7u7uwKyd//////7+E1i3Z57pUZDoTY7nA0SbGGze"+
"E2DIAzmD/+vfuZJ9s4t1roRuqX1mpHhgoXRcoXRc/9a99KV0YEgw7u7u"+
"7u7uwq6f////////GF69gKvkX5flA0WeGW7iA0+3GWzgEk+j/+7l/+zh"+
"/+nc/+bY/+TT/+HP/97L/9zH/9nD86t9YEgw7u7u7u7uxLCh////////"+
"tcDPE1StGly1yNXZ+fryBVG5BkGOz8rK//LqvpiEuZJ9s4t1roRuqX1m"+
"pHhgoXRc/93I87CHYEgw7u7u7u7uxrKk////////9fX1zdDTYWZsVFVW"+
"YWFhBkunubzC//jz//Xw//Ps//Do/+7k/+vf/+jb/+bX/+PS/+DO8raR"+
"YEgw7u7u7u7ux7Sm////////xMTEAAAAwcHBoqKihYWFVVVVn56d//r3"+
"//j0//bx//Tt//Hp/+/l/+zh/+nd/+fY/+TU8b2cYEgw7u7u7u7uybao"+
"////////ODg4LCws1tbWwcHBoqKihYWFZGRk//37//v5//n2//fy//Xv"+
"//Lr//Dn/+3j/+re/+ja8MOmYEgw7u7u7u7uy7iq////////U1NTSUlJ"+
"tLS01dXVwcHBoqKidXV1///+//38/LeL+7SI+q+D+ap++KV496Bz9p1w"+
"/+vg8MmxZk437u7u7u7uzbqs////////fn5+Y2NjXV1dbW1tWFhYwcHB"+
"hISE//////////79//z7//v4//n1//bx//Tu//Lq/+/m78+6b1dB7u7u"+
"7u7uz7yu////////xcXFbGxsgoKCoaGhjo6OVVVVra2t/////////LeL"+
"+7SI+q+D+ap++KV496Bz9p1w//Pr79TEeWJN7u7u7u7u0L6w////////"+
"8vLyuLi4jY2NiIiIhYWFtLS08fHx//////////////////////38//z6"+
"//r3//j0//bw7tnMgm1Z7u7u7u7u0b+x////////////////////////"+
"//////////////////////////////////////79//z7//v4//n1//fy"+
"i3Zj7u7u7u7u0sCy0b+x0L6wz72vzrutzLqsy7iqybeoyLWmxrOkxLGi"+
"w6+hwa2fv6udvqmbvKiZu6aXuaWWuKOUt6KTtqGStaCR7u7u7u7u7u7u"+
"7u7u";
private static string tasksBmpEnc = @"Qk32BgAAAAAAADYAAAAoAAA"+

"AGAAAABgAAAABABgAAAAAAAAAAADEDgAAxA4AAAAAAAAAAAAA7u7u7u7"+
"u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7"+
"u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u3N3fkXxqeGB"+
"LalE5cVc/c1lBf2JKl3RZiWhMe1xBb1M5aE42Zkw0Zk01aE42YUkxYkk"+
"xYkkxkod97u7u7u7u7u7u7u7u7u7uv62e+ezi69nQ7M6+7Miz6L+prI+"+
"rWFKqmHyk7rWU77OO77CM8LCK8bCH8a2F8qp98aV13pZnZkwz7u7u7u7"+
"u7u7u7u7u7u7uv62e//37/vr3/vTw+uvkwLnaJDO/BhmzJjTDybTG99K"+
"8+NC49syy9sms9sao9cOl8LiV8KR0aU417u7u7u7u7u7u7u7u7u7uwK6"+
"f//7+//z7/Pj3xcTmLDvBFynIMEXkIDbXVGHO6dHO+tzJ+tjD+dW++dK"+
"5+c+19sWn8qd2Y0kx7u7u7u7u7u7u7u7u7u7uw7Gj/////Pv9wcTsKDj"+
"FFCnMRVjuZHX1PlPoFzHSeHPJ+d3O+tzI+tjD+dS9+dG59seq8ayEaEw"+
"07u7u7u7u7u7u7u7u7u7uxrWm9vf9pKzoJjjNGi7TR1nreoj/j5v8ZXf"+
"0N0zlJjTPv7LP+t7O+tvI+tfC+dS998qv8K+LaU427u7u7u7u7u7u7u7"+
"u7u7u08W619v5Kz7XJjrfTl/ze4v/tLr59/Dyoab2Znb0LUPmNUTO1sX"+
"R+9/N+tvH+tjC99C277GNbVI47u7u7u7u7u7u7u7u7u7uy7qt6+3+kp7"+
"4UGT4c4P/sbj+/Pr5/vj16ePykpz5Y3T0KDzfbHHR6dTS++HQ+tvG+dn"+
"D8bqabVI57u7u7u7u7u7u7u7u7u7uybeo////9ff/qLL/wsr//Pz///3"+
"8/vv5/ff09e7wpav4YnP0KDzajYzQ6NPT/N7O+NrG8b+idFlA7u7u7u7"+
"u7u7u7u7u7u7uyriq////////+Pn//v7///////////38/vr2/vj08er"+
"wmaL6WWvyMELXmJbS9OPb+d/Q88mxc1Y97u7u7u7u7u7u7u7u7u7uzLq"+
"s//////////////////////////7+//36/vr3/vn0+fDvsLT1WmruNUb"+
"Qta/V+uXX9M+6hWdP7u7u7u7u7u7u7u7u7u7uzryt///////////////"+
"///////////////7+//79//v3/vj0+O7wurz0TV3sSFTS08fa9t7PmXl"+
"h7u7u7u7u7u7u7u7u7u7uz72v/////////////////////fj1+Orh9uH"+
"W89TD88+78sew9NK99drNm5/xVWbwYWvV6dzgrIlw7u7u7u7u7u7u7u7"+
"u7u7u0L6w////////////////X4ycVYGSTHaIS21/SGN0SGJySF9vdnd"+
"9pZWQ89TDt7n1TF3oZGvOuJ2L7u7u7u7u7u7u7u7u7u7u0b+x///////"+
"/////////dJmou+Xsmd3ofs/fdcXVcMHSbrrNbbHCbHJ69dTD++3nw8H"+
"uNUjqZGjJ7u7u7u7u7u7u7u7u7u7u0b+x////////////////i6q2pMn"+
"StuzzYYycdLG+fs/ed8jaXY2eRl1t8uDU++je/O7mzsnmUFCX7u7u7u7"+
"u7u7u7u7u7u7u0sCy////////////////3ufqdZuqx+30V3aFXoCPaZW"+
"kjdDeTWx8v7Ko/vr2/fTv/fTu+/XxnZSu7u7u7u7u7u7u7u7u7u7u6ur"+
"r2Mq/0b+x0L6wz72vyLeqc5qpoMHLxfD3v+zzruXvkMjVaX6GwK6ewrC"+
"hwa+gwK6fv62e4OHi7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7"+
"u7u7u5ObnfKa1eaOxcpyrcJWkboiW4+Pj7u7u7u7u7u7u7u7u7u7u7u7"+
"u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u";
// Static constructor to initialize

// the form's static fields.
static StackView()
{
// Create the static bitmaps from Base64 encoding.
CreateBitmaps();
}
public StackView()
{
this.InitializeComponent();
// Assign icons to ToolStripButton controls.

this.InitializeImages();
// Set up renderers.
this.stackStrip.Renderer = new StackRenderer();
}
// This utility method assigns icons to each

// ToolStripButton control.
private void InitializeImages()
{
this.mailStackButton.Image = mailBmp;
this.calendarStackButton.Image = calendarBmp;
this.contactsStackButton.Image = contactsBmp;
this.tasksStackButton.Image = tasksBmp;
}
// This utility method creates bitmaps for all the icons.

// It uses a utility method called DeserializeFromBase64
// to decode the Base64 image data.
private static void CreateBitmaps()
{
mailBmp = DeserializeFromBase64(mailBmpEnc);
calendarBmp = DeserializeFromBase64(calendarBmpEnc);
contactsBmp = DeserializeFromBase64(contactsBmpEnc);
tasksBmp = DeserializeFromBase64(tasksBmpEnc);
}
// This utility method cretes a bitmap from

// a Base64-encoded string.
internal static Bitmap DeserializeFromBase64(string data)
{
// Decode the string and create a memory stream
// on the decoded string data.
MemoryStream stream =
new MemoryStream(Convert.FromBase64String(data));
// Create a new bitmap from the stream.

Bitmap b = new Bitmap(stream);
return b;
}
// This method handles the Load event for the UserControl.

private void StackView_Load(object sender, EventArgs e)
{
// Dock bottom.
this.Dock = DockStyle.Bottom;
// Set AutoSize.
}
// This method handles the Click event for all

// the ToolStripButton controls in the StackView.
private void stackButton_Click(object sender, EventArgs e)
{
// Define a "one of many" state, similar to
// the logic of a RadioButton control.
foreach (ToolStripItem item in this.stackStrip.Items)
{
if ((item != sender) &&
(item is ToolStripButton))
{
((ToolStripButton)item).Checked = false;
}
}
}

{
{
}
}
internal class StackRenderer : ToolStripProfessionalRenderer

{
private static Bitmap titleBarGripBmp;
private static string titleBarGripEnc =
@"Qk16AQAAAAAAADYAAAAoAAAAIwAAAAMAAAABABgAAAAAAAAAAADEDgAAxA4AAAAAAAAAAAAAuG
My+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uG
MyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5ANj+RzIomHRh+/
n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomH
Rh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5ANj+RzIoRzIozHtMzHtMRz
IoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzIozHtMzH
tMRzIoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzIozHtMANj+";
// Define titlebar colors.

private static Color titlebarColor1 = Color.FromArgb(89, 135,
214);
204);
194);
184);
174);
164);
154);
private static Color borderColor = Color.FromArgb(0, 0, 128);
static StackRenderer()
{
titleBarGripBmp =
StackView.DeserializeFromBase64(titleBarGripEnc);
}
public StackRenderer()
{
}
private void DrawTitleBar(Graphics g, Rectangle rect)

{
// Assign the image for the grip.
Image titlebarGrip = titleBarGripBmp;
// Fill the titlebar.

// This produces the gradient and the rounded-corner effect.
g.DrawLine(new Pen(titlebarColor1), rect.X, rect.Y, rect.X +
rect.Width, rect.Y);
g.DrawLine(new Pen(titlebarColor2), rect.X, rect.Y + 1,
rect.X + rect.Width, rect.Y + 1);
// Center the titlebar grip.

g.DrawImage(
titlebarGrip,
new Point(rect.X + ((rect.Width / 2) -
(titlebarGrip.Width / 2)),
rect.Y + 1));
}
// This method handles the RenderGrip event.

protected override void
OnRenderGrip(ToolStripGripRenderEventArgs e)
{
DrawTitleBar(
e.Graphics,
new Rectangle(0, 0, e.ToolStrip.Width, 7));
}
// This method handles the RenderToolStripBorder event.

OnRenderToolStripBorder(ToolStripRenderEventArgs e)
{
DrawTitleBar(
e.Graphics,
}
// This method handles the RenderButtonBackground event.

OnRenderButtonBackground(ToolStripItemRenderEventArgs e)
{
Rectangle bounds = new Rectangle(Point.Empty, e.Item.Size);
Color gradientBegin = Color.FromArgb(203, 225, 252);

Color gradientEnd = Color.FromArgb(125, 165, 224);
ToolStripButton button = e.Item as ToolStripButton;

if (button.Pressed || button.Checked)
{
gradientBegin = Color.FromArgb(254, 128, 62);
gradientEnd = Color.FromArgb(255, 223, 154);
}
else if (button.Selected)
{
}
using (Brush b = new LinearGradientBrush(

bounds,
gradientBegin,
gradientEnd,
LinearGradientMode.Vertical))
{
g.FillRectangle(b, bounds);
}
e.Graphics.DrawRectangle(
SystemPens.ControlDarkDark,
bounds);
g.DrawLine(
bounds.X,
bounds.Y,
bounds.Width - 1,
bounds.Y);
g.DrawLine(
bounds.X,
bounds.Y,
bounds.X,
bounds.Height - 1);
ToolStrip toolStrip = button.Owner;

ToolStripButton nextItem = button.Owner.GetItemAt(
button.Bounds.X,
button.Bounds.Bottom + 1) as ToolStripButton;
if (nextItem == null)
{
g.DrawLine(
bounds.X,
bounds.Height - 1,
bounds.X + bounds.Width - 1,
bounds.Height - 1);
}
}
}
#region Component Designer generated code

{
this.stackStrip = new System.Windows.Forms.ToolStrip();
this.mailStackButton = new
this.calendarStackButton = new
this.contactsStackButton = new
this.tasksStackButton = new
this.stackStrip.SuspendLayout();
//
// stackStrip
//
this.stackStrip.CanOverflow = false;
this.stackStrip.Dock = System.Windows.Forms.DockStyle.Bottom;
this.stackStrip.Font = new System.Drawing.Font("Tahoma", 10F,
System.Drawing.FontStyle.Bold);
this.stackStrip.GripStyle =
System.Windows.Forms.ToolStripGripStyle.Hidden;
this.stackStrip.Items.AddRange(new
this.mailStackButton,
this.calendarStackButton,
this.contactsStackButton,
this.tasksStackButton});
this.stackStrip.LayoutStyle =
System.Windows.Forms.ToolStripLayoutStyle.VerticalStackWithOverflow;
this.stackStrip.Location = new System.Drawing.Point(0, 11);
this.stackStrip.Name = "stackStrip";
this.stackStrip.Padding = new System.Windows.Forms.Padding(0, 7,
0, 0);
this.stackStrip.RenderMode =
System.Windows.Forms.ToolStripRenderMode.Professional;
this.stackStrip.Size = new System.Drawing.Size(150, 139);
this.stackStrip.TabIndex = 0;
this.stackStrip.Text = "toolStrip1";
//
// mailStackButton
//
this.mailStackButton.CheckOnClick = true;
this.mailStackButton.ImageAlign =
System.Drawing.ContentAlignment.MiddleLeft;
this.mailStackButton.ImageScaling =
System.Windows.Forms.ToolStripItemImageScaling.None;
this.mailStackButton.ImageTransparentColor =
System.Drawing.Color.FromArgb(((int)(((byte)(238)))), ((int)(((byte)
(238)))), ((int)(((byte)(238)))));
this.mailStackButton.Margin = new
System.Windows.Forms.Padding(0);
this.mailStackButton.Name = "mailStackButton";
this.mailStackButton.Padding = new
this.mailStackButton.Size = new System.Drawing.Size(149, 27);
this.mailStackButton.Text = " Mail";
this.mailStackButton.TextAlign =
this.mailStackButton.Click += new
System.EventHandler(this.stackButton_Click);
//
// calendarStackButton
//
this.calendarStackButton.CheckOnClick = true;
this.calendarStackButton.ImageAlign =
this.calendarStackButton.ImageScaling =
this.calendarStackButton.ImageTransparentColor =
(238)))), ((int)(((byte)(238)))));
this.calendarStackButton.Margin = new
this.calendarStackButton.Name = "calendarStackButton";
this.calendarStackButton.Padding = new
this.calendarStackButton.Size = new System.Drawing.Size(149,
27);
this.calendarStackButton.Text = " Calendar";
this.calendarStackButton.TextAlign =
this.calendarStackButton.Click += new
//
// contactsStackButton
//
this.contactsStackButton.CheckOnClick = true;
this.contactsStackButton.ImageAlign =
this.contactsStackButton.ImageScaling =
this.contactsStackButton.ImageTransparentColor =
(238)))), ((int)(((byte)(238)))));
this.contactsStackButton.Margin = new
this.contactsStackButton.Name = "contactsStackButton";
this.contactsStackButton.Padding = new
this.contactsStackButton.Size = new System.Drawing.Size(149,
27);
this.contactsStackButton.Text = " Contacts";
this.contactsStackButton.TextAlign =
this.contactsStackButton.Click += new
//
// tasksStackButton
//
this.tasksStackButton.CheckOnClick = true;
this.tasksStackButton.ImageAlign =
this.tasksStackButton.ImageScaling =
this.tasksStackButton.ImageTransparentColor =
(238)))), ((int)(((byte)(238)))));
this.tasksStackButton.Margin = new
this.tasksStackButton.Name = "tasksStackButton";
this.tasksStackButton.Padding = new
this.tasksStackButton.Size = new System.Drawing.Size(149, 27);
this.tasksStackButton.Text = " Tasks";
this.tasksStackButton.TextAlign =
this.tasksStackButton.Click += new
//
// StackView
//
this.Controls.Add(this.stackStrip);
this.Name = "StackView";
this.Load += new System.EventHandler(this.StackView_Load);
this.stackStrip.ResumeLayout(false);
this.stackStrip.PerformLayout();
}
#endregion
}
}
Confira também
MenuStrip
ToolStrip
StatusStrip
Controle ToolStrip
Como: Criar um formulário MDI com
mesclagem de menu e controles
ToolStrip
Artigo • 02/06/2023
O System.Windows.Forms namespace dá suporte a aplicativos de interface de vários

documentos (MDI) e o controle dá suporte à mesclagem de MenuStrip menus. Os
formulários MDI também ToolStrip podem controlar.
Há suporte extensivo para esse recurso no Visual Studio.
Consulte também o passo a passos: Criando um formulário MDI com mesclagem de

menu e controles ToolStrip.
Exemplo
O exemplo de código a seguir demonstra como usar ToolStripPanel controles com um
formulário MDI. O formulário também dá suporte à mesclagem com menus filho.
C#
using System;
namespace MdiFormCS
{
// This code example demonstrates an MDI form
// that supports menu merging and moveable
// ToolStrip controls
{
private MenuStrip menuStrip1;
private ToolStripMenuItem newToolStripMenuItem;
private ToolStripPanel toolStripPanel1;
public Form1()
{
}
{
{
}
}
// This method creates a new ChildForm instance

// and attaches it to the MDI parent form.
{
ChildForm f = new ChildForm();
f.MdiParent = this;
f.Text = "Form - " + this.MdiChildren.Length.ToString();
f.Show();
}

{
this.newToolStripMenuItem = new
this.toolStripPanel1 = new
System.Windows.Forms.ToolStripPanel();
this.toolStripPanel1.SuspendLayout();
//
// menuStrip1
//
this.menuStrip1.MdiWindowListItem = this.toolStripMenuItem1;
//
//
this.toolStripMenuItem1.DropDownItems.AddRange(new
this.newToolStripMenuItem});
this.toolStripMenuItem1.Size = new System.Drawing.Size(57, 20);
this.toolStripMenuItem1.Text = "Window";
//
// newToolStripMenuItem
//
this.newToolStripMenuItem.Name = "newToolStripMenuItem";
this.newToolStripMenuItem.Size = new System.Drawing.Size(106,
22);
this.newToolStripMenuItem.Text = "New";
this.newToolStripMenuItem.Click += new
System.EventHandler(this.newToolStripMenuItem_Click);
//
// toolStripPanel1
//
this.toolStripPanel1.Controls.Add(this.toolStrip1);
this.toolStripPanel1.Dock = System.Windows.Forms.DockStyle.Left;
this.toolStripPanel1.Location = new System.Drawing.Point(0, 49);
this.toolStripPanel1.Name = "toolStripPanel1";
this.toolStripPanel1.Orientation =
System.Windows.Forms.Orientation.Vertical;
this.toolStripPanel1.RowMargin = new
System.Windows.Forms.Padding(0, 3, 0, 0);
this.toolStripPanel1.Size = new System.Drawing.Size(26, 199);
//
// toolStrip1
//
this.toolStrip1.Dock = System.Windows.Forms.DockStyle.None;
//
// toolStripPanel2
//
this.toolStripPanel2.Dock = System.Windows.Forms.DockStyle.Top;
this.toolStripPanel2.Location = new System.Drawing.Point(0, 24);
System.Windows.Forms.Orientation.Horizontal;
//
// toolStrip2
//
//
// toolStripPanel3
//
this.toolStripPanel3.Dock =
System.Windows.Forms.DockStyle.Right;
this.toolStripPanel3.Location = new System.Drawing.Point(266,
49);
System.Windows.Forms.Orientation.Vertical;
//
// toolStrip3
//
//
// toolStripPanel4
//
this.toolStripPanel4.Dock =
System.Windows.Forms.DockStyle.Bottom;
this.toolStripPanel4.Location = new System.Drawing.Point(0,
248);
System.Windows.Forms.Orientation.Horizontal;
//
// toolStrip4
//
//
// Form1
//
this.Controls.Add(this.toolStripPanel3);
this.IsMdiContainer = true;
this.toolStripPanel1.ResumeLayout(false);
this.toolStripPanel1.PerformLayout();
}
#endregion
}
public class ChildForm : Form

{
private System.Windows.Forms.MenuStrip menuStrip1;
private System.Windows.Forms.ToolStripMenuItem toolStripMenuItem1;
public ChildForm()
{
}

{
{
}
}

{
//
// menuStrip1
//
//
//
this.toolStripMenuItem1.Size = new System.Drawing.Size(90, 20);
this.toolStripMenuItem1.Text = "ChildMenuItem";
//
// ChildForm
//
this.Name = "ChildForm";
this.Text = "ChildForm";
}
#endregion
}

{
/// <summary>
/// </summary>
[STAThread]
static void Main()
{
}
}
}
Este exemplo de código requer:
Confira também
Controle ToolStrip
Como: Criar um formulário MDI com
controles ToolStripPanel
Artigo • 02/06/2023
Você pode criar um formulário MDI (interface de documento múltiplo) que tenha
ToolStrip controles que o enquadram em todos os quatro lados.
Exemplo
O exemplo de código a seguir demonstra como usar controles encaixados
ToolStripPanel para enquadrar uma janela MDI com quatro ToolStrip controles.
No exemplo, o Join método anexa os ToolStrip controles aos controles correspondentes

ToolStripPanel .
C#
using System;
C#
// This code example demonstrates how to use ToolStripPanel

// controls with a multiple document interface (MDI).
{
public Form1()
{
// Make the Form an MDI parent.
// Create ToolStripPanel controls.

ToolStripPanel tspTop = new ToolStripPanel();
ToolStripPanel tspBottom = new ToolStripPanel();
ToolStripPanel tspLeft = new ToolStripPanel();
ToolStripPanel tspRight = new ToolStripPanel();
// Dock the ToolStripPanel controls to the edges of the form.

tspTop.Dock = DockStyle.Top;
tspBottom.Dock = DockStyle.Bottom;
tspLeft.Dock = DockStyle.Left;
tspRight.Dock = DockStyle.Right;
// Create ToolStrip controls to move among the

// ToolStripPanel controls.
// Create the "Top" ToolStrip control and add

// to the corresponding ToolStripPanel.
ToolStrip tsTop = new ToolStrip();
tsTop.Items.Add("Top");
tspTop.Join(tsTop);
// Create the "Bottom" ToolStrip control and add

ToolStrip tsBottom = new ToolStrip();
tsBottom.Items.Add("Bottom");
tspBottom.Join(tsBottom);
// Create the "Right" ToolStrip control and add

ToolStrip tsRight = new ToolStrip();
tsRight.Items.Add("Right");
tspRight.Join(tsRight);
// Create the "Left" ToolStrip control and add

ToolStrip tsLeft = new ToolStrip();
tsLeft.Items.Add("Left");
tspLeft.Join(tsLeft);
// Create a MenuStrip control with a new window.

ToolStripMenuItem windowMenu = new ToolStripMenuItem("Window");
ToolStripMenuItem windowNewMenu = new ToolStripMenuItem("New", null,
new EventHandler(windowNewMenu_Click));
windowMenu.DropDownItems.Add(windowNewMenu);
((ToolStripDropDownMenu)(windowMenu.DropDown)).ShowImageMargin =
false;
((ToolStripDropDownMenu)(windowMenu.DropDown)).ShowCheckMargin =
true;
// Assign the ToolStripMenuItem that displays

// the list of child forms.
ms.MdiWindowListItem = windowMenu;
// Add the window ToolStripMenuItem to the MenuStrip.

ms.Items.Add(windowMenu);
// Dock the MenuStrip to the top of the form.

// The Form.MainMenuStrip property determines the merge target.

this.MainMenuStrip = ms;
// Add the ToolStripPanels to the form in reverse order.

this.Controls.Add(tspRight);
this.Controls.Add(tspLeft);
this.Controls.Add(tspBottom);
this.Controls.Add(tspTop);
// Add the MenuStrip last.
}
// This event handler is invoked when

// the "New" ToolStripMenuItem is clicked.
// It creates a new Form and sets its MdiParent
// property to the main form.
void windowNewMenu_Click(object sender, EventArgs e)
{
Form f = new Form();
f.MdiParent = this;
f.Show();
}
}
Confira também
ToolStrip
ToolStripPanel
Join
ToolStripItem
ToolStripMenuItem
Controle ToolStrip
Como: Alterar a aparência de texto e
imagens de ToolStrip nos Windows
Forms
Artigo • 02/06/2023
Você pode controlar se o texto e as imagens são exibidos em um ToolStripItem e como

elas são alinhadas em relação umas às outras e a ToolStrip.
Para definir o que é exibido em um ToolStripItem

Defina a DisplayStyle propriedade como o valor desejado. As possibilidades
são Image , e None ImageAndText Text . O padrão é ImageAndText .
C#
toolStripButton2.DisplayStyle =
Para alinhar texto em um ToolStripItem

Defina a TextAlign propriedade como o valor desejado. As possibilidades são
qualquer combinação de parte superior, intermediária e inferior com esquerda,
centro e direita. O padrão é MiddleCenter .
C#
toolStripSplitButton1.TextAlign =
System.Drawing.ContentAlignment.MiddleRight;
Para alinhar uma imagem em um ToolStripItem

Defina a ImageAlign propriedade como o valor desejado. As possibilidades são
qualquer combinação de parte superior, intermediária e inferior com esquerda,
centro e direita. O padrão é MiddleLeft .
C#
toolStripSplitButton1.ImageAlign =
System.Drawing.ContentAlignment.MiddleRight;
Para definir como o texto e as imagens do ToolStripItem
são exibidos em relação uns aos outros
Defina a TextImageRelation propriedade como o valor desejado. As possibilidades
são ImageAboveText , ImageBeforeText , Overlay , TextAboveImage e
TextBeforeImage . O padrão é ImageBeforeText .
C#
toolStripButton1.TextImageRelation =
System.Windows.Forms.TextImageRelation.ImageAboveText;
Confira também
ToolStrip
Como: Alterar o espaçamento e o
alinhamento de itens ToolStrip no
Windows Forms
Artigo • 02/06/2023
O ToolStrip controle dá suporte total a recursos de layout, como dimensionamento,

espaçamento de ToolStripItem controles em relação uns aos outros, a disposição de
controles no ToolStripe o espaçamento de controles relativos ao ToolStrip.
Como o valor padrão da propriedade é true , os AutoSize controles são dimensionados

automaticamente, a menos que você defina a AutoSize propriedade como false .
Para dimensionar manualmente um ToolStripItem

1. Defina a AutoSize propriedade para false o controle associado.
C#
toolStripButton1.AutoSize = false;
2. Defina a Size propriedade da maneira desejada para o associado ToolStripItem.
Para definir o espaçamento de um ToolStripItem

1. Insira os valores desejados, em pixels, na Margin propriedade do controle
associado.
Os valores da Margin propriedade especificam o espaçamento entre o item e os

itens adjacentes nesta ordem: Esquerda, Superior, Direita e Inferior.
C#
toolStripTextBox1.Margin = new System.Windows.Forms.Padding

(3, 0, 3, 0);
Para alinhar um ToolStripItem à direita de ToolStrip

1. Defina a Alignment propriedade para Right o controle associado. Por padrão,
Alignment é definido como Left, o que alinha os controles ao lado esquerdo do
ToolStrip.
C#
toolStripSplitButton1.Alignment =
System.Windows.Forms.ToolStripItemAlignment.Right;
Para organizar itens de ToolStrip no ToolStrip

Defina a LayoutStyle propriedade como o valor desejado ToolStripLayoutStyle .
C#
toolStripDropDown1.LayoutStyle =
System.Windows.Forms.ToolStripLayoutStyle.Flow;
Confira também
ToolStrip
Layout
LayoutCompleted
LayoutSettings
TextImageRelation
Placement
CanOverflow
Como: Criar e definir um renderizador
personalizado para o controle ToolStrip
no Windows Forms
Artigo • 02/06/2023
ToolStrip os controles dão suporte fácil a temas e estilos. Você pode obter aparência e
comportamento completamente personalizados (aparência) definindo a
ToolStrip.Renderer propriedade ou a ToolStripManager.Renderer propriedade como um
renderizador personalizado.
Você pode atribuir renderizadores a cada indivíduoToolStrip,

MenuStripContextMenuStripou StatusStrip controle, ou pode usar a Renderer
propriedade para afetar todos os objetos definindo a ToolStrip.RenderMode
propriedade como ToolStripRenderMode.ManagerRenderMode.
７ Observação
RenderMode retornará Custom somente se o valor de ToolStrip.Renderer não

null for .
Para criar um renderizador personalizado

1. Estenda a ToolStripRenderer classe.
2. Implementar a renderização personalizada desejada substituindo membros

apropriados em...
C#
public class RedTextRenderer : _

System.Windows.Forms.ToolStripRenderer
{
protected override void _
OnRenderItemText(ToolStripItemTextRenderEventArgs e)
{
e.TextColor = Color.Red;
e.TextFont = new Font("Helvetica", 7, FontStyle.Bold);
base.OnRenderItemText(e);
}
}
Para definir o renderizador personalizado para ser o
processador atual
1. Para definir o renderizador personalizado para um ToolStrip, defina a
ToolStrip.Renderer propriedade como o renderizador personalizado.
C#
toolStrip1.Renderer = new RedTextRenderer();
2. Ou para definir o renderizador personalizado para todas as ToolStrip classes

contidas em seu aplicativo: defina a ToolStripManager.Renderer propriedade para
o renderizador personalizado e defina a RenderMode propriedade como
ManagerRenderMode.
C#
toolStrip1.RenderMode = ToolStripRenderMode.ManagerRenderMode;
ToolStripManager.Renderer = new RedTextRenderer();
Confira também
Renderer
ToolStripRenderer
RenderMode
Como: Criar botões de alternância em
controles ToolStrip
Artigo • 02/06/2023
Quando um usuário clica em um botão de alternância, ele aparece afundado e mantém

a aparência submersa até que o usuário clique no botão novamente.
Para criar um ToolStripButton de alternamento

Use o código, como o exemplo de código a seguir. Esse código pressupõe que seu
formulário contém um ToolStrip controle e que sua Items coleção contém um
ToolStripButton chamado toolStripButton1 . Ele também pressupõe que você
tenha um manipulador de eventos chamado toolStripButton1_CheckedChanged .
C#
toolStripButton1.CheckOnClick = true;
toolStripButton1.CheckedChanged += new _
EventHandler(toolStripButton1_CheckedChanged);
Confira também
ToolStripButton
Como: Personalizar o desenho de um
controle ToolStrip
Artigo • 02/06/2023
Os ToolStrip controles têm as seguintes classes de renderização (pintura) associadas:
ToolStripSystemRenderer fornece a aparência e o estilo do sistema operacional.
ToolStripProfessionalRenderer fornece a aparência e o estilo do Microsoft Office.
ToolStripRenderer é a classe base abstrata para as outras duas classes de

renderização.
Para desenhar personalizado (também conhecido como desenho do proprietário),

ToolStripvocê pode substituir uma das classes do renderizador e alterar um aspecto da
lógica de renderização.
Os procedimentos a seguir descrevem vários aspectos do desenho personalizado.
Alternar entre os renderizadores fornecidos

Defina a RenderMode propriedade como o ToolStripRenderMode valor desejado.
Com ManagerRenderMode, o estático RenderMode determina o renderizador para

seu aplicativo. Os outros valores são ToolStripRenderModeCustom, Professionale
System.
Alterar as bordas de estilo do Office

Substitua ToolStripProfessionalRenderer.OnRenderToolStripBorder, mas não chame
a classe base.
７ Observação
Há uma versão desse método para ToolStripRenderer, ToolStripSystemRenderere

ToolStripProfessionalRenderer.
Alterar a ProfessionalColorTable
Substitua ProfessionalColorTable e altere as cores desejadas.
C#

{
public Form1()
{
}

{
var colorTable = new MyColorTable();
toolStrip1.Renderer = new
ToolStripProfessionalRenderer(colorTable);
}
class MyColorTable: ProfessionalColorTable

{
public override System.Drawing.Color ButtonPressedGradientBegin
=> Color.Red;
public override System.Drawing.Color
ButtonPressedGradientMiddle => Color.Blue;
public override System.Drawing.Color ButtonPressedGradientEnd
=> Color.Green;
ButtonSelectedGradientBegin => Color.Yellow;
ButtonSelectedGradientMiddle => Color.Orange;
public override System.Drawing.Color ButtonSelectedGradientEnd
=> Color.Violet;
}
}
Alterar a renderização para todas as ToolStrips

1. Use a ToolStripManager.RenderMode propriedade para escolher um dos
renderizadores fornecidos.
2. Use ToolStripManager.Renderer para atribuir um renderizador personalizado.
3. Verifique se isso ToolStrip.RenderMode está definido como o valor padrão de

ManagerRenderMode.
Desativar as cores do Office

Defina ToolStripManager.VisualStylesEnabled como false .
Desativar as cores do Office para um ToolStrip
Use um código semelhante ao seguinte exemplo.
C#
ProfessionalColorTable colorTable = new ProfessionalColorTable();

colorTable.UseSystemColors = true;
toolStrip1.Renderer = new ToolStripProfessionalRenderer(colorTable);
Confira também
ToolStripSystemRenderer
ToolStripRenderer
Windows Forms
Como: Personalizar cores em aplicativos
ToolStrip
Artigo • 02/06/2023
Você pode personalizar a aparência da sua ToolStrip usando a

ToolStripProfessionalRenderer classe para usar cores personalizadas.
Exemplo
O exemplo de código a seguir demonstra como usar um ToolStripProfessionalRenderer
para definir cores personalizadas em tempo de execução.
C#
// This code example demonstrates how to use a ProfessionalRenderer

// to define custom professional colors at runtime.
class Form2 : Form
{
public Form2()
{
// Populate the ToolStrip control.

ts.Items.Add("Apples");
ts.Items.Add("Oranges");
ts.Items.Add("Pears");
ts.Items.Add(
"Change Colors",
null,
new EventHandler(ChangeColors_Click));
// Create a new MenuStrip.


// Add the top-level menu items.

ms.Items.Add("File");
ms.Items.Add("Edit");
ms.Items.Add("View");
ms.Items.Add("Window");
// Add the ToolStrip to Controls collection.


}
// This event handler is invoked when the "Change colors"

// ToolStripItem is clicked. It assigns the Renderer
// property for the ToolStrip control.
void ChangeColors_Click(object sender, EventArgs e)
{
ToolStripManager.Renderer =
new ToolStripProfessionalRenderer(new
CustomProfessionalColors());
}
}
// This class defines the gradient colors for

// the MenuStrip and the ToolStrip.
class CustomProfessionalColors : ProfessionalColorTable
{
public override Color ToolStripGradientBegin
{ get { return Color.BlueViolet; } }
public override Color ToolStripGradientMiddle

{ get { return Color.CadetBlue; } }
public override Color ToolStripGradientEnd

{ get { return Color.CornflowerBlue; } }
public override Color MenuStripGradientBegin

{ get { return Color.Salmon; } }
public override Color MenuStripGradientEnd

{ get { return Color.OrangeRed; } }
}

Confira também
ToolStripManager
ProfessionalColorTable
MenuStrip
ToolStrip
Como: Definir a organização Z de
controles ToolStrip encaixados
Artigo • 02/06/2023
Para posicionar um ToolStrip controle corretamente com o encaixe, você deve

posicionar o controle corretamente na ordem z do formulário.
Exemplo
O exemplo de código a seguir demonstra como organizar um ToolStrip controle e um
controle encaixado MenuStrip especificando a ordem z.
C#
public Form2()
{

ts.Items.Add(
"Change Colors",
null,





}
A ordem z é determinada pela ordem na qual o ToolStrip e MenuStrip
os controles são adicionados à coleção do Controls formulário.
C#


Inverta a ordem dessas chamadas para o Add método e exiba o efeito no layout.

Confira também
MenuStrip
ToolStrip
Add
Controls
Dock
Controle ToolStrip
Como: Detectar quando o ponteiro do
mouse passa sobre um ToolStripItem
Artigo • 21/06/2023
Use o procedimento a seguir para detectar quando o ponteiro do mouse está sobre um
ToolStripItem.
Para detectar quando o ponteiro está sobre um

ToolStripItem
Use a Selected propriedade para itens em que CanSelect é true .
Isso impedirá que você precise sincronizar os MouseEnter eventos e MouseLeave .
Confira também
ToolStripItem
Selected
Como habilitar AutoComplete em
controles ToolStrip nos Windows Forms
Artigo • 02/06/2023
O procedimento a seguir combina um ToolStripLabel com um ToolStripComboBox que

pode ser descartado para mostrar uma lista de itens, como sites visitados recentemente.
Se o usuário digita um caractere que corresponde ao primeiro caractere de um dos itens
na lista, o item é exibido imediatamente.
７ Observação
A conclusão automática funciona com ToolStrip controles da mesma forma que

funciona com controles tradicionais, como ComboBox e TextBox.
Para habilitar AutoComplete em um controle ToolStrip

1. Crie um ToolStrip controle e adicione itens a ele.
C#
toolStrip1 = new System.Windows.Forms.ToolStrip();

toolStrip1.Items.AddRange(new System.Windows.Forms.ToolStripItem[]
{toolStripLabel1, toolStripComboBox1});
2. Defina a Overflow propriedade do rótulo e a caixa de combinação para Never que

a lista esteja sempre disponível, independentemente do tamanho do formulário.
C#
toolStripLabel1.Overflow = _
System.Windows.Forms.ToolStripItemOverflow.Never
toolStripComboBox1.Overflow =
System.Windows.Forms.ToolStripItemOverflow.Never
3. Adicione palavras à coleção Items do ToolStripComboBox controle.
C#
toolStripComboBox1.Items.AddRange(new object[] {"First item", "Second

item", "Third item"});
4. Defina a AutoCompleteMode propriedade da caixa de combinação como Append.
C#
toolStripComboBox1.AutoCompleteMode =
System.Windows.Forms.AutoCompleteMode.Append;
5. Defina a AutoCompleteSource propriedade da caixa de combinação como

ListItems.
C#
toolStripComboBox1.AutoCompleteSource =
System.Windows.Forms.AutoCompleteSource.ListItems;
Confira também
ToolStrip
ToolStripLabel
ToolStripComboBox
AutoCompleteMode
AutoCompleteSource
Como habilitar a reorganização de itens
ToolStrip em tempo de execução no
Windows Forms
Artigo • 02/06/2023
Você pode permitir que o usuário reorganize ToolStripItem os ToolStripcontroles no .
Para habilitar o rearranjo ToolStripItem em tempo de

execução
Defina a propriedade AllowItemReorder como true . Por padrão, AllowItemReorder
é false .
Em tempo de execução, o usuário segura a tecla ALT e o botão esquerdo do

mouse para arrastar um ToolStripItem para um local diferente no ToolStrip.
C#
toolStrip1.AllowItemReorder = true;
Confira também
ToolStrip
AllowItemReorder
Como: Habilitar a tecla TAB para deixar
um controle ToolStrip
Artigo • 02/06/2023
Use o procedimento a seguir para permitir que o usuário pressione a tecla TAB para sair
de um ToolStrip para o próximo controle na ordem de tabulação.
Aceita ToolStrip a primeira tecla TAB e as teclas de direção selecionam itens dentro do
ToolStrip. Quando o usuário pressiona a tecla TAB uma segunda vez, ele leva o usuário
para o próximo controle na ordem de tabulação.
Para permitir que o usuário pressione a tecla TAB para

sair de um ToolStrip para o próximo controle
Defina a TabStop propriedade como ToolStrip true .
Confira também
ToolStrip
TabStop
Como: Implementar um
ToolStripRenderer personalizado
Artigo • 02/06/2023
Você pode personalizar a aparência de um ToolStrip controle implementando uma

classe derivada de ToolStripRenderer. Isso oferece a flexibilidade para criar uma
aparência diferente da aparência fornecida e ToolStripSystemRenderer das
ToolStripProfessionalRenderer classes.
Exemplo
O exemplo de código a seguir demonstra como implementar uma classe personalizada
ToolStripRenderer . Neste exemplo, o controle GridStrip implementa um quebra-
cabeça de bloco deslizante, que permite que o usuário mova os blocos em um layout de
tabela para formar uma imagem. Um controle personalizado ToolStrip organiza seus
ToolStripButton controles em um layout de grade. O layout contém uma célula vazia, na
qual o usuário pode deslizar um bloco adjacente usando uma operação do tipo "arrastar
e soltar". Blocos que o usuário pode mover são realçados.
A classe GridStripRenderer personaliza três aspectos da aparência do controle

GridStrip :
Borda GridStrip
Borda ToolStripButton
ToolStripButton Imagem
C#
using System;
using System.Drawing.Imaging;
using System.Text;
using System.Windows.Forms.Layout;
namespace GridStripLib
{
// The following class implements a sliding-tile puzzle.
// The GridStrip control is a custom ToolStrip that arranges
// its ToolStripButton controls in a grid layout. There is
// one empty cell, into which the user can slide an adjacent
// tile with a drag-and-drop operation. Tiles that are eligible
// for moving are highlighted.
public class GridStrip : ToolStrip
{
// The button that is the drag source.
private ToolStripButton dragButton = null;
// Settings for the ToolStrip control's TableLayoutPanel.

// This provides access to the cell position of each
// ToolStripButton.
private TableLayoutSettings tableSettings = null;
// The empty cell. ToolStripButton controls that are

// adjacent to this button can be moved to this button's
// cell position.
private ToolStripButton emptyCellButton = null;
// The dimensions of each tile. A tile is represented

// by a ToolStripButton controls.
private Size tileSize = new Size(128, 128);
// The number of rows in the GridStrip control.

private readonly int rows = 5;
// The number of columns in the GridStrip control.

private readonly int columns = 5;
// The one-time initialzation behavior is enforced

// with this field. For more information, see the
// OnPaint method.
private bool firstTime = false;
// This is a required by the Windows Forms designer.

private System.ComponentModel.IContainer components;
// The default constructor.

public GridStrip()
{
this.InitializeTableLayoutSettings();
}
// This property exposes the empty cell to the

// GridStripRenderer class.
internal ToolStripButton EmptyCell
{
get
{
return this.emptyCellButton;
}
}
// This utility method initializes the TableLayoutPanel

// which contains the ToolStripButton controls.
private void InitializeTableLayoutSettings()
{
// Specify the numbers of rows and columns in the GridStrip
control.
this.tableSettings = base.LayoutSettings as TableLayoutSettings;
this.tableSettings.ColumnCount = this.rows;
this.tableSettings.RowCount = this.columns;
// Create a dummy bitmap with the dimensions of each tile.

// The GridStrip control sizes itself based on these dimensions.
Bitmap b = new Bitmap(tileSize.Width, tileSize.Height);
// Populate the GridStrip control with ToolStripButton controls.

for (int i = 0; i < this.tableSettings.ColumnCount; i++)
{
for (int j = 0; j < this.tableSettings.RowCount; j++)
{
// Create a new ToolStripButton control.
ToolStripButton btn = new ToolStripButton();
btn.DisplayStyle = ToolStripItemDisplayStyle.Image;
btn.Image = b;
btn.ImageAlign = ContentAlignment.MiddleCenter;
btn.ImageScaling = ToolStripItemImageScaling.None;
btn.Margin = Padding.Empty;
btn.Padding = Padding.Empty;
// Add the new ToolStripButton control to the GridStrip.

this.Items.Add(btn);
// Set the cell position of the ToolStripButton control.

TableLayoutPanelCellPosition cellPos = new
TableLayoutPanelCellPosition(i, j);
this.tableSettings.SetCellPosition(btn, cellPos);
// If this is the ToolStripButton control at cell (0,0),

// assign it as the empty cell button.
if( i == 0 && j == 0 )
{
btn.Text = "Empty Cell";
btn.Image = b;
this.emptyCellButton = btn;
}
}
}
}
// This method defines the Paint event behavior.

// The GridStripRenderer requires that the GridStrip
// be fully layed out when it is renders, so this
// initialization code cannot be placed in the
// GridStrip constructor. By the time the Paint
// event is raised, the control layout has been
// completed, so the GridStripRenderer can paint
// correctly. This one-time initialization is
// implemented with the firstTime field.
{
base.OnPaint(e);
if (!this.firstTime)
{
this.Renderer = new GridStripRenderer();
// Comment this line to see the unscrambled image.

this.ScrambleButtons();
this.firstTime = true;
}
}
// This utility method changes the ToolStripButton control

// positions in the TableLayoutPanel. This scrambles the
// buttons to initialize the puzzle.
private void ScrambleButtons()
{
int i = 0;
int lastElement = this.Items.Count - 1;
while ( (i != lastElement ) &&

(lastElement - i > 1) )
{
TableLayoutPanelCellPosition pos1 =
this.tableSettings.GetCellPosition(this.Items[i]);
TableLayoutPanelCellPosition pos2 =
this.tableSettings.GetCellPosition(this.Items[lastElement]);
this.tableSettings.SetCellPosition(
this.Items[i++],
pos2);
this.tableSettings.SetCellPosition(
this.Items[lastElement--],
pos1);
}
}
// This method defines the MouseDown event behavior.

// If the user has clicked on a valid drag source,
// the drag operation starts.
protected override void OnMouseDown(MouseEventArgs mea)
{
base.OnMouseDown(mea);
ToolStripButton btn = this.GetItemAt(mea.Location) as

ToolStripButton;
if (btn != null)
{
if (this.IsValidDragSource(btn))
{
this.dragButton = btn;
}
}
}
// This method defines the MouseMove event behavior.

protected override void OnMouseMove(MouseEventArgs mea)
{
base.OnMouseMove(mea);
// Is a drag operation pending?

if (this.dragButton != null)
{
// A drag operation is pending. Call DoDragDrop to
// determine the disposition of the operation.
DragDropEffects dropEffect = this.DoDragDrop(
new DataObject(this.dragButton),
DragDropEffects.Move);
}
}
// This method defines the DragOver event behavior.

protected override void OnDragOver(DragEventArgs dea)
{
base.OnDragOver(dea);
// Get the ToolStripButton control

// at the given mouse position.
Point p = new Point(dea.X, dea.Y);
ToolStripButton item = this.GetItemAt(
this.PointToClient(p)) as ToolStripButton;
// If the ToolStripButton control is the empty cell,

// indicate that the move operation is valid.
if( item == this.emptyCellButton )
{
// Set the drag operation to indicate a valid move.
dea.Effect = DragDropEffects.Move;
}
}
// This method defines the DragDrop event behavior.

protected override void OnDragDrop(DragEventArgs dea)
{
base.OnDragDrop(dea);
// Did a valid move operation occur?

if (dea.Effect == DragDropEffects.Move)
{
// The move operation is valid. Adjust the state
// of the GridStrip control's TableLayoutPanel,
// by swapping the positions of the source button
// and the empty cell button.
// Get the cell of the control to move.
TableLayoutPanelCellPosition sourcePos =
tableSettings.GetCellPosition(this.dragButton);
// Get the cell of the emptyCellButton.

TableLayoutPanelCellPosition dropPos =
tableSettings.GetCellPosition(this.emptyCellButton);
// Move the control to the empty cell.

tableSettings.SetCellPosition(this.dragButton, dropPos);
// Set the position of the empty cell to

// that of the previously occupied cell.
tableSettings.SetCellPosition(this.emptyCellButton,
sourcePos);
// Reset the drag operation.

this.dragButton = null;
}
}
// This method defines the DragLeave event behavior.

// If the mouse leaves the client area of the GridStrip
// control, the drag operation is canceled.
protected override void OnDragLeave(EventArgs e)
{
base.OnDragLeave(e);
// Reset the drag operation.

this.dragButton = null;
}
// This method defines the ueryContinueDrag event behavior.

// If the mouse leaves the client area of the GridStrip
// control, the drag operation is canceled.
OnQueryContinueDrag(QueryContinueDragEventArgs qcdevent)
{
base.OnQueryContinueDrag(qcdevent);
// Get the current mouse position, in screen coordinates.

Point mousePos = this.PointToClient(Control.MousePosition);
// If the mouse position is outside the GridStrip control's

// client area, cancel the drag operation. Be sure to
// transform the mouse's screen coordinates to client
coordinates.
if (!this.ClientRectangle.Contains(mousePos))
{
qcdevent.Action = DragAction.Cancel;
}
}
// This utility method determines if a button

// is positioned relative to the empty cell
// such that it can be dragged into the empty cell.
private bool IsValidDragSource(ToolStripButton b)
{
TableLayoutPanelCellPosition sourcePos =
tableSettings.GetCellPosition(b);
TableLayoutPanelCellPosition emptyPos =
tableSettings.GetCellPosition(this.emptyCellButton);
return (IsValidDragSource(sourcePos, emptyPos));

}
// This utility method determines if a cell position

// is adjacent to the empty cell.
internal static bool IsValidDragSource(
TableLayoutPanelCellPosition sourcePos,
TableLayoutPanelCellPosition emptyPos)
{
bool returnValue = false;
// A cell is considered to be a valid drag source if it

// is adjacent to the empty cell. Cells that are positioned
// on a diagonal are not valid.
if (((sourcePos.Column == emptyPos.Column - 1) && (sourcePos.Row
== emptyPos.Row)) ||
((sourcePos.Column == emptyPos.Column + 1) && (sourcePos.Row
== emptyPos.Row)) ||
((sourcePos.Column == emptyPos.Column) && (sourcePos.Row ==
emptyPos.Row - 1)) ||
((sourcePos.Column == emptyPos.Column) && (sourcePos.Row ==
emptyPos.Row + 1)))
{
returnValue = true;
}
return returnValue;
}
// This class implements a custom ToolStripRenderer for the

// GridStrip control. It customizes three aspects of the
// GridStrip control's appearance: GridStrip border,
// ToolStripButton border, and ToolStripButton image.
internal class GridStripRenderer : ToolStripRenderer
{
// The style of the empty cell's text.
private static StringFormat style = new StringFormat();
// The thickness (width or height) of a

// ToolStripButton control's border.
static int borderThickness = 2;
// The main bitmap that is the source for the

// subimagesthat are assigned to individual
// ToolStripButton controls.
private Bitmap bmp = null;
// The brush that paints the background of

// the GridStrip control.
private Brush backgroundBrush = null;
// This is the static constructor. It initializes the

// StringFormat for drawing the text in the empty cell.
static GridStripRenderer()
{
style.Alignment = StringAlignment.Center;
style.LineAlignment = StringAlignment.Center;
}
// This method initializes the GridStripRenderer by

// creating the image that is used as the source for
// the individual button images.
protected override void Initialize(ToolStrip ts)
{
base.Initialize(ts);
this.InitializeBitmap(ts);
}
// This method initializes an individual ToolStripButton

// control. It copies a subimage from the GridStripRenderer's
// main image, according to the position and size of
// the ToolStripButton.
protected override void InitializeItem(ToolStripItem item)
{
base.InitializeItem(item);
GridStrip gs = item.Owner as GridStrip;
// The empty cell does not receive a subimage.

if ((item is ToolStripButton) &&
(item != gs.EmptyCell))
{
// Copy the subimage from the appropriate
// part of the main image.
Bitmap subImage = bmp.Clone(
item.Bounds,
PixelFormat.Undefined);
// Assign the subimage to the ToolStripButton

// control's Image property.
item.Image = subImage;
}
}
// This utility method creates the main image that

// is the source for the subimages of the individual
// ToolStripButton controls.
private void InitializeBitmap(ToolStrip toolStrip)
{
// Create the main bitmap, into which the image is drawn.
this.bmp = new Bitmap(
toolStrip.Size.Width,
toolStrip.Size.Height);
// Draw a fancy pattern. This could be any image or drawing.

using (Graphics g = Graphics.FromImage(bmp))
{
// Draw smoothed lines.
g.SmoothingMode = SmoothingMode.AntiAlias;
// Draw the image. In this case, it is

// a number of concentric ellipses.
for (int i = 0; i < toolStrip.Size.Width; i += 8)
{
g.DrawEllipse(Pens.Blue, 0, 0, i, i);
}
}
}
// This method draws a border around the GridStrip control.

protected override void OnRenderToolStripBorder(
ToolStripRenderEventArgs e)
{
base.OnRenderToolStripBorder(e);
ControlPaint.DrawFocusRectangle(
e.Graphics,
e.AffectedBounds,
SystemColors.ControlDarkDark,
SystemColors.ControlDarkDark);
}
// This method renders the GridStrip control's background.

protected override void OnRenderToolStripBackground(
ToolStripRenderEventArgs e)
{
base.OnRenderToolStripBackground(e);
// This late initialization is a workaround. The gradient

// depends on the bounds of the GridStrip control. The
bounds
// are dependent on the layout engine, which hasn't fully
// performed layout by the time the Initialize method runs.
if (this.backgroundBrush == null)
{
this.backgroundBrush = new LinearGradientBrush(
e.ToolStrip.ClientRectangle,
SystemColors.ControlLightLight,
SystemColors.ControlDark,
90,
true);
}
// Paint the GridStrip control's background.

e.Graphics.FillRectangle(
this.backgroundBrush,
e.AffectedBounds);
}
// This method draws a border around the button's image. If the

background
// to be rendered belongs to the empty cell, a string is drawn.
Otherwise,
// a border is drawn at the edges of the button.
protected override void OnRenderButtonBackground(
ToolStripItemRenderEventArgs e)
{
base.OnRenderButtonBackground(e);
// Define some local variables for convenience.

GridStrip gs = e.ToolStrip as GridStrip;
ToolStripButton gsb = e.Item as ToolStripButton;
// Calculate the rectangle around which the border is

painted.
Rectangle imageRectangle = new Rectangle(
borderThickness,
borderThickness,
e.Item.Width - 2 * borderThickness,
e.Item.Height - 2 * borderThickness);
// If rendering the empty cell background, draw an

// explanatory string, centered in the ToolStripButton.
if (gsb == gs.EmptyCell)
{
"Drag to here",
gsb.Font,
SystemBrushes.ControlDarkDark,
imageRectangle, style);
}
else
{
// If the button can be a drag source, paint its border
red.
// otherwise, paint its border a dark color.
Brush b = gs.IsValidDragSource(gsb) ? b =
Brushes.Red : SystemBrushes.ControlDarkDark;
// Draw the top segment of the border.

Rectangle borderSegment = new Rectangle(
0,
0,
e.Item.Width,
imageRectangle.Top);
g.FillRectangle(b, borderSegment);
// Draw the right segment.

borderSegment = new Rectangle(
imageRectangle.Right,
0,
e.Item.Bounds.Right - imageRectangle.Right,
imageRectangle.Bottom);
// Draw the left segment.

0,
0,
imageRectangle.Left,
e.Item.Height);
// Draw the bottom segment.

0,
imageRectangle.Bottom,
e.Item.Width,
e.Item.Bounds.Bottom - imageRectangle.Bottom);
}
}
}
#region Windows Forms Designer generated code

{
//
// GridStrip
//
this.AllowDrop = true;
this.BackgroundImageLayout =
System.Windows.Forms.ImageLayout.None;
this.CanOverflow = false;
this.Dock = System.Windows.Forms.DockStyle.None;
this.GripStyle = System.Windows.Forms.ToolStripGripStyle.Hidden;
this.LayoutStyle =
System.Windows.Forms.ToolStripLayoutStyle.Table;
}
#endregion
}
}
Confira também
MenuStrip
ToolStrip
ToolStripRenderer
ToolStripSystemRenderer
StatusStrip
Controle ToolStrip
Como gerenciar o estouro de ToolStrip
nos Windows Forms
Artigo • 21/06/2023
Quando todos os itens em um ToolStrip controle não se encaixam no espaço alocado,

você pode habilitar a ToolStrip funcionalidade de estouro no e determinar o
comportamento de estouro de s específicos ToolStripItem.
Quando você adiciona ToolStripItems que exigem mais espaço do que é alocado para o
ToolStrip tamanho atual do formulário, um ToolStripOverflowButton aparece
automaticamente no ToolStrip. Os ToolStripOverflowButton itens exibidos e habilitados
para estouro são movidos para o menu de estouro suspenso. Isso permite que você
personalize e priorize como seus ToolStrip itens se ajustam corretamente a diferentes
tamanhos de formulário. Você também pode alterar a aparência de seus itens quando
eles se enquadram no estouro usando as Placement propriedades e
ToolStripOverflow.DisplayedItems e o LayoutCompleted evento. Se você ampliar o
formulário em tempo de design ou tempo de execução, mais ToolStripItems poderão
ser exibidos no main ToolStrip e o ToolStripOverflowButton poderá até desaparecer até
diminuir o tamanho do formulário.
Para habilitar o estouro em um controle

ToolStrip
Verifique se a CanOverflow propriedade não está definida false como para o
ToolStrip. O padrão é True .
Quando CanOverflow é True (o padrão), um ToolStripItem é enviado para o menu

de estouro suspenso quando o conteúdo do ToolStripItem excede a largura de um
horizontal ToolStrip ou a altura de um vertical ToolStrip.
Especificar comportamento de estouro de um

item ToolStripItem específico
Defina a Overflow propriedade do ToolStripItem como o valor desejado. As
possibilidades são Always , Never e AsNeeded . O padrão é AsNeeded .
C#
toolStripTextBox1.Overflow = _
System.Windows.Forms.ToolStripItemOverflow.Never;
Confira também
ToolStrip
ToolStripOverflowButton
Overflow
CanOverflow
Como: Remover um ToolStrip de um
ToolStripContainer para um formulário
Artigo • 02/06/2023
Use o procedimento a seguir para mover um ToolStrip de um para um

ToolStripContainer formulário.
Para mover um ToolStrip para fora de um

ToolStripContainer para um formulário
1. Selecione o ToolStrip.
2. Corte pressionando ToolStrip CTRL+X ou clique com o botão direito do ToolStrip

mouse e escolha Cortar no menu de contexto.
3. Selecione o formulário.
4. Cole o ToolStrip pressionando CTRL+V ou escolha Colar no menu Editar .
5. Defina a Dock propriedade da ToolStrip parte superior.
Confira também
ToolStrip
ToolStripContainer
Como: Posicionar um ToolStripItem em
um ToolStrip
Artigo • 02/06/2023
Você pode mover ou adicionar um ToolStripItem ao lado esquerdo ou direito de um

ToolStrip.
Para mover ou adicionar um ToolStripItem ao lado

esquerdo de um ToolStrip
1. Defina a ToolStripItemAlignment propriedade do ToolStripItem como Left.
Para mover ou adicionar um ToolStripItem ao lado direito

de um ToolStrip
1. Defina a ToolStripItemAlignment propriedade do ToolStripItem como Right.
Confira também
ToolStripItem
ToolStripItemAlignment
Left
Right
Como: Definir o renderizador ToolStrip
em tempo de execução
Artigo • 02/06/2023
Você pode personalizar a aparência do controle ToolStrip criando uma classe

personalizada ProfessionalColorTable .
Exemplo
O exemplo de código a seguir demonstra como criar uma classe personalizada
ProfessionalColorTable . Essa classe define gradientes para um MenuStrip e um
ToolStrip controle.
Para usar este exemplo de código, compile e execute o aplicativo e clique em Alterar
Cores para aplicar os gradientes definidos na classe personalizada
ProfessionalColorTable .
C#
using System;
C#
// This code example demonstrates how to use a ProfessionalRenderer

// to define custom professional colors at runtime.
class Form2 : Form
{
public Form2()
{

ts.Items.Add(
"Change Colors",
null,





}

{
new ToolStripProfessionalRenderer(new
CustomProfessionalColors());
}
}

{




}
Definindo uma classe ProfessionalColorTable
personalizada
Os gradientes personalizados são definidos na CustomProfessionalColors classe.
C#

{




}
Atribuindo um renderizador personalizado

Crie um novo ToolStripProfessionalRenderer com uma CustomProfessionalColors
classe e atribua-o ToolStripManager.Renderer à propriedade.
C#

{
new ToolStripProfessionalRenderer(new CustomProfessionalColors());
}
Confira também
ToolStripManager
ProfessionalColorTable
MenuStrip
ToolStrip
Controle ToolStrip
Como: Definir o renderizador ToolStrip
para um aplicativo
Artigo • 02/06/2023
Você pode personalizar a aparência de seus ToolStrip controles individualmente ou para

todos os ToolStrip controles em seu aplicativo.
Exemplo
O exemplo de código a seguir demonstra como aplicar seletivamente um renderizador
personalizado a um ToolStrip controle e a um MenuStrip controle.
Para usar este exemplo de código, compile e execute o aplicativo e selecione o escopo
da rendição personalizada do ComboBox controle. Clique em Aplicar para definir o
renderizador.
Para ver a renderização do item de menu personalizado, selecione a opção MenuStrip

no ComboBox controle, clique em Aplicar e abra o item de menu Arquivo .
C#
using System;
C#
// This example demonstrates how to apply a

// custom professional renderer to an individual
// ToolStrip or to the application as a whole.
class Form6 : Form
{
ComboBox targetComboBox = new ComboBox();
public Form6()
{
// Alter the renderer at the top level.
// Create and populate a new ToolStrip control.

ts.Name = "ToolStrip";
// Create a new menustrip with a new window.
ms.Name = "MenuStrip";
// add top level items

ToolStripMenuItem fileMenuItem = new ToolStripMenuItem("File");
ms.Items.Add(fileMenuItem);
// Add subitems to the "File" menu.

fileMenuItem.DropDownItems.Add("Open");
fileMenuItem.DropDownItems.Add("Save");
fileMenuItem.DropDownItems.Add("Save As...");
fileMenuItem.DropDownItems.Add("-");
fileMenuItem.DropDownItems.Add("Exit");
// Add a Button control to apply renderers.

Button applyButton = new Button();
applyButton.Text = "Apply Custom Renderer";
applyButton.Click += new EventHandler(applyButton_Click);
// Add the ComboBox control for choosing how

// to apply the renderers.
targetComboBox.Items.Add("All");
targetComboBox.Items.Add("MenuStrip");
targetComboBox.Items.Add("ToolStrip");
targetComboBox.Items.Add("Reset");
// Create and set up a TableLayoutPanel control.

TableLayoutPanel tlp = new TableLayoutPanel();
tlp.Dock = DockStyle.Fill;
tlp.RowCount = 1;
tlp.ColumnCount = 2;
tlp.ColumnStyles.Add(new ColumnStyle(SizeType.AutoSize));
tlp.ColumnStyles.Add(new ColumnStyle(SizeType.Percent));
tlp.Controls.Add(applyButton);
tlp.Controls.Add(targetComboBox);
// Create a GroupBox for the TableLayoutPanel control.

GroupBox gb = new GroupBox();
gb.Text = "Apply Renderers";
gb.Dock = DockStyle.Fill;
gb.Controls.Add(tlp);
// Add the GroupBox to the form.

this.Controls.Add(gb);
// Add the ToolStrip to the form's Controls collection.


}

// the "Apply Renderers" button is clicked.
// Depending on the value selected in a ComboBox control,
// it applies a custom renderer selectively to
// individual MenuStrip or ToolStrip controls,
// or it applies a custom renderer to the
// application as a whole.
void applyButton_Click(object sender, EventArgs e)
{
ToolStrip ms = ToolStripManager.FindToolStrip("MenuStrip");
ToolStrip ts = ToolStripManager.FindToolStrip("ToolStrip");
if (targetComboBox.SelectedItem != null)
{
switch (targetComboBox.SelectedItem.ToString())
{
case "Reset":
{
ms.RenderMode = ToolStripRenderMode.ManagerRenderMode;
ts.RenderMode = ToolStripRenderMode.ManagerRenderMode;
// Set the default RenderMode to Professional.

ToolStripManager.RenderMode =
ToolStripManagerRenderMode.Professional;
break;
}
case "All":
{
ms.RenderMode = ToolStripRenderMode.ManagerRenderMode;
ts.RenderMode = ToolStripRenderMode.ManagerRenderMode;
// Assign the custom renderer at the application level.

ToolStripManager.Renderer = new
CustomProfessionalRenderer();
break;
}
case "MenuStrip":
{
// Assign the custom renderer to the MenuStrip control
only.
ms.Renderer = new CustomProfessionalRenderer();
break;
}
case "ToolStrip":
{
// Assign the custom renderer to the ToolStrip control
only.
ts.Renderer = new CustomProfessionalRenderer();
break;
}
}
}
}
}
// This type demonstrates a custom renderer. It overrides the

// OnRenderMenuItemBackground and OnRenderButtonBackground methods
// to customize the backgrounds of MenuStrip items and ToolStrip buttons.
class CustomProfessionalRenderer : ToolStripProfessionalRenderer
{
OnRenderMenuItemBackground(ToolStripItemRenderEventArgs e)
{
if (e.Item.Selected)
{
using (Brush b = new
SolidBrush(ProfessionalColors.SeparatorLight))
{
e.Graphics.FillEllipse(b, e.Item.ContentRectangle);
}
}
else
{
using (Pen p = new Pen(ProfessionalColors.SeparatorLight))
{
e.Graphics.DrawEllipse(p, e.Item.ContentRectangle);
}
}
}

{
Rectangle r = Rectangle.Inflate(e.Item.ContentRectangle, -2, -2);
if (e.Item.Selected)
{
using (Brush b = new
SolidBrush(ProfessionalColors.SeparatorLight))
{
e.Graphics.FillRectangle(b, r);
}
}
else
{
using (Pen p = new Pen(ProfessionalColors.SeparatorLight))
{
e.Graphics.DrawRectangle(p, r);
}
}
}
}
Defina a ToolStripManager.Renderer propriedade para aplicar um renderizador

personalizado a todos os ToolStrip controles em seu aplicativo.
Defina a ToolStrip.Renderer propriedade para aplicar um renderizador personalizado a

um controle individual ToolStrip .

Confira também
ToolStripManager
MenuStrip
ToolStrip
Controle ToolStrip
Como alongar um ToolStripTextBox para
preencher a largura restante de um
ToolStrip (Windows Forms)
Artigo • 02/06/2023
Quando você define a Stretch propriedade de um ToolStrip controle como true , o

controle preenche seu contêiner de ponta a ponta e redimensiona quando seu
contêiner é redimensionado. Nesta configuração, você pode achar útil esticar um item
no controle, como um ToolStripTextBox, para preencher o espaço disponível e
redimensionar quando o controle for redimensionado. Esse alongamento será útil, por
exemplo, se você desejar obter aparência e comportamento semelhantes para a barra
de endereços do Microsoft® Internet Explorer.
Exemplo
O exemplo de código a seguir fornece uma classe derivada da ToolStripTextBox
chamada ToolStripSpringTextBox . Essa classe substitui o GetPreferredSize método para
calcular a largura disponível do controle pai ToolStrip depois que a largura combinada
de todos os outros itens tiver sido subtraída. Este exemplo de código também fornece
uma Form classe e uma Program classe para demonstrar o novo comportamento.
C#
using System;
public class ToolStripSpringTextBox : ToolStripTextBox

{
public override Size GetPreferredSize(Size constrainingSize)
{
// Use the default size if the text box is on the overflow menu
// or is on a vertical ToolStrip.
if (IsOnOverflow || Owner.Orientation == Orientation.Vertical)
{
return DefaultSize;
}
// Declare a variable to store the total available width as

// it is calculated, starting with the display width of the
// owning ToolStrip.
Int32 width = Owner.DisplayRectangle.Width;
// Subtract the width of the overflow button if it is displayed.
if (Owner.OverflowButton.Visible)
{
width = width - Owner.OverflowButton.Width -
Owner.OverflowButton.Margin.Horizontal;
}
// Declare a variable to maintain a count of ToolStripSpringTextBox

// items currently displayed in the owning ToolStrip.
Int32 springBoxCount = 0;
foreach (ToolStripItem item in Owner.Items)

{
// Ignore items on the overflow menu.
if (item.IsOnOverflow) continue;
if (item is ToolStripSpringTextBox)
{
// For ToolStripSpringTextBox items, increment the count and
// subtract the margin width from the total available width.
springBoxCount++;
width -= item.Margin.Horizontal;
}
else
{
// For all other items, subtract the full width from the
total
// available width.
width = width - item.Width - item.Margin.Horizontal;
}
}
// If there are multiple ToolStripSpringTextBox items in the owning

// ToolStrip, divide the total available width between them.
if (springBoxCount > 1) width /= springBoxCount;
// If the available width is less than the default width, use the
// default width, forcing one or more items onto the overflow menu.
if (width < DefaultSize.Width) width = DefaultSize.Width;
// Retrieve the preferred size from the base class, but change the
// width to the calculated width.
Size size = base.GetPreferredSize(constrainingSize);
size.Width = width;
return size;
}
}

{
public Form1()
{
ToolStrip toolStrip1 = new ToolStrip();
toolStrip1.Dock = DockStyle.Top;
toolStrip1.Items.Add(new ToolStripLabel("Address"));
toolStrip1.Items.Add(new ToolStripSpringTextBox());
toolStrip1.Items.Add(new ToolStripButton("Go"));
Controls.Add(toolStrip1);
Text = "ToolStripSpringTextBox demo";
}
}

{
[STAThread]
static void Main()
{
}
}
Confira também
ToolStrip
ToolStrip.Stretch
ToolStripTextBox
ToolStripTextBox.GetPreferredSize
Como: Usar a propriedade Spring de forma interativa em um StatusStrip
Como: Usar ToolTips em controles
ToolStrip
Artigo • 02/06/2023
Você pode exibir um ToolTip para o ToolStrip controle desejado definindo a propriedade
do ShowItemToolTips controle como true .
Para exibir uma dica de ferramenta

Defina a ShowItemToolTips propriedade do controle como true .
O valor ToolStrip.ShowItemToolTips padrão é true , e o valor padrão de

MenuStrip.ShowItemToolTips e StatusStrip.ShowItemToolTips é false .
Para usar a propriedade ToolTipText para o texto de dica

de ferramenta de um ToolStripButton
1. Defina a ShowItemToolTips propriedade do botão como true .
2. Defina a ToolStripButton.AutoToolTip propriedade do botão como false .
A AutoToolTip propriedade é true , por padrão, para ToolStripButton,

ToolStripDropDownButtone ToolStripSplitButton.
A ToolStripButton usa sua Text propriedade para o ToolTip texto por padrão. Use
este procedimento para exibir texto personalizado em um ToolStripButtonToolTip.
７ Observação
Se você definir ToolStripItemDisplayStyle como None ou Image, nenhum texto

será exibido no botão, mas a dica de ferramenta ainda será exibida.
Confira também
ShowItemToolTips
ToolStripButton
Como: Encapsular um controle do
Windows Forms com
Artigo • 02/06/2023
ToolStripControlHostfoi projetado para habilitar a hospedagem de controles arbitrários

de Windows Forms usando o ToolStripControlHost construtor ou estendendo-
seToolStripControlHost. É mais fácil encapsular o controle estendendo
ToolStripControlHost e implementando propriedades e métodos que expõem
propriedades e métodos usados com frequência do controle. Você também pode expor
eventos para o controle no ToolStripControlHost nível.
Para hospedar um controle em um ToolStripControlHost

por derivação
1. Estender ToolStripControlHost. Implemente um construtor sem parâmetros que
chama o construtor de classe base passando o controle desejado.
C#
// Call the base constructor passing in a MonthCalendar instance.

public ToolStripMonthCalendar() : base (new MonthCalendar()) { }
2. Declare uma propriedade do mesmo tipo que o controle encapsulado e retorne

Control como o tipo correto de controle no acessador de propriedade.
C#
public MonthCalendar MonthCalendarControl

{
get
{
return Control as MonthCalendar;
}
}
3. Exponha outras propriedades e métodos usados com frequência do controle

encapsulado com propriedades e métodos na classe estendida.
C#
// Expose the MonthCalendar.FirstDayOfWeek as a property.
public Day FirstDayOfWeek
{
get
{
return MonthCalendarControl.FirstDayOfWeek;
}
set { MonthCalendarControl.FirstDayOfWeek = value; }
}
// Expose the AddBoldedDate method.

public void AddBoldedDate(DateTime dateToBold)
{
MonthCalendarControl.AddBoldedDate(dateToBold);
}
4. Opcionalmente, substitua os métodos e OnUnsubscribeControlEvents os

OnSubscribeControlEventsmétodos e adicione os eventos de controle que você
deseja expor.
C#
protected override void OnSubscribeControlEvents(Control c)

{
// Call the base so the base events are connected.
base.OnSubscribeControlEvents(c);
// Cast the control to a MonthCalendar control.

MonthCalendar monthCalendarControl = (MonthCalendar) c;
// Add the event.

monthCalendarControl.DateChanged +=
new DateRangeEventHandler(OnDateChanged);
}
protected override void OnUnsubscribeControlEvents(Control c)

{
// Call the base method so the basic events are unsubscribed.
base.OnUnsubscribeControlEvents(c);

// Remove the event.

monthCalendarControl.DateChanged -=
}
5. Forneça o encapsulamento necessário para os eventos que deseja expor.

C#
// Declare the DateChanged event.

public event DateRangeEventHandler DateChanged;
// Raise the DateChanged event.

private void OnDateChanged(object sender, DateRangeEventArgs e)
{
if (DateChanged != null)
{
DateChanged(this, e);
}
}
Exemplo
C#
//Declare a class that inherits from ToolStripControlHost.

public class ToolStripMonthCalendar : ToolStripControlHost
{
// Call the base constructor passing in a MonthCalendar instance.
public ToolStripMonthCalendar() : base (new MonthCalendar()) { }
public MonthCalendar MonthCalendarControl

{
get
{
return Control as MonthCalendar;
}
}
// Expose the MonthCalendar.FirstDayOfWeek as a property.

public Day FirstDayOfWeek
{
get
{
return MonthCalendarControl.FirstDayOfWeek;
}
set { MonthCalendarControl.FirstDayOfWeek = value; }
}
// Expose the AddBoldedDate method.

public void AddBoldedDate(DateTime dateToBold)
{
MonthCalendarControl.AddBoldedDate(dateToBold);
}
// Subscribe and unsubscribe the control events you wish to expose.

protected override void OnSubscribeControlEvents(Control c)
{
// Call the base so the base events are connected.
base.OnSubscribeControlEvents(c);

// Add the event.

monthCalendarControl.DateChanged +=
}
protected override void OnUnsubscribeControlEvents(Control c)

{
// Call the base method so the basic events are unsubscribed.
base.OnUnsubscribeControlEvents(c);

// Remove the event.

monthCalendarControl.DateChanged -=
}
// Declare the DateChanged event.

public event DateRangeEventHandler DateChanged;
// Raise the DateChanged event.

private void OnDateChanged(object sender, DateRangeEventArgs e)
{
if (DateChanged != null)
{
DateChanged(this, e);
}
}
}
Confira também
Passo a passo: Criar um controle
ToolStrip com estilo profissional
Artigo • 02/06/2023
Você pode dar aos controles do ToolStrip aplicativo uma aparência e um

comportamento profissionais escrevendo sua própria classe derivada do
ToolStripProfessionalRenderer tipo.
Este passo a passo demonstra como usar ToolStrip controles para criar um controle
composto semelhante ao Painel de Navegação fornecido pelo Microsoft® Outlook®.
As seguintes tarefas são ilustradas nesta explicação passo a passo:
Criar um projeto da Biblioteca de Controle do Windows.
Projetar o controle StackView.
Implementar um renderizador personalizado.
Quando tiver terminado, você terá um controle de cliente personalizado reutilizável com
a aparência profissional de um controle do Microsoft Office XP.
Para copiar o código neste tópico como uma única lista, consulte Como criar um
controle ToolStrip com estilo profissional.
Pré-requisitos
Criar o projeto da biblioteca de controle

1. No Visual Studio, crie um novo projeto da Biblioteca de Controle do Windows
chamado StackViewLibrary .
2. No Gerenciador de Soluções, exclua o controle padrão do projeto excluindo o

arquivo de origem denominado "UserControl1.cs" ou "UserControl1.vb",
dependendo da linguagem de sua escolha.
Para obter mais informações, consulte Como remover, excluir e excluir itens.
3. Adicione um novo UserControl item ao projeto StackViewLibrary . Dê ao novo

arquivo de origem o nome base StackView .
Projetar o controle StackView
O StackView controle é um controle composto com um controle filho ToolStrip . Para
obter mais informações sobre controles de composição, consulte Variedades de
controles personalizados.
1. Na Caixa de Ferramentas, arraste um ToolStrip controle para a superfície de

design.
2. Na janela Propriedades , defina as ToolStrip propriedades do controle de acordo

com a tabela a seguir.
Propriedade Valor
Nome stackStrip
CanOverflow false
Dock Bottom
Fonte Tahoma, 10pt, style=Bold
GripStyle Hidden
LayoutStyle VerticalStackWithOverflow
Preenchimento 0, 7, 0, 0
RenderMode Professional
3. No Designer Windows Forms, clique no ToolStrip botão Adicionar do controle e

adicione um ToolStripButton ao stackStrip controle.
4. Na janela Propriedades , defina as ToolStripButton propriedades do controle de

acordo com a tabela a seguir.
Propriedade Valor
Nome mailStackButton
CheckOnClick true
CheckState Checked
DisplayStyle ImageAndText
ImageAlign MiddleLeft
Propriedade Valor
ImageScaling None
ImageTransparentColor 238, 238, 238
Margem 0, 0, 0, 0
Preenchimento 3, 3, 3, 3
Texto Correio
TextAlign MiddleLeft
5. Repita a etapa 7 para mais ToolStripButton três controles.
Nomeie os controles como calendarStackButton , contactsStackButton e

tasksStackButton . Defina o valor da Text propriedade como Calendário, Contatos
e Tarefas, respectivamente.
Tratar eventos
Dois eventos são importantes para fazer com que o controle StackView se comporte
corretamente. Manipule o Load evento para posicionar o controle corretamente.
Manipule o Click evento para cada ToolStripButton um fornecer o comportamento de
estado do StackView controle semelhante ao RadioButton controle.
1. No Designer de Formulários do Windows, selecione o controle StackView .
3. Clique duas vezes no evento Carregar para gerar o manipulador de eventos

StackView_Load .
4. No manipulador de eventos StackView_Load , copie e cole o código a seguir.
C#
// This method handles the Load event for the UserControl.

private void StackView_Load(object sender, EventArgs e)
{
// Dock bottom.
this.Dock = DockStyle.Bottom;
// Set AutoSize.
}
5. No Designer de Formulários do Windows, selecione o controle mailStackButton .
7. Clique duas vezes no evento Clique.
O Designer de Formulários do Windows gera o manipulador de eventos

mailStackButton_Click .
8. Renomeie o manipulador de eventos mailStackButton_Click como

stackButton_Click .
Para obter mais informações, consulte Renomear uma refatoração de símbolo de

código.
9. Adicione o seguinte código ao manipulador de eventos stackButton_Click .
C#
// This method handles the Click event for all

// the ToolStripButton controls in the StackView.
private void stackButton_Click(object sender, EventArgs e)
{
// Define a "one of many" state, similar to
// the logic of a RadioButton control.
foreach (ToolStripItem item in this.stackStrip.Items)
{
if ((item != sender) &&
(item is ToolStripButton))
{
((ToolStripButton)item).Checked = false;
}
}
}
10. No Designer de Formulários do Windows, selecione o controle

calendarStackButton .
11. Na janela Propriedades, defina o evento Clique para o manipulador de eventos

stackButton_Click .
12. Repita as etapas 10 e 11 para os controles contactsStackButton e

tasksStackButton .
Definir ícones
Cada botão StackView tem um ícone associado. Para conveniência, cada ícone é
representado como uma cadeia de caracteres codificada em Base64, que é
desserializada antes de uma Bitmap ser criada a partir dela. Em um ambiente de
produção, armazene dados de bitmap como um recurso e seus ícones serão exibidos no
Designer de Formulários do Windows. Para obter mais informações, consulte Como
adicionar imagens de tela de fundo ao Windows Forms.
1. No Editor de Códigos, insira o seguinte código na definição de classe StackView .

Esse código inicializa os bitmaps para os ToolStripButton ícones.
C#
private static Bitmap mailBmp;

private static Bitmap calendarBmp;
private static Bitmap contactsBmp;
private static Bitmap tasksBmp;
private static string mailBmpEnc = @"Qk32BgAAAAAAADYAAAAoAAAA"+

"GAAAABgAAAABABgAAAAAAAAAAADEDgAAxA4AAAAAAAAAAAAA7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7uv4yFvouE"+
"vYmDu4eBuYV/t4N9tYB7s355sXt3tntxsnhwsHZurXNsrHFrp21pomln"+
"oGdlnmVjnWNi7u7u7u7u7u7u7u7u7u7uwY6H9N3C/vDa/ejM+tSp+cye"+
"98OS9bqI87F/87KA8qt68KRy76Bu7phl7ZVi7JVi54xb0ntSoGVj7u7u"+
"7u7u7u7u7u7u7u7uwo+Ix6WZ9ujb//bn/u/b/OfL++HA+9iv+tev+tSr"+
"+tKo+cyg+Mic9b+S9LqM8al35ZZmoXBSoWdk7u7u7u7u7u7u7u7u7u7u"+
"xZSN9ejayaOY9uvh//js/vXo/e/a/evS/OfL/OTF+927+9u1+tSq+tKl"+
"+cqW8buFqHZa7JVdn2hm7u7u7u7u7u7u7u7u7u7uxZSN//ns9ercxqKV"+
"+O7k//nw//fu//fr/vTl/u/c/uvU/eLB/N+7+tev8b6Hq3pe+Lh6/69q"+
"oWpp7u7u7u7u7u7u7u7u7u7ux5eP//vv//vw9OncxKOX9+7m//v1//nz"+
"//jx//bs/+7Z/erQ/eTC8syiqntg+M6a/9Oh/8CFom1s7u7u7u7u7u7u"+
"7u7u7u7uypqS//z4//v28ebYza2evp6V7+Lb8uzl8+3l8uvk9Ore9ejZ"+
"6NO/poVyt4xx5b2T/9ap/8ybpXFw7u7u7u7u7u7u7u7u7u7uzJ2V///8"+
"7uPbzaye/fv6/fv5v6GTvKCQvJ+Nu5qIupmJt5uKsZWE+u3e+unYo4Jq"+
"572O/9KjqHd17u7u7u7u7u7u7u7u7u7uzqCX7OHbzKud/fr58url5tnQ"+
"5dfO5dfN5dfM5NbM49TI3Mq+3Mm93Mm8382/+unbrIJp57WGrH597u7u"+
"7u7u7u7u7u7u7u7uz6GZ0LGj6uHa/fv67OLc6+Hb7eTd7ePd7eLb7eLb"+
"7uPb9e7l9evk9uvj9+zh/PHlzr61r4VtsoWC7u7u7u7u7u7u7u7u7u7u"+
"0aKXfdb/8uzn///////////////////////+//37/Pn3+fXv9fHp8+vl"+
"8enk7uXe1si/L6f3tYeC7u7u7u7u7u7u7u7u7u7uy6mkdM3/+vf1////"+
"/////////////////fz8/Pv69fPx7vDw7O/w2OfvxN/swt/thMXnK6ft"+
"r4SC7u7u7u7u7u7u7u7u7u7u1KeevuX6nNf2rN/7nNz9h9X+b8z+VMb/"+
"RsT/RsT/PsP/Obz7NLT2MbL0K6vuJ6XpKKfrLqrvr4J/7u7u7u7u7u7u"+
"7u7u7u7u28jC0rSo0O36yOv7x+r7v+f8suP9o97+jtj+idn+htX/e83/"+
"a8f/XcD/Tbn/SLf/R7b/rJKJ7u7u7u7u7u7u7u7u7u7u7u7u7u7u6ePi"+
"07ew29zd1e/61O/60e77y+z8vun9reH+mNn+gdH/ccj/ZMP/Vr3/t7/C"+
"uKCX7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u6uXk2b621rux1fH6"+
"3fL61/L7y+/8u+f9pt7+jNT+cMn/XcH/rZyW1c3L7u7u7u7u7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u6N/d07Op3d7f2/P60vD7xez8"+
"r+H9k9X+kr/cv6Wb7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u6uXk2L612cG31e73yOv7seL8uKWezLex7u7u"+
"7u7u7u7u7u7u6eHg1LOpzaeayaqh4dvb7u7u7u7u7u7u7u7u7u7u7u7u"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u";
private static string calendarBmpEnc = @"Qk32BgAAAAAAADYAAAAo"+

"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7uuKOUkXxqemNO"+
"alM8YEgwYEgwYkoxYUgwYEgwY0szYkoxYEgwYEgwYEgwYEgwZEszYUgw"+
"YEgwY0oyYUgwYEgwYEgw7u7u7u7uuqWW6tPE27qlxKCLu5d837OUzKGC"+
"t41xsYpt37OUzKGCt41xrodq37OUzKGCt41xrodq37OUzKGCt41xrodq"+
"Zk447u7u7u7uvKaX//fz/+3i/NvFwJl6/+nb/d3H+c+1vJV2/+HP/tW8"+
"/MWluZJz/9vG/9Gw+8OfuJFy/86y/sKf97eSuJFyYEgw7u7u7u7uvaiZ"+
"//j2//Hq/OTY0qiL/+7h/+TR/N3J0KWI/+TU/9vE/9S4zqOF/+LR/9zE"+
"/sywzaKE/9e//8yt/sWizaKEYEgw7u7u7u7uv6qb//v5//j1//bx5Lug"+
"//Ho//Dl/+nb5Lqg/+fZ/+LQ/97I5Lqf/+XU/+HN/9zF5Lqf/9bC/9S7"+
"/9C05LqfYEgw7u7u7u7uwauc4bib1ayOxZyBvpd74LaY0qiKwJd7uJF1"+
"4LWWz6WGvJJ2D0XuBTnjBjXQAiy8ACm137OUzKGCt41xrodqYEgw7u7u"+
"7u7uxK6f//v6/Ozg/eHQx6CC/+/m+uHQ+tjDwpt9/+re/+DM/9O4I1Tz"+
"/9zG/9O5/86wASu4/9fC98Sm87uYuJFyYEgw7u7u7u7uxrCh//39//n0"+
"/One1qyQ//v4/vHn+uHR06mM//Pt/+rc/+HMPGr0/+TU/93H/9i/AzHJ"+
"/+LP/9i++curzaKEYEgw7u7u7u7ux7Kj//39//38/fbw5Luh//z7/vj1"+
"/uzh5Lug//fx//bv/+vgWoH2/+/m/+vd/+PQAzTa/+XU/+XU/97J5Lqf"+
"YUkx7u7u7u7uybOk47yh3rab1q2SzaWL4bqe2a+SzKKHwpqA4bmd1q2O"+
"x52CbY/5WYD3OWb0IFP0Aj3t4Lib06iJwJV5sopwYEgw7u7u7u7uzbep"+
"//39//n1//Dn1a2S/vv6+uvh9+DPyqKG//Tt+eXX+eDSxJx//One+tzH"+
"+dC3v5d6/9/K+9C1+8akuI9yalM97u7u7u7u0Lyu//39//r3//f03bWa"+
"//7+/vXx+urg1q2R//f0/O3i+eTV06mM//fy/+7i+NfCz6WI/+zg/+DM"+
"/9CzyZ6Adl5I7u7u7u7u0sCy//38//39//395L2j//7+//79/vn45L2j"+
"//38//n2/vLr5L2j//37//n2/unf5L2j/+/l/+nc/+DN5L2jf2dS7u7u"+
"7u7u6KaG6KaG6KSE56OB56B+55565pt25phy5ZVt5ZJp5I5k5Itf5Iha"+
"44RV44FR4n5M4ntI4XhE23I812w00mkzyGAo7u7u7u7u6amK/93L/dfD"+
"/9a+/s+2/syy/sis/sSl/cGh/byb/LeV+7SO+rCJ+auC+ad9+KN3+KBx"+
"95xu95pq9pdn9pVkyGAo7u7u7u7u662P/+LQ/t/M/t3K/drG/dfC/dK8"+
"/c63/Mqx/Mer+sKk+r6f+bqY+LaT+LGM96yG9qmA9aV69aB19J1w9Jps"+
"yGAo7u7u7u7u7LKV7LKV662P6aeG56F/559855x45pp05pdw5ZRs5ZFo"+
"5I5j5Itf5Ihb44VW44JS4n9O4nxK4XpG4XdC4XU/2Ws27u7u7u7upJqU"+
"////pJqU////n5aQ////mZCL////kYmF////iIJ+////fnp2////dXJv"+
"////bGpo////ZGNi////XV5c////7u7u7u7u7u7uICUg6enpICUg6enp"+
"ICUg6enpICUg6enpICUg6enpICUg6enpICUg3t7eICUg0NDQICUgvb29"+
"ICUguLi4ICUg7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u"+
"7u7u";
private static string contactsBmpEnc = @"Qk32BgAAAAAAADYAAAAo"+
"7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7uuqWWh3FeeWJN"+
"alM8YEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgwYEgw"+
"YEgwYEgwYEgwYEgwYEgw7u7u7u7uuqWW//bx7t3T7trO7tfI79LB7865"+
"8Mqy8MWq8cCi8buZ8raR8rKJ862C86l69KV09KFt9Z5o9Zxk9Zph9Zph"+
"YEgw7u7u7u7uu6aX//n2//fy//Xv//Lr//Dn/+3j/+re/+ja/+XW/+LR"+
"/+DN/93J/9rF/9jB/9W9/9O5/9G2/8+z/86x9ZphYEgw7u7u7u7uvKiZ"+
"//z6//r30M/SGlmtA0uuA0WfAz+RATmHADV9zr23/+PTs4t1roRuqX1m"+
"pHhgoXRcoXRcoXRc/9C09Z1mYEgw7u7u7u7uvqqb//79//z7FFe3N3rV"+
"SYrkQ4XeA0OaGW3eC02nGkF4/+fZ/+TV/+LQ/9/M/9zI/9rE/9fA/9W8"+
"/9O59KFtYEgw7u7u7u7uwKyd//////7+E1i3Z57pUZDoTY7nA0SbGGze"+
"E2DIAzmD/+vfuZJ9s4t1roRuqX1mpHhgoXRcoXRc/9a99KV0YEgw7u7u"+
"7u7uwq6f////////GF69gKvkX5flA0WeGW7iA0+3GWzgEk+j/+7l/+zh"+
"/+nc/+bY/+TT/+HP/97L/9zH/9nD86t9YEgw7u7u7u7uxLCh////////"+
"tcDPE1StGly1yNXZ+fryBVG5BkGOz8rK//LqvpiEuZJ9s4t1roRuqX1m"+
"pHhgoXRc/93I87CHYEgw7u7u7u7uxrKk////////9fX1zdDTYWZsVFVW"+
"YWFhBkunubzC//jz//Xw//Ps//Do/+7k/+vf/+jb/+bX/+PS/+DO8raR"+
"YEgw7u7u7u7ux7Sm////////xMTEAAAAwcHBoqKihYWFVVVVn56d//r3"+
"//j0//bx//Tt//Hp/+/l/+zh/+nd/+fY/+TU8b2cYEgw7u7u7u7uybao"+
"////////ODg4LCws1tbWwcHBoqKihYWFZGRk//37//v5//n2//fy//Xv"+
"//Lr//Dn/+3j/+re/+ja8MOmYEgw7u7u7u7uy7iq////////U1NTSUlJ"+
"tLS01dXVwcHBoqKidXV1///+//38/LeL+7SI+q+D+ap++KV496Bz9p1w"+
"/+vg8MmxZk437u7u7u7uzbqs////////fn5+Y2NjXV1dbW1tWFhYwcHB"+
"hISE//////////79//z7//v4//n1//bx//Tu//Lq/+/m78+6b1dB7u7u"+
"7u7uz7yu////////xcXFbGxsgoKCoaGhjo6OVVVVra2t/////////LeL"+
"+7SI+q+D+ap++KV496Bz9p1w//Pr79TEeWJN7u7u7u7u0L6w////////"+
"8vLyuLi4jY2NiIiIhYWFtLS08fHx//////////////////////38//z6"+
"//r3//j0//bw7tnMgm1Z7u7u7u7u0b+x////////////////////////"+
"//////////////////////////////////////79//z7//v4//n1//fy"+
"i3Zj7u7u7u7u0sCy0b+x0L6wz72vzrutzLqsy7iqybeoyLWmxrOkxLGi"+
"w6+hwa2fv6udvqmbvKiZu6aXuaWWuKOUt6KTtqGStaCR7u7u7u7u7u7u"+
"7u7u";
private static string tasksBmpEnc = @"Qk32BgAAAAAAADYAAAAoAAA"+

"AGAAAABgAAAABABgAAAAAAAAAAADEDgAAxA4AAAAAAAAAAAAA7u7u7u7"+
"u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u3N3fkXxqeGB"+
"LalE5cVc/c1lBf2JKl3RZiWhMe1xBb1M5aE42Zkw0Zk01aE42YUkxYkk"+
"xYkkxkod97u7u7u7u7u7u7u7u7u7uv62e+ezi69nQ7M6+7Miz6L+prI+"+
"rWFKqmHyk7rWU77OO77CM8LCK8bCH8a2F8qp98aV13pZnZkwz7u7u7u7"+
"u7u7u7u7u7u7uv62e//37/vr3/vTw+uvkwLnaJDO/BhmzJjTDybTG99K"+
"8+NC49syy9sms9sao9cOl8LiV8KR0aU417u7u7u7u7u7u7u7u7u7uwK6"+
"f//7+//z7/Pj3xcTmLDvBFynIMEXkIDbXVGHO6dHO+tzJ+tjD+dW++dK"+
"5+c+19sWn8qd2Y0kx7u7u7u7u7u7u7u7u7u7uw7Gj/////Pv9wcTsKDj"+
"FFCnMRVjuZHX1PlPoFzHSeHPJ+d3O+tzI+tjD+dS9+dG59seq8ayEaEw"+
"07u7u7u7u7u7u7u7u7u7uxrWm9vf9pKzoJjjNGi7TR1nreoj/j5v8ZXf"+
"0N0zlJjTPv7LP+t7O+tvI+tfC+dS998qv8K+LaU427u7u7u7u7u7u7u7"+
"u7u7u08W619v5Kz7XJjrfTl/ze4v/tLr59/Dyoab2Znb0LUPmNUTO1sX"+
"R+9/N+tvH+tjC99C277GNbVI47u7u7u7u7u7u7u7u7u7uy7qt6+3+kp7"+
"4UGT4c4P/sbj+/Pr5/vj16ePykpz5Y3T0KDzfbHHR6dTS++HQ+tvG+dn"+
"D8bqabVI57u7u7u7u7u7u7u7u7u7uybeo////9ff/qLL/wsr//Pz///3"+
"8/vv5/ff09e7wpav4YnP0KDzajYzQ6NPT/N7O+NrG8b+idFlA7u7u7u7"+
"u7u7u7u7u7u7uyriq////////+Pn//v7///////////38/vr2/vj08er"+
"wmaL6WWvyMELXmJbS9OPb+d/Q88mxc1Y97u7u7u7u7u7u7u7u7u7uzLq"+
"s//////////////////////////7+//36/vr3/vn0+fDvsLT1WmruNUb"+
"Qta/V+uXX9M+6hWdP7u7u7u7u7u7u7u7u7u7uzryt///////////////"+
"///////////////7+//79//v3/vj0+O7wurz0TV3sSFTS08fa9t7PmXl"+
"h7u7u7u7u7u7u7u7u7u7uz72v/////////////////////fj1+Orh9uH"+
"W89TD88+78sew9NK99drNm5/xVWbwYWvV6dzgrIlw7u7u7u7u7u7u7u7"+
"u7u7u0L6w////////////////X4ycVYGSTHaIS21/SGN0SGJySF9vdnd"+
"9pZWQ89TDt7n1TF3oZGvOuJ2L7u7u7u7u7u7u7u7u7u7u0b+x///////"+
"/////////dJmou+Xsmd3ofs/fdcXVcMHSbrrNbbHCbHJ69dTD++3nw8H"+
"uNUjqZGjJ7u7u7u7u7u7u7u7u7u7u0b+x////////////////i6q2pMn"+
"StuzzYYycdLG+fs/ed8jaXY2eRl1t8uDU++je/O7mzsnmUFCX7u7u7u7"+
"u7u7u7u7u7u7u0sCy////////////////3ufqdZuqx+30V3aFXoCPaZW"+
"kjdDeTWx8v7Ko/vr2/fTv/fTu+/XxnZSu7u7u7u7u7u7u7u7u7u7u6ur"+
"r2Mq/0b+x0L6wz72vyLeqc5qpoMHLxfD3v+zzruXvkMjVaX6GwK6ewrC"+
"hwa+gwK6fv62e4OHi7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7"+
"u7u7u5ObnfKa1eaOxcpyrcJWkboiW4+Pj7u7u7u7u7u7u7u7u7u7u7u7"+
"u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u";
// Static constructor to initialize

// the form's static fields.
static StackView()
{
// Create the static bitmaps from Base64 encoding.
CreateBitmaps();
}
public StackView()
{

}
// This utility method assigns icons to each

// ToolStripButton control.
private void InitializeImages()
{
this.mailStackButton.Image = mailBmp;
this.calendarStackButton.Image = calendarBmp;
this.contactsStackButton.Image = contactsBmp;
this.tasksStackButton.Image = tasksBmp;
}
// This utility method creates bitmaps for all the icons.

// It uses a utility method called DeserializeFromBase64
// to decode the Base64 image data.
private static void CreateBitmaps()
{
mailBmp = DeserializeFromBase64(mailBmpEnc);
calendarBmp = DeserializeFromBase64(calendarBmpEnc);
contactsBmp = DeserializeFromBase64(contactsBmpEnc);
tasksBmp = DeserializeFromBase64(tasksBmpEnc);
}
// This utility method cretes a bitmap from

// a Base64-encoded string.
internal static Bitmap DeserializeFromBase64(string data)
{
// Decode the string and create a memory stream
// on the decoded string data.
MemoryStream stream =
new MemoryStream(Convert.FromBase64String(data));
// Create a new bitmap from the stream.

Bitmap b = new Bitmap(stream);
return b;
}
2. Adicione uma chamada ao método InitializeImages no construtor de classe

StackView .
C#
public StackView()
{

}
Implementar um renderizador personalizado
Você pode personalizar a maioria dos elementos do StackView controle em que
implemento uma classe derivada da ToolStripRenderer classe. Neste procedimento, você
implementará uma ToolStripProfessionalRenderer classe que personaliza a aderência e
desenha planos de fundo gradientes para os ToolStripButton controles.
1. Insira o seguinte código na definição de controle StackView .
Essa é a definição para a StackRenderer classe, que substitui o RenderGrip,

RenderToolStripBordere RenderButtonBackground os métodos para produzir uma
aparência personalizada.
C#
internal class StackRenderer : ToolStripProfessionalRenderer

{
private static Bitmap titleBarGripBmp;
private static string titleBarGripEnc =
@"Qk16AQAAAAAAADYAAAAoAAAAIwAAAAMAAAABABgAAAAAAAAAAADEDgAAxA4AAAAAAAAAA
AAAuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy
+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n5uGMyuGMy+/n5+/n
5ANj+RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/Rz
IomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+/n5wm8/RzIomHRh+
/n5ANj+RzIoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzIozHtMzHtM
RzIoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzIozHtMzHtMRzIoRzI
ozHtMANj+";
// Define titlebar colors.

private static Color titlebarColor1 = Color.FromArgb(89, 135, 214);
private static Color borderColor = Color.FromArgb(0, 0, 128);
static StackRenderer()
{
titleBarGripBmp =
StackView.DeserializeFromBase64(titleBarGripEnc);
}
public StackRenderer()
{
}
private void DrawTitleBar(Graphics g, Rectangle rect)

{
// Assign the image for the grip.
Image titlebarGrip = titleBarGripBmp;
// Fill the titlebar.

// This produces the gradient and the rounded-corner effect.
g.DrawLine(new Pen(titlebarColor1), rect.X, rect.Y, rect.X +
rect.Width, rect.Y);
g.DrawLine(new Pen(titlebarColor2), rect.X, rect.Y + 1, rect.X
+ rect.Width, rect.Y + 1);
// Center the titlebar grip.

g.DrawImage(
titlebarGrip,
new Point(rect.X + ((rect.Width / 2) - (titlebarGrip.Width
/ 2)),
rect.Y + 1));
}
// This method handles the RenderGrip event.

protected override void OnRenderGrip(ToolStripGripRenderEventArgs
e)
{
DrawTitleBar(
e.Graphics,
}
// This method handles the RenderToolStripBorder event.

OnRenderToolStripBorder(ToolStripRenderEventArgs e)
{
DrawTitleBar(
e.Graphics,
}
// This method handles the RenderButtonBackground event.

{
Rectangle bounds = new Rectangle(Point.Empty, e.Item.Size);
Color gradientBegin = Color.FromArgb(203, 225, 252);

Color gradientEnd = Color.FromArgb(125, 165, 224);
ToolStripButton button = e.Item as ToolStripButton;
if (button.Pressed || button.Checked)
{
}
else if (button.Selected)
{
}
using (Brush b = new LinearGradientBrush(

bounds,
gradientBegin,
gradientEnd,
LinearGradientMode.Vertical))
{
g.FillRectangle(b, bounds);
}
e.Graphics.DrawRectangle(
bounds);
g.DrawLine(
bounds.X,
bounds.Y,
bounds.Width - 1,
bounds.Y);
g.DrawLine(
bounds.X,
bounds.Y,
bounds.X,
bounds.Height - 1);
ToolStrip toolStrip = button.Owner;

ToolStripButton nextItem = button.Owner.GetItemAt(
button.Bounds.X,
button.Bounds.Bottom + 1) as ToolStripButton;
if (nextItem == null)
{
g.DrawLine(
bounds.X,
bounds.Height - 1,
bounds.X + bounds.Width - 1,
bounds.Height - 1);
}
}
}
2. StackView No construtor do controle, crie uma nova instância da classe e atribua
StackRenderer essa instância à stackStrip propriedade do Renderer controle.
C#
public StackView()
{

}
Testar o controle StackView

O StackView controle deriva da UserControl classe. Portanto, você pode testar o
controle com o Contêiner de teste do UserControl. Para obter mais informações,
consulte Como testar o comportamento em tempo de execução de um UserControl.
1. Pressione F5 para criar o projeto e iniciar o Contêiner de Teste usercontrol.
2. Mova o ponteiro sobre os botões do controle StackView e, em seguida, clique em

um botão para ver a aparência de seu estado selecionado.
Próximas etapas
Neste passo a passo, você criou controle de cliente personalizado reutilizável com a
aparência profissional de um controle do Office XP. Você pode usar a ToolStrip família
de controles para muitas outras finalidades:
Criar um formulário com um menu padrão preenchido automaticamente. Para

mais informações, consulte Instruções passo a passo: fornecendo itens de menu
padrão para um formulário.
Crie um formulário MDI (interface de documento múltiplo) com controles de

ToolStrip encaixe. Para obter mais informações, consulte Como criar um formulário
MDI com mesclagem de menu e controles ToolStrip.
Confira também
MenuStrip
ToolStrip
StatusStrip
Controle ToolStrip
Passo a passo: Criar um formulário MDI
com mesclagem de menu e controles
ToolStrip
Artigo • 02/06/2023
O System.Windows.Forms namespace dá suporte a vários aplicativos MDI (interface de

documento) e o MenuStrip controle dá suporte à mesclagem de menu. Os formulários
MDI também ToolStrip podem controlar.
Este passo a passo demonstra como usar ToolStripPanel controles com um formulário
MDI. O formulário também dá suporte à mesclagem com menus filho. As seguintes
tarefas são ilustradas nesta explicação passo a passo:
Criando o menu principal do formulário. O nome real do menu variará.
Adicionando o ToolStripPanel controle à Caixa de Ferramentas.
Criando um formulário filho.
Organizando ToolStripPanel controles por ordem z.
Quando terminar, você terá um formulário MDI que dá suporte à mesclagem de menus
e controles móveis ToolStrip .
Para copiar o código neste tópico como uma única lista, consulte Como criar um
formulário MDI com mesclagem de menu e controles ToolStrip.
Pré-requisitos
Criar o projeto
1. No Visual Studio, crie um projeto de aplicativo do Windows chamado MdiForm
(File>New>Project>Visual C# ou Visual Basic>Classic Desktop>Windows Forms
Application).
2. No Designer de Formulários do Windows, selecione o formulário.

3. No janela Propriedades, defina o valor como IsMdiContainer true .
Criar o menu principal

O formulário MDI pai contém o menu principal. O menu principal tem um item de menu
chamado Janela. Com o item de menu Janela, você pode criar formulários filho. Os itens
de menu de formulários filho são mesclados no menu principal.
1. Na Caixa de Ferramentas, arraste um MenuStrip controle para o formulário.
2. Adicione um ToolStripMenuItem ao controle e nomeie-o MenuStripcomo Janela.
3. Selecione o controle MenuStrip.
4. No janela Propriedades, defina o valor da MdiWindowListItem propriedade como

ToolStripMenuItem1 .
5. Adicione um subitem no item de menu Janela e nomeie o subitem como Novo.
7. Clique duas vezes no Click evento.
O designer de Windows Forms gera um manipulador de eventos para o Click

evento.
8. Adicione o seguinte código ao manipulador de eventos.
C#
// This method creates a new ChildForm instance

// and attaches it to the MDI parent form.
{
ChildForm f = new ChildForm();
f.MdiParent = this;
f.Show();
}
Adicionar o controle ToolStripPanel à Caixa de

Ferramentas
Ao usar MenuStrip controles com um formulário MDI, você deve ter o ToolStripPanel
controle. Você deve adicionar o ToolStripPanel controle à Caixa de Ferramentas para
criar seu formulário MDI no Designer de Windows Forms.
1. Abra a caixa de ferramentas e, em seguida, clique na guia Todos os Windows

Forms para mostrar os controles dos Windows Forms disponíveis.
2. Clique com o botão direito do mouse para abrir o menu de atalho e selecione
Escolher Itens.
3. Na caixa de diálogo Escolher Itens da Caixa de Ferramentas, role para baixo a

coluna Nome até encontrar ToolStripPanel.
4. Marque a caixa de seleção por ToolStripPanele, em seguida, clique em OK.
O ToolStripPanel controle é exibido na Caixa de Ferramentas.
Criar um formulário filho

Neste procedimento, você definirá uma classe de formulário filho separada que tem seu
próprio MenuStrip controle. Os itens de menu para esse formulário são mesclados com
as do formulário pai.
1. Adicione um novo formulário chamado ChildForm ao projeto.
Para obter mais informações, consulte Como adicionar o Windows Forms a um

projeto.
2. Na Caixa de Ferramentas, arraste um MenuStrip controle para o formulário filho.
3. Clique no MenuStrip glifo de ações do designer do controle ( ) e selecione Editar

Itens.
4. Na caixa de diálogo Editor da Coleção de Itens , adicione um novo

ToolStripMenuItemnome ChildMenuItem ao menu filho.
Para obter mais informações, consulte Editor de Coleção dos Itens ToolStrip.
Testar o formulário
2. Clique no item de menu Janela para abrir o menu e, em seguida, clique em Novo.
Um novo formulário filho é criado na área de cliente do MDI do formulário. O

menu do formulário filho será mesclado com o menu principal.
3. Feche o formulário filho.
O menu do formulário filho será removido do menu principal.
4. Clique em Novo várias vezes.
Os formulários filho são listados automaticamente no item de menu Janela porque

a MenuStrip propriedade do MdiWindowListItem controle é atribuída.
Adicionar suporte ao ToolStrip

Neste procedimento, você adicionará quatro ToolStrip controles ao formulário pai do
MDI. Cada ToolStrip controle é adicionado dentro de um ToolStripPanel controle, que é
encaixado na borda do formulário.
1. Na Caixa de Ferramentas, arraste um ToolStripPanel controle para o formulário.
2. Com o ToolStripPanel controle selecionado, clique duas vezes no ToolStrip controle

na Caixa de Ferramentas.
Um ToolStrip controle é criado no ToolStripPanel controle.
3. Selecione o controle ToolStripPanel.
4. No janela Propriedades, altere o valor da propriedade do Dock controle para Left.
O ToolStripPanel controle encaixa no lado esquerdo do formulário, abaixo do

menu principal. A área do cliente MDI redimensiona para se ajustar ao
ToolStripPanel controle.
5. Repita as etapas de 1 a 4.
Encaixe o novo ToolStripPanel controle na parte superior do formulário.
O ToolStripPanel controle é encaixado sob o menu principal, mas à direita do

primeiro ToolStripPanel controle. Esta etapa ilustra a importância da ordem z no
posicionamento correto dos ToolStripPanel controles.
6. Repita as etapas 1 a 4 para mais ToolStripPanel dois controles.
Encaixe os novos ToolStripPanel controles à direita e à parte inferior do formulário.
Organizar controles ToolStripPanel por ordem Z

A posição de um controle encaixado ToolStripPanel no formulário MDI é determinada
pela posição do controle na ordem z. Você pode facilmente organizar a ordem z dos
controles na janela de estrutura de tópicos do documento.
1. No menu Exibir, clique em Outras janelas e clique em Estrutura de Tópicos do

Documento.
A disposição dos controles ToolStripPanel do procedimento anterior não é padrão.

Isso ocorre porque a ordem z não está correta. Use a janela de estrutura de
tópicos do documento para alterar a ordem z de controles.
2. Na janela de estrutura de tópicos do documento, selecione ToolStripPanel4.
3. Clique no botão de seta para baixo repetidamente, até ToolStripPanel4 estar na

parte inferior da lista.
O controle ToolStripPanel4 é encaixado na parte inferior do formulário, sob outros

controles.
4. Selecione ToolStripPanel2.
5. Clique no botão de seta para baixo uma vez para posicionar o controle em terceiro
lugar na lista.
O controle ToolStripPanel2 é encaixado à parte superior do formulário, abaixo do

menu principal e acima de outros controles.
6. Selecione vários controles da janela Estrutura de Tópicos do Documento e mova-

os em diferentes posições na ordem z. Observe o efeito da ordem z no
posicionamento de controles encaixados. Use CTRL-Z ou Desfazer no menu Editar
para desfazer as alterações.
Ponto de verificação – testar seu formulário

2. Clique na alça de um ToolStrip controle e arraste o controle para diferentes

posições no formulário.
Você pode arrastar um ToolStrip controle de um ToolStripPanel controle para

outro.
Próximas etapas
Neste passo a passo, você criou um formulário pai MDI com ToolStrip controles e
mesclagem de menu. Você pode usar a ToolStrip família de controles para muitas outras
finalidades:
Foi criado um formulário com um menu padrão preenchido automaticamente.

Para mais informações, consulte Instruções passo a passo: fornecendo itens de
menu padrão para um formulário.
Dê aos seus ToolStrip controles uma aparência profissional. Para obter mais
informações, consulte Como definir o renderizador ToolStrip para um aplicativo.
Confira também
MenuStrip
ToolStrip
StatusStrip
Como: Inserir um MenuStrip em um menu suspenso MDI
Controle ToolStrip
Artigo • 02/06/2023
ToolStrip controles apresentam rafting interno (compartilhamento de espaço horizontal

ou vertical dentro da área de ferramenta quando encaixado) usando o
ToolStripContainer.
compilar recursos ToolStripContainer em seus aplicativos.
Nesta seção
Visão geral do controle ToolStripContainer
Fornece tópicos que descrevem a finalidade e os principais conceitos do controle
Windows FormsToolStripContainer.
Como: Adicionar um ToolStripContainer a um formulário

Demonstra a adição de um ToolStripContainer aplicativo e a adição de um controle a
um painel específico do ToolStripContainer.
Como: Adicionar um controle a um ToolStripContentPanel

Demonstra a adição de um controle ao ToolStripContentPanel.
Referência
ToolStripContainer
Fornece documentação de referência para o ToolStripContainer controle.
Fornece documentação de ToolStripContainer referência para o ToolStripContentPanel
controle.
Consulte também a caixa de diálogo Tarefas ToolStripContainer.
ToolStripPanel
Fornece documentação de referência para o ToolStripPanel controle.
Confira também
ToolStripContainer
Artigo • 02/06/2023
A ToolStripContainer tem painéis nos lados esquerdo, direito, superior e inferior para
posicionamento e rafting ToolStripe MenuStripStatusStrip controles. Vários ToolStrip
controles são empilhados verticalmente se você colocá-los à esquerda ou à direita
ToolStripContainer. Eles são empilhados horizontalmente se você colocá-los na parte
superior ou inferior ToolStripContainer. Você pode usar a central ToolStripContentPanel
do para posicionar controles ToolStripContainer tradicionais no formulário.
Todos ou todos os ToolStripContainer controles podem ser selecionados diretamente no

momento do design e podem ser excluídos. Cada painel de um ToolStripContainer é
expansível e recolhível e redimensiona com os controles que ele contém.
Membros importantes do ToolStripContainer
Nome Descrição
BottomToolStripPanel Obtém o painel inferior do ToolStripContainer.
BottomToolStripPanelVisible Obtém ou define um valor que indica se o painel inferior do

ToolStripContainer está visível.
LeftToolStripPanel Obtém o painel esquerdo do ToolStripContainer.
LeftToolStripPanelVisible Obtém ou define um valor que indica se o painel esquerdo do

RightToolStripPanel Obtém o painel direito do ToolStripContainer.
RightToolStripPanelVisible Obtém ou define um valor que indica se o painel direito do

TopToolStripPanel Obtém o painel superior do ToolStripContainer.
TopToolStripPanelVisible Obtém ou define um valor que indica se o painel superior do

Confira também
ToolStripContainer
Como: Adicionar um ToolStripContainer
a um formulário
Artigo • 02/06/2023
Você pode adicionar programaticamente um ToolStripContainer formulário do Windows

e preenchê-lo com controles.
Exemplo
O exemplo de código a seguir demonstra como adicionar um ToolStripContainer e um
ToolStrip a um Windows Forms, como adicionar itens ao
ToolStripTopToolStripPanelToolStripToolStripContainer.
C#
using System;
using System.Data;
using System.Text;

{
private ToolStripContainer toolStripContainer1;
public Form1()
{
}
[STAThread]
static void Main()
{
}

{
toolStripContainer1 = new System.Windows.Forms.ToolStripContainer();
toolStrip1 = new System.Windows.Forms.ToolStrip();
// Add items to the ToolStrip.
toolStrip1.Items.Add("One");
toolStrip1.Items.Add("Two");
toolStrip1.Items.Add("Three");
// Add the ToolStrip to the top panel of the ToolStripContainer.
toolStripContainer1.TopToolStripPanel.Controls.Add(toolStrip1);
// Add the ToolStripContainer to the form.
Controls.Add(toolStripContainer1);
}
}
Referências aos assemblies System.Drawing, System.Text e System.Windows.Forms.
Confira também
ToolStripContainer
Controle ToolStrip
Como: Adicionar um controle a um
Artigo • 02/06/2023
Você pode adicionar programaticamente um ou mais controles a um

ToolStripContentPanel.
Exemplo
O exemplo de código a seguir demonstra como adicionar um RichTextBox a um
ToolStripContentPanel.
C#
using System;
using System.Data;
using System.Text;

{
private ToolStripContainer tsc;
private RichTextBox rtb;
public Form1()
{
}
[STAThread]
static void Main()
{
}

{
this.tsc = new System.Windows.Forms.ToolStripContainer();
this.rtb = new System.Windows.Forms.RichTextBox();
this.tsc.ContentPanel.Controls.Add(this.rtb);
this.Controls.Add(this.tsc);
}
}
Referências aos assemblies System, System.Data e System.Windows.Forms.
Confira também
ToolStripContainer
Controle ToolStrip
Controle ToolStripPanel
Artigo • 02/06/2023
ToolStripPanel O controle permite o compartilhamento de espaço horizontal ou

vertical dentro da área de ferramenta quando encaixado e organizando controles
ToolStrip quando você não precisa dos quatro painéis e do painel central de um
ToolStripContainer.
compilar recursos ToolStripPanel em seus aplicativos.
Nesta seção
Visão geral do controle ToolStripPanel
Windows FormsToolStripContainer.
Como: Unir ToolStripPanels

Demonstra a adição de ToolStrip controles a um ToolStripPanel .
Como: Usar ToolStripPanels para MDI

Demonstra a flexibilidade proporcionada pelos ToolStripPanel controles em um
aplicativo de Interface de Documento Múltiplo.
Referência
ToolStripPanel
Confira também
Visão geral do controle ToolStripPanel
Artigo • 02/06/2023
Um ToolStripPanel fornece uma única área para posicionamento e rafting ToolStripe

MenuStripStatusStrip controles. Vários ToolStrip controles são empilhados vertical ou
horizontalmente, dependendo do ToolStripPanelOrientation .
Membros importantes do ToolStripPanel
Nome Descrição
Orientation Obtém ou define um valor que indica a orientação horizontal ou vertical do

ToolStripPanel.
Renderer Obtém ou define um ToolStripRenderer usado para personalizar a aparência de

um ToolStripPanel.
RenderMode Obtém ou define os estilos de pintura a serem aplicados ao ToolStripPanel.
RowMargin Obtém ou define o espaçamento, em pixels, entre o ToolStripPanelRow

.ToolStripPanel
Rows Obtém a ToolStripPanelRow seguinte ToolStripPanel.
Join Adiciona um ToolStrip a um ToolStripPanel.
Confira também
ToolStripContainer
Exemplo de ToolStrip
Artigo • 02/06/2023
Você pode unir ToolStrip controles a um ToolStripPanel tempo de execução, que fornece
a flexibilidade de aplicativos MDI (interface de vários documentos).
Exemplo
O exemplo de código a seguir demonstra como unir ToolStrip controles a um
ToolStripPanel.
C#




tspTop.Join(tsTop);




Confira também
ToolStrip
ToolStripPanel
Artigo • 02/06/2023
O ToolStripPanel recurso fornece flexibilidade para aplicativos MDI (interface de vários

documentos) usando o Join método.
Exemplo
O exemplo de código a seguir demonstra como usar ToolStripPanel controles para MDI.
C#
// This code example demonstrates how to use ToolStripPanel

// controls with a multiple document interface (MDI).
{
public Form1()
{
// Make the Form an MDI parent.




tspTop.Join(tsTop);



// Create a MenuStrip control with a new window.

ToolStripMenuItem windowMenu = new ToolStripMenuItem("Window");
ToolStripMenuItem windowNewMenu = new ToolStripMenuItem("New", null,
new EventHandler(windowNewMenu_Click));
windowMenu.DropDownItems.Add(windowNewMenu);
((ToolStripDropDownMenu)(windowMenu.DropDown)).ShowImageMargin =
false;
((ToolStripDropDownMenu)(windowMenu.DropDown)).ShowCheckMargin =
true;
// Assign the ToolStripMenuItem that displays

// the list of child forms.
ms.MdiWindowListItem = windowMenu;
// Add the window ToolStripMenuItem to the MenuStrip.

ms.Items.Add(windowMenu);
// Dock the MenuStrip to the top of the form.

// The Form.MainMenuStrip property determines the merge target.

this.MainMenuStrip = ms;
// Add the ToolStripPanels to the form in reverse order.

this.Controls.Add(tspRight);
this.Controls.Add(tspLeft);
this.Controls.Add(tspBottom);
this.Controls.Add(tspTop);
// Add the MenuStrip last.

}

// the "New" ToolStripMenuItem is clicked.
// It creates a new Form and sets its MdiParent
// property to the main form.
void windowNewMenu_Click(object sender, EventArgs e)
{
Form f = new Form();
f.MdiParent = this;
f.Show();
}
}

Confira também
ToolStripPanel
Controle ToolStripProgressBar
Artigo • 02/06/2023
A ToolStripProgressBar combina ToolStrip recursos de renderização e rafting com sua

funcionalidade típica de acompanhamento de processo.
Nesta seção
Visão geral do controle ToolStripProgressBar
Windows FormsToolStripProgressBar.
Referência
ToolStripPanel
Fornece documentação de referência para o ToolStripProgressBar controle.
Confira também
Artigo • 02/06/2023
Combina ToolStripProgressBar a funcionalidade de rafting e renderização de todos os

ToolStrip controles com sua funcionalidade típica de acompanhamento de processo. A
ToolStripProgressBar geralmente é hospedado por StatusStripe com menos frequência
por um ToolStrip.
Embora ToolStripProgressBar substitua e adicione funcionalidade ao controle em

versões anteriores, ToolStripProgressBar é mantido para compatibilidade com versões
anteriores e uso futuro, se desejado.
Membros importantes ToolStripProgressBar
Nome Descrição
MarqueeAnimationSpeed Obtém ou define um valor que representa o atraso entre cada

atualização de exibição Marquee, em milissegundos.
Maximum Obtém ou define o limite superior do intervalo definido para esse

ToolStripProgressBar.
Minimum Obtém ou define o limite inferior do intervalo que está definido para
esse ToolStripProgressBar.
Style Obtém ou define o estilo usado ToolStripProgressBar para exibir o

progresso de uma operação.
Value Obtém ou define o valor atual da ToolStripProgressBar.
PerformStep Avança a posição atual da barra de progresso até o valor da

propriedade Step.
Confira também
Controle ToolStripStatusLabel
Artigo • 02/06/2023
O ToolStripStatusLabel fornece uma área de exibição em um StatusStrip texto, imagens

ou ambos.
Nesta seção
Visão geral do controle ToolStripStatusLabel
Windows FormsToolStripStatusLabel.
Referência
Fornece documentação de referência para o ToolStripStatusLabel controle.
StatusStrip
Fornece documentação de referência para o StatusStrip controle.
Fornece documentação de referência para o ToolStripProgressBar controle.
Confira também
Artigo • 02/06/2023
É ToolStripStatusLabel um rótulo para um StatusStrip. Como o Label ou ToolStripLabel,

fornece ToolStripStatusLabel uma área de exibição não clicável para texto, imagens ou
ambos. Ele ToolStripStatusLabel é hospedado por um StatusStrip.
Membros importantes do ToolStripStatusLabel
Nome Descrição
Spring Obtém ou define um valor que indica se o ToolStripStatusLabel espaço disponível é

preenchido automaticamente à StatusStrip medida que o formulário é
redimensionado
BorderSides Obtém ou define um valor que indica quais lados do ToolStripStatusLabel mostram
bordas.
BorderStyle Obtém ou define o estilo de borda do ToolStripStatusLabel.
Confira também
Componente ToolTip (Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms ToolTip exibe texto quando o usuário aponta para
controles. Uma dica de ferramenta pode ser associada a qualquer controle. Um exemplo
de uso desse controle: para economizar espaço em um formulário, você pode exibir um
pequeno ícone em um botão e usar uma Dica de Ferramenta para explicar a função do
botão.
Nesta seção
Visão geral do componente ToolTip
Apresenta os conceitos gerais do componente, que ToolTip permite que os usuários
vejam o texto quando apontam o mouse para um controle.
Como: Definir ToolTips para controles em um Windows Form no momento do design

Descreve como definir dicas de ferramenta no código ou no designer.
Como: Alterar o atraso do componente ToolTip do Windows Forms

Explica como definir valores que controlam quanto tempo uma dica de ferramenta leva
para aparecer e o tempo para o qual ela é mostrada.
Referência
Classe ToolTip
Ajuda de controle usando ToolTips

Discute dicas de ferramentas como uma maneira de fazer mensagens de Ajuda breves e
especializadas para controles individuais em Windows Forms.
(Windows Forms)
Artigo • 02/06/2023
O componente Windows Forms ToolTip exibe texto quando o usuário aponta para
controles. Uma dica de ferramenta pode ser associada a qualquer controle. Um exemplo
de uso desse componente: para economizar espaço em um formulário, você pode exibir
um pequeno ícone em um botão e usar uma dica de ferramenta para explicar a função
do botão.
Trabalhando com o componente ToolTip

Um ToolTip componente fornece uma ToolTip propriedade para vários controles em
um Formulário do Windows ou em outro contêiner. Por exemplo, se você colocar um
ToolTip componente em um formulário, poderá exibir "Digite seu nome aqui" para um
TextBox controle e "Clique aqui para salvar alterações" para um Button controle.
Os principais métodos do ToolTip componente são SetToolTip e GetToolTip. Você pode

usar o SetToolTip método para definir as Dicas de Ferramenta exibidas para controles.
Para obter mais informações, consulte Como definir ToolTips para controles em um
Windows Form no tempo de design. As propriedades de chave são Active, que devem
ser definidas true para que a Dica de Ferramenta apareça e AutomaticDelay, o que
define o período de tempo que a cadeia de caracteres tooltip é mostrada, quanto
tempo o usuário deve apontar para o controle para que a Dica de Ferramenta apareça e
quanto tempo leva para que as janelas da Dica de Ferramenta subsequente apareçam.
Para obter mais informações, consulte Como alterar o atraso do componente ToolTip
dos Windows Forms.
Confira também
ToolTip
Como: Definir ToolTips para controles em um Windows Form no momento do
design
Como definir dicas de ferramenta para
controles em um formulário Windows
em tempo de design
Artigo • 02/06/2023
Você pode definir uma cadeia ToolTip de caracteres no código ou no designer Windows
Forms no Visual Studio. Para obter mais informações sobre o componente ToolTip ,
consulte Visão geral do componente ToolTip.
Definir uma Dica de Ferramenta

programaticamente
1. Adicione o controle que exibirá a Dica de Ferramenta.
2. Use o SetToolTip método do ToolTip componente .
C#
// In this example, button1 is the control to display the ToolTip.

toolTip1.SetToolTip(button1, "Save changes");
Definir uma Dica de Ferramenta no designer

1. Em Visual Studio, adicione um ToolTip componente ao formulário.
2. Selecione o controle que exibirá a Dica de Ferramenta ou adicione-a ao formulário.
3. Na janela Propriedades , de definido o valor ToolTip em ToolTip1 como uma

cadeia de caracteres de texto apropriada.
Para remover uma Dica de Ferramenta

programaticamente
1. Use o SetToolTip método do ToolTip componente .
C#
// In this example, button1 is the control displaying the ToolTip.

toolTip1.SetToolTip(button1, null);
Remover uma Dica de Ferramenta no designer
1. Em Visual Studio, selecione o controle que está exibindo a Dica de Ferramenta.
2. Na janela Propriedades , exclua o texto na Dica de Ferramenta em ToolTip1.
Confira também
Componente ToolTip
Como: Alterar o atraso do componente
ToolTip do Windows Forms
Artigo • 02/06/2023
Há vários valores de atraso que você pode definir para um componente Windows
FormsToolTip. A unidade de medida para todas essas propriedades é milissegundos. A
InitialDelay propriedade determina quanto tempo o usuário deve apontar para o
controle associado para que a cadeia de caracteres ToolTip apareça. A ReshowDelay
propriedade define o número de milissegundos necessários para que cadeias de
caracteres de Dica de Ferramenta subsequentes apareçam à medida que o mouse passa
de um controle associado à Dica de Ferramenta para outro. A AutoPopDelay
propriedade determina o período de tempo que a cadeia de caracteres ToolTip é
mostrada. Você pode definir esses valores individualmente ou definindo o valor da
AutomaticDelay propriedade; as outras propriedades de atraso são definidas com base
no valor atribuído à AutomaticDelay propriedade. Por exemplo, quando AutomaticDelay
é definido como um valor N, InitialDelay é definido como N, ReshowDelay é definido
como o valor dividido AutomaticDelay por cinco (ou N/5) e AutoPopDelay é definido
como um valor cinco vezes o valor da AutomaticDelay propriedade (ou 5N).
Para definir o atraso

1. Defina as seguintes propriedades conforme mostrado neste exemplo.
C#
ToolTip1.InitialDelay = 500;
ToolTip1.ReshowDelay = 100;
ToolTip1.AutoPopDelay = 5000;
Confira também
Como: Definir ToolTips para controles em um Windows Form no momento do
design
Componente ToolTip
Controle TrackBar (Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms TrackBar (também às vezes chamado de controle

deslizante) é usado para navegar por uma grande quantidade de informações ou para
ajustar visualmente uma configuração numérica. O TrackBar controle tem duas partes:
o polegar, também conhecido como controle deslizante, e as marcas de escala. O
elevador é parte que pode ser ajustada. Sua posição corresponde à Value propriedade.
As marcas de escala são indicadores visuais espaçados em intervalos regulares. A barra
de faixa se move em incrementos que você especifica e pode ser alinhada horizontal ou
verticalmente. Um exemplo de uso de uma barra de faixa seria para definir a taxa de
piscar do cursor ou a velocidade do mouse.
Nesta seção
Visão geral do controle TrackBar
Apresenta os conceitos gerais do controle, que TrackBar permite que os usuários
naveguem por informações ajustando visualmente uma configuração numérica.
Referência
Classe TrackBar
Visão geral do controle TrackBar
(Windows Forms)
Artigo • 02/06/2023
O controle Windows Forms TrackBar (também às vezes chamado de controle deslizante)

é usado para navegar por uma grande quantidade de informações ou para ajustar
visualmente uma configuração numérica. O TrackBar controle tem duas partes: o
polegar, também conhecido como controle deslizante, e as marcas de escala. O
elevador é parte que pode ser ajustada. Sua posição corresponde à Value propriedade.
As marcas de escala são indicadores visuais espaçados em intervalos regulares. A
trackbar se move em incrementos especificados e pode ser alinhada horizontalmente ou
verticalmente. Por exemplo, é possível usar a trackbar para controlar a taxa de
intermitência do cursor ou a velocidade do mouse em um sistema.
As principais propriedades do TrackBar controle sãoValue, e
MinimumTickFrequencyMaximum. TickFrequency é o espaçamento dos tiques.
Minimum e Maximum são os menores e maiores valores que podem ser representados
na barra de faixas.
Duas outras propriedades importantes são SmallChange e LargeChange. O valor da

SmallChange propriedade é o número de posições que o polegar move em resposta a
ter a tecla LEFT ou SETA PARA A DIREITA pressionada. O valor da LargeChange
propriedade é o número de posições que o polegar move em resposta a ter a tecla
PAGE UP ou PAGE DOWN pressionada, ou em resposta a cliques de mouse na barra de
faixa em ambos os lados do polegar.
Confira também
TrackBar
Controle TrackBar
Controle TreeView (Windows Forms)
Artigo • 02/06/2023
O controle TreeView dos Windows Forms exibe uma hierarquia de nós, como a forma
como arquivos e pastas são exibidos no painel esquerdo do recurso Windows Explorer
em sistemas operacionais Windows.
Nesta seção
Visão geral do controle TreeView

Fornece instruções para adicionar e remover nós de um modo de exibição de árvore.

(Windows Forms)
Fornece instruções para derivar um item em uma exibição de lista ou um nó em um
modo de exibição de árvore para adicionar campos, métodos ou construtores de que
você precisa.
Como: Determinar qual nó TreeView foi clicado

Fornece instruções para determinar qual nó em um modo de exibição de árvore foi
clicado, para que o aplicativo possa responder apropriadamente.
Como: Iterar em todos os nós de um controle TreeView do Windows Forms

Fornece instruções para examinar todos os nós em um modo de exibição de árvore.
Como: Definir ícones para o controle TreeView do Windows Forms

Fornece instruções para exibir ícones para os nós de um modo de exibição de árvore.
Como: Anexar um menu ShortCut a um nó TreeView

Demonstra como adicionar um menu de atalho a um nó do modo de exibição de
árvore.
Veja também como adicionar e remover nós com o controle Windows Forms TreeView
usando o designer e como anexar um menu de atalho a um TreeNode usando o
designer.
Referência
Classe TreeView
(Windows Forms)
Artigo • 02/06/2023
Com o controle Windows FormsTreeView, você pode exibir uma hierarquia de nós para
os usuários, como a maneira como arquivos e pastas são exibidos no painel esquerdo
do recurso do Windows Explorer do sistema operacional Windows. Cada nó no modo
de exibição de árvore pode conter outros nós, chamados nós filho. Você pode exibir nós
pai ou nós que contêm nós filhos, como expandidos ou recolhidos. Você também pode
exibir uma exibição de árvore com caixas de seleção ao lado dos nós definindo a
propriedade do modo de exibição de CheckBoxes árvore como true . Em seguida, você
pode selecionar ou limpar nós programaticamente definindo a propriedade true do
Checked nó como ou false .
As principais propriedades do TreeView controle são Nodes e SelectedNode. A Nodes
propriedade contém a lista de nós de nível superior no modo de exibição de árvore. A
SelectedNode propriedade define o nó selecionado no momento. Você pode exibir
ícones ao lado de nós. O controle usa imagens do ImageList nome na propriedade do
modo de exibição de ImageList árvore. A ImageIndex propriedade define a imagem
padrão para nós no modo de exibição de árvore. Para obter mais informações sobre
como exibir imagens, veja Como definir ícones para o controle TreeView dos Windows
Forms. Se você estiver usando o Visual Studio 2005, terá acesso a uma grande biblioteca
de imagens padrão que você pode usar com o TreeView controle.
Confira também
TreeView
Controle TreeView
(Windows Forms)
Como: Adicionar e remover nós com o
controle TreeView do Windows Forms
Artigo • 02/06/2023
O controle Windows Forms TreeView armazena os nós de nível superior em sua Nodes
coleção. Cada TreeNode um também tem sua própria Nodes coleção para armazenar
seus nós filho. Ambas as propriedades de coleção são do tipo TreeNodeCollection, que
fornece membros de coleção padrão que permitem adicionar, remover e reorganizar os
nós em um único nível da hierarquia de nós.
Para adicionar nós programaticamente

1. Use o Add método da propriedade do modo de exibição de Nodes árvore.
C#
// Adds new node as a child node of the currently selected node.

TreeNode newNode = new TreeNode("Text for new node");
treeView1.SelectedNode.Nodes.Add(newNode);
Para remover nós programaticamente

1. Use o Remove método da propriedade do modo de exibição de Nodes árvore para
remover um único nó ou o Clear método para limpar todos os nós.
C#
// Removes currently selected node, or root if nothing

// is selected.
treeView1.Nodes.Remove(treeView1.SelectedNode);
// Clears all nodes.
TreeView1.Nodes.Clear();
Confira também
Controle TreeView
(Windows Forms)
Como: Adicionar e remover nós com o
componente TreeView do Windows
Artigo • 02/06/2023
Como o controle Windows Forms TreeView exibe nós de maneira hierárquica, ao

adicionar um nó, você deve prestar atenção ao nó pai.

formulário contendo um TreeView controle. Para obter informações sobre como
Para adicionar ou remover nós no designer

1. Selecione o controle TreeView.
2. Na janela Propriedades, clique nas Reticências ( ) ao lado da Nodes propriedade.
O Editor TreeNode é exibido.
3. Para adicionar nós, deve existir um nó raiz; se não existir, primeiro adicione uma
raiz clicando no botão Adicionar Raiz. Em seguida, adicione nós filho,
selecionando a raiz ou qualquer outro nó e clicando no botão Adicionar Filho.
4. Para excluir nós, selecione o nó a ser excluído e clique no botão Excluir.
Confira também
Controle TreeView
(Windows Forms)
Como: Anexar um menu ShortCut a um
nó TreeView
Artigo • 21/06/2023
O controle Windows Forms TreeView exibe uma hierarquia de nós, semelhante aos
arquivos e pastas exibidos no painel esquerdo do Windows Explorer. Ao definir a
ContextMenuStrip propriedade , você pode fornecer operações contextuais ao usuário
quando ele clicar com o botão direito do mouse no TreeView controle. Ao associar um
ContextMenuStrip componente a itens individuais TreeNode , você pode adicionar um
nível personalizado de funcionalidade de menu de atalho aos seus TreeView controles.
Para associar um menu de atalho a um TreeNode

programaticamente
1. Instancie um TreeView controle com as configurações de propriedade apropriadas,
crie uma raiz TreeNodee adicione subnós.
2. Crie uma instância de um ContextMenuStrip componente e adicione um

ToolStripMenuItem para cada operação que você deseja disponibilizar em tempo
de execução.
3. Defina a ContextMenuStrip propriedade do apropriado TreeNode para o menu de

atalho que você criar.
4. Quando essa propriedade for definida, o menu de atalho será exibido quando
você clicar no nó com o botão direito do mouse.
O exemplo de código a seguir cria um básico TreeView e ContextMenuStrip associado à

raiz do .TreeViewTreeNode Você precisará personalizar as opções de menu para aqueles
que se encaixam no TreeView que você está desenvolvendo. Além disso, você desejará
escrever código para manipular os Click eventos desses itens de menu.
C#
// Declare the TreeView and ContextMenuStrip

private TreeView menuTreeView;
private ContextMenuStrip docMenu;
public void InitializeMenuTreeView()

{
// Create the TreeView.
menuTreeView = new TreeView();
menuTreeView.Size = new Size(200, 200);
// Create the root node.
TreeNode docNode = new TreeNode("Documents");
// Add some additional nodes.

docNode.Nodes.Add("phoneList.doc");
docNode.Nodes.Add("resume.doc");
// Add the root nodes to the TreeView.

menuTreeView.Nodes.Add(docNode);
// Create the ContextMenuStrip.

docMenu = new ContextMenuStrip();
//Create some menu items.

ToolStripMenuItem openLabel = new ToolStripMenuItem();
openLabel.Text = "Open";
ToolStripMenuItem deleteLabel = new ToolStripMenuItem();
deleteLabel.Text = "Delete";
ToolStripMenuItem renameLabel = new ToolStripMenuItem();
renameLabel.Text = "Rename";
//Add the menu items to the menu.

docMenu.Items.AddRange(new ToolStripMenuItem[]{openLabel,
deleteLabel, renameLabel});
// Set the ContextMenuStrip property to the ContextMenuStrip.

docNode.ContextMenuStrip = docMenu;
// Add the TreeView to the form.

this.Controls.Add(menuTreeView);
}
Confira também
ContextMenuStrip
Controle TreeView
Como: Anexar um menu de atalho a um
TreeNode usando o designer
Artigo • 21/06/2023
O controle Windows Forms TreeView exibe uma hierarquia de nós, semelhante aos
arquivos e pastas exibidos no painel esquerdo do recurso do Windows Explorer em
sistemas operacionais Windows. Ao definir a ContextMenuStrip propriedade , você pode
fornecer operações contextuais ao usuário quando ele clicar com o botão direito do
mouse no TreeView controle. Ao associar um ContextMenuStrip componente a itens
individuais TreeNode , você pode adicionar um nível personalizado de funcionalidade de
menu de atalho aos seus TreeView controles.
Para associar um menu de atalho a um

TreeNode em tempo de design
1. Adicione um TreeView controle ao formulário e adicione nós ao TreeView
conforme necessário. Para obter mais informações, veja Como adicionar e remover
nós com o controle TreeView dos Windows Forms.
2. Adicione um ContextMenuStrip componente ao formulário e adicione itens de

menu ao menu de atalho que representam operações no nível do nó que você
deseja disponibilizar em tempo de execução. Para obter mais informações, veja
Como adicionar itens de menu a um ContextMenuStrip.
3. Reabra a caixa de diálogo TreeNodeEditor do TreeView controle, selecione o nó a

ser editado e defina sua ContextMenuStrip propriedade como o menu de atalho
que você adicionou.
4. Quando essa propriedade for definida, o menu de atalho será exibido quando
você clicar no nó com o botão direito do mouse.
Além disso, você desejará escrever código para manipular os Click eventos desses
itens de menu.
Confira também
Controle TreeView
Como: Adicionar informações
personalizadas a um controle TreeView
ou ListView (Windows Forms)
Artigo • 02/06/2023
Você pode criar um nó derivado em um controle Windows Forms TreeView ou um item

derivado em um ListView controle. A derivação permite adicionar todos os campos
necessários, assim como métodos e construtores personalizados para manipulá-los. Um
uso desse recurso é anexar um objeto do cliente a cada nó de árvore ou item de lista.
Os exemplos aqui são para um TreeView controle, mas a mesma abordagem pode ser
usada para um ListView controle.
Para derivar um nó de árvore

Crie uma nova classe de nó, derivada da TreeNode classe, que tem um campo
personalizado para registrar um caminho de arquivo.
C#
class myTreeNode : TreeNode

{
public string FilePath;
public myTreeNode(string fp)

{
FilePath = fp;
this.Text = fp.Substring(fp.LastIndexOf("\\"));
}
}
Para usar um nó de árvore derivado

1. É possível usar o novo nó de árvore derivado como um parâmetro para chamadas
de função.
No exemplo abaixo, o caminho definido para o local do arquivo de texto é a pasta

Meus Documentos. Isso é feito porque podemos presumir que a maioria dos
computadores rodando o sistema operacional Windows vão incluir este diretório.
Isso também permite que usuários com níveis mínimos de acesso ao sistema
executem com segurança o aplicativo.
C#
// You should replace the bold text file

// in the sample below with a text file of your own choosing.
treeView1.Nodes.Add(new myTreeNode(System.Environment.GetFolderPath
+ @"\TextFile.txt") );
2. Se você tiver passado o nó de árvore e ele for digitado como uma TreeNode
classe, será necessário converter para sua classe derivada. Se trata de uma
conversão explícita de um tipo de objeto para outro. Para obter mais informações
sobre conversão, consulte Conversões implícitas e explícitas (Visual Basic),
conversões de conversão e tipo (Visual C#) ou Operador cast: () (Visual C++).
C#
protected void treeView1_AfterSelect (object sender,

System.Windows.Forms.TreeViewEventArgs e)
{
myTreeNode myNode = (myTreeNode)e.Node;
MessageBox.Show("Node selected is " + myNode.FilePath);
}
Confira também
Controle TreeView
Controle ListView
Como determinar qual nó TreeView foi
clicado (Windows Forms)
Artigo • 21/06/2023
Ao trabalhar com o controle Windows FormsTreeView, uma tarefa comum é determinar

qual nó foi clicado e responder adequadamente.
Para determinar qual nó TreeView foi clicado

1. Use o EventArgs objeto para retornar uma referência ao objeto de nó clicado.
2. Determine qual nó foi clicado verificando a TreeViewEventArgs classe , que contém

dados relacionados ao evento.
C#
protected void treeView1_AfterSelect (object sender,

System.Windows.Forms.TreeViewEventArgs e)
{
// Determine by checking the Text property.
MessageBox.Show(e.Node.Text);
}
７ Observação
Como alternativa, você pode usar o MouseEventArgsMouseDown do evento

ou MouseUp para obter os X valores de coordenada e Y do Point em que o
clique ocorreu. Em seguida, use o TreeView método do GetNodeAt controle
para determinar qual nó foi clicado.
Confira também
Controle TreeView
Como: Iterar em todos os nós de um
controle TreeView do Windows Forms
Artigo • 02/06/2023
Às vezes, é útil examinar cada nó em um controle Windows Forms TreeView para

executar algum cálculo nos valores do nó. Essa operação pode ser feita usando um
método recursivo (procedimento recursivo no VB.NET) que itera em cada nó em cada
coleção da árvore.
Cada TreeNode objeto em um exibição de árvore tem propriedades que você pode usar
para navegar no exibição de árvore: FirstNode, LastNode, NextNode, PrevNodee Parent.
O valor da propriedade Parent é o nó pai do nó atual. Os nós filho do nó atual, se
houver algum, são listados em sua Nodes propriedade. O TreeView próprio controle tem
a propriedade TopNode , que é o nó raiz de toda a exibição de árvore.
Abordagem recursiva
A abordagem recursiva usa um método que processa um nó de árvore e, em seguida,
chama o mesmo método para cada nó filho. Isso se repete até que cada nó na árvore
seja processado. A desvantagem dessa abordagem é que, se a árvore for grande, você
poderá ter um erro de estouro de pilha e ficar sem memória.
O exemplo a seguir mostra como imprimir a TreeNode propriedade de cada Text objeto:
C#
private void PrintRecursive(TreeNode treeNode)

{
// Print the node.
System.Diagnostics.Debug.WriteLine(treeNode.Text);
MessageBox.Show(treeNode.Text);
// Visit each node recursively.

foreach (TreeNode tn in treeNode.Nodes)
{
PrintRecursive(tn);
}
}
// Call the procedure using the TreeView.

private void CallRecursive(TreeView treeView)
{
// Print each node recursively.
foreach (TreeNode n in treeView.Nodes)
{
//recursiveTotalNodes++;
PrintRecursive(n);
}
}
Abordagem não recursiva

O exemplo a seguir é uma abordagem iterativa alternativa para percorrer os nós da
árvore usando uma Queue<T> coleção. Essa abordagem não segue a relação pai-filho
de um nó apenas garante que cada nó seja impresso. Se você quiser processar cada nó
de árvore e seus filhos, primeiro, use a Stack<T> coleção
C#
private void PrintNonRecursive(TreeNode treeNode)

{
if (treeNode != null)
{
//Using a queue to store and process each node in the TreeView
Queue<TreeNode> staging = new Queue<TreeNode>();
staging.Enqueue(treeNode);
while (staging.Count > 0)

{
treeNode = staging.Dequeue();
// Print the node.

System.Diagnostics.Debug.WriteLine(treeNode.Text);
MessageBox.Show(treeNode.Text);
foreach (TreeNode node in treeNode.Nodes)

{
staging.Enqueue(node);
}
}
}
}
// Call the procedure using the TreeView.

private void CallNonRecursive(TreeView treeView)
{
// Print each node.
foreach (TreeNode n in treeView.Nodes)
{
PrintNonRecursive(n);
}
}
Confira também
Controle TreeView
Procedimentos recursivos
Como: Definir ícones para o controle
TreeView do Windows Forms
Artigo • 02/06/2023
O controle Windows Forms TreeView pode exibir ícones ao lado de cada nó. Os ícones
são posicionados imediatamente à esquerda do texto do nó. Para exibir esses ícones,
você deve associar o modo de exibição de árvore a um ImageList controle. Para obter
mais informações sobre listas de imagens, consulte Componente ImageList e Como
adicionar ou remover imagens com o componente ImageList dos Windows Forms.
７ Observação
Um bug no Microsoft .NET Framework versão 1.1 impede que imagens apareçam
em TreeView nós quando o aplicativo chamaApplication.EnableVisualStyles. Para
contornar esse bug, chame Application.DoEvents seu Main método imediatamente
após a chamada EnableVisualStyles. Esse bug é corrigido no .NET Framework 2.0.
Para exibir imagens em um modo de exibição de árvore

1. Defina a TreeView propriedade do ImageList controle para o controle existente
ImageList que você deseja usar.
Essas propriedades podem ser definidas no designer com a janela Propriedades ou

no código.
C#
treeView1.ImageList = imageList1;
2. Defina as propriedades e SelectedImageIndex os nósImageIndex. A ImageIndex

propriedade determina a imagem exibida para os estados normais e expandidos
do nó e a SelectedImageIndex propriedade determina a imagem exibida para o
estado selecionado do nó.
Essas propriedades podem ser definidas no código ou no Editor TreeNode. Para

abrir o Editor do TreeNode, clique no botão reticências ( ) ao lado da Nodes
propriedade no janela Propriedades.
C#
// (Assumes that imageList1 contains at least two images and
// the TreeView control contains a selected image.)
treeView1.SelectedNode.ImageIndex = 0;
treeView1.SelectedNode.SelectedImageIndex = 1;
Confira também
(Windows Forms)
Controle WebBrowser (Windows Forms)
Artigo • 02/06/2023
o controle de Windows Forms WebBrowser hospeda páginas da web e fornece recursos

de navegação na internet para seu aplicativo.
Nesta seção
Visão geral do controle WebBrowser
Segurança de WebBrowser
Discute problemas de segurança relacionados ao controle.
Como: Navegar até uma URL com o controle WebBrowser

Demonstra como usar o controle para navegar até uma URL específica.
Como: Imprimir com um controle WebBrowser

Demonstra como imprimir uma página da Web sem exibi-la.
Como: Adicionar recursos do navegador da Web a um Aplicativo do Windows Forms

Descreve como inicializar o controle para ser usado como um navegador da Web.
Como: Criar um visualizador de documento HTML em um Aplicativo do Windows Forms

Descreve como inicializar o controle a ser usado como um visualizador HTML.
Como: Implementar a comunicação bidirecional entre o código DHTML e o código do

aplicativo cliente
Descreve como configurar a comunicação bidirecional entre o código do aplicativo e
DHTML em uma página da Web hospedada pelo controle.
Usando o Document Object Model HTML gerenciado

Fornece tópicos que descrevem como manipular ou criar páginas HTML hospedadas
pelo WebBrowser controle.
Referência
Classe WebBrowser
WebBrowserDocumentCompletedEventArgs
WebBrowserDocumentCompletedEventHandler
Descreve esse delegado.
WebBrowserEncryptionLevel
Descreve esta enumeração e todos os seus valores.
WebBrowserNavigatedEventArgs
WebBrowserNavigatedEventHandler
WebBrowserNavigatingEventArgs
WebBrowserNavigatingEventHandler
WebBrowserProgressChangedEventArgs
WebBrowserProgressChangedEventHandler
WebBrowserReadyState
WebBrowserRefreshOption
Confira também
Artigo • 02/06/2023
O WebBrowser controle fornece um wrapper gerenciado para o controle WebBrowser

ActiveX. O wrapper gerenciado permite exibir páginas da Web em seus aplicativos
cliente dos Windows Forms. Você pode usar WebBrowser o controle para duplicar
Internet Explorer Navegação na Web funcionalidade em seu aplicativo ou desabilitar a
funcionalidade Internet Explorer padrão e usar o controle como um visualizador de
documentos HTML simples. Você também pode usar o controle para adicionar
elementos de interface do usuário baseados em DHTML ao formulário e ocultar o fato
de que eles estão hospedados no WebBrowser controle . Essa abordagem permite
combinar perfeitamente controles Web com controles dos Windows Forms em um
único aplicativo.
Propriedades, métodos e eventos usados com

frequência
O WebBrowser controle tem várias propriedades, métodos e eventos que você pode
usar para implementar controles encontrados Internet Explorer. Por exemplo, você pode
usar o método Navigate para implementar uma barra de endereços e os métodos
GoBack , GoForward , Stop e Refresh para implementar os botões de navegação em uma
barra de ferramentas. Você pode manipular o evento Navigated para atualizar a barra
de endereços com o valor da propriedade Url e a barra de título com o valor da
propriedade DocumentTitle .
Se você quiser gerar seu próprio conteúdo de página dentro de seu aplicativo, defina a
propriedade DocumentText . Se você estiver familiarizado com o DOM (Modelo de Objeto
do Documento) HTML, também poderá manipular o conteúdo da página da Web por
meio da propriedade Document . Com essa propriedade, você pode armazenar e
modificar documentos na memória, em vez de navegar entre arquivos.
A propriedade Document também permite que você chame os métodos implementados

no código de script da página da Web do seu código de aplicativo cliente. Para acessar
o código do aplicativo cliente do seu código de script, defina a propriedade
ObjectForScripting . O objeto especificado pode ser acessado pelo seu código de script
como o objeto window.external .
Nome Descrição
Nome Descrição
Propriedade Obtém um objeto que fornece acesso gerenciado para DOM (Modelo de
Document Objeto do Documento) HTML da página da Web atual.
Evento Ocorre quando uma página da Web conclui o carregamento.

DocumentCompleted
Propriedade Obtém ou define o conteúdo HTML da página da Web atual.

DocumentText
Propriedade Obtém o título da página da Web atual.

DocumentTitle
Método GoBack Navega para a página anterior no histórico.
Método GoForward Navega para a próxima página no histórico.
Método Navigate Navega para a URL especificada.
Evento Navigating Ocorre antes do início de navegação, permitindo que a ação seja
cancelada.
Propriedade Obtém ou define um objeto que o código de script da página da Web

ObjectForScripting pode usar para se comunicar com o aplicativo.
Método Print Imprime a página da Web atual.
Método Refresh Recarrega a página da Web atual.
Método Stop Interrompe a navegação atual e para elementos de página dinâmicos,

como sons e animação.
Propriedade Url Obtém ou define a URL da página da Web atual. Configurar essa
propriedade leva o controle para a nova URL.
Confira também
WebBrowser
WebBrowserDocumentCompletedEventArgs
WebBrowserDocumentCompletedEventHandler
WebBrowserEncryptionLevel
WebBrowserNavigatedEventArgs
WebBrowserNavigatedEventHandler
WebBrowserNavigatingEventArgs
WebBrowserNavigatingEventHandler
WebBrowserProgressChangedEventArgs
WebBrowserReadyState
WebBrowserRefreshOption
Como: Adicionar recursos do navegador da Web a um Aplicativo do Windows
Forms
Como: Criar um visualizador de documento HTML em um Aplicativo do Windows
Forms
Como: Implementar a comunicação bidirecional entre o código DHTML e o código
do aplicativo cliente
Artigo • 02/06/2023
O WebBrowser controle foi projetado para funcionar somente em confiança total. O

conteúdo HTML exibido no controle pode vir de servidores Web externos e pode conter
código não gerenciado na forma de scripts ou controles Web. Se você usar o
WebBrowser controle nessa situação, o controle não será menos seguro do que o
Internet Explorer, mas o controle gerenciado WebBrowser não impede a execução desse
código não gerenciado.
Para obter mais informações sobre problemas de segurança relacionados ao controle

ActiveX WebBrowser subjacente, consulte Controle WebBrowser.
Confira também
WebBrowser
Controle WebBrowser
Como: Navegar até uma URL com o
controle WebBrowser
Artigo • 21/06/2023
O exemplo de código a seguir demonstra como navegar pelo WebBrowser controle

para uma URL específica.
Para determinar quando o novo documento está totalmente carregado, manipule o

DocumentCompleted evento. Para obter uma demonstração desse evento, consulte
Como imprimir com um controle WebBrowser.
Exemplo
C#
this.webBrowser1.Navigate("https://www.microsoft.com");
Um controle WebBrowser chamado webBrowser1 .
Referências aos assemblies System e System.Windows.Forms .
Confira também
WebBrowser
WebBrowser.DocumentCompleted
WebBrowser.Navigating
WebBrowser.Navigated
Controle WebBrowser
Como: Imprimir com um controle
WebBrowser
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como usar o WebBrowser controle para

imprimir uma página da Web sem exibi-lo.
Exemplo
C#
private void PrintHelpPage()

{
// Create a WebBrowser instance.
WebBrowser webBrowserForPrinting = new WebBrowser();
// Add an event handler that prints the document after it loads.

webBrowserForPrinting.DocumentCompleted +=
new WebBrowserDocumentCompletedEventHandler(PrintDocument);
// Set the Url property to load the document.

webBrowserForPrinting.Url = new Uri(@"\\myshare\help.html");
}
private void PrintDocument(object sender,

WebBrowserDocumentCompletedEventArgs e)
{
// Print the document now that it is fully loaded.
((WebBrowser)sender).Print();
// Dispose the WebBrowser now that the task is complete.

((WebBrowser)sender).Dispose();
}
Confira também
WebBrowser
Print
Url
Como: Adicionar recursos do navegador da Web a um Aplicativo do Windows
Forms
Como: Criar um visualizador de documento HTML em um Aplicativo do Windows
Forms
Como adicionar recursos do navegador
da Web a um aplicativo Windows Forms
Artigo • 02/06/2023
Com o WebBrowser controle , você pode adicionar a funcionalidade do navegador da

Web ao seu aplicativo. O controle funciona como um navegador da Web por padrão.
Depois de carregar uma URL inicial Url definindo a propriedade , você pode navegar
clicando em hiperlinks ou usando atalhos de teclado para mover para trás e para frente
pelo histórico de navegação. Por padrão, você pode acessar a funcionalidade adicional
do navegador por meio do menu de atalho acessado quando se clica com o botão
direito do mouse. Você também pode abrir novos documentos soltando-os no controle.
O WebBrowser controle também tem várias propriedades, métodos e eventos que você
pode usar para implementar recursos de interface do usuário semelhantes aos
encontrados no Internet Explorer.
O exemplo de código a seguir implementa uma barra de endereços, botões de

navegador típicos, um menu Arquivo, uma barra de status e uma barra de título que
exibe o título da página atual.
Exemplo
C#
using System;
using System.Security.Permissions;

{
public Form1()
{
// Create the form layout. If you are using Visual Studio,
// you can replace this code with code generated by the designer.
InitializeForm();
// The following events are not visible in the designer, so

// you must associate them with their event-handlers in code.
webBrowser1.CanGoBackChanged +=
new EventHandler(webBrowser1_CanGoBackChanged);
webBrowser1.CanGoForwardChanged +=
new EventHandler(webBrowser1_CanGoForwardChanged);
webBrowser1.DocumentTitleChanged +=
new EventHandler(webBrowser1_DocumentTitleChanged);
webBrowser1.StatusTextChanged +=
new EventHandler(webBrowser1_StatusTextChanged);
// Load the user's home page.
webBrowser1.GoHome();
}
// Displays the Save dialog box.

private void saveAsToolStripMenuItem_Click(object sender, EventArgs e)
{
webBrowser1.ShowSaveAsDialog();
}
// Displays the Page Setup dialog box.

private void pageSetupToolStripMenuItem_Click(object sender, EventArgs
e)
{
webBrowser1.ShowPageSetupDialog();
}
// Displays the Print dialog box.

private void printToolStripMenuItem_Click(object sender, EventArgs e)
{
webBrowser1.ShowPrintDialog();
}
// Displays the Print Preview dialog box.

private void printPreviewToolStripMenuItem_Click(
{
webBrowser1.ShowPrintPreviewDialog();
}
// Displays the Properties dialog box.

private void propertiesToolStripMenuItem_Click(
{
webBrowser1.ShowPropertiesDialog();
}
// Selects all the text in the text box when the user clicks it.
private void toolStripTextBox1_Click(object sender, EventArgs e)
{
toolStripTextBox1.SelectAll();
}
// Navigates to the URL in the address box when

// the ENTER key is pressed while the ToolStripTextBox has focus.
private void toolStripTextBox1_KeyDown(object sender, KeyEventArgs e)
{
if (e.KeyCode == Keys.Enter)
{
Navigate(toolStripTextBox1.Text);
}
}
// Navigates to the URL in the address box when

// the Go button is clicked.
private void goButton_Click(object sender, EventArgs e)
{
Navigate(toolStripTextBox1.Text);
}
// Navigates to the given URL if it is valid.

private void Navigate(String address)
{
if (String.IsNullOrEmpty(address)) return;
if (address.Equals("about:blank")) return;
if (!address.StartsWith("http://") &&
!address.StartsWith("https://"))
{
address = "http://" + address;
}
try
{
webBrowser1.Navigate(new Uri(address));
}
catch (System.UriFormatException)
{
return;
}
}
// Updates the URL in TextBoxAddress upon navigation.

private void webBrowser1_Navigated(object sender,
WebBrowserNavigatedEventArgs e)
{
toolStripTextBox1.Text = webBrowser1.Url.ToString();
}
// Navigates webBrowser1 to the previous page in the history.

private void backButton_Click(object sender, EventArgs e)
{
webBrowser1.GoBack();
}
// Disables the Back button at the beginning of the navigation history.

private void webBrowser1_CanGoBackChanged(object sender, EventArgs e)
{
backButton.Enabled = webBrowser1.CanGoBack;
}
// Navigates webBrowser1 to the next page in history.

private void forwardButton_Click(object sender, EventArgs e)
{
webBrowser1.GoForward();
}
// Disables the Forward button at the end of navigation history.

private void webBrowser1_CanGoForwardChanged(object sender, EventArgs e)
{
forwardButton.Enabled = webBrowser1.CanGoForward;
}
// Halts the current navigation and any sounds or animations on

// the page.
private void stopButton_Click(object sender, EventArgs e)
{
webBrowser1.Stop();
}
// Reloads the current page.

private void refreshButton_Click(object sender, EventArgs e)
{
// Skip refresh if about:blank is loaded to avoid removing
// content specified by the DocumentText property.
if (!webBrowser1.Url.Equals("about:blank"))
{
webBrowser1.Refresh();
}
}
// Navigates webBrowser1 to the home page of the current user.

private void homeButton_Click(object sender, EventArgs e)
{
webBrowser1.GoHome();
}
// Navigates webBrowser1 to the search page of the current user.

private void searchButton_Click(object sender, EventArgs e)
{
webBrowser1.GoSearch();
}
// Prints the current document using the current print settings.

private void printButton_Click(object sender, EventArgs e)
{
webBrowser1.Print();
}
// Updates the status bar with the current browser status text.
private void webBrowser1_StatusTextChanged(object sender, EventArgs e)
{
toolStripStatusLabel1.Text = webBrowser1.StatusText;
}
// Updates the title bar with the current document title.

private void webBrowser1_DocumentTitleChanged(object sender, EventArgs
e)
{
this.Text = webBrowser1.DocumentTitle;
}
// Exits the application.

private void exitToolStripMenuItem_Click(object sender, EventArgs e)
{
Application.Exit();
}
// The remaining code in this file provides basic form initialization

and
// includes a Main method. If you use the Visual Studio designer to
create
// your form, you can use the designer generated code instead of this
code,
// but be sure to use the names shown in the variable declarations here,
// and be sure to attach the event handlers to the associated events.
private WebBrowser webBrowser1;
private MenuStrip menuStrip1;

private ToolStripMenuItem fileToolStripMenuItem,
saveAsToolStripMenuItem, printToolStripMenuItem,
printPreviewToolStripMenuItem, exitToolStripMenuItem,
pageSetupToolStripMenuItem, propertiesToolStripMenuItem;
private ToolStripSeparator toolStripSeparator1, toolStripSeparator2;
private ToolStrip toolStrip1, toolStrip2;

private ToolStripTextBox toolStripTextBox1;
private ToolStripButton goButton, backButton,
forwardButton, stopButton, refreshButton,
homeButton, searchButton, printButton;
private StatusStrip statusStrip1;

private ToolStripStatusLabel toolStripStatusLabel1;
private void InitializeForm()

{
webBrowser1 = new WebBrowser();
menuStrip1 = new MenuStrip();

fileToolStripMenuItem = new ToolStripMenuItem();
saveAsToolStripMenuItem = new ToolStripMenuItem();
toolStripSeparator1 = new ToolStripSeparator();
printToolStripMenuItem = new ToolStripMenuItem();
printPreviewToolStripMenuItem = new ToolStripMenuItem();
toolStripSeparator2 = new ToolStripSeparator();
exitToolStripMenuItem = new ToolStripMenuItem();
pageSetupToolStripMenuItem = new ToolStripMenuItem();
propertiesToolStripMenuItem = new ToolStripMenuItem();
toolStrip1 = new ToolStrip();

goButton = new ToolStripButton();
backButton = new ToolStripButton();
forwardButton = new ToolStripButton();
stopButton = new ToolStripButton();
refreshButton = new ToolStripButton();
homeButton = new ToolStripButton();
searchButton = new ToolStripButton();
printButton = new ToolStripButton();
toolStrip2 = new ToolStrip();

toolStripTextBox1 = new ToolStripTextBox();
statusStrip1 = new StatusStrip();

toolStripStatusLabel1 = new ToolStripStatusLabel();
menuStrip1.Items.Add(fileToolStripMenuItem);
fileToolStripMenuItem.DropDownItems.AddRange(
new ToolStripItem[] {
saveAsToolStripMenuItem, toolStripSeparator1,
pageSetupToolStripMenuItem, printToolStripMenuItem,
printPreviewToolStripMenuItem, toolStripSeparator2,
propertiesToolStripMenuItem, exitToolStripMenuItem
});
fileToolStripMenuItem.Text = "&File";
saveAsToolStripMenuItem.Text = "Save &As...";
pageSetupToolStripMenuItem.Text = "Page Set&up...";
printToolStripMenuItem.Text = "&Print...";
printPreviewToolStripMenuItem.Text = "Print Pre&view...";
propertiesToolStripMenuItem.Text = "Properties";
exitToolStripMenuItem.Text = "E&xit";
printToolStripMenuItem.ShortcutKeys = Keys.Control | Keys.P;
saveAsToolStripMenuItem.Click +=
new System.EventHandler(saveAsToolStripMenuItem_Click);
pageSetupToolStripMenuItem.Click +=
new System.EventHandler(pageSetupToolStripMenuItem_Click);
printToolStripMenuItem.Click +=
new System.EventHandler(printToolStripMenuItem_Click);
printPreviewToolStripMenuItem.Click +=
new System.EventHandler(printPreviewToolStripMenuItem_Click);
propertiesToolStripMenuItem.Click +=
new System.EventHandler(propertiesToolStripMenuItem_Click);
exitToolStripMenuItem.Click +=
new System.EventHandler(exitToolStripMenuItem_Click);
toolStrip1.Items.AddRange(new ToolStripItem[] {
goButton, backButton, forwardButton, stopButton,
refreshButton, homeButton, searchButton, printButton});
goButton.Text = "Go";
backButton.Text = "Back";
forwardButton.Text = "Forward";
stopButton.Text = "Stop";
refreshButton.Text = "Refresh";
homeButton.Text = "Home";
searchButton.Text = "Search";
printButton.Text = "Print";
backButton.Enabled = false;
forwardButton.Enabled = false;
goButton.Click += new System.EventHandler(goButton_Click);

backButton.Click += new System.EventHandler(backButton_Click);
forwardButton.Click += new System.EventHandler(forwardButton_Click);
stopButton.Click += new System.EventHandler(stopButton_Click);
refreshButton.Click += new System.EventHandler(refreshButton_Click);
homeButton.Click += new System.EventHandler(homeButton_Click);
searchButton.Click += new System.EventHandler(searchButton_Click);
printButton.Click += new System.EventHandler(printButton_Click);
toolStrip2.Items.Add(toolStripTextBox1);
toolStripTextBox1.Size = new System.Drawing.Size(250, 25);
toolStripTextBox1.KeyDown +=
new KeyEventHandler(toolStripTextBox1_KeyDown);
toolStripTextBox1.Click +=
new System.EventHandler(toolStripTextBox1_Click);
statusStrip1.Items.Add(toolStripStatusLabel1);
webBrowser1.Dock = DockStyle.Fill;
webBrowser1.Navigated +=
new WebBrowserNavigatedEventHandler(webBrowser1_Navigated);
Controls.AddRange(new Control[] {
webBrowser1, toolStrip2, toolStrip1,
menuStrip1, statusStrip1, menuStrip1 });
}
[STAThread]
static void Main()
{
}
}
Compilar o código
Referências aos System assemblies , System.Drawing e System.Windows.Forms .
Confira também
WebBrowser
Controle WebBrowser
Como: Criar um visualizador de
documento HTML em um Aplicativo do
Windows Forms
Artigo • 02/06/2023
Você pode usar o WebBrowser controle para exibir e imprimir documentos HTML sem
fornecer a funcionalidade completa de um navegador da Internet. Isso é útil quando
você quer aproveitar os recursos de formatação de HTML, mas não quer que os usuários
carreguem páginas da Web arbitrárias que podem conter controles de Web não
confiáveis ou código de script potencialmente mal-intencionado. Talvez você queira
restringir a funcionalidade do WebBrowser controle dessa maneira, por exemplo, para
usá-lo como um visualizador de email HTML ou para fornecer ajuda formatada em
HTML em seu aplicativo.
Para criar um visualizador de documentos HTML

1. Defina a AllowWebBrowserDrop propriedade para false impedir que o
WebBrowser controle abra arquivos descartados sobre ela.
C#
webBrowser1.AllowWebBrowserDrop = false;
2. Defina a Url propriedade como o local do arquivo inicial a ser exibido.
C#
webBrowser1.Url = new Uri("http://www.contoso.com/");
Um controle WebBrowser chamado webBrowser1 .
Confira também
WebBrowser
AllowWebBrowserDrop
Url
Como: Implementar a comunicação
bidirecional entre o código DHTML e o
código do aplicativo cliente
Artigo • 02/06/2023
Você pode usar o controle para adicionar o WebBrowser código de aplicativo Web
DHTML (HTML dinâmico) existente aos seus aplicativos cliente Windows Forms. Isso é
útil quando você tiver investido tempo de desenvolvimento significativo na criação de
controles com base em DHTML e quiser aproveitar os recursos de interface do usuário
avançada dos Windows Forms sem reescrever o código existente.
O WebBrowser controle permite implementar a comunicação bidirecional entre o

código do aplicativo cliente e o código de script da página da Web por meio das
propriedades e Document da página da ObjectForScripting Web. Além disso, você pode
configurar o controle para que seus WebBrowser controles Web se misturem
perfeitamente com outros controles no formulário do aplicativo, ocultando sua
implementação DHTML. Para mesclar perfeitamente os controles, formate a página
exibida para que a cor do plano de fundo e o estilo visual correspondam ao restante do
formulário e use o , IsWebBrowserContextMenuEnablede WebBrowserShortcutsEnabled
as AllowWebBrowserDroppropriedades para desabilitar os recursos padrão do
navegador.
Para inserir DHTML em seu aplicativo dos

Windows Forms
1. Defina a WebBrowser propriedade do AllowWebBrowserDrop controle para false
impedir que o WebBrowser controle abra arquivos descartados sobre ele.
C#
2. Defina a propriedade do IsWebBrowserContextMenuEnabled controle para false

impedir que o controle exiba seu WebBrowser menu de atalho quando o usuário
clicar com o botão direito do mouse nele.
C#
webBrowser1.IsWebBrowserContextMenuEnabled = false;
3. Defina a propriedade do WebBrowserShortcutsEnabled controle para false
impedir que o WebBrowser controle responda a teclas de atalho.
C#
webBrowser1.WebBrowserShortcutsEnabled = false;
4. Defina a ObjectForScripting propriedade no construtor do formulário ou substitua

o OnLoad método.
O código a seguir usa a classe de formulário em si para o objeto de script.
C#
webBrowser1.ObjectForScripting = new MyScriptObject(this);
5. Implemente seu objeto de script.
C#
public class MyScriptObject

{
private Form1 _form;
public MyScriptObject(Form1 form)

{
_form = form;
}
public void Test(string message)

{
MessageBox.Show(message, "client code");
}
}
6. Use o objeto window.external no código de script para acessar propriedades

públicas e métodos do objeto especificado.
O código HTML a seguir demonstra como chamar um método no objeto de script

com um clique de botão. Copie esse código para o elemento BODY de um
documento HTML que você carrega usando o método do Navigate controle ou
que você atribui à propriedade do DocumentText controle.
HTML
<button onclick="window.external.Test('called from script code')">
call client code from script code
</button>
7. Implemente funções em seu código de script que seu código do aplicativo usará.
O seguinte elemento SCRIPT HTML apresenta uma função de exemplo. Copie esse
código para o elemento HEAD de um documento HTML que você carrega usando
o método do Navigate controle ou que você atribui à propriedade do
DocumentText controle.
HTML
<script>
function test(message) {
alert(message);
}
</script>
8. Use a Document propriedade para acessar o código de script do código do

aplicativo cliente.
Por exemplo, adicione o código a seguir a um manipulador de eventos de botão

Click .
C#
webBrowser1.Document.InvokeScript("test",
new String[] { "called from client code" });
9. Quando terminar de depurar seu DHTML, defina a propriedade do

ScriptErrorsSuppressed controle para true impedir que o WebBrowser controle
exiba mensagens de erro para problemas de código de script.
C#
// Uncomment the following line when you are finished debugging.

//webBrowser1.ScriptErrorsSuppressed = true;
Exemplo
O exemplo de código completo a seguir fornece um aplicativo de demonstração que
você pode usar para entender esse recurso. O código HTML é carregado no
WebBrowser controle por meio da DocumentText propriedade em vez de ser carregado
de um arquivo HTML separado.
C#
using System;

{
private WebBrowser webBrowser1 = new WebBrowser();
[STAThread]
{
}
public Form1()
{
button1.Text = "call script code from client code";
button1.Dock = DockStyle.Top;
webBrowser1.Dock = DockStyle.Fill;
Controls.Add(webBrowser1);
Controls.Add(button1);
}

{
base.OnLoad(e);
webBrowser1.IsWebBrowserContextMenuEnabled = false;
webBrowser1.WebBrowserShortcutsEnabled = false;
webBrowser1.ObjectForScripting = new MyScriptObject(this);
// Uncomment the following line when you are finished debugging.
//webBrowser1.ScriptErrorsSuppressed = true;
webBrowser1.DocumentText =
"<html><head><script>" +
"function test(message) { alert(message); }" +
"</script></head><body><button " +
"onclick=\"window.external.Test('called from script code')\">" +
"call client code from script code</button>" +
"</body></html>";
}

{
webBrowser1.Document.InvokeScript("test",
new String[] { "called from client code" });
}
}
public class MyScriptObject

{
private Form1 _form;
public MyScriptObject(Form1 form)

{
_form = form;
}
public void Test(string message)

{
MessageBox.Show(message, "client code");
}
}
Este código requer:
Confira também
WebBrowser
WebBrowser.Document
WebBrowser.ObjectForScripting
Controle WebBrowser
Usando o Document Object Model
HTML gerenciado
Artigo • 02/06/2023
O DOM (modelo de objeto de documento HTML gerenciado) fornece um wrapper com

base no .NET Framework para as classes HTML expostas pelo Internet Explorer. Use
essas classes para manipular páginas HTML hospedadas no WebBrowser controle ou
para criar novas páginas desde o início.
Nesta seção
Como: Acessar o Modelo de Objeto do Documento HTML gerenciado
Descreve como obter uma instância válida de HtmlDocument um aplicativo Windows
Forms ou um UserControl hospedado no Internet Explorer.
Como: Acessar a fonte HTML no Modelo de Objeto do Documento HTML gerenciado

Descreve como obter o a fonte HTML original, sem modificações e como obter a fonte
"ativa" que reflete o estado atual do DOM.
Como: Alterar estilos em um elemento no Modelo de Objeto do Documento HTML

gerenciado
Descreve como manipular estilos que são usados para controlar a exibição visual de
elementos.
Acessando quadros no Document Object Model HTML gerenciado

Descreve quais são os quadros e conjuntos de quadros e como acessar o DOM de um
quadro.
Acessando membros não expostos no Document Object Model HTML gerenciado

Descreve como acessar membros do DOM subjacente que não tenham um equivalente
gerenciado.
Referência
HtmlDocument
HtmlElement
HtmlWindow
Controle WebBrowser
Como: Acessar o Modelo de Objeto do
Documento HTML gerenciado
Artigo • 21/06/2023
É possível acessar o Document Object Model (DOM) do HTML gerenciado a partir de

dois tipos de aplicativos:
Um aplicativo do Windows Forms (.exe) que hospedou o controle WebBrowser

gerenciado. Essas duas tecnologias se complementam entre si, com o controle
WebBrowser exibindo a página para o usuário e o DOM do HTML representando a
estrutura lógica do documento.
Um UserControl do Windows Forms hospedado dentro do Internet Explorer. É

possível acessar o DOM do HTML que representa a página na qual o UserControl
está hospedado para alterar a estrutura do documento ou abrir caixas de diálogo
restritas, entre muitas outras possibilidades.
Para acessar o DOM a partir de um aplicativo do

Windows Forms
1. Hospede um controle WebBrowser dentro do aplicativo do Windows Forms e
monitore pelo evento DocumentCompleted. Para obter detalhes sobre controles
de host e monitoramento de eventos, consulte Eventos.
2. Recupere o HtmlDocument da página atual acessando a propriedade Document

do controle WebBrowser.
Para acessar o DOM a partir de um UserControl

hospedado no Internet Explorer
1. Crie sua própria classe derivada personalizada da classe UserControl. Para mais
informações, consulte Como criar controles compostos.
2. Coloque o seguinte código dentro do manipulador de eventos Carregar do

UserControl:
C#
HtmlDocument doc = null;
private void UserControl1_Load(object sender, EventArgs e)

{
if (this.Site != null)
{
doc = (HtmlDocument)this.Site.GetService(typeof(HtmlDocument));
}
}
1. Ao usar o DOM através do controle WebBrowser, é sempre necessário esperar até
o evento DocumentCompleted ocorrer antes de tentar acessar a propriedade
Document do controle WebBrowser. O evento DocumentCompleted é elevado
após o documento inteiro ser carregado, se o DOM for usado antes disso, haverá o
risco de causar uma exceção de tempo de execução no aplicativo.

1. O aplicativo ou o UserControl exigirá confiança total para acessar o DOM do HTML
gerenciado. Se você estiver implantando um aplicativo Windows Forms usando o
ClickOnce, poderá solicitar confiança total usando Elevação de Permissão ou
Implantação de Aplicativo Confiável; consulte Protegendo aplicativos ClickOnce
para obter detalhes.
Confira também
Como: Acessar a fonte HTML no Modelo
de Objeto do Documento HTML
gerenciado
Artigo • 21/06/2023
As propriedades DocumentStream e DocumentText no controle WebBrowser retornam o

HTML do documento atual do modo que foi inicialmente exibido. No entanto, caso
modificar a página usando chamadas de método e propriedade como AppendChild e
InnerHtml, essas mudanças não aparecerão quando chamar DocumentStream e
DocumentText. Para obter a fonte HTML mais atualizada do DOM, é necessário chamar a
OuterHtml propriedade no elemento HTML.
O procedimento a seguir mostra como recuperar a fonte dinâmica e exibi-la em um

menu de atalho separado.
Recuperação de fonte dinâmica com a propriedade

OuterHtml
1. Crie um novo aplicativo Windows Forms. Comece com um único Forme chame-o
Form1 de .
2. Hospede o WebBrowser controle em seu aplicativo Windows Forms e nomeie-o

WebBrowser1 como . Para obter mais informações, consulte Como adicionar
recursos do navegador da Web a um Aplicativo dos Windows Forms.
3. Crie um segundo Form em seu aplicativo chamado CodeForm .
4. Adicione um RichTextBox controle a CodeForm e defina sua Dock propriedade

como Fill .
5. Crie uma propriedade pública em CodeForm chamada Code .
C#
public string Code

{
get
{
if (richTextBox1.Text != null)
{
return (richTextBox1.Text);
}
else
{
return ("");
}
}
set
{
richTextBox1.Text = value;
}
}
6. Adicione um Button controle chamado Button1 ao e Formmonitore o Click evento.

Para obter detalhes sobre como monitorar eventos, consulte Eventos.
7. Adicione o seguinte código ao manipulador de eventos do Click.
C#

{
HtmlElement elem;
if (webBrowser1.Document != null)
{
CodeForm cf = new CodeForm();
HtmlElementCollection elems =
webBrowser1.Document.GetElementsByTagName("HTML");
if (elems.Count == 1)
{
elem = elems[0];
cf.Code = elem.OuterHtml;
cf.Show();
}
}
}
Sempre teste o valor de Document antes de tentar recuperá-lo. Se a página atual não
tiver terminado de carregar, o Document ou um ou mais de seus objetos filhos podem
não ser inicializados.
Confira também
Como: Alterar estilos em um elemento
no Modelo de Objeto do Documento
HTML gerenciado
Artigo • 21/06/2023
Você pode usar estilos em HTML para controlar a aparência de um documento e seus
elementos. HtmlDocument e HtmlElement dão suporte Style a propriedades que têm
cadeias de caracteres de estilo do seguinte formato:
name1:value1;...;nameN:valueN;
Veja esse DIV com uma cadeia de caracteres de estilo que define a fonte como Arial e
todo o texto como negrito:
HTML
<DIV style="font-face:arial;font-weight:bold;">
Hello, world!
</DIV>
O problema com a manipulação de estilos usando a Style propriedade é que ela pode
ser complicada para adicionar e remover as configurações de estilo individuais da
cadeia de caracteres. Por exemplo, seria um procedimento complexo renderizar o texto
anterior em itálico sempre que o usuário posicionar o cursor sobre o DIV e remover o
itálico quando o cursor deixar o DIV . O tempo poderia se tornar um problema se você
precisasse manipular um grande número de estilos dessa maneira.
O procedimento a seguir contém o código que pode ser usado para manipular
facilmente os estilos em documentos e elementos HTML. O procedimento exige que
você saiba como executar tarefas básicas no Windows Forms, tal como criar um novo
projeto e adicionar um controle a um formulário.
Processar as alterações de estilo em um Aplicativo do

Windows Forms
1. Criar um novo projeto dos Windows Forms.
2. Crie um novo arquivo de classe terminando na extensão apropriada para sua

linguagem de programação.
3. Copie o código de classe StyleGenerator na seção Exemplo deste tópico para o
arquivo de classe e salve o código.
4. Salve o seguinte HTML em um arquivo chamado Test.htm.
HTML
<HTML>
<BODY>
<DIV style="font-face:arial;font-weight:bold;">
Hello, world!
</DIV><P>
<DIV>
Hello again, world!
</DIV><P>
</BODY>
</HTML>
5. Adicione um WebBrowser controle chamado webBrowser1 à forma main do

projeto.
6. Adicione o seguinte código ao arquivo de código do seu projeto.
） Importante
Verifique se o webBrowser1_DocumentCompleted manipulador de eventos está

configurado como um ouvinte para o DocumentCompleted evento. No Visual
Studio, clique duas vezes no WebBrowser controle; em um editor de texto,
configure o ouvinte programaticamente.
C#
StyleGenerator sg = null;
HtmlElement elem = null;
private void webBrowser1_DocumentCompleted(object sender,

WebBrowserDocumentCompletedEventArgs e)
{
sg = new StyleGenerator();
webBrowser1.Document.MouseOver += new
HtmlElementEventHandler(Document_MouseOver);
webBrowser1.Document.MouseLeave += new
HtmlElementEventHandler(Document_MouseLeave);
}
void Document_MouseOver(object sender, HtmlElementEventArgs e)
{
elem = webBrowser1.Document.GetElementFromPoint(e.MousePosition);
if (elem.TagName.Equals("DIV"))
{
sg.ParseStyleString(elem.Style);
sg.SetStyle("font-style", "italic");
elem.Style = sg.GetStyleString();
}
}
void Document_MouseLeave(object sender, HtmlElementEventArgs e)

{
if (elem != null)
{
sg.RemoveStyle("font-style");
elem.Style = sg.GetStyleString();
// Reset, since we may mouse over a new DIV element next time.
sg.Clear();
}
}
7. Execute o projeto. Passe o cursor pelo primeiro DIV para observar os efeitos do
código.
Exemplo
O exemplo de código a seguir mostra o código completo para a classe StyleGenerator ,
que analisa um valor de estilo existente, dá suporte à adição, alteração e remoção de
estilos e retorna um novo valor de estilo com as alterações solicitadas.
C#
using System;
using System.Text;
namespace ManagedDOMStyles
{
public class StyleGenerator
{
private Dictionary<string, string> styleDB;
public StyleGenerator()
{
styleDB = new Dictionary<string, string>();
}
public bool ContainsStyle(string name)

{
return(styleDB.ContainsKey(name));
}
public string SetStyle(string name, string value)

{
string oldValue = "";
if (!(name.Length > 0))

{
throw (new ArgumentException("Parameter name cannot be zero-
length."));
}
if (!(value.Length > 0))
{
throw (new ArgumentException("Parameter value cannot be
zero-length."));
}
if (styleDB.ContainsKey(name))
{
oldValue = styleDB[name];
}
styleDB[name] = value;
return (oldValue);
}
public string GetStyle(string name)

{
if (!(name.Length > 0))
{
throw (new ArgumentException("Parameter name cannot be zero-
length."));
}
{
return (styleDB[name]);
}
else
{
return ("");
}
}
public void RemoveStyle(string name)

{
{
styleDB.Remove(name);
}
}
public string GetStyleString()
{
if (styleDB.Count > 0)
{
StringBuilder styleString = new StringBuilder("");
foreach (string key in styleDB.Keys)
{
styleString.Append(String.Format("{0}:{1};",
(object)key, (object)styleDB[key]));
}
return (styleString.ToString());
}
else
{
return ("");
}
}
public void ParseStyleString(string styles)

{
if (styles.Length > 0)
{
string[] stylePairs = styles.Split(new char[] { ';' });
foreach(string stylePair in stylePairs)
{
if (stylePairs.Length > 0)
{
string[] styleNameValue = stylePair.Split(new char[]
{ ':' });
if (styleNameValue.Length == 2)
{
styleDB[styleNameValue[0]] = styleNameValue[1];
}
}
}
}
}
public void Clear()

{
styleDB.Clear();
}
}
}
Confira também
HtmlElement
Acessando quadros no Document
Object Model HTML gerenciado
Artigo • 02/06/2023
Alguns documentos HTML são compostos de quadros ou janelas que podem manter
seus próprios documentos HTML distintos. Usar quadros facilita a criação de páginas
HTML na qual uma ou mais partes da página permanecem estáticas, como uma barra de
navegação, enquanto outros quadros alterar seu conteúdo constantemente.
Criadores de HTML podem criar quadros de duas maneiras:
Usando as marcas FRAMESET e FRAME , que criam janelas fixas.
-ou-
Usando a marca IFRAME , que cria uma janela flutuante que pode ser reposicionada
em tempo de execução.
1. Como os quadros contêm documentos HTML, eles são representados no Modelo

de Objeto do Documento (DOM) como elementos de janela e de quadro.
2. Quando você acessa uma FRAME ou IFRAME marca usando a coleção Frames,
HtmlWindowvocê está recuperando o elemento de janela correspondente ao
quadro. Isso representa todas as propriedades dinâmicas do quadro, como sua
URL, documento e tamanho atual.
3. Quando você acessa uma FRAME ou IFRAME marca usando a WindowFrameElement

propriedade de HtmlWindow, a Children coleção ou métodos como
GetElementsByName ou GetElementById, você está recuperando o elemento de
quadro. Isso representa as propriedades estáticas do quadro, incluindo a URL
especificada no arquivo HTML original.
Quadros e Segurança
O acesso aos quadros é complicado pelo fato de que o HTML DOM gerenciado
implementa uma medida de segurança, conhecida como segurança de scripts entre
quadros. Se um documento contiver um FRAMESET com duas ou mais FRAME s em
domínios diferentes, esses FRAME s não poderão interagir entre si. Em outras palavras,
um FRAME que exibe conteúdo de seu site não pode acessar informações em um FRAME
site que hospeda um site de terceiros, como http://www.adatum.com/ . Essa segurança é
implementada no nível da HtmlWindow classe. Você pode obter informações gerais
sobre uma FRAME hospedagem de outro site, como sua URL, mas não poderá acessar
Document ou alterar o tamanho ou o local de sua hospedagem FRAME ou IFRAME .
Essa regra também se aplica às janelas que você abre usando os métodos e OpenNew
os Open métodos. Se a janela aberta estiver em um domínio diferente da página
hospedada no WebBrowser controle, você não poderá mover essa janela nem examinar
seu conteúdo. Essas restrições também serão impostas se você usar o WebBrowser
controle para exibir um site diferente do site usado para implantar seu aplicativo
baseado em Windows Forms. Se você usar a tecnologia de implantação do ClickOnce
para instalar seu aplicativo do site A e usar o WebBrowser site B para exibição, não
poderá acessar os dados do site B.
Confira também
<elemento frame>
Acessando membros não expostos no
Document Object Model HTML
gerenciado
Artigo • 02/06/2023
O DOM (Modelo de Objeto de Documento HTML) gerenciado contém uma classe

chamada HtmlElement que expõe as propriedades, os métodos e os eventos que todos
os elementos HTML têm em comum. Às vezes, no entanto, será necessário acessar
membros que a interface gerenciada não expõe diretamente. Este tópico examina duas
maneiras de acessar membros não expostos, incluindo funções JScript e VBScript
definidas dentro de uma página da Web.
Acessando Membros Não Expostos por meio

de Interfaces Gerenciadas
HtmlDocument e HtmlElement forneça quatro métodos que permitem o acesso a
membros não expostos. A tabela a seguir mostra os tipos e seus métodos
correspondentes.
Tipo do membro Método(s)
Propriedades (HtmlElement) GetAttribute
SetAttribute
Métodos InvokeMember
Eventos (HtmlDocument) AttachEventHandler
DetachEventHandler
Eventos (HtmlElement) AttachEventHandler
DetachEventHandler
Eventos (HtmlWindow) AttachEventHandler
DetachEventHandler
Ao usar esses métodos, presume-se que se tem um elemento do tipo subjacente

correto. Suponha que você queira escutar o evento Submit de um elemento FORM em
uma página HTML, para que seja possível executar o pré-processamento nos valores de
FORM antes de o usuário enviá-los para o servidor. Teoricamente, se tiver controle sobre
a HTML, você definirá que o FORM terá um atributo ID único.
HTML
<HTML>
<HEAD>
<TITLE>Form Page</TITLE>
</HEAD>
<BODY>
<FORM ID="form1">
... form fields defined here ...
</FORM>
</BODY>
</HTML>
Depois de carregar essa página no WebBrowser controle, você pode usar o

GetElementById método para recuperar o tempo de execução FORM usando form1 como
argumento.
C#
private void SubmitForm(String formName)

{
HtmlElementCollection elems = null;
HtmlElement elem = null;
if (webBrowser1.Document != null)
{
HtmlDocument doc = webBrowser1.Document;
elems = doc.All.GetElementsByName(formName);
if (elems != null && elems.Count > 0)
{
elem = elems[0];
if (elem.TagName.Equals("FORM"))
{
elem.InvokeMember("Submit");
}
}
}
}
Acessando as Interfaces Não Gerenciadas

Também é possível acessar membros não expostos no HTML DOM gerenciado usando
as interfaces Component Object Model (COM) não gerenciadas expostas por cada classe
DOM. Isso será recomendado se for necessário fazer várias chamadas em membros não
expostos ou se os membros não expostos retornarem outras interfaces não gerenciadas
não encapsuladas pelo o HTML DOM gerenciado.
A tabela a seguir mostra todas as interfaces não gerenciadas expostas por meio do
HTML DOM gerenciado. Clique em cada link para obter uma explicação de seu uso e
exemplos de código.
Tipo Interface não gerenciada
HtmlDocument DomDocument
HtmlElement DomElement
HtmlWindow DomWindow
HtmlHistory DomHistory
A maneira mais fácil de usar as interfaces COM é adicionar uma referência à biblioteca
de HTML DOM não gerenciada (MSHTML.dll) por meio do aplicativo, embora não haja
suporte para isso.
Acessando Funções de Script

Uma página HTML pode definir uma ou mais funções usando uma linguagem de script,
como JScript ou VBScript. Essas funções são colocadas dentro de uma página SCRIPT na
página e podem ser executadas sob demanda ou em resposta a um evento no DOM.
Você pode chamar todas as funções de script definidas em uma página HTML usando o
InvokeScript método. Se o método script retornar um elemento HTML, você poderá usar
uma conversão para converter esse resultado de retorno em um HtmlElement. Para
obter detalhes e código de exemplo, consulte InvokeScript.
Confira também
Controles dos Windows Forms usados
para listar opções
Artigo • 02/06/2023
Você pode adicionar uma variedade de controles a um Windows Form para fornecer aos
usuários uma lista de opções de escolha. Dependendo do quanto você deseja restringir
a entrada dos usuários, você pode adicionar um ListBox controle, um ComboBox
controle ou um CheckedListBox controle. Use os links a seguir para determinar qual
controle atende mais bem às suas necessidades.
Nesta seção
Recomenda um controle baseado em lista apropriado dependendo das necessidades e
restrições do seu Windows Form.
Como: Acessar itens específicos em um controle ComboBox, ListBox ou CheckedListBox

do Windows Forms
Fornece instruções para determinar programaticamente qual item em uma lista aparece
em uma determinada posição.
Como: Adicionar e remover itens de um controle ComboBox, ListBox ou CheckedListBox

do Windows Forms
Fornece instruções para adicionar ou remover itens de uma lista de itens do controle.

Fornece instruções para exibir e armazenar dados de formulário em formatos úteis.

Fornece instruções para associar um controle baseado em lista a uma fonte de dados.
Como: Classificar o conteúdo de um controle ComboBox, ListBox ou CheckedListBox do

Windows Forms
Explica como classificar dados de lista em sua fonte de dados.
Referência
CheckedListBox
ComboBox
ListBox



Quando usar um ComboBox dos
Windows Forms em vez de um ListBox
Artigo • 02/06/2023
O ComboBox e os ListBox controles têm comportamentos semelhantes e, em alguns

casos, podem ser intercambiáveis. No entanto, há vezes, em que um ou outro é mais
apropriado para uma tarefa.
Em geral, uma caixa de combinação é apropriada quando há uma lista das opções
sugeridas e uma caixa de listagem é apropriada quando você deseja limitar a entrada
para o que está na lista. Uma caixa de combinação contém um campo de caixa de texto,
portanto, as opções que não estão na lista podem ser digitadas. A exceção é quando a
DropDownStyle propriedade é definida como DropDownList . Nesse caso, o controle
selecionará um item se você digitar sua primeira letra.
Além disso, caixas de combinação economizam espaço em um formulário. Como a lista

completa não é exibida até que o usuário clique na seta para baixo, uma caixa de
combinação pode se encaixar facilmente em um pequeno espaço em que uma caixa de
listagem não caberia. Uma exceção é quando a DropDownStyle propriedade é definida
como Simple : a lista completa é exibida e a caixa de combinação ocupa mais espaço do
que uma caixa de listagem.
Confira também
ComboBox
ListBox
Como: Acessar itens específicos em um
controle ComboBox, ListBox ou
Artigo • 02/06/2023
Acessar itens específicos em uma caixa de combinação Windows Forms, caixa de

listagem ou caixa de listagem marcada é uma tarefa essencial. Ele permite que você
determine programaticamente o que está em uma lista, em qualquer posição
determinada.
Para acessar um item específico

1. Consulte a Items coleção usando o índice do item específico:
C#
private string GetItemText(int i)

{
// Return the text of the item using the index:
return (comboBox1.Items[i].ToString());
}
Confira também
ComboBox
ListBox
CheckedListBox
Como: Adicionar e remover itens de um
Artigo • 02/06/2023
Itens podem ser adicionados a uma caixa de combinação dos Windows Forms, caixa de
listagem ou caixa de listagem marcada de várias maneiras, porque esses controles
podem ser vinculados a uma variedade de fontes de dados. No entanto, este tópico
demonstra o método mais simples e não requer nenhuma vinculação de dados.
Normalmente, os itens exibidos são cadeias de caracteres; No entanto, qualquer objeto
pode ser usado. O texto que é exibido no controle é o valor retornado pelo método do
ToString objeto.
Para adicionar Itens

1. Adicione a cadeia de caracteres ou objeto à lista usando o método Add da classe
ObjectCollection . A coleção é referenciada usando a Items Propriedade:
C#
comboBox1.Items.Add("Tokyo");
ou –
2. Insira a cadeia de caracteres ou o objeto no ponto desejado na lista com o Insert

método:
C#
checkedListBox1.Items.Insert(0, "Copenhagen");
ou –
3. Atribua uma matriz inteira à Items coleção:
C#
System.Object[] ItemObject = new System.Object[10];

for (int i = 0; i <= 9; i++)
{
ItemObject[i] = "Item" + i;
}
listBox1.Items.AddRange(ItemObject);
Para remover um item

1. Chame o Remove método ou RemoveAt para excluir itens.
O Remove tem um argumento que especifica o item a ser removido. RemoveAt

Remove o item com o número de índice especificado.
C#
// To remove item with index 0:

comboBox1.Items.RemoveAt(0);
// To remove currently selected item:
comboBox1.Items.Remove(comboBox1.SelectedItem);
// To remove "Tokyo" item:
comboBox1.Items.Remove("Tokyo");
Para remover todos os itens

1. Chame o método Clear para remover todos os itens da coleção:
C#
listBox1.Items.Clear();
Confira também
ComboBox
ListBox
CheckedListBox
Como: Criar uma tabela de pesquisa
para um controle ComboBox, ListBox ou
Artigo • 02/06/2023
Às vezes, é útil exibir dados em um formato amigável em um formulário do Windows

Forms, porém, armazene os dados em um formato que seja mais significativo para o
programa. Por exemplo, um formulário de pedido de alimentos pode exibir os itens de
menu por nome em uma caixa de listagem. No entanto, a tabela de dados que registra
a ordem conteria os números de identificação exclusivos que representam os alimentos.
As tabelas a seguir mostram um exemplo de como armazenar e exibir dados de
formulários de pedidos de alimentos.
OrderDetailsTable
OrderID ItemID Quantidade
4085 12 1
4086 13 3
ItemTable
ID Nome
12 Batata
13 Frango
Nesse cenário, uma tabela, OrderDetailsTable, armazena as informações reais que serão
exibidas e salvas. Porém, para economizar espaço, isso é feito de maneira bastante
enigmática. A outra tabela, ItemTable, contém apenas informações relacionadas à
aparência sobre qual número de ID é equivalente a qual nome de alimento, e nada
sobre os pedidos de alimentos.
O ItemTable está conectado ao ComboBoxcontrole ou CheckedListBox ao controle

ListBoxpor meio de três propriedades. A propriedade DataSource contém o nome dessa
tabela. A propriedade DisplayMember contém a coluna de dados da tabela que você
deseja exibir no controle (o nome do alimento). A propriedade ValueMember contém a
coluna de dados dessa tabela com as informações armazenadas (o número de ID).
O OrderDetailsTable está conectado ao controle por sua coleção de associações,

acessada por meio da DataBindings propriedade. Ao adicionar um objeto de associação
à coleção, uma propriedade de controle será conectada a um membro de dados
específico (a coluna de números de ID) em uma fonte de dados (OrderDetailsTable).
Quando uma seleção é feita no controle, a entrada de formulário será salva nessa
tabela.
Criar uma tabela de pesquisa

1. Adicione um ComboBox, ListBoxou CheckedListBox controle ao formulário.
2. Conecte-se à fonte de dados.
3. Estabeleça uma relação de dados entre as duas tabelas. Consulte Introdução a

Objetos DataRelation.
4. Defina as propriedades a seguir. Elas podem ser definidos no código ou no

designer.
Propriedade Configuração
DataSource A tabela que contém informações sobre qual número de ID é equivalente

a qual item. No cenário anterior, isso é ItemTable .
DisplayMember A coluna da tabela de fonte de dados a ser exibida no controle. No

cenário anterior, isso é "Name" (para definir no código, use aspas).
ValueMember A coluna da tabela de fonte de dados que contém as informações

armazenadas. No cenário anterior, isso é "ID" (para definir no código,
use aspas).
5. Em um procedimento, chame o Add método da ControlBindingsCollection classe

para associar a propriedade do SelectedValue controle à tabela que registra a
entrada do formulário. Você também pode fazer isso no Designer, em vez de no
código, acessando a propriedade do DataBindings controle na janela Propriedades
. No cenário anterior, isso é OrderDetailsTable e a coluna é "ItemID" .
C#
listBox1.DataBindings.Add("SelectedValue", OrderDetailsTable,
"ItemID");
Confira também
Associação de dados e o Windows Forms
Como: Associar um controle ComboBox
ou ListBox do Windows Forms aos
dados
Artigo • 02/06/2023
Você pode vincular o ComboBox e ListBox aos dados para executar tarefas como
navegação de dados em um banco de dados, inserção de novos dados ou edição de
dados existentes.
Para associar controles ComboBox ou ListBox

1. De definir a DataSource propriedade como um objeto de fonte de dados. As
fontes de BindingSource dados possíveis IList incluem um limite a dados, uma
tabela de dados, uma exibição de dados, um conjunto de dados, um gerenciador
de exibição de dados, uma matriz ou qualquer classe que implemente a interface.
Para mais informações, consulte Fontes de Dados com Suporte nos Windows
Forms.
2. Se você estiver se vinculando a uma tabela, de DisplayMember definir a

propriedade como o nome de uma coluna na fonte de dados.
- ou -
Se você estiver se vinculando a IListum , de definir o membro de exibição como

uma propriedade pública do tipo na lista.
C#
private void BindComboBox()

{
comboBox1.DataSource = dataSet1.Tables["Suppliers"];
comboBox1.DisplayMember = "ProductName";
}
７ Observação
Se você estiver vinculado a uma fonte de dados que não implementa a

ArrayListinterface , como um , os dados do controle vinculado não serão
atualizados quando a IBindingList fonte de dados for atualizada. Por exemplo,
se você tiver uma caixa de combinação vinculada a ArrayListArrayListum e os
dados são adicionados ao , esses novos itens não aparecerão na caixa de
combinação. No entanto, você pode forçar
SuspendBindingResumeBindingBindingContext a atualização da caixa de
combinação chamando os métodos e na instância da classe à qual o controle
está vinculado.
Confira também
ComboBox
ListBox
Associação de dados e o Windows Forms
Como: Classificar o conteúdo de um
Artigo • 02/06/2023
Windows Forms controles não classificam quando estão associados a dados. Para exibir
dados classificados, use uma fonte de dados que dê suporte à classificação e, em
seguida, classifique-os na fonte de dados. As fontes de dados que dão suporte à
classificação são exibições de dados, gerenciadores de exibição de dados e matrizes
classificadas.
Se o controle não estiver associado a dados, você poderá classificá-lo.
Para classificar a lista

1. Defina a propriedade Sorted como true .
Essa configuração reposiciona todos os itens de lista existentes em ordem

classificada.
Confira também
ComboBox
ListBox
CheckedListBox
Desenvolvendo controles dos Windows
Forms personalizados com o .NET
Framework
Artigo • 02/06/2023
Os controles do Windows Forms são componentes reutilizáveis que encapsulam a

funcionalidade de interface do usuário e são usados em aplicativos Windows do lado do
cliente. O Windows Forms não só fornece vários controles prontos para usar como
também proporciona a infraestrutura para desenvolver seus próprios controles. É
possível combinar os controles existentes, ampliar os controles existentes e fazer seus
controles personalizados. Esta seção fornece informações básicas e exemplos para
ajudar a desenvolver controles do Windows Forms.
Nesta seção
Visão geral do uso de controles nos Windows Forms
Destaca os elementos essenciais do uso de controles em aplicativos do Windows Forms.
Variedades de controles personalizados

Descreve os diferentes tipos de controles personalizados que você pode definir com o
System.Windows.Forms namespace .
Noções básicas sobre o desenvolvimento de controle dos Windows Forms

Fala sobre os primeiros passos no desenvolvimento de um controle do Windows Forms.
Propriedades em controles dos Windows Forms

Mostra como adicionar propriedades aos controles do Windows Forms.
Eventos em controles dos Windows Forms

Descreve como manipular e definir eventos nos controles do Windows Forms.
Atributos em controles dos Windows Forms

Descreve os atributos que você pode aplicar a propriedades ou outros membros de
seus componentes e controles personalizados.
Pintura e renderização de controle personalizada

Mostra como personalizar a aparência de seus controles.
Layout em controles dos Windows Forms

Mostra como criar layouts para seus controles e formulários.
Multithread em controles dos Windows Forms
Mostra como implementar controles multithreaded.
Referência
System.Windows.Forms.Control
System.Windows.Forms.UserControl
Atributos em tempo de design para componentes
Lista atributos de metadados para aplicar a componentes e controles para que eles
sejam exibidos corretamente em tempo de design em designers visuais.
Estendendo o suporte para tempo de design

Descreve como implementar classes como editores e designers que fornecem suporte
ao tempo de design.
Como licenciar componentes e controles

Descreve como implementar licenciamento em seus controles e componentes.
Consulte também Desenvolvendo controles do Windows Forms em tempo de design.

Visão geral do uso de controles nos
Windows Forms
Artigo • 02/06/2023
Este tópico descreve os elementos essenciais de um aplicativo dos Windows Forms e

fornece um exemplo simples que usa controles e manipula eventos em um aplicativo
dos Windows Forms.
Aplicativos simples dos Windows Forms

No mínimo, um aplicativo dos Windows Forms consiste nos seguintes elementos:
Uma ou mais classes que derivam de System.Windows.Forms.Form.
Um Main método que invoca o static método ( shared no Visual Basic) Run e
passa uma Form instância para ele. O Run método processa mensagens do sistema
operacional para o aplicativo.
O exemplo de código a seguir mostra os elementos essenciais de um aplicativo dos

Windows Forms.
C#
using System;
public class MyForm : Form {
public MyForm() {
this.Text = "Hello World";
}
[STAThread]
public static void Main(string[] args) {
MyForm aform = new MyForm();
// The Application.Run method processes messages from the operating system
// to your application. If you comment out the next line of code,
// your application will compile and execute, but because it is not in the
// message loop, it will exit after an instance of the form is created.
Application.Run(aform);
}
}
Uso de controles em um aplicativo dos
Windows Forms
O exemplo de código a seguir mostra um aplicativo simples que ilustra como os
aplicativos dos Windows Forms usam controles e manipulam eventos. O exemplo
consiste em três botões em um formulário; cada botão altera a cor da tela de fundo
quando clicado.
C#
using System;
using System.Resources;
public class MyForm : Form {

private Button red;
private Button blue;
private Button green;
public MyForm() : base() {

}
protected override void Dispose(bool disposing) {

}
// InitializeComponent is a helper method for the constructor.

// It is included for consistency with code that is
// auto-generated by the Windows Forms designer in Visual Studio.
private void InitializeComponent() {
// A delegate for the click event of a button. The argument to

// the constructor contains a reference to the method that performs the
// event handling logic.
EventHandler handler = new EventHandler(button_Click);
// Creates three buttons, sets their properties, and attaches

// an event handler to each button.
red = new Button();

red.Text = "Red";
red.Location = new Point(100, 50);
red.Size = new Size(50, 50);
red.Click +=handler;
Controls.Add(red);
blue = new Button();

blue.Text = "Blue";
blue.Location = new Point(100, 100);
blue.Size = new Size(50, 50);
blue.Click += handler;
Controls.Add(blue);
green = new Button();

green.Text = "Green";
green.Location = new Point(100, 150);
green.Size = new Size(50, 50);
green.Click += handler;
Controls.Add(green);
}
// Event handler.
private void button_Click(object sender, EventArgs e) {
if (sender == red) this.BackColor = Color.Red ;
else if (sender == blue) this.BackColor = Color.Blue;
else this.BackColor = Color.Green;
}
// The STAThreadAttribute informs the common language runtime that
// Windows Forms uses the single-threaded apartment model.
[STAThread]
Application.Run(new MyForm());
}
Confira também
Framework
Artigo • 02/06/2023
Com o .NET Framework, você pode desenvolver e implementar novos controles. Você
pode estender a funcionalidade do controle de usuário familiar, além dos controles
existentes, por herança. Você também pode escrever controles personalizados que
executam suas próprias pinturas.
Decidir qual tipo de controle criar pode ser confuso. Este tópico destaca as diferenças
entre os vários tipos de controles dos quais você pode herdar e fornece informações
sobre como escolher um tipo específico de controle para seu projeto.
７ Observação
Para obter informações sobre a criação de um controle para usar no Web Forms,
consulte Desenvolvendo controles de servidores ASP.NET personalizados.
Classe de controle base

A Control classe é a classe base para controles Windows Forms. Ela fornece a
infraestrutura necessária para exibição visual em aplicativos Windows Forms.
A Control classe executa as seguintes tarefas para fornecer exibição visual em aplicativos
Windows Forms:
Expõe um identificador de janela.
Gerencia o roteamento de mensagens.
Fornece eventos de teclado e mouse, além de muitos outros eventos da interface

do usuário.
Fornece recursos de layout avançados.
Contém muitas propriedades específicas para exibição visual, como ForeColor,

BackColore WidthHeight.
Fornece a segurança e o suporte a threading necessários para um controle dos

Windows Forms atuar como um controle do Microsoft® ActiveX®.
Como grande parte da infraestrutura é fornecida pela classe base, é relativamente fácil
desenvolver seus próprios controles dos Windows Forms.
Tipos de controles
O Windows Forms dá suporte a três tipos de controles definidos pelo usuário:
composição, estendido e personalizado. As seções a seguir descrevem cada tipo de
controle e fornecem recomendações para escolher o tipo para usar em seus projetos.
Controles de composição
Um controle de composição é uma coleção de controles dos Windows Forms
encapsulados em um contêiner comum. Esse tipo de controle é, às vezes, chamado de
controle de usuário. Os controles contidos são chamados controles constituintes.
Um controle de composição contém todas as funcionalidades inerentes associadas a

cada um dos controles dos Windows Forms contidos e permite que você exponha
seletivamente e associe suas propriedades. Um controle de composição também é ideal
para a funcionalidade de manipulação do teclado padrão sem nenhum esforço adicional
de desenvolvimento de sua parte.
Por exemplo, um controle de composição poderia ser criado para exibir dados de
endereço de cliente de um banco de dados. Esse controle pode incluir um DataGridView
controle para exibir os campos de banco de dados, uma BindingSource associação para
lidar com uma fonte de dados e um BindingNavigator controle para se mover pelos
registros. Você pode expor seletivamente propriedades de vinculação de dados, além de
poder empacotar e reutilizar todo o controle do aplicativo para o aplicativo. Para obter
um exemplo desse tipo de controle de composição, consulte Como aplicar atributos em
controles dos Windows Forms.
Para criar um controle composto, deriva da UserControl classe. A UserControl classe

base fornece roteamento de teclado para controles filho e permite que controles filho
funcionem como um grupo. Para obter mais informações, consulte Desenvolvendo um
controle dos Windows Forms de composição.
Recomendação
Herda da UserControl classe se:
Você deseja combinar a funcionalidade de vários controles dos Windows Forms

em uma única unidade reutilizável.
Controles estendidos
Você pode derivar um controle herdado de qualquer controle Windows Forms existente.
Com essa abordagem, você pode reter todas as funcionalidades inerentes de um
controle Windows Forms e estender essa funcionalidade adicionando propriedades
personalizadas, métodos ou outros recursos. Com essa opção, você pode substituir a
lógica de pintura do controle base e estender a interface do usuário alterando sua
aparência.
Por exemplo, você pode criar um controle derivado do Button controle que rastreia
quantas vezes um usuário clicou nele.
Em alguns controles, você também pode adicionar uma aparência personalizada à

interface gráfica do usuário do controle substituindo o OnPaint método da classe base.
Para um botão estendido que rastreia cliques, você pode substituir o OnPaint método
para chamar a implementação base e OnPaint, em seguida, desenhar a contagem de
cliques em um canto da Button área do cliente do controle.
Recomendação
Herde de um controle dos Windows Forms se:
A maioria da funcionalidade que você precisa já é idêntica a um controle Windows

Forms existente.
Você não precisa de uma interface gráfica do usuário personalizada ou deseja criar
uma nova interface gráfica do usuário para um controle existente.
Controles personalizados
Outra maneira de criar um controle é criar um substancialmente desde o início
herdando de Control. A Control classe fornece todas as funcionalidades básicas exigidas
pelos controles, incluindo eventos de manipulação de mouse e teclado, mas nenhuma
funcionalidade específica de controle ou interface gráfica.
Criar um controle herdando da Control classe requer muito mais pensamento e esforço
do que herdar ou UserControl um controle Windows Forms existente. Como uma
grande quantidade de implementação é deixada para você, o controle pode ter maior
flexibilidade do que um controle de composição ou estendido e você pode personalizar
o controle para atender às suas necessidades.
Para implementar um controle personalizado, você deve escrever código para o OnPaint
evento do controle, bem como qualquer código específico do recurso necessário. Você
também pode substituir o WndProc método e manipular mensagens do Windows
diretamente. Essa é a maneira mais eficiente para criar um controle, mas, para usar essa
técnica com eficiência, você precisa estar familiarizado com a API do Win32® da
Microsoft.
Um exemplo de um controle personalizado é um controle de relógio que duplica a

aparência e o comportamento de um relógio analógico. A pintura personalizada é
invocada para fazer com que as mãos do relógio se movam em resposta a Tick eventos
de um componente interno Timer . Para obter mais informações, consulte Como
desenvolver um controle simples dos Windows Forms.
Recomendação
Herda da Control classe se:
Você deseja fornecer uma representação gráfica personalizada do seu controle.
Você precisa implementar a funcionalidade personalizada que não está disponível

por controles padrão.
Controles ActiveX
Embora a infraestrutura dos Windows Forms tenha sido otimizada para hospedar
controles dos Windows Forms, você ainda poderá usar controles ActiveX. Há suporte
para esta tarefa no Visual Studio. Para mais informações, consulte Como adicionar
controles ActiveX ao Windows Forms.
Controles sem janelas

As tecnologias ActiveX e Microsoft Visual Basic® 6.0 dão suporte a controles sem
janelas. Os controles sem janelas não têm suporte nos Windows Forms.
Experiência de design personalizado

Se você precisar implementar uma experiência de tempo de design personalizada, você
poderá criar seu próprio designer. Para controles compostos, derive sua classe de
designer personalizada das classes ou das ParentControlDesignerDocumentDesigner
classes. Para controles estendidos e personalizados, derive sua classe de designer
personalizada da ControlDesigner classe.
Use o DesignerAttribute para associar seu controle ao designer. Para obter mais
informações, consulte Estendendo o suporte em tempo de design e Como criar um
controle dos Windows Forms que aproveita os recursos de tempo de design.
Confira também
Framework
Como: Desenvolver um controle simples do Windows Forms
Desenvolvendo um controle dos Windows Forms composto
Como criar um controle dos Windows Forms que aproveita recursos de tempo de
design
Recomendações do tipo de controle
Artigo • 02/06/2023
O .NET Framework fornece a capacidade de desenvolver e implementar novos controles.

Além do controle de usuário familiar, agora você poderá gravar controles
personalizados que executam sua os que executam suas próprias pinturas e que podem
até mesmo estender as funcionalidades de controles existentes por meio de herança.
Decidindo qual tipo de controle criar pode ser confuso. Esta seção destaca as diferenças
entre os vários tipos de controles pelos quais você pode herdar e fornece considerações
relacionadas ao tipo que você escolher para seu projeto.
７ Observação
Caso queira criar um controle para usar no Web Forms, consulte Desenvolvendo
Controles de Servidores ASP.NET Personalizados.
Herdando de um controle dos Windows Forms

Você pode derivar um controle herdado de qualquer controle Windows Forms existente.
Essa abordagem permite a você reter todas as funcionalidades inerentes de um controle
Windows Forms e estender essa funcionalidade adicionando propriedades
personalizadas, métodos ou outras funcionalidades. Por exemplo, você pode criar um
controle derivado TextBox que pode aceitar apenas números e converter
automaticamente a entrada em um valor. Um controle desse tipo pode conter código
de validação que foi chamado sempre que o texto na caixa de texto foi alterado e pode
ter uma propriedade adicional, Valor. Em alguns controles, você também pode adicionar
uma aparência personalizada à interface gráfica do controle substituindo o OnPaint
método da classe base.
Herde de um controle dos Windows Forms se:
A maioria da funcionalidade que você precisa já é idêntica a um controle Windows

Forms existente.
Você não precisa de uma interface gráfica personalizada ou deseja criar um novo
front-end gráfico para um controle existente.
Herdando da classe UserControl

Um controle de usuário é uma coleção de controles dos Windows Forms encapsulados
em um contêiner comum. Um contêiner contém todas as funcionalidades inerentes
associadas a cada um dos controles dos Windows Forms e permite que você exponha
seletivamente e associe suas propriedades. Um exemplo de um controle composto
poderia ser um controle criado para exibir dados de endereço de cliente de um banco
de dados. Esse controle incluiria várias caixas de texto para exibir cada campo e
controles de botão para navegar pelos registros. Você pode expor seletivamente
propriedades de associação de dados, além de poder empacotar e reutilizar todo o
controle do aplicativo para o aplicativo.
Herda da UserControl classe se:
Você deseja combinar a funcionalidade de vários controles dos Windows Forms

em uma única unidade reutilizável.
Herdando da Classe de Controle

Outra maneira de criar um controle é criar um substancialmente do zero herdando de
Control. A Control classe fornece toda a funcionalidade básica exigida por controles (por
exemplo, eventos), mas nenhuma funcionalidade ou interface gráfica específica do
controle. Criar um controle herdando da Control classe requer muito mais pensamento
e esforço do que herdar do controle do usuário ou de um controle de Windows Forms
existente. O autor deve escrever código para o OnPaint evento do controle, bem como
qualquer código específico de funcionalidade que seja necessário. Maior flexibilidade é
permitida, no entanto e você pode personalizar um controle para atender às suas
necessidades. Um exemplo de um controle personalizado é um controle de relógio que
duplica a aparência e a ação de um relógio analógico. A pintura personalizada seria
invocada para fazer com que as mãos do relógio se movessem em resposta a Tick
eventos de um componente de temporizador interno.
Herda da Control classe se:
Você deseja fornecer uma representação gráfica personalizada do seu controle.
Você precisa implementar a funcionalidade personalizada que não está disponível

por controles padrão.
Artigos relacionados
Como exibir um controle na caixa de diálogo Escolher Itens da Caixa de
Ferramentas
Passo a passo: serializando coleções de tipos padrão com
DesignerSerializationVisibilityAttribute
Passo a passo: herdando de um controle de Windows Forms
Como: Fornecer um bitmap da caixa de ferramentas para um controle
Como herdar de controles dos Windows Forms existentes
Passo a passo: depurando controles personalizados dos Windows Forms em

tempo de Design
Como: Herdar da classe Control
Como: Testar o comportamento de tempo de execução de um UserControl
Como alinhar um controle às bordas de formulários no tempo de design
Como: Herdar da classe UserControl
Como Criar Controles para o Windows Forms
Como: Criar controles compostos
Passo a passo: criando um controle composto
Passo a passo: criando um controle de Windows Forms que aproveita os recursos

de Design-Time do Visual Studio
design
Confira também
Noções básicas sobre o
desenvolvimento de controle dos
Windows Forms
Artigo • 02/06/2023
Um controle Windows Forms é uma classe que deriva direta ou indiretamente de

System.Windows.Forms.Control. A lista a seguir descreve os cenários comuns para o
desenvolvimento de controles do Windows Forms:
Combinando controles existentes para criar um controle composto.
Controles compostos encapsulam uma interface do usuário que pode ser

reutilizada como um controle. Um exemplo de um controle composto é um
controle que consiste em uma caixa de texto e um botão de redefinição. Designers
visuais dão suporte avançado para a criação de controles compostos. Para criar um
controle composto, deriva de System.Windows.Forms.UserControl. A classe
UserControl base fornece roteamento de teclado para controles filho e permite
que controles filho funcionem como um grupo. Para obter mais informações,
consulte Desenvolvendo um controle dos Windows Forms de composição.
Estendendo um controle existente para personalizá-la ou aumentar sua

funcionalidade.
Um botão cuja cor não pode ser alterado e um botão que tem uma propriedade
adicional que controla quantas vezes ele foi clicado são exemplos de controles
estendidos. Você pode personalizar qualquer controle do Windows Forms
derivado dele e substituir ou adicionar propriedades, métodos e eventos.
Criando um controle que não combina ou estende os controles existentes.
Nesse cenário, derive seu controle da classe Controlbase. Você pode adicionar e
substituir propriedades, métodos e eventos da classe base. Para começar, consulte
Como desenvolver um controle simples do Windows Forms.
A classe base para controles Windows Forms, Controlfornece o encanamento necessário

para exibição visual em aplicativos baseados no Windows do lado do cliente. Control
fornece um identificador de janela, manipula o roteamento de mensagens e fornece
eventos de mouse e teclado, bem como muitos outros eventos de interface do usuário.
Ele fornece layout avançado e tem propriedades específicas para exibição visual,
comoForeColor, , BackColor, HeightWidthe muitas outras. Além disso, ele fornece
segurança, suporte a threading e interoperabilidade com controles ActiveX. Como
grande parte da infraestrutura é fornecida pela classe base, é relativamente fácil
desenvolver seus próprios controles dos Windows Forms.
Confira também
Desenvolvendo um controle dos Windows Forms composto
Como: Criar um controle do Windows Forms que mostre o progresso
Como: Desenvolver um controle simples
do Windows Forms
Artigo • 02/06/2023
Esta seção explica as etapas principais para a criação de um controle personalizado dos
Windows Forms. O controle simples desenvolvido neste passo a passo permite que o
alinhamento de sua Text propriedade seja alterado. Ele não gera ou manipula eventos.
Para criar um controle personalizado simples

1. Defina uma classe derivada de System.Windows.Forms.Control.
C#
public class FirstControl:Control {}
2. Defina as propriedades. (Você não precisa definir propriedades, pois um controle

herda muitas propriedades da classe, mas a Control maioria dos controles
personalizados geralmente define propriedades adicionais.) O fragmento de
código a Text seguir define uma propriedade nomeada TextAlignment que
FirstControl usa para formatar a exibição da propriedade herdada.Control Para
obter mais informações sobre como definir as propriedades, consulte Properties

Overview (Visão geral das propriedades).
C#
// ContentAlignment is an enumeration defined in the System.Drawing

// namespace that specifies the alignment of content on a drawing
// surface.
private ContentAlignment alignmentValue = ContentAlignment.MiddleLeft;
Ao definir uma propriedade que altera a exibição visual do controle, você deve
invocar o Invalidate método para redesenhar o controle. Invalidate é definido na
classe Controlbase.
3. Substitua o método protegido herdado OnPaintControl para fornecer lógica de

renderização ao seu controle. Se você não substituir OnPaint, seu controle não
poderá desenhar sozinho. No fragmento de código a seguir, o OnPaint método
exibe a Text propriedade herdada Control com o alinhamento especificado pelo
alignmentValue campo.
C#

{
base.OnPaint(e);
StringFormat style = new StringFormat();
style.Alignment = StringAlignment.Near;
switch (alignmentValue)
{
case ContentAlignment.MiddleLeft:
break;
case ContentAlignment.MiddleRight:
style.Alignment = StringAlignment.Far;
break;
case ContentAlignment.MiddleCenter:
break;
}
// Call the DrawString method of the System.Drawing class to write

// text. Text and ClientRectangle are properties inherited from
// Control.
Text,
Font,
new SolidBrush(ForeColor),
ClientRectangle, style);
}
4. Forneça atributos para o seu controle. Os atributos permitem que um designer

visual exiba adequadamente seu controle, suas propriedades e eventos no tempo
de design. O fragmento de código a seguir se aplica aos atributos para a
propriedade TextAlignment . Em um designer como o Visual Studio, o Category
atributo (mostrado no fragmento de código) faz com que a propriedade seja
exibida em uma categoria lógica. O Description atributo faz com que uma cadeia
de caracteres descritiva seja exibida na parte inferior da janela Propriedades
quando a TextAlignment propriedade é selecionada. Para obter mais informações
sobre atributos, consulte Design-Time Attributes for Components (Atributos de
tempo de design para componentes).
C#
[
Category("Alignment"),
Description("Specifies the alignment of text.")
]
5. (opcional) Forneça recursos para o seu controle. Você pode fornecer um recurso,
como um bitmap, para seu controle usando uma opção do compilador ( /res para
C#) para recursos de pacote com seu controle. Em tempo de execução, o recurso
pode ser recuperado usando os métodos da ResourceManager classe. Para obter
mais informações sobre a criação e o uso de recursos, consulte Resources in
Desktop Apps (Recursos em aplicativos da Área de Trabalho).
6. Compile e implante seu controle. Para compilar e implantar FirstControl, ,

execute as seguintes etapas:
a. Salve o código no exemplo a seguir em um arquivo de origem (como

FirstControl.cs ou FirstControl.vb).
b. Compile o código-fonte em um assembly e salve-o no diretório do aplicativo.

Para fazer isso, execute o seguinte comando do diretório que contém o arquivo
de origem.
Console
vbc -t:library -out:[path to your application's

directory]/CustomWinControls.dll -r:System.dll -
r:System.Windows.Forms.dll -r:System.Drawing.dll FirstControl.vb
Console
csc -t:library -out:[path to your application's

directory]/CustomWinControls.dll -r:System.dll -
r:System.Windows.Forms.dll -r:System.Drawing.dll FirstControl.cs
A opção do compilador /t:library informa o compilador que o assembly que

você está criando é uma biblioteca (e não um executável). A opção /out
especifica o caminho e o nome do assembly. A opção /r fornece o nome dos
assemblies referenciados pelo seu código. Neste exemplo, você cria um
assembly particular que somente os seus aplicativos podem usar. Portanto, você
precisa salvá-lo no diretório do aplicativo. Para obter mais informações sobre o
empacotamento e a implantação de um controle para distribuição, consulte
Implantação.
O exemplo a seguir mostra o código para FirstControl . O controle é colocado no

namespace CustomWinControls . Um namespace fornece um agrupamento lógico de
tipos relacionados. Você pode criar seu controle em um namespace novo ou existente.
Em C#, a declaração using (no Visual Basic, Imports ) permite que os tipos sejam
acessados de um namespace sem usar o nome totalmente qualificado do tipo. No
exemplo a seguir, a declaração permite que o using código acesse a classe
System.Windows.FormsControl simplesmente Control em vez de ter que usar o nome
System.Windows.Forms.Controltotalmente qualificado.
C#
using System;
namespace CustomWinControls
{
public class FirstControl : Control
{
public FirstControl()
{
}
// ContentAlignment is an enumeration defined in the System.Drawing

// namespace that specifies the alignment of content on a drawing
// surface.
private ContentAlignment alignmentValue =
ContentAlignment.MiddleLeft;
[
Category("Alignment"),
Description("Specifies the alignment of text.")
]
public ContentAlignment TextAlignment
{
get
{
return alignmentValue;
}
set
{
alignmentValue = value;
// The Invalidate method invokes the OnPaint method

described
// in step 3.
Invalidate();
}
}

{
base.OnPaint(e);
StringFormat style = new StringFormat();
switch (alignmentValue)
{
case ContentAlignment.MiddleLeft:
break;
case ContentAlignment.MiddleRight:
style.Alignment = StringAlignment.Far;
break;
case ContentAlignment.MiddleCenter:
break;
}
// Call the DrawString method of the System.Drawing class to

write
// text. Text and ClientRectangle are properties inherited from
// Control.
Text,
Font,
new SolidBrush(ForeColor),
ClientRectangle, style);
}
}
}
Usando o controle personalizado em um

formulário
O exemplo a seguir mostra um formulário simples que usa FirstControl . Ele cria três
instâncias de FirstControl , cada uma com um valor diferente para a propriedade
TextAlignment .
Para compilar e executar esse exemplo
1. Salve o código no exemplo a seguir em um arquivo de origem (SimpleForm.cs ou

SimpleForms.vb).
2. Compile o código-fonte em um assembly executável, executando o seguinte

comando do diretório que contém o arquivo de origem.
Console
vbc -r:CustomWinControls.dll -r:System.dll -r:System.Windows.Forms.dll

-r:System.Drawing.dll SimpleForm.vb
Console
csc -r:CustomWinControls.dll -r:System.dll -r:System.Windows.Forms.dll

-r:System.Drawing.dll SimpleForm.cs
CustomWinControls.dll é o assembly que contém a classe FirstControl . Esse

assembly deve estar no mesmo diretório que o arquivo de origem para o
formulário que o acessa (SimpleForm.cs ou SimpleForms.vb).
3. Execute SimpleForm.exe usando o seguinte comando.
Console
SimpleForm
C#
using System;
namespace CustomWinControls
{
public class SimpleForm : System.Windows.Forms.Form

{
private FirstControl firstControl1;
private System.ComponentModel.Container components = null;
public SimpleForm()
{
}
protected override void Dispose( bool disposing )

{
if( disposing )
{
if (components != null)
{
}
}
base.Dispose( disposing );
}

{
this.firstControl1 = new FirstControl();
//
// firstControl1
//
this.firstControl1.BackColor =
System.Drawing.SystemColors.ControlDark;
this.firstControl1.Location = new System.Drawing.Point(96, 104);
this.firstControl1.Name = "firstControl1";
this.firstControl1.Size = new System.Drawing.Size(75, 16);
this.firstControl1.TabIndex = 0;
this.firstControl1.Text = "Hello World";
this.firstControl1.TextAlignment =
//
// SimpleForm
//
this.Controls.Add(this.firstControl1);
this.Name = "SimpleForm";
this.Text = "SimpleForm";
}
[STAThread]
static void Main()
{
Application.Run(new SimpleForm());
}
}
}
Confira também
Como: Criar um controle do Windows
Forms que mostre o progresso
Artigo • 02/06/2023
O exemplo de código a seguir mostra um controle personalizado chamado

FlashTrackBar que pode ser usado para mostrar ao usuário o nível ou o andamento de
um aplicativo. Ele usa um gradiente para representar visualmente o progresso.
O controle FlashTrackBar ilustra os seguintes conceitos:
Definindo propriedades personalizadas.
Definindo eventos personalizados. ( FlashTrackBar define o evento ValueChanged .)
Substituindo o OnPaint método para fornecer lógica para desenhar o controle.
Computando a área disponível para desenhar o controle usando sua

ClientRectangle propriedade. FlashTrackBar faz isso no seu método
OptimizedInvalidate .
Implementação de serialização ou persistência em uma propriedade quando ela

for alterada no Designer de Formulários do Windows. FlashTrackBar define os
métodos ShouldSerializeStartColor e ShouldSerializeEndColor para serializar
suas propriedades StartColor e EndColor .
A tabela a seguir mostra as propriedades personalizadas definidas por FlashTrackBar .
AllowUserEdit Indica se o usuário pode alterar o valor da barra de acompanhamento dinâmica

clicando nela e arrastando-a.
EndColor Especifica a cor final da barra de acompanhamento.
DarkenBy Especifica quanto a tela de fundo é escurecida em relação ao gradiente em

primeiro plano.
Max Especifica o valor máximo da barra de acompanhamento.
Min Especifica o valor mínimo da barra de acompanhamento.
StartColor Especifica a cor inicial do gradiente.
ShowPercentage Indica se um percentual deve ser exibido com relação ao gradiente.

ShowValue Indica se o valor atual deve ser exibido com relação ao gradiente.
ShowGradient Indica se a barra de acompanhamento deve exibir um gradiente de cores

mostrando o valor atual.
- Value Especifica o valor atual da barra de acompanhamento.
A tabela a seguir mostra os membros adicionais definidos pelo FlashTrackBar: o evento

de propriedade alterada e o método que gera o evento.
Membro DESCRIÇÃO
ValueChanged O evento que é gerado quando a propriedade Value da barra de

acompanhamento é alterada.
OnValueChanged O método que gera o evento ValueChanged .
７ Observação
FlashTrackBar usa a EventArgs classe para dados de evento e EventHandler para o

representante do evento.
Para lidar com os eventos EventName correspondentes, FlashTrackBar substitui os

seguintes métodos dos System.Windows.Forms.Controlquais ele herda:
OnPaint
OnMouseDown
OnMouseMove
OnMouseUp
OnResize
Para lidar com os eventos alterados por propriedade correspondentes, FlashTrackBar

substitui os seguintes métodos System.Windows.Forms.Controldos quais ele herda:
OnBackColorChanged
OnBackgroundImageChanged
OnTextChanged
Exemplo
O controle FlashTrackBar define dois editores de tipo de interface do usuário,
FlashTrackBarValueEditor e FlashTrackBarDarkenByEditor , que são mostrados nas
listagens de código a seguir. A classe HostApp usa o controle FlashTrackBar em um

Windows Form.
C#
namespace Microsoft.Samples.WinForms.Cs.FlashTrackBar {
using System;
using System.ComponentModel.Design;
using System.Drawing.Design;
public class FlashTrackBar : System.Windows.Forms.Control {

/// <summary>
/// </summary>
private System.ComponentModel.Container components;
private const int LeftRightBorder = 10;

private int value = 0;
private int min = 0;
private int max = 100;
private bool showPercentage = false;
private bool showValue = false;
private bool allowUserEdit = true;
private bool showGradient = true;
private int dragValue = 0;
private bool dragging = false;
private Color startColor = Color.Red;
private Color endColor = Color.LimeGreen;
private EventHandler onValueChanged;
private Brush baseBackground = null;
private Brush backgroundDim = null;
private byte darkenBy = 200;
public FlashTrackBar() {
//
// Required for Windows Form Designer support
//
SetStyle(ControlStyles.Opaque, true);
SetStyle(ControlStyles.ResizeRedraw, true);
Debug.Assert(GetStyle(ControlStyles.ResizeRedraw), "Should be
redraw!");
}
/// <summary>
/// </summary>
{
if (disposing) {
if (components != null) {
}
}
}
/// <summary>
/// </summary>
void InitializeComponent () {
this.components = new System.ComponentModel.Container ();
this.ForeColor = System.Drawing.Color.White;
this.BackColor = System.Drawing.Color.Black;
this.Text = "FlashTrackBar";
}
[
Category("Flash"),
DefaultValue(true)
]
public bool AllowUserEdit {
get {
return allowUserEdit;
}
set {
if (value != allowUserEdit) {
allowUserEdit = value;
if (!allowUserEdit) {
Capture = false;
dragging = false;
}
}
}
}
[
Category("Flash")
]
public Color EndColor {
get {
return endColor;
}
set {
endColor = value;
if (baseBackground != null && showGradient) {
baseBackground.Dispose();
baseBackground = null;
}
Invalidate();
}
}
public bool ShouldSerializeEndColor() {

return !(endColor == Color.LimeGreen);
}
[
Category("Flash"),
Editor(typeof(FlashTrackBarDarkenByEditor),
typeof(UITypeEditor)),
DefaultValue((byte)200)
]
public byte DarkenBy {
get {
return darkenBy;
}
set {
if (value != darkenBy) {
darkenBy = value;
if (backgroundDim != null) {
backgroundDim.Dispose();
backgroundDim = null;
}
OptimizedInvalidate(Value, max);
}
}
}
[
Category("Flash"),
DefaultValue(100)
]
public int Max {
get {
return max;
}
set {
if (max != value) {
max = value;
Invalidate();
}
}
}
[
Category("Flash"),
DefaultValue(0)
]
public int Min {
get {
return min;
}
set {
if (min != value) {
min = value;
Invalidate();
}
}
}
[
Category("Flash")
]
public Color StartColor {
get {
return startColor;
}
set {
startColor = value;
}
Invalidate();
}
}
public bool ShouldSerializeStartColor() {

return !(startColor == Color.Red);
}
[
Category("Flash"),
RefreshProperties(RefreshProperties.Repaint),
DefaultValue(false)
]
public bool ShowPercentage {
get {
return showPercentage;
}
set {
if (value != showPercentage) {
showPercentage = value;
if (showPercentage) {
showValue = false;
}
Invalidate();
}
}
}
[
Category("Flash"),
RefreshProperties(RefreshProperties.Repaint),
DefaultValue(false)
]
public bool ShowValue {
get {
return showValue;
}
set {
if (value != showValue) {
showValue = value;
if (showValue) {
showPercentage = false;
}
Invalidate();
}
}
}
[
Category("Flash"),
DefaultValue(true)
]
public bool ShowGradient {
get {
return showGradient;
}
set {
if (value != showGradient) {
showGradient = value;
if (baseBackground != null) {
}
Invalidate();
}
}
}
[
Category("Flash"),
Editor(typeof(FlashTrackBarValueEditor), typeof(UITypeEditor)),
DefaultValue(0)
]
public int Value {
get {
if (dragging) {
return dragValue;
}
return value;
}
set {
if (value != this.value) {
int old = this.value;
this.value = value;
OnValueChanged(EventArgs.Empty);
OptimizedInvalidate(old, this.value);
}
}
}
// ValueChanged Event
[Description("Raised when the Value displayed changes")]
public event EventHandler ValueChanged {
add {
onValueChanged += value;
}
remove {
onValueChanged -= value;
}
}
private void OptimizedInvalidate(int oldValue, int newValue) {

Rectangle client = ClientRectangle;
float oldPercentValue = ((float)oldValue / ((float)Max -

(float)Min));
int oldNonDimLength = (int)(oldPercentValue *
(float)client.Width);
float newPercentValue = ((float)newValue / ((float)Max -

(float)Min));
int newNonDimLength = (int)(newPercentValue *
(float)client.Width);
int min = Math.Min(oldNonDimLength, newNonDimLength);

int max = Math.Max(oldNonDimLength, newNonDimLength);
Rectangle invalid = new Rectangle(

client.X + min,
client.Y,
max - min,
client.Height);
Invalidate(invalid);
string oldToDisplay;
string newToDisplay;
if (ShowPercentage) {
oldToDisplay = Convert.ToString((int)(oldPercentValue *
100f)) + "%";
newToDisplay = Convert.ToString((int)(newPercentValue *
100f)) + "%";
}
else if (ShowValue) {
oldToDisplay = Convert.ToString(oldValue);
newToDisplay = Convert.ToString(newValue);
}
else {
oldToDisplay = null;
newToDisplay = null;
}
if (oldToDisplay != null && newToDisplay != null) {

Graphics g = CreateGraphics();
SizeF oldFontSize = g.MeasureString(oldToDisplay, Font);
SizeF newFontSize = g.MeasureString(newToDisplay, Font);
RectangleF oldFontRect = new RectangleF(new PointF(0, 0),
oldFontSize);
RectangleF newFontRect = new RectangleF(new PointF(0, 0),
newFontSize);
oldFontRect.X = (client.Width - oldFontRect.Width) / 2;
oldFontRect.Y = (client.Height - oldFontRect.Height) / 2;
newFontRect.X = (client.Width - newFontRect.Width) / 2;
newFontRect.Y = (client.Height - newFontRect.Height) / 2;
Invalidate(new Rectangle((int)oldFontRect.X,
(int)oldFontRect.Y, (int)oldFontRect.Width, (int)oldFontRect.Height));
Invalidate(new Rectangle((int)newFontRect.X,
(int)newFontRect.Y, (int)newFontRect.Width, (int)newFontRect.Height));
}
}
protected override void OnMouseDown(MouseEventArgs e) {

return;
}
Capture = true;
dragging = true;
SetDragValue(new Point(e.X, e.Y));
}
protected override void OnMouseMove(MouseEventArgs e) {

base.OnMouseMove(e);
if (!allowUserEdit || !dragging) {
return;
}
}
protected override void OnMouseUp(MouseEventArgs e) {

base.OnMouseUp(e);
return;
}
Capture = false;
dragging = false;
value = dragValue;
}
protected override void OnPaint(PaintEventArgs e) {
base.OnPaint(e);
if (baseBackground == null) {
if (showGradient) {
baseBackground = new LinearGradientBrush(new Point(0,
0),
new
Point(ClientSize.Width, 0),
StartColor,
EndColor);
}
else if (BackgroundImage != null) {
baseBackground = new TextureBrush(BackgroundImage);
}
else {
baseBackground = new SolidBrush(BackColor);
}
}
backgroundDim ??= new SolidBrush(Color.FromArgb(DarkenBy,

Color.Black));
Rectangle toDim = ClientRectangle;

float percentValue = ((float)Value / ((float)Max - (float)Min));
int nonDimLength = (int)(percentValue * (float)toDim.Width);
toDim.X += nonDimLength;
toDim.Width -= nonDimLength;
string text = Text;

string toDisplay = null;
RectangleF textRect = new RectangleF();
if (ShowPercentage || ShowValue || text.Length > 0) {
if (ShowPercentage) {
toDisplay = Convert.ToString((int)(percentValue * 100f))
+ "%";
}
else if (ShowValue) {
toDisplay = Convert.ToString(Value);
}
else {
toDisplay = text;
}
SizeF textSize = e.Graphics.MeasureString(toDisplay, Font);

textRect.Width = textSize.Width;
textRect.Height = textSize.Height;
textRect.X = (ClientRectangle.Width - textRect.Width) / 2;
textRect.Y = (ClientRectangle.Height - textRect.Height) / 2;
}
e.Graphics.FillRectangle(baseBackground, ClientRectangle);
e.Graphics.FillRectangle(backgroundDim, toDim);
e.Graphics.Flush();
if (toDisplay != null && toDisplay.Length > 0) {
e.Graphics.DrawString(toDisplay, Font, new
SolidBrush(ForeColor), textRect);
}
}
protected override void OnTextChanged(EventArgs e) {

base.OnTextChanged(e);
Invalidate();
}
protected override void OnBackColorChanged(EventArgs e) {

base.OnBackColorChanged(e);
if ((baseBackground != null) && (!showGradient)) {
}
}
protected override void OnBackgroundImageChanged(EventArgs e) {

}
}
protected override void OnResize(EventArgs e) {

base.OnResize(e);
}
}
protected virtual void OnValueChanged(EventArgs e) {

if (onValueChanged != null) {
onValueChanged.Invoke(this, e);
}
}
private void SetDragValue(Point mouseLocation) {
Rectangle client = ClientRectangle;
if (client.Contains(mouseLocation)) {
float percentage = (float)mouseLocation.X /
(float)ClientRectangle.Width;
int newDragValue = (int)(percentage * (float)(max - min));
if (newDragValue != dragValue) {
int old = dragValue;
dragValue = newDragValue;
OptimizedInvalidate(old, dragValue);
}
}
else {
if (client.Y <= mouseLocation.Y && mouseLocation.Y <=
client.Y + client.Height) {
if (mouseLocation.X <= client.X && mouseLocation.X >
client.X - LeftRightBorder) {
int newDragValue = min;
}
}
else if (mouseLocation.X >= client.X + client.Width &&
mouseLocation.X < client.X + client.Width + LeftRightBorder) {
int newDragValue = max;
}
}
}
else {
if (dragValue != value) {
dragValue = value;
}
}
}
}
}
}
C#
using System;
using System.Windows.Forms.ComponentModel;
using System.Windows.Forms.Design;
public class FlashTrackBarDarkenByEditor : FlashTrackBarValueEditor {

protected override void SetEditorProps(FlashTrackBar editingInstance,
FlashTrackBar editor) {
base.SetEditorProps(editingInstance, editor);
editor.Min = 0;
editor.Max = byte.MaxValue;
}
}
}
C#
using System;
using System.Windows.Forms.ComponentModel;
public class FlashTrackBarValueEditor :

System.Drawing.Design.UITypeEditor {
private IWindowsFormsEditorService edSvc = null;
protected virtual void SetEditorProps(FlashTrackBar editingInstance,

FlashTrackBar editor) {
editor.ShowValue = true;
editor.StartColor = Color.Navy;
editor.EndColor = Color.White;
editor.ForeColor = Color.White;
editor.Min = editingInstance.Min;
editor.Max = editingInstance.Max;
}
public override object EditValue(ITypeDescriptorContext context,

IServiceProvider provider, object value) {
if (context != null
&& context.Instance != null
&& provider != null) {
edSvc =
(IWindowsFormsEditorService)provider.GetService(typeof(IWindowsFormsEditorSe
rvice));
if (edSvc != null) {
FlashTrackBar trackBar = new FlashTrackBar();
trackBar.ValueChanged += new
EventHandler(this.ValueChanged);
SetEditorProps((FlashTrackBar)context.Instance,
trackBar);
bool asInt = true;
if (value is int) {
trackBar.Value = (int)value;
}
else if (value is byte) {
asInt = false;
trackBar.Value = (byte)value;
}
edSvc.DropDownControl(trackBar);
if (asInt) {
value = trackBar.Value;
}
else {
value = (byte)trackBar.Value;
}
}
}
return value;
}
public override UITypeEditorEditStyle

GetEditStyle(ITypeDescriptorContext context) {
if (context != null && context.Instance != null) {
return UITypeEditorEditStyle.DropDown;
}
return base.GetEditStyle(context);
}
private void ValueChanged(object sender, EventArgs e) {

if (edSvc != null) {
edSvc.CloseDropDown();
}
}
}
}
C#
namespace Microsoft.Samples.WinForms.Cs.HostApp {
using System;
using Microsoft.Samples.WinForms.Cs.FlashTrackBar;
public class HostApp : System.Windows.Forms.Form {

/// <summary>
/// </summary>
private System.ComponentModel.Container components;
protected internal
Microsoft.Samples.WinForms.Cs.FlashTrackBar.FlashTrackBar flashTrackBar1;
public HostApp() {
//
// Required for Windows Form Designer support
//
}
/// <summary>
/// </summary>
{
if (disposing) {
if (components != null) {
}
}
}
/// <summary>
/// </summary>
private void InitializeComponent() {
this.components = new System.ComponentModel.Container ();
this.flashTrackBar1 = new
Microsoft.Samples.WinForms.Cs.FlashTrackBar.FlashTrackBar ();
this.Text = "Control Example";
this.ClientSize = new System.Drawing.Size (600, 450);
flashTrackBar1.BackColor = System.Drawing.Color.Black;
flashTrackBar1.Dock = System.Windows.Forms.DockStyle.Fill;
flashTrackBar1.TabIndex = 0;
flashTrackBar1.ForeColor = System.Drawing.Color.White;
flashTrackBar1.Text = "Drag the Mouse and say Wow!";
flashTrackBar1.Value = 73;
flashTrackBar1.Size = new System.Drawing.Size (600, 450);
this.Controls.Add (this.flashTrackBar1);
}
/// <summary>
/// </summary>
[STAThread]
Application.Run(new HostApp());
}
}
}
Confira também
Desenvolver um controle de Windows
Forms composto
Artigo • 21/06/2023
Você pode desenvolver um controle de Windows Forms composto combinando outros

controles Windows Forms. Os controles compostos que derivam de são chamados de
controles de UserControl usuário. A classe base, UserControl, fornece roteamento de
teclado para os controles filho, garantindo assim que os controles filho possam receber
o foco. Para obter um exemplo de controle de usuário, consulte o UserControl exemplo
em Como aplicar atributos em controles Windows Forms.
O designer de Windows Forms no Visual Studio fornece suporte avançado em tempo de

design para criar controles de usuário.
Passo a passo: criando um controle de composição com o Visual C#

Ferramentas

Instruções passo a passo: herdando um controle dos Windows Forms com Visual
C#

tempo de Design

do Visual Studio Design-Time
design
Confira também
Como: Aplicar atributos a controles do Windows Forms
Framework
Propriedades em controles dos
Windows Forms
Artigo • 02/06/2023
Um controle Windows Forms herda muitas propriedades da classe

System.Windows.Forms.Controlbase. Elas incluem propriedades como Font, ForeColor,
BackColor, Bounds, ClientRectangle, DisplayRectangle, Enabled, Focused, , Height,
Width, , VisibleAutoSizee muitas outras. Para obter detalhes sobre as propriedades
herdadas, consulte System.Windows.Forms.Control.
Você pode substituir as propriedades herdadas em seu controle, bem como definir
novas propriedades.
Nesta seção
Definir uma propriedade
Mostra como implementar uma propriedade para um controle personalizado ou
componente e mostra como integrar a propriedade ambiente no de design.
Definindo valores padrão com o ShouldSerialize e os métodos de redefinição

Mostra como definir valores de propriedade padrão para um controle ou componente
personalizado.
Eventos com propriedade alterada

Descreve como habilitar as notificações de alteração de propriedade quando um valor
da propriedade for alterado.
Como: Expor as propriedades de controles constituintes

Mostra como expor as propriedades de controles constituintes em um controle de
composição o personalizado.
Implementação do método em controles personalizados

Descreve como implementar métodos de componentes e controles personalizados.
Referência
UserControl
Documenta a classe base para implementar controles de composição.
TypeConverterAttribute
Documenta o atributo que especifica o TypeConverter a ser usado para um tipo de
propriedade personalizado.
EditorAttribute
Documenta o atributo que especifica o UITypeEditor a ser usado para uma propriedade
personalizada.
Descreve os atributos que você pode aplicar a propriedades ou outros membros de
seus componentes e controles personalizados.
Atributos em tempo de design para componentes

Lista atributos de metadados para aplicar a componentes e controles para que eles
sejam exibidos corretamente em tempo de design em designers visuais.

Descreve como implementar classes como editores e designers que fornecem suporte
ao tempo de design.
Definindo uma propriedade em
controles dos Windows Forms
Artigo • 02/06/2023
Para obter uma visão geral das propriedades, consulte Visão geral das propriedades. Há
algumas considerações importantes ao definir uma propriedade:
Você deve aplicar atributos às propriedades que você definir. Atributos especificam
como o designer deve exibir uma propriedade. Para obter detalhes, consulte
Atributos de tempo de design para componentes.
Se a alteração da propriedade afetar a exibição visual do controle, chame o

Invalidate método (que seu controle herda de Control) do set acessador.
Invalidate por sua vez, chama o OnPaint método, que redesenha o controle. Várias
chamadas para Invalidate resultar em uma única chamada para OnPaint eficiência.
A biblioteca de classes do .NET Framework fornece conversores de tipo para tipos

de dados comuns como inteiros, números decimais, valores boolianos e outros. A
finalidade de um conversor de tipo geralmente é fornecer conversão de cadeia de
caracteres para valor (de dados de cadeia de caracteres em outros tipos de dados).
Tipos de dados comuns são associados a conversores de tipo padrão que
convertem valores em cadeias de caracteres e nos tipos de dados apropriados. Se
você definir uma propriedade que é um tipo de dados personalizado (isto é, fora
do padrão), será necessário aplicar um atributo que especifica o conversor de tipo
para associá-lo a essa propriedade. Você também pode usar um atributo para
associar um editor de tipos de interface do usuário personalizado a uma
propriedade. Um editor de tipos de interface do usuário fornece uma interface do
usuário para editar uma propriedade ou tipo de dados. Um seletor de cor é um
exemplo de um editor de tipos de interface do usuário. Exemplos de atributos são
fornecidos no final deste tópico.
７ Observação
Se um conversor de tipo ou um editor de tipos de interface do usuário não

estiver disponível para a propriedade personalizada, você poderá
implementar um conforme descrito em Estendendo o suporte no tempo de
design.
O fragmento de código a seguir define uma propriedade personalizada chamada

EndColor para o controle personalizado FlashTrackBar .
C#
public class FlashTrackBar : Control {

...
// Private data member that backs the EndColor property.
private Color endColor = Color.LimeGreen;
// The Category attribute tells the designer to display
// it in the Flash grouping.
// The Description attribute provides a description of
// the property.
[
Category("Flash"),
Description("The ending color of the bar.")
]
// The public property EndColor accesses endColor.
public Color EndColor {
get {
return endColor;
}
set {
endColor = value;
}
// The Invalidate method calls the OnPaint method, which redraws
// the control.
Invalidate();
}
}
...
}
O fragmento de código a seguir associa um conversor de tipo e um editor de tipo à

interface do usuário com a propriedade Value . Nesse caso Value , é um inteiro e tem
um conversor de tipo padrão, mas o TypeConverterAttribute atributo aplica um
conversor de tipo personalizado ( FlashTrackBarValueConverter ) que permite que o
designer o exiba como uma porcentagem. O editor de tipo da interface do usuário,
FlashTrackBarValueEditor , permite que o percentual seja exibido visualmente. Este
exemplo também mostra que o conversor de tipo ou editor especificado pelo
TypeConverterAttribute atributo ou EditorAttribute substitui o conversor padrão.
C#
[
Category("Flash"),
TypeConverter(typeof(FlashTrackBarValueConverter)),
Editor(typeof(FlashTrackBarValueEditor), typeof(UITypeEditor)),
Description("The current value of the track bar. You can enter an actual
value or a percentage.")
]
public int Value {
...
}
Confira também
Definindo valores padrão com o ShouldSerialize e os métodos de redefinição
Definindo valores padrão com o
ShouldSerialize e os métodos de
redefinição
Artigo • 02/06/2023
ShouldSerialize e Reset são métodos opcionais que você pode fornecer para uma
propriedade, se a propriedade não tiver um valor padrão simples. Se a propriedade tiver

um valor padrão simples, você deverá aplicar DefaultValueAttribute e fornecer o valor
padrão ao construtor da classe de atributo. Qualquer um desses mecanismos habilita os
recursos a seguir no designer:
A propriedade fornecerá uma indicação visual no navegador de propriedades se

tiver sido modificado de seu valor padrão.
O usuário pode clicar com o botão direito do mouse na propriedade e escolher

Redefinir para restaurar a propriedade para o valor padrão.
O designer gera um código mais eficiente.
７ Observação
Aplique os métodos DefaultValueAttribute Ou forneça

Reset PropertyName ShouldSerialize e PropertyName. Não use os dois.
Ao declarar um método ShouldSerialize ou Reset , use o modificador private de

acesso. Esses métodos geralmente são invocados pelo designer e não pelo código do
usuário.
O método Reset PropertyName define uma propriedade para o valor padrão, conforme
mostrado no seguinte fragmento de código.
C#
private void ResetMyFont()

{
MyFont = null;
}
７ Observação
Se uma Reset propriedade não tiver um método , DefaultValueAttributenão
estiver marcada com um e não tiver um valor padrão fornecido em sua declaração,
Reset a opção para essa propriedade será desabilitada no menu de atalho da
janela Propriedades do Designer de Formulários do Windows no Visual Studio.
Designers como Visual Studio ShouldSerialize usam o método PropertyName para

verificar se uma propriedade foi alterada de seu valor padrão e gravar código no
formulário somente se uma propriedade for alterada, permitindo assim uma geração de
código mais eficiente. Por exemplo:
C#
// Returns true if the font has changed; otherwise, returns false.

// The designer writes code to the form only if true is returned.
private bool ShouldSerializeMyFont()
{
return thefont != null;
}
 Dica
Se você quiser impedir permanentemente que uma propriedade seja serializada

pelo designer, adicione o atributo DesignerSerializationVisibility com o valor de
Hidden .
Segue um exemplo de código completo.
C#
using System;
public class MyControl : Control {

// Declare an instance of the Font class
// and set its default value to null.
private Font thefont = null;
// The MyFont property.

public Font MyFont {
// Note that the MyFont property never
// returns null.
get {
if (thefont != null) return thefont;
if (Parent != null) return Parent.Font;
return Control.DefaultFont;
}
set {
thefont = value;
}
}
private bool ShouldSerializeMyFont()

{
return thefont != null;
}
private void ResetMyFont()

{
MyFont = null;
}
}
Nesse caso, MyFont null mesmo quando o valor da variável privada acessada pela
propriedade for , null o navegador de propriedade não exibirá ; em vez disso, Font ele
exibirá a propriedade do pai, null se não for , Font ou o valor padrão definido em
Control. Portanto, o valor padrão para MyFont não pode ser simplesmente definido e
um DefaultValueAttribute não pode ser aplicado a essa propriedade. Em vez disso, os
métodos ShouldSerialize e Reset devem ser implementados para a propriedade
MyFont .
Confira também
Definir uma propriedade
System.ComponentModel.DesignerSerializationVisibilityAttribute
Artigo • 21/06/2023
Se você quiser que o controle envie notificações quando uma propriedade chamada
PropertyName mudar, defina um evento chamado PropertyName Changed e um método
chamado On PropertyName Changed que gera o evento. A convenção de nomenclatura
nos Windows Forms é acrescentar a palavra Changed ao nome da propriedade. O tipo
de delegado de evento associado para eventos alterados por propriedade é
EventHandlere o tipo de dados de evento é EventArgs. A classe Control base define
muitos eventos alterados por propriedade, como BackColorChanged,
BackgroundImageChanged, FontChanged, LocationChangede outros. Para obter
informações secundárias sobre eventos, consulte Eventos e Eventos em controles dos
Windows Forms.
Eventos de propriedade alterada são úteis porque permitem que os consumidores de

um controle anexem manipuladores de eventos que respondem à alteração. Se o
controle precisar responder a um evento alterado pela propriedade que ele gera,
substitua o método PropertyName Changed correspondente On em vez de anexar um
delegado ao evento. Um controle normalmente responde a um evento de propriedade
alterada atualizando outras propriedades ou redesenhando a superfície de alguns ou
todos os desenhos.
O exemplo a seguir mostra como o FlashTrackBar controle personalizado responde a

alguns dos eventos alterados pela propriedade herdados de Control. Para um exemplo
completo, consulte Como criar um controle dos Windows Forms que mostre o
progresso.
C#
protected override void OnTextChanged(EventArgs e) {

Invalidate();
}
protected override void OnBackColorChanged(EventArgs e) {

base.OnBackColorChanged(e);
}
}
Confira também
Eventos
Como: Expor as propriedades de
controles constituintes
Artigo • 02/06/2023
Os controles que compõem um controle de composição são chamados controles de

membro. Esses controles normalmente são declarados particulares e, portanto, não
podem ser acessados pelo desenvolvedor. Se você quiser disponibilizar as propriedades
desses controles para futuros usuários, deverá expô-las para o usuário. Uma
propriedade de um controle de membro é exposta pela criação de uma propriedade no
controle de usuário e usando os acessadores get e set dessa propriedade para efetivar
a alteração na propriedade privada do controle de membro.
Considere um controle de usuário hipotético com um botão de membro chamado

MyButton . Neste exemplo, quando o usuário solicita a ConstituentButtonBackColor
propriedade, o valor armazenado na BackColor propriedade é MyButton entregue.
Quando o usuário atribui um valor a essa propriedade, esse valor é passado
automaticamente para a BackColor propriedade e MyButton o set código será
executado, alterando a cor de MyButton .
O exemplo a seguir mostra como expor a BackColor propriedade do botão constituinte:
C#
public Color ButtonColor

{
get
{
return(myButton.BackColor);
}
set
{
myButton.BackColor = value;
}
}
Para expor uma propriedade de um controle de membro

1. Crie uma propriedade pública para o controle de usuário.
2. Na seção get da propriedade, escreva o código que recupera o valor da

propriedade que você deseja expor.
3. Na seção set da propriedade, escreva o código que passa o valor da propriedade
para a propriedade exposta do controle de membro.
Confira também
UserControl
Implementação do método em
controles personalizados
Artigo • 02/06/2023
Um método é implementado em um controle da mesma maneira que seria em qualquer

outro componente.
No Visual Basic, se for necessário a um método retornar um valor, será implementado

como um Public Function . Se nenhum valor for retornado, será implementado como
um Public Sub . Métodos são declarados usando a seguinte sintaxe:
VB
Public Function ConvertMatterToEnergy(Matter as Integer) As Integer

' Conversion code goes here.
End Function
Como funções retornam um valor, devem especificar um tipo de retorno, como inteiro,
cadeia de caracteres, objeto e assim por diante. Os argumentos Function ou Sub que os
procedimentos tomam, quando houver, também devem ser especificados.
O C# não distingue entre funções e procedimentos, como o Visual Basic faz. Um

método retorna um valor ou um void . A sintaxe para declarar um método público em
C# é:
C#
public int ConvertMatterToEnergy(int matter)

{
// Conversion code goes here.
}
Ao declarar um método, declare todos os seus argumentos como tipos de dados

explícitos sempre que possível. Argumentos que tomam referências de objetos devem
ser declarados como tipos de classe específicos — por exemplo, As Widget ao invés de
As Object . No Visual Basic, a configuração padrão Option Strict impõe essa regra
automaticamente.
Argumentos digitados permitem a captura de muitos erros do desenvolvedor pelo

compilador, ao invés de em tempo de execução. O compilador sempre captura erros,
enquanto o teste de tempo de execução é apenas tão bom quanto o conjunto de testes.
Métodos sobrecarregados
Se desejar permitir aos usuários de seu controle fornecer diferentes combinações de
parâmetros a um método, forneça múltiplas sobrecargas do método, usando tipos de
dados explícitos. Evite criar parâmetros declarados As Object que podem conter
qualquer tipo de dados, pois isso pode levar a erros que podem não ser capturados no
teste.
７ Observação
O tipo de dados universal no Common Language Runtime é Object ao invés de

Variant . Variant foi removido do idioma.
Por exemplo, o Spin método de um controle hipotético Widget pode permitir

especificação direta de direção e velocidade de rotação ou especificação de outro
Widget objeto do qual o momento angular deve ser absorvido:
C#
public void Spin(SpinDirectionsEnum spinDirection, double

revolutionsPerSecond)
{
// Implementation code here.
}
public void Spin(Widget driver)

{
// Implementation code here.
}
Confira também
Eventos
Eventos em controles dos Windows
Forms
Artigo • 21/06/2023
Um controle Windows Forms herda mais de sessenta eventos de

System.Windows.Forms.Control. Isso inclui o Paint evento , que faz com que um controle
seja desenhado, eventos relacionados à exibição de uma janela, como os Resize eventos
e Layout , e eventos de baixo nível de mouse e teclado. Alguns eventos de baixo nível
são sintetizados por Control em eventos semânticos, como Click e DoubleClick. Para
obter detalhes sobre eventos herdados, consulte Control.
Se o controle personalizado precisar substituir a funcionalidade de evento herdada,

substitua o método EventName herdado On em vez de anexar um delegado. Se você
não estiver familiarizado com o modelo de evento no .NET Framework, consulte
Gerando eventos de um componente.
Confira também
Substituindo o método OnPaint
Identificando a entrada do usuário
Definir um evento
Eventos
Substituindo o método OnPaint
Artigo • 21/06/2023
As etapas básicas para substituir qualquer evento definido no .NET Framework são
idênticas e resumidas na lista a seguir.
Substituir um evento herdado

1. Substituir o método On EventName protegido.
2. Chame o método On EventName da classe base do método On EventName

substituído, de modo que delegados registrados recebam o evento.
O Paint evento é discutido em detalhes aqui porque cada controle Windows Forms deve
substituir o Paint evento que herda de Control. A classe base Control não sabe como um
controle derivado precisa ser desenhado e não fornece nenhuma lógica de pintura no
OnPaint método . O OnPaint método de Control simplesmente despacha o Paint evento
para receptores de eventos registrados.
Se você trabalhou com o exemplo em Como desenvolver um controle de Windows

Forms simples, você viu um exemplo de substituição do OnPaint método. O fragmento
de código a seguir é retirado desse exemplo.
C#
public class FirstControl : Control {

public FirstControl() {}
protected override void OnPaint(PaintEventArgs e) {
// Call the OnPaint method of the base class.
base.OnPaint(e);
// Call methods of the System.Drawing.Graphics object.
e.Graphics.DrawString(Text, Font, new SolidBrush(ForeColor),
ClientRectangle);
}
}
A PaintEventArgs classe contém dados para o Paint evento. Ele tem duas propriedades,
conforme mostrado no código a seguir.
C#
public class PaintEventArgs : EventArgs {

...
public System.Drawing.Rectangle ClipRectangle {}
public System.Drawing.Graphics Graphics {}
...
}
ClipRectangle é o retângulo a ser pintado e a Graphics propriedade se refere a um

Graphics objeto . As classes no System.Drawing namespace são classes gerenciadas que
fornecem acesso à funcionalidade do GDI+, a nova biblioteca de gráficos do Windows.
O Graphics objeto tem métodos para desenhar pontos, cadeias de caracteres, linhas,
arcos, reticências e muitas outras formas.
Um controle invoca seu OnPaint método sempre que precisa alterar sua exibição visual.
Esse método, por sua vez, aciona o Paint evento.
Confira também
Eventos
Renderizando um controle dos Windows Forms
Definir um evento
Identificando a entrada do usuário
Artigo • 02/06/2023
Este tópico descreve os principais eventos de teclado e mouse fornecidos por

System.Windows.Forms.Control. Ao manipular um evento, os autores do controle devem
substituir o método On EventName protegido em vez de associar um delegado ao
evento. Para ver uma análise de eventos, consulte Gerando eventos de um componente.
７ Observação
Se não houver dados associados a um evento, uma instância da classe EventArgs

base será passada como um argumento para o On método EventName.
Eventos de teclado
Os eventos comuns de teclado que o controle pode manipular são KeyDown, KeyPresse
KeyUp.
Nome Método a ser Descrição do evento

do substituído
evento
KeyDown void Gerado somente quando uma tecla é pressionada pela

OnKeyDown(KeyEventArgs) primeira vez.
KeyPress void OnKeyPress Gerado sempre que uma tecla é pressionada. Se uma
chave for mantida pressionada, um KeyPress evento será
(KeyPressEventArgs) gerado na taxa de repetição definida pelo sistema
operacional.
KeyUp void Gerado quando uma tecla é liberada.

OnKeyUp(KeyEventArgs)
７ Observação
Manipular a entrada do teclado é consideravelmente mais complexo que substituir

os eventos na tabela anterior e está além do escopo deste tópico. Para obter mais
informações, consulte Entrada do usuário no Windows Forms.
Eventos de mouse
Os eventos do mouse que seu controle pode manipular sãoMouseDown, , ,
MouseHover, MouseLeavee MouseUpMouseMove. MouseEnter
Nome do Método a ser substituído Descrição do evento

evento
MouseDown void Gerado quando o botão do mouse é pressionado

OnMouseDown(MouseEventArgs) enquanto o ponteiro está sobre o controle.
MouseEnter void Gerado quando o ponteiro entra pela primeira vez

OnMouseEnter(EventArgs) na região do controle.
MouseHover void Gerado quando o ponteiro do mouse focaliza o

OnMouseHover(EventArgs) controle.
MouseLeave void Gerado quando o ponteiro do mouse deixa a região

OnMouseLeave(EventArgs) do controle.
MouseMove void Gerado quando o ponteiro do mouse se move na

OnMouseMove(MouseEventArgs) região do controle.
MouseUp void Gerado quando o botão do mouse é liberado

OnMouseUp(MouseEventArgs) enquanto o ponteiro está sobre o controle ou o
ponteiro sai da região do controle.
O fragmento de código a seguir mostra um exemplo de substituição do MouseDown

evento.
C#
protected override void OnMouseDown(MouseEventArgs e) {

return;
}
Capture = true;
dragging = true;
}
O fragmento de código a seguir mostra um exemplo de substituição do MouseMove

evento.
C#
protected override void OnMouseMove(MouseEventArgs e) {

base.OnMouseMove(e);
return;
}
}
O fragmento de código a seguir mostra um exemplo de substituição do MouseUp

evento.
C#
protected override void OnMouseUp(MouseEventArgs e) {

base.OnMouseUp(e);
return;
}
Capture = false;
dragging = false;
value = dragValue;
}
Para ver o código-fonte completo para o exemplo FlashTrackBar , consulte Como criar
um controle do Windows Forms que mostra o progresso.
Confira também
Definir um evento
Eventos
Entrada do usuário no Windows Forms
Definindo um evento em controles dos
Windows Forms
Artigo • 02/06/2023
Para obter detalhes sobre como definir eventos personalizados, consulte Eventos. Se
você definir um evento que não tenha dados associados, use o tipo de base para dados
de eventos, EventArgs e use EventHandler como o delegado do evento. Tudo o que
resta fazer é definir um membro do evento e um método EventName protegido On que
gera o evento.
O fragmento de código a seguir mostra como o controle personalizado FlashTrackBar

define um evento personalizado, ValueChanged . Para obter o código completo do
FlashTrackBar exemplo, consulte como criar um controle de Windows Forms que
mostra o progresso.
C#
using System;
public class FlashTrackBar : Control {

// The event does not have any data, so EventHandler is adequate
// as the event delegate.
private EventHandler onValueChanged;
// Define the event member using the event keyword.
// In this case, for efficiency, the event is defined
// using the event property construct.
public event EventHandler ValueChanged {
add {
onValueChanged += value;
}
remove {
onValueChanged -= value;
}
}
// The protected method that raises the ValueChanged
// event when the value has actually
// changed. Derived controls can override this method.
protected virtual void OnValueChanged(EventArgs e)
{
onValueChanged?.Invoke(this, e);
}
}
Confira também
Eventos
Atributos em controles dos Windows
Forms
Artigo • 02/06/2023
O .NET Framework fornece uma variedade de atributos que podem se aplicados aos
membros de seus controles personalizados e componentes. Alguns desses atributos
afetam o comportamento de uma classe no tempo de execução, enquanto outros
afetam o comportamento no tempo de design.
Atributos de propriedades de controles e

componentes
A tabela a seguir mostra os atributos que podem ser aplicados a propriedades ou
outros membros de seus controles e componentes personalizados. Para ver um exemplo
que usa muitos desses atributos, consulte Como aplicar atributos a controles dos
Windows Forms.
Atributo Descrição
AmbientValueAttribute Especifica o valor a ser passado para uma propriedade para

fazer com que a propriedade obtenha o seu valor de outra
origem. Isso é conhecido como ambiente.
BrowsableAttribute Especifica se uma propriedade ou evento deve ser exibido em

uma janela Propriedades .
CategoryAttribute Especifica o nome da categoria na qual agrupar a propriedade

ou o evento quando exibido em um PropertyGrid controle
definido como Categorized modo.
DefaultValueAttribute Especifica o valor padrão de uma propriedade.
DescriptionAttribute Especifica uma descrição de uma propriedade ou evento.
DisplayNameAttribute Especifica o nome de exibição de uma propriedade, evento ou

método public void que não usa argumentos.
EditorAttribute Especifica o editor que deve ser usado para alterar uma
propriedade.
EditorBrowsableAttribute Especifica que uma propriedade ou método é visível em um

editor.
HelpKeywordAttribute Especifica a palavra-chave de contexto para uma classe ou

membro.
LocalizableAttribute Especifica se uma propriedade deve ser localizada.
PasswordPropertyTextAttribute Indica que a representação de texto de um objeto é obscurecida

por caracteres como asteriscos.
ReadOnlyAttribute Especifica se a propriedade à qual esse atributo está associado é

somente leitura ou leitura/gravação no tempo de design.
RefreshPropertiesAttribute Indica que a grade de propriedades deve ser atualizada quando

o valor da propriedade associada é alterado.
TypeConverterAttribute Especifica o tipo a ser usado como um conversor para o objeto

ao qual este atributo está associado.
Atributos para propriedades de vinculação de

dados
A tabela a seguir mostra os atributos que podem ser aplicados para especificar como os
controles e componentes personalizados interagem com vinculação de dados.
BindableAttribute Especifica se uma propriedade normalmente é usada para

associação.
ComplexBindingPropertiesAttribute Especifica a fonte de dados e as propriedades de membro

de dados para um componente.
DefaultBindingPropertyAttribute Especifica a propriedade de associação padrão de um

componente.
LookupBindingPropertiesAttribute Especifica a fonte de dados e as propriedades de membro

de dados para um componente.
AttributeProviderAttribute Habilita o redirecionamento de atributo.
Atributos para classes

A tabela a seguir mostra os atributos que podem ser aplicados para especificar o
comportamento dos seus controles e componentes personalizados no tempo de design.
DefaultEventAttribute Especifica o evento padrão de um componente.
DefaultPropertyAttribute Especifica a propriedade padrão de um componente.
DesignerAttribute Especifica a classe usada para implementar os serviços de tempo de

design para um componente.
DesignerCategoryAttribute Especifica que o designer de uma classe pertence a uma

determinada categoria.
ToolboxItemAttribute Representa um atributo de um item de caixa de ferramentas.
ToolboxItemFilterAttribute Especifica a cadeia de caracteres de filtro e o tipo de filtro para um

item de Caixa de ferramentas.
Confira também
Attribute
Como: Aplicar atributos a controles do Windows Forms
Framework
Como: Aplicar atributos a controles do
Windows Forms
Artigo • 17/06/2023
Para desenvolver componentes e controles que interagem corretamente com o

ambiente de design e são executados corretamente no tempo de execução, você
precisa aplicar atributos corretamente a classes e membros.
Ｕ Cuidado
Este conteúdo foi escrito para .NET Framework. Se você estiver usando o .NET 6 ou
uma versão posterior, use esse conteúdo com cuidado. O sistema de designer foi
alterado para Windows Forms e é importante que você examine as alterações de
Designer desde .NET Framework artigo.
Exemplo
O exemplo de código a seguir demonstra como usar vários atributos em um controle
personalizado. O controle demonstra um recurso de funcionalidade em log simples.
Quando o controle está associado a uma fonte de dados, ele exibe os valores enviados
pela fonte de dados em um DataGridView controle. Se um valor exceder o valor
especificado pela propriedade Threshold , um evento ThresholdExceeded será gerado.
O AttributesDemoControl registra valores com uma classe LogEntry . A classe LogEntry é

uma classe de modelo, o que significa que ela é parametrizada pelo tipo abordado pelo
registro em log. Por exemplo, se o AttributesDemoControl registrar em log os valores do
tipo float , cada instância LogEntry será declarada e usada da seguinte maneira.
C#
// This method handles the timer's Elapsed event. It queries

// the performance counter for the next value, packs the
// value in a LogEntry object, and adds the new LogEntry to
// the list managed by the BindingSource.
private void timer1_Elapsed(
object sender,
System.Timers.ElapsedEventArgs e)
{
// Get the latest value from the performance counter.
float val = this.performanceCounter1.NextValue();
// The performance counter returns values of type float,
// but any type that implements the IComparable interface
// will work.
LogEntry<float> entry = new LogEntry<float>(val, DateTime.Now);
// Add the new LogEntry to the BindingSource list.

this.bindingSource1.Add(entry);
}
７ Observação
Como LogEntry é parametrizado por um tipo arbitrário, ele deve usar a reflexão
para operar no tipo de parâmetro. Para que o recurso de limite funcione, o tipo T
de parâmetro deve implementar a IComparable interface .
O formulário que hospeda o AttributesDemoControl consulta um contador de

desempenho periodicamente. Cada valor é empacotado em um LogEntry do tipo
apropriado e adicionado ao do BindingSourceformulário. O AttributesDemoControl
recebe o valor por meio de sua associação de dados e exibe o valor em um
DataGridView controle .
C#
using System;
using System.Data;
using System.Reflection;
using System.Text;
// This sample demonstrates the use of various attributes for

// authoring a control.
namespace AttributesDemoControlLibrary
{
// This is the event handler delegate for the ThresholdExceeded event.
public delegate void
ThresholdExceededEventHandler(ThresholdExceededEventArgs e);
// This control demonstrates a simple logging capability.

[ComplexBindingProperties("DataSource", "DataMember")]
[DefaultBindingProperty("TitleText")]
[DefaultEvent("ThresholdExceeded")]
[DefaultProperty("Threshold")]
[HelpKeywordAttribute(typeof(UserControl))]
[ToolboxItem("System.Windows.Forms.Design.AutoSizeToolboxItem,System.Design"
)]
public class AttributesDemoControl : UserControl
{
// This backs the Threshold property.

private object thresholdValue;
// The default fore color value for DataGridView cells that

// contain values that exceed the threshold.
private static Color defaultAlertForeColorValue = Color.White;
// The default back color value for DataGridView cells that

private static Color defaultAlertBackColorValue = Color.Red;
// The ambient color value.

private static Color ambientColorValue = Color.Empty;
// The fore color value for DataGridView cells that

private Color alertForeColorValue = defaultAlertForeColorValue;
// The back color value for DataGridView cells that

private Color alertBackColorValue = defaultAlertBackColorValue;
// Child controls that comprise this UserControl.

private TableLayoutPanel tableLayoutPanel1;
// Required for designer support.

// Default constructor.
public AttributesDemoControl()
{
}
[Category("Appearance")]
[Description("The title of the log data.")]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]
[Localizable(true)]
[HelpKeywordAttribute("AttributesDemoControlLibrary.AttributesDemoControl.Ti
tleText")]
public string TitleText
{
get
{
return this.label1.Text;
}
set
{
this.label1.Text = value;
}
}
// The inherited Text property is hidden at design time and

// raises an exception at run time. This enforces a requirement
// that client code uses the TitleText property instead.
[Browsable(false)]
[EditorBrowsable(EditorBrowsableState.Never)]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
public override string Text
{
get
{
throw new NotSupportedException();
}
set
{
throw new NotSupportedException();
}
}
[AmbientValue(typeof(Color), "Empty")]
[DefaultValue(typeof(Color), "White")]
[Description("The color used for painting alert text.")]
public Color AlertForeColor
{
get
{
if (this.alertForeColorValue == Color.Empty &&
this.Parent != null)
{
return Parent.ForeColor;
}
return this.alertForeColorValue;
}
set
{
this.alertForeColorValue = value;
}
}
// This method is used by designers to enable resetting the

// property to its default value.
public void ResetAlertForeColor()
{
this.AlertForeColor =
AttributesDemoControl.defaultAlertForeColorValue;
}
// This method indicates to designers whether the property

// value is different from the ambient value, in which case
// the designer should persist the value.
private bool ShouldSerializeAlertForeColor()
{
return (this.alertForeColorValue !=
AttributesDemoControl.ambientColorValue);
}
[DefaultValue(typeof(Color), "Red")]
[Description("The background color for painting alert text.")]
public Color AlertBackColor
{
get
{
if (this.alertBackColorValue == Color.Empty &&
{
return Parent.BackColor;
}
return this.alertBackColorValue;
}
set
{
this.alertBackColorValue = value;
}
}

public void ResetAlertBackColor()
{
this.AlertBackColor =
AttributesDemoControl.defaultAlertBackColorValue;
}

private bool ShouldSerializeAlertBackColor()
{
return (this.alertBackColorValue !=
}
[Category("Data")]
[Description("Indicates the source of data for the control.")]
[RefreshProperties(RefreshProperties.Repaint)]
[AttributeProvider(typeof(IListSource))]
public object DataSource
{
get
{
return this.dataGridView1.DataSource;
}
set
{
this.dataGridView1.DataSource = value;
}
}
[Category("Data")]
[Description("Indicates a sub-list of the data source to show in the
control.")]
public string DataMember
{
get
{
return this.dataGridView1.DataMember;
}
set
{
this.dataGridView1.DataMember = value;
}
}
// This property would normally have its BrowsableAttribute

// set to false, but this code demonstrates using
// ReadOnlyAttribute, so BrowsableAttribute is true to show
// it in any attached PropertyGrid control.
[Browsable(true)]
[Category("Behavior")]
[Description("The timestamp of the latest entry.")]
[ReadOnly(true)]
public DateTime CurrentLogTime
{
get
{
int lastRowIndex =
this.dataGridView1.Rows.GetLastRow(
DataGridViewElementStates.Visible);
if (lastRowIndex > -1)

{
DataGridViewRow lastRow =
this.dataGridView1.Rows[lastRowIndex];
DataGridViewCell lastCell = lastRow.Cells["EntryTime"];
return ((DateTime)lastCell.Value);
}
else
{
return DateTime.MinValue;
}
}
set
{
}
}
[Category("Behavior")]
[Description("The value above which the ThresholdExceeded event will
be raised.")]
public object Threshold
{
get
{
return this.thresholdValue;
}
set
{
this.thresholdValue = value;
}
}
// This property exists only to demonstrate the

// PasswordPropertyText attribute. When this control
// is attached to a PropertyGrid control, the returned
// string will be displayed with obscuring characters
// such as asterisks. This property has no other effect.
[Category("Security")]
[Description("Demonstrates PasswordPropertyTextAttribute.")]
[PasswordPropertyText(true)]
public string Password
{
get
{
return "This is a demo password.";
}
}
// This property exists only to demonstrate the

// DisplayName attribute. When this control
// is attached to a PropertyGrid control, the
// property will be appear as "RenamedProperty"
// instead of "MisnamedProperty".
[Description("Demonstrates DisplayNameAttribute.")]
[DisplayName("RenamedProperty")]
public bool MisnamedProperty
{
get
{
return true;
}
}
// This is the declaration for the ThresholdExceeded event.
public event ThresholdExceededEventHandler ThresholdExceeded;
#region Implementation
// This is the event handler for the DataGridView control's

// CellFormatting event. Handling this event allows the
// AttributesDemoControl to examine the incoming log entries
// from the data source as they arrive.
//
// If the cell for which this event is raised holds the
// log entry's timestamp, the cell value is formatted with
// the full date/time pattern.
//
// Otherwise, the cell's value is assumed to hold the log
// entry value. If the value exceeds the threshold value,
// the cell is painted with the colors specified by the
// AlertForeColor and AlertBackColor properties, after which
// the ThresholdExceeded is raised. For this comparison to
// succeed, the log entry's type must implement the IComparable
// interface.
private void dataGridView1_CellFormatting(
object sender,
DataGridViewCellFormattingEventArgs e)
{
try
{
{
if (e.Value is DateTime)
{
// Display the log entry time with the
// full date/time pattern (long time).
e.CellStyle.Format = "F";
}
else
{
// Scroll to the most recent entry.
DataGridViewRow row =
this.dataGridView1.Rows[e.RowIndex];
DataGridViewCell cell = row.Cells[e.ColumnIndex];
this.dataGridView1.FirstDisplayedCell = cell;
if (this.thresholdValue != null)
{
// Get the type of the log entry.
object val = e.Value;
Type paramType = val.GetType();
// Compare the log entry value to the threshold

value.
// Use reflection to call the CompareTo method
on the
// template parameter's type.
int compareVal = (int)paramType.InvokeMember(
"CompareTo",
BindingFlags.Default |
BindingFlags.InvokeMethod,
null,
e.Value,
new object[] { this.thresholdValue },
System.Globalization.CultureInfo.InvariantCulture);
// If the log entry value exceeds the threshold

value,
// set the cell's fore color and back color
properties
// and raise the ThresholdExceeded event.
if (compareVal > 0)
{
e.CellStyle.BackColor =
this.alertBackColorValue;
e.CellStyle.ForeColor =
this.alertForeColorValue;
ThresholdExceededEventArgs teea =
new ThresholdExceededEventArgs(
this.thresholdValue,
e.Value);
this.ThresholdExceeded(teea);
}
}
}
}
}
{
Trace.WriteLine(ex.Message);
}
}

{
{
}
}

{
System.Windows.Forms.DataGridViewCellStyle
dataGridViewCellStyle1 = new System.Windows.Forms.DataGridViewCellStyle();
this.dataGridView1 = new System.Windows.Forms.DataGridView();
(this.dataGridView1)).BeginInit();
//
//
this.tableLayoutPanel1.AutoSize = true;
System.Windows.Forms.ColumnStyle(System.Windows.Forms.SizeType.Absolute,
100F));
System.Windows.Forms.ColumnStyle(System.Windows.Forms.SizeType.Absolute,
100F));
this.tableLayoutPanel1.Controls.Add(this.dataGridView1, 0, 1);
this.tableLayoutPanel1.Dock =
System.Windows.Forms.DockStyle.Fill;
10);
this.tableLayoutPanel1.Padding = new
//
// dataGridView1
//
this.dataGridView1.AllowUserToDeleteRows = false;
this.dataGridView1.AllowUserToOrderColumns = true;
this.dataGridView1.ColumnHeadersHeightSizeMode =
this.dataGridView1.AutoSizeRowsMode =
System.Windows.Forms.DataGridViewAutoSizeRowsMode.AllCells;
dataGridViewCellStyle1.Alignment =
System.Windows.Forms.DataGridViewContentAlignment.MiddleLeft;
dataGridViewCellStyle1.BackColor =
System.Drawing.SystemColors.Control;
dataGridViewCellStyle1.Font = new System.Drawing.Font("Microsoft
Sans Serif", 8.25F, System.Drawing.FontStyle.Regular,
System.Drawing.GraphicsUnit.Point, ((byte)(0)));
dataGridViewCellStyle1.ForeColor =
System.Drawing.SystemColors.WindowText;
dataGridViewCellStyle1.SelectionBackColor =
System.Drawing.SystemColors.Highlight;
dataGridViewCellStyle1.SelectionForeColor =
System.Drawing.SystemColors.HighlightText;
dataGridViewCellStyle1.WrapMode =
System.Windows.Forms.DataGridViewTriState.False;
this.dataGridView1.ColumnHeadersDefaultCellStyle =
dataGridViewCellStyle1;
this.dataGridView1.ColumnHeadersHeight = 4;
this.dataGridView1.Dock = System.Windows.Forms.DockStyle.Fill;
this.dataGridView1.Location = new System.Drawing.Point(13, 57);
this.dataGridView1.Name = "dataGridView1";
this.dataGridView1.RowHeadersVisible = false;
this.dataGridView1.Size = new System.Drawing.Size(399, 354);
this.dataGridView1.TabIndex = 1;
this.dataGridView1.CellFormatting += new
System.Windows.Forms.DataGridViewCellFormattingEventHandler(this.dataGridVie
w1_CellFormatting);
//
// label1
//
this.label1.BackColor = System.Drawing.SystemColors.Control;
this.label1.Dock = System.Windows.Forms.DockStyle.Fill;
this.label1.Text = "label1";
this.label1.TextAlign =
//
// AttributesDemoControl
//
this.Name = "AttributesDemoControl";
(this.dataGridView1)).EndInit();
}
#endregion
}
// This is the EventArgs class for the ThresholdExceeded event.

public class ThresholdExceededEventArgs : EventArgs
{
private object thresholdValue = null;
private object exceedingValue = null;
public ThresholdExceededEventArgs(
object thresholdValue,
object exceedingValue)
{
this.thresholdValue = thresholdValue;
this.exceedingValue = exceedingValue;
}
public object ThresholdValue

{
get
{
return this.thresholdValue;
}
}
public object ExceedingValue

{
get
{
return this.exceedingValue;
}
}
}
// This class encapsulates a log entry. It is a parameterized

// type (also known as a template class). The parameter type T
// defines the type of data being logged. For threshold detection
// to work, this type must implement the IComparable interface.
[TypeConverter("LogEntryTypeConverter")]
public class LogEntry<T> where T : IComparable
{
private T entryValue;
private DateTime entryTimeValue;
public LogEntry(
T value,
DateTime time)
{
this.entryValue = value;
this.entryTimeValue = time;
}
public T Entry
{
get
{
return this.entryValue;
}
}
public DateTime EntryTime

{
get
{
return this.entryTimeValue;
}
}
// This is the TypeConverter for the LogEntry class.

public class LogEntryTypeConverter : TypeConverter
{
public override bool CanConvertFrom(
ITypeDescriptorContext context,
Type sourceType)
{
if (sourceType == typeof(string))
{
return true;
}
return base.CanConvertFrom(context, sourceType);

}
public override object ConvertFrom(

System.Globalization.CultureInfo culture,
object value)
{
if (value is string)
{
string[] v = ((string)value).Split(new char[] { '|' });
Type paramType = typeof(T);

T entryValue = (T)paramType.InvokeMember(
"Parse",
BindingFlags.Static | BindingFlags.Public |
null,
null,
new string[] { v[0] },
culture);
return new LogEntry<T>(

entryValue,
DateTime.Parse(v[2]));
}
return base.ConvertFrom(context, culture, value);

}
public override object ConvertTo(

object value,
Type destinationType)
{
if (destinationType == typeof(string))
{
LogEntry<T> le = value as LogEntry<T>;
string stringRepresentation =
String.Format("{0} | {1}",
le.Entry,
le.EntryTime);
return stringRepresentation;
}
return base.ConvertTo(context, culture, value,

destinationType);
}
}
}
}
C#
using System;
using System.Data;
using AttributesDemoControlLibrary;
// This sample demonstrates using the AttributesDemoControl to log

// data from a data source.
namespace AttributesDemoControlTest
{
{
private System.Diagnostics.PerformanceCounter performanceCounter1;
private Button startButton;
private Button stopButton;
private System.Timers.Timer timer1;
private ToolStripStatusLabel statusStripPanel1;
private NumericUpDown numericUpDown1;
private GroupBox groupBox1;
private GroupBox groupBox2;
private TableLayoutPanel tableLayoutPanel1;
private AttributesDemoControl attributesDemoControl1;
// This form uses an AttributesDemoControl to display a stream

// of LogEntry objects. The data stream is generated by polling
// a performance counter and communicating the counter values
// to the control with data binding.
public Form1()
{
// Set the initial value of the threshold up/down control

// to the control's threshold value.
this.numericUpDown1.Value =
(decimal)(float)this.attributesDemoControl1.Threshold;
// Assign the performance counter's name to the control's

// title text.
this.attributesDemoControl1.TitleText =
this.performanceCounter1.CounterName;
}
// This method handles the ThresholdExceeded event. It posts

// the value that exceeded the threshold to the status strip.
private void attributesDemoControl1_ThresholdExceeded(
ThresholdExceededEventArgs e)
{
"{0}: Value {1} exceeded threshold {2}",
this.attributesDemoControl1.CurrentLogTime,
e.ExceedingValue,
e.ThresholdValue);
this.ReportStatus( msg );
}
// This method handles the timer's Elapsed event. It queries

// the performance counter for the next value, packs the
// value in a LogEntry object, and adds the new LogEntry to
// the list managed by the BindingSource.
private void timer1_Elapsed(
object sender,
System.Timers.ElapsedEventArgs e)
{
// Get the latest value from the performance counter.
float val = this.performanceCounter1.NextValue();
// The performance counter returns values of type float,

// but any type that implements the IComparable interface
// will work.
LogEntry<float> entry = new LogEntry<float>(val, DateTime.Now);
// Add the new LogEntry to the BindingSource list.

this.bindingSource1.Add(entry);
}
private void numericUpDown1_ValueChanged(object sender, EventArgs e)

{
this.attributesDemoControl1.Threshold =
(float)this.numericUpDown1.Value;

"Threshold changed to {0}",
this.attributesDemoControl1.Threshold);
this.ReportStatus(msg);
}
private void startButton_Click(object sender, EventArgs e)
{
this.ReportStatus(DateTime.Now + ": Starting");
this.timer1.Start();
}
private void stopButton_Click(object sender, EventArgs e)

{
this.ReportStatus(DateTime.Now + ": Stopping");
this.timer1.Stop();
}
private void ReportStatus(string msg)

{
if (msg != null)
{
this.statusStripPanel1.Text = msg;
}
}
[STAThread]
static void Main()
{
}

{
{
}
}

{
this.bindingSource1 = new
System.Windows.Forms.BindingSource(this.components);
this.performanceCounter1 = new
System.Diagnostics.PerformanceCounter();
this.startButton = new System.Windows.Forms.Button();
this.stopButton = new System.Windows.Forms.Button();
this.timer1 = new System.Timers.Timer();
this.statusStripPanel1 = new
System.Windows.Forms.ToolStripStatusLabel();
this.numericUpDown1 = new System.Windows.Forms.NumericUpDown();
this.groupBox1 = new System.Windows.Forms.GroupBox();
this.groupBox2 = new System.Windows.Forms.GroupBox();
this.attributesDemoControl1 = new
AttributesDemoControlLibrary.AttributesDemoControl();
(this.bindingSource1)).BeginInit();
(this.performanceCounter1)).BeginInit();
(this.timer1)).BeginInit();
(this.numericUpDown1)).BeginInit();
this.groupBox1.SuspendLayout();
this.groupBox2.SuspendLayout();
//
// performanceCounter1
//
this.performanceCounter1.CategoryName = ".NET CLR Memory";
this.performanceCounter1.CounterName = "Gen 0 heap size";
this.performanceCounter1.InstanceName = "_Global_";
//
// startButton
//
this.startButton.Location = new System.Drawing.Point(31, 25);
this.startButton.Name = "startButton";
this.startButton.TabIndex = 1;
this.startButton.Text = "Start";
this.startButton.Click += new
System.EventHandler(this.startButton_Click);
//
// stopButton
//
this.stopButton.Location = new System.Drawing.Point(112, 25);
this.stopButton.Name = "stopButton";
this.stopButton.TabIndex = 2;
this.stopButton.Text = "Stop";
this.stopButton.Click += new
System.EventHandler(this.stopButton_Click);
//
// timer1
//
this.timer1.Interval = 1000;
this.timer1.SynchronizingObject = this;
this.timer1.Elapsed += new
System.Timers.ElapsedEventHandler(this.timer1_Elapsed);
//
// statusStripPanel1
//
this.statusStripPanel1.BorderStyle =
System.Windows.Forms.Border3DStyle.SunkenOuter;
this.statusStripPanel1.DisplayStyle =
System.Windows.Forms.ToolStripItemDisplayStyle.Text;
this.statusStripPanel1.Name = "statusStripPanel1";
this.statusStripPanel1.Text = "Ready";
//
// numericUpDown1
//
this.numericUpDown1.Location = new System.Drawing.Point(37, 29);
this.numericUpDown1.Maximum = new decimal(new int[] {
1410065408,
2,
0,
0});
this.numericUpDown1.Name = "numericUpDown1";
this.numericUpDown1.TabIndex = 7;
this.numericUpDown1.ValueChanged += new
System.EventHandler(this.numericUpDown1_ValueChanged);
//
// groupBox1
//
this.groupBox1.Anchor = System.Windows.Forms.AnchorStyles.None;
this.groupBox1.Controls.Add(this.numericUpDown1);
this.groupBox1.Location = new System.Drawing.Point(280, 326);
this.groupBox1.Name = "groupBox1";
this.groupBox1.Size = new System.Drawing.Size(200, 70);
this.groupBox1.TabIndex = 13;
this.groupBox1.TabStop = false;
this.groupBox1.Text = "Threshold Value";
//
// groupBox2
//
this.groupBox2.Anchor = System.Windows.Forms.AnchorStyles.None;
this.groupBox2.Controls.Add(this.startButton);
this.groupBox2.Controls.Add(this.stopButton);
this.groupBox2.Location = new System.Drawing.Point(26, 327);
this.groupBox2.Name = "groupBox2";
this.groupBox2.Size = new System.Drawing.Size(214, 68);
this.groupBox2.TabIndex = 14;
this.groupBox2.TabStop = false;
this.groupBox2.Text = "Logging";
//
//
50F));
50F));
this.tableLayoutPanel1.Controls.Add(this.groupBox2, 0, 1);
this.tableLayoutPanel1.Controls.Add(this.groupBox1, 1, 1);
this.tableLayoutPanel1.Controls.Add(this.attributesDemoControl1,
0, 0);
this.tableLayoutPanel1.Dock =
0);
this.tableLayoutPanel1.Padding = new
//
// attributesDemoControl1
//
this.tableLayoutPanel1.SetColumnSpan(this.attributesDemoControl1, 2);
this.attributesDemoControl1.DataMember = "";
this.attributesDemoControl1.DataSource = this.bindingSource1;
this.attributesDemoControl1.Dock =
this.attributesDemoControl1.Location = new
System.Drawing.Point(13, 13);
this.attributesDemoControl1.Name = "attributesDemoControl1";
this.attributesDemoControl1.Padding = new
this.attributesDemoControl1.Size = new System.Drawing.Size(488,
306);
this.attributesDemoControl1.TabIndex = 0;
this.attributesDemoControl1.Threshold = 200000F;
this.attributesDemoControl1.TitleText = "TITLE";
this.attributesDemoControl1.ThresholdExceeded += new
AttributesDemoControlLibrary.ThresholdExceededEventHandler(this.attributesDe
moControl1_ThresholdExceeded);
//
// Form1
//
this.BackColor = System.Drawing.SystemColors.Control;
this.Font = new System.Drawing.Font("Microsoft Sans Serif",
8.25F, System.Drawing.FontStyle.Regular, System.Drawing.GraphicsUnit.Point,
((byte)(0)));
(this.bindingSource1)).EndInit();
(this.performanceCounter1)).EndInit();
(this.timer1)).EndInit();
(this.numericUpDown1)).EndInit();
this.groupBox1.ResumeLayout(false);
this.groupBox2.ResumeLayout(false);
}
}
}
O primeiro exemplo de código é a implementação AttributesDemoControl . O segundo

exemplo de código demonstra um formulário que usa o AttributesDemoControl .
Atributos de nível de classe

Alguns atributos são aplicados no nível de classe. O exemplo de código a seguir mostra
os atributos que normalmente são aplicados a um controle do Windows Forms.
C#
// This control demonstrates a simple logging capability.

[ComplexBindingProperties("DataSource", "DataMember")]
[DefaultBindingProperty("TitleText")]
[DefaultEvent("ThresholdExceeded")]
[DefaultProperty("Threshold")]
[HelpKeywordAttribute(typeof(UserControl))]
[ToolboxItem("System.Windows.Forms.Design.AutoSizeToolboxItem,System.Design"
)]
public class AttributesDemoControl : UserControl
{
Atributo TypeConverter
TypeConverterAttribute é outro atributo de nível de classe comumente usado. O
exemplo de código a seguir mostra seu uso para a classe LogEntry . Este exemplo
também mostra uma implementação de um TypeConverter para o LogEntry tipo,
chamado LogEntryTypeConverter .
C#
// This class encapsulates a log entry. It is a parameterized

// type (also known as a template class). The parameter type T
// defines the type of data being logged. For threshold detection
// to work, this type must implement the IComparable interface.
[TypeConverter("LogEntryTypeConverter")]
public class LogEntry<T> where T : IComparable
{
private T entryValue;
private DateTime entryTimeValue;
public LogEntry(
T value,
DateTime time)
{
this.entryValue = value;
this.entryTimeValue = time;
}
public T Entry
{
get
{
return this.entryValue;
}
}
public DateTime EntryTime

{
get
{
return this.entryTimeValue;
}
}
// This is the TypeConverter for the LogEntry class.

public class LogEntryTypeConverter : TypeConverter
{
public override bool CanConvertFrom(
Type sourceType)
{
if (sourceType == typeof(string))
{
return true;
}
return base.CanConvertFrom(context, sourceType);

}
public override object ConvertFrom(

object value)
{
if (value is string)
{
string[] v = ((string)value).Split(new char[] { '|' });
Type paramType = typeof(T);

T entryValue = (T)paramType.InvokeMember(
"Parse",
BindingFlags.Static | BindingFlags.Public |
null,
null,
new string[] { v[0] },
culture);
return new LogEntry<T>(

entryValue,
DateTime.Parse(v[2]));
}
return base.ConvertFrom(context, culture, value);

}
public override object ConvertTo(

object value,
Type destinationType)
{
if (destinationType == typeof(string))
{
LogEntry<T> le = value as LogEntry<T>;
string stringRepresentation =
String.Format("{0} | {1}",
le.Entry,
le.EntryTime);
return stringRepresentation;
}
return base.ConvertTo(context, culture, value, destinationType);

}
}
}
Atributos de nível de membro

Alguns atributos são aplicados no nível do membro. O exemplo de código a seguir
mostra alguns atributos que normalmente são aplicados às propriedades de controles
do Windows Forms.
C#
[Description("The title of the log data.")]
[DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)]
[Localizable(true)]
[HelpKeywordAttribute("AttributesDemoControlLibrary.AttributesDemoControl.Ti
tleText")]
public string TitleText
{
get
{
return this.label1.Text;
}
set
{
this.label1.Text = value;
}
}
Atributo AmbientValue
O exemplo a seguir demonstra o e mostra o AmbientValueAttribute código que dá
suporte à sua interação com o ambiente de design. Essa interação é chamada ambiente.
C#
[DefaultValue(typeof(Color), "White")]
[Description("The color used for painting alert text.")]
public Color AlertForeColor
{
get
{
if (this.alertForeColorValue == Color.Empty &&
{
return Parent.ForeColor;
}
return this.alertForeColorValue;
}
set
{
this.alertForeColorValue = value;
}
}

public void ResetAlertForeColor()
{
this.AlertForeColor = AttributesDemoControl.defaultAlertForeColorValue;
}

private bool ShouldSerializeAlertForeColor()
{
return (this.alertForeColorValue !=
}
Atributos de associação de dados

Os exemplos a seguir demonstram uma implementação da associação de dados
complexos. O nível ComplexBindingPropertiesAttributede classe , mostrado
anteriormente, especifica as DataSource propriedades e DataMember a serem usadas
para associação de dados. O AttributeProviderAttribute especifica o tipo ao qual a
DataSource propriedade será associada.
C#
[Category("Data")]
[Description("Indicates the source of data for the control.")]
[RefreshProperties(RefreshProperties.Repaint)]
[AttributeProvider(typeof(IListSource))]
public object DataSource
{
get
{
return this.dataGridView1.DataSource;
}
set
{
this.dataGridView1.DataSource = value;
}
}
C#
[Category("Data")]
[Description("Indicates a sub-list of the data source to show in the
control.")]
public string DataMember
{
get
{
return this.dataGridView1.DataMember;
}
set
{
this.dataGridView1.DataMember = value;
}
}
O formulário que hospeda o AttributesDemoControl requer uma referência ao
assembly AttributesDemoControl para compilar.
Confira também
IComparable
DataGridView
Framework
Como serializar coleções de tipos padrão com
Pintura e renderização de controle
personalizada
Artigo • 02/06/2023
A pintura personalizada de controles é uma das muitas tarefas complicadas que são
facilitadas pelo .NET Framework. Ao criar um controle personalizado, você tem muitas
opções em relação à aparência gráfica dele. Ao criar um controle que herda de Control ,
você deverá fornecer o código que permite ao controle renderizar sua representação
gráfica. Ao criar um controle de usuário herdando de UserControl ou herdando de um
dos controles dos Windows Forms, você pode substituir a representação gráfica padrão
e fornecer seu próprio código de elementos gráficos. Se você deseja fornecer
renderização personalizada para os controles membros de um UserControl que você
está criando, suas opções tornam-se mais limitadas, mas ainda proporcionam uma
ampla gama de possibilidades gráficas para seus aplicativos e controles.
Nesta seção
Renderizando um controle dos Windows Forms
Mostra como programar a lógica que exibe um controle.
Controles desenhados pelo usuário

Fornece uma visão geral das etapas necessárias para escrever e substituir um código de
renderização para o seu controle.
Controles constituintes
Descreve como implementar o código de renderização personalizada para controles
membros em seus formulários e controles de usuário.
Como: Deixar o controle invisível em tempo de execução

Mostra como usar a Visible propriedade para ocultar e mostrar um controle.
Como: Dar ao controle um segundo plano transparente

Mostra como usar o SetStyle método para criar uma cor de tela de fundo opaca,
transparente ou parcialmente transparente.
Renderizando controles com estilos visuais

Mostra como renderizar controles com estilos visuais em sistemas operacionais que dão
suporte a eles.
Referência
Control
UserControl
OnPaint
Descreve esse método.
Como: criar objetos gráficos para desenho
Apresenta a funcionalidade de elementos gráficos GDI+ de uma perspectiva do Visual
Studio e fornece links para mais informações.

Descreve os tipos de controles personalizados que você pode criar.
Renderizando um controle dos
Windows Forms
Artigo • 21/06/2023
Renderização se refere ao processo de criar uma representação visual na tela do usuário.

Windows Forms usa GDI (a nova biblioteca de elementos gráficos do Windows) para
renderização. As classes gerenciadas que fornecem acesso ao GDI estão no
System.Drawing namespace e em seus subnamespaces.
Os elementos a seguir estão envolvidos na renderização de controles:
A funcionalidade de desenho fornecida pela classe

System.Windows.Forms.Controlbase .
Os elementos essenciais da biblioteca de elementos gráficos GDI.
A geometria da região de desenho.
O procedimento para liberar recursos gráficos.
Funcionalidade de desenho fornecida pelo

controle
A classe Control base fornece funcionalidade de desenho por meio de seu Paint evento.
Um controle aciona o Paint evento sempre que precisa atualizar sua exibição. Para obter
mais informações sobre os eventos no .NET Framework, consulte Tratando e gerando
eventos.
A classe de dados de evento para o Paint evento, PaintEventArgs, contém os dados

necessários para desenhar um controle — um identificador para um objeto gráfico e um
objeto retângulo que representa a região na qual desenhar. Esses objetos são
mostrados em negrito no seguinte fragmento de código.
C#
public class PaintEventArgs : EventArgs, IDisposable {

public System.Drawing.Rectangle ClipRectangle {get;}
public System.Drawing.Graphics Graphics {get;}
// Other properties and methods.
...
}
Graphics é uma classe gerenciada que encapsula a funcionalidade de desenho,
conforme descrito na discussão da GDI mais adiante neste tópico. O ClipRectangle é
uma instância da Rectangle estrutura e define a área disponível na qual um controle
pode desenhar. Um desenvolvedor de controle pode calcular o ClipRectangle usando a
ClipRectangle propriedade de um controle, conforme descrito na discussão sobre
geometria mais adiante neste tópico.
Um controle deve fornecer lógica de renderização substituindo o OnPaint método

herdado de Control. OnPaint obtém acesso a um objeto gráfico e um retângulo para
desenhar por meio do Graphics e as ClipRectangle propriedades da PaintEventArgs
instância passadas para ele.
C#
protected virtual void OnPaint(PaintEventArgs pe);
O OnPaint método da classe base Control não implementa nenhuma funcionalidade de

desenho, mas apenas invoca os delegados de evento registrados com o Paint evento.
Ao substituir OnPaint, você normalmente deve invocar o OnPaint método da classe base
para que os delegados registrados recebam o Paint evento. No entanto, os controles
que pintam toda a superfície não devem invocar o da OnPaintclasse base, pois isso
introduz cintilação. Para obter um exemplo de substituição do evento, consulte Como
criar um controle de Windows Forms que mostra o OnPaint progresso.
７ Observação
Não invoque OnPaint diretamente do controle; em vez disso, invoque o Invalidate

método (herdado de Control) ou algum outro método que invoque Invalidate. O
Invalidate método, por sua vez, invoca OnPaint. O Invalidate método é
sobrecarregado e, dependendo dos argumentos fornecidos para Invalidate e , um
controle redesenha parte ou toda a área da tela.
A classe base Control define outro método útil para desenhar — o OnPaintBackground
método .
C#
protected virtual void OnPaintBackground(PaintEventArgs pevent);
OnPaintBackground pinta a tela de fundo (e, portanto, a forma) da janela e tem a

garantia de ser rápida, enquanto OnPaint pinta os detalhes e pode ser mais lento
porque solicitações de pintura individuais são combinadas em um Paint evento que
cobre todas as áreas que precisam ser redesenhadas. Talvez você queira invocar o
OnPaintBackground se, por exemplo, quiser desenhar uma tela de fundo colorida de
gradiente para o controle.
Embora OnPaintBackground tenha uma nomenclatura semelhante a um evento e use o

mesmo argumento que o OnPaint método , OnPaintBackground não é um método de
evento verdadeiro. Não há nenhum PaintBackground evento e OnPaintBackground não
invoca delegados de eventos. Ao substituir o OnPaintBackground método , uma classe
derivada não é necessária para invocar o OnPaintBackground método de sua classe
base.
Noções básicas sobre a GDI+

A Graphics classe fornece métodos para desenhar várias formas, como círculos,
triângulos, arcos e reticências, bem como métodos para exibir texto. O System.Drawing
namespace e seus subnamespaces contêm classes que encapsulam elementos gráficos,
como formas (círculos, retângulos, arcos e outros), cores, fontes, pincéis e assim por
diante. Para obter mais informações sobre a GDI, consulte Usando classes gráficas
gerenciadas. Os conceitos básicos da GDI também são descritos em Como criar um
controle de Windows Forms que mostra o progresso.
Geometria da região de desenho

A ClientRectangle propriedade de um controle especifica a região retangular disponível
para o controle na tela do usuário, enquanto a ClipRectangle propriedade de
PaintEventArgs especifica a área que é realmente pintada. (Lembre-se de que a pintura é
feita no método de Paint evento que usa uma PaintEventArgs instância como seu
argumento). Um controle pode precisar pintar apenas uma parte da sua área disponível,
como é o caso quando uma pequena seção da exibição do controle é alterada. Nessas
situações, um desenvolvedor de controle deve calcular o retângulo real para desenhar e
passá-lo para Invalidate. As versões sobrecarregadas de Invalidate que usam um
Rectangle ou Region como argumento usam esse argumento para gerar a ClipRectangle
propriedade de PaintEventArgs.
O fragmento de código a seguir mostra como o controle personalizado FlashTrackBar

calcula a área retangular na qual desenhar. A client variável indica a ClipRectangle
propriedade . Para ver um exemplo completo, consulte Como criar um controle do
Windows Forms que mostre o progresso.
C#
Rectangle invalid = new Rectangle(
client.X + min,
client.Y,
max - min,
client.Height);
Invalidate(invalid);
Liberando recursos gráficos

Objetos gráficos são caros porque usam recursos do sistema. Esses objetos incluem
instâncias da System.Drawing.Graphics classe , bem como instâncias de
System.Drawing.Brush, System.Drawing.Pene outras classes gráficas. É importante que
você crie um recurso de gráfico somente quando precisar dele e o libere assim que
terminar de usá-lo. Se você criar um tipo que implementa a interface, chame seu
IDisposableDispose método quando terminar de usar para liberar recursos.
O fragmento de código a seguir mostra como o FlashTrackBar controle personalizado

cria e libera um Brush recurso. Para ver o código-fonte completo, consulte Como criar
um controle do Windows Forms que mostre o progresso.
C#
private Brush baseBackground = null;
C#
base.OnPaint(e);
if (baseBackground == null) {
if (showGradient) {
baseBackground = new LinearGradientBrush(new Point(0, 0),
new Point(ClientSize.Width,
0),
StartColor,
EndColor);
}
else if (BackgroundImage != null) {
baseBackground = new TextureBrush(BackgroundImage);
}
else {
baseBackground = new SolidBrush(BackColor);
}
}
C#
protected override void OnResize(EventArgs e) {
base.OnResize(e);
}
}
Confira também
Como: Criar um controle do Windows Forms que mostre o progresso
Artigo • 02/06/2023
O .NET Framework possibilita que você desenvolva facilmente seus próprios controles.
Você pode criar um controle de usuário, que é um conjunto de controles padrão
vinculados por código ou pode criar seu próprio controle desde o início. Você pode até
mesmo usar herança para criar um controle que herde de um controle existente e
adicionar à sua funcionalidade inerente. Independentemente da abordagem utilizada, o
.NET Framework oferece a funcionalidade de desenhar uma interface gráfica
personalizada para qualquer controle que você criar.
A pintura de um controle é realizada pela execução do código no método do OnPaint

controle. O único argumento do OnPaint método é um PaintEventArgs objeto que
fornece todas as informações e funcionalidades necessárias para renderizar o controle.
As PaintEventArgs propriedades fornecem como propriedades dois objetos principais
que serão usados na renderização do controle:
ClipRectangle objeto – o retângulo que representa a parte do controle que será

desenhada. Pode ser todo o controle ou parte do controle, dependendo de como
o controle é desenhado.
Graphics objeto – encapsula vários objetos e métodos orientados a gráficos que

fornecem a funcionalidade necessária para desenhar seu controle.
Para obter mais informações sobre o Graphics objeto e como usá-lo, consulte Como
criar objetos gráficos para desenho.
O OnPaint evento é acionado sempre que o controle é desenhado ou atualizado na tela

e o ClipRectangle objeto representa o retângulo no qual a pintura ocorrerá. Se todo o
controle precisar ser atualizado, ele ClipRectangle representará o tamanho de todo o
controle. Se apenas parte do controle precisar ser atualizada, no entanto, o
ClipRectangle objeto representará apenas a região que precisa ser redesenhada. Um
exemplo de um caso assim seria quando um controle foi parcialmente encoberto por
outro controle ou formulário na interface do usuário.
Ao herdar da Control classe, você deve substituir o OnPaint método e fornecer código
de renderização gráfica dentro. Se você quiser fornecer uma interface gráfica
personalizada para um controle de usuário ou um controle herdado, também poderá
fazer isso substituindo o OnPaint método. Um exemplo é mostrado abaixo:
C#
{
// Call the OnPaint method of the base class.
base.OnPaint(e);
// Declare and instantiate a new pen.

using (System.Drawing.Pen myPen = new System.Drawing.Pen(Color.Aqua))
{
// Draw an aqua rectangle in the rectangle represented by the control.
e.Graphics.DrawRectangle(myPen, new Rectangle(this.Location,
this.Size));
}
}
O exemplo anterior demonstra como renderizar um controle com uma representação

gráfica muito simples. Ele chama o OnPaint método da classe base, cria um Pen objeto
com o qual desenhar e, finalmente, desenha uma reticência no retângulo determinado
pelo controle e Size pelo Location controle. Embora a maioria dos códigos de
renderização seja significativamente mais complicada do que isso, este exemplo
demonstra o uso do Graphics objeto contido no PaintEventArgs objeto. Observe que, se
você estiver herdando de uma classe que já tem uma representação gráfica, como
UserControl ou Button, e não deseja incorporar essa representação à sua renderização,
não deve chamar o método da OnPaint classe base.
O código no OnPaint método do controle será executado quando o controle for

desenhado pela primeira vez e sempre que for atualizado. Para garantir que o controle
seja redesenhado sempre que ele for redimensionado, adicione a seguinte linha ao
construtor do seu controle:
C#
SetStyle(ControlStyles.ResizeRedraw, true);
７ Observação
Use a Control.Region propriedade para implementar um controle não retangular.
Confira também
Region
ControlStyles
Graphics
OnPaint
PaintEventArgs
Artigo • 02/06/2023
Os controles que compõem um controle de usuário ou controles membros como são

denominados, são relativamente inflexíveis quando se trata de renderização de
elementos gráficos personalizados. Todos os controles Windows Forms lidam com sua
própria renderização por meio de seu próprio OnPaint método. Como esse método é
protegido, ele não está acessível para o desenvolvedor e, portanto, não pode ser
impedido de ser executado quando o controle é pintado. Isso não significa, no entanto,
que não é possível adicionar código para afetar a aparência dos controles membros. A
renderização adicional pode ser realizada adicionando um manipulador de eventos. Por
exemplo, suponha que você estava criando um UserControl botão chamado MyButton .
Se você quisesse ter renderização adicional além do Buttonque foi fornecido pelo,
adicionaria código ao controle de usuário semelhante ao seguinte:
C#
// Add the event handler to the button's Paint event.

MyButton.Paint +=
new System.Windows.Forms.PaintEventHandler (this.MyPaint);
// Create the custom painting method.
protected void MyPaint (object sender,
System.Windows.Forms.PaintEventArgs e)
{
// Additional rendering code goes here.
}
７ Observação
Alguns controles Windows Forms, comoTextBox, são pintados diretamente pelo

Windows. Nessas instâncias, o OnPaint método nunca é chamado e, portanto, o
exemplo acima nunca será chamado.
Isso cria um método que é executado sempre que o evento MyButton.Paint é

executado, conferindo, assim, uma representação gráfica adicional ao controle. Observe
que isso não impede a execução de MyButton.OnPaint e, portanto, toda pintura
normalmente executada por um botão será realizada além da sua pintura personalizada.
Para obter detalhes sobre a tecnologia GDI+ e a renderização personalizada, consulte
Criando imagens gráficas com GDI+. Se desejar ter uma representação exclusiva do seu
controle, a melhor opção será criar um controle herdado e escrever código de
renderização personalizada para ele. Para ver mais detalhes, consulte Controles
desenhados pelo usuário.
Confira também
UserControl
OnPaint
Como: Deixar o controle invisível em
tempo de execução
Artigo • 02/06/2023
Há vezes em que você quer criar um controle de usuário invisível em tempo de

execução. Por exemplo, um controle que é um relógio despertador pode ser invisível,
exceto quando o alarme foi acionado. Isso é feito facilmente definindo a Visible
propriedade. Se a Visible propriedade for true , seu controle aparecerá normalmente. Se
for false , o controle será ocultado. Embora o código em seu controle ainda possa ser
executado enquanto invisível, você não poderá interagir com o controle por meio da
interface do usuário. Se quiser criar um controle invisível que ainda responde à entrada
do usuário (por exemplo, cliques de mouse), você deverá criar um controle transparente.
Para obter mais informações, veja Como dar ao controle de uma tela de fundo
transparente.
Para deixar o controle invisível em tempo de execução

1. Defina a propriedade Visible como false .
C#
// To set the Visible property from within your object's own code.
this.Visible = false;
// To set the Visible property from another object.
myControl1.Visible = false;
Confira também
Visible
Framework
Como: Dar ao controle um segundo plano transparente
Como: Dar ao controle um segundo
plano transparente
Artigo • 02/06/2023
Em versões anteriores do .NET Framework, os controles não dão suporte à configuração

de backcolores transparentes sem primeiro definir o SetStyle método no construtor dos
formulários. Na versão da estrutura atual, o backcolor para a Transparent maioria dos
controles pode ser definido como na janela Propriedades no tempo de design ou no
código no construtor do formulário.
７ Observação
Windows Forms controles não dão suporte à verdadeira transparência. A tela de

fundo de um controle de Windows Forms transparente é pintada por seu pai.
７ Observação
O Button controle não dá suporte a um backcolor transparente mesmo quando a

BackColor propriedade está definida como Transparent.
Para dar ao seu controle um backcolor transparente

No janela Propriedades, escolha a BackColor propriedade e defina-a
comoTransparent
Confira também
FromArgb
Framework
Usando classes de elementos gráficos gerenciadas
Como: desenhar linhas opacas e semitransparentes
Renderizando controles com estilos
visuais
Artigo • 21/06/2023
O .NET Framework dá suporte para renderizar controles e outros elementos da interface

do usuário do Windows usando estilos visuais em sistemas operacionais que dão
suporte a eles. Este tópico discute os vários níveis de suporte no .NET Framework para
renderizar controles e outros elementos de interface do usuário com o estilo visual atual
do sistema operacional.
Classes de renderização para controles comuns

Renderizar um controle refere-se a desenhar a interface do usuário de um controle. O
System.Windows.Forms namespace fornece a ControlPaint classe para renderizar alguns
controles de Windows Forms comuns. No entanto, essa classe desenha controles no
estilo clássico do Windows, o que pode dificultar a manutenção de uma experiência de
interface do usuário consistente ao desenhar controles personalizados em aplicativos
com os estilos visuais habilitados.
O .NET Framework 2.0 inclui classes no System.Windows.Forms namespace que

renderizam as partes e os estados de controles comuns com estilos visuais. Cada uma
dessas classes inclui métodos static para desenhar o controle ou partes do controle
em um estado específico com o estilo visual atual do sistema operacional.
Algumas dessas classes foram projetadas para desenhar o controle relacionado

independentemente de estilos visuais estarem disponíveis. Se os estilos visuais
estiverem habilitados, os membros da classe desenharão o controle relacionado com
estilos visuais. Se os estilos visuais estiverem desabilitados, os membros da classe
desenharão o controle no estilo clássico do Windows. Essas classes incluem:
ButtonRenderer
CheckBoxRenderer
GroupBoxRenderer
RadioButtonRenderer
Outras classes só podem desenhar o controle relacionado quando os estilos visuais

estiverem disponíveis e seus membros lançarão uma exceção se os estilos visuais
estiverem desabilitados. Essas classes incluem:
ComboBoxRenderer
ProgressBarRenderer
ScrollBarRenderer
TabRenderer
TextBoxRenderer
TrackBarRenderer
Para obter mais informações sobre como usar essas classes para desenhar um controle,
consulte Como usar uma classe de renderização do controle.
Elemento de estilo visual e classes de

renderização
O System.Windows.Forms.VisualStyles namespace inclui classes que podem ser usadas
para desenhar e obter informações sobre qualquer controle ou elemento de interface
do usuário compatível com estilos visuais. Os controles com suporte incluem controles
comuns que têm uma classe de renderização no System.Windows.Forms namespace
(consulte a seção anterior), bem como outros controles, como controles de tabulação e
controles de barras. Outros elementos de interface do usuário com suporte incluem as
partes do menu Iniciar, a barra de tarefas e a área não cliente do Windows.
As classes main do System.Windows.Forms.VisualStyles namespace são

VisualStyleElement e VisualStyleRenderer. VisualStyleElement é uma classe fundamental
para identificar qualquer controle ou elemento de interface do usuário com suporte por
estilos visuais. Além VisualStyleElement de si mesmo, o
System.Windows.Forms.VisualStyles namespace inclui muitas classes aninhadas de
VisualStyleElement com static propriedades que retornam um VisualStyleElement para
cada estado de um controle, parte de controle ou outro elemento de interface do
usuário com suporte por estilos visuais.
VisualStyleRenderer fornece os métodos que desenham e obtêm informações sobre

cada VisualStyleElement um definido pelo estilo visual atual do sistema operacional.
Informações que podem ser recuperadas sobre um elemento incluem seu tamanho
padrão, o tipo de tela de fundo e definições de cores. VisualStyleRendererencapsula a
funcionalidade da API de estilos visuais (UxTheme) da parte do Windows Shell do SDK
da Plataforma Windows. Para obter mais informações, consulte Habilitando estilos
visuais.
Para obter mais informações sobre como usar VisualStyleRenderer e VisualStyleElement,
consulte Como renderizar um elemento de estilo visual.
Habilitar estilos visuais

Para habilitar estilos visuais para um aplicativo escrito para o .NET Framework versão
1.0, os programadores devem incluir um manifesto do aplicativo que especifica que
ComCtl32.dll versão 6 ou posterior será usado para desenhar controles. Aplicativos
criados com o .NET Framework versão 1.1 ou posterior podem usar o
Application.EnableVisualStyles método da Application classe .
Verificando se há suporte para estilos visuais

A RenderWithVisualStyles propriedade da Application classe indica se o aplicativo atual
está desenhando controles com estilos visuais. Ao pintar um controle personalizado,
você pode marcar o valor de RenderWithVisualStyles para determinar se você deve
renderizar seu controle com ou sem estilos visuais. A tabela a seguir lista as quatro
condições que devem existir para RenderWithVisualStyles retornar true .
Condição Observações
O sistema operacional dá Para verificar essa condição separadamente, use a IsSupportedByOS

suporte a estilos visuais. propriedade da VisualStyleInformation classe .
O usuário habilitou estilos Para verificar essa condição separadamente, use a IsEnabledByUser
visuais no sistema propriedade da VisualStyleInformation classe .
operacional.
Os estilos visuais estão Os estilos visuais podem ser habilitados em um aplicativo chamando
habilitados no aplicativo. o Application.EnableVisualStyles método ou usando um manifesto
do aplicativo que especifica que ComCtl32.dll versão 6 ou posterior
será usado para desenhar controles.
Os estilos visuais estão Para verificar essa condição separadamente, use a VisualStyleState
sendo usados para propriedade da Application classe e verifique se ela tem o valor
desenhar a área de cliente VisualStyleState.ClientAreaEnabled ou
das janelas de aplicativos. VisualStyleState.ClientAndNonClientAreasEnabled.
Para determinar quando um usuário habilita ou desabilita estilos visuais ou alterna de

um estilo visual para outro, marcar para o UserPreferenceCategory.VisualStyle valor nos
manipuladores para os SystemEvents.UserPreferenceChanging eventos ou
SystemEvents.UserPreferenceChanged .
） Importante
Se você quiser usar VisualStyleRenderer para renderizar um controle ou elemento

de interface do usuário quando o usuário habilitar ou alternar estilos visuais,
certifique-se de fazer isso ao manipular o UserPreferenceChanged evento em vez
do UserPreferenceChanging evento. Uma exceção será gerada se você usar a
VisualStyleRenderer classe ao manipular UserPreferenceChanging.
Confira também
Pintura e renderização de controle personalizada
Como: Usar uma classe de renderização
do controle
Artigo • 02/06/2023
Este exemplo demonstra como usar a ComboBoxRenderer classe para renderizar a seta
suspensa de um controle de caixa de combinação. O exemplo consiste no OnPaint
método de um controle personalizado simples. A ComboBoxRenderer.IsSupported
propriedade é usada para determinar se os estilos visuais estão habilitados na área do
cliente das janelas do aplicativo. Se os estilos visuais estiverem ativos, o
ComboBoxRenderer.DrawDropDownButton método renderizará a seta suspensa com
estilos visuais; caso contrário, o ControlPaint.DrawComboButton método renderizará a
seta suspensa no estilo clássico do Windows.
Exemplo
C#
// Render the drop-down arrow with or without visual styles.

{
base.OnPaint(e);
if (!ComboBoxRenderer.IsSupported)
{
ControlPaint.DrawComboButton(e.Graphics,
this.ClientRectangle, ButtonState.Normal);
}
else
{
ComboBoxRenderer.DrawDropDownButton(e.Graphics,
this.ClientRectangle, ComboBoxState.Normal);
}
}
Um controle personalizado derivado da Control classe.
Um Form que hospeda o controle personalizado.

Referências a Systemnamespaces e System.Windows.Forms.VisualStyles
namespacesSystem.DrawingSystem.Windows.Forms.
Confira também
Como: Renderizar um elemento de
estilo visual
Artigo • 02/06/2023
O System.Windows.Forms.VisualStyles namespace expõe objetos que representam os

elementos VisualStyleElement da interface do usuário (interface do usuário) do Windows
compatíveis com estilos visuais. Este tópico demonstra como usar a VisualStyleRenderer
classe para renderizar o que representa os VisualStyleElement botões Desativar e
Desligar do menu Iniciar.
Para renderizar um elemento de estilo visual

1. Crie um VisualStyleRenderer e defina-o como o elemento que você deseja
desenhar. Observe o uso da Application.RenderWithVisualStyles propriedade e do
VisualStyleRenderer.IsElementDefined método; o VisualStyleRenderer construtor
gerará uma exceção se os estilos visuais estiverem desabilitados ou um elemento
for indefinido.
C#
private VisualStyleRenderer renderer = null;

private readonly VisualStyleElement element =
VisualStyleElement.StartPanel.LogOffButtons.Normal;
public CustomControl()
{
this.Location = new Point(50, 50);
this.BackColor = SystemColors.ActiveBorder;
if (Application.RenderWithVisualStyles &&
VisualStyleRenderer.IsElementDefined(element))
{
renderer = new VisualStyleRenderer(element);
}
}
2. Chame o DrawBackground método para renderizar o elemento que o

VisualStyleRenderer atualmente representa.
C#

{
// Draw the element if the renderer has been set.
if (renderer != null)
{
renderer.DrawBackground(e.Graphics, this.ClientRectangle);
}
// Visual styles are disabled or the element is undefined,

// so just draw a message.
else
{
this.Text = "Visual styles are disabled.";
TextRenderer.DrawText(e.Graphics, this.Text, this.Font,
new Point(0, 0), this.ForeColor);
}
}
Um controle personalizado derivado da Control classe.
Um Form que hospeda o controle personalizado.
Referências a Systemnamespaces e System.Windows.Forms.VisualStyles

namespacesSystem.DrawingSystem.Windows.Forms.
Confira também
Layout em controles dos Windows
Forms
Artigo • 02/06/2023
aplicativos. O System.Windows.Forms namespace oferece muitas ferramentas de layout
para fazer isso.
Nesta seção
Descreve a AutoSize propriedade e sua função no layout.
Margem e preenchimento em controles dos Windows Forms

Descreve as Margin propriedades e Padding suas funções no layout.
Como: Alinhar um controle às bordas de formulários

Demonstra como usar a Dock propriedade para alinhar seu controle à borda do
formulário que ocupa.
Como: Criar uma borda em torno de um controle do Windows Forms usando

preenchimento
Demonstra como usar a Padding propriedade para estruturar um controle.
Como: Implementar um mecanismo de layout personalizado

Demonstra como implementar um LayoutEngine para organizar controles Windows
Forms.
Referência
TableLayoutPanel
Fornece documentação de referência para o TableLayoutPanel controle.
FlowLayoutPanel
Fornece documentação de referência para o FlowLayoutPanel controle.
Confira também
Comportamento de AutoSize no controle TableLayoutPanel
Artigo • 02/06/2023
A AutoSize propriedade permite que um controle altere seu tamanho, se necessário,

para alcançar o valor especificado pela PreferredSize propriedade. Você ajusta o
comportamento de dimensionamento para controles específicos configurando a
propriedade AutoSizeMode .
Comportamento de AutoSize
Apenas alguns controles dão suporte à AutoSize propriedade. Além disso, alguns
controles que dão suporte à AutoSize propriedade também dão suporte à AutoSizeMode
propriedade.
A AutoSize propriedade produz um comportamento um pouco diferente, dependendo

do tipo de controle específico e do valor da AutoSizeMode propriedade, se a
propriedade existir. A tabela a seguir descreve os comportamentos que sempre são
verdadeiros e fornece uma breve descrição de cada um:
Comportamento sempre Descrição

verdadeiro
O dimensionamento automático é Isso significa que ele nunca aumenta ou diminui um

um recurso de tempo de execução. controle e, em seguida, não tem mais efeito.
Se um controle alterar o tamanho, o Quando o conteúdo de um controle faz com que ele
valor de sua Location propriedade cresça, o controle aumenta para a direita e para baixo.
sempre permanecerá constante. Controles não crescem para a esquerda.
As Dock propriedades e as Anchor O valor da propriedade do Location controle é ajustado

propriedades são honradas quando ao valor correto.
AutoSize é true .
Nota O Label controle é a exceção a essa regra. Quando
você definir o valor da propriedade de AutoSize um
controle encaixado Label como true , o Label controle não
será estendido.
Os controles MaximumSize e As MaximumSize propriedades e as MinimumSize

MinimumSize as propriedades são propriedades não são afetadas pela AutoSize
sempre honrados, propriedade.
independentemente do valor de sua
AutoSize propriedade.
Comportamento sempre Descrição
verdadeiro
Não há um tamanho mínimo Isso significa que, se um controle for definido para
definido por padrão. reduzir AutoSize e não tiver conteúdo, o valor de sua Size
propriedade será 0,0. Nesse caso, o controle será
reduzido a um ponto e não ficará visível imediatamente.
Se um controle não implementar o Isso significa que a configuração AutoSize para true não
GetPreferredSize método, o método terá efeito.
retornará o GetPreferredSizeSize
último valor atribuído à propriedade.
Um controle em uma Esse tamanho é imposto como um tamanho máximo.

TableLayoutPanel célula sempre Esse não é o caso quando a célula faz parte de uma
diminui para caber na célula até que AutoSize linha ou coluna.
ela MinimumSize seja atingida.
Propriedade AutoSizeMode
A AutoSizeMode propriedade fornece um controle mais refinado sobre o
comportamento padrão AutoSize . A propriedade AutoSizeMode especifica como um
controle dimensiona a si mesmo de acordo com seu conteúdo. O conteúdo, por
exemplo, pode ser o texto para um Button controle ou os controles filho de um
contêiner.
A tabela a seguir mostra as AutoSizeMode configurações e uma descrição do

comportamento que cada configuração provoca.
Configuração Comportamento
de
AutoSizeMode
GrowAndShrink O controle aumenta ou diminui para conter o conteúdo.
Os MinimumSize valores e os valores MaximumSize são honrados, mas o valor

atual da Size propriedade é ignorado.
Esse é o mesmo comportamento que controles com a AutoSize propriedade e

nenhuma AutoSizeMode propriedade.
GrowOnly O controle cresce tanto quanto necessário para abranger seu conteúdo, mas
não reduzirá menor que o valor especificado por sua Size propriedade.
Esse é o valor padrão de AutoSizeMode .

Controles que dão suporte à propriedade
AutoSize
A tabela a seguir lista os controles que dão suporte às propriedades e AutoSizeMode aos
AutoSize controles.
Suporte para AutoSize Tipo de controle
Suporte para a propriedade - AutoSize. CheckBox

- Nenhuma AutoSizeMode propriedade.
DomainUpDown
Label
LinkLabel
MaskedTextBox (TextBox base)
NumericUpDown
RadioButton
TextBox
TrackBar
Suporte para a propriedade - AutoSize. Button

Suporte para a propriedade - AutoSizeMode .
CheckedListBox
FlowLayoutPanel
Form
GroupBox
Panel
TableLayoutPanel
Suporte para AutoSize Tipo de controle
- Nenhuma AutoSize propriedade. CheckedListBox
ComboBox
DataGridView
DateTimePicker
ListBox
ListView
MaskedTextBox
MonthCalendar
ProgressBar
PropertyGrid
RichTextBox
SplitContainer
TabControl
TabPage
TreeView
WebBrowser
ScrollBar
AutoSize no ambiente de design

A tabela a seguir descreve o comportamento de dimensionamento de um controle em
tempo de design, com base no valor dele AutoSize e AutoSizeMode das propriedades.
Substitua a SelectionRules propriedade para determinar se um determinado controle

está em um estado redimensionável pelo usuário. Na tabela a seguir, "não pode"
significa Moveable apenas, "pode" significa AllSizeable e Moveable.
Configurações de Gesto de dimensionamento em tempo de design
AutoSize
- AutoSize = true O usuário não pode redimensionar o controle em tempo de design,

- Nenhuma AutoSizeMode exceto para os seguintes controles:
propriedade.
- TextBox
- MaskedTextBox
- RichTextBox
- TrackBar
- AutoSize = true O usuário não pode redimensionar o controle em tempo de design.

- AutoSizeMode =
GrowAndShrink
- AutoSize = true O usuário pode redimensionar o controle em tempo de design.

- AutoSizeMode = Quando a Size propriedade é definida, o usuário só pode aumentar o
GrowOnly tamanho do controle.
- AutoSize = false , ou O usuário pode redimensionar o controle em tempo de design.

AutoSize a propriedade
está oculta.
７ Observação
Para maximizar a produtividade, o designer de Windows Forms no Visual Studio

sombreia a AutoSize propriedade da Form classe. Em tempo de design, o
formulário se comporta como se a AutoSize propriedade estivesse definida como
false , independentemente de sua configuração real. Em runtime, nenhuma
acomodação especial é feita e a AutoSize propriedade é aplicada conforme

especificado pela configuração da propriedade.
Confira também
AutoSize
PreferredSize
GetPreferredSize
Como: Alinhar um controle às bordas de
formulários
Artigo • 02/06/2023
Você pode fazer com que o controle se alinhe à borda dos formulários definindo a Dock
propriedade. Essa propriedade determina onde reside o controle no formulário. A Dock
propriedade pode ser definida com os seguintes valores:
Configuração Efeito no seu controle
Bottom Encaixa na parte inferior do formulário.
Fill Preenche todo o espaço restante no formulário.
Left Encaixa do lado esquerdo do formulário.
None Não encaixa em nenhum lugar e aparece no local especificado por sua Location
propriedade.
Right Encaixa do lado direito do formulário.
Top Encaixa na parte superior do formulário.
Há suporte para tempo de design para esse recurso no Visual Studio.
Definir a propriedade Dock para o controle em

tempo de execução
Defina a Dock propriedade como o valor apropriado no código.
C#
// To set the Dock property internally.

this.Dock = DockStyle.Top;
// To set the Dock property from another object.
UserControl1.Dock = DockStyle.Top;
Confira também
Control.Dock
Control.Anchor
Framework
Margem e preenchimento em controles
dos Windows Forms
Artigo • 02/06/2023
aplicativos. O System.Windows.Forms namespace oferece muitos recursos de layout
para fazer isso. Duas das mais importantes são as propriedades e Padding as Margin
propriedades.
A Margin propriedade define o espaço em torno do controle que mantém outros

controles a uma distância especificada das bordas do controle.
A Padding propriedade define o espaço no interior de um controle que mantém o

conteúdo do controle (por exemplo, o valor de sua Text propriedade) a uma distância
especificada das bordas do controle.
A ilustração a seguir mostra as propriedades e Margin as Padding propriedades em um

controle.
Há suporte de tempo de design para esse recurso no Visual Studio. Confira também o
passo a passo: colocando controles Windows Forms com preenchimento, margens e a
propriedade AutoSize.
Confira também
AutoSize
Margin
Padding
LayoutEngine
TableLayoutPanel
FlowLayoutPanel
Como: Criar uma borda em torno de um
controle do Windows Forms usando
preenchimento
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como criar uma borda ou estrutura de tópicos
em torno de um RichTextBox controle. O exemplo define o valor da propriedade de
Padding um Panel controle como 5 e define a Dock propriedade de um controle filho
RichTextBox como Fill. O BackColor controle é definido como Blue, o Panel que cria uma
borda azul em torno do RichTextBox controle.
Exemplo
C#
using System;
namespace MarginAndPadding
{
{
private Panel panel1;
private RichTextBox richTextBox1;
/// <summary>
/// </summary>
// This code example demonstrates using the Padding property to

// create a border around a RichTextBox control.
public Form1()
{
this.panel1.BackColor = System.Drawing.Color.Blue;
this.panel1.Padding = new System.Windows.Forms.Padding(5);
this.panel1.Dock = System.Windows.Forms.DockStyle.Fill;
this.richTextBox1.BorderStyle =
System.Windows.Forms.BorderStyle.None;
this.richTextBox1.Dock = System.Windows.Forms.DockStyle.Fill;
}
/// <summary>
/// </summary>
{
{
}
}
/// <summary>
/// </summary>
{
this.panel1 = new System.Windows.Forms.Panel();
this.richTextBox1 = new System.Windows.Forms.RichTextBox();
this.panel1.SuspendLayout();
//
// panel1
//
this.panel1.Controls.Add(this.richTextBox1);
this.panel1.Location = new System.Drawing.Point(20, 20);
this.panel1.Name = "panel1";
this.panel1.Size = new System.Drawing.Size(491, 313);
this.panel1.TabIndex = 0;
//
// richTextBox1
//
this.richTextBox1.Location = new System.Drawing.Point(5, 5);
this.richTextBox1.Name = "richTextBox1";
this.richTextBox1.Size = new System.Drawing.Size(481, 303);
this.richTextBox1.TabIndex = 0;
this.richTextBox1.Text = "";
//
// Form1
//
this.Controls.Add(this.panel1);
this.panel1.ResumeLayout(false);
}
#endregion
}

{
/// <summary>
/// </summary>
[STAThread]
static void Main()
{
}
}
}
Confira também
Padding
Margem e preenchimento em controles dos Windows Forms
Como: Implementar um mecanismo de
layout personalizado
Artigo • 02/06/2023
O exemplo de código a seguir demonstra como criar um mecanismo de layout

personalizado que executa um layout de fluxo simples. Ele implementa um controle de
painel chamado DemoFlowPanel , que substitui a LayoutEngine propriedade para fornecer
uma instância da DemoFlowLayout classe.
Exemplo
C#
using System;
using System.Text;
using System.Windows.Forms.Layout;
// This class demonstrates a simple custom layout panel.

// It overrides the LayoutEngine property of the Panel
// control to provide a custom layout engine.
public class DemoFlowPanel : Panel
{
private DemoFlowLayout layoutEngine;
public DemoFlowPanel()
{
}
public override LayoutEngine LayoutEngine

{
get
{
layoutEngine ??= new DemoFlowLayout();
return layoutEngine;
}
}
}
// This class demonstrates a simple custom layout engine.

public class DemoFlowLayout : LayoutEngine
{
public override bool Layout(
object container,
LayoutEventArgs layoutEventArgs)
{
Control parent = container as Control;
// Use DisplayRectangle so that parent.Padding is honored.

Rectangle parentDisplayRectangle = parent.DisplayRectangle;
Point nextControlLocation = parentDisplayRectangle.Location;
foreach (Control c in parent.Controls)

{
// Only apply layout to visible controls.
if (!c.Visible)
{
continue;
}
// Respect the margin of the control:

// shift over the left and the top.
nextControlLocation.Offset(c.Margin.Left, c.Margin.Top);
// Set the location of the control.

c.Location = nextControlLocation;
// Set the autosized controls to their

// autosized heights.
if (c.AutoSize)
{
c.Size = c.GetPreferredSize(parentDisplayRectangle.Size);
}
// Move X back to the display rectangle origin.

nextControlLocation.X = parentDisplayRectangle.X;
// Increment Y by the height of the control

// and the bottom margin.
nextControlLocation.Y += c.Height + c.Margin.Bottom;
}
// Optional: Return whether or not the container's

// parent should perform layout as a result of this
// layout. Some layout engines return the value of
// the container's AutoSize property.
return false;
}
}
Confira também
LayoutEngine
Control.LayoutEngine
Multithread em controles dos Windows
Forms
Artigo • 02/06/2023
Em muitos aplicativos, você pode tornar sua interface do usuário mais ágil executando
operações demoradas em outro thread. Várias ferramentas estão disponíveis para
multithreading de seus controles Windows Forms, incluindo o System.Threading
namespace, o Control.BeginInvoke método e o BackgroundWorker componente.
７ Observação
O BackgroundWorker componente substitui e adiciona funcionalidade ao

namespace e ao System.ThreadingControl.BeginInvoke método; no entanto, eles
são retidos para compatibilidade com versões anteriores e uso futuro, se você
escolher. Para obter mais informações, consulte Visão Geral do Componente
BackgroundWorker.
Nesta seção
Como: Chamadas thread-safe para controles do Windows Forms
Mostra como fazer chamadas thread-safe para controles dos Windows Forms.
Como: Usar um thread em segundo plano para pesquisar arquivos

Mostra como usar o System.Threading namespace e o BeginInvoke método para
pesquisar arquivos de forma assíncrona.
Referência
BackgroundWorker
Documenta um componente que encapsula um thread de trabalho para operações
assíncronas.
LoadAsync
Documenta como carregar um som de forma assíncrona.
LoadAsync
Documenta como carregar uma imagem de forma assíncrona.
Mostra como executar uma operação demorada com o BackgroundWorker
componente.
Visão geral do componente BackgroundWorker

Fornece tópicos que descrevem como usar o BackgroundWorker componente para
operações assíncronas.
Como fazer chamadas thread-safe para
Artigo • 21/06/2023
O multithreading pode melhorar o desempenho de aplicativos Windows Forms, mas o

acesso a controles Windows Forms não é inerentemente thread-safe. O multithreading
pode expor seu código a bugs muito sérios e complexos. Dois ou mais threads que
manipulam um controle podem forçar o controle a um estado inconsistente e levar a
condições de corrida, deadlocks e congelamentos ou travamentos. Se você implementar
o multithreading em seu aplicativo, certifique-se de chamar controles entre threads de
uma maneira thread-safe. Para obter mais informações, consulte Práticas recomendadas
de threading gerenciado.
Há duas maneiras de chamar com segurança um controle Windows Forms de um thread

que não criou esse controle. Você pode usar o System.Windows.Forms.Control.Invoke
método para chamar um delegado criado no thread main, que, por sua vez, chama o
controle. Ou você pode implementar um System.ComponentModel.BackgroundWorker,
que usa um modelo controlado por eventos para separar o trabalho feito no thread em
segundo plano dos relatórios sobre os resultados.
Chamadas entre threads não seguras

Não é seguro chamar um controle diretamente de um thread que não o criou. O snippet
de código a seguir ilustra uma chamada não segura para o
System.Windows.Forms.TextBox controle. O Button1_Click manipulador de eventos cria
um novo WriteTextUnsafe thread, que define diretamente a propriedade do
TextBox.Text thread main.
C#

{
thread2 = new Thread(new ThreadStart(WriteTextUnsafe));
thread2.Start();
}
private void WriteTextUnsafe()
{
textBox1.Text = "This text was set unsafely.";
}
O depurador do Visual Studio detecta essas chamadas de thread não seguras gerando
uma InvalidOperationException com a mensagem, operação entre threads inválida.
Controle "" acessado de um thread diferente do thread no qual ele foi criado. O
InvalidOperationException sempre ocorre para chamadas entre threads não seguras
durante a depuração do Visual Studio e pode ocorrer no runtime do aplicativo. Você
deve corrigir o problema, mas pode desabilitar a exceção definindo a
Control.CheckForIllegalCrossThreadCalls propriedade como false .
Chamadas entre threads seguras

Os exemplos de código a seguir demonstram duas maneiras de chamar com segurança
um controle Windows Forms de um thread que não o criou:
1. O System.Windows.Forms.Control.Invoke método , que chama um delegado do

thread main para chamar o controle.
2. Um System.ComponentModel.BackgroundWorker componente, que oferece um
modelo controlado por eventos.
Em ambos os exemplos, o thread em segundo plano dorme por um segundo para

simular o trabalho que está sendo feito nesse thread.
Você pode criar e executar esses exemplos como aplicativos .NET Framework na linha de
comando C# ou Visual Basic. Para obter mais informações, consulte Compilação de linha
de comando com csc.exe ou Compilar a partir da linha de comando (Visual Basic).
A partir do .NET Core 3.0, você também pode compilar e executar os exemplos como
aplicativos do Windows .NET Core de uma pasta que tem um arquivo de projeto .NET
Core Windows Forms <folder name.csproj>.
Exemplo: usar o método Invoke com um

delegado
O exemplo a seguir demonstra um padrão para garantir chamadas thread-safe para um
controle Windows Forms. Ele consulta a System.Windows.Forms.Control.InvokeRequired
propriedade , que compara a criação da ID do thread do controle com a ID do thread de
chamada. Se as IDs de thread forem as mesmas, ela chamará o controle diretamente. Se
as IDs de thread forem diferentes, ela chamará o Control.Invoke método com um
delegado do thread main, que faz a chamada real para o controle.
O SafeCallDelegate habilita a TextBox definição da propriedade do Text controle. O

WriteTextSafe método consulta InvokeRequired. Se InvokeRequired retornar true ,
WriteTextSafe passará o SafeCallDelegate para o Invoke método para fazer a chamada
real para o controle. Se InvokeRequired retornar false , WriteTextSafe definirá o

TextBox.Text diretamente. O Button1_Click manipulador de eventos cria o novo thread
e executa o WriteTextSafe método .
C#
using System;
public class InvokeThreadSafeForm : Form

{
private delegate void SafeCallDelegate(string text);
private Thread thread2 = null;
[STAThread]
static void Main()
{
Application.Run(new InvokeThreadSafeForm());
}
public InvokeThreadSafeForm()
{
button1 = new Button
{
Text = "Set text safely"
};
button1.Click += new EventHandler(Button1_Click);
{
Size = new Size(240, 20)
};
}

{
thread2 = new Thread(new ThreadStart(SetText));
thread2.Start();
Thread.Sleep(1000);
}
private void WriteTextSafe(string text)

{
if (textBox1.InvokeRequired)
{
var d = new SafeCallDelegate(WriteTextSafe);
textBox1.Invoke(d, new object[] { text });
}
else
{
textBox1.Text = text;
}
}
private void SetText()

{
WriteTextSafe("This text was set safely.");
}
}
Exemplo: usar um manipulador de eventos

BackgroundWorker
Uma maneira fácil de implementar o multithreading é com o
System.ComponentModel.BackgroundWorker componente , que usa um modelo
controlado por eventos. O thread em segundo plano executa o
BackgroundWorker.DoWork evento, que não interage com o thread main. O thread
main executa os BackgroundWorker.ProgressChanged manipuladores de eventos e
BackgroundWorker.RunWorkerCompleted , que podem chamar os controles do thread
main.
Para fazer uma chamada thread-safe usando BackgroundWorker, crie um método no

thread em segundo plano para fazer o trabalho e associe-o ao DoWork evento. Crie
outro método no thread main para relatar os resultados do trabalho em segundo plano
e associá-lo ao ProgressChanged evento ou RunWorkerCompleted . Para iniciar o thread
em segundo plano, chame BackgroundWorker.RunWorkerAsync.
O exemplo usa o RunWorkerCompleted manipulador de eventos para definir a TextBox

propriedade do Text controle. Para obter um exemplo usando o ProgressChanged
evento, consulte BackgroundWorker.
C#
using System;
public class BackgroundWorkerForm : Form
{
[STAThread]
static void Main()
{
Application.Run(new BackgroundWorkerForm());
}
public BackgroundWorkerForm()
{
backgroundWorker1 = new BackgroundWorker();
backgroundWorker1.DoWork += new
DoWorkEventHandler(BackgroundWorker1_DoWork);
backgroundWorker1.RunWorkerCompleted += new
RunWorkerCompletedEventHandler(BackgroundWorker1_RunWorkerCompleted);
button1 = new Button
{
Text = "Set text safely with BackgroundWorker"
};
button1.Click += new EventHandler(Button1_Click);
{
Size = new Size(240, 20)
};
}
{
backgroundWorker1.RunWorkerAsync();
}
private void BackgroundWorker1_DoWork(object sender, DoWorkEventArgs e)

{
// Sleep 2 seconds to emulate getting data.
Thread.Sleep(2000);
e.Result = "This text was set safely by BackgroundWorker.";
}
private void BackgroundWorker1_RunWorkerCompleted(object sender,

{
textBox1.Text = e.Result.ToString();
}
}
Confira também
BackgroundWorker
Como executar uma operação em segundo plano
Como implementar um formulário que usa uma operação em segundo plano
Desenvolver controles de Windows Forms personalizados com o .NET Framework
Como: Usar um thread em segundo
plano para pesquisar arquivos
Artigo • 02/06/2023
O BackgroundWorker componente substitui e adiciona funcionalidade ao

System.Threading namespace; no entanto, o System.Threading namespace é retido para
compatibilidade com versões anteriores e uso futuro, se você escolher. Para obter mais
informações, consulte Visão Geral do Componente BackgroundWorker.
O Windows Forms usa o modelo de single-threaded apartment (STA), pois Windows

Forms é baseado em janelas nativas do Win32, que são inerentemente STA. O modelo
STA implica que uma janela pode ser criada em qualquer thread, mas ela não pode
mudar os threads já criados e todas as chamadas de função a ela devem ocorrer em seu
thread de criação. Fora do Windows Forms, as classes do .NET Framework usam o
modelo de threading livre. Para obter informações sobre threading no .NET Framework,
consulte Threading.
O modelo STA exige que qualquer método em um controle que precise ser chamado de
fora do thread de criação do controle deve realizar marshaling (ser executado no)
thread de criação do controle. A classe Control base fornece vários métodos
(BeginInvokeInvokeeEndInvoke) para essa finalidade. Invoke faz chamadas de método
síncrono; BeginInvoke faz chamadas de método assíncrono.
Se o multithreading for usado no controle em tarefas com uso intensivo de recursos, a

interface do usuário poderá permanecer responsiva enquanto uma computação com
uso intensivo de recursos é executada em um thread de tela de fundo.
O exemplo a seguir ( DirectorySearcher ) mostra um controle do Windows Forms com

multithread que usa um thread em segundo plano para pesquisar recursivamente
arquivos de um diretório que correspondam a uma cadeia de caracteres de pesquisa
especificada e, em seguida, preenche uma caixa de listagem com o resultado da
pesquisa. Os principais conceitos ilustrados pelo exemplo são os seguintes:
DirectorySearcher inicia um novo thread para executar a pesquisa. O thread
executa o método ThreadProcedure que, por sua vez, chama o método

RecurseDirectory auxiliar para fazer a pesquisa e preencher a caixa de listagem.
No entanto, preencher a caixa de listagem exige uma chamada entre threads,

conforme explicado nos próximos dois itens com marcadores.
DirectorySearcher define o método AddFiles para adicionar arquivos a uma caixa
de listagem; no entanto, RecurseDirectory não pode invocar diretamente

AddFiles , porque AddFiles pode executar somente no thread de STA que criou
DirectorySearcher .
A única maneira RecurseDirectory de chamar AddFiles é por meio de uma

chamada entre threads , ou seja, chamando Invoke ou BeginInvoke fazendo
marshal AddFiles para o thread de criação de DirectorySearcher .
RecurseDirectory usa BeginInvoke para que a chamada possa ser feita de forma
assíncrona.
O marshaling de um método requer o equivalente de um ponteiro de função ou

retorno de chamada. Isso é feito usando delegados no .NET Framework.
BeginInvoke usa um delegado como argumento. DirectorySearcher portanto,
define um delegado ( FileListDelegate ), associa AddFiles a uma instância de
FileListDelegate seu construtor e passa essa instância delegada para
BeginInvoke. DirectorySearcher também define um delegado de evento terá o
marshaling realizado quando a pesquisa for concluída.
C#
namespace Microsoft.Samples.DirectorySearcher
{
using System;
using System.IO;
/// <summary>
/// This class is a Windows Forms control that implements a simple
directory searcher.
/// You provide, through code, a search string and it will search
directories on
/// a background thread, populating its list box with matches.
/// </summary>
public class DirectorySearcher : Control
{
// Define a special delegate that handles marshaling
// lists of file names from the background directory search
// thread to the thread that contains the list box.
private delegate void FileListDelegate(string[] files, int startIndex,
int count);
private ListBox listBox;

private string searchCriteria;
private bool searching;
private bool deferSearch;
private Thread searchThread;
private FileListDelegate fileListDelegate;
private EventHandler onSearchComplete;
public DirectorySearcher()
{
listBox = new ListBox();
listBox.Dock = DockStyle.Fill;
Controls.Add(listBox);
fileListDelegate = new FileListDelegate(AddFiles);

onSearchComplete = new EventHandler(OnSearchComplete);
}
public string SearchCriteria

{
get
{
return searchCriteria;
}
set
{
// If currently searching, abort
// the search and restart it after
// setting the new criteria.
//
bool wasSearching = Searching;
if (wasSearching)
{
StopSearch();
}
listBox.Items.Clear();
searchCriteria = value;
if (wasSearching)
{
BeginSearch();
}
}
}
public bool Searching

{
get
{
return searching;
}
}
public event EventHandler SearchComplete;
/// <summary>
/// This method is called from the background thread. It is called
through
/// a BeginInvoke call so that it is always marshaled to the thread
that
/// owns the list box control.
/// </summary>
/// <param name="files"></param>
/// <param name="startIndex"></param>
/// <param name="count"></param>
private void AddFiles(string[] files, int startIndex, int count)
{
while(count-- > 0)
{
listBox.Items.Add(files[startIndex + count]);
}
}
public void BeginSearch()

{
// Create the search thread, which
// will begin the search.
// If already searching, do nothing.
//
if (Searching)
{
return;
}
// Start the search if the handle has

// been created. Otherwise, defer it until the
// handle has been created.
if (IsHandleCreated)
{
searchThread = new Thread(new ThreadStart(ThreadProcedure));
searching = true;
searchThread.Start();
}
else
{
deferSearch = true;
}
}
protected override void OnHandleDestroyed(EventArgs e)

{
// If the handle is being destroyed and you are not
// recreating it, then abort the search.
if (!RecreatingHandle)
{
StopSearch();
}
base.OnHandleDestroyed(e);
}
protected override void OnHandleCreated(EventArgs e)

{
base.OnHandleCreated(e);
if (deferSearch)
{
deferSearch = false;
BeginSearch();
}
}
/// <summary>
/// This method is called by the background thread when it has
finished
/// the search.
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void OnSearchComplete(object sender, EventArgs e)
{
if (SearchComplete != null)
{
SearchComplete(sender, e);
}
}
public void StopSearch()

{
if (!searching)
{
return;
}
if (searchThread.IsAlive)
{
searchThread.Abort();
searchThread.Join();
}
searchThread = null;
searching = false;
}
/// <summary>
/// Recurses the given path, adding all files on that path to
/// the list box. After it finishes with the files, it
/// calls itself once for each directory on the path.
/// </summary>
/// <param name="searchPath"></param>
private void RecurseDirectory(string searchPath)
{
// Split searchPath into a directory and a wildcard specification.
//
string directory = Path.GetDirectoryName(searchPath);
string search = Path.GetFileName(searchPath);
// If a directory or search criteria are not specified, then

return.
//
if (directory == null || search == null)
{
return;
}
string[] files;
// File systems like NTFS that have

// access permissions might result in exceptions
// when looking into directories without permission.
// Catch those exceptions and return.
try
{
files = Directory.GetFiles(directory, search);
}
catch(UnauthorizedAccessException)
{
return;
}
catch(DirectoryNotFoundException)
{
return;
}
// Perform a BeginInvoke call to the list box

// in order to marshal to the correct thread. It is not
// very efficient to perform this marshal once for every
// file, so batch up multiple file calls into one
// marshal invocation.
int startingIndex = 0;
while(startingIndex < files.Length)

{
// Batch up 20 files at once, unless at the
// end.
//
int count = 20;
if (count + startingIndex >= files.Length)
{
count = files.Length - startingIndex;
}
// Begin the cross-thread call. Because you are passing

// immutable objects into this invoke method, you do not have to
// wait for it to finish. If these were complex objects, you
would
// have to either create new instances of them or
// wait for the thread to process this invoke before modifying
// the objects.
IAsyncResult r = BeginInvoke(fileListDelegate, new object[]
{files, startingIndex, count});
startingIndex += count;
}
// Now that you have finished the files in this directory, recurse
for
// each subdirectory.
string[] directories = Directory.GetDirectories(directory);
foreach(string d in directories)
{
RecurseDirectory(Path.Combine(d, search));
}
}
/// <summary>
/// This is the actual thread procedure. This method runs in a
background
/// thread to scan directories. When finished, it simply exits.
/// </summary>
private void ThreadProcedure()
{
// Get the search string. Individual
// field assigns are atomic in .NET, so you do not
// need to use any thread synchronization to grab
// the string value here.
try
{
string localSearch = SearchCriteria;
// Now, search the file system.

//
RecurseDirectory(localSearch);
}
finally
{
// You are done with the search, so update.
//
searching = false;
// Raise an event that notifies the user that

// the search has terminated.
// You do not have to do this through a marshaled call, but
// marshaling is recommended for the following reason:
// Users of this control do not know that it is
// multithreaded, so they expect its events to
// come back on the same thread as the control.
BeginInvoke(onSearchComplete, new object[] {this,
EventArgs.Empty});
}
}
}
}
Usando o Controle com Multithread em um

Formulário
A exemplo a seguir mostra como o controle com multithread DirectorySearcher pode
ser usado em um formulário.
C#
namespace SampleUsage
{
using System;
using System.Data;
using Microsoft.Samples.DirectorySearcher;
/// <summary>
/// Summary description for Form1.
/// </summary>
{
private DirectorySearcher directorySearcher;
private System.Windows.Forms.TextBox searchText;
private System.Windows.Forms.Label searchLabel;
private System.Windows.Forms.Button searchButton;
public Form1()
{
//
// Required for Windows Forms designer support.
//
//
// Add any constructor code after InitializeComponent call here.
//
}

/// <summary>
/// Required method for designer support. Do not modify
/// </summary>
{
this.directorySearcher = new
Microsoft.Samples.DirectorySearcher.DirectorySearcher();
this.searchButton = new System.Windows.Forms.Button();
this.searchText = new System.Windows.Forms.TextBox();
this.searchLabel = new System.Windows.Forms.Label();
this.directorySearcher.Anchor =
(((System.Windows.Forms.AnchorStyles.Top |
| System.Windows.Forms.AnchorStyles.Right);
this.directorySearcher.Location = new System.Drawing.Point(8, 72);
this.directorySearcher.SearchCriteria = null;
this.directorySearcher.Size = new System.Drawing.Size(271, 173);
this.directorySearcher.TabIndex = 2;
this.directorySearcher.SearchComplete += new
System.EventHandler(this.directorySearcher_SearchComplete);
this.searchButton.Location = new System.Drawing.Point(8, 16);
this.searchButton.Size = new System.Drawing.Size(88, 40);
this.searchButton.TabIndex = 0;
this.searchButton.Text = "&Search";
this.searchButton.Click += new
System.EventHandler(this.searchButton_Click);
this.searchText.Anchor = ((System.Windows.Forms.AnchorStyles.Top |
System.Windows.Forms.AnchorStyles.Left)
| System.Windows.Forms.AnchorStyles.Right);
this.searchText.Location = new System.Drawing.Point(104, 24);
this.searchText.Size = new System.Drawing.Size(175, 20);
this.searchText.TabIndex = 1;
this.searchText.Text = "c:\\*.cs";
this.searchLabel.ForeColor = System.Drawing.Color.Red;
this.searchLabel.Location = new System.Drawing.Point(104, 48);
this.searchLabel.Size = new System.Drawing.Size(176, 16);
this.searchLabel.TabIndex = 3;
this.Controls.AddRange(new System.Windows.Forms.Control[]
{this.searchLabel,
this.directorySearcher,
this.searchText,
this.searchButton});
this.Text = "Search Directories";
}
#endregion
/// <summary>
/// </summary>
[STAThread]
static void Main()
{
}
private void searchButton_Click(object sender, System.EventArgs e)

{
directorySearcher.SearchCriteria = searchText.Text;
searchLabel.Text = "Searching...";
directorySearcher.BeginSearch();
}
private void directorySearcher_SearchComplete(object sender,

System.EventArgs e)
{
searchLabel.Text = string.Empty;
}
}
}
Confira também
BackgroundWorker
Framework
Controles dos Windows Forms por
função
Artigo • 02/06/2023
O Windows Forms oferece controles e componentes que executam várias funções. A

tabela a seguir lista os controles e componentes dos Windows Forms de acordo com a
função geral. Além disso, quando há vários controles que têm a mesma função, o
controle recomendado é listado com uma observação sobre o controle que foi
substituído por ele. Em uma tabela separada posterior, os controles substituídos são
listados com suas substituições recomendadas.
７ Observação
As tabelas a seguir não listam todos os controles ou componentes que você pode
usar nos Windows Forms. Para obter uma lista mais abrangente, consulte Controles
a serem usados nos Windows Forms
Controles e componentes recomendados

Exibição de Controle O DataGridView controle fornece uma tabela

dados DataGridView personalizável para exibir dados. A DataGridView classe
permite a personalização de células, linhas, colunas e
bordas. Nota: O DataGridView controle fornece vários
recursos básicos e avançados que estão ausentes no
DataGrid controle. Para obter mais informações,
consulte Diferenças entre o Windows Forms
DataGridView e os Controles do DataGrid
Vinculação de componente Simplifica a associação de controles em um formulário

dados e BindingSource a dados, fornecendo gerenciamento de moeda,
navegação notificação de alteração e outros serviços.
Controle Fornece uma interface do tipo de barra de ferramentas

BindingNavigator para navegar e manipular dados em um formulário.
Edição de texto Controle TextBox Exibe o texto inserido em tempo de design que pode
ser editado por usuários em tempo de execução ou ser
modificado programaticamente.
Controle Permite que o texto seja exibido formatado em texto

RichTextBox sem formatação ou em RTF (Formato Rich Text).
Controle Restringe o formato da entrada do usuário

MaskedTextBox
Exibição de Controle Label Exibe o texto que os usuários não podem editar
informações diretamente.
(somente
leitura)

janela ou site.
Controle StatusStrip Exibe informações sobre o estado atual do aplicativo

usando uma área com quadros, geralmente na parte
inferior de um formulário pai.
Controle Exibe o progresso atual de uma operação para o

ProgressBar usuário.
Exibição de Controle Permite ao usuário navegar em páginas da Web dentro

página da Web WebBrowser do seu formulário.
Seleção de uma Controle Exibe uma lista rolável de itens, cada um deles
lista CheckedListBox acompanhado por uma caixa de seleção.
Controle ComboBox Exibe uma lista suspensa de itens.
Controle Exibe uma lista de itens de texto que os usuários

DomainUpDown podem percorrer usando os botões para cima e para
baixo.
Controle ListBox Exibe uma lista de texto e itens gráficos (ícones).
Controle ListView Exibe os itens em um dos quatro modos de exibição

diferentes. Os modos de exibição incluem somente
texto, texto com ícones pequenos, texto com ícones
grandes e exibição de detalhes.
Controle Exibe uma lista de numerais que os usuários podem

NumericUpDown percorrer usando os botões para cima e para baixo.
Controle TreeView Exibe uma coleção hierárquica de objetos de nó que

podem consistir em texto com caixas de seleção
opcionais ou ícones.
Exibição de Controle PictureBox Exibe arquivos gráficos, como bitmaps e ícones, em um

gráficos quadro.
Armazenamento Controle ImageList Serve como um repositório de imagens. ImageList os

de gráficos controles e as imagens que eles contêm podem ser
reutilizados de um aplicativo para o próximo.
Configuração do Controle CheckBox Exibe uma caixa de seleção e um rótulo de texto.

valor Geralmente, é usado para definir opções.
Controle Exibe uma lista rolável de itens, cada um deles

CheckedListBox acompanhado por uma caixa de seleção.
Controle Exibe um botão que pode ser ativado ou desativado.

RadioButton
Controle TrackBar Permite aos usuários definir valores em uma escala

movendo um "controle de posição" ao longo da escala.
Configuração de Controle Exibe um calendário gráfico para permitir que os

data DateTimePicker usuários selecionem uma data ou hora.
Controle Exibe um calendário gráfico para permitir que os

MonthCalendar usuários selecionem um intervalo de datas.
Caixas de Controle Exibe a caixa de diálogo do seletor de cor que permite

diálogo ColorDialog que os usuários definam a cor de um elemento de
interface.
Controle FontDialog Exibe uma caixa de diálogo que permite que os

usuários definam uma fonte e seus atributos.

OpenFileDialog usuários naveguem até um arquivo e o selecionem.
Controle PrintDialog Exibe uma caixa de diálogo que permite que os

usuários selecionem uma impressora e definam seus
atributos.
Controle Exibe uma caixa de diálogo que exibe como um

PrintPreviewDialog componente de PrintDocument controle será exibido
quando impresso.

FolderBrowserDialog usuários naveguem, criem e, eventualmente,
selecionem uma pasta

SaveFileDialog usuários salvem um arquivo.
Controles de Controle MenuStrip Cria menus personalizados. Nota: O MenuStrip foi

menu projetado para substituir o MainMenu controle .
Controle Cria menus de contexto personalizados. Observação: O

ContextMenuStrip ContextMenuStrip é projetado para substituir o
ContextMenu controle.
Comandos Controle Button Inicia, para ou interrompe um processo.

janela ou site.
Controle NotifyIcon Exibe um ícone na área de notificação de status da

barra de tarefas que representa um aplicativo em
execução em segundo plano.
Controle ToolStrip Cria barras de ferramentas que podem ter a aparência

do Microsoft Windows XP, Microsoft Office, Microsoft
Internet Explorer ou uma aparência personalizada, com
ou sem temas e com suporte para estouro e
reordenação de itens em tempo de execução.
Observação: O ToolStrip controle foi projetado para
substituir o ToolBar controle.
Ajuda do componente Fornece Ajuda pop-up ou online para os controles.

usuário HelpProvider
componente ToolTip Fornece uma janela pop-up que exibe uma breve
descrição da finalidade do controle quando o usuário
deixa o ponteiro sobre o controle.
Agrupando Controle Panel Agrupa um conjunto de controles em um quadro

outros controles rolável sem rótulo.
Controle GroupBox Agrupa um conjunto de controles (como botões de

opção) em um quadro não rolável rotulado.
Controle TabControl Fornece uma página com guias para organizar e

acessar objetos agrupados com eficiência.
Controle Fornece dois painéis separados por uma barra móvel.

SplitContainer Observação: O SplitContainer controle foi projetado
para substituir o Splitter controle.

TableLayoutPanel conteúdo em uma grade composta por linhas e
colunas.

FlowLayoutPanel conteúdo horizontal ou verticalmente.
Áudio Controle Reproduz arquivos de som no formato .wav. Os sons

SoundPlayer podem ser carregados ou executados de forma
assíncrona.
Controles e componentes substituídos por

função
Função Controle Substituição
substituído recomendada
Exibição de dados DataGrid DataGridView
Exibição de informações (controles somente StatusBar StatusStrip

leitura)
Controles de menu ContextMenu ContextMenuStrip
MainMenu MenuStrip
Comandos ToolBar ToolStrip
StatusBar StatusStrip
Layout de formulários Splitter SplitContainer
Confira também
Framework
Desenvolver controles Windows Forms
em tempo de design
Artigo • 02/06/2023
Para autores de controle, o .NET Framework fornece uma ampla variedade de tecnologia
de criação de controle. Os autores não estão mais limitados a criar controles de
composição que atuam como uma coleção de controles preexistentes. Por meio de
herança, você pode criar seus próprios controles de com base em controles de
composição preexistentes ou controles dos Windows Forms preexistentes. Você
também pode criar seus próprios controles que implementam pintura personalizada.
Essas opções possibilitam muita flexibilidade no design e a funcionalidade da interface
visual. Para aproveitar esses recursos, familiarize-se com os conceitos de programação
baseada em objeto.
７ Observação
Não é necessário ter uma compreensão completa da herança, mas você pode achar
útil se referir aos conceitos básicos de herança (Visual Basic).
Caso queira criar controles personalizados para usar em Web Forms, consulte
Desenvolvendo Controles Personalizados ASP.NET Server.
Nesta seção
Mostra como criar um controle de composição simples em C#.

Mostra como criar um controle simples dos Windows Forms usando herança em C#.
Passo a passo: executar tarefas comuns usando ações de designer

Mostra como usar o recurso de smart tag em controles dos Windows Forms.

Mostra como usar o DesignerSerializationVisibilityAttribute.Content atributo para
serializar uma coleção.
Passo a passo: depurando controles personalizados dos Windows Forms em tempo de

Design
Mostra como depurar o comportamento de tempo de design de um controle dos
Windows Forms.
Passo a passo: criando um controle de Windows Forms que aproveita os recursos de

Design-Time do Visual Studio
Mostra como integrar fortemente um controle de composição ao ambiente de design.

Apresenta uma visão geral de considerações para implementar um controle dos
Windows Forms.

Mostra como criar um controle herdando de um controle de composição.

Fornece uma visão geral do procedimento para criar um controle de composição.

Mostra como criar um controle estendido herdando da Button classe de controle.

Apresenta uma visão geral da criação de um controle estendido.

Mostra como usar a Dock propriedade para alinhar seu controle à borda do formulário
que ocupa.
Como exibir um controle na caixa de diálogo Escolher Itens da Caixa de Ferramentas

Mostra o procedimento para instalar seu controle de modo que ele apareça na caixa de
diálogo Personalizar caixa de ferramentas.

Mostra como usar o ToolboxBitmapAttribute para exibir um ícone ao lado do controle
personalizado na Caixa de Ferramentas.

Mostra como usar o Contêiner de Teste UserControl para testar o comportamento de
um controle de composição.
Erros de tempo de design no Designer de Formulários do Windows

Explica o significado e o uso da lista de erros de tempo de design que aparece no
Microsoft Visual Studio quando o carregamento do Designer de Formulários do
Windows falha.
Solução de problemas de criação de controle e de componente
Mostra como diagnosticar e corrigir problemas comuns que podem ocorrer quando
você criar um controle ou componente personalizado.
Referência
System.Windows.Forms.Control
System.Windows.Forms.UserControl
Desenvolvendo controles dos Windows Forms personalizados com o .NET Framework
Discute como criar seus próprios controles personalizados com o .NET Framework.
Independência da linguagem e componentes independentes da linguagem

Apresenta o Common Language Runtime, que foi projetado para simplificar a criação e
uso de componentes. Um aspecto importante dessa simplificação é melhor
interoperabilidade entre componentes escritos usando diferentes linguagens de
programação. A CLS (Common Language Specification) possibilita criar ferramentas e
componentes que funcionam com várias linguagens de programação.

Descreve como habilitar seu componente ou controle para ser exibido na caixa de
diálogo Personalizar Caixa de Ferramentas.
Passo a passo: criar um controle
composto com C #
Artigo • 02/06/2023
Os controles de composição fornecem um meio pelo qual as interfaces gráficas

personalizadas podem ser criadas e reutilizadas. Basicamente, um controle de
composição é um componente com uma representação visual. Assim, ele pode consistir
em um ou mais controles, componentes ou blocos de código dos Windows Forms que
podem estender a funcionalidade ao validar a entrada do usuário, modificar
propriedades de exibição ou executar outras tarefas exigidas pelo autor. Os controles de
composição podem ser colocados nos Windows Forms da mesma maneira que outros
controles. Na primeira parte deste passo a passo, você cria um controle de composição
simples chamado ctlClock . Na segunda parte do passo a passo, você estende a
funcionalidade de ctlClock por meio da herança.
Criar o projeto
Ao criar um novo projeto, você especifica seu nome para definir o namespace raiz, o
nome do assembly e o nome do projeto e garante que o componente padrão estará no
namespace correto.
Para criar a biblioteca de controles de ctlClockLib e o

controle ctlClock
1. No Visual Studio, crie um novo projeto da Biblioteca de Controle Windows Forms
e nomeie-o ctlClockLib.
O nome do projeto, ctlClockLib , também é atribuído ao namespace raiz por

padrão. O namespace raiz é usado para qualificar os nomes dos componentes no
assembly. Por exemplo, se dois assemblies fornecem componentes chamados
ctlClock , será possível especificar o componente ctlClock usando
ctlClockLib.ctlClock.
2. Em Gerenciador de Soluções, clique com o botão direito do mouse em

UserControl1.cs e clique em Renomear. Altere o nome de arquivo para
ctlClock.cs . Clique no botão Sim quando for perguntado se deseja renomear
todas as referências ao elemento de código "UserControl1".

７ Observação
Por padrão, um controle composto herda da UserControl classe fornecida

pelo sistema. A UserControl classe fornece a funcionalidade exigida por todos
os controles compostos e implementa métodos e propriedades padrão.
3. No menu Arquivo, clique em Salvar Tudo para salvar o projeto.
Adicionar controles e componentes do

Windows ao controle composto
Uma interface visual é uma parte essencial do controle de composição. Essa interface
visual é implementada pela adição de um ou mais controles do Windows à superfície do
designer. Na demonstração a seguir, você incorporará controles do Windows no
controle de composição e escreverá um código para implementar a funcionalidade.
Para adicionar um Rótulo e um Temporizador ao controle

de composição
1. Em Gerenciador de Soluções, clique com o botão direito do mouse em ctlClock.cs
e clique em Exibir Designer.
2. Na Caixa de Ferramentas, expanda o nó Controles Comuns e clique duas vezes

em Rótulo.
Um Label controle nomeado label1 é adicionado ao controle na superfície do

designer.
3. No designer, clique em label1. Na janela Propriedades, defina as propriedades a

seguir.
Propriedade Altere para
Nome lblDisplay
Texto (blank space)
TextAlign MiddleCenter
Font.Size 14
4. Na Caixa de Ferramentas, expanda o nó Componentes e clique duas vezes em
Temporizador.
Como é um Timer componente, ele não tem representação visual em tempo de

execução. Portanto, ele não aparece com os controles na superfície do designer,
mas sim no Designer de Componentes (uma bandeja na parte inferior da
superfície do designer).
5. No Designer de Componentes, clique em temporizador1 e defina a Interval

propriedade como 1000 . true Enabled
A Interval propriedade controla a frequência com que o Timer componente marca.

A cada tique de timer1 , ele executa o código no evento timer1_Tick . O intervalo
representa o número de milissegundos entre os tiques.
6. No Designer de Componentes, clique duas vezes no temporizador1 para ir ao

timer1_Tick evento para ctlClock .
7. Modifique o código para que ele fique parecido com o exemplo de código a
seguir. Lembre-se de alterar o modificador de acesso de private para protected .
C#
protected void timer1_Tick(object sender, System.EventArgs e)

{
// Causes the label to display the current time.
lblDisplay.Text = DateTime.Now.ToLongTimeString();
}
Esse código fará com que a hora atual seja mostrada em lblDisplay . Como o
intervalo de timer1 foi definido como 1000 , esse evento ocorrerá a cada vários
milhares de milissegundos, atualizando a hora atual a cada segundo.
8. Modifique o método para que ele seja substituível pela palavra-chave virtual .
Para obter mais informações, consulte a seção “Herdando de um controle de
usuário” abaixo.
C#
protected virtual void timer1_Tick(object sender, System.EventArgs e)

Adicionar propriedades ao controle composto
Agora, o controle do relógio encapsula um Label controle e um componente, cada um
Timer com seu próprio conjunto de propriedades inerentes. Embora as propriedades
individuais desses controles não estejam acessíveis aos próximos usuários do controle,
você poderá criar e expor propriedades personalizadas, escrevendo os blocos de código
apropriados. No procedimento a seguir, você adicionará propriedades ao controle que
permitem ao usuário alterar a cor da tela de fundo e do texto.
Para adicionar uma propriedade ao controle de

composição
1. Em Gerenciador de Soluções, clique com o botão direito do mouse em ctlClock.cs
e clique em Exibir Código.
O Editor de Código do controle é aberto.
2. Localize a instrução public partial class ctlClock . Sob a chave de abertura ( {) ,

digite o código a seguir.
C#
private Color colFColor;

private Color colBColor;
Essas instruções criam as variáveis particulares que você usará para armazenar os
valores para as propriedades que está prestes a criar.
3. Insira ou cole o código a seguir abaixo das declarações de variável da etapa 2.
C#
// Declares the name and type of the property.

public Color ClockBackColor
{
// Retrieves the value of the private variable colBColor.
get
{
return colBColor;
}
// Stores the selected value in the private variable colBColor, and
// updates the background color of the label control lblDisplay.
set
{
colBColor = value;
lblDisplay.BackColor = colBColor;
}
}
// Provides a similar set of instructions for the foreground color.
public Color ClockForeColor
{
get
{
return colFColor;
}
set
{
colFColor = value;
lblDisplay.ForeColor = colFColor;
}
}
O código anterior cria duas propriedades personalizadas, ClockForeColor e

ClockBackColor , disponíveis para os próximos usuários desse controle. As
instruções get e set fornecem armazenamento e recuperação do valor da

propriedade, bem como o código para implementar a funcionalidade apropriada
para a propriedade.
Testar o controle
Controles não são aplicativos autônomos; eles devem ser hospedados em um contêiner.
Teste o comportamento do tempo de execução do controle e exerça suas propriedades
com o Contêiner de Teste de UserControl. Para obter mais informações, consulte Como
testar o comportamento em tempo de execução de um UserControl.
Para testar o controle

1. Pressione F5 para criar o projeto e executar seu controle no Contêiner de Teste
usercontrol.
2. Na grade de propriedades do contêiner de teste, localize a propriedade

ClockBackColor e, em seguida, selecione a propriedade para exibir a paleta de
cores.
3. Escolha uma cor clicando nela.
A cor da tela de fundo do controle é alterada para a cor selecionada.

4. Use uma sequência semelhante de eventos para verificar se a propriedade
ClockForeColor está funcionando como esperado.
Nesta seção e nas seções anteriores, você viu como os componentes e controles
do Windows podem ser combinados com um código e empacotamento para
fornecer funcionalidade personalizada na forma de um controle de composição.
Você aprendeu a expor as propriedades no controle de composição e a testar o
controle após sua conclusão. Na próxima seção, você aprenderá a construir um
controle de composição herdado usando ctlClock como base.
Herdar de um controle composto

Nas seções anteriores, você aprendeu a combinar controles, componentes e código do
Windows em controles de composição reutilizáveis. O controle de composição agora
pode ser usado como base para a criação de outros controles. O processo de derivação
de classe de uma classe base é chamado herança. Nesta seção, você criará um controle
de composição chamado ctlAlarmClock . Esse controle será derivado de seu controle
pai, ctlClock . Você aprenderá a estender a funcionalidade de ctlClock , substituindo
métodos pai e adicionando novos métodos e novas propriedades.
A primeira etapa na criação de um controle herdado é derivá-lo de seu pai. Essa ação
cria um novo controle que tem todas as propriedades, métodos e características gráficas
do controle pai, mas que também pode atuar como uma base para a adição de uma
funcionalidade nova ou modificada.
Para criar o controle herdado

ctlClockLib, aponte para Adicionar e clique em Controle de Usuário.
A caixa de diálogo Adicionar Novo Item é aberta.
2. Selecione o modelo Controle de Usuário Herdado.
3. Na caixa Nome, digite ctlAlarmClock.cs e clique em Adicionar.
A caixa de diálogo Seletor de Herança é exibida.
4. Em Nome do Componente, clique duas vezes em ctlClock.
5. Em Gerenciador de Soluções, navegue pelos projetos atuais.

７ Observação
Um arquivo chamado ctlAlarmClock.cs foi adicionado ao projeto atual.
Adicionar as propriedades do alarme

As propriedades são adicionadas a um controle herdado da mesma forma que são
adicionadas a um controle de composição. Agora você usará a sintaxe de declaração de
propriedade para adicionar duas propriedades ao controle: AlarmTime , que armazenará
o valor de data e hora em que o alarme será acionado e AlarmSet , que indicará se o
alarme está definido.
Para adicionar propriedades ao controle de composição

ctlAlarmClock e clique em Exibir Código.
2. Localize a instrução public class . Observe que o controle herda de

ctlClockLib.ctlClock . Sob a chave de abertura (instrução {) , digite o código a
seguir.
C#
private DateTime dteAlarmTime;

private bool blnAlarmSet;
// These properties will be declared as public to allow future
// developers to access them.
public DateTime AlarmTime
{
get
{
return dteAlarmTime;
}
set
{
dteAlarmTime = value;
}
}
public bool AlarmSet
{
get
{
return blnAlarmSet;
}
set
{
blnAlarmSet = value;
}
}
Adicionar à interface gráfica do controle

O controle herdado tem uma interface visual que é idêntica ao controle do qual ele é
herdado. Ele contém os mesmos controles constituintes que seu controle pai, mas as
propriedades dos controles constituintes só estarão disponíveis se forem
especificamente expostas. Você pode fazer adições à interface gráfica de um controle de
composição herdado da mesma maneira como faria com qualquer controle de
composição. Para continuar fazendo adições à interface visual do despertador, você
adicionará um controle de rótulo que piscará quando o alarme estiver soando.
Para adicionar o controle de rótulo

ctlAlarmClock e clique em Exibir Designer.
O designer de ctlAlarmClock é aberto na janela principal.
2. Clique na parte de exibição do controle e exiba a janela Propriedades.
７ Observação
Embora todas as propriedades sejam exibidas, elas ficam esmaecidas. Isso

indica que essas propriedades são nativas de lblDisplay e não podem ser
modificadas nem acessadas na janela Propriedades. Por padrão, os controles
contidos em um controle de composição são private e suas propriedades
não são acessíveis por nenhum meio.
７ Observação
Se você desejar que os próximos usuários do controle de composição tenham

acesso a seus controles internos, declare-os como public ou protected . Isso
permitirá definir e modificar as propriedades de controles contidos no
controle de composição usando o código apropriado.
3. Adicione um Label controle ao controle composto.

4. Usando o mouse, arraste o Label controle imediatamente abaixo da caixa de
exibição. Na janela Propriedades, defina as propriedades a seguir.
Propriedade Configuração
Nome lblAlarm
Texto Alarme!
TextAlign MiddleCenter
Visível false
Adicionar a Funcionalidade de Alarme

Nos procedimentos anteriores, você adicionou propriedades e um controle que
habilitarão a funcionalidade de alarme do controle de composição. Neste procedimento,
você adicionará um código para comparar a hora atual com a hora do alarme e, se
forem iguais, elas piscarão um alarme. Ao substituir o método timer1_Tick de ctlClock
e adicionar um código adicional a ele, você estenderá a funcionalidade de
ctlAlarmClock ao mesmo tempo que reterá todas as funcionalidades inerentes de
ctlClock .
Para substituir o método timer1_Tick de ctlClock
1. No Editor de códigos, localize a instrução private bool blnAlarmSet; .

Imediatamente abaixo dela, adicione a instrução a seguir.
C#
private bool blnColorTicker;
2. No Editor de códigos, localize a chave de fechamento ( }) no final da classe. Antes

da chave, adicione o código a seguir.
C#
protected override void timer1_Tick(object sender, System.EventArgs e)

{
// Calls the Timer1_Tick method of ctlClock.
base.timer1_Tick(sender, e);
// Checks to see if the alarm is set.
if (AlarmSet == false)
return;
else
// If the date, hour, and minute of the alarm time are the same
as
// the current time, flash an alarm.
{
if (AlarmTime.Date == DateTime.Now.Date && AlarmTime.Hour ==
DateTime.Now.Hour && AlarmTime.Minute ==
DateTime.Now.Minute)
{
// Sets lblAlarmVisible to true, and changes the background
color based on
// the value of blnColorTicker. The background color of the
label
// will flash once per tick of the clock.
lblAlarm.Visible = true;
if (blnColorTicker == false)
{
lblAlarm.BackColor = Color.Red;
blnColorTicker = true;
}
else
{
lblAlarm.BackColor = Color.Blue;
blnColorTicker = false;
}
}
else
{
// Once the alarm has sounded for a minute, the label is
made
// invisible again.
lblAlarm.Visible = false;
}
}
}
A adição desse código realiza várias tarefas. A instrução override direciona o

controle a usar esse método em vez do método herdado do controle base.
Quando esse método é chamado, ele chama o método que substitui ao invocar a
instrução base.timer1_Tick , garantindo que toda a funcionalidade incorporada no
controle original seja reproduzida nesse controle. Em seguida, ele executa um
código adicional para incorporar a funcionalidade de alarme. Um controle de
rótulo intermitente será exibido quando o alarme for acionado.
O controle do despertador está quase concluído. A única coisa que resta é

implementar uma maneira de desligá-lo. Para fazer isso, você adicionará um
código ao método lblAlarm_Click .
Para implementar o método de desligamento

ctlAlarmClock.cs e clique em Exibir Designer.
O designer será aberto.
2. Adicione um botão no controle. Defina as propriedades do botão da seguinte

maneira.
Propriedade Valor
Nome btnAlarmOff
Texto Desabilitar o alarme
3. No designer, clique duas vezes em btnAlarmOff.
O Editor de Código é aberto na linha private void btnAlarmOff_Click .
4. Modifique esse método para que ele fique parecido com o código a seguir.
C#
private void btnAlarmOff_Click(object sender, System.EventArgs e)

{
// Turns off the alarm.
AlarmSet = false;
// Hides the flashing label.
lblAlarm.Visible = false;
}
Usar o controle herdado em um formulário

Você pode testar seu controle herdado da mesma forma que testou o controle de classe
base: ctlClock pressione F5 para compilar o projeto e executar seu controle no
Contêiner de Teste UserControl. Para obter mais informações, consulte Como testar o
comportamento em tempo de execução de um UserControl.
Para colocar o controle em funcionamento, você precisará hospedá-lo em um

formulário. Assim como ocorre com um controle de composição padrão, um controle de
composição herdado não pode ser autônomo e deve ser hospedado em um formulário
ou em outro contêiner. Já que ctlAlarmClock tem uma profundidade maior de
funcionalidade, um código adicional é necessário para testá-lo. Neste procedimento,
você escreverá um programa simples para testar a funcionalidade de ctlAlarmClock .
Você escreverá um código para definir e exibir a propriedade AlarmTime de
ctlAlarmClock e testará suas funções inerentes.
Para criar e adicionar o controle a um formulário de teste
1. Em Gerenciador de Soluções, clique com o botão direito do mouse em ctlClockLib

e clique em Compilar.
2. Adicione um novo projeto de aplicativo Windows Forms à solução e nomeie-o

como Teste.
3. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó

Referências do projeto de teste. Clique em Adicionar referência para exibir a caixa
de diálogo Adicionar referência. Clique na guia rotulada como Projetos. O projeto
ctlClockLib estará listado em Nome do Projeto. Clique duas vezes no projeto
para adicionar a referência ao projeto de teste.
4. Em Gerenciador de Soluções, clique com o botão direito do mouse em Testar e

clique em Compilar.
5. Na Caixa de Ferramentas, expanda o nó Componentes de ctlClockLib.
6. Clique duas vezes em ctlAlarmClock para adicionar uma cópia de ctlAlarmClock

ao seu formulário.
7. Na Caixa de Ferramentas, localize e clique duas vezes em DateTimePicker para

adicionar um DateTimePicker controle ao formulário e adicione um Label controle
clicando duas vezes no Rótulo.
8. Use o mouse para posicionar os controles em um local conveniente do formulário.
9. Defina as propriedades desses controles conforme mostrado a seguir.
label1 Texto (blank space)
Nome lblTest
dateTimePicker1 Nome dtpTest
Formato Time
10. No designer, clique duas vezes em dtpTest.
O Editor de Códigos é aberto para private void dtpTest_ValueChanged .

11. Modifique o código para que ele fique parecido com o mostrado a seguir.
C#
private void dtpTest_ValueChanged(object sender, System.EventArgs e)

{
ctlAlarmClock1.AlarmTime = dtpTest.Value;
ctlAlarmClock1.AlarmSet = true;
lblTest.Text = "Alarm Time is " +
ctlAlarmClock1.AlarmTime.ToShortTimeString();
}
12. Em Gerenciador de Soluções, clique com o botão direito do mouse em Testar e

clique em Definir como Projeto inicial.
13. No menu Depurar , clique em Iniciar Depuração.
O programa de teste é iniciado. Observe que a hora atual é atualizada no

ctlAlarmClock controle e que a hora inicial é mostrada no DateTimePicker
controle.
14. Clique no DateTimePicker local em que os minutos da hora são exibidos.
15. Usando o teclado, defina um valor de minutos que tem um minuto a mais que a
hora atual mostrada por ctlAlarmClock .
A hora da configuração do alarme é mostrada em lblTest . Aguarde até que a

hora exibida atinja a hora de configuração do alarme. Quando a hora exibida
atingir a hora na qual o alarme está definido, o lblAlarm piscará.
16. Desligue o alarme clicando em btnAlarmOff . Agora você pode redefinir o alarme.
Este artigo abordou uma série de conceitos-chave. Você aprendeu a criar um controle
de composição, combinando controles e componentes em um contêiner de controle de
composição. Você aprendeu a adicionar propriedades ao controle e a escrever um
código para implementar a funcionalidade personalizada. Na última seção, você
aprendeu a estender a funcionalidade de determinado controle de composição por
meio da herança e a alterar a funcionalidade dos métodos do host ao substituí-los.
Confira também
Ferramentas
Instruções passo a passo: herdando um controle dos Windows Forms com Visual
C#
Passo a passo: herdar de um controle de
Windows Forms com C #
Artigo • 02/06/2023
Com o C#, você pode criar controles personalizados poderosos por meio da herança.
Com a herança, você é capaz de criar controles que mantêm todas as funcionalidades
inerentes de controles padrão dos Windows Forms, mas também incorporam
funcionalidades personalizadas. Neste passo a passo, você criará um controle herdado
simples chamado ValueButton . Esse botão herdará a funcionalidade do controle de
Windows Forms Button padrão e exporá uma propriedade personalizada chamada
ButtonValue .
Criar o projeto
Quando cria um novo projeto, você especifica seu nome para definir o namespace raiz,
o nome do assembly e o nome do projeto e para garantir que o componente padrão
estará no namespace correto.
Para criar a biblioteca de controle ValueButtonLib e o

controle ValueButton
1. No Visual Studio, crie um novo projeto da Biblioteca de Controle Windows Forms
e nomeie-o como ValueButtonLib.
O nome do projeto, ValueButtonLib , também é atribuído ao namespace raiz por

padrão. O namespace raiz é usado para qualificar os nomes dos componentes no
assembly. Por exemplo, se dois assemblies fornecerem componentes chamados
ValueButton , você poderá especificar o componente ValueButton usando
ValueButtonLib.ValueButton . Para obter mais informações, consulte Namespaces.
2. No Gerenciador de Soluções, clique com o botão direito do mouse em

UserControl1.cs e escolha Renomear no menu de atalho. Altere o nome do
arquivo para ValueButton.cs. Clique no botão Sim quando solicitado se desejar
renomear todas as referências ao elemento de código ' UserControl1 '.

ValueButton.cs e selecione Exibir Código.
4. Localize a class linha de instrução e altere o tipo do qual esse controle herda para
UserControlButton. public partial class ValueButton Isso permite que o controle
herdado herde toda a funcionalidade do Button controle.
5. No Gerenciador de Soluções, abra o nó ValueButton.cs para exibir o arquivo de

código gerado pelo designer, ValueButton.Designer.cs. Abra este arquivo no
Editor de Código.
6. Localize o InitializeComponent método e remova a linha que atribui a

AutoScaleMode propriedade. Essa propriedade não existe no Button controle.
7. No menu Arquivo, escolha Salvar Tudo para salvar o projeto.
７ Observação
Um designer visual não está mais disponível. Como o Button controle faz sua
própria pintura, você não consegue modificar sua aparência no designer. Sua
representação visual será exatamente igual à da classe da qual herda (ou seja),
Buttona menos que seja modificada no código. Você ainda pode adicionar
componentes, que não têm uma interface do usuário, à superfície de design.
Adicionar uma propriedade ao controle

herdado
Um uso possível dos controles herdados dos Windows Forms é a criação de controles
que são idênticos em termos de aparência a controles padrão dos Windows Forms, mas
que expõem propriedades personalizadas. Nesta seção, você adicionará uma
propriedade chamada ButtonValue ao controle.
Para adicionar a propriedade de valor

ValueButton.cs e, depois, clique em Exibir Código no menu de atalho.
2. Localize a instrução class . Cole o código a seguir imediatamente depois de { :
C#
// Creates the private variable that will store the value of your
// property.
private int varValue;
// Declares the property.
public int ButtonValue
{
// Sets the method for retrieving the value of your property.
get
{
return varValue;
}
// Sets the method for setting the value of your property.
set
{
varValue = value;
}
}
Esse código define os métodos segundo os quais a propriedade ButtonValue é

armazenada e recuperada. A instrução get define o valor retornado como o valor
que é armazenado na variável particular varValue e a instrução set define o valor
da variável particular usando a palavra-chave value .
3. No menu Arquivo, escolha Salvar Tudo para salvar o projeto.
Testar o controle
Controles não são projetos autônomos; eles devem ser hospedados em um contêiner.
Para testar seu controle, você precisa fornecer um projeto de teste em que ele será
executado. Você também precisa tornar seu controle acessível para o projeto de teste
compilando-o. Nesta seção, você compilará seu controle e o testará em um Windows
Form.
Para compilar seu controle

No menu Compilar, clique em Compilar Solução. O build deve ser bem-sucedido, sem
avisos ou erros do compilador.
Para criar um projeto de teste

1. No menu Arquivo, aponte para Adicionar e clique em Novo Projeto para abrir a
caixa de diálogo Adicionar Novo Projeto.
2. Selecione o nó Windows, abaixo de Visual C# e clique em Aplicativo dos

Windows Forms.
3. Na caixa Nome , insira Teste.

4. No Gerenciador de Soluções, clique com o botão direito do mouse no nó
Referências de seu projeto de teste e selecione Adicionar Referência no menu de
atalho para exibir a caixa de diálogo Adicionar Referência.
5. Clique na guia rotulada como Projetos. Seu projeto ValueButtonLib será listado em
Nome do Projeto. Clique duas vezes no projeto para adicionar a referência ao
projeto de teste.
6. No Gerenciador de Soluções, clique com o botão direito do mouse em Testar e

selecione Compilar.
Para adicionar o controle ao formulário

1. No Gerenciador de Soluções, clique com o botão direito do mouse em Form1.cs e
selecione Designer de Modo de Exibição no menu de atalho.
2. Na Caixa de Ferramentas, selecione Componentes ValueButtonLib. Clique duas

vezes em ValueButton.
Um ValueButton aparece no formulário.
3. Clique com o botão direito do mouse em ValueButton e selecione Propriedades

no menu de atalho.
4. Na janela Propriedades, examine as propriedades desse controle. Observe que

elas são idênticas às propriedades expostas por um botão padrão, exceto que há
uma propriedade adicional, ButtonValue.
5. Defina a propriedade ButtonValue como 5.
6. Na guia Todos os Windows Forms da Caixa de Ferramentas, clique duas vezes em

Rótulo para adicionar um Label controle ao formulário.
7. Reposicione o rótulo no centro do formulário.
8. Clique duas vezes em valueButton1 .
O Editor de Códigos é aberto no evento valueButton1_Click .
9. Insira a seguinte linha de código.
C#
label1.Text = valueButton1.ButtonValue.ToString();
10. No Gerenciador de Soluções, clique com o botão direito do mouse em Teste e
escolha Definir como Projeto de Inicialização no menu de atalho.
11. No menu Depuração, selecione Iniciar Depuração.
Form1 é exibido.
12. Clique em valueButton1 .
O numeral "5" é exibido em label1 , demonstrando que a propriedade

ButtonValue de seu controle herdado foi passada para label1 por meio do
método valueButton1_Click . Portanto, seu controle ValueButton herda todas as
funcionalidades do botão padrão dos Windows Forms, mas expõe uma
propriedade adicional personalizada.
Confira também
Ferramentas
Passo a passo: criando um controle de composição com o Visual C#
Passo a passo: executar tarefas comuns
usando ações de designer
Artigo • 02/06/2023
À medida que você constrói formulários e controles para seu aplicativo Windows Forms,
há muitas tarefas que você executará repetidamente. A lista a seguir mostra algumas
das tarefas normalmente executadas que você encontrará:
Adicionando ou removendo uma guia em um TabControl.

Encaixando um controle ao pai.
Alterando a orientação de um SplitContainer controle.
Para acelerar o desenvolvimento, muitos controles oferecem ações de designer, que são
menus sensíveis ao contexto que permitem executar tarefas comuns como essas em um
único gesto no tempo de design. Essas tarefas são chamadas de verbos de ações de
designer.
As ações do designer permanecem anexadas a uma instância de controle por seu tempo
de vida no designer e estão sempre disponíveis.
Criar o projeto
A primeira etapa é criar o projeto e configurar o formulário.

DesignerActionsExample.
2. Selecione o formulário no Designer de Formulários do Windows.
Usar ações de designer

As ações do designer estão sempre disponíveis em tempo de design em controles que
lhes oferecem.
1. Arraste um TabControl da Caixa de Ferramentas para seu formulário. Observe o

glifo de ações do designer ( ) que aparece na lateral do TabControl.
2. Clique no glifo de ações do designer. No menu de atalho que aparece ao lado do

glifo, selecione o item Adicionar guia. Observe que uma nova página de guia é
adicionada ao TabControl.

glifo, selecione o item Adicionar coluna. Observe que uma nova coluna é
adicionada ao TableLayoutPanel controle.
5. Arraste um SplitContainer controle da Caixa de Ferramentas para o formulário.

glifo, selecione o item Orientação do Divisor Horizontal . Observe que a
SplitContainer barra de divisor do controle agora é orientada horizontalmente.
Confira também
TextBox
TabControl
SplitContainer
DesignerActionList
Passo a passo: Serializar coleções de
tipos padrão
Artigo • 02/06/2023
Seus controles personalizados às vezes exporão uma coleção como uma propriedade.
Este passo a passo demonstra como usar a DesignerSerializationVisibilityAttribute classe
para controlar como uma coleção é serializada em tempo de design. Aplicar o Content
valor à sua propriedade de coleção garante que a propriedade será serializada.
Para copiar o código neste tópico como uma lista única, consulte Como serializar
coleções de tipos padrão com o DesignerSerializationVisibilityAttribute.
Pré-requisitos
É necessário o Visual Studio para concluir este passo a passo.
Criar um controle com uma coleção serializável

A primeira etapa é criar um controle que tem uma coleção serializável como uma
propriedade. Você pode editar o conteúdo dessa coleção usando o Editor de Coleção,
acessível por meio da janela Propriedades.
1. No Visual Studio, crie um projeto da Biblioteca de Controle do Windows e nomeie-

o serializationDemoControlLib.
2. Renomeie UserControl1 para SerializationDemoControl . Para obter mais

informações, consulte Renomear uma refatoração de símbolo de código.
3. Na janela Propriedades , defina o valor da Padding.All propriedade como 10.
4. Coloque um TextBox controle no SerializationDemoControl .
5. Selecione o controle TextBox. Na janela Propriedades , defina as propriedades a

seguir.
Multilinha true
Dock Fill
ScrollBars Vertical
ReadOnly (somente-leitura) true
6. No Editor de Códigos, declare um campo de matriz de cadeia de caracteres

chamado stringsValue em SerializationDemoControl .
C#
// This field backs the Strings property.

private String[] stringsValue = new String[1];
7. Defina a propriedade Strings no SerializationDemoControl .
７ Observação
O Content valor é usado para habilitar a serialização da coleção.
C#
// When the DesignerSerializationVisibility attribute has

// a value of "Content" or "Visible" the designer will
// serialize the property. This property can also be edited
// at design time with a CollectionEditor.
[DesignerSerializationVisibility(
DesignerSerializationVisibility.Content )]
public String[] Strings
{
get
{
return this.stringsValue;
}
set
{
this.stringsValue = value;
// Populate the contained TextBox with the values

// in the stringsValue array.
StringBuilder sb =
new StringBuilder(this.stringsValue.Length);
for (int i = 0; i < this.stringsValue.Length; i++)

{
sb.Append(this.stringsValue[i]);
sb.Append("\r\n");
}
this.textBox1.Text = sb.ToString();
}
}

usercontrol.
9. Localize a propriedade Strings no PropertyGrid contêiner de teste UserControl.

Selecione a propriedade Cadeias de Caracteres e, em seguida, selecione as
reticências ( ) para abrir o Editor de Coleção de Cadeias de Caracteres.
10. Insira várias cadeias de caracteres no Editor de Conjunto de Cadeia de Caracteres.

Separe-os pressionando a tecla Enter no final de cada cadeia de caracteres. Clique
em OK quando terminar de inserir cadeias de caracteres.
７ Observação
As cadeias de caracteres que você digitou aparecem no TextBox

. SerializationDemoControl
Serializar uma propriedade de coleção

Para testar o comportamento de serialização do seu controle, coloque-o em um
formulário e altere o conteúdo da coleção com o Editor de Coleção. Você pode ver o
estado da coleção serializada examinando um arquivo de designer especial no qual o
designer de Windows Forms emite o código.
1. Adicione um projeto de Aplicativos do Windows à solução. Dê ao projeto o nome

de SerializationDemoControlTest .
2. Na Caixa de Ferramentas, localize a guia chamada Componentes da

SerializationDemoControlLib. Nessa guia, você encontrará o
SerializationDemoControl . Para mais informações, consulte Instruções passo a
passo: preenchendo de forma automática a caixa de ferramentas com
componentes personalizados.
3. Coloque um SerializationDemoControl em seu formulário.
4. Localize a propriedade Strings na janela Propriedades. Clique na Strings

propriedade e clique nas reticências ( ) para abrir o Editor de Coleção de
Cadeias de Caracteres.
5. Digite várias cadeias de caracteres no Editor de Conjunto de Cadeia de
Caracteres. Separe-os pressionando Enter no final de cada cadeia de caracteres.
Clique em OK quando terminar de inserir cadeias de caracteres.
７ Observação
As cadeias de caracteres que você digitou aparecem no TextBox

. SerializationDemoControl
6. Em Gerenciador de Soluções, clique no botão Mostrar Todos os Arquivos.
7. Abra o nó Form1. Abaixo está um arquivo chamado Form1.Designer.cs ou

Form1.Designer.vb. Este é o arquivo no qual o Designer de Formulários do
Windows emite um código que representa o estado de tempo de design do
formulário e seus controles filho. Abra esse arquivo no Editor de Código.
8. Abra a região chamada Código gerado pelo Windows Form Designer e localize a
seção rotulada como serializationDemoControl1. Sob esse rótulo está o código
que representa o estado serializado do seu controle. As cadeias de caracteres que
você digitou na etapa 5 aparecem em uma atribuição para a propriedade Strings .
Os exemplos de código a seguir no C# e no Visual Basic mostram código
semelhante ao que você verá se digitou as cadeias de caracteres "vermelho",
"laranja" e "amarelo".
C#
this.serializationDemoControl1.Strings = new string[] {

"red",
"orange",
"yellow"};
9. No Editor de Código, altere o valor da DesignerSerializationVisibilityAttribute

propriedade na Strings propriedade para Hidden.
C#
[DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden
)]
10. Recompile a solução e repita as etapas 3 e 4.
７ Observação
Neste caso, o Designer de Formulários do Windows não emite nenhuma
atribuição para a propriedade Strings .
Próximas etapas
Se você souber como serializar uma coleção de tipos padrão, considere integrar seus
controles personalizados mais profundamente no ambiente de tempo de design. Os
tópicos a seguir descrevem como aprimorar a integração do tempo de design de seus
controles personalizados:
Arquitetura de tempo de design
Visão geral da serialização de designer

Confira também
Passo a passo: Depurar controles de
Windows Forms personalizados em
tempo de design
Artigo • 02/06/2023
Quando criar um controle personalizado, frequentemente você achará necessário

depurar seu comportamento em tempo de design. Isso será especialmente válido se
você estiver criando um designer personalizado para seu controle personalizado. Para
obter detalhes, consulte Instruções passo a passo: criando um controle dos Windows
Forms que aproveite os recursos de tempo de design do Visual Studio.
Você pode depurar seus controles personalizados usando o Visual Studio, da mesma
forma que depuraria qualquer outra classe do .NET Framework. A diferença é que você
depurará uma instância separada do Visual Studio que está executando o código do
controle personalizado.
Criar o projeto
A primeira etapa é criar o projeto do aplicativo. Você usará este projeto para criar o
aplicativo que hospeda o controle personalizado.
No Visual Studio, crie um projeto de aplicativo do Windows e nomeie-o como

DebuggingExample.

1. Adicione um projeto de Biblioteca de controle do Windows à solução.
2. Adicione um novo item UserControl ao projeto DebugControlLibrary. Nomeie-o

debugControl.
3. Em Gerenciador de Soluções, exclua o controle padrão do projeto excluindo o

arquivo de código com um nome base de UserControl1.
4. Compile a solução.
Neste ponto, você poderá ver o controle personalizado na Caixa de Ferramentas.
Para verificar o progresso, localize a nova guia chamada Componentes
DebugControlLibrary e clique para selecioná-la. Quando ela abrir, você verá seu
controle listado como DebugControl com o ícone padrão ao lado dele.
Adicionar uma propriedade ao controle

personalizado
Para demonstrar que o código de seu controle personalizado está sendo executado em
tempo de design, você adicionará uma propriedade e definirá um ponto de interrupção
no código que implementa a propriedade.
1. Abra DebugControl no Editor de Códigos. Adicione o seguinte código à definição

da classe:
C#
private string demoStringValue = null;

[Browsable(true)]
public string DemoString
{
get
{
return this.demoStringValue;
}
set
{
demoStringValue = value;
}
}
Adicionar seu controle personalizado ao

formulário de host
Para depurar o comportamento em tempo de design do controle personalizado, você
colocará uma instância da classe do controle personalizado em um formulário do host.
1. No projeto "DebuggingExample", abra Form1 no Designer de Formulários do

Windows.
2. Na caixa de Ferramentas, abra a guia Componentes de DebugControlLibrary e

arraste uma instância de DebugControl para o formulário.
3. Encontre a propriedade personalizada DemoString na janela Propriedades.
Observe que você pode alterar seu valor, da mesma forma que faria com qualquer
outra propriedade. Observe também que, quando a propriedade DemoString for
selecionada, a cadeia de caracteres de descrição da propriedade aparecerá na
parte inferior da janela Propriedades.
Configurar o projeto para depuração em tempo

de design
Para depurar o comportamento em tempo de design do seu controle personalizado,
você depurará uma instância separada do Visual Studio que está executando o código
do seu controle personalizado.
1. Clique com o botão direito do mouse no projeto DebugControlLibrary no

Gerenciador de Soluções e selecione Propriedades.
2. Na folha de propriedades DebugControlLibrary, selecione a guia Depurar.
Na seção Iniciar Ação, selecione Iniciar programa externo. Você vai depurar uma
instância separada do Visual Studio, portanto, clique nas reticências ( ) para
procurar o IDE do Visual Studio. O nome do arquivo executável é devenv.exee, se
você estiver instalado no local padrão, seu caminho será
%ProgramFiles(x86)%\Microsoft Visual Studio\2019\<edition>\Common7\IDE.
3. Selecione OK para fechar a caixa de diálogo.
4. Clique com botão direito do mouse no projeto DebugControlLibrary e selecione

Definir como Projeto de Inicialização para habilitar essa configuração de
depuração.
Depurar seu controle personalizado em tempo

de design
Agora, você está pronto para depurar o controle personalizado enquanto ele é
executado em modo de design. Quando você iniciar a sessão de depuração, uma nova
instância do Visual Studio será criada e você a usará para carregar a solução
"DebuggingExample". Quando você abrir Form1 no Designer de Formulários, uma
instância do controle personalizado será criada e começará a ser executada.
1. Abra o arquivo de origem DebugControl no Editor de Códigos e coloque um

ponto de interrupção no acessador Set da propriedade DemoString .
2. Pressione F5 para iniciar a sessão de depuração. Uma nova instância do Visual
Studio é criada. É possível diferenciar as instâncias de duas maneiras:
A instância de depuração tem as palavras Em execução na barra de título
A instância de depuração tem o botão Iniciar em sua barra de ferramentas

Depurar desabilitado
Seu ponto de interrupção é definido na instância de depuração.
3. Na nova instância do Visual Studio, abra a solução "DebuggingExample". Você

pode localizar facilmente a solução selecionando Projetos Recentes no menu
Arquivo. O arquivo de solução "DebuggingExample.sln" será listado como o
arquivo usado mais recentemente.
） Importante
Se você estiver depurando um .NET 5 (.NET Core 3.1) ou posterior Windows

Forms projeto, use essa instância do Visual Studio para anexar um depurador
ao processo deDesignToolsServer.exe. Selecione a Anexação de
Depuração>para processar o item de menu. LocalizeDesignToolsServer.exe na
lista de processos e pressione Attach.
4. Abra Form1 no Designer de Formulários e selecione o controle DebugControl.
5. Altere o valor da propriedade DemoString . Quando você confirma a alteração, a

instância de depuração do Visual Studio adquire foco e a execução para no ponto
de interrupção. É possível percorrer passo a passo o acessador de propriedade, da
mesma forma que você o faria com qualquer outro código.
6. Para interromper a depuração, saia da instância hospedada do Visual Studio ou

selecione o botão Parar Depuração na instância de depuração.
Próximas etapas
Agora que você pode depurar seus controles personalizados em tempo de design, há
muitas possibilidades para expandir a interação do controle com o IDE do Visual Studio.
Você pode usar a DesignMode propriedade da Component classe para escrever

um código que só será executado em tempo de design. Para obter detalhes,
consulte DesignMode.
Há vários atributos que você pode aplicar a propriedades do controle para
manipular a interação do seu controle personalizado com o designer. Você pode
encontrar esses atributos no System.ComponentModel namespace.
Você pode escrever um designer personalizado para seu controle personalizado.

Isso lhe dá controle total sobre a experiência de design usando a infra-estrutura de
designer extensível exposta pelo Visual Studio. Para obter detalhes, consulte
Instruções passo a passo: criando um controle dos Windows Forms que aproveite
os recursos de tempo de design do Visual Studio.
Confira também
Passo a passo: criar um controle que
aproveite os recursos de tempo de
design
Artigo • 02/06/2023
A experiência de tempo de design para um controle personalizado pode ser aprimorada

por meio da criação de um designer personalizado associado.
Este artigo ilustra como criar um designer personalizado para um controle

personalizado. Você implementará um MarqueeControl tipo e uma classe de designer
associada chamada MarqueeControlRootDesigner .
O MarqueeControl tipo implementa uma exibição semelhante a uma marquise de teatro

com luzes animadas e texto piscando.
O designer para esse controle interage com o ambiente de design para fornecer uma
experiência de tempo de design personalizada. Com o designer personalizado, você
pode montar uma implementação MarqueeControl personalizada com luzes animadas e
o texto piscando em muitas combinações. Você pode usar o controle montado em um
formulário como qualquer outro controle dos Windows Forms.
Quando você terminar de usar este passo a passo, seu controle personalizado será
semelhante ao seguinte:
Para obter a listagem de códigos completa, consulte Como criar um controle dos
Windows Forms que aproveita funcionalidades de tempo de design.
Pré-requisitos
Para concluir este passo a passo, você precisará de Visual Studio.
Criar o projeto
A primeira etapa é criar o projeto do aplicativo. Você usará este projeto para criar o
aplicativo que hospeda o controle personalizado.
Em Visual Studio, crie um novo projeto de aplicativo Windows Forms e nomeie-o

MarqueeControlTest.

1. Adicione um projeto de biblioteca de controles dos Windows Forms à solução.
Nomeie o projeto MarqueeControlLibrary.
2. Usando o Gerenciador de Soluções, exclua o controle padrão do projeto,

excluindo o arquivo de origem denominado "UserControl1.cs" ou
"UserControl1.vb", dependendo da linguagem de sua escolha.
3. Adicione um novo UserControl item ao MarqueeControlLibrary projeto. Dê ao

novo arquivo de origem um nome base de MarqueeControl.
4. Usando o Gerenciador de Soluções, crie uma nova pasta no projeto

MarqueeControlLibrary .
5. Clique com o botão direito do mouse na pasta Design e adicione uma nova classe.
Nomeie-o MarqueeControlRootDesigner.
6. Você precisará usar tipos do assembly System.Design, portanto, adicione essa

referência ao MarqueeControlLibrary projeto.
Referenciar o controle personalizado Project

Você usará o projeto MarqueeControlTest para testar o controle personalizado. O
projeto de teste fará o reconhecimento do controle personalizado quando você
adicionar uma referência do projeto ao assembly MarqueeControlLibrary .
No projeto MarqueeControlTest , adicione uma referência do projeto ao assembly

MarqueeControlLibrary . Certifique-se de usar a guia Projetos da caixa de diálogo
Adicionar Referência, em vez de referenciar o assembly MarqueeControlLibrary

diretamente.
Definir um controle personalizado e seu

designer personalizado
Seu controle personalizado derivará da UserControl classe. Isso permite que o controle
contenha outros controles e dá a seu controle muita funcionalidade padrão.
O controle personalizado terá um designer personalizado associado. Isso permite que

você crie uma experiência de design exclusiva, desenvolvida especificamente para seu
controle personalizado.
Você associa o controle ao designer usando a DesignerAttribute classe. Como você está
desenvolvendo todo o comportamento de tempo de design do controle personalizado,
o designer personalizado implementará a IRootDesigner interface.
Para definir um controle personalizado e o respectivo

designer personalizado
1. Abra o arquivo de origem MarqueeControl no Editor de Código. Na parte superior
do arquivo, importe os seguintes namespaces:
C#
using System;
2. Adicione a DesignerAttribute declaração de MarqueeControl classe. Isso associa o

controle personalizado ao respectivo designer.
C#
[Designer( typeof(
MarqueeControlLibrary.Design.MarqueeControlRootDesigner ), typeof(
IRootDesigner ) )]
public class MarqueeControl : UserControl
{
3. Abra o arquivo de origem MarqueeControlRootDesigner no Editor de Código. Na

parte superior do arquivo, importe os seguintes namespaces:
C#
using System;
4. Altere a declaração de MarqueeControlRootDesigner para herdar da classe

DocumentDesigner. Aplique o ToolboxItemFilterAttribute para especificar a
interação do designer com a Caixa de Ferramentas.
７ Observação
A definição da MarqueeControlRootDesigner classe foi colocada em um

namespace chamado MarqueeControlLibrary.Design. Essa declaração coloca o
designer em um namespace especial reservado para tipos relacionados a
design.
C#
namespace MarqueeControlLibrary.Design
{
[ToolboxItemFilter("MarqueeControlLibrary.MarqueeBorder",
ToolboxItemFilterType.Require)]
[ToolboxItemFilter("MarqueeControlLibrary.MarqueeText",
public class MarqueeControlRootDesigner : DocumentDesigner
{
5. Defina o construtor para a classe MarqueeControlRootDesigner . Insira uma

WriteLine instrução no corpo do construtor. Isso será útil para depuração.
C#
public MarqueeControlRootDesigner()
{
Trace.WriteLine("MarqueeControlRootDesigner ctor");
}
Criar uma instância do controle personalizado

1. Adicione um novo UserControl item ao MarqueeControlTest projeto. Dê ao novo
arquivo de origem um nome base de DemoMarqueeControl.
2. Abra o DemoMarqueeControl arquivo no Editor de Código. Na parte superior do
arquivo, importe o namespace MarqueeControlLibrary :
C#
using MarqueeControlLibrary;
3. Altere a declaração de DemoMarqueeControl para herdar da classe MarqueeControl .
5. Abra o Form1 no Designer Windows Forms.
6. Localize a guia Componentes MarqueeControlTest na Caixa de Ferramentas e

abra-a. Arraste um DemoMarqueeControl da Caixa de Ferramentas para seu
formulário.
Configurar o Project para depuração de

Design-Time
Quando você estiver desenvolvendo uma experiência personalizada de tempo de
design, será necessário depurar seus controles e componentes. Há uma maneira simples
de configurar seu projeto para permitir a depuração em tempo de design. Para obter
mais informações, consulte Passo a passo: depurando controles dos Windows Forms
personalizados em tempo de design.
1. Clique com o botão direito do mouse no projeto MarqueeControlLibrary e

selecione Propriedades.
2. Na caixa de diálogo Páginas da Propriedade MarqueeControlLibrary , selecione a

página Depurar .
3. Na seção Iniciar Ação , selecione Iniciar Programa Externo. Você vai depurar uma
instância separada de Visual Studio, portanto, clique no botão reticências ( ) para
procurar o IDE Visual Studio. O nome do arquivo executável é devenv.exe e, se
você estiver instalado no local padrão, seu caminho será
%ProgramFiles(x86)%\Microsoft Visual Studio\2019\
<edition>\Common7\IDE\devenv.exe.
4. Selecione OK para fechar a caixa de diálogo.

5. Clique com o botão direito do mouse no projeto MarqueeControlLibrary e
selecione Definir como StartUp Project para habilitar essa configuração de
depuração.
Agora você está pronto para depurar o comportamento de tempo de design de seu
controle personalizado. Depois de determinar que o ambiente de depuração está
configurado corretamente, você testará a associação entre o controle personalizado e o
designer personalizado.
Para testar o ambiente de depuração e a associação com

o designer
1. Abra o arquivo de origem MarqueeControlRootDesigner no Editor de Código e
coloque um ponto de interrupção na WriteLine instrução.
2. Pressione F5 para iniciar a sessão de depuração.
Uma nova instância de Visual Studio é criada.
3. Na nova instância do Visual Studio, abra a solução MarqueeControlTest. Você pode

localizar facilmente a solução selecionando Projetos Recentes no menu Arquivo. O
arquivo de solução MarqueeControlTest.sln será listado como o arquivo usado
mais recentemente.
4. Abra o DemoMarqueeControl no designer.
A instância de depuração de Visual Studio obtém o foco e as paradas de execução

no ponto de interrupção. Pressione F5 para continuar a sessão de depuração.
Nesse ponto, tudo está preparado para você desenvolver e depurar seu controle
personalizado e o respectivo designer personalizado associado. O restante deste artigo
se concentra nos detalhes da implementação de recursos do controle e do designer.
Implementar o controle personalizado

O MarqueeControl é com um UserControl pouco de personalização. Ele apresenta dois
métodos: Start (que inicia a animação do letreiro) e Stop (que interrompe a animação).
Já que MarqueeControl contém controles filho que implementam a interface
IMarqueeWidget , Start e Stop enumeram cada controle filho e chamam os métodos
StartMarquee e StopMarquee , respectivamente, em cada controle filho que implementa
IMarqueeWidget .
A aparência do e controles MarqueeBorder depende do layout, portanto MarqueeControl ,

substitui o OnLayout método e chama PerformLayout controles filho desse MarqueeText
tipo.
Esta é a extensão das personalizações de MarqueeControl . Os recursos de tempo de

execução são implementados pelos controles MarqueeBorder e MarqueeText e os
recursos de tempo de design são implementados pelas classes MarqueeBorderDesigner e
MarqueeControlRootDesigner .
Para implementar seu controle personalizado

1. Abra o arquivo de origem MarqueeControl no Editor de Código. Implemente os
métodos Start e Stop .
C#
public void Start()

{
// The MarqueeControl may contain any number of
// controls that implement IMarqueeWidget, so
// find each IMarqueeWidget child and call its
// StartMarquee method.
foreach( Control cntrl in this.Controls )
{
if( cntrl is IMarqueeWidget )
{
IMarqueeWidget widget = cntrl as IMarqueeWidget;
widget.StartMarquee();
}
}
}
public void Stop()

{
// The MarqueeControl may contain any number of
// controls that implement IMarqueeWidget, so find
// each IMarqueeWidget child and call its StopMarquee
// method.
{
{
widget.StopMarquee();
}
}
}
2. Substitua o método OnLayout.
C#
protected override void OnLayout(LayoutEventArgs levent)

{
base.OnLayout (levent);
// Repaint all IMarqueeWidget children if the layout

// has changed.
{
{
Control control = cntrl as Control;
control.PerformLayout();
}
}
}
Criar um controle filho para seu controle

personalizado
O MarqueeControl hospedará os dois tipos de controle filho: o controle MarqueeBorder e
o controle MarqueeText .
MarqueeBorder : esse controle pinta uma borda de "luzes" em torno das próprias
bordas. As luzes piscam em sequência, por isso elas parecem se mover em torno
da borda. A velocidade na qual as luzes piscam é controlada por uma propriedade
chamada UpdatePeriod . Várias outras propriedades personalizadas determinam
outros aspectos da aparência do controle. Dois métodos, chamados StartMarquee
e StopMarquee , controlam quando a animação começa e para.
MarqueeText : esse controle pinta uma cadeia de caracteres piscando. Assim como
o controle MarqueeBorder , a velocidade na qual o texto pisca é controlada pela

propriedade UpdatePeriod . O controle MarqueeText também tem os métodos
StartMarquee e StopMarquee em comum com o controle MarqueeBorder .
Em tempo de design, o MarqueeControlRootDesigner permite que esses tipos de controle

sejam adicionados a um MarqueeControl em qualquer combinação.
Recursos comuns dos dois controles são incluídos em uma interface chamada
IMarqueeWidget . Isso permite que o MarqueeControl descubra os controles filho
relacionados ao letreiro e dê a eles tratamento especial.
Para implementar o recurso de animação periódica, você usará BackgroundWorker

objetos do System.ComponentModel namespace. Você pode usar Timer objetos, mas
quando muitos IMarqueeWidget objetos estão presentes, o único thread de interface do
usuário pode não conseguir acompanhar a animação.
Para criar um controle filho para o seu controle

personalizado
1. Adicione um novo item de classe ao projeto MarqueeControlLibrary . Dê ao novo
arquivo de origem o nome base "IMarqueeWidget".
2. Abra o arquivo de origem IMarqueeWidget no Editor de Código e altere a

declaração de class para interface :
C#
// This interface defines the contract for any class that is to

// be used in constructing a MarqueeControl.
public interface IMarqueeWidget
{
3. Adicione o código a seguir à interface IMarqueeWidget para expor dois métodos e

uma propriedade que manipulam a animação do letreiro:
C#
// This interface defines the contract for any class that is to

// be used in constructing a MarqueeControl.
public interface IMarqueeWidget
{
// This method starts the animation. If the control can
// contain other classes that implement IMarqueeWidget as
// children, the control should call StartMarquee on all
// its IMarqueeWidget child controls.
void StartMarquee();
// This method stops the animation. If the control can

// contain other classes that implement IMarqueeWidget as
// children, the control should call StopMarquee on all
// its IMarqueeWidget child controls.
void StopMarquee();
// This method specifies the refresh rate for the animation,
// in milliseconds.
int UpdatePeriod
{
get;
set;
}
}
4. Adicione um novo item de Controle Personalizado ao projeto

MarqueeControlLibrary . Dê ao novo arquivo de origem o nome base
"MarqueeText".
5. Arraste um BackgroundWorker componente da Caixa de Ferramentas para o

controle MarqueeText . Esse componente permitirá que o controle MarqueeText se
atualize de modo assíncrono.
6. Na janela Propriedades, defina as propriedades e WorkerSupportsCancellation o

WorkerReportsProgress BackgroundWorker componente como verdadeiros. Essas
configurações permitem que o BackgroundWorker componente acione

periodicamente o ProgressChanged evento e cancele atualizações assíncronas.
Para obter mais informações, consulte o Componente BackgroundWorker.
7. Abra o arquivo de origem MarqueeText no Editor de Código. Na parte superior do

arquivo, importe os seguintes namespaces:
C#
using System;
8. Altere a declaração de MarqueeText herdar Label e implementar a IMarqueeWidget

interface:
C#
[ToolboxItemFilter("MarqueeControlLibrary.MarqueeText",
public partial class MarqueeText : Label, IMarqueeWidget
{
9. Declare as variáveis de instância que correspondem às propriedades expostas e
inicialize-as no construtor. O campo isLit determina se o texto será pintado na
cor fornecida pela propriedade LightColor .
C#
// When isLit is true, the text is painted in the light color;

// When isLit is false, the text is painted in the dark color.
// This value changes whenever the BackgroundWorker component
// raises the ProgressChanged event.
private bool isLit = true;
// These fields back the public properties.

private int updatePeriodValue = 50;
private Color lightColorValue;
private Color darkColorValue;
// These brushes are used to paint the light and dark

// colors of the text.
private Brush lightBrush;
private Brush darkBrush;
// This component updates the control asynchronously.

public MarqueeText()
{
// This call is required by the Windows.Forms Form Designer.
// Initialize light and dark colors

// to the control's default values.
this.lightColorValue = this.ForeColor;
this.darkColorValue = this.BackColor;
this.lightBrush = new SolidBrush(this.lightColorValue);
this.darkBrush = new SolidBrush(this.darkColorValue);
}
10. Implemente a interface IMarqueeWidget .
Os StartMarquee métodos e StopMarquee os métodos invocam os

BackgroundWorker métodos e CancelAsync do RunWorkerAsync componente para
iniciar e parar a animação.
Os Category atributos e os atributos Browsable são aplicados à propriedade para

UpdatePeriod que ela apareça em uma seção personalizada da janela Propriedades
chamada "Marquee".
C#
public virtual void StartMarquee()

{
// Start the updating thread and pass it the UpdatePeriod.
this.backgroundWorker1.RunWorkerAsync(this.UpdatePeriod);
}
public virtual void StopMarquee()

{
// Stop the updating thread.
}
[Category("Marquee")]
[Browsable(true)]
public int UpdatePeriod
{
get
{
return this.updatePeriodValue;
}
set
{
if (value > 0)
{
this.updatePeriodValue = value;
}
else
{
throw new ArgumentOutOfRangeException("UpdatePeriod", "must
be > 0");
}
}
}
11. Implemente os acessadores de propriedade. Você exporá duas propriedades aos

clientes: LightColor e DarkColor . Os Category atributos e os atributos Browsable
são aplicados a essas propriedades, portanto, as propriedades aparecem em uma
seção personalizada da janela Propriedades chamada "Marquee".
C#
[Browsable(true)]
public Color LightColor
{
get
{
return this.lightColorValue;
}
set
{
// The LightColor property is only changed if the
// client provides a different value. Comparing values
// from the ToArgb method is the recommended test for
// equality between Color structs.
if (this.lightColorValue.ToArgb() != value.ToArgb())
{
this.lightColorValue = value;
this.lightBrush = new SolidBrush(value);
}
}
}
[Browsable(true)]
public Color DarkColor
{
get
{
return this.darkColorValue;
}
set
{
// The DarkColor property is only changed if the
if (this.darkColorValue.ToArgb() != value.ToArgb())
{
this.darkColorValue = value;
this.darkBrush = new SolidBrush(value);
}
}
}
12. Implemente os manipuladores para os BackgroundWorker componentes DoWork

e ProgressChanged eventos.
O DoWork manipulador de eventos dorme para o número de milissegundos

especificados até UpdatePeriod que ele acione o ProgressChanged evento, até que
o código pare a animação chamando CancelAsync.
O ProgressChanged manipulador de eventos alterna o texto entre seu estado claro

e escuro para dar a aparência de piscar.
C#
// This method is called in the worker thread's context,

// so it must not make any calls into the MarqueeText control.
// Instead, it communicates to the control using the
// ProgressChanged event.
//
// The only work done in this event handler is
// to sleep for the number of milliseconds specified
// by UpdatePeriod, then raise the ProgressChanged event.
object sender,
System.ComponentModel.DoWorkEventArgs e)
{
// This event handler will run until the client cancels

// the background task by calling CancelAsync.
while (!worker.CancellationPending)
{
// The Argument property of the DoWorkEventArgs
// object holds the value of UpdatePeriod, which
// was passed as the argument to the RunWorkerAsync
// method.
Thread.Sleep((int)e.Argument);
// The DoWork eventhandler does not actually report

// progress; the ReportProgress event is used to
// periodically alert the control to update its state.
worker.ReportProgress(0);
}
}
// The ProgressChanged event is raised by the DoWork method.

// This event handler does work that is internal to the
// control. In this case, the text is toggled between its
// light and dark state, and the control is told to
// repaint itself.
System.ComponentModel.ProgressChangedEventArgs e)
{
this.isLit = !this.isLit;
this.Refresh();
}
13. Substitua o OnPaint método para habilitar a animação.
C#

{
// The text is painted in the light or dark color,
// depending on the current value of isLit.
this.ForeColor =
this.isLit ? this.lightColorValue : this.darkColorValue;
base.OnPaint(e);
}
14. Pressione F6 para criar a solução.
Criar o controle filho MarqueeBorder

O controle MarqueeBorder é um pouco mais sofisticado do que o controle MarqueeText .
Ele tem mais propriedades e a animação no OnPaint método está mais envolvida. A
princípio, ele é bem semelhante ao controle MarqueeText .
Como o MarqueeBorder controle pode ter controles filho, ele precisa estar ciente dos
Layout eventos.
Para criar o controle MarqueeBorder

1. Adicione um novo item de Controle Personalizado ao projeto
MarqueeControlLibrary . Dê ao novo arquivo de origem o nome base
"MarqueeBorder".
2. Arraste um BackgroundWorker componente da Caixa de Ferramentas para o

controle MarqueeBorder . Esse componente permitirá que o controle MarqueeBorder
se atualize de modo assíncrono.
3. Na janela Propriedades, defina as propriedades e WorkerSupportsCancellation o

WorkerReportsProgress BackgroundWorker componente como verdadeiros. Essas
configurações permitem que o BackgroundWorker componente acione

periodicamente o ProgressChanged evento e cancele atualizações assíncronas.
Para obter mais informações, consulte o Componente BackgroundWorker.
4. Na janela Propriedades , selecione o botão Eventos . Anexar manipuladores para

eventos e eventos DoWorkProgressChanged .
5. Abra o arquivo de origem MarqueeBorder no Editor de Código. Na parte superior

do arquivo, importe os seguintes namespaces:
C#
using System;
6. Altere a declaração de MarqueeBorder herdar Panel e implementar a

IMarqueeWidget interface.
C#
[Designer(typeof(MarqueeControlLibrary.Design.MarqueeBorderDesigner ))]
[ToolboxItemFilter("MarqueeControlLibrary.MarqueeBorder",
public partial class MarqueeBorder : Panel, IMarqueeWidget
{
7. Declare duas enumerações para gerenciar o estado do controle MarqueeBorder :

MarqueeSpinDirection , que determina a direção na qual as luzes "giram" ao redor
da borda e MarqueeLightShape , que determina a forma das luzes (circulares ou
quadradas). Coloque essas declarações antes da declaração de classe
MarqueeBorder .
C#
// This defines the possible values for the MarqueeBorder

// control's SpinDirection property.
public enum MarqueeSpinDirection
{
CW,
CCW
}
// This defines the possible values for the MarqueeBorder

// control's LightShape property.
public enum MarqueeLightShape
{
Square,
Circle
}
8. Declare as variáveis de instância que correspondem às propriedades expostas e

inicialize-as no construtor.
C#
public static int MaxLightSize = 10;
// These fields back the public properties.

private int updatePeriodValue = 50;
private int lightSizeValue = 5;
private int lightPeriodValue = 3;
private int lightSpacingValue = 1;
private Color lightColorValue;
private Color darkColorValue;
private MarqueeSpinDirection spinDirectionValue =
MarqueeSpinDirection.CW;
private MarqueeLightShape lightShapeValue = MarqueeLightShape.Square;
// These brushes are used to paint the light and dark

// colors of the marquee lights.
private Brush lightBrush;
private Brush darkBrush;
// This field tracks the progress of the "first" light as it

// "travels" around the marquee border.
private int currentOffset = 0;
// This component updates the control asynchronously.

public MarqueeBorder()
{
// This call is required by the Windows.Forms Form Designer.
// Initialize light and dark colors

// to the control's default values.
this.lightColorValue = this.ForeColor;
this.darkColorValue = this.BackColor;
this.lightBrush = new SolidBrush(this.lightColorValue);
this.darkBrush = new SolidBrush(this.darkColorValue);
// The MarqueeBorder control manages its own padding,

// because it requires that any contained controls do
// not overlap any of the marquee lights.
int pad = 2 * (this.lightSizeValue + this.lightSpacingValue);
this.Padding = new Padding(pad, pad, pad, pad);
SetStyle(ControlStyles.OptimizedDoubleBuffer, true);
}
9. Implemente a interface IMarqueeWidget .
Os StartMarquee métodos e StopMarquee os métodos invocam os

BackgroundWorker métodos e CancelAsync do RunWorkerAsync componente para
iniciar e parar a animação.
Já que o controle MarqueeBorder pode conter controles filho, o método

StartMarquee enumera todos os controles filho e chama StartMarquee naqueles
que implementam IMarqueeWidget . O método StopMarquee tem uma
implementação semelhante.
C#
public virtual void StartMarquee()

{
// The MarqueeBorder control may contain any number of
// each IMarqueeWidget child and call its StartMarquee
// method.
foreach (Control cntrl in this.Controls)
{
if (cntrl is IMarqueeWidget)
{
widget.StartMarquee();
}
}
// Start the updating thread and pass it the UpdatePeriod.

this.backgroundWorker1.RunWorkerAsync(this.UpdatePeriod);
}
public virtual void StopMarquee()

{
// The MarqueeBorder control may contain any number of
// each IMarqueeWidget child and call its StopMarquee
// method.
foreach (Control cntrl in this.Controls)
{
if (cntrl is IMarqueeWidget)
{
widget.StopMarquee();
}
}
// Stop the updating thread.

}
[Browsable(true)]
public virtual int UpdatePeriod
{
get
{
return this.updatePeriodValue;
}
set
{
if (value > 0)
{
this.updatePeriodValue = value;
}
else
{
throw new ArgumentOutOfRangeException("UpdatePeriod", "must
be > 0");
}
}
}
10. Implemente os acessadores de propriedade. O controle MarqueeBorder tem várias

propriedades para controlar sua aparência.
C#
[Browsable(true)]
public int LightSize
{
get
{
return this.lightSizeValue;
}
set
{
if (value > 0 && value <= MaxLightSize)
{
this.lightSizeValue = value;
this.DockPadding.All = 2 * value;
}
else
{
throw new ArgumentOutOfRangeException("LightSize", "must be
> 0 and < MaxLightSize");
}
}
}
[Browsable(true)]
public int LightPeriod
{
get
{
return this.lightPeriodValue;
}
set
{
if (value > 0)
{
this.lightPeriodValue = value;
}
else
{
throw new ArgumentOutOfRangeException("LightPeriod", "must
be > 0 ");
}
}
}
[Browsable(true)]
public Color LightColor
{
get
{
return this.lightColorValue;
}
set
{
// The LightColor property is only changed if the
if (this.lightColorValue.ToArgb() != value.ToArgb())
{
this.lightColorValue = value;
this.lightBrush = new SolidBrush(value);
}
}
}
[Browsable(true)]
public Color DarkColor
{
get
{
return this.darkColorValue;
}
set
{
// The DarkColor property is only changed if the
if (this.darkColorValue.ToArgb() != value.ToArgb())
{
this.darkColorValue = value;
this.darkBrush = new SolidBrush(value);
}
}
}
[Browsable(true)]
public int LightSpacing
{
get
{
return this.lightSpacingValue;
}
set
{
if (value >= 0)
{
this.lightSpacingValue = value;
}
else
{
throw new ArgumentOutOfRangeException("LightSpacing", "must
be >= 0");
}
}
}
[Browsable(true)]
[EditorAttribute(typeof(LightShapeEditor),
typeof(System.Drawing.Design.UITypeEditor))]
public MarqueeLightShape LightShape
{
get
{
return this.lightShapeValue;
}
set
{
this.lightShapeValue = value;
}
}
[Browsable(true)]
public MarqueeSpinDirection SpinDirection
{
get
{
return this.spinDirectionValue;
}
set
{
this.spinDirectionValue = value;
}
}
11. Implemente os manipuladores para os BackgroundWorker componentes DoWork

e ProgressChanged eventos.
O DoWork manipulador de eventos dorme para o número de milissegundos

especificados até UpdatePeriod que ele acione o ProgressChanged evento, até que
o código pare a animação chamando CancelAsync.
O ProgressChanged manipulador de eventos incrementa a posição da luz "base",

da qual o estado claro/escuro das outras luzes é determinado e chama o Refresh
método para fazer com que o controle se repinize.
C#
// This method is called in the worker thread's context,

// so it must not make any calls into the MarqueeBorder
// control. Instead, it communicates to the control using
// the ProgressChanged event.
//
// The only work done in this event handler is
// to sleep for the number of milliseconds specified
// by UpdatePeriod, then raise the ProgressChanged event.
System.ComponentModel.DoWorkEventArgs e)
{
// This event handler will run until the client cancels

// the background task by calling CancelAsync.
while (!worker.CancellationPending)
{
// The Argument property of the DoWorkEventArgs
// object holds the value of UpdatePeriod, which
// was passed as the argument to the RunWorkerAsync
// method.
Thread.Sleep((int)e.Argument);
// The DoWork eventhandler does not actually report

// progress; the ReportProgress event is used to
// periodically alert the control to update its state.
worker.ReportProgress(0);
}
}
// The ProgressChanged event is raised by the DoWork method.

// This event handler does work that is internal to the
// control. In this case, the currentOffset is incremented,
// and the control is told to repaint itself.
private void backgroundWorker1_ProgressChanged(
object sender,
System.ComponentModel.ProgressChangedEventArgs e)
{
this.currentOffset++;
this.Refresh();
}
12. Implemente os métodos auxiliares, IsLit e DrawLight .
O método IsLit determina a cor de uma luz em uma posição especificada. As

luzes "acesas" são desenhadas na cor fornecida pela propriedade LightColor ,
enquanto as luzes "escuras" são desenhadas na cor fornecida pela propriedade
DarkColor .
O método DrawLight desenha uma luz usando a cor, forma e posição apropriadas.
C#
// This method determines if the marquee light at lightIndex

// should be lit. The currentOffset field specifies where
// the "first" light is located, and the "position" of the
// light given by lightIndex is computed relative to this
// offset. If this position modulo lightPeriodValue is zero,
// the light is considered to be on, and it will be painted
// with the control's lightBrush.
protected virtual bool IsLit(int lightIndex)
{
int directionFactor =
(this.spinDirectionValue == MarqueeSpinDirection.CW ? -1 : 1);
return (
(lightIndex + directionFactor * this.currentOffset) %
this.lightPeriodValue == 0
);
}
protected virtual void DrawLight(

Graphics g,
Brush brush,
int xPos,
int yPos)
{
switch (this.lightShapeValue)
{
case MarqueeLightShape.Square:
{
g.FillRectangle(brush, xPos, yPos, this.lightSizeValue,
this.lightSizeValue);
break;
}
case MarqueeLightShape.Circle:
{
g.FillEllipse(brush, xPos, yPos, this.lightSizeValue,
this.lightSizeValue);
break;
}
default:
{
Trace.Assert(false, "Unknown value for light shape.");
break;
}
}
}
13. Substitua os métodos OnLayout e OnPaint.
O OnPaint método desenha as luzes ao longo das bordas do MarqueeBorder

controle.
Como o OnPaint método depende das dimensões do MarqueeBorder controle,

você precisa chamá-lo sempre que o layout for alterado. Para conseguir isso,
substitua OnLayout e chame Refresh.
C#
protected override void OnLayout(LayoutEventArgs levent)

{
base.OnLayout(levent);
// Repaint when the layout has changed.

this.Refresh();
}
// This method paints the lights around the border of the

// control. It paints the top row first, followed by the
// right side, the bottom row, and the left side. The color
// of each light is determined by the IsLit method and
// depends on the light's position relative to the value
// of currentOffset.
{
g.Clear(this.BackColor);
base.OnPaint(e);
// If the control is large enough, draw some lights.

if (this.Width > MaxLightSize &&
this.Height > MaxLightSize)
{
// The position of the next light will be incremented
// by this value, which is equal to the sum of the
// light size and the space between two lights.
int increment =
this.lightSizeValue + this.lightSpacingValue;
// Compute the number of lights to be drawn along the

// horizontal edges of the control.
int horizontalLights =
(this.Width - increment) / increment;
// Compute the number of lights to be drawn along the

// vertical edges of the control.
int verticalLights =
(this.Height - increment) / increment;
// These local variables will be used to position and

// paint each light.
int xPos = 0;
int yPos = 0;
int lightCounter = 0;
Brush brush;
// Draw the top row of lights.

for (int i = 0; i < horizontalLights; i++)
{
brush = IsLit(lightCounter) ? this.lightBrush :
this.darkBrush;
DrawLight(g, brush, xPos, yPos);
xPos += increment;
lightCounter++;
}
// Draw the lights flush with the right edge of the control.
xPos = this.Width - this.lightSizeValue;
// Draw the right column of lights.

for (int i = 0; i < verticalLights; i++)
{
this.darkBrush;
yPos += increment;
lightCounter++;
}
// Draw the lights flush with the bottom edge of the control.
yPos = this.Height - this.lightSizeValue;
// Draw the bottom row of lights.

for (int i = 0; i < horizontalLights; i++)
{
this.darkBrush;
xPos -= increment;
lightCounter++;
}
// Draw the lights flush with the left edge of the control.
xPos = 0;
// Draw the left column of lights.

for (int i = 0; i < verticalLights; i++)
{
this.darkBrush;
yPos -= increment;
lightCounter++;
}
}
}
Criar um designer personalizado para sombrear

e filtrar propriedades
A classe MarqueeControlRootDesigner fornece a implementação para o designer raiz.
Além desse designer, que opera no MarqueeControl designer personalizado, você
precisará de um designer personalizado que esteja especificamente associado ao
MarqueeBorder controle. Este designer oferece um comportamento personalizado
apropriado no contexto do designer raiz personalizado.
Especificamente, o MarqueeBorderDesigner fará o "sombreamento" de determinadas

propriedades do controle MarqueeBorder e as filtrará, alterando a interação delas com o
ambiente de design.
Interceptar chamadas para o acessador de propriedade de um componente é conhecido

como "sombreamento". Ele permite que um designer acompanhe o valor definido pelo
usuário e, opcionalmente, passe esse valor para o componente que está sendo
projetado.
Para este exemplo, as propriedades e Enabled as Visible propriedades serão sombreadas

pelo , o que impede que o usuário faça o controle invisível ou desabilitado durante o
MarqueeBorderDesigner MarqueeBorder tempo de design.
Designers também podem adicionar e remover propriedades. Para este exemplo, a
Padding propriedade será removida no momento do design, pois o MarqueeBorder
controle define programaticamente o preenchimento com base no tamanho das luzes
especificadas pela LightSize propriedade.
A classe base para MarqueeBorderDesigner é ComponentDesigner, que tem métodos que

podem alterar os atributos, propriedades e eventos expostos por um controle em
tempo de design:
PreFilterProperties
PostFilterProperties
PreFilterAttributes
PostFilterAttributes
PreFilterEvents
PostFilterEvents
Ao alterar a interface pública de um componente usando esses métodos, siga estas

regras:
Adicionar ou remover itens apenas nos métodos PreFilter
Modificar itens existentes apenas nos métodos PostFilter
Sempre chamar a implementação base primeiro nos métodos PreFilter
Sempre chamar a implementação base por último nos métodos PostFilter
Aderir a essas regras garante que todos os designers no ambiente de tempo de design
tenham uma exibição consistente de todos os componentes que estão sendo criados.
A ComponentDesigner classe fornece um dicionário para gerenciar os valores das

propriedades sombreadas, o que alivia a necessidade de criar variáveis de instância
específicas.
Para criar um designer personalizado para propriedades

de sombra e de filtro
1. Clique com o botão direito do mouse na pasta Design e adicione uma nova classe.
Dê ao arquivo de origem um nome base de MarqueeBorderDesigner.
2. Abra o arquivo de origem MarqueeBorderDesigner no Editor de Código. Na parte
superior do arquivo, importe os seguintes namespaces:
C#
using System;
3. Alterar a declaração de MarqueeBorderDesigner herdar de ParentControlDesigner.
Como o MarqueeBorder controle pode conter controles filho,

MarqueeBorderDesigner herda de ParentControlDesigner, o que manipula a
interação pai-filho.
C#
namespace MarqueeControlLibrary.Design
{
public class MarqueeBorderDesigner : ParentControlDesigner
{
4. Substitua a implementação base de PreFilterProperties.
C#
protected override void PreFilterProperties(IDictionary properties)

{
base.PreFilterProperties(properties);
if (properties.Contains("Padding"))
{
properties.Remove("Padding");
}
properties["Visible"] = TypeDescriptor.CreateProperty(
typeof(MarqueeBorderDesigner),
(PropertyDescriptor)properties["Visible"],
new Attribute[0]);
properties["Enabled"] = TypeDescriptor.CreateProperty(
typeof(MarqueeBorderDesigner),
(PropertyDescriptor)properties["Enabled"],
new Attribute[0]);
}
5. Implemente as propriedades e Visible as Enabled propriedades. Essas
implementações fazem sombreamento das propriedades do controle.
C#
public bool Visible

{
get
{
return (bool)ShadowProperties["Visible"];
}
set
{
this.ShadowProperties["Visible"] = value;
}
}
public bool Enabled

{
get
{
return (bool)ShadowProperties["Enabled"];
}
set
{
this.ShadowProperties["Enabled"] = value;
}
}
Manipular alterações de componente

A classe MarqueeControlRootDesigner fornece a experiência de tempo de design
personalizada para suas instâncias de MarqueeControl . A maior parte da funcionalidade
de tempo de design é herdada da DocumentDesigner classe. Seu código implementará
duas personalizações específicas: tratar alterações de componente e adicionar verbos de
designer.
Conforme os usuários projetam suas instâncias de MarqueeControl , o designer raiz

controlará as alterações para o MarqueeControl e os respectivos controles filho. O
ambiente de tempo de design oferece um serviço
IComponentChangeServiceconveniente para acompanhar as alterações no estado do
componente.
Você adquire uma referência a esse serviço consultando o ambiente com o GetService
método. Se a consulta for bem-sucedida, o designer poderá anexar um manipulador
para o ComponentChanged evento e executar todas as tarefas necessárias para manter
um estado consistente no tempo de design.
No caso da MarqueeControlRootDesigner classe, você chamará o Refresh método em

cada IMarqueeWidget objeto contido pelo MarqueeControl . Isso fará com que o
IMarqueeWidget objeto se repinque adequadamente quando propriedades como a de
Size seus pais forem alteradas.
Para manipular alterações de componente

1. Abra o arquivo de origem MarqueeControlRootDesigner no Editor de Código e
substitua o Initialize método. Chame a implementação base de Initialize e consulta
para o IComponentChangeService.
C#
base.Initialize(component);
IComponentChangeService cs =
GetService(typeof(IComponentChangeService))
as IComponentChangeService;
if (cs != null)
{
cs.ComponentChanged +=
new ComponentChangedEventHandler(OnComponentChanged);
}
2. Implemente o OnComponentChanged manipulador de eventos. Teste o tipo do

componente de envio e, se for um IMarqueeWidget , chame seu Refresh método.
C#
private void OnComponentChanged(

object sender,
ComponentChangedEventArgs e)
{
if (e.Component is IMarqueeWidget)
{
this.Control.Refresh();
}
}
Adicionar verbos de designer ao designer
personalizado
Um verbo do designer é um comando de menu vinculado a um manipulador de
eventos. Verbos do designer são adicionados ao menu de atalho de um componente
em tempo de design. Para obter mais informações, consulte DesignerVerb.
Você adicionará dois verbos do designer a seus designers: Executar Teste e Parar Teste.
Esses verbos permitirão que você exiba o comportamento em tempo de execução de
MarqueeControl em tempo de design. Esses verbos serão adicionados a
Quando Executar Teste é invocado, o manipulador de eventos de verbo chamará o

método StartMarquee no MarqueeControl . Quando Parar Teste é invocado, o
manipulador de eventos de verbo chamará o método StopMarquee no MarqueeControl .
A implementação dos métodos StartMarquee e StopMarquee chama esses métodos nos
controles contidos que implementam IMarqueeWidget , de modo que quaisquer
controles IMarqueeWidget independentes também participam do teste.
Para adicionar verbos do designer a seus designers

personalizados
1. Na classe MarqueeControlRootDesigner , adicione manipuladores de eventos
denominados OnVerbRunTest e OnVerbStopTest .
C#
private void OnVerbRunTest(object sender, EventArgs e)

{
MarqueeControl c = this.Control as MarqueeControl;
c.Start();
}
private void OnVerbStopTest(object sender, EventArgs e)

{
MarqueeControl c = this.Control as MarqueeControl;
c.Stop();
}
2. Conecte esses manipuladores de eventos a seus verbos do designer

correspondentes. MarqueeControlRootDesigner herda um DesignerVerbCollection
de sua classe base. Você criará dois novos DesignerVerb objetos e os adicionará a
essa coleção no Initialize método.
C#
this.Verbs.Add(
new DesignerVerb("Run Test",
new EventHandler(OnVerbRunTest))
);
this.Verbs.Add(
new DesignerVerb("Stop Test",
new EventHandler(OnVerbStopTest))
);
Criar um UITypeEditor personalizado

Quando você cria uma experiência de tempo de design personalizada para os usuários,
geralmente é desejável criar uma interação personalizada com a janela Propriedades.
Você pode fazer isso criando um UITypeEditor.
O controle MarqueeBorder expõe várias propriedades na janela Propriedades. Duas

dessas propriedades, MarqueeSpinDirection e MarqueeLightShape , são representadas por
enumerações. Para ilustrar o uso de um editor de tipos de interface do usuário, a
MarqueeLightShape propriedade terá uma classe associada UITypeEditor .
Para criar um editor de tipo de interface do usuário

personalizado
1. Abra o arquivo de origem MarqueeBorder no Editor de Código.
2. Na definição da MarqueeBorder classe, declare uma classe chamada

LightShapeEditor que deriva de UITypeEditor.
C#
// This class demonstrates the use of a custom UITypeEditor.

// It allows the MarqueeBorder control's LightShape property
// to be changed at design time using a customized UI element
// that is invoked by the Properties window. The UI is provided
// by the LightShapeSelectionControl class.
internal class LightShapeEditor : UITypeEditor
{
3. Declarar uma IWindowsFormsEditorService variável de instância chamada
editorService .
C#
private IWindowsFormsEditorService editorService = null;
4. Substitua o método GetEditStyle. Essa implementação retorna DropDown, o que

informa ao ambiente de design como exibir o LightShapeEditor .
C#
public override UITypeEditorEditStyle GetEditStyle(

System.ComponentModel.ITypeDescriptorContext context)
{
return UITypeEditorEditStyle.DropDown;
}
5. Substitua o método EditValue. Essa implementação consulta o ambiente de design

de um IWindowsFormsEditorService objeto. Se for bem-sucedida, ela criará um
LightShapeSelectionControl . O DropDownControl método é invocado para iniciar
o LightShapeEditor . O valor retornado dessa invocação é enviado de volta para o

ambiente de design.
C#
public override object EditValue(

IServiceProvider provider,
object value)
{
if (provider != null)
{
editorService =
provider.GetService(
typeof(IWindowsFormsEditorService))
as IWindowsFormsEditorService;
}
if (editorService != null)
{
LightShapeSelectionControl selectionControl =
new LightShapeSelectionControl(
(MarqueeLightShape)value,
editorService);
editorService.DropDownControl(selectionControl);
value = selectionControl.LightShape;
}
return value;
}
Criar um controle de exibição para seu

UITypeEditor personalizado
A propriedade MarqueeLightShape dá suporte a dois tipos de formas de luz: Square e
Circle . Você criará um controle personalizado usado unicamente para exibir
graficamente esses valores na janela Propriedades. Esse controle personalizado será

usado por você UITypeEditor para interagir com o janela Propriedades.
Para criar um controle de exibição para o editor de tipo

de interface do usuário personalizado
1. Adicione um novo UserControl item ao MarqueeControlLibrary projeto. Dê ao
novo arquivo de origem um nome base de LightShapeSelectionControl.
2. Arraste dois Panel controles da Caixa de Ferramentas para o

LightShapeSelectionControl . Nomeie-os squarePanel e circlePanel . Posicione-os
lado a lado. Defina a Size propriedade de ambos os Panel controles como (60, 60).
Defina a Location propriedade do squarePanel controle como (8, 10). Defina a
Location propriedade do circlePanel controle como (80, 10). Por fim, defina a Size
propriedade como LightShapeSelectionControl (150, 80).
3. Abra o arquivo de origem LightShapeSelectionControl no Editor de Código. Na

parte superior do arquivo, importe o namespace System.Windows.Forms.Design:
C#
4. Implementar Click manipuladores de eventos para controles e controles

squarePanel circlePanel . Esses métodos invocam CloseDropDown para encerrar a
sessão de edição personalizada UITypeEditor .
C#
private void squarePanel_Click(object sender, EventArgs e)
{
this.lightShapeValue = MarqueeLightShape.Square;
this.Invalidate( false );
this.editorService.CloseDropDown();
}
private void circlePanel_Click(object sender, EventArgs e)

{
this.lightShapeValue = MarqueeLightShape.Circle;
this.Invalidate( false );
this.editorService.CloseDropDown();
}
5. Declarar uma IWindowsFormsEditorService variável de instância chamada

editorService .
C#
private IWindowsFormsEditorService editorService;
6. Declare uma variável de instância MarqueeLightShape chamada lightShapeValue .
C#
private MarqueeLightShape lightShapeValue = MarqueeLightShape.Square;
7. LightShapeSelectionControl No construtor, anexe os Click manipuladores de

eventos aos squarePanel eventos e circlePanel Click controles. Além disso, defina
uma sobrecarga de construtor que atribua o valor MarqueeLightShape do ambiente
de design ao campo lightShapeValue .
C#
// This constructor takes a MarqueeLightShape value from the

// design-time environment, which will be used to display
// the initial state.
public LightShapeSelectionControl(
MarqueeLightShape lightShape,
IWindowsFormsEditorService editorService )
{
// This call is required by the designer.
// Cache the light shape value provided by the
// design-time environment.
this.lightShapeValue = lightShape;
// Cache the reference to the editor service.

this.editorService = editorService;
// Handle the Click event for the two panels.

this.squarePanel.Click += new EventHandler(squarePanel_Click);
this.circlePanel.Click += new EventHandler(circlePanel_Click);
}
8. Dispose No método, desanexe os Click manipuladores de eventos.
C#
protected override void Dispose( bool disposing )

{
if( disposing )
{
// Be sure to unhook event handlers
// to prevent "lapsed listener" leaks.
this.squarePanel.Click -=
new EventHandler(squarePanel_Click);
this.circlePanel.Click -=
new EventHandler(circlePanel_Click);
if(components != null)
{
}
}
base.Dispose( disposing );
}
9. Em Gerenciador de Soluções, clique no botão Mostrar Todos os Arquivos. Abra o

arquivo LightShapeSelectionControl.Designer.cs ou
LightShapeSelectionControl.Designer.vb e remova a definição padrão do Dispose
método.
10. Implemente a propriedade LightShape .
C#
// LightShape is the property for which this control provides

// a custom user interface in the Properties window.
public MarqueeLightShape LightShape
{
get
{
return this.lightShapeValue;
}
set
{
if( this.lightShapeValue != value )
{
this.lightShapeValue = value;
}
}
}
11. Substitua o método OnPaint. Essa implementação desenhará um círculo e um

quadrado preenchidos. Ela também realçará o valor selecionado desenhando uma
borda ao redor de uma forma ou de outra.
C#

{
base.OnPaint (e);
using(
Graphics gSquare = this.squarePanel.CreateGraphics(),
gCircle = this.circlePanel.CreateGraphics() )
{
// Draw a filled square in the client area of
// the squarePanel control.
gSquare.FillRectangle(
Brushes.Red,
0,
0,
this.squarePanel.Width,
this.squarePanel.Height
);
// If the Square option has been selected, draw a

// border inside the squarePanel.
if( this.lightShapeValue == MarqueeLightShape.Square )
{
gSquare.DrawRectangle(
Pens.Black,
0,
0,
this.squarePanel.Width-1,
this.squarePanel.Height-1);
}
// Draw a filled circle in the client area of

// the circlePanel control.
gCircle.Clear( this.circlePanel.BackColor );
gCircle.FillEllipse(
Brushes.Blue,
0,
0,
this.circlePanel.Width,
this.circlePanel.Height
);
// If the Circle option has been selected, draw a

// border inside the circlePanel.
if( this.lightShapeValue == MarqueeLightShape.Circle )
{
gCircle.DrawRectangle(
Pens.Black,
0,
0,
this.circlePanel.Width-1,
this.circlePanel.Height-1);
}
}
}
Testar seu controle personalizado no Designer

Neste ponto, você pode compilar o projeto MarqueeControlLibrary . Teste a
implementação, criando um controle que herda da classe MarqueeControl e usando-o
em um formulário.
Para criar uma implementação personalizada de

MarqueeControl
1. Abra DemoMarqueeControl no Designer de Formulários do Windows. Isso cria uma
instância do tipo DemoMarqueeControl e a exibe em uma instância do tipo
2. Na Caixa de Ferramentas, abra a guia Componentes MarqueeControlLibrary .

Você verá os MarqueeBorder controles disponíveis MarqueeText para seleção.
3. Arraste uma instância do controle MarqueeBorder para a superfície de design

DemoMarqueeControl . Encaixe esse controle MarqueeBorder no controle pai.
4. Arraste uma instância do controle MarqueeText para a superfície de design

DemoMarqueeControl .
6. Clique com o botão direito do mouse no DemoMarqueeControl e, do menu de
atalho, selecione a opção Executar Teste para iniciar a animação. Clique em Parar
Teste para interromper a animação.
7. Abra o Formulário1 no modo Design.
8. Coloque dois Button controles no formulário. Nomeie-os startButton e

stopButton altere os valores de Text propriedade para Iniciar e Parar,
respectivamente.
9. Implementar Click manipuladores de eventos para ambos os Button controles.
10. Na Caixa de Ferramentas, abra a guia Componentes MarqueeControlTest . Você

verá o DemoMarqueeControl disponível para seleção.
11. Arraste uma instância de DemoMarqueeControl na superfície de design Form1.
12. Click Nos manipuladores de eventos, invoque o e Stop os Start métodos no

DemoMarqueeControl .
C#
private void startButton_Click(object sender, System.EventArgs e)

{
this.demoMarqueeControl1.Start();
}
private void stopButton_Click(object sender, System.EventArgs e)

{
this.demoMarqueeControl1.Stop();
}
13. Defina o projeto MarqueeControlTest como o projeto de inicialização e execute-o.

Você verá o formulário exibindo seu DemoMarqueeControl . Selecione o botão Iniciar
para iniciar a animação. Você deve ver o texto piscando e as luzes se movendo ao
redor da borda.
Próximas etapas
O MarqueeControlLibrary demonstra uma implementação simples de controles
personalizados e designers associados. Você pode tornar esse exemplo mais sofisticado
de várias maneiras:
Altere os valores da propriedade para DemoMarqueeControl no designer. Adicione
mais controles MarqueBorder e encaixe-os dentro das respectivas instâncias pai
para criar um efeito aninhado. Faça experiências com configurações diferentes
para o UpdatePeriod e as propriedades relacionadas à luz.
Crie suas próprias implementações de IMarqueeWidget . Você pode, por exemplo,

criar uma "sinalização de neon" piscando ou uma sinalização animada com várias
imagens.
Personalize ainda mais a experiência de tempo de design. Você pode tentar

sombrear mais propriedades do que Enabled e Visibleadicionar novas
propriedades. Adicione novos verbos do designer para simplificar tarefas comuns,
como encaixar controles filho.
Licencie o MarqueeControl .
Controle o modo como os controles são serializados e como o código é gerado

para eles. Para obter mais informações, consulte Geração e compilação de código-
fonte dinâmico.
Confira também
UserControl
ParentControlDesigner
DocumentDesigner
IRootDesigner
DesignerVerb
UITypeEditor
BackgroundWorker
Como criar controles para Windows
Forms
Artigo • 02/06/2023
Um controle representa um link gráfico entre o usuário e o programa. Um controle

pode fornecer ou processar dados, aceitar a entrada do usuário, responder a eventos ou
executar quaisquer outras funções que conectam o usuário ao aplicativo. Como um
controle é essencialmente um componente com uma interface gráfica, ele pode cumprir
qualquer função realizada por um componente, além de oferecer interação ao usuário.
Os controles são criados para atender a objetivos específicos e a criação de controles é
apenas outra tarefa de programação. Com isso em mente, as etapas a seguir
representam uma visão geral do processo de criação de controles. Os links fornecem
informações adicionais sobre as etapas individuais.
Criar um controle
1. Determine o que o controle deverá realizar ou qual será o papel executado por ele
no aplicativo. Os fatores a serem considerados incluem:
Que tipo de interface gráfica será necessária?
Quais as interações específicas do usuário esse controle manipulará?
A funcionalidade necessária é fornecida por algum dos controles existentes?
É possível obter a funcionalidade necessária combinando vários controles do

Windows Forms?
2. Caso seja necessário um modelo de objeto para o controle, determine como a

funcionalidade será distribuída ao longo do modelo de objeto e divida-a entre o
controle e os subobjetos. Um modelo de objeto poderá ser útil se você estiver
planejando um controle complexo ou desejar incorporar várias funcionalidades.
3. Determine o tipo de controle (por exemplo, controle de usuário, controle

personalizado, controle herdado do Windows Forms) necessário. Para obter
detalhes, consulte Recomendações do Tipo de Controle e Variedades de Controles
Personalizados.
4. Expresse funcionalidades como propriedades, métodos e eventos do controle e

seus subobjetos ou estruturas subsidiárias e atribua níveis de acesso apropriados
(por exemplo, público, protegido e assim por diante).
5. Se uma pintura personalizada for necessária para o controle, adicione código a ele.
Para obter detalhes, consulte Pintura e renderização de controle personalizado.
6. Se o controle herdar, você poderá testar seu comportamento de

UserControlruntime criando o projeto de controle e executando-o no Contêiner
de Teste usercontrol. Para obter mais informações, consulte Como testar o
comportamento em tempo de execução de um UserControl.
7. Também é possível testar e depurar o controle criando um novo projeto, como um

Aplicativo do Windows, e colocá-lo em um contêiner. Esse processo é
demonstrado como parte do Passo a passo: criação de um controle composto.
8. Ao adicionar cada recurso, adicione recursos ao projeto de teste para praticar a

nova funcionalidade.
9. Repita, refinando o design.
10. Empacote e implante o controle. Para obter detalhes, consulte Primeiro olhar para
a implantação no Visual Studio.
Confira também
Como criar controles compostos
Artigo • 02/06/2023
Os controles de composição podem ser usados de várias maneiras. É possível criá-los

como parte de um projeto de aplicativo da área de trabalho do Windows e usá-los
somente em formulários do projeto. Também é possível criá-los em um projeto da
Biblioteca de Controles do Windows, compilar o projeto em um assembly e usar os
controles em outros projetos. Você pode até herdar deles e usar a herança visual para
personalizá-los rapidamente para fins especiais.
Criar um controle de composição

1. No Visual Studio, crie um novo projeto de aplicativo do Windows e nomeie-o
como DemoControlHost.
2. No menu Projeto , clique em Adicionar Controle de Usuário.
3. Na caixa de diálogo Adicionar Novo Item, dê ao arquivo de classe (arquivo .vb ou

.cs) o nome que você deseja que o controle de composição tenha.
4. Selecione o botão Adicionar para criar o arquivo de classe para o controle

composto.
5. Adicione os controles da Caixa de Ferramentas à superfície do controle de

composição.
6. Coloque o código em procedimentos de evento, a fim de manipular eventos

gerados pelo controle de composição ou por seus controles constituintes.
7. Feche o designer do controle de composição e salve o arquivo quando solicitado.
8. No menu Compilar, clique em Compilar Solução.
O projeto deve ser criado para que os controles personalizados apareçam na Caixa
de Ferramentas.
9. Use a guia DemoControlHost da Caixa de Ferramentas para adicionar instâncias

do controle ao Form1 .
Criar uma biblioteca de classes de controle

1. Abra um novo projeto da Biblioteca de Controles do Windows.
Por padrão, o projeto contém um controle de composição.
2. Adicione controles e código, conforme descrito no procedimento acima.
3. Escolha um controle que as classes de herança não alterarão e defina a

propriedade Modificadores desse controle como Privada.
4. Compile a DLL.
Herdar de um controle de composição em uma

biblioteca de classes de controle
1. No menu Arquivo, aponte para Adicionar e selecione Novo Projeto para adicionar
um novo projeto dos Aplicativos do Windows à solução.
2. No Gerenciador de Soluções, clique com o botão direito do mouse na pasta

Referências do novo projeto e escolha Adicionar Referência para abrir a caixa de
diálogo Adicionar Referência.
3. Selecione a guia Projetos e clique duas vezes no projete de biblioteca de controle.
4. No menu Compilar, clique em Compilar Solução.
5. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto de

biblioteca de controle e selecione Adicionar Novo Item no menu de atalho.
6. Selecione o modelo Controle de Usuário Herdado na caixa de diálogo Adicionar

Novo Item.
7. Na caixa de diálogo Selecionador de Herança, clique duas vezes no controle do

qual você deseja herdar.
Um novo controle será adicionado ao projeto.
8. Abra o designer visual do novo controle e adicione outros controles constituintes.
É possível ver os controles constituintes que foram herdados do controle

composição na DLL e alterar as propriedades de controles cuja propriedade
Modificadores for Pública. Não é possível alterar as propriedades do controle cuja
propriedade Modificadores for Privada.
Confira também
Passo a passo: Herdando de um controle Windows Forms
Recomendações do tipo de controle
Artigo • 02/06/2023
Para combinar a funcionalidade de um ou mais controles do Windows Forms no modo

personalizado, é possível criar um controle de usuário. Os controles de usuário
combinam rápido desenvolvimento de controle, a funcionalidade padrão de controle do
Windows Forms e a versatilidade de propriedades e métodos personalizados. Ao
começar a criar um controle de usuário tomamos contato com um designer visível,
sobre o qual é possível colocar controles padrão do Windows Forms. Esses controles
mantêm todas suas funcionalidades inerentes, bem como a aparência e o
comportamento (look and feel) dos controles padrão. No entanto, uma vez que esses
controles são incorporados no controle de usuário, eles não estão mais disponíveis por
meio de código. O controle de usuário faz sua própria pintura e também manipula toda
a funcionalidade básica associada com controles.
Para criar um controle de usuário

1. Crie um novo projeto da Biblioteca de Controle do Windows no Visual Studio.
Um novo projeto é criado com um controle de usuário em branco.
2. Arraste os controles da aba Windows Forms da Caixa de ferramentas para o

designer.
3. Esses controles devem ser posicionados e projetados como se deseja que eles
apareçam no controle de usuário final. Se quiser permitir que os desenvolvedores
acessem os controles constituintes, será preciso declará-los como públicos ou
exibir seletivamente as propriedades do controle constituinte. Para mais detalhes,
consulte Como expor propriedades de controles constituintes.
4. Implemente os métodos ou propriedades personalizados que o controle

incorporará.

usercontrol. Para obter mais informações, consulte Como testar o comportamento
em tempo de execução de um UserControl.
Confira também
Solucionar problemas de manipuladores de eventos herdados no Visual Basic
Como herdar de controles dos Windows
Forms existentes
Artigo • 02/06/2023
Se você quiser estender a funcionalidade de um controle existente, poderá criar um

controle derivado de um controle existente por meio de herança. Ao herdar de um
controle existente, você herda todas as funcionalidades e propriedades visuais desse
controle. Por exemplo, se você estivesse criando um controle do qual herdou Button,
seu novo controle ficaria e agiria exatamente como um controle padrão Button . Dessa
forma, você poderia estender ou modificar a funcionalidade de seu novo controle por
meio da implementação de métodos e propriedades personalizados. Em alguns
controles, você também pode alterar a aparência visual do controle herdado
substituindo seu OnPaint método.
Criar um controle herdado

1. No Visual Studio, crie um novo projeto de aplicativo Windows Forms.
2. No menu Projeto, escolha Adicionar Novo Item.
A caixa de diálogo Adicionar Novo Item aparecerá.
3. Na caixa de diálogo Adicionar Novo Item, clique duas vezes em Controle

personalizado.
Um novo controle personalizado será adicionado ao projeto.
4. Se você estiver usando:
No Visual Basic, na parte superior do Gerenciador de Soluções, clique em

Mostrar Todos os Arquivos. Expanda CustomControl1.vb e abra
CustomControl1.Designer.vb no Editor de Código.
C#, abra CustomControl1.cs no Editor de Código.
5. Localize a declaração de classe, que herda de Control.
6. Altere a classe base para o controle do qual você deseja herdar.
Por exemplo, se você quiser herdar, altere a declaração de Buttonclasse para o

seguinte:
C#
public partial class CustomControl1 : System.Windows.Forms.Button
7. Se você estiver usando Visual Basic, salve e feche CustomControl1.Designer.vb.

Abra CustomControl1.vb no Editor de Código.
8. Implemente os métodos ou propriedades personalizados que o controle

incorporará.
9. Se você quiser modificar a aparência gráfica do controle, substitua o OnPaint

método.
７ Observação
A substituição OnPaint não permitirá que você modifique a aparência de

todos os controles. Esses controles que têm toda a pintura feita pelo
Windows (por exemplo) TextBoxnunca chamam seu OnPaint método e,
portanto, nunca usarão o código personalizado. Consulte a documentação da
Ajuda para o controle específico que você deseja modificar para ver se o
OnPaint método está disponível. Para obter uma lista de todos os controles
do Windows Forms, consulte Controles a serem usados no Windows Forms.
Se um controle não tiver OnPaint sido listado como um método membro,
você não poderá alterar sua aparência substituindo esse método. Para obter
mais informações sobre pintura personalizada, consulte Pintura e
renderização de controle personalizado.
C#
protected override void OnPaint(PaintEventArgs pe)

{
base.OnPaint(pe);
// Insert code to do custom painting.
// If you want to completely change the appearance of your control,
// do not call base.OnPaint(pe).
}
10. Salve e teste seu controle.
Confira também
Solucionando problemas de manipuladores de eventos herdados no Visual Basic
Artigo • 02/06/2023
Se você quiser criar um controle completamente personalizado para usar em um

Formulário do Windows, você deve herdar da Control classe. Embora a herdação da
Control classe exija que você execute mais planejamento e implementação, ela também
fornece o maior intervalo de opções. Ao herdar, Controlvocê herda a funcionalidade
básica que faz com que os controles funcionem. A funcionalidade inerente à classe
manipula a Control entrada do usuário por meio do teclado e do mouse, define os
limites e o tamanho do controle, fornece um identificador de janelas e fornece
manipulação e segurança de mensagens. Ela não incorpora nenhum pintura, que nesse
caso é a renderização efetiva da interface gráfica do controle, nem incorpora qualquer
funcionalidade de interação do usuário específica. Você deve fornecer todos esses
aspectos por meio de código personalizado.
Criar um controle personalizado

1. No Visual Studio, crie um novo projeto da Biblioteca de Controle do Windows ou
aplicativodo Windows .
2. No menu Projeto, escolha Adicionar Classe.
3. Na caixa de diálogo Adicionar Novo Item, clique em Controle Personalizado.
Um novo controle personalizado será adicionado ao projeto.
4. Pressione F7 para abrir o Editor de Código para seu controle personalizado.
5. Localize o OnPaint método, que estará vazio, exceto por uma chamada para o
OnPaint método da classe base.
6. Modifique o código para incorporar qualquer pintura personalizada desejada ao

seu controle.
Para obter informações sobre como escrever código para renderizar elementos
gráficos para controles, consulte Pintura e renderização de controle personalizado.
7. Implemente os métodos, propriedades ou eventos personalizados que o controle

incorporará.
8. Salve e teste seu controle.

Confira também
Solucionando problemas de manipuladores de eventos herdados no Visual Basic
Como alinhar um controle às bordas de
formulários na hora do design
Artigo • 02/06/2023
Você pode fazer com que o controle se alinhe à borda dos formulários definindo o valor
da Dock propriedade. Essa propriedade determina onde reside o controle no formulário.
A Dock propriedade pode ser definida com os seguintes valores:
Configuração Efeito no seu controle
Bottom Encaixa na parte inferior do formulário.
Fill Preenche todo o espaço restante no formulário.
Left Encaixa do lado esquerdo do formulário.
None Não encaixa em nenhum lugar e aparece no local especificado por ele Location.
Right Encaixa do lado direito do formulário.
Top Encaixa na parte superior do formulário.
Esses valores também podem ser definidos no código. Para obter mais informações,
consulte Como alinhar um controle às bordas de formulários.
Definir a propriedade Dock para o controle em

tempo de design
1. No Designer de Windows Forms no Visual Studio, selecione seu controle.
2. Na janela Propriedades , clique na caixa suspensa ao lado da Dock propriedade.
Uma interface gráfica que representa as seis configurações possíveis Dock é

exibida.
3. Escolha a configuração apropriada.
4. O controle agora será encaixado da maneira especificada pela configuração.
Confira também
Control.Dock
Control.Anchor
Como: Alinhar um controle às bordas de formulários
de alinhamento
TableLayoutPanel
FlowLayoutPanel
Como exibir um controle na caixa de
diálogo Escolher Itens da Caixa de
Ferramentas
Artigo • 02/06/2023
Ao desenvolver e distribuir controles, convém que esses controles apareçam na caixa de

diálogo Escolher Itens da Caixa de Ferramentas do Visual Studio, que é exibida quando
você clica com o botão direito do mouse na Caixa de Ferramentas e seleciona Itens de
Escolha. Você pode permitir que seu controle apareça na caixa de diálogo usando o
procedimento de registro AssemblyFoldersEx.
Para exibir seu controle na caixa de diálogo Escolher Itens da Caixa de Ferramentas:
Instale o assembly do controle no cache de assembly global. Para obter mais

informações, consulte Como instalar um assembly no cache de assembly global.
-ou-
Registre o controle e assemblies de tempo de design associados usando o

procedimento de registro AssemblyFoldersEx. AssemblyFoldersEx é um local de
Registro em que os fornecedores de terceiros armazenam caminhos para cada
versão da estrutura à qual dão suporte. A resolução de tempo de design pode
procurar neste local do Registro para localizar assemblies de referência. O script de
Registro pode especificar os controles que deseja que apareçam na caixa de
ferramentas.
Confira também
Como instalar um assembly no cache de assembly global
Como: Fornecer um bitmap da caixa de
ferramentas para um controle
Artigo • 02/06/2023
Se você quiser que um ícone especial para seu controle apareça na caixa de
ferramentas do Visual Studio, você poderá especificar uma imagem específica usando o
ToolboxBitmapAttribute. Esta classe é um atributo, um tipo especial de classe que você
pode anexar a outras classes. Para obter mais informações sobre atributos, consulte a
visão geral de atributos (Visual Basic) para Visual Basic ou Atributos (C#) para C#.
Usando o ToolboxBitmapAttribute, você pode especificar uma cadeia de caracteres que

indica o caminho e o nome do arquivo para um bitmap de 16 por 16 pixels. O bitmap
aparece ao lado de seu controle quando adicionado à Caixa de ferramentas. Você
também pode especificar um Type, nesse caso, o bitmap associado a esse tipo é
carregado. Se você especificar uma cadeia de caracteres e uma Type cadeia de
caracteres, o controle procurará um recurso de imagem com o nome especificado pelo
parâmetro de cadeia de caracteres no assembly que contém o tipo especificado pelo
Type parâmetro.
Especificar um bitmap da caixa de ferramentas

para seu controle
1. Adicione a ToolboxBitmapAttribute declaração de classe do controle antes da
palavra-chave para visual Class Basic e acima da declaração de classe para Visual
C#.
C#
// Specifies the bitmap associated with the Button type.

[ToolboxBitmap(typeof(Button))]
class MyControl1 : UserControl
{
}
// Specifies a bitmap file.
[ToolboxBitmap(@"C:\Documents and Settings\Joe\MyPics\myImage.bmp")]
class MyControl2 : UserControl
{
}
// Specifies a type that indicates the assembly to search, and the name
// of an image resource to look for.
[ToolboxBitmap(typeof(MyControl), "MyControlBitmap")]
class MyControl : UserControl
{
}
2. Recompile o projeto.
７ Observação
O bitmap não aparece na caixa de ferramentas para controles e componentes

gerados automaticamente. Para ver o bitmap, recarregue o controle usando a
caixa de diálogo Escolher Itens da Caixa de Ferramentas. Para mais
informações, consulte Instruções passo a passo: preenchendo de forma
automática a caixa de ferramentas com componentes personalizados.
Confira também
ToolboxBitmapAttribute
Visão geral de atributos (Visual Basic)
Atributos (C#)
Como testar o comportamento em
tempo de execução de um UserControl
Artigo • 02/06/2023
Ao desenvolver um UserControl, você precisa testar seu comportamento em tempo de

execução. É possível criar um projeto de aplicativo separado do Windows e colocar o
controle em um formulário de teste, porém esse procedimento é inconveniente. Uma
maneira mais rápida e fácil é usar o Contêiner de teste de UserControl fornecido pelo
Visual Studio. Esse contêiner de teste é iniciado diretamente do seu projeto de
biblioteca de controles do Windows.
） Importante
Para que o contêiner de teste carregue o seu UserControl, o controle deve ter pelo
menos um construtor público.
７ Observação
Não é possível testar um controle do Visual C++ usando o Contêiner de teste de

UserControl.
Testar o comportamento em tempo de

execução de um UserControl
1. No Visual Studio, crie um projeto de biblioteca de controle do Windows e nomeie-
o como TestContainerExample.
2. No Designer de Windows Forms, arraste um Label controle da Caixa de

Ferramentas para a superfície de design do controle.
3. Pressione F5 para compilar o projeto e executar o Contêiner de Teste usercontrol.

O contêiner de teste aparece com o seu UserControl no painel Visualização .
4. Selecione a BackColor propriedade exibida no PropertyGrid controle à direita do

painel visualização . Altere seu valor para ControlDark. Observe que o controle é
alterado para uma cor mais escura. Tente alterar outros valores de propriedade e
observar o efeito em seu controle.
5. Clique na caixa de seleção Controle de usuário Dock Fill abaixo do painel
Visualização. Observe que o controle é redimensionado para preencher o painel.
Redimensione o contêiner de teste e observe como o controle é redimensionado
com o painel.
6. Feche o contêiner de teste.
7. Adicione outro controle de usuário ao projeto TestContainerExample.
8. No Designer de Windows Forms, arraste um Button controle da Caixa de

9. Pressione F5 para compilar o projeto e executar o contêiner de teste.
10. Clique em Selecionar ControleComboBox de Usuário para alternar entre os dois

controles de usuário.
Testar controles de usuário de outro projeto

É possível testar os controles de usuário de outros projetos no contêiner de teste do seu
projeto atual.
1. No Visual Studio, crie um projeto de biblioteca de controle do Windows e nomeie-

o como TestContainerExample2.
2. No Designer de Windows Forms, arraste um RadioButton controle da Caixa de

3. Pressione F5 para compilar o projeto e executar o contêiner de teste. O contêiner

de teste aparece com o seu UserControl no painel Visualização .
4. Clique no botão Carregar .
5. Na caixa de diálogo Abrir , navegue até TestContainerExample.dll, que você criou

no procedimento anterior. Selecione TestContainerExample.dll e clique no botão
Abrir para carregar os controles do usuário.
6. Use o Select User ControlComboBox para alternar entre os dois controles de

usuário do projeto TestContainerExample .
Confira também
UserControl
Designer de Controle de Usuário
página de erro do Designer Windows
Forms
Artigo • 21/03/2023
Se o Designer de Windows Forms não for carregado devido a um erro no código, em

um componente de terceiros ou em outro lugar, você verá uma página de erro em vez
do designer. Esta página de erro não significa necessariamente um bug no designer. O
bug pode estar em algum lugar na página code-behind chamada <your-form-name>.
Designer.cs. Os erros aparecem em barras amarelas recolhidas com um link para ir para
o local do erro na página de código.
Você pode optar por ignorar os erros e continuar carregando o designer clicando em
Ignorar e Continuar. Essa ação pode resultar em um comportamento inesperado, por
exemplo, os controles podem não aparecer na superfície de design.
Instâncias desse erro

Quando a barra de erros amarela é expandida, cada instância do erro é listada. Muitos
tipos de erro incluem um local exato no seguinte formato: [Nome do Projeto][Nome do
Formulário] Linha:[Número da Linha] Coluna:[Número da Coluna]. Se uma pilha de
chamadas estiver associada ao erro, você poderá clicar no link Mostrar Pilha de
Chamadas para vê-la. Examinar a pilha de chamadas pode ajudá-lo a resolver o erro.
７ Observação
Para aplicativos do Visual Basic, a página de erro em tempo de design não

exibe mais de um erro, mas pode exibir várias instâncias do mesmo erro.
Para aplicativos C++, os erros não têm links de localização de código.
Ajuda com esse erro

Se um tópico de ajuda para o erro estiver disponível, clique no link Ajuda do MSDN
para navegar diretamente até a página de ajuda.
Postagens do fórum sobre este erro

Clique no link Pesquisar nos Fóruns do MSDN as postagens relacionadas a este link de
erro para navegar até os fóruns da Rede de Desenvolvedores da Microsoft. Talvez você
queira pesquisar especificamente os fóruns Windows Forms Designer ou Windows
Forms .
Erros de tempo de design

Esta seção lista alguns dos erros que você pode encontrar.
'<identifier name>' não é um identificador válido
Esse erro indica que um campo, método, evento ou objeto é nomeado incorretamente.
'<name>' já existe em '<nome> do projeto'

Mensagem de erro: "'<name>' já existe em '<nome> do projeto'. Insira um nome
exclusivo."
Você especificou um nome para um formulário herdado que já existe no projeto. Para
corrigir esse erro, dê ao formulário herdado um nome exclusivo.
'<Nome> da guia Caixa de Ferramentas' não é uma

categoria de caixa de ferramentas
Um designer de terceiros tentou acessar uma guia na Caixa de Ferramentas que não
existe. Entre em contato com o fornecedor do componente.
Um analisador de linguagem solicitado não está instalado

Mensagem de erro: "Um analisador de idioma solicitado não está instalado. O nome do
analisador de idioma é '{0}'."
O Visual Studio tentou carregar um designer registrado para o tipo de arquivo, mas não
pôde. Isso provavelmente ocorre devido a um erro que ocorreu durante a instalação.
Entre em contato com o fornecedor do idioma que você está usando para obter uma
correção.
Um serviço necessário para gerar e analisar o código

fonte não foi encontrado
Esse é um problema com um componente de terceiros. Entre em contato com o
fornecedor do componente.
Ocorreu uma exceção ao tentar criar uma instância de

'<nome> do objeto'
Mensagem de erro: "Ocorreu uma exceção ao tentar criar uma instância de '<nome> do
objeto'. A exceção era "<cadeia de caracteres de> exceção".
Um designer de terceiros solicitou que o Visual Studio criava um objeto, mas o objeto
gerou um erro. Entre em contato com o fornecedor do componente.
Outro editor tem '<nome> do documento' aberto em um

modo incompatível
Mensagem de erro: "Outro editor tem '<nome> do documento' aberto em um modo
incompatível. Feche o editor e tente essa operação novamente."
Esse erro surgirá se você tentar abrir um arquivo que já esteja aberto em outro editor. O
editor que já tem o arquivo aberto é mostrado. Para corrigir esse erro, feche o editor
que tem o arquivo aberto e tente novamente.
Outro editor fez alterações no '<nome> do documento'

Feche e reabra o designer para que as alterações entrem em vigor. Normalmente, o
Visual Studio recarrega automaticamente um designer depois que as alterações são
feitas. No entanto, outros designers, como designers de componentes de terceiros,
podem não dar suporte ao comportamento de recarregamento. Nesse caso, o Visual
Studio solicita que você feche e reabra o designer manualmente.
Outro editor tem o arquivo aberto em um modo

incompatível
Mensagem de erro: "Outro editor tem o arquivo aberto em um modo incompatível.
Feche o editor e tente essa operação novamente."
Essa mensagem é semelhante a "Outro editor tem '<nome> do documento' aberto em

um modo incompatível", mas o Visual Studio não consegue determinar o nome do
arquivo. Para corrigir esse erro, feche o editor que tem o arquivo aberto e tente
novamente.
A classificação de matriz '<rank in array>' é muito alta

O Visual Studio só dá suporte a matrizes de dimensão única no bloco de código
analisado pelo designer. Matrizes multidimensionais são válidas fora dessa área.
Não foi possível abrir o assembly '<nome> do assembly'

Mensagem de erro: "Não foi possível abrir o assembly '<nome> do assembly'. Verifique
se o arquivo ainda existe."
Essa mensagem de erro surge quando você tenta abrir um arquivo que não pôde ser
aberto. Verifique se o arquivo existe e se é um assembly válido.
Tipo de elemento inválido. Esse serializador espera um

elemento do tipo '<type name>'
Esse é um problema com um componente de terceiros. Entre em contato com o
Não é possível acessar a caixa de ferramentas do Visual

Studio neste momento
O Visual Studio fez uma chamada para a Caixa de Ferramentas, que não estava
disponível. Se você vir esse erro, registre um problema usando Relatar um problema.
Não é possível associar um manipulador de eventos ao

evento '<nome> do evento' porque ele é somente leitura
Esse erro geralmente surge quando você tenta conectar um evento a um controle
herdado de uma classe base. Se a variável de membro do controle for privada, o Visual
Studio não poderá conectar o evento ao método . Os controles herdados privadamente
não podem ter eventos adicionais associados a eles.
Não é possível criar um nome de método para o

componente solicitado porque ele não é um membro do
recipiente de design
O Visual Studio tentou adicionar um manipulador de eventos a um componente que
não tem uma variável de membro no designer. Entre em contato com o fornecedor do
componente.
Não é possível nomear o objeto '<name>' porque ele já

está chamado de '<name>'
Esse é um erro interno no serializador do Visual Studio. Ele indica que o serializador
tentou nomear um objeto duas vezes, o que não tem suporte. Se você vir esse erro,
registre um problema usando Relatar um problema.
Não é possível remover ou destruir o componente

herdado '<nome> do componente'
Os controles herdados estão sob a propriedade de sua classe herdada. As alterações no
controle herdado devem ser feitas na classe da qual o controle se origina. Portanto,
você não pode renomeá-lo ou destruí-lo.
A categoria '<Nome> da guia Caixa de Ferramentas' não

tem uma ferramenta para a classe '<nome> da classe'
O designer tentou fazer referência a uma classe em uma determinada guia Caixa de
Ferramentas, mas a classe não existe. Entre em contato com o fornecedor do
componente.
A classe '<nome da> classe' não tem construtor

correspondente
Um designer de terceiros pediu ao Visual Studio para criar um objeto com parâmetros
específicos no construtor que não existe. Contate o fornecedor do componente.
Falha na geração de código para a propriedade

'<property name>'
Este é um wrapper genérico para um erro. A cadeia de caracteres de erro que
acompanha essa mensagem fornecerá mais detalhes sobre a mensagem de erro e terá
um link para um tópico de ajuda mais específico. Para corrigir esse erro, resolva o erro
especificado na mensagem de erro acrescentada a esse erro.
O componente '<component name>' não chamou

Container.Add() em seu construtor
Esse é um erro no componente que você acabou de carregar ou colocar no formulário.
Indica que o componente não se adicionou ao controle de contêiner (seja outro
controle ou um formulário). O designer continuará funcionando, mas pode haver
problemas com o componente em tempo de execução.
Para corrigir o erro, entre em contato com o fornecedor do componente. Ou, se for um
componente que você criou, chame o IContainer.Add método no construtor do
componente.
O nome do componente não pode ser deixado em

branco
Esse erro surge quando você tenta renomear um componente para um valor vazio.
Não foi possível acessar a variável '<nome> da variável'

porque ela ainda não foi inicializada
Esse erro pode surgir devido a dois cenários. Um fornecedor de componentes de
terceiros tem um problema com um controle ou componente que ele distribuiu ou o
código que você escreveu tem dependências recursivas entre componentes.
Para corrigir esse erro, verifique se o código não tem uma dependência recursiva. Se
estiver livre desses problemas, observe o texto exato da mensagem de erro e entre em
contato com o fornecedor do componente.
Não foi possível localizar o tipo '<type name>'

Mensagem de erro: "Não foi possível localizar o tipo '<nome> do tipo'. Verifique se o
assembly que contém esse tipo é referenciado. Se esse tipo fizer parte do seu projeto de
desenvolvimento, verifique se o projeto foi criado com êxito."
Esse erro ocorreu porque uma referência não foi encontrada. Verifique se o tipo
indicado na mensagem de erro é referenciado e se todos os assemblies exigidos pelo
tipo também são referenciados. Muitas vezes, o problema é que um controle na solução
não foi criado. Para compilar, selecione Compilar Solução no menu Compilar . Caso
contrário, se o controle já tiver sido criado, adicione uma referência manualmente no
menu de clique com o botão direito do mouse da pasta Referências ou Dependências
no Gerenciador de Soluções.
Não foi possível carregar o tipo '<type name>'

Mensagem de erro: "Não foi possível carregar o tipo '<type name>'. Certifique-se de
que o assembly que contém esse tipo seja adicionado às referências do projeto."
O Visual Studio tentou conectar um método de manipulação de eventos e não

conseguiu encontrar um ou mais tipos de parâmetro para o método . Isso geralmente é
causado por uma referência ausente. Para corrigir esse erro, adicione a referência que
contém o tipo ao projeto e tente novamente.
Não foi possível localizar os modelos de itens do projeto

para componentes herdados
Os modelos para formulários herdados no Visual Studio não estão disponíveis. Se você
vir esse erro, registre um problema usando Relatar um problema.
A classe delegada '<class name>' não tem nenhum

método invoke. Essa classe é um delegado
O Visual Studio tentou criar um manipulador de eventos, mas há algo errado com o tipo
de evento. Isso pode acontecer se o evento tiver sido criado por uma linguagem não
compatível com CLS. Contate o fornecedor do componente.
Declaração duplicada do membro '<nome do> membro'

Esse erro ocorre porque uma variável de membro foi declarada duas vezes (por
exemplo, dois controles nomeados Button1 são declarados no código). Os nomes
devem ser exclusivos entre formulários herdados. Além disso, os nomes não podem ser
diferentes apenas por caso.
Erro ao ler recursos do arquivo de recurso para a cultura

'<nome> da cultura'
Esse erro poderá ocorrer se houver um arquivo .resx inválido no projeto.
Para corrigir esse erro:
1. Clique no botão Mostrar Todos os Arquivos no Gerenciador de Soluções para

exibir os arquivos .resx associados à solução.
2. Carregue o arquivo .resx no Editor XML clicando com o botão direito do mouse no
arquivo .resx e escolhendo Abrir.
3. Edite o arquivo .resx manualmente para resolver os erros.
Erro ao ler recursos do arquivo de recurso para a cultura

padrão '<culture name>'
Esse erro poderá ocorrer se houver um arquivo .resx inválido no projeto para a cultura
padrão.
Para corrigir esse erro:
1. Clique no botão Mostrar Todos os Arquivos no Gerenciador de Soluções para

exibir os arquivos .resx associados à solução.
2. Carregue o arquivo .resx no Editor XML clicando com o botão direito do mouse no
arquivo .resx e escolhendo Abrir.
3. Edite o arquivo .resx manualmente para resolver os erros.
Falha ao analisar o método '<method name>'

Mensagem de erro: "Falha ao analisar o método '<nome> do método'. O analisador
relatou o seguinte erro: '<cadeia de caracteres de> erro'. Procure na Lista de Tarefas
possíveis erros."
Esta é uma mensagem de erro geral para problemas que surgem durante a análise.
Esses erros geralmente ocorrem devido a erros de sintaxe. Consulte a Lista de Tarefas
para obter mensagens específicas relacionadas ao erro.
Nome do componente inválido: '<nome> do

componente'
Você tentou renomear um componente para um valor inválido para esse idioma. Para
corrigir esse erro, nomeie o componente de modo que ele esteja em conformidade com
as regras de nomenclatura para esse idioma.
O tipo '<nome> de classe' é feito de várias classes

parciais no mesmo arquivo
Ao definir uma classe em vários arquivos usando a palavra-chave parcial , você só pode
ter uma definição parcial em cada arquivo.
Para corrigir esse erro, remova todas, exceto uma das definições parciais da classe do
arquivo.
Não foi possível encontrar o assembly '<assembly

name>'
Mensagem de erro: "Não foi possível encontrar o assembly '<nome> do assembly'.
Verifique se o assembly é referenciado. Se o assembly fizer parte do projeto de
desenvolvimento atual, verifique se o projeto foi criado."
Esse erro é semelhante a "O tipo '<type name>' não pôde ser encontrado", mas esse
erro geralmente ocorre devido a um atributo de metadados. Para corrigir esse erro,
verifique se todos os assemblies usados pelos atributos são referenciados.
O nome do assembly '<assembly name>' é inválido

Um componente solicitou um assembly específico, mas o nome fornecido pelo
componente não é um nome de assembly válido. Contate o fornecedor do componente.
A classe base '<class name>' não pode ser projetada

O Visual Studio carregou a classe , mas a classe não pode ser projetada porque o
implementador da classe não forneceu um designer. Se a classe der suporte a um
designer, verifique se não há problemas que possam causar problemas ao exibi-lo em
um designer, como erros do compilador. Além disso, verifique se todas as referências à
classe estão corretas e se todos os nomes de classe estão escritos corretamente. Caso
contrário, se a classe não for projetável, edite-a no modo de exibição de Código.
A classe base '<class name>' não pôde ser carregada

A classe não é referenciada no projeto, portanto, o Visual Studio não pode carregá-la.
Para corrigir esse erro, adicione uma referência à classe no projeto e feche e reabra a
janela Windows Forms Designer.
A classe '<class name>' não pode ser projetada nesta

versão do Visual Studio
O designer para esse controle ou componente não dá suporte aos mesmos tipos que o
Visual Studio. Contate o fornecedor do componente.
O nome da classe não é um identificador válido para este

idioma
O código-fonte que está sendo criado pelo usuário tem um nome de classe que não é
válido para o idioma que está sendo usado. Para corrigir esse erro, nomeie a classe de
modo que ela esteja em conformidade com os requisitos de idioma.
O componente não pode ser adicionado porque contém
uma referência circular a '<reference name>'
Você não pode adicionar um controle ou componente a si mesmo. Outra situação em
que isso pode ocorrer é se houver código no método InitializeComponent de um
formulário (por exemplo, Form1) que cria outra instância do Form1.
O designer não pode ser modificado no momento

Esse erro ocorre quando o arquivo no editor é marcado como somente leitura. Verifique
se o arquivo não está marcado como somente leitura e se o aplicativo não está em
execução.
O designer não pôde ser mostrado para esse arquivo

porque nenhuma das classes existentes nele podem ser
criadas
Esse erro ocorre quando o Visual Studio não consegue encontrar uma classe base que
atenda aos requisitos do designer. Formulários e controles devem derivar de uma classe
base que dê suporte a designers. Se você estiver derivando de um formulário ou
controle herdado, verifique se o projeto foi criado.
O designer da classe base '<class name>' não está

instalado
O Visual Studio não pôde carregar o designer para a classe . Se você vir esse erro,
registre um problema usando Relatar um problema.
O designer deve criar uma instância do tipo '<type

name>', mas não pode porque o tipo é declarado como
abstrato
Esse erro ocorreu porque a classe base do objeto que está sendo passado para o
designer é abstrata, o que não é permitido.
Não foi possível carregar o arquivo no designer

A classe base desse arquivo não dá suporte a nenhum designer. Como solução
alternativa, use o modo de exibição de Código para trabalhar no arquivo. Clique com o
botão direito do mouse no arquivo em Gerenciador de Soluções e escolha Exibir
Código.
A linguagem deste arquivo não suporta a análise de

código e geração de serviços necessários
Mensagem de erro: "O idioma desse arquivo não dá suporte aos serviços de análise e
geração de código necessários. Verifique se o arquivo que você está abrindo é um
membro de um projeto e tente abrir o arquivo novamente."
Esse erro provavelmente resultou da abertura de um arquivo que está em um projeto

que não dá suporte a designers.
A classe de analisador de idioma '<nome> da classe' não

é implementada corretamente
Mensagem de erro: "A classe de analisador de idioma '<nome> da classe' não está
implementada corretamente. Entre em contato com o fornecedor para obter um
módulo de analisador atualizado."
O idioma em uso registrou uma classe de designer que não deriva da classe base
correta. Entre em contato com o fornecedor do idioma que você está usando.
O nome '<name>' já é usado por outro objeto

Esse é um erro interno no serializador do Visual Studio. Se você vir esse erro, registre
um problema usando Relatar um problema.
O objeto '<object name>' não implementa a interface

IComponent
O Visual Studio tentou criar um componente, mas o objeto criado não implementa a
IComponent interface . Entre em contato com o fornecedor do componente para obter
uma correção.
O objeto '<object name>' retornou nulo para a

propriedade '<property name>', mas isso não é
permitido
Há algumas propriedades do .NET que sempre devem retornar um objeto . Por exemplo,
a coleção Controls de um formulário sempre deve retornar um objeto, mesmo quando
não há controles nele.
Para corrigir esse erro, verifique se a propriedade especificada no erro não é nula.
O objeto de dados de serialização não é do tipo

adequado
Um objeto de dados oferecido pelo serializador não é uma instância de um tipo que
corresponde ao serializador atual que está sendo usado. Contate o fornecedor do
componente.
O serviço '<nome> do serviço' é necessário, mas não

pôde ser localizado
Mensagem de erro: "O serviço '<nome> do serviço' é necessário, mas não pôde ser
localizado. Pode haver um problema com a instalação do Visual Studio."
Um serviço exigido pelo Visual Studio não está disponível. Se você estava tentando
carregar um projeto que não dá suporte a esse designer, use o Editor de Código para
fazer as alterações necessárias. Caso contrário, se você vir esse erro, registre um
problema usando Relatar um problema.
A instância de serviço deve derivar ou implementar

'<nome> da interface'
Esse erro indica que um componente ou designer de componente chamou o método
AddService , que requer uma interface e um objeto, mas o objeto especificado não
implementa a interface especificada. Contate o fornecedor do componente.
Não foi possível modificar o texto na janela de código

Mensagem de erro: "Não foi possível modificar o texto na janela de código. Verifique se
o arquivo não é somente leitura e se há espaço em disco suficiente."
Esse erro ocorre quando o Visual Studio não consegue editar um arquivo devido a
problemas de espaço em disco ou memória ou o arquivo é marcado como somente
leitura.
O objeto enumerados da caixa de ferramentas só dá
suporte para recuperar um item de cada vez
Se você vir esse erro, se vir esse erro, registre um problema usando Relatar um
problema.
O item caixa de ferramentas para '<nome> do

componente' não pôde ser recuperado da Caixa de
Ferramentas
Mensagem de erro: "Não foi possível recuperar o item da Caixa de Ferramentas para
'<nome> do componente' da Caixa de Ferramentas. Verifique se o assembly que
contém o item Caixa de Ferramentas está instalado corretamente. O item Caixa de
Ferramentas gerou o seguinte erro: <cadeia de caracteres de> erro."
O componente em questão lançou uma exceção quando o Visual Studio a acessou.

Contate o fornecedor do componente.
Não foi possível recuperar o item da Caixa de

Ferramentas para '<Nome> do item da Caixa de
Ferramentas' da Caixa de Ferramentas
Mensagem de erro: "O item da Caixa de Ferramentas para '<Nome> do item da Caixa
de Ferramentas' não pôde ser recuperado da Caixa de Ferramentas. Tente remover o
item da Caixa de Ferramentas e adicioná-lo novamente."
Esse erro ocorrerá se os dados dentro do item Caixa de Ferramentas forem corrompidos
ou a versão do componente tiver sido alterada. Tente remover o item da Caixa de
Ferramentas e adicioná-lo novamente.
Não foi possível encontrar o tipo '<type name>'

Mensagem de erro: "Não foi possível encontrar o tipo '<type name>'. Verifique se o
assembly que contém o tipo é referenciado. Se o assembly fizer parte do projeto de
desenvolvimento atual, verifique se o projeto foi criado."
Ao carregar o designer, o Visual Studio não conseguiu encontrar um tipo. Verifique se o

assembly que contém o tipo é referenciado. Se o assembly fizer parte do projeto de
desenvolvimento atual, verifique se o projeto foi criado.
O serviço de digitação com resolução só pode ser
chamado pelo segmento do aplicativo principal
O Visual Studio tentou acessar os recursos necessários do thread errado. Esse erro é
exibido quando o código usado para criar o designer chama o serviço de resolução de
tipos de um thread diferente do thread do aplicativo principal. Para corrigir esse erro,
chame o serviço do thread correto ou entre em contato com o fornecedor do
componente.
A variável '<variable name>' não foi declarada ou nunca

foi atribuída
O código-fonte tem uma referência a uma variável, como Button1, que não é declarada
ou atribuída. Se a variável não tiver sido atribuída, essa mensagem aparecerá como um
aviso, não como um erro.
Já existe um manipulador de comandos para o comando

de menu '<nome> do comando de menu'
Esse erro surgirá se um designer de terceiros adicionar um comando que já tenha um
manipulador à tabela de comandos. Contate o fornecedor do componente.
Já existe um componente chamado '<nome> do

componente'
Mensagem de erro: "Já existe um componente chamado '<nome> do componente'. Os
componentes devem ter nomes exclusivos e os nomes não devem diferenciar
maiúsculas de minúsculas. Um nome também não pode entrar em conflito com o nome
de qualquer componente em uma classe herdada."
Essa mensagem de erro surge quando houve uma alteração no nome de um

componente no janela Propriedades. Para corrigir esse erro, verifique se todos os nomes
de componentes são exclusivos, não diferenciam maiúsculas de minúsculas e não
entram em conflito com os nomes de nenhum componente nas classes herdadas.
Já existe um criador de item da Caixa de Ferramentas

registrado para o formato '<nome> do formato'
Um componente de terceiros fez um retorno de chamada para um item em uma guia
Caixa de Ferramentas, mas o item já continha um retorno de chamada. Contate o
Este mecanismo de idioma não suporta um CodeModel

com o qual carregar um designer
Esta mensagem é semelhante a "O idioma desse arquivo não dá suporte aos serviços
necessários de análise e geração de código", mas essa mensagem envolve um problema
de registro interno. Se você vir esse erro, se vir esse erro, registre um problema usando
Relatar um problema.
O tipo '<type name>' não tem um construtor com

parâmetros de tipos '<nomes> de tipo de parâmetro'
O Visual Studio não pôde encontrar um construtor que tivesse parâmetros
correspondentes. Isso pode ser o resultado do fornecimento de um construtor com
tipos diferentes daqueles que são necessários. Por exemplo, um construtor Point pode
ter dois inteiros. Se você forneceu floats, esse erro será gerado.
Para corrigir esse erro, use um construtor diferente ou converta explicitamente os tipos
de parâmetro de modo que correspondam aos fornecidos pelo construtor.
Não é possível adicionar a referência '<reference name>'

ao aplicativo atual
Mensagem de erro: "Não é possível adicionar referência '<nome> de referência' ao
aplicativo atual. Verifique se uma versão diferente de '<nome> de referência' ainda não
foi referenciada."
O Visual Studio não pode adicionar uma referência. Para corrigir esse erro, verifique se
uma versão diferente da referência ainda não foi referenciada.
Não é possível fazer check-out do arquivo atual

Mensagem de erro: "Não é possível fazer check-out do arquivo atual. O arquivo pode
estar bloqueado ou talvez seja necessário fazer check-out do arquivo manualmente."
Esse erro surge quando você altera um arquivo que está atualmente com check-in no
controle do código-fonte. Normalmente, o Visual Studio apresenta a caixa de diálogo
de check-out de arquivo para que o usuário possa fazer check-out do arquivo. Desta
vez, o arquivo não foi verificado, talvez devido a um conflito de mesclagem durante o
check-out. Para corrigir esse erro, verifique se o arquivo não está bloqueado e tente
fazer check-out do arquivo manualmente.
Não é possível localizar a página chamada '<Nome da

guia da caixa> de diálogo Opções'
Esse erro surge quando um designer de componente solicita acesso a uma página na
caixa de diálogo Opções usando um nome que não existe. Contate o fornecedor do
componente.
Não é possível localizar a propriedade '<property name>'

na página '<Nome da guia da caixa> de diálogo Opções'
Esse erro surge quando um designer de componente solicita acesso a um valor
específico em uma página da caixa de diálogo Opções, mas esse valor não existe.
Contate o fornecedor do componente.
O Visual Studio não pode abrir um designer para o

arquivo porque a classe nele não herda de uma classe
que pode ser projetada visualmente
O Visual Studio carregou a classe, mas o designer dessa classe não pôde ser carregado.
O Visual Studio exige que os designers usem a primeira classe em um arquivo. Para
corrigir esse erro, mova o código de classe para que ele seja a primeira classe no
arquivo e carregue o designer novamente.
O Visual Studio não pode salvar ou carregar instâncias do

tipo '<type name>'
Esse é um problema com um componente de terceiros. Contate o fornecedor do
componente.
O Visual Studio não consegue abrir o '<nome> do

documento' no modo Design
Mensagem de erro: "O Visual Studio não consegue abrir '<nome> do documento' no
modo Design. Nenhum analisador está instalado para o tipo de arquivo."
Esse erro indica que o idioma do projeto não dá suporte a um designer e surge quando
você tenta abrir um arquivo na caixa de diálogo Abrir Arquivo ou de Gerenciador de
Soluções. Em vez disso, edite o arquivo no modo de exibição de código.
O Visual Studio não pôde encontrar um designer para

classes do tipo '<type name>'
O Visual Studio carregou a classe, mas a classe não pode ser projetada. Em vez disso,
edite a classe no modo de exibição código clicando com o botão direito do mouse na
classe e escolhendo Exibir Código.
Veja também
Desenvolver controles Windows Forms usando o designer
Fórum do designer do Windows Forms
Solucionar problemas de criação de
controle e de componente
Artigo • 02/06/2023
Este tópico lista os seguintes problemas comuns que surgem ao desenvolver

componentes e controles:
Não é possível adicionar o controle à caixa de ferramentas
Não é possível depurar o componente nem o controle de usuário do Windows

Forms
O evento é gerado duas vezes no componente ou no controle herdado
Erro de tempo de design: "Falha em criar o componente 'Nome do Componente'"
STAThreadAttribute
O ícone do componente não aparece na caixa de ferramentas
Não é possível adicionar o controle à caixa de

ferramentas
Se você quiser adicionar um controle personalizado criado em outro projeto ou um
controle de terceiros à Caixa de Ferramentas, faça isso manualmente. Se o projeto atual
contiver seu controle ou componente, ele deverá aparecer na Caixa de Ferramentas
automaticamente. Para mais informações, consulte Instruções passo a passo:
preenchendo de forma automática a caixa de ferramentas com componentes
personalizados.
Para adicionar um controle à Caixa de Ferramentas

1. Clique com o botão direito do mouse em Caixa de Ferramentas e selecione
Escolher Itens no menu de atalho.
2. Na caixa de diálogo Escolher Itens da Caixa de Ferramentas, adicione o

componente:
Se você quiser adicionar um controle ou um componente do .NET

Framework, clique na guia Componentes do .NET Framework.
– ou –
Se você quiser adicionar um componente COM ou um controle ActiveX,

clique na guia Componentes COM.
3. Se o controle estiver listado na caixa de diálogo, confirme que ele está selecionado
e, em seguida, clique em OK.
O controle é adicionado à Caixa de Ferramentas.
4. Se seu controle não estiver listado na caixa de diálogo, faça o seguinte:
a. Clique no botão Procurar .
b. Navegue até a pasta que contém o arquivo .dll com o controle.
c. Selecione o arquivo .dll e clique em Abrir.
Seu controle aparece na caixa de diálogo.
d. Confirme que o controle está selecionado e, em seguida, clique em OK.
Seu controle é adicionado à Caixa de Ferramentas.
Não é possível depurar o componente nem o

controle de usuário do Windows Forms
Se o UserControl controle deriva da classe, você pode depurar seu comportamento em
tempo de execução com o contêiner de teste. Para obter mais informações, consulte
Como testar o comportamento em tempo de execução de um UserControl.
Outros controles e componentes personalizados não são projetos autônomos. Eles

devem ser hospedados por um aplicativo como um projeto do Windows Forms. Para
depurar um controle ou um componente, adicione-o a um projeto do Windows Forms.
Para depurar um controle ou um componente

1. No menu Compilar, clique em Compilar Solução para compilar sua solução.
2. No menu Arquivo, escolha Adicionar e, em seguida, Novo Projeto para adicionar

um projeto de teste ao seu aplicativo.
3. Na caixa de diálogo Adicionar Novo Projeto, escolha Aplicativos do Windows

para o tipo de projeto.
4. Em Gerenciador de Soluções, clique com o botão direito do mouse no nó
Referências para o novo projeto. No menu de atalho, clique em Adicionar
Referência para adicionar uma referência ao projeto que contém o controle ou o
componente.
5. Crie uma instância do seu controle ou componente no projeto de teste. Se o

componente estiver na Toolbox, você poderá arrastá-lo para a superfície do
designer ou criar a instância programaticamente, conforme mostrado no exemplo
de código a seguir.
C#
MyNeatComponent Component1 = new MyNeatComponent();
Agora você pode depurar seu componente ou controle como de costume.
Para obter mais informações sobre depuração, consulte Depuração no Visual Studio e
Passo a passo: depurando personalizar controles personalizados do Windows Forms no
tempo de design.
O evento é gerado duas vezes no componente

ou no controle herdado
Isso provavelmente é devido a uma cláusula Handles duplicada. Para obter mais
informações, consulte Solução de problemas de manipuladores de eventos herdados no
Visual Basic.
Erro de tempo de design: "Falha em criar o

componente 'Nome do Componente'"
Seu componente ou controle deve fornecer um construtor sem parâmetros sem
parâmetros. Quando o ambiente de design cria uma instância do seu componente ou
controle, ele não tenta fornecer nenhum parâmetro para as sobrecargas do construtor
que aceitam parâmetros.
STAThreadAttribute
Ele STAThreadAttribute informa ao CLR (Common Language Runtime) que Windows
Forms usa o modelo de apartamento de thread único. Você poderá perceber um
comportamento não intencional se não aplicar esse atributo ao método Main do
aplicativo do Windows Forms. Por exemplo, as imagens em segundo plano podem não
aparecer para controles como ListView. Alguns controles também podem exigir esse
atributo para um comportamento correto de Preenchimento Automático e do tipo
"arrastar e soltar".
O ícone do componente não aparece na caixa

de ferramentas
Quando você usa ToolboxBitmapAttribute para associar um ícone ao componente
personalizado, o bitmap não aparece na Caixa de Ferramentas para componentes
gerados automaticamente. Para ver o bitmap, recarregue o controle usando a caixa de
diálogo Escolher Itens da Caixa de Ferramentas. Para obter mais informações, consulte
Como fornecer um bitmap da caixa de ferramentas para um controle.
Confira também
tempo de Design

Dotnet Desktop Winforms Controls Netframeworkdesktop 4.8

Enviado por

Dados do documento

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Dotnet Desktop Winforms Controls Netframeworkdesktop 4.8

Enviado por

Direitos autorais:

Formatos disponíveis

Dê a sua opinião sobre a experiência de download do PDF.

Controles de formulários do Windows

Organizando controles nos Windows Forms

Controles a serem usados nos Windows Forms

Desenvolvendo controles dos Windows Forms personalizados com o .NET Framework

Desenvolvendo controles do Windows Forms no tempo de design

Para padronizar o layout da interface do usuário do aplicativo baseado no Windows,

Para alinhar vários controles em um formulário

2. Selecione os controles que você deseja alinhar. O primeiro controle selecionado é

3. No menu Formatar , selecione Alinhar e selecione uma das sete opções

Se você estiver projetando um formulário que o usuário pode redimensionar em tempo

A Anchor propriedade interage com a AutoSize propriedade. Para obter mais

Ancorar um controle em um formulário

É possível ancorar vários controles simultaneamente pressionando a tecla

2. Na janela Propriedades , clique na seta à direita da Anchor propriedade.

Um editor será exibido e mostra uma cruz.

Os controles estão ancorados na parte superior e esquerda por padrão.

5. Para fechar o Anchor editor de propriedades, clique no nome da Anchor

Quando o formulário é exibido em tempo de execução, o controle é redimensionado

Determinados controles, como o ComboBox controle, têm um limite para sua

Controles são encaixados na ordem z inversa.

Para encaixar um controle

2. Na janela Propriedades , clique na seta à direita da Dock propriedade.

3. Clique no botão que representa a borda do formulário no qual você deseja

O controle é redimensionado automaticamente para ajustar os limites da borda

Ao criar uma interface do usuário complexa ou trabalhar com um formulário MDI

Dispondo controles em camadas no design

2. No menu Formatar , selecione pedidoe, em seguida, selecione trazer para frente

Dispondo controles em camadas de forma

Por exemplo, se um TextBox controle, txtFirstName , estiver abaixo de outro controle e

Windows Forms dá suporte a Contenção de controle. A contenção de controle

Ao projetar a interface do usuário do seu aplicativo do Windows, você pode bloquear os

Além disso, você pode bloquear e desbloquear todos os controles no formulário de

Para bloquear um controle

Para bloquear todos os controles em um

Esse comando bloqueia também o tamanho do formulário, pois um formulário é

Todos os controles bloqueados anteriormente no formulário agora estão

Para desbloquear controles bloqueados

Para posicionar controles, use o designer Windows Forms no Visual Studio ou

Posicionar um controle na superfície de design

Selecione o controle e mova-o com as teclas de direção para posicioná-lo com

Posicionar um controle usando o janela

2. Na janela Propriedades , insira valores para Location a propriedade, separados por

O primeiro número (X) é a distância entre a borda esquerda do contêiner; o

Você pode expandir a Location propriedade para digitar os valores X e Y

button1.Location = new Point(100, 100);

2. Altere a coordenada X do local do controle usando a Left subpropriedade.

Incrementar o local de um controle

Use a Location propriedade para definir as posições X e Y de um controle

Você pode redimensionar controles individuais e redimensionar vários controles do

Para redimensionar um controle

Selecione o controle e pressione as teclas de direção enquanto mantém

Para redimensionar vários controles em um

À medida que você se acostuma a trabalhar no ambiente de desenvolvimento do Visual

Definir opções globais de Windows Forms

2. No painel esquerdo da caixa de diálogo Opções, clique em Designer de

No painel direito, sob o título Configurações de Layout, você pode configurar as

A ordem de tabulação é a ordem na qual um usuário move o foco de um controle para

Para definir a ordem de tabulação de um

Isso ativa o modo de seleção de ordem de tabulação do formulário. Um número

2. Clique nos controles sequencialmente para estabelecer a ordem de tabulação

Local do controle na ordem de tabulação pode ser definido como qualquer

Como alternativa, a ordem de tabulação pode ser definida no janela Propriedades

Para remover um controle da ordem de