Category: PowerBuilder
Hits: 3541

User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active

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.




Similar to LargeButton except for picture size.



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



Similar to LargeButton for user events albeit different properties.


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.


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.


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.



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.