Tutorial: Agregar controles a un documento en tiempo de ejecución en un complemento de VSTO

Puede agregar controles a cualquier documento de Microsoft Office Word abierto mediante un complemento VSTO. En este tutorial se muestra cómo usar la cinta de opciones para permitir que los usuarios agreguen un Button elemento o a RichTextContentControl un documento.

Aplicación: la información de este tema se aplica a los proyectos de complemento de VSTO para Word 2010. Para obtener más información, consulta Features Available by Office Application and Project Type.

En este tutorial se muestran las tareas siguientes:

• Crear un nuevo proyecto de complemento de VSTO de Word.

• Proporcionar una interfaz de usuario (UI) para agregar controles al documento.

• Agregar controles al documento en tiempo de ejecución.

• Quitar controles del documento.

  Nota:

  Es posible que tu equipo muestre nombres o ubicaciones diferentes para algunos de los elementos de la interfaz de usuario de Visual Studio en las siguientes instrucciones. 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 Personalizar el IDE.

Requisitos previos

Necesitará los componentes siguientes para completar este tutorial:

• Una edición de Visual Studio que incluye las herramientas para desarrolladores de Microsoft Office. Para obtener más información, vea Configurar un equipo para desarrollar soluciones de Office.

• Word 2013 o Word 2010 .

Crear un nuevo proyecto de complemento de Word

Empiece creando un proyecto de complemento de VSTO de Word.

Para crear un nuevo proyecto de complemento de VSTO de Word

1. Cree un proyecto de complemento de VSTO para Word con el nombre WordDynamicControls. Para obtener más información, vea Cómo: Crear proyectos de Office en Visual Studio.

2. Agregue una referencia al ensamblado Microsoft.Office.Tools.Word.v4.0.Utilities.dll . Esta referencia es obligatoria para agregar mediante programación un control de Windows Forms al documento más adelante en este tutorial.

Proporcionar una interfaz de usuario para agregar controles a un documento

Agregue una pestaña personalizada a la cinta en Word. Los usuarios pueden seleccionar las casillas en la pestaña para agregar controles a un documento.

Para proporcionar una interfaz de usuario para agregar controles a un documento

1. En el menú Proyecto , haga clic en Agregar nuevo elemento.

2. En el cuadro de diálogo Agregar nuevo elemento , seleccione Cinta (diseñador visual).

3. Cambie el nombre de la nueva cinta de opciones por MyRibbony 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.

4. En el diseñador de la cinta, haga clic en el grupo group1 .

5. En la ventana Propiedades , cambie la propiedad Etiqueta para group1 a Agregar controles.

6. Desde la pestaña Controles de la cinta de Office del Cuadro de herramientas, arrastre un control CheckBox a group1.

7. Haga clic en CheckBox1 para seleccionarlo.

8. En la ventana Propiedades , cambie las siguientes propiedades:

   Propiedad	Valor
   Nombre	addButtonCheckBox
   Label	Botón Agregar

9. Agregue una segunda casilla a group1, y, a continuación, cambie las siguientes propiedades.

   Propiedad	Valor
   Nombre	addRichTextCheckBox
   Label	Agregar control de texto enriquecido

10. En el diseñador de la cinta, haga doble clic en Agregar botón.

    El controlador de eventos Click de la casilla Agregar botón se abre en el Editor de código.

11. Vuelva al diseñador de la cinta y haga doble clic en Agregar control de texto enriquecido.

    El controlador de eventos Click de la casilla Agregar control de texto enriquecido se abre en el Editor de código.

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

Agregar y quitar controles en el documento activo

En el código de complemento de VSTO, debe convertir el documento activo en un Documentde para poder agregar un control. En soluciones de Office, pueden agregarse controles administrados solo a los elementos host, que actúan como contenedores para los controles. En los proyectos de complemento de VSTO, los elementos host se pueden crear en tiempo de ejecución mediante el GetVstoObject método .

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

