Caja de herramientas de desarrollo y pruebas para NVDA

• Autor: Cyrille Bougot
• Versión actual: 6.3 estable
• Compatibilidad con NVDA: de 2019.2 en adelante
• Ver este complemento en la web de la comunidad internacional
• Descargar versión estable
• Ver código fuente en GitHub

Este complemento reúne diversas funciones para depuración y pruebas en NVDA.

Características

• Un diálogo mejorado para reiniciar que permite indicar algunas opciones
  extra cuando se reinicia NVDA.
• Un script de conmutación y un backport de la función «Reproducir un sonido
  para los errores registrados» de NVDA.
• Un explorador de propiedades de los objetos.
• Un modo de descripción extendida para los scripts: cuando está activado,
  el modo ayuda de entrada anuncia información de los scripts que no tienen
  descripción.
• Órdenes para ayudar con la lectura y el análisis del registro.
• En el espacio de trabajo de la consola Python, una función para abrir el
  código fuente de un objeto.
• Un script personalizado de inicio para la consola Python
• Una orden para registrar la pila de llamadas de la función speech.speak.

Diálogo reiniciar mejorado

La orden NVDA+shift+q abre un diálogo para indicar algunas opciones extra
antes de reiniciar NVDA. Las opciones que pueden especificarse corresponden
a las opciones de línea de órdenes que se pueden usar con nvda.exe,
como -c para la ruta de configuración, --disable-addons para
deshabilitar los complementos, etc.

Reproducir un sonido para los errores registrados

La opción «Reproducir un sonido para los errores registrados» se
introdujo en NVDA 2021.3 y permite especificar si NVDA reproducirá un sonido
de error en caso de que se registre un error.

Este complemento proporciona una orden adicional (NVDA+control+alt+e) para
conmutar este ajuste. Puedes elegir:

• «Sólo en versiones de prueba de NVDA» (por defecto) para que NVDA
  reproduzca sonidos de error sólo si la versión actual de NVDA es una
  versión de prueba (alfa, beta o ejecutada desde el código fuente).
• «Sí» para habilitar los sonidos de error sea cual sea tu versión de NVDA.

En versiones de NVDA anteriores a la 2021.3, este complemento proporciona el
backport de esta característica y la posibilidad de controlarla con la orden
de teclado. La casilla de verificación del panel de opciones avanzadas, sin
embargo, no se incluye.

Explorador de propiedades de los objetos

Esta función permite anunciar algunas propiedades del objeto actual en el
navegador de objetos sin abrir el visualizador del registro.

Para enumerar las propiedades de un objeto, mueve el navegador de objetos
hacia él y usa las siguientes órdenes:

• Selecciona la propiedad anterior y la anuncia para el navegador de
  objetos.
• Selecciona la siguiente propiedad y la anuncia para el navegador de
  objetos.
• Anuncia la propiedad seleccionada actualmente para el navegador de
  objetos; al pulsar dos veces rápidamente, muestra esta información en un
  mensaje explorable.

Estas tres órdenes vienen sin asignar por defecto; tendrás que asignarlas
desde el diálogo Gestos de entrada para poder usarlas.

La lista de propiedades soportadas es la siguiente: nombre, rol, estado,
valor, nombre de clase de la ventana, id de control de la ventana, manejador
de la ventana, ubicación, clase Python, orden de resolución de métodos de la
clase Python.

Esta función es una mejora de un ejemplo de la guía de desarrollo de
NVDA.

Modo de descripción extendida de scripts

Cuando el modo de descripción extendida de scripts está activado, el modo de
ayuda de entrada (NVDA+1) se modifica de la siguiente manera. Si un script
no tiene descripción, se anuncian su nombre y su clase. Si un script tiene
descripción, esta se anuncia como siempre. El gesto para activar o
desactivar esta función es NVDA+control+alt+d.

