¡Hola a todos!
Faltan un par de semanas para que NVDA 2018.2 vea la luz, y sin embargo nadie ha parado de hablar de los cambios que trae desde hace ya un tiempo. Uno de los más importantes es el nuevo diálogo de preferencias organizado en categorías, al que hemos hecho referencia ya en varias entradas al hablar de complementos que se actualizan. En este tutorial veremos qué hay que hacer para que el diálogo de preferencias de nuestro complemento se integre en el nuevo diálogo de opciones de NVDA. Nos apoyaremos en el complemento Enhanced Aria, ya que su código es bastante simple, está en un único módulo y los cambios realizados son relativamente sencillos de entender. ¡Comencemos!
Nota: este es un artículo avanzado de desarrollo. Se asume que el lector sabe hacer complementos sencillos, y conoce el lenguaje Python con todo lo que ello conlleva.
Creación de ajustes sensibles a cambios de perfil
NVDA nos da mucha flexibilidad a la hora de crear diálogos para nuestros complementos. De hecho, nos da tanta que nos podemos perder, hacernos un lío, y programar todo con wx para luego darnos cuenta de que existen módulos que nos abstraen de un montón de detalles complejos. Con la configuración pasa exactamente lo mismo, podemos saber que existe configobj, pero ignorar que hay una capa por encima que nos facilita la vida. Definir una especificación de configuración es tan sencillo como crear una variable global en el módulo de nuestro complemento, indicando de qué tipo son los valores y el valor por defecto de cada uno. Esta es la configuración de Enhanced Aria:
confspec={
"reportBanner":"boolean(default=true)",
"reportMain":"boolean(default=true)",
"reportContentinfo":"boolean(default=true)",
"reportNavigation":"boolean(default=true)",
"reportComplementary":"boolean(default=true)",
...}
En el caso de Enhanced Aria, todo lo que se configura es booleano, casillas que se marcan o desmarcan. Una vez definida la especificación, hay que decirle a NVDA que la añada al conjunto de especificaciones. Una variable global definida por sí sola en un módulo no va a hacer nada: config.conf.spec['aria']=confspec
Después de este inciso, breve pero necesario para entender todo lo demás, vamos a los diálogos en sí.
El diálogo tradicional de ajustes
Un diálogo tradicional de ajustes es una clase que hereda de gui.settingsDialogs.SettingsDialog. ¡Cuidado con las mayúsculas al programar, nos pueden hacer pasar un mal rato! Todos los diálogos de preferencias de NVDA heredan de esta clase, y los complementos también suelen hacerlo. La clase SettingsDialog nos ofrece varios métodos y propiedades que podemos redefinir:
- title: propiedad que define el título del diálogo. Debe ser una cadena de caracteres.
- makeSettings(self, sizer): este método se usa para rellenar el sizer que se recibe como parámetro con los controles que queramos. Enseguida vemos un ejemplo.
- postInit(self): se ejecuta tras crear y mostrar el diálogo en pantalla. Sirve para llevar el foco por defecto a un control que nos interese, por ejemplo.
- onOk(self, evt): NVDA llama a este método cuando se pulse el botón aceptar. Los botones Aceptar y Cancelar vienen ya en la clase padre, no tenemos que añadirlos en makeSettings. Aquí se hacen cosas tales como guardar la configuración. Importante llamar al método de la clase padre cuando terminemos.
- onCancel(self, evt): método que se ejecuta al pulsar el botón cancelar. Importante llamar al método de la clase padre si lo redefinimos.
NVDA 2018.2 extiende este diálogo añadiendo un botón de aplicar, el evento asociado (onApply), y la posibilidad de que el diálogo pueda abrirse varias veces simultáneamente. Todas estas novedades son opcionales para conservar la compatibilidad con complementos que no se adapten a ellas.
Veamos algunos ejemplos. El título de Enhanced Aria es traducible a otros idiomas, y quedaría así: title=(u"Enhanced Aria settings")
El método makeSettings sería el siguiente. Para no hacer muy pesada la lectura, se pondrá sólo una parte:
def makeSettings(self, sizer):(u"Report banners"))
#TRANSLATORS: report banners checkbox
self.bannerenabled=wx.CheckBox(self, wx.NewId(), label=
self.bannerenabled.SetValue(config.conf['aria']['reportBanner'])
sizer.Add(self.bannerenabled,border=10,flag=wx.BOTTOM)
#TRANSLATORS: report main content checkbox
self.mainenabled=wx.CheckBox(self, wx.NewId(), label=(u"Report main content"))
self.mainenabled.SetValue(config.conf['aria']['reportMain'])
sizer.Add(self.mainenabled,border=10,flag=wx.BOTTOM)
#TRANSLATORS: report search forms checkbox
self.searchenabled=wx.CheckBox(self, wx.NewId(), label=(u"Report search forms"))
self.searchenabled.SetValue(config.conf['aria']['reportSearch'])
sizer.Add(self.searchenabled,border=10,flag=wx.BOTTOM)
...
Como se puede ver, no sólo creamos, etiquetamos y añadimos casillas de verificación, sino que establecemos su valor basándonos en la configuración actual. Una vez creadas, postInit hace lo siguiente:
def postInit(self):
self.bannerenabled.SetFocus()
Nuestro diálogo ya está listo. Como se puede intuir, no se ha redefinido el método onCancel, que simplemente descarta todo y no tiene que hacer nada más. Sin embargo, el método onOk sí tiene trabajo.
def onOk(self, evt):
config.conf['aria']['reportBanner']=self.bannerenabled.GetValue()
config.conf['aria']['reportMain']=self.mainenabled.GetValue()
config.conf['aria']['reportSearch']=self.searchenabled.GetValue()
config.conf['aria']['reportForm']=self.formenabled.GetValue()
...
applyConfig()
super(enhancedAriaSettings, self).onOk(evt) # Importante, llamada al padre!
Y ahora, ¿qué hacemos para poder llegar a este diálogo?
Como bien se ha dicho antes, la magia no existe. En el método init de la clase GlobalPlugin, hay que crear un elemento de menú y asociarlo al submenú preferencias de NVDA.
self.prefsMenu = gui.mainFrame.sysTrayIcon.menu.GetMenuItems()[0]
#TRANSLATORS: The configuration option in NVDA Preferences menu
self.enhancedAriaSettingsItem = self.prefsMenu.Append(wx.ID_ANY, _(u"Enhanced aria settings..."), _(u"Change enhanced Aria settings"))
gui.mainFrame.sysTrayIcon.Bind(wx.EVT_MENU, self.onEnhancedAriaMenu, self.enhancedAriaSettingsItem) # Asociamos abrir el menú a activar el diálogo
No debemos olvidarnos de eliminar el elemento de menú en el método terminate, de lo contrario aparecerá duplicado al recargar las extensiones: self.prefsMenu.RemoveItem(self.enhancedAriaSettingsItem)
Para activar el diálogo, hacemos algo como esto: gui.mainFrame._popupSettingsDialog(enhancedAriaSettings)
Esta es la clase que contiene nuestro diálogo, enhancedAriaSettings. Pero lo hará por poco tiempo, ¡es hora de dar el salto al diálogo de categorías!
El panel de configuración en el diálogo de categorías
Para añadir paneles de configuración al diálogo de opciones, simplemente debemos crear una clase que herede de gui.settingsDialogs.SettingsPanel, y añadir nuestro panel al diálogo de opciones de NVDA, que está definido como variable global en el módulo gui. Esta clase nos ofrece los siguientes métodos y propiedades:
- title: el título del panel de configuración.
- makeSettings(self, sizer): al igual que antes, se nos pasa un sizer que rellenaremos con controles.
- onSave(self): código que se ejecuta al pulsar los botones aceptar o aplicar del diálogo. Ya no es necesario llamar al método padre, como sí pasaba en onOk.
- onPanelActivated(self): código que se ejecuta cuando se selecciona este panel. Aquí sí se debería llamar al método padre. Sin embargo, no deberíamos mover el foco como se hacía en postInit.
- onPanelDeactivated(self): código que se ejecuta al abandonar el panel. Se debe llamar al método padre si lo redefinimos.
- onDiscard(self): método que se llama al salir del diálogo de opciones sin guardar los cambios.
Una vez definido nuestro panel, debemos agregarlo al diálogo de opciones de NVDA. Por ejemplo, en el método init de la clase GlobalPlugin: NVDASettingsDialog.categoryClasses.append(enhancedAriaPanel)
Y por supuesto, eliminarlo en el método terminate, de lo contrario nos arriesgamos a que se duplique: NVDASettingsDialog.categoryClasses.remove(enhancedAriaPanel)
El código queda más simple, ¿verdad? Es muy sencillo hacer un complemento con preferencias que se adapte a NVDA 2018.2. Y como a mí no me gusta lo fácil, vamos a complicarlo un poco: vamos a añadir compatibilidad entre versiones. Puede haber gente que no quiera actualizar NVDA, y no debemos olvidarnos de ellos.
Soporte para todas las versiones de NVDA posibles
Llegados a este punto, podríamos tener dos clases: una con el diálogo y otra con el panel. Podríamos añadir el panel al diálogo de opciones y crear un elemento de menú en el submenú preferencias, y no pasaría nada. Como ya se ha dicho, NVDA nos da flexibilidad. ¿Permitiría esto que nuestro complemento adaptado funcionase con versiones antiguas? La respuesta ya te la puedes imaginar, si fuera afirmativa no existiría este apartado en el tutorial.
Por un lado, tal y como está, nuestro complemento muere estrepitosamente en NVDA 2018.1.1, diciendo que hay módulos que no encuentra. Por otro, queremos que el elemento de menú aparezca en versiones antiguas, y el panel del diálogo de opciones en las nuevas. Para lo último, en los métodos init y terminate de GlobalPlugin, podemos hacer algo como esto.
Método init:
if hasattr(settingsDialogs, 'SettingsPanel'): # Es el nuevo NVDA
NVDASettingsDialog.categoryClasses.append(enhancedAriaPanel)
else:
self.prefsMenu = gui.mainFrame.sysTrayIcon.menu.GetMenuItems()[0].GetSubMenu()
#TRANSLATORS: The configuration option in NVDA Preferences menu
self.enhancedAriaSettingsItem = self.prefsMenu.Append(wx.ID_ANY, _(u"Enhanced aria settings..."), _(u"Change enhanced Aria settings"))
gui.mainFrame.sysTrayIcon.Bind(wx.EVT_MENU, self.onEnhancedAriaMenu, self.enhancedAriaSettingsItem)
Método terminate:
if hasattr(settingsDialogs, 'SettingsPanel'):
NVDASettingsDialog.categoryClasses.remove(enhancedAriaPanel)
else: # Es el antiguo
self.prefsMenu.RemoveItem(self.enhancedAriaSettingsItem)
Como se puede comprobar, miramos si existen atributos que sólo podrían existir en NVDA 2018.2.
De cara a la importación de módulos, podríamos hacer algo como esto:
import gui
from gui import settingsDialogs
try:
from gui import NVDASettingsDialog
from gui.settingsDialogs import SettingsPanel
except:
pass # No hacer nada si falla
El planteamiento está muy bien. Si falla al importar las clases es porque no existen, ya que estamos en un NVDA antiguo. Por lo tanto, nos olvidamos del panel y usamos el elemento de menú y el diálogo clásico. ¿Todos estamos deacuerdo? Sí, excepto el intérprete Python.
Cuando Python lea nuestro archivo de complemento, verá que intentamos definir la clase del panel, y que indicamos un padre que no existe porque no lo hemos importado. Por suerte, Python es tan flexible como NVDA: cualquier variable se puede asignar a cualquier cosa, sin importar el tipo e incluso sin que importe que sea una clase o función. Lo único que nos pide es algo de lo que pueda heredar el panel, así que vamos a darle el objeto base del lenguaje: object. En la cláusula except, en vez de poner pass para que no haga nada, hacemos: SettingsPanel=object
Optimización de código
Es tentador copiar y pegar código de unos métodos a otros. En el caso de EnhancedAria, siempre define las mismas casillas, y siempre guarda la misma configuración. Sin embargo, no es una buena práctica, ya que si tenemos un fallo este también se duplica, y hay que corregirlo tantas veces como se haya hecho el copia-pega. Por lo tanto, se ha sacado el código repetido y se ha metido en funciones globales del módulo:
- addonSettingsTitle: título del diálogo y del panel. Es el mismo en ambos casos. Si lo dejamos duplicado, un traductor tendría que modificarlo dos veces.
- createSettings(obj, sizer): obj es una referencia al objeto que llama a la función. Es como el self que vimos antes. Esta función crea las casillas.
- storeSettings(obj): almacena los ajustes al pulsar el botón aceptar.
Haciendo estos cambios, el tamaño de las clases se reduce. Así quedaría el método onSave:
def onSave(self):
storeSettings(self)
Conclusión
Existen muchas formas de adaptar nuestros complementos para que aprovechen las nuevas características introducidas en NVDA 2018.2. Podemos modificarlos, o podemos dejarlos como están. Sin embargo, para proporcionar una experiencia de usuario consistente, se recomienda lo primero más que lo segundo. En este tutorial se ha visto sólo una de las muchísimas alternativas existentes. Tanto Python como NVDA son flexibles, permitiendo que cada desarrollador haga las cosas a su manera y optimice el código como le parezca oportuno. Por ejemplo, la simplificación de código vista anteriormente podría haberse hecho definiendo una clase y aplicando herencia múltiple, si bien es cierto que este enfoque podría complicar un poco las cosas. Espero que hayáis disfrutado leyendo este tutorial tanto como yo al escribirlo, y que os sirva para poner vuestros complementos al día. Para cualquier pregunta o sugerencia, no dudéis en dejarnos un comentario debajo.
¡Hasta la próxima!
