Thursday, April 28, 2016

A Beginner's Guide to Creating Custom Dragon Commands for SDL Trados Studio

Let me start by saying that the beginner in the title is me. For the past couple of weeks, I've been learning and experimenting to increase Dragon's usability in Studio, a non-supported application. This will be a summary of what I've learned and a how-to for other users who may want to get started with some basic scripts. If you have no programming experience and feel this is too complicated, believe me when I say that if I've been able to do it, so can you, as my previous experience was limited to creating the odd Word macro, so I basically started from scratch.

I will also be adding some ready-to-use Dragon command scripts for Studio to this post so you can borrow them if you'd like and get up and running in a short time, rather than having to redo many of the things that I and others have done before.

Required Software
What will you need for these commands to work? Custom Dragon commands can only be created or added in the professional version of the software, so at the very least you will need one of the following:

1. Dragon NaturallySpeaking Professional (version 13 and higher if you want to use open-ended commands).

or

2. Dragon NaturallySpeaking Premium (again, version 13 or higher) + KnowBrainer 2016. KnowBrainer is a Dragon add-on that adds command capabilities to any version of Dragon,

or

3. Dragon Professional Individual 14 (this is the latest version of the software, where Premium has been replaced with Professional Individual).

To prepare these commands I have used Dragon Professional Individual 14 + KnowBrainer 2016. It may seem like overkill, as both offer command creation functionality, but KnowBrainer is a much easier to use repository of the Dragon commands, increasing ease-of-use and flexibility. A 30-day trial can be found here.

Creating Custom Commands
Dragon offers four different ways of creating commands. For this post, I will be focusing on the Advanced Scripting option, which is also the only option available in KnowBrainer.

To create a new command, we go to Tools - Add New Command in Dragon or to Add Command (or say "New Command") in KnowBrainer. To clarify: all of these commands can be entered either in Dragon or in KnowBrainer, there's no need to add them to both.

Here are the Dragon and KnowBrainer Command Editor windows, side-by-side.


Dragon scripts are written in Visual Basic, so there are a few things that we need to know to write even the simplest of scripts. An important piece of information is how to enter the names of keys into a script. For example, what to enter if you want Dragon to execute Ctrl+C to copy selected text, or Ctrl+Alt+Right Arrow to select several words to the right of your cursor, or Shift+F3 to change case.

This is done through SendKeys statements, and that's the first thing I had to learn to get started, so that's where we will start.

There is a handy reference of all the keys and modifier keys you will need here:
https://msdn.microsoft.com/en-us/library/aa266279(v=vs.60).aspx
Microsoft's Visual Basic for Applications Reference

Looking at this, we can see that Ctrl+C would be ^C and Ctrl+Alt+Right Arrow would be ^%{RIGHT}, and Shift+F3 would be +{F3}. That's the first step to start converting our Studio shortcuts into scripts. Whatever shortcut we want to emulate would be placed inside a SendKeys statement, like this:

The example above is the command for my Confirm Segment shortcut in Studio, which, as you can see, is Alt+Q. The command can be customized to any shortcut (the key presses used in the script must match the Studio shortcut), and it can be named anything you want. To learn about finding and customizing Studio's shortcuts, Emma Goldsmith has a couple of excellent articles here.

The word(s) in the Command Name field represent what you will say to deploy the command. It's possible to copy the command and give the new copy a different name, so you can deploy the command with any of its alternate names. For example, I have 3 identical Alt+Q commands, called "Confirm", "Continue" and "AltQ". Note that all the user-entered code should be placed between the "Sub Main" and "End Sub" lines.

Notes about the SendKeys statement:
  • This statement sends keystrokes as if they were typed on the keyboard.
  • The syntax is SendKeys "string", where string are the keystrokes to be sent
  • Don't forget to enclose the string in quotation marks. 
  • A keystroke command can be repeated multiple times by adding a number after the key name, for example, {Right 5} would result in the right arrow key being pressed five times.
  • To pause a macro/command until the keys are sent, a comma and a 1 can be added after the end of the SendKeys command, for example SendKeys "^v", 1 means that the macro should wait until the paste operation is completed to proceed.
KnowBrainer offers a very useful feature called VerbalBasic Commands, which means that you can add lines of code by dictating them. Here is the list of some of the SendKeys coding commands:



Sample commands for you to try

As I said earlier, for the commands to work, the shortcut must match what you have in Studio, so if a command doesn't work for you, check your Studio shortcuts and make the appropriate adaptations.

