Getting started with the ribbon library for MapBasic

1. Getting started with the Ribbon Library Peter Horsbøll Møller March 2015

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

3. Prerequisites: Download and install: - MapInfo Pro 12.5 64 bit Get it >>> - MapBasic 12.5.1 Get it >>>

4. Get the Ribbon Library You can get the Ribbon Library from: Github.com: • https://github.com/PeterHorsbollMoller/mbRibbonExample Community Download: • http://communitydownloads.pbinsight.com/code-exchange/download/ribbonlibrary-for-mapbasic

5. Unzip the Ribbon Library Sample Application Sample tables Icons for the ribbon Full source code

6. Running the RibbonExample

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

8. Create a new file structure Create a new base folder Create a sub folder for your MapBasic source code Base folder Source code

9. Create a file structure Copy the Library folder from the RibbonExample to your source code folder Base folder Source code Library

10. 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: Compile with MapBasic 12.5.1 Create a main source code file (.mb) Include the RibbonLib header file Include some MapBasic header files Will show the new Notification

11. 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 12.5.1 Create a MapBasic Project file (.mbp) Name of final MapBasic application Compiled libraries to be included Your compiled module

12. Run the application in MapInfo Pro x64

13. Adding an EndHandler To make sure your application tidy up after itself, add an EndHandler to your application Call the EndHandler of the RibbonLib

14. ”How do I create a newTab and add a Group to it?”

15. Add a newTab to the Ribbon 1. Check if theTab already exists 2. If not, add it Adding the new Tab Does it already exist?

17. 1. Check if the Group already exists 2. If not, add it Add a Group to theTab Adding the new Group Does it already exist?

19. How do I add a Button to my new Group?

20. 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

21. 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

22. 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

24. Adding multiple buttons Add more elements to the arrays Loop the elements

26. What about splitbuttons? Can I create these, too?

27. Add a SplitButton with a SplitButtonGroup I’m adding a new SplitButton control I’m setting the icon of the SplitButton to match the icons of the first button I’ll add to it later And I’m setting the handler of the SplitButton to match the handler of the first button, too Finally I add a SplitButtonGroup Adding the SplitButton Adding a SplitButtonGroup Set icons Set handler

28. Adding buttons to the SplitButtonGroup And then we add the buttons to the SplitButtonGroup This is similar to adding buttons to a Group on aTab Adding the Buttons Specify icons, tooltips and handlers ControlID – needed in the handler

29. The handler/subprocedure The the ID of the control Did the user use the initial button or did he select one from the list?

31. ”How can I easily add the standard buttons to the Tools window?”

32. 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

33. 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

34. 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

35. Include compiled modules in your project You need to include several extra compiled modules in the MapBasic project file Reading/writing configuration files Managing files and folders Working with map windows Aboutbox and programinformation Handling strings i different languages Working with strings

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

38. 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 Internal MapInfo image Image file on disk

39. Defines for Internal images I have created defines for the internal images of MapInfo Pro 64 bit in a file called MI_ICONS_X64.def. The file is included in the source code for this sample application in the Library folder and it will also be included with the RibbonLibrary SampleApplication later.

40. ”Are you sharing the source code for this sample application?”

41. Get the source code for the sample application I have shared the source code on the Danish Pitney Bowes Software blog. Get it here: http://blogs.pitneybowes.dk/files/2015/03/MyFirstRibbonApp.zip Have fun!

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