Extending FG with macros/scripts

[lunatis]

Since I've noticed that quite a few feature requests could be remedied with a macro/scripting tool, I would like to suggest AutoHotkey (https://www.autohotkey.com) as a companion to FG. It is an open source freeware with powerful features and good documentation, offering the following benefits:

macroscan be compiled to small, stand-alone .exe files that you can distribute to your friends who don't have AutoHotkey installed.
you can use any key as an additional hotkey for executing a macro (besides the 96 hotkeys provided)
you can use abbreviations for long texts (e.g., useful shortcut for character names, just type 'Bor' or 'pl1' for 'Boromir II.')
you can remap any key to another key (e.g., useful for non-english keyboards that have a different layout)
you can record your keyboard and mouse actions instead of programming it step-by-step
much, much more


While I'm sure the developers of FG could (and in some cases will) offer similar features, I hope they will spent their precious time on those goodies that we are really looking forward to and we help ourselves with the little things.

Programming is quite easy. Here's a simple example to start with:



#ifWinActive, ahk_class HORIZON

F1::Send, /die 2d10{ENTER}

#IfWinActive


Explanation:
In order to intercept keyboard and mouse movements in the Fantasy Grounds window only, you use #ifWinActive and check the currently active window for its identity, in our case for a window class called “ahk_class HORIZON”, which is the class name used in FG demo (and probably also in FG lite/full). Without this line, the script would work in other applications as well (which is often a bad idea because it overwrites the original hotkeys).

Mapping keys to effects is rather simple: Specify the hotkey, add “::” and the desired effect. The “Send” command (a comma is used to separate a command from it’s parameters) sends the following characters to the application window, just as you would type them. Special keys like the Enter key are written in uppercase and enclosed in brackets.

The last #IfWinActive ends the list of hotkeys for this application window.

To test this out, do the following: Download and install AutoHotkey, copy & paste the code above in a textfile called some_filename.ahk and double-click to start. You will see a little H in a green box at the bottom right of your screen where you can edit, reload, suspend and terminate the script. Then start FG and press F1.

I will soon provide more examples for you to see how simple, yet effective macro-scripting FG can be.

[lunatis]

Here's another example for an autotext function that expands abbreviations. In this case you will get "Roll for Initiative!" by entering "rfi".



#ifWinActive, ahk_class HORIZON

::rfi::Roll for Initiative{!}{ENTER}

#IfWinActive


Explanation:
Instead of a single hotkey, you can specify a combination of keys (a hotstring) by starting with "::", followed by the abbreviation, another "::" and the text to replace the abbreviation with.

{}^!+# are regarded as special characters which need to be enclosed in braces.

[lunatis]

Now something some of you have long been waiting for: Pasting the Clipboard with the standard shortcut CTRL+v.



#ifWinActive, ahk_class HORIZON

^v::Send, %Clipboard%

#IfWinActive


Explanation:
The ^ character represents the CTRL-key. The content of the clipboard can be accessed with the variable %Clipboard%. Simple as that.

Note: The developers just announced that clipboard pasting will be supported in the next patch. In the meanwhile you can use this workaround.

[lunatis]

Of course, we can also script mouse actions. Here are two examples: "F2" for arranging dice nicely with the press of a button instead of right-click, move left, left-click. And "F3" for turning ambience to camp-fire mode.



CoordMode, Mouse, Relative
#ifWinActive, ahk_class HORIZON

F2::
WinGetPos, xoff, yoff, width, height, ahk_class HORIZON
MouseGetPos, xpos,ypos
MouseClick, right, 10, 400, ,0
MouseClick, left, 10, 400, ,0
MouseMove, xpos,ypos,0
return

F3::
WinGetPos, xoff, yoff, width, height, ahk_class HORIZON
MouseGetPos, xpos,ypos
MouseClick, left, width - 80, 50, ,0
MouseClick, left, 520, 420, ,0
MouseMove, xpos,ypos,0
return

#IfWinActive


Explanation:
Our code now begins with a command to use relative instead of absolute values for mouse positions. As we don't know the current window size for sure, this is preferrable.