To copy the commands, simply copy and paste the command code making sure your command begins with Sub Main and ends with End Sub. Remember that Sub Main and End Sub are already present when you open a new command window, so make sure not to duplicate them when pasting.

Change the names to whatever you prefer and try out the commands. I have included English and Spanish versions of each command where appropriate, and you will notice that I have not used any accents in the command names in Spanish. That's so that the commands can be added either to Dragon or KnowBrainer, as KnowBrainer doesn't accept accented characters as part of the command name. For other languages, simply change to command name to your own language. If the command contains only shortcuts, it will work in any language. If it's an open-ended command, see the appropriate note below.

If a command name isn't working for you, here's a tip I got from an experienced user: change the name of the command to a single word, for example, change Add tags to segment to Addtagstosegment. That usually does the trick.

Command type: Shortcuts and key presses
Description
English
Spanish
1
Applies tags around selected text

Note: Acronym recognition must be disabled in the TM for this to work properly (otherwise acronyms will be inserted as tags)

The Studio shortcut used here is Ctrl+Alt+Down; replace as needed
Command name: Apply tags

Sub Main
SendKeys "^%{Down}"
SendKeys "{Enter}"
End Sub
Command name: Agregar tags

Sub Main
SendKeys "^%{Down}"
SendKeys "{Enter}"
End Sub
2
Selects the entire segment, adds tags, confirms the segment and goes to the next segment. To be used when there’s only one pair of tags in the segment.

Note: Acronym recognition must be disabled in the TM for this to work properly (otherwise acronyms will be inserted as tags)

The Studio shortcut used here is Ctrl+Alt+Down; replace as needed
Command name: Add tags to segment
  
Sub Main
SendKeys "^a"
Wait .2
SendKeys "^%{Down}"
SendKeys "{Enter}"
Wait .2
SendKeys "^%{Enter}"
End Sub
Command name: Agregar tags a segmento
  
Sub Main
SendKeys "^a"
Wait .2
SendKeys "^%{Down}"
SendKeys "{Enter}"
Wait .2
SendKeys "^%{Enter}"
End Sub
3
Selects the entire segment, copies it to the clipboard, copies source to target (my Studio shortcut is Alt+W), deletes all the text between the tags, pastes the previously cut text between the tags. To be used when there’s multiple tags but all the text is between one pair of tags.

Video demonstration here

Note: Acronym recognition must be disabled in the TM for this to work properly (otherwise acronyms will be inserted as tags)

The Studio shortcut used here is Ctrl+Alt+Down; replace as needed
Command name: Paste with tags

Sub Main
SendKeys "^A"
Wait .1
SendKeys "^X"
Wait .1
SendKeys "%W"
Wait .1
SendKeys "{Right}"
SendKeys "^+D"
Wait .1
SendKeys "^V"
End Sub
Command name: Pegar con tags

Sub Main
SendKeys "^A"
Wait .1
SendKeys "^X"
Wait .1
SendKeys "%W"
Wait .1
SendKeys "{Right}"
SendKeys "^+D"
Wait .1
SendKeys "^V"
End Sub
4
Resets previously used filters
Command name: Reset filters

Sub Main
SendKeys "^%{F6}"
End Sub
Command name: Restablecer filtros

Sub Main
SendKeys "^%{F6}"
End Sub
5
Places the cursor in the Filter text box
Command name: Filter by

Sub Main
SendKeys "^{F6}"
End Sub
Command name: Filtrar por

Sub Main
SendKeys "^{F6}"
End Sub
6
Adds files to the active project
Command name: Add files

Sub Main
SendKeys "%{F12}"
End Sub
Command name: Agregar archivos

Sub Main
SendKeys "%{F12}"
End Sub
7
In the Files view, opens the folder containing the project files
Command name: Explore folder

Sub Main
SendKeys "%+{Enter}"
End Sub
Command name: Explorar carpeta

Sub Main
SendKeys "%+{Enter}"
End Sub
8
Creates a new translation memory
Command name: New memory

Sub Main
SendKeys "%+N"
End Sub
Command name: Nueva memoria

Sub Main
SendKeys "%+N"
End Sub
9
Removes all the TMs from the project
Command name: Remove all TMs

Sub Main
SendKeys "^%+M"
End Sub
Command name: Quitar todas las memorias

Sub Main
SendKeys "^%+M"
End Sub
10
Activates the Files view
Command name: Files view

Sub Main
SendKeys "%+F"
End Sub
Command name: Vista archivos

Sub Main
SendKeys "%+F"
End Sub
11
Toggles track changes
Command name: Enable track changes

