Using a MapBasic library to integrate tools into MapInfo Pro 64 bit

In the previous article I discussed how you can use the new .NET API from MapBasic to integrate your MapBasic application into the new ribbon interface of MapInfo Pro 12.5 64 bit.

In this article I will show you how some of the basics tasks can be done easier by using a MapBasic library, or module, that wraps the .NET API into a number of easy to use custom MapBasic functions and procedures.

I intentionally write “basics tasks” because currently the Ribbon library doesn’t allow you to modify all parts of the new Ribbon interface.

With “basic tasks” I’m referring to task such as creating and removing tabs, groups and basic controls like buttons, toolbuttons and splitbuttons. You will also be able to add buttons to and remove buttons from splitbuttons.

MapBasic 12.5.1

First you need to download and install MapBasic 12.5.1 from the Pitney Bowes website: http://www.pbinsight.com/support/product-downloads/item/mapbasic-v12.5.1-download

You need this new version of MapBasic in order to compile MapBasic applications that modify the new Ribbon interface.

You can install MapBasic 12.5.1 side by side with MapBasic 12.5 or other older versions of MapBasic.

Also note that the compiled MapBasic application will require at least MapInfo Pro 12.5.1 in order to run.

What exactly is the RibbonLib?

The Ribbon library is a MapBasic module, a .mb file, containing a number of custom MapBasic functions and procedures that will help MapBasic programmers integrate their current and new MapBasic applications into the new ribbon interface of MapInfo Pro 64 bit.

The Ribbon library wraps the .NET API into a number of function making it possible to add a new button to the Ribbon via a few MapBasic function calls.

To use the functions from the Ribbon library in your own MapBasic module you have to include the declarations of the functions and procedures of the library in your module. You do this using the “include” statement.

With the Ribbon library comes a set of other custom made libraries that are being used by the Ribbon library and the Ribbon Example application. The declarations for these have also been included in the Ribbon Example application as you can see below. The Ribbon library include statement has been highlighted in blue.

When you start using functions and procedures in your source files that aren’t within the source file, the files will get compiled to mbo files instead of mbx files. You will afterwards have to link these mbo files into the final mbx file using a MapBasic project file, a mbp file.

The MapBasic project file for the Ribbon Example application looks like this:

Take a look at the Ribbon Example application when you download the resources to get a view on how you can structure a MapBasic project that uses several modules.

Working with tabs

Let’s start with the first element on the ribbon, the tabs.

The RibbonLib lets you analyse existing tabs and add tabs to the ribbon. In the code below you can see that I first check if a certain tab exists using the RBNTabExists function. If it doesn’t exist I’m adding it to the ribbon with the RBNAddTab function.

nCtrlIdx now holds a reference to the internal ID of the tab in the RibbonLib. You can use this to work with your Tab thru the functions in the RibbonLib that require an Index value for a Tab.

Working with groups

Afterwards I can add groups to this new tab, or to any other existing tab on the ribbon.

Again I start by investigating if the group already exists. If not I use the function RBNTabAddGroup to add it to the Tab. In this base I use the same name and caption for the group – a constant named xProgramMenu defined earlier in the code.

Working with buttons - adding

Finally we get to the part where you add controls, or buttons, that the user actually will use to interact with your application.

You can add a basic button which can be compared to the Menu Item of PushButton from the classic menubased user interface via the “Button” based functions. Or you can use any of the other control types such ToolButton, RibbonSeparator or SplitButton via the more generic “control” based functions.

In the first example I’m adding a button to the new group that I created on the new TOOLS Tab above with the function RBNGroupAddButton. Notice how I first add the button and then afterwards use the Index of the button to specify its tooltip, icons and the handler it’s calling when the user activates it.

The function RBNControlSetToolTipIdx takes a number of parameters. Firstly the Index of the control to set the tooltip on, then the description which is the caption of the tooltip and finally the actual tooltip and potentially also a tooltip that will be shown if the tool has been disabled.

