DHTMLX Docs & Samples Explorer

Index
dhtmlxtoolbar

## Items Settings Manipulations

### Iterator

Method forEachItem() calls a user-defined function for every existing item in the toolbar passing item's id into it. Using iterator can be very useful in case the user wants all the items to be subjects for the same changes.

        <script>
            toolbar.forEachItem(function(itemId){});
            // or
            function doWithItem(itemId){
                // code here
            }
            toolbar.forEachItem(doWithItem);
        </script>

For example, let's write the code that will be responsible for disabling all toolbar items:

          <script>
               toolbar.forEachItem(function(id){
                    toolbar.disableItem(id);
               });
          </script>

Method forEachListOption() calls a user-defined function for every listed option of a certain Select Button in the toolbar passing listed option's id into it.

          <script>
              toolbar.forEachListOption(itemId, function(listOptionId){});
              // or
              function doWithListOption(listOptionId){
                  // code here
              }
              toolbar.forEachListOption(itemId, doWithListOption);
          </script>

### Applied to Any Item

The following methods can be applied to any item in the toolbar:

- setPosition() - sets item's new position;
- getPosition() - gets current item's position;
- getType() - gets item's type by item's id.

        <script>
            toolbar.setPosition(itemId, pos);
            var position = toolbar.getPosition(itemId); // returns current item's position
            var itemType = toolbar.getType(itemId); // returns item's type
        </script>

### Button

#### Showing/Hiding Button

To hide/show any button the user should pass button's id to the following methods:

        <script>
            toolbar.showItem(id);
            toolbar.hideItem(id);
        </script>

The user has the possibility to check whether any button is visible. The method returns true if the button is visible:

        <script>
            var isVisible = toolbar.isVisible(id); // returns true|false
        </script>

#### Enabling/Disabling Button

Any button in the toolbar can be enabled/disabled by user:

        <script>
            toolbar.enableItem(id);
            toolbar.disableItem(id);
        </script>

Also the user has the possibility to check whether any button is enabled. This can be done by calling the following method:

        <script>
            var isEnabled = toolbar.isEnabled(id); // returns true|false
        </scrip>

The user should pass id of the button that will be checked. The method returns true if the button is enabled, and false if it's disabled.

#### Setting Button's Text

The user can set any button's text/label. This button's id and text of button's label are passed as parameters to the following method:

        <script>
            toolbar.setItemText(id, text);
        </script>

The user can get button's text using getItemText() method. The method returns the current title text of the button:

        <script>
            var text = toolbar.getItemText(id); // returns current item's text
        </script>

#### Setting Button's Image

Any button in the toolbar can have its own image displayed in the button display area. setItemImage() and setItemImageDis() methods allow user to set image to a button by passing the following parameters:

- id - id of the button;
- url - path to the image for the enabled/disabled state of the button.

        <script>
            toolbar.setItemImage(id, url);
            toolbar.setItemImageDis(id, url);
        </scrip>

Button's image whether for the enabled or the disabled state can be easily removed/cleared by means of clearItemImage() and clearItemImageDis() methods to which the user should pass button's id:

        <script>
            toolbar.clearItemImage(id);
            toolbar.clearItemImageDis(id);
        </script>

#### Setting Buttons's Tooltip

The user can specify the supplementary information regarding any button in the toolbar. setItemToolTip() method takes the following parameters:

- id - button id;
- tip - this parameter sets the title that appears when user hovers the mouse over the button.

        <script>
            toolbar.setItemToolTip(id, tip);
        </script>

The following method can return the current button's tooltip text:

        <script>
            var tip = toolbar.getItemToolTip(id); // returns current button's tooltip text
        </script>

### Select Button

The following methods that are available for the Button item, can be applied to the Select Button item as well:

- toolbar.showItem(id);
- toolbar.hideItem(id);
- toolbar.isVisible(id);

- toolbar.enableItem(id);
- toolbar.disableItem(id);
- toolbar.isEnabled(id);

- toolbar.setItemText(id, text);
- toolbar.getItemText(id);

- toolbar.setItemImage(id, url);
- toolbar.setItemImageDis(id, url);
- toolbar.clearItemImage(id);
- toolbar.clearItemImageDis(id);

- toolbar.setItemToolTip(id, tip);
- toolbar.getItemToolTip(id);

All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.

#### Setting Select Button Width

A simple method is used to set this item's width:

        <script>
            toolbar.setWidth(id, width);
        </script>

The parameters are:

- id - item's id;
- width - the value of item's new width.

#### Adding/Removing Listed Option

A new Listed Option can be added using addListOption() method that accepts the following parameters:

- parentId - id of the parent item;
- id - id of the new item that will be added;
- pos - position of the new item;
- type - item's type can be “button” or “separator”;
- text - item's label;
- img - path to item's image.

        <script>
            toolbar.addListOption(parentId, id, pos, type, text, img);
        </script>

Any Listed Option can be easily removed by calling the following method:

        <script>
            toolbar.removeListOption(parentId,id);
        </script>

