the do-it-yourself (DIY) approach
=================================
For those who don't like reading directions, start with the "cheat sheet" I
just posted to the list and pick an existing menu item which seems similar
to the one you want to add:
http://www.abisource.com/mailinglists/abiword-dev/99/March/0111.html
Then, grep through the source to find all the code which implements it, and
in each spot, clone and rename as needed. Alternatively, you could scroll
back through Bonsai and find the original checkin for that feature.
the connect-the-dots (CTD) approach
===================================
OK, here are some more specific hints.
First you need to create the action (or EditMethod) which gets fired when
the menu item is chosen. This happens by adding a function with a fixed
prototype to the static class in ap_EditMethods.cpp. Since everything you
need to do is confined to that one file, I'll assert that the DIY approach
should suffice for this step.
If you're in a real hurry, and you don't want to create an EditMethod for
your new "read my mind" feature yet, there is a "noop" method you can use.
However, it's a lot more useful to create your new method so that the
binding is in place, even if you have to stub out your implementation as
follows:
Defun1(readMyMind)
{
XAP_Frame * pFrame = (XAP_Frame *) pAV_View->getParentData();
UT_ASSERT(pFrame);
s_TellNotImplemented(pFrame, "Read my mind feature", __LINE__);
return UT_TRUE;
}
As for the menu code, it's driven by XP tables in the following five
abi/src/wp/ap/xp/ files:
1. ap_Menu_Id.h defines all MENU_IDs
2. ap_Menu_LabelSet_EnUS.h US English version of menu strings
3. ap_Menu_Layouts_MainMenu.h arranges MENU_IDs into main menu bar
4. ap_Menu_ActionSet.cpp binds each MENU_ID to behaviors
5. ap_Menu_Functions.cpp helper functions for some MENU_IDs
To add a new menu item, the first three steps are no-brainers:
1. Give it a unique MENU_ID,
2. define the user-visible labels for that MENU_ID, and
3. insert it at the right spot on some menu.
The final two steps aren't that much harder:
4. Add a table entry to bind that MENU_ID to an EditMethod by name. There
are a number of entries in the table which control a variety of menu
behaviors, such as:
- whether to check it or disable it, or
- whether it has a dynamic label, or
- whether it raises a dialog, and
- other stuff I forget right now
Once again, I'll assert that a DIY approach will get you through this step
just fine. The code is quite legible, and there are a number of examples to
model from.
5. This step is usually not required, since most menu items don't change
state dynamically. However, for those that do, you may need to add one or
two helper functions to specify that additional behavior. These also get
bound to a MENU_ID by name in step 4 above. Again, it's a small file, so
DIY from here.
There, now that wasn't so bad, was it? :-)
the official technical documentation approach
=============================================
TODO
Seriously, though. If someone would like to write this up more cleanly
without all my cavalier DIY references, and submit the resulting .abw
document, I'm sure we'd be happy to check it into the abi/docs portion of
the tree.
Paul