Sub Main
SendKeys "^%{F10}"
SendKeys "{Esc}"
End Sub
Command name: Activar track changes

Sub Main
SendKeys "^%{F10}"
SendKeys "{Esc}"
End Sub
12
Toggles track changes
Command name: Disable track changes

Sub Main
SendKeys "^%{F10}"
SendKeys "{Esc}"
End Sub
Command name: Desactivar track changes

Sub Main
SendKeys "^%{F10}"
SendKeys "{Esc}"
End Sub
13
Selects text from the cursor to the end of the segment
Command name: Select to end of segment
  
Sub Main
SendKeys "^+{PgDn}"
End Sub
Command name: Seleccionar hasta fin de segmento
  
Sub Main
SendKeys "^+{PgDn}"
End Sub
14
Selects text from the cursor to the beginning of the segment
Command name: Select to beginning of segment
  
Sub Main
SendKeys "^+{PgUp}"
End Sub
Command name: Seleccionar hasta inicio de segmento
  
Sub Main
SendKeys "^+{PgUp}"
End Sub
15
Presses the Escape key
Command name: Escape
  
Sub Main
SendKeys "{Esc}"
End Sub
Command name: Escape
  
Sub Main
SendKeys "{Esc}"
End Sub
16
Changes the selected text’s case (note this cycles through lowercase, title case and uppercase)
Command name: Uppercase
  
Sub Main
Sendkeys "+{F3}"
End Sub
Command name: Mayusculas
  
Sub Main
Sendkeys "+{F3}"
End Sub
17
Changes the selected text’s case (note this cycles through lowercase, title case and uppercase)
Command name: Title case
  
Sub Main
Sendkeys "+{F3}"
End Sub
Command name: Mayusculas titulo
  
Sub Main
Sendkeys "+{F3}"
End Sub
18
Changes the selected text’s case (note this cycles through lowercase, title case and uppercase)
Command name: Lowercase
  
Sub Main
Sendkeys "+{F3}"
End Sub
Command name: Minusculas
  
Sub Main
Sendkeys "+{F3}"
End Sub
19
Displays recognized terms from the active termbases

Video demonstration here
Command name: Display terms
  
Sub Main
SendKeys "^+L"
End Sub
Command name: Mostrar terminos
  
Sub Main
SendKeys "^+L"
End Sub
20
Presses the right arrow key once
Command name: Right arrow
  
Sub Main
Sendkeys "{Right}"
End Sub
Command name: Flecha derecha
  
Sub Main
Sendkeys "{Right}"
End Sub
21
Presses the right arrow key three times
Command name: Right arrow 3
  
Sub Main
Sendkeys "{Right 3}"
End Sub
Command name: Flecha derecha 3
  
Sub Main
Sendkeys "{Right 3}"
End Sub
22
Deletes all the text between the cursor position and the next tag
Command name: Delete until tag
  
Sub Main
SendKeys "^+D"
End Sub
Command name: Borrar hasta tag
  
Sub Main
SendKeys "^+D"
End Sub
23
Selects the entire active segment
Command name: Select segment
  
Sub Main
SendKeys "^a"
End Sub
Command name: Seleccionar segmento
  
Sub Main
SendKeys "^a"
End Sub
24
Removes all the tags from the segment
Command name: Remove tags
  
Sub Main
SendKeys "^%{Space}"
End Sub
Command name: Borrar tags
  
Sub Main
SendKeys "^%{Space}"
End Sub
25
Inserts opening and closing question marks and places the cursor between them

Command name: Pregunta
  
Sub Main
SendKeys "¿?{Left}"
End Sub
26
Clears the target segment
Command name: Clear segment
  
Sub Main
Sendkeys "%{Del}"
End Sub
Command name: Borrar segmento
  
Sub Main
Sendkeys "%{Del}"
End Sub
27
Adds html underlining tags around the selected text
Command name: U around
  
Sub Main
SendKeys "^c"
SendKeys "<u>"
SendKeys "^v"
SendKeys "</u>"
Wait .3
SendKeys "{Right}"
End Sub
Command name: Rodearu
  
Sub Main
SendKeys "^c"
SendKeys "<u>"
SendKeys "^v"
SendKeys "</u>"
Wait .3
SendKeys "{Right}"
End Sub
28
Displays tags without text
Command name: No tag text
  
Sub Main
Sendkeys "%VN"
End Sub
Command name: Tags no texto
  
Sub Main
Sendkeys "%VN"
End Sub
29
Displays tag ID numbers
Command name: Tag ID
  
