Command of the Week - Macros (Week 16)
This series is called the command of the week, but it could also explain a feature. The explanations will tend to explain the technical parts of the command, and is intended to highlight the basics (and complexities) of the command, and information about how to use it, but won't be a detailed tutorial. It is up to you to use it creatively in your maps.
Week 16 - MacrosMost commands in CC3+ has a text-only equivalent, allowing you to type in the command and any parameters and coordinates directly on the command line instead of using your mouse, toolbars and menus. Not only does this make a lot of tasks a lot faster to accomplish, but it also means that we can create macros containing series of these commands, to automate frequent or difficult tasks.
For this Command of the Week entry, I will highlight the bare basics of Macros and how to use them. For a more in-depth look at macros, I recommend having a look at the relevant chapters in the Tome of Ultimate Mapping, or the Macro issue of The Cartographers Annual vol 3. Also note that the map links we discussed in an earlier installment are also actually single-command macros.
Where to find itMenu: Tools -> Macros
Command Line: Enter the name of any macro to execute it
How to use itMacros are a very large topic, so I won't go into detail on what you can put in a macro here. Instead, I'll construct a very simple macro, and have a look at various ways to use it. More advanced macros are used the exact same way as our simple macro here, and you will find examples of them in the sources mentioned above.
Our example Macro
FSTYLE wavesThis is a very simple macro. What it does is to set a fill style (waves - used for the sake of example since any template will have this, but oviously you can use nicer fills), a line width (0 - ensuring a filled entity and not just an outline), a color (54 - blue) and then using the box command to draw a square starting at (10,10) and ending at (100,100). Depending on your map size, background color and current zoom, this may or may not be easy to see when drawn.
BOX 10,10 100,100
This example is really simple, but shows how a macro is basically just a series of commands.
Adding them to the CC3+ macro fileCC3+ has a single macro file where all macros are stored. Technically, you can load in a different file than the standard one, but this is not recommended, since a lot of the functionality in CC3+ relies on these standard macros being present. Before we start working on this file, I recommend making a backup copy of the file @fcw32.mac, this is the CC3+ macro file.
Before we add macros to this file, be aware that patches and updates may overwrite this file, so always keep a separate copy of your personal macros somewhere else so you can paste them back in after running an update.
There are two ways to edit this file, either from within CC3+ itself, or through the use of an external text editor, like notepad. The file itself is a plain text file.
Now, let us add our macro to this file. Activate the Tools -> Macros -> Edit Macros menu item. This will pop up a box with all the macros in it. You can add your macro anywhere in this file (like the top), just make sure to not add it in the middle of another macro.
When adding a macro to this file, we need a bit of a framework. We need to start with telling CC3+ the name of our macro, and we need to tell CC3+ when the macro ends. So, for our example macro, add this to the file:
MACRO DRAWBOXAfter the ENDM (end Macro) line, leave one blank line before the next macro start. Scroll down in the file and see how the other macros does this if you are uncertain.
BOX 10,10 100,100
Once you click OK, a save as box will appear. CC3+ will offer to save the file under it's existing name, fcw32.mac in the CC3+ data directory. This is fine, so just click Save, and confirm that you want to overwrite the existing file. (If you ever mess up this file, you may need to restore the backup you made)
Now, simply type DRAWBOX and hit enter on the command line in CC3+, and your macro should be run. You can try to change some properties beforehand, like fill style and color to make sure the macro work as intended.
After adding your macro to the macro file, you can also call it from other places in CC3, such as assigning the command to a toolbar button or menu item. The Tome and the helpfiles have more information on editing menu items.
Using it in a script fileA script file is a macro contained in a separate file that must be loaded each time you wish to run the command. This is great for complex commands that you rarely need, but for commands you often use, you should add them to the macro file instead.
To create a script file, simply create a new blank file in a text editor and insert the macro commands (The ones from our example macro above, NOT including the additional MACRO/ENDM commands we used in the CC3+ macro file). Then save this file with a .scr extension. Make sure the file is saved as a plain text file, and if you have file extensions hidden by default in windows, be aware that it will probably add a hidden .txt extension at the end, making it file.scr.txt, which is NOT what you want. Also note that some version of windows treats the .scr extension as a screensaver executable, so you can't simply double click on it to open it.
Note the last line of the script file should be a blank line, but do NOT add additional blank lines. A blank line causes the previous command (but without the parameters) to be repeated, much the same as when you click the left mouse button inside the drawing windows in CC3+ without picking a new command.
Once you have saved your macro as a script file, you can run it from within CC3+ by going to Tools -> Macros -> Script file and simply browse to your desired file. It will be run immediately upon loading it (and if you wish to run it again, you need to load it again)
Adding it to a hotspotThe most common usage of hotspots are to link to maps and files, but a hotspot can contain a complete macro.
Simply go to Tools -> Macros - Make Hotspot; In the dialog that pops up, add the macro command (again, just the commands, NOT the MACRO/END lines from the macro file), click ok, and define the hotspot area. You now have a clickable area in your map which will execute the macro. Note that the hotspot window will be shown using a visual rectangle for now, but it will be gone the next time you start CC3+ and load the map. You can also toggle the visibility from View -> Show/Hide Hyperlinks. (Se the Link with map entry of this series for more on hyperlinks)
Adding it to a drawing toolYou can also create drawing tools that contain macros. For example, the forest drawing tools typically work by letting you draw a polygon, and then use a macro command to call the fil with symbols command on the polygon you just drew. A drawing tool can also execute a macro directly, without you drawing anything manually.
To add your macro to a drawing tool, click the All Drawing Tools button, and hit Advanced. Now, create yourself a new drawing tool with whatever name you choose, and enable the 'Use Macro Command' option for this tool. Click the Command to execute button, and add our macro commands in this edit box. Click OK to close it, save your new tool, and close the window. Whenever we activate this tool, it will draw our square. Obviously, since we have the coordinates hard-coded, it will still draw it in the same position as before. If we made the macro a bit more advanced, we could have it ask the user to click a spot first, and place the rectangle there. This is probably a bit more in line for how we expect our drawing tools to work, but I won't go into these changes here.
Final NotesThere are a lot more to macros than just being a series of CC3+ commands. There are variables and branching logic, ensuring that macros can do complex tasks depending on situation and user choice. All of this is documented in the sources mentioned earlier. This installment only touches the very surface of the topic to get you started.
Also note that only commands that accept all their inputs on the command line can be used in macros. A command that pops up a dialog box cannot be automated using a macro. Do note that there are often text-only versions of many regular commands. For example, the FRX (Fractalize) command pops up a dialog and is thus unsuited for use in a macro, but there also exists a text-only equivalent, FRXM that is macro-friendly. Look for the macro-friendly versions of the commands.