Adding Toolbar Buttons

Ever wanted to add your own buttons to the CC3+ toolbars? Perhaps you have a command you use frequently, or just want quick access to a symbol catalog?

CC3+ doesn’t have a built-in editor to do this, but all it takes is a few simple changes in a text file to make it happen.

In this blog post, I am going to go through the basics for adding a new button to your toolbar. To keep it simple, I’ll just focus on buttons, although there are other things you can do in the menu as well, such as adding pop-up menus when you right click a button, but I’ll just cover the basics for now.

If you like, you can also watch the basics of this article as a video, and then come back to check out additional details in the article later.

Prerequisite Information

Before we get started, it is important to know a few details about the menu files found in CC3+.

First of all, they’re just plain text files that can be edited with any text editor, such as notepad. They’re found in the CC3+ data directory, and they have the file extension .mnu. Since these are technically configuration files for the software, they don’t respond very well to errors in them, so I strongly recommend making a backup copy of the file before editing it. This can be as simple as just selecting the file in Windows Explorer, and then hitting first Control+C (copy) followed by Control+V (paste) and Windows will make a copy of the file for us.

Secondly, CC3+ has one menu file for each mode. When you are in overland mode, it uses one menu file, and when you work in dungeon mode it uses another. Keep this in mind, as changes to the overland menu file will do you no good if you want to see the new button while working in dungeon mode.

Thirdly, CC3+ uses numbered positions for the buttons in the toolbar. To put it at the beginning of a toolbar, it needs a low number, and to put it at the end, it need a higher number. The first digit in the number indicate which toolbar it belongs to (CC3+ has 8 different toolbars), and the next two digits indicate the position on the toolbar. If you see shorter number than 3 digits, it is simply because leading zeroes aren’t included in the file. Also note that there can only be one button on each position.

Fourth, Updates to CC3+ may change the toolbars. Official ProFantasy patches usually just change the existing files rather than replace them, so personal changes shouldn’t be lost, but there may be a time in the future where a replacement is needed, so keep a copy of your changes. Also note that official updates looks for know lines int he files when they update them, so if you change around the official stuff as opposed to just adding some of your own, the update may fail to change the menu files.

The Menu Files

So, let us get started by adding that button. I’ll add two buttons here in this tutorial, one to bring up a symbol catalog, and the other to call the new-ish command COLLARAUTO that automatically fixes the screen around the map.

Step one is to find the menu files we wish to edit. The easiest way to do this is to start CC3+, then type the command OPENDOC on the command line, followed by a space, then an @-symbol, followed by enter [opendoc @]. This should open a Windows Explorer window on the CC3+ data directory. There will be many files in here, but we are interested in the ones with a .mnu extension. (Make sure Windows is configured to show file extensions). There is a good chance Windows doesn’t understand how to open these files, and will ask you which program to use. Picking Notepad is a safe choice. You’ll notice that there are multiple menu files here, this list shows the common ones:

  • CC3+ base menu (Overland Maps): fcw32.mnu
  • Dungeon Designer: dungeon.mnu
  • City Designer; city.mnu
  • Character Artist 3: ca3.mnu
  • Dioramas: dioramas.mnu
  • Perspectives: per.mnu
  • Symbol Set 3: ss3.mnu
  • Symbol Set 4: ss4.mnu
  • Cosmographer (Deckplans): cosmo3.mnu
  • Cosmographer (Overland): cosmo_land.mnu
  • Cosmographer (Starmaps): cosmo_star.mnu

Opening the file in notepad should give you something similar to the image to the right. Here, I’ve opened the overland menu, fcw32.mnu. The first few lines (6 in this example) are the names of the toolbars, while the rest of the lines are the buttons (If you scroll even further down in the file, you’ll find the menu definitions here too, but we’ll not be looking at these in this post).

To add a button, we first need to determine what toolbar and position we want. The 8 toolbars in CC3+ are:

  • 0 & 1: The zoom and basic drawing functions. Normally displayed to the right
  • 2 & 3: The map type specific tools and the edit tools. Normally displayed to the left
  • 4: The file toolbar, contains load/save and the add-on buttons. Normally displayed at the top
  • 5 & 7: Custom toolbars. Normally not shown
  • 6: The symbol toolbar (not to be confused with the symbol catalog window). Normally displayed at the top.

As you probably already know, you can use the Screen Tools button to position toolbars where you want them, as well as to enable the two custom toolbars. If you want to use lots of custom buttons, putting them on one of the custom toolbars is probably the best. Toolbar 7 is commonly used by 3rd party add-ons.

You may also note that the numbered lines (the ones after the toolbar names at the top) are not necessarily in order. They’re usually in order within each toolbar, but the entries for toolbar 3 may appear before those of toolbar 2 for example. This isn’t a problem, as the order doesn’t matter, since buttons are placed using numbered positions. Keeping them in order helps ensuring you don’t accidentally try to put two buttons in the same position however, so it is preferable to keep some order.

An example Entry

Let us look at a simple example, such as the Fractal Path Button. The entry for it looks like this:

#112,CC2FPATH:[Fractal Path]|FPATH;

