RibbonBar control

Objects and Controls
System Object Properties, Events, and Functions

A RibbonBar control enables you to create ribbons that organize user commands into logical groups. A ribbon is a modern way of organizing user commands in user interfaces. A ribbon can replace the traditional menu bar and toolbars with tabbed pages (called Category); and each Category splits into Panels that contain LargeButton (with or without RibbonMenu), SmallButton (with or without RibbonMenu), CheckBox, ComboBox, and Spin (currently unsupported). For more about these ribbon items, see the section called “Introduction to RibbonBar items” in Users Guide.

The RibbonBar control is the container and the parent object for the ribbon item controls. For the hierarchical structure of the ribbon controls and how to get and set them, refer to the section called “Accessing the RibbonBar items via PowerScripts” in Users Guide.

For how to create a RibbonBar control and adding ribbon items (Category, Panel, GroupBox, Button, Menu etc) using a tool, refer to the section called “Creating a RibbonBar using RibbonBar Builder” in Users Guide.

For how to create a RibbonBar control and adding/removing ribbon items using PowerScript functions (like InsertCategory/DeleteCategory, InsertPanel/DeletePanel, InsertLargeButton/DeleteLargeButton etc.), refer to the code examples provided in the RibbonBar demo application.

For how to display an MDI menu as a ribbon bar without needing to make any code changes, refer to the section called “Displaying an MDI menu as a ribbon bar” in Users Guide.

Properties

RibbonBar property	Datatype	Description
AccessibleDescription	String	A description of the control and/or its purpose for use by accessibility tools such as readers for visually impaired users.
AccessibleName	String	A label that briefly describes the control, such as the text in a button or the name of a menu item.
AccessibleRole	AccessibleRole (enumerated)	Describes what kind of user interface element the control is.
AutosizeHeight	Boolean	Specifies whether the RibbonBar control automatically adjusts its height. Values are: TRUE -- Height is automatically adjusted according to the content. The Height property (no matter specified in the painter or in the scripts) will be ignored. FALSE -- Height is determined by the Height property (specified in the painter or in the scripts).
BringToTop	Boolean	Specifies whether PowerBuilder moves the control to the top of the front-to-back order in the window. Values are: TRUE -- Control moved to top. FALSE -- Control not moved to top.
BuiltinTheme	Integer	Specifies the theme of the RibbonBar control. If the application is set with a theme, then the theme selected for the application will take effect and this BuiltinTheme property will be ignored.
ClassDefinition	PowerObject	An object of type PowerObject containing information about the class definition of the object or control.
DragAuto	Boolean	Specifies whether PowerBuilder puts the control automatically into Drag mode. Values are: TRUE -- When the control is clicked, the control is automatically in Drag mode. FALSE -- When the control is clicked, the control is not automatically in Drag mode. You have to manually put the control into Drag mode by using the Drag function.
DragIcon	String	Specifies the name of the stock icon or the file containing the icon you want to display when the user drags the control (the ICO file). The default icon is a box the size of the control. When the user drags the control, the icon displays when the control is over an area in which the control can be dropped (a valid drop area). When the control is over an area that is not a valid drop area, the No-Drop icon displays.
Enabled	Boolean	Specifies whether the control is enabled (can be selected). Values are: TRUE -- Control is enabled. FALSE -- Control is not enabled.
FaceName	String	Specifies the name of the typeface in which the text of the control displays (for example, Helv or Courier).
FontCharSet	FontCharSet (enumerated)	Specifies the font character set used for the text in the control. For a complete list of possible values, see the list of properties for the FontCharSet variable on the Enumerated tab page of the Browser.
FontFamily	FontFamily (enumerated)	Specifies the font family (type style) used for the text in the control. Values are: AnyFont! Decorative! Modern! Roman! Script! Swiss!
FontPitch	FontPitch (enumerated)	Specifies the pitch (spacing) of the font used for the text in the control. Values are: Default! Fixed! Variable!
Height	Integer	Specifies the height of the control, in PowerBuilder units.
HidePanelText	Boolean	Specifies the text of all ribbon panels to be invisible. (Default is FALSE.)
HideTabHeader	Boolean	Specifies the tab header area to be invisible.(Default is FALSE.) The tab header area includes the application button title, the category title, and the tab header on the same horizontal level. If RibbonBar is minimized (which means only the application button title, the category title, and the tab header are visible), this property cannot be set to TRUE.
Italic	Boolean	Specifies whether the text in the control is italic. Values are: TRUE -- Text is italic. FALSE -- Text is not italic.
Pointer	String	Specifies the name of the stock pointer or the file containing the pointer used for the control.
RightToLeft	Boolean	Unsupported.
ShowQuickAccessToolbar	Boolean	Specifies whether to show the QuickAccessToolbar in the ribbon bar after the toolbar is converted to QuickAccessToolbar. Note This property is valid only when the QuickAccessToolbar is converted from the menu toolbar (when DisplayMenuAsRibbonBar is enabled). The standalone RibbonBar control does not support this property.
TabOrder	Integer	This property is currently unsupported for the RibbonBar control. The RibbonBar control cannot receive focus when the user tabs among controls within a window.
Tag	String	Specifies the tag value assigned to the control.
TextSize	Integer	Specifies the size of the text in the control, in points. For backward compatibility, the size is stored as a negative number; for example, 10-point text size is stored as -10.
Transparency	Integer	Specifies the transparency of the control. Value is a percentage in the range 0 (opaque) to 100 (completely transparent).
Underline	Boolean	Specifies whether the text in the control is underlined. Values are: TRUE -- Text is underlined. FALSE -- Text is not underlined.
Visible	Boolean	Specifies whether the control is visible. Values are: TRUE -- Control is visible. FALSE -- Control is not visible.
Weight	Integer	Specifies the stroke weight of the text in the control; for example, 400 for normal or 700 for bold.
Width	Integer	Specifies the width of the control, in PowerBuilder units.
X	Integer	Specifies the X position (the distance from the left edge of the window), in PowerBuilder units.
Y	Integer	Specifies the Y position (the distance from the top of the window), in PowerBuilder units.

