Tutorial: Agregar controles a un documento en tiempo de ejecución en un complemento en el nivel de la aplicación

Artículo
04/28/2010

Actualización: Julio de 2008

Se aplica a
La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados. Tipo de proyecto Proyectos de nivel de aplicación Versión de Microsoft Office Word 2007 Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados.

Tipo de proyecto

Proyectos de nivel de aplicación

Versión de Microsoft Office

Word 2007

Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

A partir de Visual Studio 2008 Service Pack 1 (SP1), puede agregar controles en tiempo de ejecución a cualquier documento abierto de Microsoft Office Word 2007 utilizando un complemento en el nivel de la aplicación. En este tutorial se muestra cómo utilizar la Cinta de opciones para permitir que los usuarios agreguen un Button o un RichTextContentControl a un documento.

Este tutorial ilustra las tareas siguientes:

Crear un nuevo proyecto de complemento de Word.
Proporcionar una interfaz de usuario para agregar controles al documento.
Agregar los controles al documento en tiempo de ejecución.
Quitar los controles del documento.

Nota:
Es posible que su equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio incluidos en las instrucciones siguientes. La edición de Visual Studio que se tenga y la configuración que se utilice determinan estos elementos. Para obtener más información, vea Valores de configuración de Visual Studio.

Requisitos previos

Necesita los componentes siguientes para completar este tutorial:

Visual Studio Tools para Office (componente opcional de Visual Studio 2008 Professional y Visual Studio Team System).
Visual Studio 2008 SP1.
Microsoft Office Word 2007.

Crear un nuevo proyecto de complemento de Word

Comience por crear un proyecto de complemento de Word 2007.

Para crear un nuevo proyecto de complemento de Word

Cree un proyecto de complemento en el nivel de la aplicación para Word 2007 llamado WordDynamicControls. Para obtener más información, vea Cómo: Crear proyectos de Visual Studio para Office.

Proporcionar una interfaz de usuario para agregar controles a un documento

Agregue una ficha personalizada a la Cinta de opciones en Word. Los usuarios pueden activar las casillas de la ficha para agregar controles a un documento.

Proporcionar una interfaz de usuario para agregar controles a un documento

En el menú Proyecto, haga clic en Agregar nuevo elemento.
En el cuadro de diálogo Agregar nuevo elemento, seleccione Cinta (diseñador visual).
Cambie el nombre de la nueva cinta de opciones por MyRibbon y haga clic en Agregar.

El archivo MyRibbon.cs o MyRibbon.vb se abre en el diseñador de la cinta de opciones y muestra una ficha y un grupo predeterminados.
En el diseñador de la Cinta de opciones, haga clic en group1.
En la ventana Propiedades, cambie la propiedad Label de group1 por Add Controls.
Desde la ficha Controles de la cinta de opciones de Office del Cuadro de herramientas, arrastre un control CheckBox a group1.
Haga clic en CheckBox1 para seleccionarlo.
En la ventana Propiedades, cambie las siguientes propiedades.

Propiedad

Valor

Name

addButtonComboBox

Label

Add Button
Agregue una segunda casilla a group1y, a continuación, cambie las propiedades siguientes.

Propiedad

Valor

Name

addRichTextCheckBox

Label

Add Rich Text Control
En el Diseñador de la cinta de opciones, haga doble clic en Add Button.

El controlador de eventos Click de la casilla Add Button se abre en el Editor de código.
Vuelva al Diseñador de la cinta de opciones y haga doble clic en Add Rich Text Control.

El controlador de eventos Click de la casilla Add Rich Text Control se abre en el Editor de código.

Propiedad	Valor
Name	addButtonComboBox
Label	Add Button

Propiedad	Valor
Name	addRichTextCheckBox
Label	Add Rich Text Control

Más adelante en este tutorial, agregará código a estos controladores de eventos para agregar y quitar controles del documento activo.

Agregar y quitar los controles del documento activo

En el código del complemento, debe convertir el documento activo en un elemento host Microsoft.Office.Tools.Word.Document para poder agregar un control. En las soluciones de Visual Studio Tools para Office, los controles administrados únicamente se pueden agregar a los elementos host que actúan como contenedores de los controles. En los proyectos de complementos en el nivel de la aplicación, los elementos host únicamente se pueden crear en tiempo de ejecución, con el método GetVstoObject.

Agregue métodos a la clase ThisAddIn que se puedan llamar para agregar o quitar un Button o un RichTextContentControl del documento activo. Más adelante en este tutorial, llamará a estos métodos desde los controladores de eventos Click de las casillas de la Cinta de opciones.

Para agregar y quitar controles del documento activo

En el Explorador de soluciones, haga doble clic en ThisAddIn.cs o en ThisAddIn.vb para abrir el archivo en el Editor de código.

Agregue el código siguiente a la clase ThisAddIn. Este código declara los objetos RichTextContentControl y Button que representan los controles que se agregarán al documento.

Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
Private richTextControl As RichTextContentControl = Nothing

private Microsoft.Office.Tools.Word.Controls.Button button = null;
private RichTextContentControl richTextControl = null;

Agregue el método siguiente a la clase ThisAddIn. Cuando el usuario hace clic en la casilla Add Button de la cinta de opciones, este método agrega Button a la selección actual del documento si la casilla está activada, o quita Button si está desactivada.

