Getting started with the Ribbon Library

Peter Horsbøll MøllerNovember 2016

This will help you getting started with the Ribbon Library to develop MapBasic applications for the new ribbon based MapInfo Pro 64 bit.

Prerequisites:

Download and install:- MapInfo Pro 16.0 64 bit

Get it >>>- MapBasic 16.0

Get it >>>

The Ribbon library is a custom made MapBasic module which is part of the broader mbLibrary.It makes it easier to integrate the most common controls into the Ribbon using MapBasic.

Get the MapBasic Library - mbLibraryYou can get the MapBasic Library from Github.com:

Github.com:• https://github.com/PeterHorsbollMoller/mbLibrary

Get the Ribbon Example ApplicationYou can get the Ribbon Example Application from:

Github.com:• https://github.com/PeterHorsbollMoller/mbRibbonExample

Community Download:• http://communitydownloads.pbinsight.com/code-exchange/

download/ribbon-library-for-mapbasic

Unzip the Ribbon Library

Sample Application

Sample tables

Icons for the ribbon

Full source code

Running the RibbonExample

”How can I use the Ribbon Library in my own MapBasic project?

Create a new file structure

Create a new base folder

Create a sub folder for your MapBasic source code

Base folder

Source code

Add the mbLibrary modules

Copy the Library folder from the RibbonExample to your source code folder

Or better: Copy the files and folders from the folder mbLibrary from the MapBasic Library to the Library folder here

Base folder

Source code

Library

Use your preferred text editor to create a new Mapbasic source code file for your application

Save it to the mbcode folder as type .mb, eg. MyFirstRibbonApp.mb

Insert these lines as a start:

Create a main source code file (.mb)

Include the RibbonLib header file

Include some MapBasic header files

Will show the new Notification

Adding an EndHandler

To make sure your application tidy up after itself, add an EndHandler to your application

Compile with MapBasic 16.0

Call the EndHandler of the RibbonLib

Use your text editor to create a new Mapbasic Project file for your application

Save it to the mbcode folder as type .mbp, eg. MyFirstRibbonApp.mbp

Insert these lines as a start:

Link with MapBasic 16.0

Create a MapBasic Project file (.mbp)

Name of final MapBasic application

Compiled libraries to be included

Your compiled module

Run the application in MapInfo Pro x64

”How do I create a new Tab and add a Group to it?”

Add a new Tab to the Ribbon

1. Check if the Tab already exists2. If not, add it

Adding the new Tab

Does it already exist?

Internal name of the tab

Caption of the tab, shown on the ribbon

Run the application in MapInfo Pro x64

1. Check if the Group already exists2. If not, add it

Add a Group to the Tab

Adding the new Group

Does it already exist?

Internal name of the group

Caption of the group, shown on the ribbon

Run the application in MapInfo Pro x64

How do I add a Button to my new Group?

Adding a button to a group

First you add a new button to the group

Then you set the look and behaviour of the button, such as caption, tooltips and icon

Modular level arrays

Adding a new button

Defining its look and behaviour

Getting its Control ID for later use

The handler of the button

This handler is designed to manage several buttons calling it as it determines the ID of the button clicked by the user

Get the ID and calculate the item number

Now do the work

Requires MAPPERLib

Adding the MAPPERLib module

Include the header file in your source code

And include the compiled module in your MapBasic project file

Include MAPPERLib.def

Include MAPPERLib.mbo

Run the application in MapInfo Pro x64

Adding multiple buttons

Add more elements to the arrays

Loop the elements

Run the application in MapInfo Pro x64

”Can I use my own images on the buttons?”

Using custom images

You can refer to internal MapInfo images, see the MapBasic User Guide, Glossary, List of Embedded images for a list of all images

You can also refer to individual image files on disk, eg. in a sub folder of the application directory

Currently you can only refer to images in an asssembly if it’s located in the MapInfo Pro installation folder. We are looking into improving this.

Internal MapInfo image

Image file on disk

Defines for Internal images

In the mbLibraries folder in a a file called MI_ICONS_X64.def you can find defines for the internal images of MapInfo Pro 64 bit.

The file is included in the source code for the Ribbon Sample application in the Library folder

