Porting simple applications to the ribbon interface using MapBasic

Peter Horsbøll MøllerOctober 2017

Agenda:

1. Concepts of the ribbon interface

2. Control types available

3. Taking advantage of the Tools window

4. Integrate a tool in the ribbon interface

5. Resources

“The ribbon interface makes it easier to discover features and functions of MapInfo Pro”

1. Concepts of the ribbon interface

Ribbon: The Main Ribbon Interface from which all Ribbon controls inherit.

Ribbon Tab: Individual member of Ribbon Tab Collection (e.g.: HOME, TABLE, MAP, SPATIAL, etc.).

Ribbon Tab Group: Group of Ribbon controls under a specific Ribbon Tab that are typically related tasks (e.g.: File, Clipboard, Windows, etc.).

Ribbon Button Control: the actual control (e.g.: Tool Button or Split Button, etc.) that reside within the Ribbon Tab Group.

Working with the .NET SDK from MapBasic

It helps if you try to adopt an “Object Orientated” approach.

First, you need to get the MapInfo Pro instance (or object).From the MapInfo Pro instance, you can get the Ribbon instance.The Ribbon instance has a collection of Tab Groups.Each Tab Group has a collection of Controls.

A control, as well as the other instances the Ribbon, the Tabs and the Groups, have properties such as captions and icons that can be set.

2. Control types available

Button Control

SplitButton Control

Button Controls

Gallery Control

GalleryItem Controls

ToolButton Control DropDownButton Control

Button Controls

3. Taking advantage of the Tools window

Tools window on the HOME tab

Tools window as a dockable window

Tool window – Addin procedures

Each tool can publish information

Sub procedures:•Sub AddIn_About•Sub AddIn_Help•Sub AddIn_DefaultCommand

Functions:•Function AddIn_Name()•Function AddIn_Description()•Function AddIn_Version()•Function AddIn_ImageUri()•Function AddIn_DefaultCommandText()

Help File Aboutbox End

Description

Version

Image

NameDefault Command

activated thru

double click

4. Integrate a tool in the ribbon interface

Running an old application

You can run older applications in the new 64 bit MapInfo ProMany of these will work and get loadedSome will be only loaded into the Tools Window, others also into the LEGACY tab

Definition files

Typically, you have used a number of standard definition files in your MapBasic application:• MapBasic.def: Constants for MapBasic functions like TableInfo() etc.• Menu.def: Constants for MapInfo Pro menu commands• Icons.def: Constants for icons used in MapInfo Pro

When building an application for the ribbon interface in MapInfo Pro you will need to include a few more:• IMapInfoPro.def: Declaration for the .NET API methods• Enums.def: Constants used in the .NET API such as control types etc.

Includes and Declares

Include the new definition files:Include "IMapInfoPro.def"

Include "Enums.def"

Declare the Tools window procedures/function you want to use:Declare Sub AddIn_About

Declare Function AddIn_Name() As String

Declare Function AddIn_Description() As String

Declare Function AddIn_Version() As String

Declare Function AddIn_ImageUri() As String

Declare the EndHandler used to remove controls from the ribbonDeclare Sub EndHandler

Modular level variables

'IMapInfoPro:

Dim mtsMapInfoApplication as This

'The Ribbon:

Dim mtsRibbon as This

'The Tab Collection of the Ribbon:

Dim mtsRibbonTabColl as This

'The Control Collection of the group:

Dim mtsGroupControlColl As This

'The Button we are adding:

Dim mtsBtn As This

Let’s build the interface:

Sub Main

'We need this to get resources, like icons, from .NET assemblies

Call RegisterUriParser(New_GenericUriParser(1), "pack", -1)

'Get the IMapInfoPro instance

mtsMapInfoApplication = SystemInfo(SYS_INFO_IMAPINFOAPPLICATION)

'Get the Ribbon from the MapInfo Pro instance

mtsRibbon = GetRibbon(mtsMapInfoApplication)

'Get the Ribbon Tab Collection from the Ribbon instance

mtsRibbonTabColl = GetTabsColl(mtsRibbon)

Getting the .NET instances

Still preparing to build the interface:

'Get the Ribbon Tab named "TabSpatial" from the Ribbon Tab Collection

Dim tsRibbonTab As This

tsRibbonTab =GetRbnTabCollItemStr(mtsRibbonTabColl, "TabSpatial")

'Get the ribbon group collection.

Dim tsRibbonGroupColl As This

tsRibbonGroupColl = GetRbnTabGrps(tsRibbonTab)

