Tutorial: usar el módulo guiHelper para mejorar la apariencia visual de nuestras interfaces

A la hora de programar un complemento que tiene algún tipo de interfaz gráfica, o hacer modificaciones a la propia interfaz de NVDA, todos los desarrolladores ciegos nos hacemos la misma pregunta tarde o temprano: ¿cómo se ve en pantalla esto que estoy programando? Podemos probar distintas combinaciones de constantes, posiciones y tamaños para los controles, pero al no poder verlos, probablemente el resultado no sea el que esperamos. En la entrada de hoy vamos a hablar del módulo guiHelper, disponible desde la versión 2016.4 de NVDA. La misión de este módulo es abstraernos un poco de los detalles más visuales del diseño de nuestra interfaz, de tal forma que sólo debamos preocuparnos de añadir controles y funcionalidad. El módulo no hace magia, pero nuestras interfaces quedarán probablemente un poquito mejor que antes. Si quieres conocer este módulo un poco más, sigue leyendo. ¡Allá vamos!
Nota: en este artículo se asume que el lector tiene conocimientos sobre la programación de complementos con interfaz gráfica.

Importar el módulo

El módulo guiHelper se encuentra en el paquete gui. Si nuestro complemento tiene interfaz gráfica, en algún momento seguramente habremos importado los módulos gui y wx, por lo que sólo haría falta escribir esto:
from gui import guiHelper
Una vez hecho esto, ya podremos acceder a sus constantes, funciones y clases.

Constantes de guiHelper

Estas constantes vienen incluidas directamente en el módulo.

• BORDER_FOR_DIALOGS: es el borde que se encuentra alrededor de cada control dentro de un diálogo.
• SPACE_BETWEEN_VERTICAL_DIALOG_ITEMS: cuando los elementos de un diálogo se disponen de manera vertical, esta constante se puede emplear para indicar cuánto espacio hay entre cada elemento.
• SPACE_BETWEEN_BUTTONS_HORIZONTAL: especifica el espacio que hay entre botones dispuestos de manera horizontal.
• SPACE_BETWEEN_BUTTONS_VERTICAL: igual que en el caso anterior, pero se aplica cuando los botones están dispuestos verticalmente unos sobre otros.
• SPACE_BETWEEN_ASSOCIATED_CONTROL_HORIZONTAL: es el espacio que separa a dos controles relacionados dispuestos en horizontal.
• SPACE_BETWEEN_ASSOCIATED_CONTROL_VERTICAL: lo mismo que en el caso anterior, pero en disposiciones verticales.

Funciones de guiHelper

A día de hoy, guiHelper sólo dispone de una función a nivel de módulo: associateElements. Esta función introduce dos controles en un objeto Sizer de wx, situándolos en horizontal o vertical y separándolos adecuadamente según su tipo. Su cabecera es la siguiente:
def associateElements( firstElement, secondElement)
Los controles deben pasarse en el orden en que queremos que se asocien. Las posibles asociaciones son:

• wx.StaticText y wx.Choice, wx.TextCtrl o wx.Button: asocia una etiqueta con un cuadro combinado, un cuadro de edición o un botón, en disposición horizontal.
• wx.StaticText y wx.ListCtrl o wx.ListBox o wx.TreeCtrl: asocia una etiqueta con una presentación en lista, un cuadro de lista o una vista en árbol, en disposición vertical.
• wx.Button y wx.CheckBox: asocia un botón y una casilla de verificación, disposición horizontal.
• wx.TextCtrl y wx.Button: asocia un cuadro de texto y un botón en posición horizontal.

En todos los casos, los controles deben ser objetos ya instanciados. La función devuelve el objeto Sizer que los contiene, listo para añadirlo a un diálogo u otro Sizer.

Clases de guiHelper

El módulo guiHelper dispone de cuatro clases que nos ayudan a construir nuestra interfaz. Aunque vamos a verlas todas, la que más se usa es BoxSizerHelper. Todas ellas tienen el atributo sizer, empleado al construir el resto de la interfaz.

La clase ButtonHelper

Esta clase sirve para añadir el espacio adecuado entre botones, tanto en horizontal como en vertical. Al instanciar objetos a partir de ella, se debe especificar la orientación del Sizer que va a generar, ya sea wx.VERTICAL o wx.HORIZONTAL. Por ejemplo:
bh=guiHelper.ButtonHelper(wx.VERTICAL)
Una vez construido el objeto, podemos agregar botones llamando al método addButton:
bh.addButton(mydialog, label=_("Test button 1"))
El método addButton construye un nuevo botón con los parámetros que le pasemos, o también puede añadir un botón previamente creado. Es imprescindible indicar en el primer caso el diálogo o ventana padre que contendrá al botón, y una etiqueta por razones de accesibilidad con el parámetro label. Al acabar, se devuelve el botón creado para que podamos hacer cosas con él, como asociarle acciones.

