porting simple applications to the ribbon interface using
TRANSCRIPT
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 RIBBONLibMapBasic 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 | [email protected] Bowes