title: Putting it on a menu
author: tiglari

So now that we've got some code that does something,
we need to install a menu item so the user can have it done:
<code>
quarkpy.mapcommands.items.append(qmenu.item("&Do Nothing", TagSideClick))
</code>
On important point is that the text of this line has to start at
the same horizontal position as the `def' line above, so that
the whole thing looks like this:
<code>
def tagSideClick (m):
    quarkx.msgbox("This command does nothing", MT_INFORMATION, MB_OK)
</code>
<code>
quarkpy.mapcommands.items.append(quarkpy.qmenu.item("&Do Nothing", tagSideClick))
</code>
rather than say like this:
<code>
def tagSideClick (m):
    quarkx.msgbox("This command does nothing", MT_INFORMATION, MB_OK)
</code>
<code>
    quarkpy.mapcommands.items.append(qmenu.item("&Do Nothing", tagSideClick))
</code>
The reason is that Python uses indendation to impose block-structure,
so that the first version first defines the TagSideClick function
and then puts an item on the mapcommands menu, while the second
version defines a TagSideClick function that first produces a
message-box and then adds something to the menu (so that something
will never show up unless the TagSideClick function gets called,
which isn't going to happen).
The blank line on other hand is just make the presentation clearer,
and doesn't affect the operation of the program.

And it remains to explain what this menu-item-adding line actually
does.  quarky.mapcommands is the module where the `commands'
menu is defined.  It creates a list-valued variable `items',
and `append' is a built-in Python function for attaching
something to a list.

What we append to this list is an something created by the
`item' function, defined in the module quarkpy.qmenu.  We don't
have to import this module because that job is already done by
the qeditor.py module.  This has among its import statements:
<code>
import qmenu
</code>
So when we import everything from quarkpy.maputils, and it
imports everything from quarkpy.qeditor, we wind up getting
qmenu, but we have to qualify the stuff in it with `qmenu'.
This lets us use obvious words like `item', without having
to use clumsy prefixing conventions, etc. to prevent name
collisions.

So when this is all typed out and saved into a file `maptagside.py' in
in the plugins directory, you should be able to start up QuArK, fire
up the map editor, find the `Do Nothing' command on the command menu,
click on it, and see the resulting message box.

If it doesn't work, possible explanations are:
<UL>
<LI> A syntax error in the program, in which case you'll be looking
at the QuArK console, which will have some kind of error message.
<LI> Your module-file's name doesn't start with `map', in which case
QuArK will work but your new command won't appear on the menu.
<LI> Something else, tell me when you manage to figure out it.
</UL>

If all else fails, the file <tt>maptagside0.py</tt> in
<a href="zips">plugin_examples.zip</a>
contains what is hopefully a working version of the code for this
section.

I'll also say a bit more about what goes on when modules are loaded.
When a module is loaded, it is first `compiled' into a file with the
same name and extension .pyc, which will load more quickly.  If
the current .py file is older than the corresponding .pyc file,
the compilation stage is skipped, and the .pyc file is loaded
straight in.  So you can delete all the .pyc files if you want to,
but it will slow things down the first time QuArK is run.