Can I also make a Button checkable? Or even modify the image on the Button?

Create a Button and make it toggleableAny Button can be checked so there isn’t a special CheckButton control

Use a modular variable to hold the index of the buttonLet’s remember the index of the control

Set the Control to be ”toggleable”

Create the handler and let it toggle the buttonWe are using two modular variables. One to hold the current state of the button and another to hold the index of the button

Change the state of the button (checked/unchecked)

Here we change the Tooltip and the image of the button

”Can I hide controls, groups and tabs? Can I select a certain tab?”

Hiding elements

You can change the visibility of the elements on the Ribbon.

Hide a tab

Hide a group on a tab

Show a control using the index

Hide a control using the names

Selecting tabs

You can select tabs to give these focus.

This could be useful if you load a tool and want to make sure the user notices that you created some tools on a certain tab

What about splitbuttons? Can I create these, too?

Add a SplitButton with a SplitButtonGroup

Start by adding a SplitButton control.

Then set the icon of the SplitButton to match the icon of the first button to add to it later.

Also set the handler of the SplitButton to match the handler of the first button, too. This will be the default action of the SplitButton

Finally, you can add a SplitButtonGroup Adding the SplitButton

Adding a SplitButtonGroup

Set icons

Set handler

Adding buttons to the SplitButtonGroup

And then you can add the buttons to the SplitButtonGroup

This is similar to adding buttons to a Group on a Tab

Adding the Buttons

Specify icons, tooltips and handlers

ControlID – needed in the handler

The handler/subprocedure

The the ID of the control

Did the user use the initial button or did he select one from the list?

Run the application in MapInfo Pro x64

Can you talk a bit about Context menus?

Working with Context menus – Alter Menu

Context menus, aka. right click menus, are not new to the Ribbon interface.

You can use the classic Alter Menu statement to add menu items to an existing context menu.

Working with Context menus - RibbonLib

You can also use the RibbonLib to add ContextMenuItem controls to Context menus – and add images to these as well.

But the Map Mini Toolbar can’t be modified, right?

Adding to the Map Mini Toolbar

You can alos add controls, buttons or toolbuttons, to the map mini toolbar to make certain tools easy accessible for the user when working in a map window

Inserting a StackPanel

Adding a Tool_Button

Specifying a built-in command

”How can I easily integrate my application in the Tools window?”

Tool Manager – Addin procedures

Each tool can publish information

Sub •AddIn_About•AddIn_Help•AddIn_DefaultCommand

Function •AddIn_Name()•AddIn_Description()•AddIn_Version()•AddIn_ImageUri()

Help File Aboutbox End

Description

Version

Image

Name

Default Command activated thru double click

The ProgramInfo module

These standard subprocedures and functions have been added to the ProgramInfo module

Include the header file for this module in your application module

Include the ProgramInfo.def file

Configure the ProgramInfo module

Specify the values for ProgramInfo to use in the dialogs

You can use the functions from ProgramInfo to get to the values, such as the application name via PRGIGetApplicationName()

Specifying values for ProgramInfo

Use functions from ProgramInfo to get to the values

Include compiled modules in your projectYou need to include several extra compiled modules in the MapBasic project file

Reading/writing configuration filesManaging files and foldersWorking with map windowsAboutbox and programinformationHandling strings i different languagesWorking with strings

Run the application in MapInfo Pro x64

Do I really have to use the RibbonLib for integrating my application into the Ribbon?

Other options

The RibbonLib helps you integrate your application into the Ribbon interface using only MapBasic (and some .NET methods).

You can achieve the same by using the methods declared in IMapInfoPro.Def

Or by using the MapInfo Pro .NET API from a .NET language such as C#

Our partner, AGIS, has developed a visual Ribbon Designer SDK which lets you do this in a visual designer.

What did he just talk about?

Summary

We have looked at• Getting the RibbonLib• Creating a MapBasic project• Creating Tabs and Groups• Creating Buttons• Using your own images• Creating checkable Buttons• Hiding Tabs, Groups and Controls• Creating SplitButtons• Working with Context Menus• Modifying the Map Mini Toolbar• The new Tools window• Other options for designing the interface

Questions?

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