openclonk/docs/sdk/script/fn/AddMenuItem.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE funcs
  SYSTEM '../../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../../clonk.xsl"?>
<funcs>
  <func>
    <title>AddMenuItem</title>
    <category>Objects</category>
    <subcat>Menu</subcat>
    <version>5.1 OC</version>
    <syntax>
      <rtype>int</rtype>
      <params>
        <param>
          <type>string</type>
          <name>caption</name>
          <desc>Text of the new menu entry</desc>
        </param>
        <param>
          <type>string</type>
          <name>command</name>
          <desc>Command to be executed when the menu item is selected. This can be either a function name or a statement. If a function name is given then the function will be called in the object which was given as command_object to <funclink>CreateMenu</funclink>.</desc>
        </param>
        <param>
          <type>id</type>
          <name>symbol</name>
          <desc>The ID is used as a picture for the menu item. The name of the definition can be used in caption using %s. Also the ID is passed as the first parameter to the call to command in case it is a function name.</desc>
        </param>
        <param>
          <type>int</type>
          <name>count</name>
          <desc>Numeric value to be displayed next to the menu entry (such as counts and amounts).</desc>
        </param>
        <param>
          <type>any</type>
          <name>parameter</name>
          <desc>Second parameter to the function specified in command (see remark).</desc>
        </param>
        <param>
          <type>string</type>
          <name>info_caption</name>
          <desc>Description text of the new menu entry.</desc>
        </param>
        <param>
          <type>int</type>
          <name>extra</name>
          <desc>Extra parameter for special behaviour of the menu entry.<br/> Lower 7 bits (0-127): menu symbol.<br/> 0: normal<br/> 1: rank symbol. With symbol specified, the Rank.png component of that definition will be used. count indicates the rank<br/> 2: picture facet, shifted to the right by XPar1 times the facet width. This is used to include multiple menu symbols in a single definition.<br/> 3: XPar1 specifies an object to be drawn with the rank symbol. If the object has no info section (and thus no rank), there will be an empty entry in context menus.<br/> 4: XPar1 specifies an object to be drawn.<br/> 7: XPar1 is a prop list that contains parameters for the menu symbol drawing. See picture parameter of <funclink>CustomMessage</funclink> for possible members. Bit 8 (128): XPar2 is used as object value and overrides the normal object value. Also see extra in <funclink>CreateMenu</funclink></desc>
          <optional />
        </param>
        <param>
          <type>any</type>
          <name>XPar1</name>
          <desc>First additional parameter for extra.</desc>
          <optional />
        </param>
        <param>
          <type>any</type>
          <name>XPar2</name>
          <desc>Second additional parameter for extra.</desc>
          <optional />
        </param>
      </params>
    </syntax>
    <desc>Adds a menu entry.</desc>
    <remark>Custom menu symbols should best have square aspect ratio.</remark>
    <remark>If a function name is specified for command, the following parameters are passed: <code>symbol, parameter, bRight[, value]</code> with bRight indicating whether the menu entry was selected with [Special2] or the right mouse button. value is passed only if bit 8 is set in extra and specifies the displayed (overridden) object value of the menu entry.</remark>
    <examples>
      <example>
        <code>
func ControlUse()
{
	// Create local menu with local commandos
	CreateMenu(GetID());
	// Create menu items
	AddMenuItem(&quot;Say hello&quot;, &quot;SayHello&quot;);
	AddMenuItem(&quot;Do magic&quot;, &quot;DoMagic&quot;);
	AddMenuItem(&quot;Create an object: %s&quot;, &quot;CreateItem&quot;, Rock);
	AddMenuItem(&quot;Create another object: %s&quot;, &quot;CreateItem&quot;, Firestone);
}

func SayHello()
{
	Message(&quot;Hello&quot;,this);
}

func DoMagic()
{
	Sound(&quot;Magic*&quot;);
}

func CreateItem(id item)
{
	CreateContents(item);
}</code>
        <text>Menu for a special item.</text>
      </example>
    </examples>
    <related>
      <funclink>CreateMenu</funclink>
      <funclink>SelectMenuItem</funclink>
      <funclink>CloseMenu</funclink>
    </related>
  </func>
  <author>jwk</author><date>2002-04</date>
</funcs>