'Get the ribbon group "SpatialCreateBar" from the ribbon group collection

Dim tsRibbonGroup As This

tsRibbonGroup = GetRbnCtrlGrpCollItemStr(tsRibbonGroupColl

, "SpatialCreateBar")

Adding controls to the Ribbon

Let’s add a control/button:

'Get Group controls collection

mtsGroupControlColl = GetRbnCtrlGrpCtrls(tsRibbonGroup)

'Now add a button to the group's controls collection with a name

', caption, and enumerated ControlType

mtsBtn = MICtrlCollAddStrStrInt(mtsGroupControlColl, "btnConnectDots“

, "Connect The Dots", ControlType_Button)

'Set command to the button

call SetRbnBtnCtrlCallingHandler(mtsBtn, "ConnectTheDots")

Adding controls to the Ribbon

Let’s add a tooltip to the control/button:

'Create & Set the button tooltip

Dim tsToolTip As This

tsToolTip = New_MapInfoRibbonToolTip()

Call SetMIRbnToolTipToolTipDescription(tsToolTip, "Connect The Dots")

Call SetMIRbnToolTipToolTipText(tsToolTip, "Creates a polygon or polyline

from the points selected")

Call SetMIRbnToolTipToolTipDisabledText(tsToolTip, "Make sure to select

records from a layer")

Call SetRbnBtnCtrlToolTip(mtsBtn, tsToolTip)

Adding controls to the Ribbon

Adding icons and setting the size of the control:

'Set the button icon

Call SetRbnBtnCtrlSmallIcon(mtsBtn, New_Uri("pack://application:, , ,

/MapInfo.StyleResources;component/Images/Spatial/segmenting_16x16.png",

0))

Call SetRbnBtnCtrlLargeIcon(mtsBtn, New_Uri("pack://application:, , ,

/MapInfo.StyleResources;component/Images/Spatial/segmenting_32x32.png",

0))

'Set the size of the button

Call SetRbnBtnCtrlIsLarge(mtsBtn, TRUE)

Adding controls to the Ribbon

Removing the control from the ribbon on exit:

Sub EndHandler

Dim bRemoved As Logical

OnError Goto HandleError

bRemoved = MICtrlCollRemove(mtsGroupControlColl, mtsBtn)

mtsBtn = NULL_PTR

Exit Sub

HandleError:

Note "EndHandler: " + Error$()

Resume Next

End Sub

Adding a Clean up to the EndHandler

Let’s add the procedures and functions for the Tools window:

Sub AddIn_About

Call About

End Function

Function AddIn_Name() As String

AddIn_Name = "Connect The Dots"

End Function

Function AddIn_Description() As String

AddIn_Description = "Creates a polygon or polyline from the points

selected in the layer the points are selected from."

End Function

Integrating into the Tools window

Function AddIn_Version() As String

AddIn_Version = "2.0"

End Function

Function AddIn_ImageUri() As String

AddIn_ImageUri = "pack://application:, , ,

/MapInfo.StyleResources;component/Images/Spatial/segmenting_16x16.png"

End Function

Integrating into the Tools window

Include Files

Addin sub/function declares

Global ribbon variables

Getting the ribbon elements

Adding a control to the ribbon

Specifying the handler

Adding Tooltip

Specifying icons

EndHandler to remove controls

Addin subs and functions

https://github.com/PeterHorsbollMoller/mbConnectTheDots

“Even though most MapBasic applications will run in 64 bit, spending some time integrating them into the ribbon will be worth the while”

4. Resources

• Li360 Community• The MapBasic Topic• The MapInfo Pro Developer Group• How to customize the MapInfo Pro ribbon interface

document, find it in the MapInfo Pro Developer Group

• Attend the upcoming MapBasic webinar in November• Look at the MapBasic samples that ship with MapBasic 16.0• Look at applications from the Community Download page

You have come this far and now you want to learn more?

• Get started, give it a try and ask for help on the Li360 Community, <<go to the Li360 Community>>

• Consider looking into using the RIBBONLib module?

• Watch this video: Getting started with the RIBBONLib MapBasic library <<Find it here on Li360>>

• Consider using .NET to customize the ribbon?

What could my next steps be?

What did he just talk about?

We looked at the structure and elements of the ribbon and what control types you have access to.

We investigated the new tools window and how to integrate your tools into this and finally we ported a very basic tool to the ribbon interface.

Thank you!

Peter Horsbøll Møller | peter.moller@pb.comPitney Bowes