Guia de início rápido: adicionando controles de entrada e edição de texto (aplicativos do Tempo de Execução do Windows em C#/VB/C++ e XAML)

Applies to Windows and Windows Phone

A estrutura do XAML inclui vários controles para inserir e editar texto, com um conjunto de propriedades para formatar o texto. Os controles de entrada de texto são TextBox, PasswordBox e RichEditBox. Este guia de início rápido mostra como você pode usar esses controles para exibir, inserir e editar texto.

Mapa: como este tópico está relacionado aos outros? Veja:

Pré-requisitos

Nós supomos que você possa criar um aplicativo do Tempo de Execução do Windows básico em C++, C# ou Visual Basic. Para obter instruções sobre adicionar um controle, veja Guia de início rápido: adicionando controles e manipulando eventos.

Escolhendo um controle de texto

A estrutura XAML inclui 3 controles centrais de entrada de texto: TextBox,PasswordBox e RichEditBox. O controle de texto que você deverá usar dependerá do cenário. Aqui estão alguns cenários e o controle recomendado.

CenárioControle recomendado

Insira ou edite texto plano, como em um formulário.

TextBox

Insira uma senha.

PasswordBox

Edite um documento, artigo ou blog que exige formatação, parágrafos, hiperlinks ou imagens embutidas.

RichEditBox

 

Caixa de texto

Você pode usar um controle TextBox para inserir e editar texto não formatado. Você pode usar a propriedade Text para obter e definir o texto em um TextBox. Veja o XAML para um simples TextBox com o seu conjunto de propriedade Text.


<TextBox  Height="35" Width="200" Text="Hello World!" Margin="20"/>

Veja o TextBox que resulta deste XAML.

Uma caixa de texto simples.

Você pode fazer um TextBox somente leitura definindo a propriedade IsReadOnly como true. Para fazer o texto de TextBox em várias linhas quebrar de linha, defina a propriedade TextWrapping como Wrap e a propriedade AcceptsReturn como true.

Você pode conseguir ou definir o texto selecionado em um TextBox usando a propriedade SelectedText. Use o evento SelectionChanged para fazer algo quando o usuário selecionar ou desmarcar texto.

Aqui, nós temos um exemplo destas propriedades e métodos em uso. Quando você selecionar texto no primeiro TextBox, o texto selecionado é exibido no segundo TextBox, que é somente leitura. Os valores das propriedades SelectionLength e SelectionStart são mostrados em dois TextBlocks. Isso é feito usando o evento SelectionChanged.


<TextBox x:Name="textBox1" Height="75" Width="300" Margin="10"
         Text="The text that is selected in this TextBox will show up in the read only TextBox below." 
         TextWrapping="Wrap" AcceptsReturn="True"
         SelectionChanged="TextBox1_SelectionChanged" />
<TextBox x:Name="textBox2" Height="75" Width="300" Margin="5" 
         TextWrapping="Wrap" AcceptsReturn="True" IsReadOnly="True"/>
<TextBlock x:Name="label1" HorizontalAlignment="Center"/>
<TextBlock x:Name="label2" HorizontalAlignment="Center"/>



// C#
private void TextBox1_SelectionChanged(object sender, RoutedEventArgs e)
{
    textBox2.Text = textBox1.SelectedText;
    label1.Text = "Selection length is " + textBox1.SelectionLength.ToString();
    label2.Text = "Selection starts at " + textBox1.SelectionStart.ToString();
}

Este é o resultado deste código.

O texto selecionado em uma caixa de texto.

PasswordBox

Você pode inserir uma única linha de conteúdo que não quebra linha em um controle PasswordBox. O usuário não pode visualizar o texto inserido; só caracteres de senha que representam o texto são exibidos. Você pode especificar este caractere de senha usando a propriedade PasswordChar e pode especificar o número máximo de caracteres que o usuário pode inserir definindo a propriedade MaxLength.

Você obtém o texto que o usuário inseriu da propriedade Password, tipicamente no manipulador do evento PasswordChanged.

Este é o XAML para um controle de caixa de senha que demonstre a aparência padrão do PasswordBox. Quando o usuário insere uma senha, ela é verificada para ver se é o valor literal, "Senha". Se é, nós mostramos uma mensagem ao usuário.


<PasswordBox x:Name="pwBox" Height="35" Width="200"
             MaxLength="8" PasswordChanged="pwBox_PasswordChanged"/>
           
<TextBlock x:Name="statusText" Margin="10" HorizontalAlignment="Center" />


// C#
private void pwBox_PasswordChanged(object sender, RoutedEventArgs e)
{
    if (pwBox.Password == "Password")
    {
        statusText.Text = "'Password' is not allowed as a password.";
    }
}

Este é o resultado quando este código é executado e o usuário digita "Senha".

Uma caixa de senha.

Nos aplicativos da Windows Store, a PasswordBox tem um botão interno que o usuário pode tocar ou clicar para exibir o texto da senha. Este é o resultado da ação do usuário. Quando o usuário o libera, a senha é automaticamente oculta novamente.

Uma caixa de senha com a senha mostrada.

Nos aplicativos da Loja do Windows Phone, o PasswordBoxapresenta uma caixa de seleção abaixo dele na qual o usuário pode clicar para exibir os caracteres da senha.

Uma caixa de senha do Windows Phone.

RichEditBox

Você pode usar um controle RichEditBox para inserir e editar documentos rich text que contêm texto formatado, hiperlinks e imagens. Você pode fazer um RichEditBox somente leitura definindo sua propriedade IsReadOnly como true.

Por padrão, a RichEditBox oferece suporte à verificação ortográfica. Para desabilitar o corretor ortográfico, defina a propriedade IsSpellCheckEnabled como falsa. Para saber mais, veja Diretrizes e lista de verificação de verificação ortográfica.

Use a propriedade Document da RichEditBox para obter esse conteúdo. O conteúdo de RichEditBox é um objeto Windows.UI.Text.ITextDocument, diferente do controle RichTextBlock, que usa objetos Windows.UI.Xaml.Documents.Block como conteúdo. A interface ITextDocument fornece um modo de carregar e salvar o documento em um fluxo, recuperar faixas de texto, obter a seleção ativa, desfazer e refazer alterações, definir atributos de formatação padrão, entre outras coisas.

Este exemplo mostra como carregar e salvar um arquivo rtf (Rich Text Format) em uma RichEditBox.


<Grid Margin="120">
    <Grid.RowDefinitions>
        <RowDefinition Height="50"/>
        <RowDefinition/>
    </Grid.RowDefinitions>
    <StackPanel Orientation="Horizontal">
        <Button Content="Open file" Click="OpenButton_Click"/>
        <Button Content="Save file" Click="SaveButton_Click"/>
    </StackPanel>
            
    <RichEditBox x:Name="editor" Grid.Row="1"/>
</Grid>


private async void OpenButton_Click(object sender, RoutedEventArgs e)
{
    // Open a text file.
    Windows.Storage.Pickers.FileOpenPicker open =
        new Windows.Storage.Pickers.FileOpenPicker();
    open.SuggestedStartLocation =
        Windows.Storage.Pickers.PickerLocationId.DocumentsLibrary;
    open.FileTypeFilter.Add(".rtf");

    Windows.Storage.StorageFile file = await open.PickSingleFileAsync();

    if (file != null)
    {
        Windows.Storage.Streams.IRandomAccessStream randAccStream =
            await file.OpenAsync(Windows.Storage.FileAccessMode.Read);

        // Load the file into the Document property of the RichEditBox.
        editor.Document.LoadFromStream(Windows.UI.Text.TextSetOptions.FormatRtf, randAccStream);
    }
}

private async void SaveButton_Click(object sender, RoutedEventArgs e)
{
    if (((ApplicationView.Value != ApplicationViewState.Snapped) ||
          ApplicationView.TryUnsnap()))
    {
        FileSavePicker savePicker = new FileSavePicker();
        savePicker.SuggestedStartLocation = PickerLocationId.DocumentsLibrary;
        
        // Dropdown of file types the user can save the file as
        savePicker.FileTypeChoices.Add("Rich Text", new List<string>() { ".rtf" });
        
        // Default file name if the user does not type one in or select a file to replace
        savePicker.SuggestedFileName = "New Document";

        StorageFile file = await savePicker.PickSaveFileAsync();
        if (file != null)
        {
            // Prevent updates to the remote version of the file until we 
            // finish making changes and call CompleteUpdatesAsync.
            CachedFileManager.DeferUpdates(file);
            // write to file
            Windows.Storage.Streams.IRandomAccessStream randAccStream =
                await file.OpenAsync(Windows.Storage.FileAccessMode.ReadWrite);

            editor.Document.SaveToStream(Windows.UI.Text.TextGetOptions.FormatRtf, randAccStream);

            // Let Windows know that we're finished changing the file so the 
            // other app can update the remote version of the file.
            FileUpdateStatus status = await CachedFileManager.CompleteUpdatesAsync(file);
            if (status != FileUpdateStatus.Complete)
            {
                Windows.UI.Popups.MessageDialog errorBox =
                    new Windows.UI.Popups.MessageDialog("File " + file.Name + " couldn't be saved.");
                await errorBox.ShowAsync();
            }
        }
    }
}

Usando o teclado virtual

O teclado virtual pode ser usado para entrada de texto, quando o aplicativo é executado em um dispositivo com tela sensível ao toque. O teclado virtual é invocado quando o usuário toca em um campo de entrada editável, como TextBox ou PasswordBox e é ignorado quando o campo de entrada perde o foco. O teclado virtual usa informações de acessibilidade para determinar quando ele é invocado e ignorado. Os controles de texto fornecidos na estrutura XAML possuem as propriedades de automação internas. Se criar os seus próprios controles de texto personalizados, você precisa implementar TextPattern para usar o teclado virtual.

Resumo e próximas etapas

Você aprendeu como criar controles TextBox, PasswordBox e RichEditBox para exibir e editar texto em seu aplicativo.

Para mais exemplos de códigos que mostram esses controles, veja o exemplo de edição de texto XAML.

Tópicos relacionados

Diretrizes e lista de verificação de entrada de texto
Diretrizes e lista de verificação de verificação ortográfica
Mapa para aplicativos da Windows Store em C# ou Visual Basic
Mapa para os aplicativos da Windows Store em C++

 

 

Mostrar:
© 2014 Microsoft