Ejecutar un gesto asociado a un script sin descripción en el modo ayuda de
entrada también crea una entrada para este script en el diálogo de
administración de gestos. Esta entrada se ubica en una categoría dedicada
llamada «Scripts sin descripción (¡Modifica bajo tu responsabilidad!)». Esto
permite añadir, eliminar o cambiar fácilmente los gestos nativos de NVDA
para estos scripts. Ten en cuenta, sin embargo, que el script puede no tener
una descripción intencionadamente para que el usuario no pueda
modificarlo. El script puede estar pensado para coincidir con un atajo de
una aplicación concreta. Por ejemplo, el script script_toggleItalic en
NVDAObjects.window.winword.WordDocument está asignado a control+k, y no
debería modificarse, ya que el gesto se pasa a la aplicación para ejecutar
realmente ese atajo de teclado.

Ejemplo de uso

Control+shift+k también conmuta la cursiva en Word, incluso si NVDA no lo
anuncia de forma nativa. Para que el resultado de pulsar control+shift+k se
anuncie como control+k, deberías seguir los siguientes pasos:

• Abre un documento de Word.
• Activa el modo de descripción extendida de scripts con NVDA+control+alt+d.
• Entra en el modo ayuda de entrada con NVDA+1.
• Pulsa control+K para anunciar el script de cursiva y añadirlo al diálogo
  de gestos.
• Sal del modo ayuda de entrada con NVDA+1.
• Abre el diálogo Gestos de entrada.
• En la categoría «Scripts sin descripción (¡Modifícalos bajo tu
  responsabilidad!)», selecciona la orden «toggleItalic en
  NVDAObjects.window.winword.WordDocument».
• Añade el atajo control+shift+k y valida.
• Si quieres, sal del modo de descripción extendida de scripts con
  NVDA+control+alt+d.

Fallo conocido: Un script añadido para una clase concreta es visible incluso
si el administrador de gestos se abre en otro contexto.

Órdenes de lectura y análisis del registro

El modo lector del registro proporciona órdenes facilitar la lectura y el
análisis del registro. En la ventana del visualizador del registro, el
lector del registro está habilitado por defecto, por lo que los comandos de
lectura del registro están disponibles de inmediato. En otras áreas de
lectura de texto, tales como un editor (por ejemplo, Notepad++) o una página
web (por ejemplo, una incidencia de GitHub), es necesario pulsar
NVDA+control+alt+l para activar el modo de lectura del registro y usar sus
órdenes. Cuando acabes con las tareas de análisis y lectura del registro,
puedes desactivar de nuevo el modo lector del registro con
NVDA+control+alt+l.

Las órdenes disponibles en el modo de lectura del registro se describen a
continuación.

Órdenes de navegación rápida

Existen órdenes de navegación de una sola letra, similares a las usadas en
modo exploración, que permiten moverse por distintos tipos de mensajes en el
registro:

• m: cualquier mensaje
• e: ERROR
• i: IO
• d: DEBUG
• f: INFO
• g: DEBUGWARNING
• w: WARNING

Pulsando la letra te moverás a la siguiente coincidencia de ese mensaje. Al
combinar la letra con la tecla shift, te desplazarás a la coincidencia
anterior.

Abrir un archivo en tu editor

En el registro, alguna línea puede hacer referencia al código fuente:

• Una línea relacionada con una traza contiene la ruta y la línea en el
  archivo, por ejemplo:
  File "virtualBuffers\__init__.pyc", line 226, in _getStoryLength
• La línea de cabecera de un mensaje registrado contiene la función que ha registrado el mensaje, p.ej.:
  INFO - config.ConfigManager._loadConfig (22:45:26.145) - MainThread (16580):

Puedes querer que se abra el archivo que contiene el código para comprender
el contexto de la traza o el mensaje registrado. Pulsa la C para abrir el
archivo.

Para que esta característica funcione, necesitas configurar el comando de tu
editor favorito. Si no estás ejecutando NVDA desde el código fuente, la
ubicación del código también debería estar configurada. Para más información
sobre la configuración, consulta el párrafo de configuración de la caja de
herramientas de desarrollo y pruebas de NVDA.

