getting started with the ribbon library - muguki user group meeting 2016
TRANSCRIPT
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 | [email protected]