La clase LabeledControlHelper

Esta clase permite crear controles etiquetados y asociar etiqueta y control entre sí en un Sizer. Se apoya en la función associateElements que vimos más arriba. La cabecera de su constructor es:
def __init__(self, parent, labelText, wxCtrlClass, **kwargs)
Por lo tanto, para construir un objeto de tipo LabeledControlHelper necesitamos pasar como parámetros el diálogo o ventana padre, el texto de la etiqueta que acompañará al control, la clase del control (cuidado, aquí no valen controles previamente creados), y cualquier argumento que necesite el control para construirse. Veámoslo de forma más clara con un ejemplo:
lch=guiHelper.LabeledControlHelper(mydialog, "Selecciona una fruta", wx.Choice, choices=['pera', 'manzana', 'fresa'])
En el ejemplo anterior hemos pasado como clase wx.Choice para crear un cuadro combinado, y como parámetros adicionales las opciones que presentará.
La clase LabeledControlHelper dispone de dos atributos para que podamos trabajar cómodamente: sizer, igual que en el resto de clases, y control, que hace referencia al control de wx que hemos creado.

La clase PathSelectionHelper

Esta clase nos permite crear de una forma rápida, sencilla y abstrayéndonos de todos los detalles, un cuadro de edición y un botón «Examinar…» como los que aparecen en muchos programas, con el objetivo de que podamos fabricar un selector de rutas. En el constructor le pasamos el padre, como siempre, el texto del botón Examinar, y el título del diálogo que se desplegará para seleccionar una ruta cuando pulsemos dicho botón. Por ejemplo:
psh=guiHelper.PathSelectionHelper(mydialog, "Examinar...", "Selecciona la carpeta que contiene los documentos")
Como en los casos anteriores, tenemos la propiedad sizer, pero además aquí nos acompaña otra: pathControl, que contiene una referencia al cuadro de texto donde está escrita la ruta.
En caso de que sea necesario, se podría crear una clase que herede de esta y sobreescribir o extender los métodos getDefaultBrowseForDirectoryPath y onBrowseForDirectory. El primero devuelve la ruta por defecto que muestra el diálogo de seleccionar carpeta, y el segundo muestra este diálogo y almacena el resultado en el cuadro de edición.

La clase BoxSizerHelper

Llegamos a la clase más importante de este módulo, la más usada, y la que emplea la funcionalidad expuesta en casi todas las otras. BoxSizerHelper permite configurar la disposición interna de un objeto Sizer. La cabecera de su constructor es:
def __init__(self, parent, orientation=None, sizer=None)
Como siempre, el primer argumento que espera recibir es la ventana padre. Después, podemos pasar una orientación (wx.VERTICAL o wx.HORIZONTAL), en cuyo caso se creará internamente un objeto Sizer, o un Sizer ya creado, a ser posible vacío. Si pasamos ambos parámetros, se produce un error.
Al igual que sucede en los casos anteriores, tenemos un atributo sizer. Esta clase, además, presenta los siguientes métodos:

• addItem(self, item, **keywordArgs): añade un control wx ya creado y lo sitúa adecuadamente. El último argumento es opcional y sólo se usa en raras ocasiones. El método devuelve el elemento que se pasa como parámetro, para que podamos asociarle acciones y hacer otras cosas con él.
• addLabeledControl(self, labelText, wxCtrlClass, **kwargs): añade un control etiquetado. El primer parámetro que recibe es el texto con la etiqueta del control, seguido de la clase del control y los parámetros adicionales que se quieran pasar. Fíjate en el ejemplo anterior del cuadro combinado. Este método devuelve el control que se acaba de agregar.
• addDialogDismissButtons(self, buttons): agrega y alinea los botones Aceptar, Cancelar y Aplicar de los diálogos estándar. Este método debería llamarse cuando ya se han añadido todos los demás controles. Buttons puede ser un objeto wx.Button, un objeto wx.Sizer o un objeto guiHelper.ButtonHelper. Devuelve el mismo objeto que se le pasa como parámetro.

Aplicaciones prácticas