#### Showing/Hiding Listed Option

Any of the Listed Options can be shown/hidden if one of the following methods is applied to it:

        <script>
            toolbar.showListOption(parentId, id);
            toolbar.hideListOption(parentId, id);
        </script>

The user has the possibility to check whether any Listed Option is visible. The method returns true if the item is visible:

        <script>
            var isVisible = toolbar.isListOptionVisible(parentId, id); // returns true|false
        </script>

#### Enabling/Disabling Listed Option

Any Listed Option in the toolbar can be enabled/disabled by user:

        <script>
            toolbar.enableListOption(parentId, id);
            toolbar.disableListOption(parentId, id);
        </script>

Also the user has the possibility to check whether any Listed Option is enabled. This can be done by calling the following method:

        <script>
            var isEnabled = toolbar.isListOptionEnabled(parentId, id); // returns true|false
        </script>

The user should pass parentId and id of the Listed Option that will be checked. The method returns true if the Listed Option is enabled.

#### Setting Listed Option's Position (moving)

The following methods can be used to set new position for a Listed Option and to get the current position of it:

        <script>
            toolbar.setListOptionPosition(parentId, id, pos);
            var pos = toolbar.getListOptionPosition(parentId, id);
        </script>

#### Setting Listed Option's Text

The user can set any Listed Option's title. This item's parentId, id and title's text are passed as parameters to the following method:

        <script>
            toolbar.setListOptionText(parentId, id, text);
        </script>

The user can get Listed Option's title using getListOptionText() method. The method returns the current title text of the item:

        <script>
            var text = toolbar.getListOptionText(parentId, id); // returns current listed option's title text
        </script>

#### Setting Listed Option's Image

A Listed Option in the toolbar can have its own image displayed in the left part of item's display area. setListOptionImage() method allows the user to set image to a Listed Option by passing the following parameters:

- parentId - id of the parent item;
- id - id of the listed option;
- url - path to the image for the listed option.

        <script>
            toolbar.setListOptionImage(parentId, id, img);
        </script>

Path to current listed option image can be got like this:

        <script>
            var listOptionImage = toolbar.getListOptionImage(parentId, id); // returns path to the current listed option image
        </script>

Listed Option's image can be easily removed/cleared by means of clearListOptionImage() method to which the user should pass item's parentId and id as parameters:

        <script>
            toolbar.clearListOptionImage(parentId, id);
        </script>

#### Setting Listed Option's Tooltip

The user can specify the supplementary information regarding any Listed Option in the toolbar. setListOptionToolTip() method takes the following parameters:

- parentId - listed option's parent id;
- id - id of the listed option;
- tip - this parameter sets the title that appears when the user hovers the mouse over the listed option.

        <script>
            toolbar.setListOptionToolTip(parentId, id, tip);
        </scri>

The following method can return the current Listed Option's tooltip text:

        <script>
            var tip = toolbar.getListOptionToolTip(parentId, id); // returns current listed option's tooltip text
        </scri>

#### Selecting Listed Option

The user can make any listed option selected by default from script. On startup, when the user first opens the list of options, this chosen listed option will be highlighted (selected). The method setListOptionSelected() takes the following parameters:

- parentId - listed option's parent id;
- id - id of the listed option.

        <script>
            toolbar.setListOptionSelected(parentId, id);
        </script>

This method doesn't make the listed option selected forever. Another listed option can be easily selected by user from page.

There is also the possibility to get the id of the current selected listed option by method getListOptionSelected():

        <script>
            var listOptionId = toolbar.getListOptionSelected(parentId); //returns id of the selected listed option
        </script>

The parameter the user should pass to this method is id of the Select Button, which listed option's id the user wants to get.

#### Get All Listed Options

Method getAllListOptions() allows the user to get all listed options ids of a certain Select Button. The only one parameter that the user should pass is the id of the chosen Select Button:

        <script>
            var allListOptions = toolbar.getAllListOptions(parentId); // returns array of all listed options ids
        <script>

### Two-State Button

The following methods that are available for the Button item, can be applied to the Two-State Button item as well:

- toolbar.showItem(id);
- toolbar.hideItem(id);
- toolbar.isVisible(id);

- toolbar.enableItem(id);
- toolbar.disableItem(id);
- toolbar.isEnabled(id);

- toolbar.setItemText(id, text);
- toolbar.getItemText(id);

- toolbar.setItemImage(id, url);
- toolbar.setItemImageDis(id, url);
- toolbar.clearItemImage(id);
- toolbar.clearItemImageDis(id);

- toolbar.setTooltip(id,tip);
- toolbar.getItemToolTip(id).

All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.

#### Setting Two-State Button State

The user can set one of two states for the Two-State Button with the help of the following method:

        <script>
            toolbar.setItemState(id, state, callEvent);
        </script>

The parameters for this method are the following:

- id - id of the two-state button;
- state - true|false, true stands for the Pressed state of the button, false stadns for the Released state of the button;
- callEvent - if set to true, calls user defined handler for onStateChange event (if there is any).