The function RBNControlSetIconsIdx also takes the Index of a controls. Besides this it needs to know what sizes the icons should have on the control and the actual name of the icons. The icons can either be stored in physical files on disk, for example in a sub folder in the application directory, or they can be stored within a .NET assembly as a resource and accessed as a pack.

Using the first couple of examples above you can create your own tab, add a group to this tab and then add one or more buttons or controls to this group. In MapInfo Pro the result could look like this

Working with buttons - inserting

The next example shows how to insert a button before an existing control on the ribbon. This is useful if you want to place your control close to an existing control with a similar behavior or functionality.

The function RBNGroupInsertButtonBefore only takes one more parameter than the previous function RBNGroupAddButton: the name of the control to position the new button before. If the named control isn’t found the control is added as the last control in the group.

Here you can see how the new control, Browser Info, is inserted before the Export control.

Working with splitbuttons

The final example I have chosen here is to show how you can add a control to an existing SplitButton. A SplitButton is a control that can hold multiple controls. It will let you group controls with similar functionality into one “dropdown” control.

The function RBNSplitButtonGroupAddControl works similar to the previous mentioned functions. It just needs a few more parameters besides the Tab and Group Name. It also needs the name of the SplitButton and the name of the MenuGroup on the SplitButton to add the new control to.

Here is a screendump showing the new button control in the existing SplitButton with the other Selection tools.

Subscribing to Events

The new .NET API also lets you subscribe to a number of new events. Previously MapBasic only had a few basic events that you can react to, including SelChangedHandler, WinChangedHandler and WinClosedHandler.

With the new .NET API we are starting to extend the range of events. To take advantage of these new events you do however have to set up subscribers to the events a bit differently.

The RibbonLib helps you do this is an easier way using a basic custom MapBasic function called RBNEventSubscribe. This functions takes two parameters: the event you want to subscribe to and the MapBasic procedure that should be alerted/called when the event occurs.

Below you can see two examples where I subscribe to the new TableOpened event and the new TableClosed event.

Here you can see the procedure that will get called when the TableClosed event occurs.

Notice that the procedure takes a This parameter that basically is a reference to the arguments of the event. You can use a number of functions declared in the IMapInfoPro.def to get attributes from the arguments object. In the example below I’m using GetTableEventsArgsTableAlias to get to the name of the table that is being closed.

Exactly what functions you can use on the arguments depends on the type of event.

Removing the custom controls on exit

If you already have been creating MapBasic applications using the classic menu based interface you know that you didn’t have to clean up your “mess” when your MapBasic application gets unloaded. MapInfo Pro did this for you.

Well, this is changing now. Your application needs to remove the tabs, groups and controls that your application adds to the Ribbon. If you use the functions from the RibbonLib to add controls etc. to the Ribbon interface, you can do the cleaning using a single procedure in the RibbonLib: RBNEndHandler.

The RibbonLib basically keeps track of where you are adding which controls and is able of removing these again.

You just have to add a call to the RBNEndHandler in the EndHandler procedure of your application. In this way the RibbonLib will remove the controls that was added.

Where do I get the RibbonLib?

We have posted the RibbonLib on our Community Download page: http://communitydownloads.pbinsight.com/code-exchange/download/ribbon-library-for-mapbasic

Go to the site and download the zip file. You are also welcome to rate this “application” on the site if you want to.

We are also sharing the sourcecode for the RibbonLib, or more precisely the RibbonExample application, via Githup. This might be an easier way for you to get access to the sourcecode and especially an easier way to get the latest version.

You can find the sourcode for the RibbonExample application here on Githup: https://github.com/PeterHorsbollMoller/mbRibbonExample

Summary

In this article I have shown how a MapBasic programmer easily can modify the ribbon interface of MapInfo Pro 12.5.1 64 bit using the Ribbon Library.

We have looked at adding tab, groups and a number of different control types.

We have also looked at how you using the RibbonLib easily can remove the custom controls added by your MapBasic application when the application is closed.

And we did briefly go thru how to subscribe to the new events added with the new .NET API.