Friend Sub ToggleButtonOnDocument()
    Dim nativeDocument As Word.Document = Globals.ThisAddIn.Application.ActiveDocument
    Dim vstoDocument As Document = nativeDocument.GetVstoObject()
    Dim name As String = "MyButton"

    If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
        If Globals.ThisAddIn.Application.Selection IsNot Nothing Then
            button = vstoDocument.Controls.AddButton( _
                Globals.ThisAddIn.Application.Selection.Range, 100, 30, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleButtonOnDocument()
{
    Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
    Document vstoDocument = nativeDocument.GetVstoObject();
    string name = "MyButton";

    if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
    {
        if (Globals.ThisAddIn.Application.Selection != null)
        {
            button = vstoDocument.Controls.AddButton(
                Globals.ThisAddIn.Application.Selection.Range, 100, 30, name);
        }
    }
    else
    {
        vstoDocument.Controls.Remove(name);
    }
}

Agregue el método siguiente a la clase ThisAddIn. Cuando el usuario hace clic en la casilla Add Rich Text Control de la cinta de opciones, este método agrega RichTextContentControl a la selección actual en el documento si la casilla está activada, o quita RichTextContentControl si está desactivada.

Friend Sub ToggleRichTextControlOnDocument()
    Dim nativeDocument As Word.Document = Globals.ThisAddIn.Application.ActiveDocument
    Dim vstoDocument As Document = nativeDocument.GetVstoObject()
    Dim name As String = "MyRichTextBoxControl"

    If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
        If Globals.ThisAddIn.Application.Selection IsNot Nothing Then
            richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                    Globals.ThisAddIn.Application.Selection.Range, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleRichTextControlOnDocument()
{
    Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
    Document vstoDocument = nativeDocument.GetVstoObject();
    string name = "MyRichTextBoxControl";

    if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
    {
        if (Globals.ThisAddIn.Application.Selection != null)
        {
            richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                Globals.ThisAddIn.Application.Selection.Range, name);
        }
    }
    else
    {
        vstoDocument.Controls.Remove(name);
    }
}

Quitar el control Button cuando se guarda el documento

No se conservan los controles de formularios Windows Forms cuando el documento se guarda y se cierra. Sin embargo, se mantiene un contenedor de ActiveX por cada control del documento y los usuarios finales pueden ver el borde de este contenedor cuando se vuelve a abrir el documento. Hay varias maneras de limpiar dinámicamente los controles de formularios Windows Forms de los complementos. En este tutorial, se quita mediante programación el control Button cuando se guarda el documento.

Para quitar el control Button cuando se guarda el documento

En el archivo de código ThisAddIn.cs o ThisAddIn.vb, agregue el método siguiente a la clase ThisAddIn. Este método es un controlador de eventos del evento DocumentBeforeSave. Si el documento guardado tiene un elemento host Document asociado a él, el controlador de eventos obtiene el elemento host y quita el control Button, si existe.

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
    If Doc.HasVstoObject() Then
        Dim vstoDocument As Document = Doc.GetVstoObject()
        If vstoDocument.Controls.Contains(button) Then
            vstoDocument.Controls.Remove(button)
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
        End If
    End If
End Sub

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Doc.HasVstoObject())
    {
        Document vstoDocument = Doc.GetVstoObject();

        if (vstoDocument.Controls.Contains(button))
        {
            vstoDocument.Controls.Remove(button);
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
        }
    }
}

En C#, agregue el código siguiente al controlador de eventos ThisAddIn_Startup. Este código es necesario en C# para conectar el controlador de eventos Application_DocumentBeforeSave al evento DocumentBeforeSave.
```
this.Application.DocumentBeforeSave += 
    new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
    Application_DocumentBeforeSave);
```

Agregar y quitar controles cuando el usuario hace clic en las casillas de la cinta de opciones

Finalmente, modifique los controladores de eventos Click de las casillas que agregó a la Cinta de opciones para agregar o quitar los controles del documento.

Agregar o quitar controles cuando el usuario hace clic las casillas de la Cinta de opciones

En el archivo de código MyRibbon.cs o MyRibbon.vb, reemplace los controladores de eventos addRichTextCheckBox_Click y los addButtonCheckBox_Click generados por el código siguiente. Este código vuelve a definir estos controladores de eventos para llamar a los métodos ToggleRichTextControlOnDocument y ToggleButtonOnDocument que agregó anteriormente a la clase ThisAddIn en este tutorial.

Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
    ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
    Globals.ThisAddIn.ToggleButtonOnDocument()
End Sub

Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
    ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
    Globals.ThisAddIn.ToggleRichTextControlOnDocument()
End Sub

private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleButtonOnDocument();
}

private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.ToggleRichTextControlOnDocument();
}

Comprobar la solución

Agregue controles a un documento seleccionándolos en la ficha personalizada de la Cinta de opciones. Al guardar el documento, se quita el control Button.

Para probar la solución.

Presione F5 para ejecutar el proyecto.
En el documento activo, presione ENTRAR varias veces para agregar los nuevos párrafos vacíos al documento.
Seleccione el primer párrafo.
Haga clic en la ficha Complementos.
En el grupo Agregar controles, haga clic en Add Button.

Aparece un botón en el primer párrafo.
Seleccione el último párrafo.
En el grupo Add Control, haga clic en Add Rich Text Control.

Se agrega un control de contenido de texto enriquecido al último párrafo.
Guarde el documento.

El botón se quita del documento.

Pasos siguientes

Para obtener más información sobre los controles en complementos en el nivel de la aplicación, vea estos temas:

Para obtener un ejemplo que muestra cómo agregar en tiempo de ejecución muchos otros tipos de controles a un documento y volver a crearlos cuando se vuelve a abrir el documento, vea Ejemplo Word Add-In Dynamic Controls.
Para ver un tutorial que muestra cómo agregar controles a una hoja de cálculo utilizando un complemento en el nivel de la aplicación para Excel, vea Tutorial: Agregar controles a una hoja de cálculo en tiempo de ejecución en un proyecto en el nivel de la aplicación.