<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">

<doc>

  <title>Macros in Menus</title>

  <p>
  KLayout allows installing macros as menu entries. Each time that menu entry is selected, 
  the macro will be executed.
  To configure a macro for installation in the menu, open the macro in the macro development environment 
  and open the macro properties dialog. 
  </p>

  <p>
  The macro is configured to be shown in the menu by checking the "Show in menu" check box.
  That also enables two other fields: the menu path and the group name.
  </p>

  <p>
  The menu path specifies the position where the macro shall be put. A macro path is a 
  sequence of symbolic names separated by a dot. For example:
  </p>
  
  <ul>
    <li><tt>edit_menu.end</tt> is the end of the "Edit" menu </li>
    <li><tt>edit_menu.undo</tt> is the "Undo" entry in the "Edit" menu</li>
  </ul>
  
  <p>To obtain
  a list of the paths available, have a look at the "Key Bindings" page in the "Application"
  section of the setup dialog ("File/Setup").
  </p>
  
  <p>
  The pseudo element "end" denotes the position
  after the last entry. The same way "begin" indicates the first entry in the menu.
  The macro will be inserted before the entry indicated by the path. Hence:
  </p>

  <ul>
    <li><tt>edit_menu.end</tt>: the macro will be inserted at the end of the "Edit" menu</li>
    <li><tt>edit_menu.undo</tt>: the macro will be inserted before the "Undo" entry.</li>
  </ul>
  
  <p>
  If a plus sign follows the macro path element, the new element is inserted <b>after</b>
  this element. For example:
  </p>
  
  <ul>
    <li><tt>edit_menu.undo+</tt>: the macro will be inserted after the "Undo" menu item.</li>
  </ul>

  <p>
  A special form can be used to generate new groups: if the given element does not exist,
  the menu generator can be instructed to create it by appending the insert point plus
  the new text string to the element after a ">" character. For example:
  </p>
  
  <ul>
    <li><tt>edit_menu.my_group>end("My Edit Functions").end</tt>: will look for "my_group" and add the new element at the end of this group. If no such
  group exists, it will be created at the end of the "Edit" menu with the title "My Edit Functions".</li>
  </ul>

  <p>
  If no macro path is specified, the macro is inserted in the "Macros" menu.
  The description of the macro is used as the menu title. If a shortcut is specified, that
  shortcut is used for the macro entry as well.
  </p>

  <p>
  The group name can be used to group together all menu entries with the same group name.
  Any text is allowed here.
  A group is separated from the other entries in the menu by a separator line. It is recommended to
  use the group feature in conjunction with a "end"-terminated menu path which is identical
  for all entries of the same group. Other uses cases are possible, but the result is 
  not defined. 
  </p>

  <h2>A Note for MacOS Users</h2>

  <p>
  The Qt/MacOS combination does not allow for dynamically configuring 
  the main menu. On MacOS the behavior is as follows:
  </p>

  <p>
  Every top-level menu entry that is generated either by code or by configuring
  a macro correspondingly, will be shown in a separate entry in the main toolbar.
  This entry is labelled "..." and is shown only when it is populated. All
  non-standard main menu entries are placed there in the same order they would
  appear in the main menu.
  </p>

</doc>