Events

RibbonBar event	Occurs
CategoryCollapsed	Occurs when the category is collapsed. When the RibbonBar is minimized, the category will be expanded when the user clicks the category title, and will be collapsed when the user clicks the title again or clicks outside of the category.
CategoryExpanded	Occurs when the category is expanded. When the RibbonBar is minimized, the category will be expanded when the user clicks the category title.
CategorySelectionChanged	After the selection changes to another category and when the category is created and the initial selection is established.
CategorySelectionChanging	When another category is about to be selected.
Constructor	Immediately before the Open event occurs in the window.
Destructor	Immediately after the Close event occurs in the window.
DragDrop	When a dragged control is dropped on the control
DragEnter	When a dragged control enters the control
DragLeave	When a dragged control leaves the control
DragWithin	When a dragged control is within the control
Help	When the user presses the F1 key or drags the context help button (question mark) from the title bar to a menu item or control
ItemUnselected	When an item changes from highlights to the other state.
Other	When a Windows message occurs that is not a PowerBuilder event
RButtonDown	When the right mouse button is pressed on the control
Resize	When the user or a script opens or resizes a window.

Functions

RibbonBar function	Datatype returned	Description
ClassName	String	Returns the name assigned to the control.
DeleteCategory	Integer	Removes a category from the RibbonBar control.
DeleteCheckBox	Integer	Removes a check box from the panel or group of the RibbonBar control.
DeleteComboBox	Integer	Removes a combo box from the panel or group of the RibbonBar control.
DeleteGroup	Integer	Removes a group from the panel of the RibbonBar control.
DeleteItem	Integer	Removes an item from the RibbonBar control.
DeleteLargeButton	Integer	Removes a large button from the panel of the RibbonBar control.
DeletePanel	Integer	Removes a panel from the category of the RibbonBar control.
DeleteSmallButton	Integer	Removes a small button from the panel or group of the RibbonBar control.
DeleteTabButton	Integer	Removes a tab button from the RibbonBar control.
Drag	Integer	Starts or ends dragging of the control.
ExportJSON	String	Saves the ribbon bar to a JSON string.
ExportXML	String	Saves the ribbon bar to an XML string.
ExportToJSONFile	Integer	Saves the ribbon bar to a JSON file.
ExportToXMLFile	Integer	Saves the ribbon bar to an XML file.
GetActiveCategory	Integer	Gets the active category in the RibbonBar control.
GetApplicationButton	Integer	Gets the application button in the RibbonBar control.
GetBestHeight	Integer	Gets the height of the RibbonBar control which is automatically adjusted according to the content (when AutosizeHeight is enabled).
GetCategory	Integer	Gets the category in the RibbonBar control.
GetCategoryByIndex	Integer	Gets the category according to its index in the RibbonBar control.
GetCategoryCount	Long	Determines the total number of categories in the RibbonBar control.
GetCategoryIndex	Long	Gets the index of the category in the RibbonBar control.
GetCheckBox	Integer	Gets the check box in the RibbonBar control.
GetChildItemByIndex	Integer	Gets the child item according to its index in the RibbonBar control.
GetChildItemCount	Long	Determines the total number of items in a parent (Category, Panel, or Group) of the RiboonBar control.
GetComboBox	Integer	Gets the combo box in the RibbonBar control.
GetContextService	Integer	Creates a reference to a context-specific instance of the specified service.
GetGroup	Integer	Gets the group in the RibbonBar control.
GetItem	Integer	Gets an item according to the handle.
GetItemByTag	Integer	Gets an item according to the tag.
GetItemParent	Integer	Gets the parent of the item.
GetLargeButton	Integer	Gets the large button in the RibbonBar control.
GetMenuByButtonHandle	Integer	Gets the menu associated with the button in the RibbonBar control.
GetPanel	Integer	Gets the panel in the category of the RibbonBar control.
GetParent	PowerObject	Returns a reference to the name of the parent object.
GetSmallButton	Integer	Gets the small button in the RibbonBar control.
GetTabButton	Long	Gets the tab button in the RibbonBar control.
GetTabButtonByIndex	Integer	Gets the tab button according to its index in the RibbonBar control.
GetTabButtonCount	Long	Determines the total number of tab buttons in the RibbonBar control.
Hide	Integer	Makes the control invisible.
ImportJSON	Integer	Loads the ribbon bar from a JSON string.
ImportXML	Integer	Loads the ribbon bar from an XML string.
ImportFromJSONFile	Integer	Loads the ribbon bar from a JSON file.
ImportFromXMLFile	Integer	Loads the ribbon bar from an XML file.
InsertCategory	Long	Inserts a category in the RibbonBar control.
InsertCategoryFirst	Long	Inserts a category as the first item in the RibbonBar control.
InsertCategoryLast	Long	Inserts a category as the last item in the RibbonBar control.
InsertCheckBox	Long	Inserts a check box in the panel or group of the RibbonBar control.
InsertCheckBoxFirst	Long	Inserts a check box as the first item in the panel or group of the RibbonBar control.
InsertCheckBoxLast	Long	Inserts a check box as the last item in the panel or group of the RibbonBar control.
InsertComboBox	Long	Inserts a combo box in the panel or group of the RibbonBar control.
InsertComboBoxFirst	Long	Inserts a combo box as the first item in the panel or group of the RibbonBar control.
InsertComboBoxLast	Long	Inserts a combo box as the last item in the panel or group of the RibbonBar control.
InsertGroup	Long	Inserts a group in the panel of the RibbonBar control.
InsertGroupFirst	Long	Inserts a group as the first item in the panel.
InsertGroupLast	Long	Inserts a group as the last item in the panel.
InsertLargeButton	Long	Inserts a large button in the panel of the RibbonBar control.
InsertLargeButtonFirst	Long	Inserts a large button as the first item in the panel of the RibbonBar control.
InsertLargeButtonLast	Long	Inserts a large button as the last item in the panel of the RibbonBar control.
InsertPanel	Long	Inserts a panel in the category of the RibbonBar control.
InsertPanelFirst	Long	Inserts a panel as the first item in the category of the RibbonBar control.
InsertPanelLast	Long	Inserts a panel as the last item in the category of the RibbonBar control.
InsertSmallButton	Long	Inserts a small button in the panel or group of the RibbonBar control.
InsertSmallButtonFirst	Long	Inserts a small button as the first item in the panel or group of the RibbonBar control.
InsertSmallButtonLast	Long	Inserts a small button as the last item in the panel or group of the RibbonBar control.
InsertTabButton	Long	Inserts a tab button in the RibbonBar control.
InsertTabButtonFirst	Long	Inserts a tab button as the first item in the RibbonBar control.
InsertTabButtonLast	Long	Inserts a tab button as the last item in the RibbonBar control.
IsMinimized	Boolean	Gets whether the RibbonBar control is minimized or not.
Move	Integer	Moves the control to a specified location.
PointerX	Integer	Returns the distance of the pointer from the left edge of the control.
PointerY	Integer	Returns the distance of the pointer from the top of the control.
PostEvent	Boolean	Adds the specified event to the end of the event queue for the specified object
Print	Integer	Prints the contents of the control. You can specify a range of pages and other settings.
RemoveApplicationButton	Integer	Removes the application button from the RibbonBar control.
ReplaceCategoryByJSON	Integer	Replaces an existing category with the category from a JSON file.
ReplaceCategoryByXML	Integer	Replaces an existing category with the category from an XML file.
Resize	Integer	Changes the size of the control.
SetActiveCategory	Integer	Sets the active category in the RibbonBar control.
SetActiveCategoryByIndex	Integer	Sets the active category according to its index in the RibbonBar control.
SetApplicationButton	Integer	Sets the application button for the RibbonBar control.
SetCategory	Integer	Sets the category for the RibbonBar control.
SetCheckBox	Integer	Sets the check box for the RibbonBar control.
SetComboBox	Integer	Sets the combo box for the RibbonBar control.
SetFocus	Integer	Sets focus to the control.
SetGroup	Integer	Sets the group for the RibbonBar control.
SetItem	Integer	Sets an item for the RibbonBar control.
SetLargeButton	Integer	Sets the large button for the RibbonBar control.
SetMinimized	Long	Sets the RibbonBar control to be minimized. When the RibbonBar control is minimized, only the application button title, the category title, and the tab header will be displayed. If the HideTabHeader property is set to TRUE (which means the application button title, category title, and the tab header are invisible), this function will not take effect.
SetPanel	Integer	Sets the panel for the RibbonBar control.
SetPosition	Integer	Specifies the front-to-back position of the RibbonBar control in the window.
SetRedraw	Integer	Controls automatic redrawing of the control.
SetSmallButton	Integer	Sets the small button for the RibbonBar control.
SetTabButton	Integer	Sets the tab button for the RibbonBar control.
Show	Integer	Makes the control visible.
TriggerEvent	Integer	Triggers a specified event in the control and executes the script for the event.
TypeOf	Object	Returns the type of the control.

Prev	Up	Next
ResultSet object	Home	RibbonApplicationButtonItem control

Objects and ControlsSystem Object Properties, Events, and Functions