Let us break this down:

  • #112 : This indicates the toolbar (1 – Right toolbar, basic drawing tools) and position on that toolbar (12). Leading zeroes are not included, so if you see something like just #5, it really means #005, so toolbar 0, position 5.
  • , : The comma is just a separator. Required.
  • CC2FPATH: This is the name of the icon to use for the button. The list of existing images is here. You can instead put a filename to an image, we’ll look at that near the end.
  • : : The colon (:) is another required separator.
  • [Fractal Path] : This is the tooltip that shows up when you hover the mouse over the button. The square brackets are required.
  • | : The vertical line tells CC3+ to cancel the previous command before running this one. You usually want this, since trying to run a command in the middle of another command usually just leads to an error. There are certain commands that are designed to do just that, but for regular commands, just keep the vertical bar.
  • FPATH : This is the command to run when clicking the button. This command behaves the same way as if you had typed it in on the command line.
  • ; : The semicolon indicates the end of the command. If you omit this, the command won’t work.

There are a few more things I’ve omitted here, for example, you can use a command in curly brackets to add a right click action to the button, and you’ll see that many of the buttons in the file have this. I won’t discuss this here, but you can find more information in both the Tome of Ultimate Mapping and this forum topic.

Adding our Buttons

So, let us try to add our own button. For simplicity, I am going to add them to the end of the symbol toolbar instead of going for a custom toolbar. It is no more difficult, but it saves me from configuring CC3+ to show these toolbars, which we discussed earlier. Note that as stated earlier, I am working on the overland menu file (fcw32.mnu) so any buttons I add here will only show up in overland mode in CC3+.

So, for the first button, I wanted to load a symbol catalog. I am going to use the CATALOG command for this. Note that this will always load the same symbol catalog, it isn’t dependent on the style. Doing that requires me to go into symbol catalog filters, which is a bit outside the scope of this article. Here’s the command for loading one of the recent free monthly catalogs (Remember here that the @-symbol refers to the root of the CC3+ data directory)

CATALOG @\Symbols\Maps\Mike Schley\MS Monthly 1.FSC;

I also need to find a spot to put my button, and an image for it. The symbol toolbar is toolbar #6, so I look through the #6xx entries, and see that the last one is #608. I am going to add two free spaces to separate it from the existing ones, so I go for #611. For an icon, I am going to borrow the tree structures button from CD3, CATICON8. My line should then look like this:

#611,CATICON8:[Monthly 1 - Elven Structures]|CATALOG @\Symbols\Maps\Mike Schley\MS Monthly 1.FSC;

This line can be placed anywhere in the file, but I recommend right below the previous line (#608). IMPORTANT: Don’t make blank lines in this file. It may be tempting to pretty up the file by leaving two blank lines for the “missing” buttons (609 & 610), but this file should have exactly one entry per line, make new lines when and if you need them.

For the second button, I wanted to use the COLLARAUTO command. This command automatically creates a new screen around the map. But, it doesn’t delete the existing one, for that we have the COLLARDEL command. Here, I’ll show how a single button click can run both those command sin succession. It is real simple, just separate the commands by semicolon. Also note that the COLLARDEL command need as an argument the sheet to delete entities from, so we must include this as well. Apart from this, it is the same considerations as for the command above, so let us just go for the final line:

#612,CCDPANEL:[Screen]|COLLARDEL SCREEN;COLLARAUTO;

The final text file with both buttons should look like the image to the right (click image for larger size).

Now, save the file, close and reopen CC3+, and make sure you are in overland mode by clicking the map menu button. You should now see both the buttons on the toolbar, and they should work correctly.

Of course, loading the symbol catalog only makes sense if that catalog isn’t already loaded, and replacing the screen may not be particularly visible if the old screen was fine, but you can test it by zooming out a bit, and placing a symbol far outside map, then hit our screen button and see how the screen is now enlarged to hide that symbol outside the map border (The point of the screen is to hide everything outside the map border. Everything is still there, just hidden by a white polygon)

Custom Images

Finally, I promised to tell you how to add your own images to the button instead of the built-in ones. To do this, you need an image in .BMP format. (any image editor should be able to convert an image to .bmp for you). However, you need the image in four different sizes, because the toolbars in CC3+ have 4 different display sizes. These four sizes are 16×16 pixels, 24×24 pixels, 32×32 pixels and 48×48 pixels. Keep in mind that these are pretty small, so you can’t have too many details. Most people will have CC3+ set to medium icons, that’s the 24×24 pixel one, so this is a good baseline for what you can include, but make sure you provide all. When you have the images, save all four copies in @Bitmaps\Icons. If you want to call your icon for MyIcon, then the four files should be called MyIcon.bmp, MyIcon24.bmp, MyIcon32.bmp and MyIcon48.bmp. Then, in the menu file, instead of the internal icon identifier, simply use the filename of the base icon (CC3+ will automatically find the correct one for your toolbar size):

#612,@Bitmaps\Icons\MyIcon.bmp:[Screen]|COLLARDEL SCREEN;COLLARAUTO;

If you have questions regarding the content of this article, please use the ProFantasy forums. It can take a long time before comments on the blog gets noticed, especially for older articles. The forums on the other hand, I frequent daily.

 



			    
		    

2 Responses to “Adding Toolbar Buttons”

  1. Both blog and video are excellent. I will now be able to add that zoom to map border button (when I get around to it)

    Thank you very much, Remy! 😀

  2. This came at the perfect time, I have a bunch of custom symbols I got from a couple of different asset artist patreons that I support and constantly loading them manually gets old. This is amazing!

Leave a Reply