Work with Ribbon

Setting/getting values and states

You can change the value or state (for a TwoState button) of a control with the help of the setState() method. It takes one parameter: a key-value pair with the ID of the control and its new value (state).

This is how you can set 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

And this is how you can change the value of an input:

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

To get the current value of the control, use the getState() method.

This is what the method returns for a TwoState button:

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

Related sample: Ribbon. Get State

And this is how you can get the current value of an input:

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

Hiding and showing controls

You can show or hide controls by their IDs. Pass them to the corresponding methods - show() and hide():

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

Disabling and enabling controls

You can disable or enable controls. The related methods - enable() and disable() - take the IDs of controls as parameters:

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

Checking if a Ribbon item is disabled

To check if an item of Ribbon is disabled, call the isDisabled() method. The method takes one parameter:

id - (string) an id of a menu item

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

Using Tree collection API

Adding controls

You can add controls dynamically with the add() method of TreeCollection.

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

Related sample: Ribbon. Add

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"
        }
    ]
});

Getting controls by IDs

You can get a particular Ribbon control by its ID via the getItem() method:

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

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

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

You can also access the children of a control with the getItems() method:

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

You can use the getLength() method of TreeCollection to count children of a control:

ribbon.data.getLength("block1");

Iterating through controls

You can work with all (or some) Ribbon controls with the help of the map() method of TreeCollection:

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

Iterating through children

To iterate through all controls in a particular block, pass one more parameter to map() - the ID of the block:

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

If you want to iterate only through immediate children, pass a third parameter - false:

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

Iterating through children is also can be done with the eachChild() method of TreeCollection:

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

To access only the immediate children, add the direct parameter and set it to false:

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

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

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

Iterating through parents

To iterate through all the parent items (the immediate parent and its parent, etc. until the parent is the ribbon itself), use the eachParent() method of TreeCollection:

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

Rearranging Ribbon controls

You can move Ribbon items to different positions with the move() method of TreeCollection. For example, this is how you can move a block with ID "bl_2" to the right edge of the Ribbon:

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

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

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

ribbon.data.getIndex("bl_2");

Making copies of controls

You can add a copy of a control and place it in the specified position on the ribbon with the copy() method of TreeCollection:

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

You can copy a control into a block of the same ribbon:

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

You can also copy a control and place it into another ribbon:

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

Clearing Ribbon

To remove all controls from Ribbon, users should call the removeAll() method of TreeCollection. Afterwards, you can load other items.

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