Extensión de la consola Python

Función openCodeFile

En la consola, puedes llamar a la siguiente función para ver el código fuente que define la variable myVar:
openCodeFile(myVar)

Para que esta característica funcione, necesitas configurar el comando de tu
editor favorito. Si no estás ejecutando NVDA desde el código fuente, la
ubicación del código también debería estar configurada. Para más información
sobre la configuración, consulta el párrafo de configuración de la caja de
herramientas de desarrollo y pruebas de NVDA.

Se puede llamar a la función openCodeFile en objetos definidos en el
código de NVDA o en objetos definidos por los complementos. No se puede
llamar en objetos cuyo código fuente no está disponible, tales como los
incorporados en Python.

Si todavía no has importado el objeto en la consola, también puedes pasar su
nombre como parámetro a la función openCodeFile.

A continuación hay ejemplos de llamadas al código de NVDA:

• Ver la definición de la función speech.speech.speak:
  openCodeFile(speech.speech.speak)
  o con el nombre pasado como parámetro:
  openCodeFile("speech.speech.speak")
• Ver la definición de la clase TextInfo:
  openCodeFile(textInfos.TextInfo)
• Ver la definición del método copyToClipboard de la clase TextInfo:
  openCodeFile(textInfos.TextInfo.copyToClipboard)
• Ver la definición de clase del objeto con el foco:
  openCodeFile(focus)
• Abrir el archivo api.py que define el módulo api:
  openCodeFile(api)

Script de inicio de la consola Python

Puedes definir un script personalizado, que se ejecutará en el espacio de
nombres de la consola Python al abrirla por primera vez, o si se recarga el
complemento (NVDA+control+f3) después de haber abierto ya la consola.

Por ejemplo, el script te permite ejecutar importaciones y definir alias que podrás usar directamente en la consola, como se muestra a continuación:

# Various import that I want in the console.
import globalVars as gv
import core
import ui
# Aliases
ocf = openCodeFile

El script de la consola Python debería encontrarse en la siguiente ubicación: RutaConfiguraciónNVDA\ndtt\consoleStartup.py
Por ejemplo:
C:\Users\myUserName\AppData\Roaming\nvda\ndtt\consoleStartup.py

Registrar la pila de llamadas de la función de voz

A veces, puedes querer saber qué parte del código es responsable de
verbalizar algo. Para ello, puedes habilitar el registro de traza de pila de
la función de voz pulsando NVDA+control+alt+s. Cada vez que NVDA hable, se
grabará una traza de pila en el registro.

Nota: puedes modificar directamente el archivo del script para parchear otra
función. Consulta las instrucciones en el propio archivo para más detalles.

Configuración de herramientas de depuración y pruebas de NVDA

Las órdenes del lector del registro y la extensión de la consola Python
pueden requerir una configuración específica. Para usar funciones que
permiten visualizar el código fuente en tu editor, primero deberías
configurar la línea de órdenes de tu editor. Si es necesario visualizar un
archivo de NVDA y no lo ejecutas desde el código fuente, también tienes que
configurar la ruta al código fuente de NVDA.

Configuración de la línea de órdenes del editor

Para usar la orden Abrir código fuente o la orden de consola
openCodeFile, primero debes configurar el comando al que se llamará para
abrir el archivo en tu editor favorito. Para ello, abre la consola de NVDA
(NVDA+control+Z), teclea la siguiente línea y pulsa intro:
config.conf['ndtt']['sourceFileOpener'] =
r'"C:\path\to\my\editor\editor.exe" "{path}":{line}' Por supuesto, deberías
modificar esta línea en función de la ubicación y el nombre real de tu
editor, y su sintaxis para abrir archivos. {path} será sustituida por la
ruta completa del archivo que se abrirá, y {line} por el número de línea
donde se situará el cursor. Por ejemplo, para configurar Notepad++ habría
que escribir el siguiente comando: config.conf['ndtt']['sourceFileOpener']
= r'"C:\Program Files\Notepad++\notepad++.exe" "{path}" -n{line}'