Sub Main
Sendkeys "%VT4"
End Sub
Command name: Tags con numeros
  
Sub Main
Sendkeys "%VT4"
End Sub
30
Opens the Options dialog
Command name: Options
  
Sub Main
Sendkeys "{F2}"
End Sub
Command name: Opciones
  
Sub Main
Sendkeys "{F2}"
End Sub
31
Copies source to target and confirms the segment

(Custom Studio shortcuts: Alt+W copy source to target; Alt+Q confirm segment)
Command name: Copy and confirm
  
Sub Main
Sendkeys "%W"
Wait .1
Sendkeys "%Q"
End Sub
Command name: Copiar y confirmar
  
Sub Main
Sendkeys "%W"
Wait .1
Sendkeys "%Q"
End Sub
32
Removes the period (or any other character) at the end of a segment
Command name: Segmento no period
  
Sub Main
SendKeys "^{PgDn}"
SendKeys "{Backspace}"
End Sub
Command name: Segmento sin punto
  
Sub Main
SendKeys "^{PgDn}"
SendKeys "{Backspace}"
End Sub
33
Adds a period at the end of a segment
Command name: Segment period
  
Sub Main
SendKeys "^{PgDn}"
SendKeys "."
End Sub
Command name: Segmento con punto
  
Sub Main
SendKeys "^{PgDn}"
SendKeys "."
End Sub

Command type: Open-ended

This is a very powerful Dragon feature that allows you to add your own text to a command.

When naming an open-ended command, the <dictation> part of the name cannot be typed or pasted, it must be selected from a list. This is because open-ended commands are a type of List Commands, which I will discuss at a later time.

Do the following when creating an open-ended command:

In Dragon


In KnowBrainer

There should be no spaces between the command name and the <dictation> part of the name.

Special note about open-ended commands in languages with special non-English characters: To avoid issues with accented characters being dropped, for example, “construcción” being written out as “construccin”, all Spanish open-ended commands (those including <dictation> in the name) must be entered directly in Dragon, not in KnowBrainer, and must use SendDragonKeys ListVar1 instead of SendKeys ListVar1. See the examples below.
34
Selects the text dictated as part of the command. For example, say “Select supervisor”, to select the word “supervisor”.
Command name: Select <dictation>
  
Sub Main
SendKeys "^{PgUp}"
SendKeys "^f"
SendKeys ListVar1
Wait .1
SendKeys "{Enter}"
Wait .1
SendKeys "{Esc}"
End Sub
Command name: Seleccionar <dictation>
  
Sub Main
SendKeys "^{PgUp}"
SendKeys "^f"
SendDragonKeys ListVar1
Wait .1
SendKeys "{Enter}"
Wait .1
SendKeys "{Esc}"
End Sub
35
Performs a search in the active document, starting at the top
Command name: Find <dictation>

Sub Main
SendKeys "^{Home}"
Wait .5
SendKeys "^f"
Wait .1
SendKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait .2
SendKeys "{Esc}"
End Sub
Command name: Buscar <dictation>

Sub Main
SendKeys "^{Home}"
Wait .5
SendKeys "^f"
Wait .1
SendDragonKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait .2
SendKeys "{Esc}"
End Sub
36
Places the cursor before the dictated word
Command name: Insert before <dictation>

Sub Main
SendKeys "^{PgUp}"
SendKeys "^f"
SendKeys ListVar1
Wait .1
SendKeys "{Enter}"
Wait .1
SendKeys "{Esc}"
Wait .1
SendKeys "{Left}"
End Sub
Command name: Insert before <dictation>

Sub Main
SendKeys "^{PgUp}"
SendKeys "^f"
SendDragonKeys ListVar1
Wait .1
SendKeys "{Enter}"
Wait .1
SendKeys "{Esc}"
Wait .1
SendKeys "{Left}"
End Sub
37
Places the cursor after the dictated word
Command name: Insert after <dictation>

Sub Main
SendKeys "^{PgUp}"
SendKeys "^f"
SendKeys ListVar1
Wait .1
SendKeys "{Enter}"
Wait .1
SendKeys "{Esc}"
Wait .1
SendKeys "{Right}"
SendKeys "{Space}"
End Sub
Command name: Insert after <dictation>

Sub Main
SendKeys "^{PgUp}"
SendKeys "^f"
SendDragonKeys ListVar1
Wait .1
SendKeys "{Enter}"
Wait .1
SendKeys "{Esc}"
Wait .1
SendKeys "{Right}"
SendKeys "{Space}"
End Sub
38
Deletes the text dictated as part of the command
Command name: Delete <dictation>
  
