Users Guide
Working with RibbonBar

The new RibbonBar control allows you to organize the navigation of your application in a simple, structured way, and gives the application the look and feel of modern applications. Because RibbonBar is provided in PowerBuilder as a control while Menu is a system object, the way that a RibbonBar works in an application is different from the application menu. This tutorial uses a demo application to walk you through the steps of replacing an application menu with a RibbonBar.

The figure below shows what the menu looks like in the original demo application.

The figure below shows what the RibbonBar control looks like after you use it to replace the menu in the application.

This tutorial contains the following sections:

Step 1: Install PowerBuilder 2022 R2.

Step 2: Download the RibbonBar demo application from here.

Step 3: Set up the sample database.

As the first step, you shall design the RibbonBar, that is, deciding what items to contain in the RibbonBar, what modern-looking image to use for each item, and how to group the items, etc.

Once you know clearly how you want the RibbonBar to look like, you can start to create it. We recommend you use the RibbonBar Builder tool to create the RibbonBar XML/JSON file. Alternatively, you can choose to directly create a RibbonBar via PowerScript.

For PowerScript functions that can be used to create a RibbonBar, refer to PowerBuilder Help > RibbonBar control. In the demo application, for better illustration purpose, you will see both the XML file and PowerScript code are provided for creating the RibbonBar. When the application initiates the RibbonBar, it uses an argument in the wf_init_ribbonbar function to decide which way (XML or PowerScript) to use for creating the RibbonBar (see Initiate the RibbonBar).

Creating the XML for the RibbonBar in this demo (Recommended):

A dedicated tool, RibbonBar Builder, is available in PowerBuilder to assist you to create the RibbonBar XML (or JSON). In the tool, you can use a template (RibbonBar.xml) to create your own XML, and preview the RibbonBar UI while you work. This is the recommended approach.

In the demo application:

Creating the PowerScript for the RibbonBar in this demo:

In the demo application:

In the Design and create a RibbonBar section, we create the RibbonBar for the application in two ways: by XML/JSON or by PowerScript. We can initiate the RibbonBar created in either way.

The ribbon item controls have no events, you should define a number of user events accordingly, move the scripts from the original menu events to the user events, and then bind the user events with the corresponding ribbon item control.

The ribbon item controls support the following user events:

When defining a user event for the ribbon control, make sure the argument (quantities and types) of the event is properly defined according to the requirement of the ribbon control. If the number of arguments or the argument type does not match with the requirement of the ribbon control, the event will not be triggered.

For example, in the demo application, we want to create and bind the clicked user event with the Order View large button. The RibbonLargeButtonItem control requires that the clicked user event have a long-type argument and return no value. Therefore, in the rbb_1 RibbonBar control, we create an event with its name as ue_orderview, argument name as al_handle, argument type as long, and the following script:

// ue_orderview (long al_handle) returns (none)
opensheet (w_order_viewer, parent, 0, Original!)

And then we bind the ue_orderview user event with the clicked event of the Order View large button using this script:

arbb.InsertLargeButtonFirst (ll_Itemhandle_Panel, wf_SetLargetButtonItem_Pro ("Order View", "OrderView", ".\picture\orderview.png", "ue_orderview", True, "", "", "ctrl+shift+O"))

You can also bind the ue_orderview user event with the clicked event of the Order View large button using the XML file:

...
   <LargeButton Text="Order View" Tag="OrderView" PictureName=".\picture\orderview.png" Clicked="ue_orderview" Shortcut="ctrl+shift+O" />
...

Different ribbon controls require different arguments and types for the user event. For details, see the corresponding user events:

Clicked in PowerScript Reference

Selected in PowerScript Reference

Modified in PowerScript Reference

SelectionChanged in PowerScript Reference

Previously the application functions are all associated with menu items. You need to decide which function to associate with which RibbonBar item now. In the demo application, you can see clearly how a function that is previously associated with a menu item is now associated with a RibbonBar item. In this tutorial, let’s explain two examples.

str_rptparm lstr_parm

lstr_parm.ftitle = 'Sales Report by Order Type'
lstr_parm.fdataobject = ""
opensheetWithParm (w_rpt_order_type, lstr_parm, parentwindow, 0, Original!)

str_rptparm lstr_parm

lstr_parm.ftitle = 'Sales Report by Order Type'
lstr_parm.fdataobject = ""
opensheetWithParm (w_rpt_order_type, lstr_parm, parent, 0, Original!)

iw_tmp = w_rpt_order_type
wf_setstyle("2D BarStacked")

ParentWindow.Dynamic Event ue_Settings(This.Tag)
If This.Checked Then Return
This.Checked = True
m_item2.Checked = False
m_item3.Checked = False
m_item4.Checked = False
m_item5.Checked = False

ribbonsmallbuttonitem lrs_item
this.getsmallbutton (al_handle, lrs_item)
string ls_tag
ls_tag = lrs_item.tag
if isvalid (iw_tmp) then
 iw_tmp.dynamic event ue_Settings(lrs_item.tag)
end if

parentwindow().post dynamic event ue_closesheet(this.classname())

parentwindow().post dynamic event ue_closesheet(this.classname())
if isvalid(w_mdi) then
 w_mdi.post function wf_refresh_ribbon()
end if
parentwindow().post function Arrangesheets(Layer!)