MapInfo Pro Developers User Group

 View Only

MapBasic Monday: Using the Create Ribbon Tab Statement in MapBasic v2021

  • 1.  MapBasic Monday: Using the Create Ribbon Tab Statement in MapBasic v2021

    Employee
    Posted 01-17-2022 05:59
    Happy #MapInfoMonday,

    Today, I have renamed #MapInfoMonday to #MapBasicMonday as I'll show you a couple of examples of how to use the Create Ribbon Tab and Set Ribbon Tab statements that we added to MapBasic v2021.​​​ These two statements can be used to add your custom controls to the ribbon interface.

    If you are using an older 64-bit version of MapInfo Pro, you can use one of the following methods to add controls to the ribbon:
    With MapBasic v2021, we added a number of statements and functions to help you inspect and modify the ribbon interface. I will not go into depth with them in this post but I wanted to highlight them so that you can read more about them in the MapBasic documentation:
    • Create Ribbon Tab statement: This statement creates a MapInfo Pro ribbon tab.
    • Create Ribbon Context Tab statement: This statement creates a MapInfo Pro ribbon contextual tab.
    • Create Ribbon Context Tab Group statement: This statement creates a MapInfo Pro ribbon contextual tab group.
    • Set Ribbon Tab statement: This statement updates a MapInfo Pro ribbon tab.
    • Set Ribbon Context Tab statement: This statement updates a MapInfo Pro ribbon contextual tab.
    • Set Ribbon Control statement: This statement updates a MapInfo Pro ribbon control.
    • Set Ribbon Clear statement: This statement removes any tabs, contextual tab groups, groups and controls added to the ribbon by a running MBX.
    • Set Ribbon Context Tab Group statement: This statement updates a MapInfo Pro ribbon contextual tab group.
    • RibbonInfo() function: This function returns a property value of a ribbon control.
    • RibbonItemInfo() function: This function returns a property value of a collection item under a control.
    • Execute Ribbon Control Handler statement: This statement executes the MapInfo Pro ribbon control handler.
    The main difference between the two statements:
    • Use the Create Ribbon Tab statement to create a MapInfo Pro ribbon tab and groups and other controls.
    • Use the Set Ribbon Tab statement to update MapInfo Pro ribbon tab, groups, and other controls. You will also use this statement to add controls to existing tabs and/or tab groups.
    Let us have a look at a couple of examples.

    Keep in mind, the element Name is internal to the application and the element Caption is what is shown in the user interface. When referring to existing elements, you will use the element Name. An element can be a tab, a group, or a control.

    Adding a control to an existing tab group

    In this first example, we want to add a new control to the existing group Calculate on the Table tab  As the tab and group already exist, we will use the Set Ribbon Tab statement in combination with the Add keyword.

    Set Ribbon Tab TAB_TABLE
       Group TAB_TABLE_CALC_GRP
       Controls ( Add
          Control "cmdPredominance" Caption "Calculate Predominance"
            Type CTRL_TYPE_BUTTON
            Size Large
            ToolTip "ToolTip: Calculate Predominance for selected columns"
             Properties( PROPERTY_CALLINGHANDLER : "MENUCalculatePredominance"
               , PROPERTY_LARGEICON : PATH_IMAGES & "CalculatePredominance_32.png"
               , PROPERTY_SMALLICON : PATH_IMAGES & "CalculatePredominance_32.png"
               )
          )

    The constants TAB_TABLE and TAB_TABLE_CALC_GRP are defined in the file RibbonControls.def along with other useful constants for working with the ribbon such as the supported properties and the icons.

    As you are adding a control to an existing group, you will need to use the Set Ribbon Tab Statement. It will fail if you use the Create Ribbon Tab statement as the tab already exists. You also need to use the Add keyword after the Controls keyword, as you want to add a new control, not modify any existing controls.

    Here is the result of the code above. The control has been added to the group Calculate on the Table tab.

    Adding a control to a new group on an existing tab

    Another scenario is that you want to add a control to an existing tab but on a new group.

    Set Ribbon Tab TAB_TABLE
       Group "grpPredominance" Caption "Predominance"
       Controls ( Add
          Control "cmdPredominance" Caption "Calculate Predominance"
            Type CTRL_TYPE_BUTTON
             Size Large
             ToolTip "ToolTip: Calculate Predominance for selected columns"
             Properties( PROPERTY_CALLINGHANDLER : "MENUCalculatePredominance"
               , PROPERTY_LARGEICON : PATH_IMAGES & "CalculatePredominance_32.png"
               , PROPERTY_SMALLICON : PATH_IMAGES & "CalculatePredominance_32.png"
               )
          )

    The Set Ribbon Tab statement checks if the specified group exists. If it doesn't it will be created. If you don't specify the group Caption, it will use the group Name as the Caption too.

    Here is the result of the code above. The control has been added to a new group, Predominance, on the Table tab.

    Adding a control to a new group on a new tab

    Let me top of the examples by creating a new tab with a new group and a single control.

    Create Ribbon Tab "tabAnalyze" Caption "Analyze"
       Group "grpPredominance" Caption "Predominance"
       Controls ( Add
          Control "cmdPredominance" Caption "Calculate Predominance"
             Type CTRL_TYPE_BUTTON
             Size Large
             ToolTip "ToolTip: Calculate Predominance for selected columns"
             Properties( PROPERTY_CALLINGHANDLER : "MENUCalculatePredominance"
                , PROPERTY_LARGEICON : PATH_IMAGES & "CalculatePredominance_32.png"
                , PROPERTY_SMALLICON : PATH_IMAGES & "CalculatePredominance_32.png"
                )
          )

    Here's the result of the Create Ribbon Tab statement.

    When using the Create Ribbon Tab statement, you can use the Add keyword in front of the controls, or you can omit it. Both ways work.

    This is a very basic example, that you can extend in multiple ways. You can with a single statement, create a new table with multiple groups each holding multiple controls. In the MapBasic Help System, you can find a Create Ribbon Sample Code that holds examples of most if not all the different control types that MapBasic/MapInfo Pro supports.

    In this article, we have just scratched the surface of the options with the newly added statements and functions for working with the ribbon. Do let us know if you have specific requirements or run into issues with these new statements.

    ------------------------------
    Peter Horsbøll Møller
    Principal Presales Consultant | Distinguished Engineer
    Precisely | Trust in Data
    ------------------------------