Barras de herramientas en Xamarin.Mac

En este artículo se describe cómo trabajar con barras de herramientas en una aplicación de Xamarin.Mac. Abarca la creación y el mantenimiento de barras de herramientas en Xcode e Interface Builder, su exposición al código y el trabajo con ellas mediante programación.

Los desarrolladores de Xamarin.Mac que trabajan con Visual Studio para Mac tienen acceso a los mismos controles de interfaz de usuario disponibles para los desarrolladores de macOS que trabajan con Xcode, incluido el control de la barra de herramientas. Dado que Xamarin.Mac se integra directamente con Xcode, es posible usar Interface Builder de Xcode para crear y mantener elementos de la barra de herramientas. Estos elementos de la barra de herramientas también pueden crearse en C#.

Las barras de herramientas en macOS se agregan a la parte superior de una ventana y proporcionan un fácil acceso a los comandos relacionados con su funcionalidad. Los usuarios de una aplicación pueden ocultar, mostrar o personalizar las barras de herramientas, y pueden presentar los elementos de la barra de herramientas de diversas formas.

En este artículo se tratan los aspectos básicos del trabajo con barras de herramientas y elementos de barras de herramientas en una aplicación de Xamarin.Mac.

Antes de continuar, lea el artículo Hello, Mac (en concreto las secciones Introducción a Xcode e Interface Builder y Salidas y acciones), ya que abarca conceptos y técnicas clave que se usarán a lo largo de esta guía.

Eche también un vistazo a la sección Exposición de clases / métodos de C# a Objective-C del documento Xamarin.Mac Internals. Explica los atributos Register y Export usados para conectar clases C# con clases Objective-C.

Introducción a las barras de herramientas

Cualquier ventana de una aplicación de macOS puede incluir una barra de herramientas:

Las barras de herramientas ofrecen a los usuarios de su aplicación un modo sencillo de acceder rápidamente a las características importantes o de uso común. Por ejemplo, una aplicación de edición de documentos puede proporcionar elementos en la barra de herramientas para establecer el color del texto, cambiar el tipo de letra o imprimir el documento actual.

Las barras de herramientas pueden mostrar elementos de tres maneras:

1. Icono y texto

   

2. Solo icono

   

3. Solo texto

   

Cambie entre estos modos haciendo clic con el botón derecho del ratón en la barra de herramientas y seleccionando un modo de visualización en el menú contextual:

Use el mismo menú para mostrar la barra de herramientas con un tamaño menor:

El menú también permite personalizar la barra de herramientas:

Al configurar una barra de herramientas en Interface Builder de Xcode, un desarrollador puede proporcionar elementos adicionales a la barra de herramientas que no formen parte de su configuración predeterminada. Así, los usuarios de la aplicación pueden personalizar la barra de herramientas, añadiendo y eliminando estos elementos predefinidos según sea necesario. Por supuesto, la barra de herramientas se puede restablecer a su configuración predeterminada.

La barra de herramientas se conecta automáticamente al menú Vista, que permite a los usuarios ocultarla, mostrarla y personalizarla:

Consulte la documentación Funcionalidad de menú incorporado para obtener más detalles.

Además, si la barra de herramientas está correctamente configurada en Interface Builder, la aplicación conservará automáticamente las personalizaciones de la barra de herramientas en varios inicios de la aplicación.

Las siguientes secciones de esta guía describen cómo crear y mantener barras de herramientas con Interface Builder de Xcode y cómo trabajar con ellas en código.

Establecimiento de un controlador de ventana principal personalizado

Para exponer los elementos de la interfaz de usuario al código C# mediante salidas y acciones, la aplicación Xamarin.Mac debe usar un controlador de ventana personalizado:

1. Abra el guion gráfico de la aplicación en Interface Builder de Xcode.

2. Seleccione el controlador de ventana en la superficie de diseño.

3. Cambie al Inspector de identidad y escriba "WindowController" como Nombre de clase:

   

4. Guarde los cambios y vuelva a Visual Studio para Mac para sincronizar.