Para agregar y quitar controles en el documento activo

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

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

   C#

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

   VB

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

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

   C#

   internal void ToggleButtonOnDocument()
   {
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
   
       string name = "MyButton";
   
       if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
       {
           Word.Selection selection = this.Application.Selection;
           if (selection != null && selection.Range != null)
           {
               button = vstoDocument.Controls.AddButton(
                   selection.Range, 100, 30, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

   VB

   Friend Sub ToggleButtonOnDocument()
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       Dim name As String = "MyButton"
   
       If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
           Dim selection = Me.Application.Selection
           If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
               button = vstoDocument.Controls.AddButton( _
                   selection.Range, 100, 30, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

4. Agregue el siguiente método a la clase ThisAddIn. Cuando el usuario hace clic en la casilla Agregar control de texto enriquecido en la cinta, este método agrega un RichTextContentControl a la selección actual en el documento si la casilla está activada, o quita el RichTextContentControl si la casilla está desactivada.

   C#

   internal void ToggleRichTextControlOnDocument()
   {
   
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
   
       string name = "MyRichTextBoxControl";
   
       if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
       {
           Word.Selection selection = this.Application.Selection;
           if (selection != null && selection.Range != null)
           {
               richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                   selection.Range, name);
           }
       }
       else
       {
           vstoDocument.Controls.Remove(name);
       }
   }
   

   VB

   Friend Sub ToggleRichTextControlOnDocument()
   
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       Dim name As String = "MyRichTextBoxControl"
   
       If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
           Dim selection = Me.Application.Selection
           If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
               richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                       selection.Range, name)
           End If
       Else
           vstoDocument.Controls.Remove(name)
       End If
   End Sub
   

Quitar el control Botón cuando se guarda el documento

Los controles de formularios de Windows Forms no se conservan cuando se guarda y se cierra el documento. Sin embargo, un contenedor de ActiveX para cada control permanece en el documento, y el borde de este contenedor lo pueden ver los usuarios finales cuando se vuelve a abrir el documento. Hay varias maneras de limpiar controles de Windows Forms creados dinámicamente en complementos de VSTO. En este tutorial, quitará mediante programación el Button control cuando se guarde el documento.

Para quitar el control Button cuando el documento se guarda

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

   C#

   private void Application_DocumentBeforeSave(Word.Document Doc, 
       ref bool SaveAsUI, ref bool Cancel)
   {
       bool isExtended = Globals.Factory.HasVstoObject(Doc);
   
   
       if (isExtended)
       {
   
           Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);
   
           if (vstoDocument.Controls.Contains(button))
           {
               vstoDocument.Controls.Remove(button);
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
           }
       }
   }
   

   VB

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

2. 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 con el 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

Por último, modifique los Click controladores de eventos de las casillas que agregó a la cinta de opciones para agregar o quitar controles en el documento.

Para agregar o quitar controles cuando el usuario hace clic en las casillas de la cinta de opciones

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

   C#

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

   VB

   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
   

Probar la solución

Agregue controles a un documento seleccionándolos en la pestaña personalizada de la cinta. Al guardar el documento, el control Button se quita.

Para probar la solución.

1. Presione F5 para ejecutar el proyecto.

2. En el documento activo, presione Entrar varias veces para agregar nuevos párrafos vacíos al documento.

3. Seleccione el primer párrafo.

4. Haga clic en la pestaña Complementos .

5. En el grupo Agregar controles , haga clic en Agregar botón.

   Se mostrará un botón en el primer párrafo.

6. Seleccione el último párrafo.

7. En el grupo Agregar controles , haga clic en Agregar control de texto enriquecido.

   Se agregará un control de contenido de texto enriquecido al último párrafo.

8. Guarde el documento.

   El botón se quitará del documento.

Pasos siguientes

Puede obtener más información acerca de los controles en los complementos de VSTO en estos temas:

• Para ver un ejemplo que muestra cómo agregar muchos otros tipos de controles a un documento en tiempo de ejecución y volver a crear los controles cuando se vuelve a abrir el documento, vea el ejemplo de controles dinámicos de complemento de Word en ejemplos de desarrollo y tutoriales de Office.

• Para ver un tutorial que muestra cómo agregar controles a una hoja de cálculo mediante un complemento VSTO para Excel, vea Tutorial: Agregar controles a una hoja de cálculo en tiempo de ejecución en el proyecto de complemento VSTO.

Contenido relacionado

• Soluciones de Word
• Agregar controles a documentos de Office en tiempo de ejecución
• Conservar controles dinámicos en documentos de Office
• Cómo: Agregar controles de Windows Forms a documentos de Office
• Cómo: Agregar controles de contenido a documentos de Word
• Ampliar documentos de Word y libros de Excel en complementos de VSTO en tiempo de ejecución