Tech Articles

Learning to define user events for items in the RibbonBar control feels like a lot of trial and error.
Different items support different events. Same event type requires different parameters.
My aim with this article is to take "... and error" out of your RibbonBar coding.
For each ribbon item type you get user event definitions that work.

Each ribbon item has its own XML element (here: Print Title is a CheckBox).
Each item binds specific user events via properties (here: Clicked on CheckBox binds to ue_PrintTitle)
Each user event must have the correct parameter list (here: Clicked event for CheckBox always requires al_handle while no other parameters allowed)
Each item type has its own PowerScript class and functions to obtain the object (here: Obtain class = RibbonCheckBoxItem via function GetCheckBox)
 

RibbonBar Structure

RibbonBar Builder is an excellent tool to build a ribbon. It's combination of XML editor and visual preview makes it easy to see the layout you define.
There is "autoscript" help in the editor for valid XML elements and XML attributes.
You name the user events within the XML syntax. However, you cannot see how to define the user events. Which parameters are required.

Available event types depend on ribbon item type. Required parameter list depends on event type and ribbon item type.
Each event type (like Clicked and Selected) has its own XML attribute where you name the user event you want it to trigger.
That event is only triggered when it defines correct parameter list.

This article lists which event types require which parameter list for each ribbon item type.

Event Signatures per Ribbon Item Type

This section only lists item types that support user events.
For each item type it lists the XML Element, PowerBuilder class name, and available event types.
For each event type it lists the required parameter list for that item type.
Each combo of item type and event type is documented by screen shot and code snippets.

LargeButton

• XML Element = LargeButton
• Class Name = RibbonLargeButtonItem
• Event Types
  • Clicked = event ue_BoardEmployees( long al_handle )
  • Selected = event ue_HoverBoardItem( long al_handle )
• Parameters
  • al_handle = Refers to the button.

SmallButton

Similar to LargeButton except for picture size.

• XML Element = SmallButton
• Class Name = RibbonSmallButtonItem
• Event Types
  • Identical to LargeButton (see above)

TabButton

Similar to LargeButton except for picture size and location within the ribbon.

• XML Element = TabButton
• Class Name = RibbonTabButtonItem
• Event Types
  • Identical to LargeButton (see above)

CheckBox

Similar to LargeButton for user events albeit different properties.

• XML Element = CheckBox
• Class Name = RibbonCheckBoxItem
• Event Types
  • Identical to LargeButton (see above)

Item (menu item in app's Recent menu)

Item's in app's Recent menu must use Type="2". That item type is prohibited anywhere else in the ribbon.

• XML Element = Item Type="2"
• Class Name = RibbonMenuItem
• Event Types
  • Clicked = event ue_RecentBoardEmployees( long al_handle, long al_index )
  • Selected = event ue_HoverRecentItem( long al_handle, al_index )
• Parameters
  • al_handle = Refers to ribbon's ApplicationButton.
  • al_index = Refers to menu item in the Recent menu.

Item (menu item in app's Master menu)

Item's in app's Master menu must use Type="0" (normal menu items) or Type="1" (separator lines). Separator lines seldomly bind to events.
Items appear either directly in the Master menu's dropdown or in cascading menus for items in the dropdown.

• XML Element = Item
• Class Name = RibbonMenuItem
• Event Types
  • Clicked = event ue_AppAbout( long al_handle, long al_index, long al_subindex )
  • Clicked = event ue_Close( long al_handle, long al_index, long al_subindex )
  • Selected = event ue_ItemSelected( long al_handle, al_index, long al_subindex )
• Parameters
  • al_handle = Refers to ribbon's ApplicationButton.
  • al_index = Refers to menu item in the Master menu.
  • al_subindex = Refers to menu item in the cascading menu.
    NOTE: About item in cascading menu has al_subindex > 0.
    NOTE: Close item without cascading menu has al_subindex = 0.

Item (menu item in other button menus)

Both LargeButton, SmallButton, and TabButton can contain a dropdown menu with optional cascading menus.
Menu items in button menus are similar to menu items in app's Master menu.

• XML Element = Item
• Class Name = RibbonMenuItem
• Event Types
  •  Identical to Item in app's Master menu (see above)
• Parameters
  • al_handle = Refers to button containing the menu.
  • al_index = Refers to menu item in button's dropdown menu.
  • al_subindex = Refers to menu item in the cascading menu.
    NOTE: Item in cascading menu has al_subindex > 0.
    NOTE: Item without cascading menu has al_subindex = 0.

ComboBox

ComboBox can have a dropdown list associated. Item in that list are ComboBox items.´They are different from menu items.
ComboBox itself has different set of event types that the other events.

• XML Element = ComboBox
• Class Name = RibbonComboBoxItem
• Event Types
  • Selected = event ue_ComboSelected( long al_handle )
  • Modified = event ue_ModifiedPaperSize( long al_handle )
  • SelectionChanged = event ue_StandardPaperSize( long al_handle, al_index )
• Parameters
  • al_handle = Refers to the ComboBox.
  • al_index = Refers to item in the combo dropdown.

SelectionChanged happens before Modified when both are defined and user selects an item from the dropdown.
Modified happens without SelectionChanged when user enters data directly in the edit box.

Outro

You cannot assign handle numbers to individual items. They are created at runtime like TreeView's item handles and RowID values in DataWindow objects.

An alternate approach is to assign a unique Tag value to each ribbon item and use GetItemByTag.
Function below adds new paper sizes to the ComboBox of paper size from example above.
It also widens the combo's dropdown list in case longer labels are added to the dropdown.

//  Function of_AddPaperSize(as_name, al_pictureID)
//    1)  Adds item to combo's list
//    2)  Widens combo width to fit longer text
//    3)  Adds VScrollBar
// ---------------------------------------------------
constant long   BOXWIDTH = 600
long   extraWidth
RibbonComboBoxItem   combo

ribbon_demo.GetItemByTag("print.pagesize", ref combo)

combo.InsertItem(as_name, al_pictureID, 1)

extraWidth = BOXWIDTH - combo.BoxWidth
combo.Width += extraWidth
combo.BoxWidth += extraWidth
combo.VScrollBar = true

// Update the RibbonBar
ribbon_demo.SetItem(combo)

Good luck starting out with the new RibbonBar control and its event processing!