WARNING: The information on this documentation will change as the development on this version of DHTML Menu Builder progresses.
It is VERY important that you always refer to the information provided in this document prior to testing new versions of the DynAPI code.

void dmbAPI_setBuffering(State)

Description

This function modifies the way DynAPI creates new commands.
By default, the buffering state will be "off". To turn it on call the function passing "true" as a parameter.

When buffering is turned on, the creation of new commands is buffered allowing your code to finish without having to wait for the DynAPI to add all the commands. This can considerably increase the speed at which your code is executed allowing the HTML document to load faster.

Buffered commands will be added to their groups when needed, that is "rendering on demand"; this means that when the user selects a menu item that displays a group whose commands have been buffered the group will be rendered and then displayed.

Although buffering can provide a truly remarkable improvement in the rendering phase of the menus (up to a 55% speed increase) one should be careful with its use.
You must remember that some functions, such as dmbAPI_getItemByCaption and dmbAPI_setGroupWidth, will fail if called before a command has actually been created. Other functions, such as dmbAPI_setOnMouseOver or dmbAPI_setFont, will be able to force the commands of a buffered group to be created before the function is executed.

If you're not sure if your code will be compatible with this option, try enabling right after calling the dmbAPI_Init() function. If you receive javascript errors about missing or undefined variables then your code is trying to access menu items that are buffered and haven't been created yet.

Also, you can turn buffering on and off as you add commands. For example, you could enable buffering at the beginning of your code and then somewhere in your code disable it and re-enable it somewhere else.
This will allow you to control which commands you want to buffer.

Take a look at the following samples to see all the modes in which you can use the buffering feature:

Code sample

dmbAPI_Init(); dmbAPI_setBuffering(true);

This is the recommended method to enable buffering.

---

Code sample

dmbAPI_setBuffering(false);

There's no need to turn buffering off but if it is turned off any buffered commands will be rendered immediately.

Code sample

dmbAPI_setBuffering(false); dmbAPI_addCommand("grp001", "My Command 01"); dmbAPI_setBuffering(true); dmbAPI_addCommand("grp001", "My Command 02");

In this sample you can see how you can selectively enable and disable buffering for specific commands. In this case, the command "My Command 01" will not be buffered and will be added to the "grp001" group immediately. Then, the "My Command 02" will be buffered and will become available inside the "grp001" group when the group is displayed.

---

Code sample

_bg(_getobj("MyGroup"));

This sample demonstrates how to render the buffered commands of a group whose name is MyGroup.

Parameters

State (boolean)

The state can either be true or false. By default, buffering is always turned off. Set it to true to enable buffering or set it to false to disable buffering and render any buffered commands.