5. Se agregará un archivo WindowController.cs a su proyecto en el Panel de solución de Visual Studio para Mac:

   

6. Vuelva a abrir el guion gráfico en Interface Builder de Xcode.

7. El archivo WindowController.h estará disponible para usarse:

   

Creación y mantenimiento de barras de herramientas en Xcode

Las barras de herramientas se crean y mantienen con Interface Builder de Xcode. Para agregar una barra de herramientas a una aplicación, edite el Guion gráfico principal de la aplicación (en este caso Main.storyboard) haciendo doble clic en él en el Panel de solución:

En el Inspector de biblioteca, escriba "herramienta" en el Cuadro de búsqueda para que sea más fácil ver todos los elementos disponibles de la barra de herramientas:

Arrastre una barra de herramientas a la ventana en el Editor de interfaz. Con la barra de herramientas seleccionada, configure su comportamiento estableciendo las propiedades en el Inspector de atributos:

Están disponibles las propiedades siguientes:

1. Mostrar: controla si la barra de herramientas muestra iconos, texto o ambos
2. Visible al iniciar: si se selecciona, la barra de herramientas estará visible de manera predeterminada.
3. Personalizable: si está seleccionado, los usuarios pueden editar y personalizar la barra de herramientas.
4. Separador: si está seleccionado, una línea horizontal delgada separa la barra de herramientas del contenido de la ventana.
5. Tamaño: establece el tamaño de la barra de herramientas.
6. Autoguardado: si está seleccionado, la aplicación conservará los cambios de configuración de la barra de herramientas de un usuario en los inicios de la aplicación.

Seleccione la opción Guardado automático y deje el resto de propiedades en su configuración predeterminada.

Tras abrir la barra de herramientas en la Jerarquía de interfaces, abra el diálogo de personalización seleccionando un elemento de la barra de herramientas:

Use este cuadro de diálogo para establecer las propiedades de los elementos que ya forman parte de la barra de herramientas, para diseñar la barra de herramientas predeterminada de la aplicación y para proporcionar elementos adicionales de la barra de herramientas que el usuario pueda seleccionar al personalizarla. Para agregar elementos a la barra de herramientas, arrástrelos desde el Inspector de biblioteca:

Se pueden agregar los siguientes elementos de la barra de herramientas:

• Elemento de barra de herramientas de imágenes: un elemento de barra de herramientas con una imagen personalizada como un icono.

• Elemento de barra de herramientas de espacio flexible: espacio flexible usado para justificar los elementos posteriores de la barra de herramientas. Por ejemplo, uno o más elementos de la barra de herramientas seguidos de un elemento de la barra de herramientas de espacio flexible y otro elemento de la barra de herramientas anclarían el último elemento a la derecha de la barra de herramientas.

• Elemento de barra de herramientas de espacio: espacio fijo entre los elementos de la barra de herramientas

• Elemento de barra de herramientas de separador: un separador visible entre dos o más elementos de barra de herramientas, para agrupar

• Personalizar elemento de barra de herramientas: permite a los usuarios personalizar la barra de herramientas.

• Elemento de barra de herramientas de impresión: permite a los usuarios imprimir el documento abierto

• Elemento de barra de herramientas de mostrar colores: muestra el selector de colores del sistema estándar:

  

• Elemento de barra de herramientas de mostrar fuente: muestra el diálogo de fuentes estándar del sistema:

  

Agregar un elemento a una barra de herramientas

Para agregar un elemento a una barra de herramientas, selecciónela en la Jerarquía de interfaces y haga clic en uno de sus elementos, con lo que aparecerá el cuadro de diálogo de personalización. A continuación, arrastre un nuevo elemento desde el Inspector de biblioteca al área Elementos permitidos de la barra de herramientas:

Para asegurarse de que un nuevo elemento forma parte de la barra de herramientas predeterminada, arrástrelo al área Elementos de la barra de herramientas predeterminada:

Para reordenar los elementos predeterminados de la barra de herramientas, arrástrelos hacia la izquierda o hacia la derecha.

A continuación, use el Inspector de atributos para establecer las propiedades predeterminadas del elemento:

Están disponibles las propiedades siguientes:

• Nombre de imagen: imagen que se va a usar como icono para el elemento
• Etiqueta: texto que se va a mostrar para el elemento de la barra de herramientas
• Etiqueta de paleta: texto que se va a mostrar para el elemento en el área Elementos permitidos de la barra de herramientas
• Etiqueta: un identificador único opcional que ayuda a identificar el elemento en el código.
• Identificador: define el tipo de elemento de la barra de herramientas. Se puede usar un valor personalizado para seleccionar un elemento de barra de herramientas en el código.
• Seleccionable: si está activado, el elemento actuará como un botón de activado o desactivado.

Adición de otros controles de interfaz de usuario a una barra de herramientas

También se pueden agregar a una barra de herramientas varios elementos de la interfaz de usuario Cocoa, como campos de búsqueda y controles segmentados.

Para probarlo, abra la barra de herramientas en la Jerarquía de interfaces y seleccione un elemento de la barra de herramientas para abrir el cuadro de diálogo de personalización. Arrastre un Campo de búsqueda del Inspector de biblioteca al área de Elementos permitidos de la barra de herramientas:

A partir de aquí, use Interface Builder para configurar el campo de búsqueda y exponerlo al código a través de una acción o salida.

Compatibilidad integrada con elementos de la barra de herramientas

Varios elementos de la interfaz de usuario Cocoa interactúan de manera predeterminada con elementos estándar de la barra de herramientas. Por ejemplo, arrastre una Vista de texto a la ventana de la aplicación y colóquela de forma que llene el área de contenido:

Guarde el documento, vuelva a Visual Studio para Mac para sincronizarlo con Xcode, ejecute la aplicación, escriba algo de texto, selecciónelo y haga clic en el elemento de la barra de herramientas Colores. Observe que la Vista de texto funciona automáticamente con el selector de color:

Uso de imágenes con elementos de la barra de herramientas

Usando un Elemento de barra de herramientas de imágenes, cualquier imagen de mapa de bits agregada a la carpeta Recursos (y a la que se haya dado una acción de compilación de Recurso de agrupación) puede mostrarse en la barra de herramientas como un icono:

1. En Visual Studio para Mac, en Panel de solución, haga clic con el botón derecho del ratón en la carpeta Recursos y seleccione Añadir>Añadir archivos.

2. En el cuadro de diálogo Añadir archivos, navegue hasta las imágenes que desee, selecciónelas y haga clic en el botón Abrir:

   

3. Seleccione Copiar, haga clic en Usar la misma acción para todos los archivos seleccionados y haga clic en Aceptar:

   

4. En el Panel de solución, haga doble clic en MainWindow.xib para abrirlo en Xcode.

5. Seleccione la barra de herramientas en la Jerarquía de interfaces y haga clic en uno de sus elementos para abrir el cuadro de diálogo de personalización.

6. Arrastre un Elemento de la barra de herramientas de imagen del Inspector de biblioteca al área Elementos permitidos de la barra de herramientas de la barra de herramientas:

   

7. En el Inspector de atributos, seleccione la imagen que acaba de agregar en Visual Studio para Mac:

   

8. Establezca la Etiqueta en "Papelera" y la Etiqueta de paleta en "Borrar documento":

   

9. Arrastre un Elemento de la barra de herramientas de separador del Inspector de biblioteca al área Elementos permitidos de la barra de herramientas de la barra de herramientas:

   

10. Arrastre el elemento separador y el elemento "Papelera" al área Elementos predeterminados de la barra de herramientas y establezca el orden de los elementos de la barra de herramientas de izquierda a derecha como se indica a continuación (Colores, Fuentes, Separador, Papelera, Espacio flexible, Impresión):

    

11. Guarde los cambios y vuelva a Visual Studio para Mac para sincronizarlo con Xcode.

Ejecute la aplicación para comprobar que la nueva barra de herramientas aparece de manera predeterminada:

Exponer elementos de la barra de herramientas con salidas y acciones

Para acceder a una barra de herramientas o a un elemento de la barra de herramientas en código, debe estar unido a una salida o a una acción:

1. En el Panel de solución, haga doble clic en Main.storyboard para abrirlo en Xcode.

2. Asegúrese de que la clase personalizada "WindowController" se ha asignado al controlador de la ventana principal en el Inspector de identidad:

   

3. A continuación, seleccione el elemento de la barra de herramientas en la Jerarquía de interfaces:

   

4. Abra la Vista de asistente, seleccione el archivo WindowController.h y arrastre con la tecla control desde el elemento de la barra de herramientas hasta el archivo WindowController.h.

5. Establezca el tipo de Conexión en Acción, escriba "trashDocument" en Nombre y haga clic en el botón Conectar:

   

6. Exponga la Vista de texto como una salida denominada "documentEditor" en el archivo ViewController.h:

   

7. Guarde los cambios y vuelva a Visual Studio para Mac para sincronizarlo con Xcode.

En Visual Studio para Mac, edite el archivo ViewController.cs y agregue el siguiente código:

public void EraseDocument() {
    documentEditor.Value = "";
}

A continuación, edite el archivo WindowController.cs y agregue el siguiente código en la parte inferior de la clase WindowController:

[Export ("trashDocument:")]
void TrashDocument (NSObject sender) {

    var controller = ContentViewController as ViewController;
    controller.EraseDocument ();
}

Al ejecutar la aplicación, el elemento Papelera de la barra de herramientas estará activo:

Observe que el elemento Papelera de la barra de herramientas puede usarse ahora para eliminar texto.

Deshabilitación de elementos de la barra de herramientas

Para deshabilitar un elemento de una barra de herramientas, cree una clase NSToolbarItem personalizada e invalide el método Validate. Después, en Interface Builder, asigne el tipo personalizado al elemento que quiere habilitar/deshabilitar.

Para crear una clase personalizada NSToolbarItem, haga clic con el botón derecho del ratón en el proyecto y seleccione Añadir>Nuevo archivo.... Seleccione General>Clase vacía, escriba "ActivatableItem" para el Nombre y haga clic en el botón Nuevo:

A continuación, edite el archivo ActivatableItem.cs para que diga lo siguiente:

using System;

using Foundation;
using AppKit;

namespace MacToolbar
{
    [Register("ActivatableItem")]
    public class ActivatableItem : NSToolbarItem
    {
        public bool Active { get; set;} = true;

        public ActivatableItem ()
        {
        }

        public ActivatableItem (IntPtr handle) : base (handle)
        {
        }

        public ActivatableItem (NSObjectFlag  t) : base (t)
        {
        }

        public ActivatableItem (string title) : base (title)
        {
        }

        public override void Validate ()
        {
            base.Validate ();
            Enabled = Active;
        }
    }
}

Haga doble clic en Main.storyboard para abrirlo en Xcode. Seleccione el elemento Papelera de la barra de herramientas creado anteriormente y cambie su clase a "ActivatableItem" en el Inspector de identidad:

Cree una salida llamada trashItem para el elemento Papelera de la barra de herramientas. Guarde los cambios y vuelva a Visual Studio para Mac para sincronizarlo con Xcode. Por último, abra MainWindow.cs y actualice el método AwakeFromNib para que quede como sigue:

public override void AwakeFromNib ()
{
    base.AwakeFromNib ();

    // Disable trash
    trashItem.Active = false;
}

Ejecute la aplicación y observe que el elemento Papelera está ahora deshabilitado en la barra de herramientas:

Resumen

En este artículo se ha echado un vistazo detallado al trabajo con barras de herramientas y elementos de barras de herramientas en una aplicación de Xamarin.Mac. Describe cómo crear y mantener barras de herramientas en Interface Builder de Xcode, cómo algunos controles de interfaz de usuario trabajan automáticamente con elementos de la barra de herramientas, cómo trabajar con barras de herramientas en código C# y cómo habilitar y deshabilitar elementos de la barra de herramientas.

Vínculos relacionados

• Hello, Mac
• Directrices de interfaz humana para barras de herramientas
• Introducción a las barras de herramientas