First of all, we need to get the current window size as this may have changed from the first time the script was executed. Window offset, width and height are stored in variables.

Then, we store the current mouse position in variables. As the mouse cursor is going to be moved by the script, this will help us remember where we left off.

Now we do a right-click or left-click at certain window positions. The zero at the end specifies the speed for moving the mouse cursor. Default is 2, but we want this to be done in an instant.

Last but not least, we move the mouse cursor back to where it came from.

Note that multi-line hotkeys should end with "return".

[lunatis]

This is more a gimmick than of any functional value, but good to demonstrate how to work with drag and drop.



#ifWinActive, ahk_class HORIZON

F4::
WinGetPos, xoff, yoff, width, height, ahk_class HORIZON
MouseGetPos, xpos,ypos
MouseClickDrag, left, 210, 700, 250, 400, 0
MouseMove, xpos,ypos,0
return

#IfWinActive


Explanation:
Similar to the examples above, but this time we specify x and y position for the left-click (210 and 700) and then x and y position for letting go of the mouse button. 0 is for speed. You will notice that the speed of you pressing "F4" makes a huge difference for the spin of the dice roll.

You might worry how to find out about the exact position values to use. Well, AutoHotkey features a "window spy" that displays the current mouse position, so you can look it up. Careful, though: Some elements are arranged with respect to the right border of the window, so you need to use the width variable minus something to get to the right spot (see the "F3" example above).

[richvalle]

Great idea! With examples too!

The devs have already thought about this and are using LUA https://www.lua.org/home.html

rv

[Dupre]

That is an interesting software. This isn't an alternative technology to our scripting interface, but rather a complementing one that you can use even with the current version of FG.

There's a typo in lunatis' URL, the correct one is https://www.autohotkey.com

[richvalle]

Well shoot. Thats what I get for not looking close enough.

rv

[kalmarjan]

I wonder if there is a way to make a script that would "dump" tokens in a select bag, name each one, and be ready for combat? That would be very cool!

Sandeman

[gurney9999]

wow, very cool... was looking into doing something with a word macro to help users, but this changes things... I've pm'd you lunatis with a question that may help me create something using this tool.

[lunatis]

Here's what you were looking for: Formatting text in editing mode. Just highlight the text with your mouse and click a hotkey. I used F5 to F7 to stay in sequence, but you can also use other hotkeys such as CTRL+u for underline (hotkey for this would be ^u).



F5::
MouseGetPos, xpos,ypos
MouseClick, right, xpos, ypos ; Context Menu
MouseClick, left, xpos-55, ypos+55, ,0 ; Formatting
MouseClick, left, xpos-110, ypos+110, 0 ; Italics
MouseMove, xpos,ypos,0
return

F6::
MouseGetPos, xpos,ypos
MouseClick, right, xpos, ypos ; Context Menu
MouseClick, left, xpos-55, ypos+55, ,0 ; Formatting
MouseClick, left, xpos-55, ypos+130, ,0 ; Bold
MouseMove, xpos,ypos,0
return

F7::
MouseGetPos, xpos,ypos
MouseClick, right, xpos, ypos ; Context Menu
MouseClick, left, xpos-55, ypos+55, ,0 ; Formatting
MouseClick, left, xpos-130, ypos+55, ,0 ; Underline
MouseMove, xpos,ypos,0
return


Explanation:
The difference to the examples above is that you move the mouse cursor relative to where it is right now. I had to do some testing to figure out the pixel distances. When you experiment on something like that, set the speed to 80 or so, so you can watch the mouse cursor move. Once you made sure everything works the way you want it, you can set it back to 0 for optimal speed.

[gurney9999]

I was also looking for the other 'formatting' commands, such as creating chat frames, Headings, lists, and links (did I forget any story page formatting options? I don't have FG here at work).

And to make sure I understand, you can define as many of these hotkeys as you want and place them in the same .ahk file, correct?

[gurney9999]

After working with lunatis on this (he did 99% of the work), F.U.M. has posted the first version of our FG-specific Autohotkey files. This release contains the following:

21 hotkeys that automate mouse-driven actions in FG (story-page commands, drawing commands, etc.)
the ability to use the number pad to navigate through all of FG's right mouse-click menus
8 examples of 'abbreviations' (such as typing rfi and it transforming into roll for initiative in the chat box).
and much much more (well, not much much more but you always see that on lists such as this :) ).Thanks to the way lunatis put these files together, once you understand how the macros work, the shortcuts you can create are virtually limitless (especially when it comes to 'abbreviations').

