Using my macros with XLplus
XLplus Ver. 3.X offers you a convenient way to include your own macros / VBA solutions into XLplus. Your tools will be treated as XLplus Add-Ons. Once you installed your tool, it will be available within the Add-Ons Menu to launch it.
Note:
XLplus Ver. 3.X placed a demo file into the directory it is installed in which can be used for testing and as a reference. The file is named
myOwnMacro.xlam. You can install this Add-On using the
Add-On Manager and test it - as well as analyse it: Use
Add-In Manager to temporarily convert the tool to a Workbook. Now you can compare its settings with the following help data. In case you wish to reinstall the tool afterwards again, convert it back to an Add-In, save it and start
Add-On Manager again.
In order to create your tool and prepare it for XLplus simply include 2 Worksheets in your solution which will steer the installation process.
The first worksheet has to be named Install_Settings, the second has to be named Install_Ribbon.
Worksheet Install_Settings has to contain the following information:
- Add-On Name
- Ver.
- Tools
- Description UK
- Description DE
|
Add-On Name |
The name of your tool as it will be shown in the Add-On Manager when installing your tool.
Note: This Add-On Name has to be identical with the name you specify in Worksheet Install_Ribbon within column Add-On Name. In case these names are not identical, your tool cannot be uninstalled or updated correctly. |
| Ver. |
The version of your tool. |
| Tools |
A list of all tools you will install. These are the single functions you will include within the Add-Ons Menu. The information is required for correctly uninstalling your tool. A correct uninstall is required when updating your tool to a new version.
The names of your tools have to be the English names you specify in Worksheet Install_Ribbon within column objLabel. |
| Description UK / DE |
A brief information about your tools in English and German. This information is shown within the installation process of your tool. |
Ex.: Install Settings
The second worksheet, Install_Ribbon, has to contain the following information:
- objHierachyID
- objContainer
- Add-On Name
- objID
- objisContainer
- objType
- objImage
- objMsoImage
- objItemSize
- objOnAction
- objLabel
- objSupertip
- objScreentip
| objHierachyID |
The objHierachyID groups your control in one Menu Group. All of your objHierachyID have to be a number greater 100. By using objHierachyID you can combine your tools thematically.
Status: Required
Proposal:
We suggest to use the following numbering schema:
| 101 |
File |
| 102 |
Edit |
| 103 |
Insert |
| 104 |
Format |
| 105 |
Tools |
| 106 |
Data |
| 107 |
View |
| 108 |
Window |
| 109 + |
custom menu names |
|
| objContainer |
objContainer is a description for your grouped commands, i.e. Edit or File. It eases up handling a variety of tools in case objHierachyID receives a description.
Status: Required |
| Add-On Name |
Add-On Name is the name you specified within Worksheet Install_Settings.
Note: Add-On Name has to be identical with the Add-On Name specified in worksheet Install_Settings. Otherwise you cannot correctly uninstall or update your Add-In.
Note: Add-On Name does not have to be entered for container objects (i.e. Menu, see objisContainer) but is mandatory for single objects like Buttons.
Status: Required
|
| objID |
objID is a unique ID identifying your tool within the MS Excel Ribbon. If obmitted or already used, the installation routine will prepare a unique ID for you.
Status: Optional |
| objisContainer |
objisContainer is a number which states if the control is a group (container) or a single control.
1 = Control is a group (container)
0 = Control is a single control
It is crucial setting these values carefully.
Status: Required
Example:
| menu |
group (1) |
| gallery |
group (1) |
| button |
control (0) |
| menuSeparator |
control (0) |
|
| objType |
objType specifies the Control to add. Currently the following controls can be added successfully:
- menu
- gallery
- button
- menuSeparator
You should require menu and button, only.
Note: objType is case-sensitive.
Status: Required |
| objImage |
objImage is the filename of an image to show for the control. See below for details.
Status: Optional |
| objMsoImage |
objMsoImage is the name of a MS Excel build-in image to use for your control. See below for details.
Status: Optional |
| objItemSize |
objItemSize steers the appearance of images within a group, i.e. a menu. Setting this to large will show large icons for all controls within the group.
Options are: large or normal.
Note: objItemSize has to be assigned to group items, i.e. menu, only!
Status: Optional |
| objOnAction |
objOnAction is the complete path to the module which shall be run when a user starts the control. The installation process will replace any path information stored in objOnAction with the current path of your tool. The information provided has to be at minimum:
i.e. MyModule.MySub
Status: Required |
| objLabel |
objLabel is the name of your tool as it will be shown within the XLplus Add-Ons menu. It has to be available in English and German.
Note: You should specify a name for your groups, too.
Status: Required |
| objSupertip |
objSupertip is information shown when a user moves the mouse cursor over a control. This information can be a longer description than objScreentip. It should be provided in English and German.
Status: Optional |
| objScreentip |
objScreentip is quick and short information for a tool.
Status: Optional |
Ex.: Ribbon Settings
Using Images
The easiest way of including images is using the build-in images of MS Excel (objMsoImage). There exist several tools which help identifying those images.
In case you wish to include your own images, you have to follow the following procedure:
- Save your images in a sub folder of the folder, XLplus is installed in. The folder has to be named images.
- Precede the name of your image with a Backslash (\) when specifying objImage.
During the installation of your tool, XLplus will create the correct path to your images for the Ribbon.
File Type
Your tool has to be an Excel Add-In of format either MS Excel 2000/2003 (*.XLA) or MS Excel 2007 or higher (*.XLAM). Normal workbooks will not be recognized by the XLplus Add-On Manager.
Translations
Your tool has to specify objLabel for English and German. In case you do not want to translate it to German (or English), simply put the English/German text into the required fields. Both languages have to be specified since XLplus allows changing the language it uses.
I screwed it up
In case you screwed up the instable Ribbon construct MS provides, you might start from scratch again. XLplus Ver. 3.X offers a tool which completely clears the XLplus Add-Ons Menu. Once this is run, all Add-Ons have been removed from XLplus and you can start again.
Note: XLplus Ver. 3.X offers another handy tool supporting you in developing your own Add-Ins. Add-In Manager allows managing all currently loaded Excel Add-Ins from within Excel itself (instead of the IDE). Using Add-In Manager you can save and close Add-Ins.
FAQ
I cannot see any Supertips
Make sure Excel is allowed to show Supertips. You will find this setting in Excel - Options - General (or Popular) - Screentip Style.
Screenshot: It is probable that you configured one or two settings wrong. You can enable error reporting for all Ribbon related errors helping to identify the problem. You will find this setting in Excel - Options - Advanced. Activate Show Add-In user interface errors.
Screenshot:
I receive an error message stating "Cannot get handle to Ribbon"
An unhandled error occured in your application which caused MS Excel to cut off the XLplus Ribbon Tab from XLplus. Restart XLplus so it can load the XLplus Ribbon Tab again and store the actual handle to it.
My macro does not start and I receive error messages
Check your settings on worksheet Install_Ribbon; compare them with the information provided here and the demo files. Reduce your settings to a menu plus buttons contained within. In case you are sure your settings are correct check your application coding - errors within your application will cause the Ribbon to stumble.
How do I check my code best?
Add breakpoints to your code. You can add manual breakpoints by setting them within the VBE or by adding a single line of code: Stop. The Stop command will halt your code and you can step through it. In case your code abandons surprisingly it is more than propable that it caused the Ribbon to stumble, too.
How can I test, if the Ribbon has stumbled?
Simply try changing the language of XLplus - if this fails with error "Cannot get handle to Ribbon" the Ribbon stumbled.
Excel entirely crashed ...
Yep, MS Excel 2007 as well as MS Excel 2010 are crash-kids when dealing with the Ribbon ...