====== zmenu_InsertItem ======

===== Description =====

Add an item to the menu in L3DT. 

===== Files =====

^ Declaration | ''zmenu.h'' |
^ Implementation | ''zmenu.cpp'' |

===== Function prototype =====

<code="C++">
bool zmenu_InsertItem(const char* lpScript, const char* lpItemText, unsigned long MenuContext, unsigned long Flags);
</code>

===== Arguments =====

^  Name  ^  Type  ^ Comment ^
|  //lpFnName//  |  ''const char*''  | A pointer to a C-style string containing the ZeoScript script to be executed by this menu option when selected.  |
|  //lpOptionName//  |  ''const char*''  | A pointer to a C-style string containing the display name of the menu option.  |
|  //MenuContext//  |  ''unsigned long''  | An enumerated integer to indicate into which menu the item should be inserted. See comments for supported values. |
|  //Flags//  |  ''unsigned long''  | Reserved. Must be 0. |

===== Return value =====

False if an error occurred, and true otherwise. 

===== Comments =====

==== Use with zfunc_Load ====

The //lpFnName// argument must be the name of a function loaded from your plugin via the [[zeolite:functions:zfunc_Load]] method. See the example provided below.

==== Menu contents ====

By default, this function adds the menu item into the '//Extensions->[your plugin name]//' menu in L3DT. However, using the //MenuContext// argument, you may insert your item into other menus. The following values are recognised:

^ Defined constant ^  Value  ^ Menu ^
| ZMENU_CONTEXT_EXT_CUR |  0  | //Extensions->[extension name]// |
| ZMENU_CONTEXT_EXT_ROOT |  1  | //Extensions// |
| ZMENU_CONTEXT_FILE_IMPORT |  2  | //File->Import// |
| ZMENU_CONTEXT_FILE_EXPORT |  3  | //File->Export// |

==== Sub-menus ====

The '.' (dot) character is used to delimit nested submenus. Thus, if you provide an //lpOptionName// of "mysubmenu.myoption", your option will appear at '//Extensions->[your plugin name]->mysubmenu->myoption//' (assuming the default //MenuContext//). Unfortunately, this means you cannot use dots for abbreviations or ellipsis (e.g. 'about...')

===== Example =====

This is from the InitPlugin function of [[bundywiki>plugins:file:L3DTio_TorqueTER|L3DTio_TorqueTER]]:

<code>
// load the extension function
zfunc_Load("L3DTio_TorqueTER.T3D.MaterialManagerUI", "ExtT3DMtlManagerUI", VarID_void, NULL);

// load the menu item for the function
zmenu_InsertItem("T3D.MaterialManagerUI", "L3DTio_TorqueTER.Torque T3D.Material Manager", ZMENU_CONTEXT_FILE_EXPORT, 0);
</code>