There is also the possibility to get current item's state by calling getItemState() method:

        <script>
            var isPressed = toolbar.getItemState(id); // returns true|false
        </script>

The method returns true in case the button is pressed, and false in case the button is released.

### Text Item

The following methods that are available for the Button item, can be applied to the Text Item as well:

- toolbar.showItem(id);
- toolbar.hideItem(id);
- toolbar.isVisible(id);

- toolbar.setItemText(id, text);
- toolbar.getItemText(id).

All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.

### Separator

The following methods that are available for the Button item, can be applied to the Separator as well:

- toolbar.showItem(id);
- toolbar.hideItem(id);
- toolbar.isVisible(id).

All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.

### Slider

The following methods that are available for the Button item, can be applied to the Slider as well:

- toolbar.showItem(id);
- toolbar.hideItem(id);
- toolbar.isVisible(id);

- toolbar.enableItem(id);
- toolbar.disableItem(id);
- toolbar.isEnabled(id).

All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.

#### Setting Slider's Tooltip Template

Toltip template is applied only to Slider. The tooltip template can be represented in three ways:

- Like a static text, for example, “Hello”;
- Like a changeable text when the user moves the slider thumb. ”%v” part should be added to the tooltip template to make the template changeable;
- Like both the above mentioned ways.

setItemToolTipTemplate() method is used to set the tooltip template:

          <script>
              toolbar.setItemToolTipTemplate(id, template);
          </script>

This method takes the following parameters:

- id - item id;
- template - tooltip template text itself.

For example, if the user wants his tooltip to show the text like this: “Current Value is:” plus the changeable text showing slider's values when the thumb is moved, the code must be the following:

        <script>
            toolbar.setItemToolTipTemplate("slider","Current Value is:+%v");
        </script>

The following method can return current slider's tooltip template:

        <script>
            var template = toolbar.getItemToolTipTemplate(id); // returns current slider's tooltip text
        </script>

#### Setting Slider's Value

The user can set the Slider to a certain value within the range of available values with the help of the following method:

        <script>
            toolbar.setValue(id,value,callEvent);
        </script>

The parameters are as follows:

- id - id of the item;
- value - the new value;
- callEvent - true|false, if set to true, calls onValueChange event.

Note: If the user has indicated the value that is not within the range of available values, the slider's thumb will be set either to the minimum or to the maximum value.

Slider's current value can be easily got by the following method:

        <script>
            var value = toolbar.getValue(id); // returns slider's current value
        </script>

#### Setting Slider's Minimum Value

There is a method to set slider's minimum value:

        <script>
            toolbar.setMinValue(id, value, label);
        </script>

The following parameters should be passed to this method:

- id - item id;
- value - minimum value;
- label - text displayed to the left of the slider (in case of horizontal slider display) or below the slider (in case of vertical slider display).

Note: if the user wants the slider's minimum value to be created text-free, it's necessary to write an empty string as label parameter. For example:

        <script>
            toolbar.setMinValue("slider", 25, "");
        </script>

Slider's current minimum value can be got using getMinValue() method:

        <script>
            var data = toolbar.getMinValue(id); // returns slider's current minimum value
        </script>

This method returns the following Array(value, label).

#### Setting Slider's Maximum Value

There is a method to set slider's maximum value:

        <script>
            toolbar.setMaxValue(id,value,label);
        </script>

The following parameters should be passed to this method:

- id - item id;
- value - maximum value;;
- label - text displayed to the right of the slider (in case of horizontal slider display) or above the slider (in case of vertical slider display).

Note: if the user wants the slider's maximum value to be created text-free, it's necessary to write an empty string as label parameter. For example:

        <script>
            toolbar.setMaxValue("slider", 25, "");
        </script>

Slider's current maximum value can be got using getMaxValue() method:

        <script>
            var data = toolbar.getMaxValue(id); // returns current maximum value
        </script>

This method returns the following Array(value, label).

### Input Item

The following methods that are available for the Button item, can be applied to the Input Item as well:

- toolbar.showItem(id);
- toolbar.hideItem(id);
- toolbar.isVisible(id);

- toolbar.enableItem(id);
- toolbar.disableItem(id);
- toolbar.isEnabled(id);

- toolbar.setItemToolTip(id, tip);
- toolbar.getItemToolTip(id).

All the parameters of the above mentioned methods are the same to those described in Button Settings Manipulations section.

The following methods that are available for the Slider item, can be applied to the Input Item as well:

- toolbar.setValue(id, value); the value parameter is the default text displayed in the Input item
- toolbar.getValue(id).

All the parameters of the above mentioned methods are the same to those described in Slider Settings Manipulations section. There's one more method applied to Select Button that can be applied to the Input Item as well:

- toolbar.setWidth(id, width);

All the parameters of the above mentioned method are the same to those described in Setting Select Button Width section.

#### Getting Input's Width

The current input's width can be got with the help of getWidth() method:

        <script>
            var width = toolbar.getWidth(id); // returns current input's width
        </script>