Al igual que en una entrada anterior, vamos a poner como ejemplo el complemento Enhanced Aria (aunque esta vez no vendrá solo), para demostrar lo fácil que es adaptar nuestros complementos para que se apoyen en guiHelper. En la versión 1.3, para agregar la primera casilla de verificación del diálogo de ajustes de aria mejorada, se hacía esto:
self.bannerenabled=wx.CheckBox(self, wx.NewId(), label=(u"Report banners")) # Como self es una clase que hereda de wx.Dialog, se pasa como padre
self.bannerenabled.SetValue(config.conf['aria']['reportBanner']) # Se establece el valor de la casilla
sizer.Add(self.bannerenabled,border=10,flag=wx.BOTTOM) # se añade la casilla sizer
Como se puede comprobar, hay que crear la casilla con su etiqueta correspondiente, asignarle el valor adecuado y añadirla al objeto que va a contenerla, con indicadores de borde y alineación. Sin embargo, en la versión 2.0 basta con hacer esto:
def createSettings(obj, sizer):
helper=guiHelper.BoxSizerHelper(obj, sizer=sizer)
obj.bannerenabled=helper.addItem(wx.CheckBox(obj, wx.NewId(), label=("Report banners")))
obj.bannerenabled.SetValue(config.conf['aria']['reportBanner'])
Como se puede ver, creamos un BoxSizerHelper pasando como parámetro el Sizer que nos dan en el método makeSettings, y que en el caso particular de esta implementación se pasa a createSettings. A continuación, agregamos una nueva casilla de verificación llamando a addItem, y luego establecemos su valor.
Veamos el diálogo de Windows 10 App Essentials, que también se apoya en este módulo. Lo podemos encontrar en el archivo w10config.py. Se trata de un diálogo completo, una clase que hereda de wx.Dialog. Por lo tanto, construirlo implica más esfuerzo, al no tener a nuestra disposición la clase SettingsDialog de NVDA o la clase SettingsPanel. En lugar del método makeSettings, que ya nos da un Sizer, las operaciones de construcción se hacen en el constructor del diálogo.
En primer lugar, se crea un objeto de tipo BoxSizer:
mainSizer = wx.BoxSizer(wx.VERTICAL)
Y a continuación, se crea un BoxSizerHelper con un Sizer nuevo, que será hijo del que se acaba de crear:
w10Helper = gui.guiHelper.BoxSizerHelper(self, orientation=wx.VERTICAL)
Teniendo el BoxSizerHelper, ya se pueden añadir controles. Vamos a ver dos de ellos, la casilla de verificación y el cuadro combinado.
self.autoUpdateCheckbox=w10Helper.addItem(wx.CheckBox(self,label=_("Automatically check for add-on &updates"))) # Se crea la casilla
self.autoUpdateCheckbox.SetValue(config.conf["wintenApps"]["autoUpdateCheck"]) # Se establece su valor
labelText = _("&Add-on update channel:") # Etiqueta del cuadro combinado
self.channels=w10Helper.addLabeledControl(labelText, wx.Choice, choices=["development", "stable"]) # Cuadro combinado
Ya para acabar, se añaden los botones Aceptar y cancelar, y se hace de una forma muy particular, ya predefinida en wx:
w10Helper.addDialogDismissButtons(self.CreateButtonSizer(wx.OK | wx.CANCEL))
En este caso no existe acceso directo a los botones, como sí pasa con el resto de los controles, así que las asociaciones se hacen de esta manera:
self.Bind(wx.EVT_BUTTON, self.onOk, id=wx.ID_OK)
self.Bind(wx.EVT_BUTTON, self.onCancel, id=wx.ID_CANCEL)
El BoxSizerHelper ya está completo, hay que añadirlo al Sizer principal. Una vez más, se pide ayuda a guiHelper, y al propio motor wx para centrarlo y posicionarlo:
mainSizer.Add(w10Helper.sizer, border=gui.guiHelper.BORDER_FOR_DIALOGS, flag=wx.ALL)
mainSizer.Fit(self)
self.Center(wx.BOTH | (wx.CENTER_ON_SCREEN if hasattr(wx, "CENTER_ON_SCREEN") else 2))

Conclusión

Es importante que nuestros complementos e interfaces gráficas en general sean visualmente usables. Aunque NVDA es un lector de pantalla empleado mayoritariamente por personas con discapacidad visual, estas personas suelen estar acompañadas por otras que ven perfectamente, especialmente cuando se introducen en el mundo de la informática. Por tanto, debemos tener en cuenta a todos los posibles usuarios.
En esta entrada hemos conocido el módulo guiHelper, que nos ayuda precisamente en esta tarea. GuiHelper no hace magia, no tiene ningún tipo de «inteligencia artificial» que coloque nuestros controles exactamente como deberían estar para que nuestra interfaz sea atractiva. Sin embargo, nos ayuda un poco a conseguirlo, simplifica nuestro código y por lo tanto facilita el mantenimiento.
Si tus complementos no se apoyan todavía en este módulo, no esperes más para adaptarlos. Tus usuarios lo agradecerán, ¡y tú también!