Work with Ribbon

Set and get values and states

Use the setState() method to change the value of a control or the state of a twoState button. The method takes one parameter: an object with key-value pairs, where the key is the ID of a control and the value is its new value or state.

The following code sets the state of a twoState button:

{ type:"button", twoState:true, id:"check" }
...
ribbon.setState({"check":true});
ribbon.setState({"check":false});

Related sample: Ribbon. Set state

The following code changes the value of an input:

{ type:"input", id: "file_name" }
...
ribbon.setState({"file_name":"My file"});

Use the getState() method to get the current values and states of controls.

The method returns the following object for a twoState button:

{ type:"button", twoState:true, id:"check" }
...
ribbon.getState();
// { check:true }
// or
// { check:false }

Related sample: Ribbon. Get state

The method returns the following object for an input:

{ type:"input", id:"file_name", value:"My file" }
...
ribbon.getState();

// {"file_name":"My file"}

Show and hide controls

The show() and hide() methods show and hide controls by their IDs. Pass the ID of a control or an array of IDs to the methods:

ribbon.hide("add_btn");
ribbon.show(["save_btn","del_btn"]);

Related sample: Ribbon. Show/hide Ribbon item

Starting from v7.0, you can call the methods without parameters to hide or show all Ribbon controls at once:

// hides all Ribbon controls
ribbon.hide();
// shows all Ribbon controls
ribbon.show();

Enable and disable controls

The enable() and disable() methods enable and disable controls by their IDs. Pass the ID of a control or an array of IDs to the methods:

ribbon.disable("add_btn");
ribbon.enable(["save_btn","del_btn"]);

Related sample: Ribbon. Enable / disable Ribbon item

Starting from v7.0, you can call the methods without parameters to disable or enable all Ribbon controls at once:

// disables all Ribbon controls
ribbon.disable();
// enables all Ribbon controls
ribbon.enable();

Check if a Ribbon item is disabled

The isDisabled() method checks whether a Ribbon item is disabled. The method takes one parameter:

id	(string | number) the ID of an item

ribbon.isDisabled("1"); // -> true/false

Related sample: Ribbon. Enable / disable Ribbon item

Select and unselect an item

Select a Ribbon item

The select() method of Ribbon selects a particular item. The method takes two parameters:

id	(string | number) the ID of an item
unselect	(boolean) optional, true to unselect previously selected items, otherwise false (default: true)

ribbon.select("print");

Related sample: Ribbon. Select / unselect

Unselect a Ribbon item

The unselect() method of Ribbon removes selection from a selected item. The method takes the ID of an item as an optional parameter:

// unselects a specified selected item
ribbon.unselect("print");

Call the method without parameters to remove selection from all selected Ribbon items:

// unselects all previously selected items
ribbon.unselect();

Related sample: Ribbon. Select / unselect

Check if a Ribbon item is selected

The isSelected() method checks whether a Ribbon item is selected. The method takes one parameter:

id	(string | number) the ID of a Ribbon item

ribbon.isSelected("print"); // -> returns true/false

Related sample: Ribbon. Select / unselect

Get selected items

The getSelected() method returns an array with the IDs of selected items:

ribbon.getSelected(); // -> ["selected_1", "selected_1.1"]

Use the TreeCollection API

Add controls

Use the add() method of TreeCollection to add controls dynamically:

ribbon.data.add({
    type:"button",
    icon:"dxi-plus",
    value:"New"
},-1,"blockId");

Related sample: Ribbon. Add item

This is how you can add a block of controls:

ribbon.data.add({
    label:"File",
    type:"block",
    id:"files",
    direction:"row",
    items: [
        {
            icon: "dxi dxi-undo",
            size: "small",
            ribbonHeight: "double"
        },
        {
            icon: "dxi dxi-redo",
            size: "small",
            ribbonHeight: "double"
        }
    ]
});

Get controls by IDs

Use the getItem() method to get a Ribbon control by its ID:

const add_btn = ribbon.data.getItem("add_btn");

To get the ID of the parent of a control, call the getParent() method:

const parentId = ribbon.data.getParent("add_btn");

The getItems() method returns the children of a control:

const items = ribbon.data.getItems("block1");

The getLength() method of TreeCollection counts the children of a control:

ribbon.data.getLength("block1");

Iterate through controls

Use the forEach() method of TreeCollection to work with all (or some) Ribbon controls:

ribbon.data.forEach(function(item){
    // remove all icons
    item.icon = "";
});
ribbon.paint();

Iterate through children

The forEach() method can also iterate through all controls of a block. Pass the ID of the block as the second parameter:

ribbon.data.forEach(function(item){
    // remove all icons
    item.icon = "";
},"bl_1");
ribbon.paint();

To iterate only through the immediate children, pass 1 as the third parameter:

ribbon.data.forEach(function(item){
    // remove all icons
    item.icon = "";
}, "bl_1", 1);
ribbon.paint();

The eachChild() method of TreeCollection also iterates through the children of a control:

ribbon.data.eachChild("bl_1",function(item){
    // remove all icons
    item.icon = "";
});
ribbon.paint();

To iterate only through the immediate children, set the direct parameter to false:

ribbon.data.eachChild("bl_1", function(item){
    // remove all icons
    item.icon = "";
},false);
ribbon.paint();

To check whether an item has children, use the haveItems() method of TreeCollection:

ribbon.data.haveItems("block1");
// -> true

Iterate through parents

The eachParent() method of TreeCollection iterates through all parents of an item, from the immediate parent up to the ribbon itself:

ribbon.data.eachParent("new_btn",function(item){
    console.log(item)
});

Rearrange Ribbon controls

Use the move() method of TreeCollection to move Ribbon items to different positions. For example, the following code moves the block with the "bl_2" ID to the right edge of the ribbon:

ribbon.data.move("bl_2",-1);

note

The ID should always be a string, even if you set it as a number in the control configuration.

To get the current position of a block, use the getIndex() method of TreeCollection:

ribbon.data.getIndex("bl_2");

Copy controls

Use the copy() method of TreeCollection to add a copy of a control and place it at the specified position on the ribbon:

ribbon.data.copy("block1",2);

The following code copies a control into a block of the same ribbon:

ribbon.data.copy("save_btn",1,ribbon.data,"block2");

The following code copies a control into a block of another ribbon:

ribbon1.data.copy("save_btn",1,ribbon2.data,"block3");

Clear Ribbon

The removeAll() method of TreeCollection removes all controls from Ribbon. After that, you can load other controls:

ribbon.data.removeAll();
ribbon.data.parse(new_controls);