Configuración de la ruta al código fuente de NVDA

Cuando un archivo relacionado con el núcleo de NVDA aparece en una traza, la
línea tiene este formato: File "config\profileUpgrader.pyc", line 30, in
upgrade

Si no ejecutas NVDA desde el código fuente, puedes indicar una ubicación
alternativa donde buscar el archivo de código fuente, como por ejemplo el
lugar donde has clonado el repositorio de NVDA. En este caso, debes
configurar la ruta donde tengas situados los archivos con el código fuente
de NVDA.

Para ello, abre la consola de NVDA (NVDA+control+Z), teclea la siguiente
línea y pulsa intro: config.conf['ndtt']['nvdaSourcePath'] =
r'C:\RutaEjemplo\GIT\nvda\source' Por supuesto, sustituye la ruta al código
fuente de NVDA con la correcta.

Asegúrate, no obstante, de que la versión de tu archivo fuente (por ejemplo,
commit de Git) es la misma que la de la instancia de NVDA en ejecución.

Registro de cambios

Versión 3.0

• En un registro, ahora se puede pulsar la C en una línea de cabecera de
  mensaje para abrir el módulo o función que lo emitió.
• En la consola, la función openCodeFile puede recibir como parámetro el
  objeto o una cadena que contenga su nombre.
• Nueva función: archivo de inicio de la consola de NVDA: si existe, el
  archivo tuCarpetaDeConfiguraciónDeNVDA\ndtt\consoleStartup.py se ejecutará
  al abrir la consola Python por primera vez o cuando se recarguen los
  complementos.
• Diversas correcciones menores para la función de la consola Python
  openCodeFile y la orden para abrir el archivo de código fuente
  correspondiente a una línea del registro.
• Corregido un problema al intentar anunciar roles y estados en el
  explorador de objetos en versiones antiguas de NVDA.
• El complemento ya no causa problemas con el interceptor de árbol al usar
  UIA en Edge.

Versión 2.1

• Diversas correcciones de fallos y refactorización y limpieza del código
  para tener en cuenta todos los casos de uso: todas las versiones
  soportadas, instalado vs. ejecutado desde el código fuente,
  etc. (colaboración de Łukasz Golonka)
• Reescritura del módulo compa (colaboración de Łukasz Golonka)
• Ahora, el diálogo para reiniciar se puede abrir sólo una vez.
• Los atajos del explorador de objetos ahora vienen por defecto sin asignar
  y deben ser asignados por el usuario.
• En el explorador de objetos, una pulsación doble para llamar al script que
  indica la propiedad del objeto ahora muestra la información indicada en un
  mensaje explorable.

Versión 2.0

• Nueva función: diálogo de reiniciar mejorado para indicar algunas opciones
  extra al reiniciar NVDA.
• Nueva función: modo de descripción extendida.
• Función para reproducir sonidos de error armonizada entre las versiones
  anterior y posterior a la 2021.3 de NVDA.
• Nueva función: las órdenes del lector del registro ahora están disponibles
  en el visualizador del registro y, opcionalmente, en cualquier cuadro de
  edición y en páginas web.
• Nueva función: en la consola Python, está disponible una función
  openCodeFile para ver el código fuente de un objeto.
• Algunas funciones están ahora deshabilitadas en modo seguro por motivos de
  seguridad.
• Se ha extendido el rango de compatibilidad del complemento (de 2019.2 a
  2021.1).
• Las liberaciones ahora se llevan a cabo con una acción de GitHub en lugar
  de AppVeyor.

Versión 1.0

• Versión inicial.

https://www.nvaccess.org/files/nvda/documentation/userGuide.html#CommandLineOptions

https://www.nvaccess.org/files/nvda/documentation/userGuide.html#PlayErrorSound

https://www.nvaccess.org/files/nvda/documentation/developerGuide.html#toc22