MS-Excel / General Formatting

---

Initializing Controls

Your custom RibbonX code might need to set your controls to a particular value or state when your VBA application first loads. For example, earlier in this tutorial you saw toggle button code that turned the Developer tab on and off. However, regardless of the current state of the Developer tab, VBA always shows a toggle in its unpressed state at startup. In this case, the application should get the current state of the Developer tab via the Options.ShowDevTools property, and then set the state of the toggle button to match.

You do this by specifying an attribute that points to a callback macro, and that macro returns a value that determines the initial state of the control. The attribute that determines whether a <toggleButton> element is initially pressed or unpressed is getPressed. Here's the <toggleButton> element from earlier in this tutorial with the getPressed attribute added:

<toggleButton id="tbToggleDeveloperTab"
	imageMso="VisualBasic"
	label="Show Developer Tab"
	size="large"
	getPressed="Module1.tbToggleDeveloperTab_GetPressed"
	onAction="Module1.tbToggleDeveloperTab_OnAction" />

When the document first loads, the program runs the macro specified by getPressed, which in this case is tbToggleDeveloperTab_GetPressed:

Sub tbToggleDeveloperTab_GetPressed(ByVal control As IRibbonControl, ByRef returnVal)
    returnVal = Options.ShowDevTools
End Sub

The returnVal variable (which can have any name you like) returns to the toggle button control the value given by Options.ShowDevTools, and this determines whether the toggle button appears pressed.

You can also initialize other attributes such as enabled, visible, size, label, and more. In each case, you do this by specifying callback attributes that point to callback macros, and those macro return values that determine the initial state of the control. Here are some common callback attributes:

getEnabled
Initializes the control's enabled attribute.
getImageMso
Initializes the control's imageMso attribute.
getKeyTip
Initializes the control's keyTip attribute.
getLabel
Initializes the control's label attribute.
getPressed
Initializes the state of a check box (checked or unchecked) or toggle button (pressed or unpressed).
getScreentip
Initializes the control's screentip attribute.
getSelectedItemID
Initializes a drop-down list by specifying the id of the item that should be selected at first. Use either this attribute or getSelectedItemIndex, but not both.
getSelectedItemIndex
Initializes a drop-down list by specifying the index of the item that should be selected at first. Use either this attribute or getSelectedItemID, but not both.
getShowLabel
Initializes the control's showLabel attribute.
getSize
Initializes the control's size attribute.
getSupertip
Initializes the control's supertip attribute.
getVisible
Initializes the control's visible attribute.

With a drop-down list, Office doesn't show a selected item by default at startup, which can be disconcerting. The getSelectedItemID and getSelectedItemIndex attributes are very handy for making sure that a drop-down list displays an item at startup. In most cases, you'll want the first item in the list selected, and you can accomplish this most easily by using getSelectedItemIndex:

getSelectedItemIndex="lstInsertHyperlinksFor_GetSelectedItemIndex"

Here's the callback macro:

Sub lstInsertHyperlinksFor_GetSelectedItemIndex(ByVal control As IRibbonControl, ByRef returnVal)
    returnVal = 0
End Sub

This works fine for drop-down lists where you've defined static <menu> items in your custom XML code. However, it's often useful to populate a drop-down list on the fly when you first load the document. You can do this by including three attributes in the <dropDown> element:

getItemCount
Returns the number of items you want to add to the list.
getItemID
Returns the id value of each item you want to add to the list.
getItemLabel
Returns the label value of each item you want to add to the list.

In each case, you specify a callback macro that returns the list data.

You can also use the attributes to populate the list portion of a <comboBox> element at startup. To place an initial value in the edit box, you use the getText attribute to specify a callback macro that returns a string value that appears in the edit box.

To demonstrate how these callbacks work, let's run through an example that populates a combo box control with a list of the application's open windows.

Here's the XML:

<comboBox id="cbWindows"
	label="Windows"
	sizeString="mmmmmmmmmmm"
	getItemCount="Module1.cbWindows_GetItemCount"
	getItemID="Module1.cbWindows_GetItemID"
	getItemLabel="Module1.cbWindows_GetItemLabel"
	getText="Module1.cbWindows_GetText" />

Here's the getItemCount attribute's callback macro:

Sub cbWindows_GetItemCount(ByVal control As IRibbonControl, ByRef returnVal)
    returnVal = Windows.Count
End Sub

This procedure just returns the value of the Windows collection's Count property. When RibbonX knows the count, it then proceeds to call the getItemID and getItemLabel callback macros that number of times. For example, if three documents are open, RibbonX calls the getItemID macro three times and then it calls the getItemLabel macro three times. Each time, the macros return the ID and label, respectively, of the next item in the list.

To see how this is done, here's the code for the getItemID attribute's callback macro:

Sub cbWindows_GetItemID(ByVal control As IRibbonControl, index As Integer, ByRef returnVal)
    returnVal = "cbWindowsItem" & index
End Sub

Notice that the Sub statement includes an extra argument named index. The list items are stored internally as an array, so index is the subscript of the next item in the array. The first time RibbonX calls this procedure, the value of index is 0, the second time index is 1, and so on. So, in the callback macro, you can create unique id values by appending the current index value to some string. In this case, the item IDs are cbWindowsItem0, cbWindowsItem1, and so on.

Finally, here's the code for the getItemLabel attribute's callback macro:

Sub cbWindows_GetItemLabel(ByVal control As IRibbonControl, index As Integer, ByRef returnVal)
    returnVal = Windows(index + 1)
End Sub

Again, the Sub statement includes the index value. In this case, however, use that value to return the corresponding member of the Windows collection-Windows(1), Windows(2), and so on. Each of these returns the name of the window, so those are the names that appear in the drop-down list.

You can use the same procedure to populate a gallery control at startup.The <gallery> element also supports the getItemCount,getItemID, and getItemLabel attributes.

With a <comboBox> element, you can also specify the initial edit box value with the getText attribute. Here's an example callback macro:

Sub cbWindows_GetItemCount(ByVal control As IRibbonControl, ByRef returnVal)
    returnVal = "Select a window..."
End Sub