dragonfly_example_rule.py

# These lines that start with the # are called comments. They don't affect the way the code runs.
# In this tutorial file, I put comments above the relevant lines.

# Before we begin, it's worth noting that the name of this file, dragonfly_example_rule.py, will cause it to never run.
# You will have to rename it to "_dragonfly_example_rule.py".
# Putting an underscore as the first character of a grammar Python file will tell dragonfly
# that you want this file to run all the time. Grammars that run all the time are good way to start.
# The alternative is making grammars for specific programs that only trigger when the programs are active.

# You can skip down to the next comment, for now this is not important...

from dragonfly import (BringApp, Key, Function, Grammar, Playback, 
                       IntegerRef, Dictation, Choice, WaitWindow, MappingRule, Text, Mouse,)

def my_function(n, text):
    print("put some Python logic here: " + str(text))

class MainRule(MappingRule):

    # It is this section that you want to edit if you're new to: mapping, extras, and defaults concepts.
    mapping = {
    # Here I'm just saying two words to trigger some other words
    "hotel info":                  Text("These types of hospitality services are not cheap."),

    # In the next line, there are two things to observe:
    # 1. The use of parentheses and the pipe symbol ( | ) lets me use either "motel" or "lodging" to trigger that command.
    # 2. The playback action, lets me tell the speech recognition engine to simulate me speaking some words.
    '(motel | lodging)':           Playback([(["hotel", "info"], 0.0)]),

    # Here I'm using BringApp -- this is the same as typing what goes in between the parentheses
    # Into the command prompt/terminnal, without the quotes and commas, like:
    # Windows OS: explorer C:\NatLink\NatLink\MacroSystem
    # Could be changed changed for Linux/Mac (which would open Windows Explorer at the specified location). Anything you can do with the command line can be done this way
    "open natlink folder":         BringApp("explorer", r"C:\NatLink\NatLink\MacroSystem"),

    # Here I'm using the Key action to press some keys -- see the documentation here: https://dragonfly2.readthedocs.io/en/latest/actions.html?#module-dragonfly.actions.action_key
    # "a-" Everything before "-" is a keyboard modifier, "a" is for the "alt" Key.
    # "-space" reprresents the SpaceBar Key. 
    # "/10" After "a-space" Slows down the keypresses by 10 ms" with a seriess of keypresses as demonstrated this may be necessary.
    # The comma "," after "a-space/10" separates keypresses in a series.
    # remax is Windows OS Specific to maximize the current window in the forefront
    "remax":                       Key("a-space/10,r/10,a-space/10,x"),

    # Here I'm chaining a bunch of different actions together to do a complex task
    # This is Windows OS speciffic but the path in BringApp could be changed for Linux/Mac
    "(show | open) documentation": BringApp('C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe') + WaitWindow(executable="chrome.exe") + Key('c-t') + WaitWindow(title="New Tab") + Text('https://dragonfly2.readthedocs.io/en/latest') + Key('enter'),

    # If you need to do more complicated tasks, or use external resources, a function might be what you need.
    # Note that here, I'm using extras: "n" and "text"
    # The angle brackets <> meaning I'm using an extra, and the square brackets [] mean that I don't have to speak that word, it's optional.
    # Advice: if you use an optional extra, like I am with "text", you should set a default value  in the defaults section down below.
    # To trigger the following command, you would have to say the word "function" followed by a number between 1 and 1000.
    '[use] function <n> [<text>]': Function(my_function, extra={'n', 'text'}),

     # Sometimes it's easier to have things as a list in a command as a choice that do different things.
     # That's what `<choice>` Is defined in `extras` allows you define that list. If you dictate `i choose custom grid` Then `CustomGrid` will be printed as text.
     # Items in the list are pairs. e.g `{"custom grid": "CustomGrid"}` The first item of a pair is the command "custom grid" and the second "CustomGrid" output text action.   
    "i choose <choice>":           Text("%(choice)s"),
    }

    extras = [
              IntegerRef("n", 1, 1000),
              Dictation("text"),
              Choice("choice",
                    {
                    "alarm": "alarm",
                    "custom grid": "CustomGrid", 
                    "element": "e"
                    }),
                ]
    defaults = {
                "n": 1,
                "text": "",
            }

# this stuff is required too-- where I have the word "sample" below, each grammar file should have external unique
grammar = Grammar('sample')
grammar.add_rule(MainRule())
grammar.load()