Sub Main
SendKeys "^{Home}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "{Del}"
Command name: Borrar <dictation>
  
Sub Main
SendKeys "^{Home}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendDragonKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "{Del}"
39
Copies the text dictated as part of the command to the clipboard
Command name: Copy <dictation>
  
Sub Main
SendKeys "^{PgUp}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "^c"
End Sub
Command name: Copiar <dictation>
  
Sub Main
SendKeys "^{PgUp}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendDragonKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "^c"
End Sub
40
Pastes the contents of the clipboard before the text dictated as part of the command 
Command name: Paste before <dictation>
  
Sub Main
SendKeys "^{PgUp}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "{Left 2}{Space}"
Wait 0.5
SendKeys "^v"
End Sub
Command name: Pegar antes de <dictation>
  
Sub Main
SendKeys "^{PgUp}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendDragonKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "{Left 2}{Space}"
Wait 0.5
SendKeys "^v"
End Sub
41
Pastes the contents of the clipboard after the text dictated as part of the command 
Command name: Paste after <dictation>
  
Sub Main
SendKeys "^{PgUp}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "{Right}{Space}"
Wait 0.5
SendKeys "^v"
End Sub
Command name: Pegar despues de <dictation>
  
Sub Main
SendKeys "^{PgUp}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendDragonKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "{Right}{Space}"
Wait 0.5
SendKeys "^v"
End Sub
42
Cuts the text dictated as part of the command and places it in the clipboard
Command name: Cut <dictation>
  
Sub Main
SendKeys "^{PgUp}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "^x"
End Sub
Command name: Cortar <dictation>
  
Sub Main
SendKeys "^{PgUp}"
Wait 0.5
SendKeys "^f"
Wait 0.1
SendDragonKeys ListVar1
Wait .5
SendKeys "{Enter}"
Wait 0.2
SendKeys "{Esc}"
Wait 0.5
SendKeys "^x"
End Sub

While all these commands are simple to implement, they significantly increase the functionality of Dragon in Studio and allow us not only to achieve text control, but application control as well.

In a future post, I will write about List Commands, a powerful way of consolidating commands with several variables into one.


Publicado por a las
Etiquetas: , , , , , , ,

7 comments:

  1. AnonymousApril 29, 2016 at 1:12 AM

    Great article Nora. This is the first time I have seen anyone writing with this kind of detail on how to use Dragon with any translation software. It's much needed, and an excellent resource I will be using a lot!

    ReplyDelete
  2. Nora DíazApril 29, 2016 at 7:12 AM

    Thank you Paul! I hope this will encourage fellow Studio users to try Dragon's capabilities. I know we've talked about the lack of full text control before, but it should become less of an issue with custom commands.

    ReplyDelete
  3. UnknownJanuary 26, 2018 at 11:15 AM

    thank you for creating this blog post. This is the first time that I have seen anyone writing about knowbrainer. I use it a lot and due to lack of information, ultimately started creating tutorials to share what I had learnt. It is on my blog at www.disabledmessenger.site and my YouTube playlist link at https://goo.gl/YXSYuy. I will link to your website in my later blog posts so that other people can benefit.

    Thank you again.

    ReplyDelete
    Replies
    1. Nora DíazJanuary 26, 2018 at 11:38 AM

      Hi Desi,

      Thank you for sharing! I browsed your blog posts and see that they include several programs in addition to tips to better use Dragon, so that's very helpful. I'll make sure to share this with others who are interested in speech recognition.

      Delete
  4. AnonymousJune 19, 2018 at 6:56 AM

    Hi Nora,
    great article, just getting started with Dragon and have managed to get all of these up and running (and some of my own too, but mostly shortcut keys). Have you given any more though to your article on List commands? Thanks, Jim.

    ReplyDelete
  5. mathildeJune 11, 2020 at 8:33 AM

    Hi Nora, this is new for me, but I managed to insert a personal command for "confirm segment" in Studio with Dragon! (proud me!)
    Now, I would like to be able to select and correct text inside a segment without going to the dictate box. I tried something but I have an error message about a wrong macro that I should get right. I don't know how to correct it or check what is wrong with this command. It looks very different from your "select " command... so hmm do you think you can help me with this? Thanks a lot!

    ReplyDelete
  6. Dragon Naturally SpeakingJune 26, 2020 at 12:18 AM

    This comment has been removed by a blog administrator.

    ReplyDelete

Subscribe to: Post Comments (Atom)