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

Puede agregar controles a cualquier documento de Microsoft Office Word abierto mediante un complemento de nivel de 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.

Se aplica a: la información de este tema se aplica a los proyectos de nivel de aplicación para Word 2007 y Word 2010. Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto de Office.

En este tutorial se muestran 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:

-

Una edición de Visual Studio 2010 que incluye las herramientas para desarrolladores de Microsoft Office. Para obtener más información, vea [Configurar un equipo para desarrollar soluciones de Office](bb398242\(v=vs.100\).md).

• Word 2007 o Word 2010.

Crear un nuevo proyecto de complemento de Word

Comience por crear un proyecto de complemento de Word.

Para crear un nuevo proyecto de complemento de Word

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

2. Si su proyecto está destinado a .NET Framework 4, 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 posteriormente en este tutorial.

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

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 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.

4. En el diseñador de la Cinta de opciones, haga clic en group1.

5. En la ventana Propiedades, cambie la propiedad Label de group1 por Add Controls.

6. Desde la ficha Controles de la cinta de opciones 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
   Name	addButtonCheckBox
   Etiqueta	Botón Agregar

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

   Propiedad	Valor
   Name	addRichTextCheckBox
   Etiqueta	Add Rich Text Control

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

    El controlador del evento Click de la casilla Add Button se abre en el Editor de código.

11. Vuelva al Diseñador de la cinta de opciones y haga doble clic en Add Rich Text Control.

    El controlador del evento Click de la casilla Add Rich Text Control 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 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 proyectos de complementos de nivel de 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

1. 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.

2. 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;
   

3. 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 un control Button a la selección actual del documento si la casilla está activada o quita el control Button si está desactivada.

   Friend Sub ToggleButtonOnDocument()
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
   
       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
   

   internal void ToggleButtonOnDocument()
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();
   
       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);
       }
   }
   

4. 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 un control RichTextContentControl a la selección actual en el documento si la casilla está activada o quita el control RichTextContentControl si está desactivada.

   Friend Sub ToggleRichTextControlOnDocument()
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()
   
       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
   

   internal void ToggleRichTextControlOnDocument()
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();
   
       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);
       }
   }
   

Quitar el control de botón 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 de botón cuando se guarda el documento

1. 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
       ' Use the following line of code in projects that target the .NET Framework 4.
       Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)
   
       ' In projects that target the .NET Framework 3.5, use the following line of code.
       ' Dim isExtended As Boolean = Doc.HasVstoObject()
   
       If isExtended Then
           ' Use the following line of code in projects that target the .NET Framework 4.
           Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)
   
           ' In projects that target the .NET Framework 3.5, use the following line of code.
           ' 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)
   {
       // Use the following line of code in projects that target the .NET Framework 4.
       bool isExtended = Globals.Factory.HasVstoObject(Doc);
   
       // In projects that target the .NET Framework 3.5, use the following line of code.
       // bool isExtended = Doc.HasVstoObject();
   
       if (isExtended)
       {
           // Use the following line of code in projects that target the .NET Framework 4.
           Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);
   
           // In projects that target the .NET Framework 3.5, use the following line of code.
           // Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();
   
           if (vstoDocument.Controls.Contains(button))
           {
               vstoDocument.Controls.Remove(button);
               Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
           }
       }
   }
   

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 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.

1. Presione F5 para ejecutar el proyecto.

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

3. Seleccione el primer párrafo.

4. Haga clic en la ficha Complementos.

5. En el grupo Agregar controles, haga clic en Add Button.

   Aparece un botón en el primer párrafo.

6. Seleccione el último párrafo.

7. 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.

8. 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 de cómo se agregan en tiempo de ejecución muchos otros tipos de controles a un documento y cómo se vuelven a crear esos controles cuando se vuelve a abrir el documento, vea Ejemplo Word Add-In Dynamic Controls en Ejemplos y tutoriales del desarrollo de Office.

• 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.

Vea también

Tareas

Cómo: Agregar controles de Windows Forms a documentos de Office

Cómo: Agregar controles de contenido a documentos de Word

Conceptos

Agregar controles a documentos de Office en tiempo de ejecución

Guardar controles dinámicos en documentos de Office

Ampliar documentos de Word y libros de Excel en complementos en el nivel de la aplicación en tiempo de ejecución

Otros recursos

Soluciones de Word

Word Add-In Dynamic Controls Sample