If you don't want to download the Autohotkey program, this freebie includes an .exe file that will allow you to use the hotkeys provided in this release. Also included are the files created for users to create new hotkeys and remap the hotkeys provided in this initial release. In order to edit these files you will need to download and install the free Autohotkey application.

You can see more info on this download on the Four Ugly Monsters Downloads page (https://www.fouruglymonsters.com/downloads_freebies.htm). (oops, I just saw I forgot to link the Downloads page to the forum page where you can download the freebie. I'll have to fix that tonight).

You can get the download here in our downloads forum. (https://www.fouruglymonsters.com/fumcomm/index.php?f=39)

We also released a tutorial (https://www.fouruglymonsters.com/tutorials_4.htm) explaining how to use the files included in the freebie, how to add additional hotkeys and abbreviations, etc.

We also opened a forum (https://www.fouruglymonsters.com/fumcomm/index.php?f=44)for those that have questions, want to request new macros, or want to submit their own code for us to include in future versions of this freebie.

[Archamus]

Now something some of you have long been waiting for: Pasting the Clipboard with the standard shortcut CTRL+v.



#ifWinActive, ahk_class HORIZON

^v::Send, %Clipboard%

#IfWinActive


Explanation:
The ^ character represents the CTRL-key. The content of the clipboard can be accessed with the variable %Clipboard%. Simple as that.

Note: The developers just announced that clipboard pasting will be supported in the next patch. In the meanwhile you can use this workaround.


This one caused a couple of slightly annoying things to happen for me.

1)If any of the letters you are pasting corresponds to an FG window short cut, like CTRL + S for the story window, then that window will open while you are pasting your text. While I was testing this out all of the windows kept popping up on me.

2)It reads all of the "returns" stored in the clipboard, preventing me from sending my text as one block of information in chat. This is even more of a pain in the rear when the source document's formatting has a return at the end of every single line.

I don't know if this has already been addressed over in the fouruglymonsters forums or not. Hopefully the next patch will be out soon and this won't matter, but in the mean time you may want to try this...



#ifWinActive, ahk_class HORIZON
^v::
ClipSaved := ClipboardAll
StringReplace, clipboard, clipboard, `r`n, %A_Space%, All
KeyWait, Control
Send, %Clipboard%
Clipboard := ClipSaved
ClipSaved =
return
#IfWinActive


Explanation:

"^v::"
Like mentioned in previous posts, this tells autohotkeys to execute this portion of the script when CTRL and V are depressed.

"ClipSaved := ClipboardAll"
This part backs up what's in the clipboard. This script is going to edit the information in the clipboard slightly, so this is the first step in ensuring our modification to the clipboard's contents is transparent for any other program you may need to also paste the info to.

"StringReplace, clipboard, clipboard, `r`n, %A_Space%, All"
This removes all the returns in the clipboard, and replaces them with a space, so that the text can be sent as one block of text in chat.

"KeyWait, Control"
Tells the script to wait until the control key has been released to execute the rest of the script. This keeps all of the FG shortcuts from firing off.

"Send, %Clipboard%"
Sends our altered(return free) clipboard to the cursor position in FG.

"Clipboard := ClipSaved"
This restores the clipboard to its original state. So now if you need to paste the clipboard into Word, it will still have all those returns we had to remove earlier.

"ClipSaved = "
This just empties the variable "ClipSaved" we were using, to keep memory down, I can't imagine anyone will actually copy enough text to paste into FG that this will ever matter, but it's just one more small line, so why not add it?

By the way thank you for posting about autohotkeys, I just bought FG a couple of weeks ago and was really annoyed by a couple of things, like no pasting, until I found this post and was able to fix pretty much everything that really bothered me. From the looks of it, anything left over that I think could be better is going to be fixed in the next patch. I can't wait!