RibbonBar control

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 in the hierarchy” in Users Guide.

For how to create a RibbonBar control using a tool, refer to the section called “Creating a RibbonBar using RibbonBar Builder” in Users Guide.

Note

This control cannot be referenced in .NET Web Service or .NET Assembly components, otherwise the component will fail to be deployed.

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.

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

Integer

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.

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.