-------------------------------------------------------
MainMenu library/server/replicant 1.0
for BeOS AA:PR (June 27th 1997)

Copyright © 1997 Olivier Wittenberg
All Rights Reserved.
-------------------------------------------------------
Please view this file with StyledEdit.
-------------------------------------------------------

1- INTRODUCTION

This package consists of:
    - MMServer: the main menu server
    - MMenu.lib: the static library to link
      against in order to be a client
    - MMTest: a sample application that uses
      the library, with sources

It is intended to let the user decide if he wants
the main menu to be integrated in the windows, or
exported to a common place.

Applications that use the library don't depend on
anything: if the server is running, the menu will
be exported, and it's up to the user to run the
server or not.

The library is static, but very small: this means
that if you are not a developer, if you don't plan
to write a program that would communicate with the
server, you may trash the library, it will work
all the same.


2- HOW TO USE IT ?

First, remember that only programs that have
specifically been written for this server will
work with it; in other words, currently, most apps
won't export their menu, despite the fact the
server is running.

The first step is to move the MMServer file to
"/boot/apps/". I hope I'll remove this limitation
soon, but I have to find a workaround for a bug
in BeOS.

To use it, simply launch MMServer. When an app
wants to export its main menu, the server will open
a tiny 16x16 window, with the icon of the active
app inside (given the active app works with this
server). If you click on the icon, the app's main
menu will pop up.

The icon is a replicant, which means that
you can drag it into any replicator (to do so, select
"show draggers" in the Be/system menu).

You can drag it to the desktop, but the best place
I've found is the Deskbar (just beside the clock).
You may create several replicated icons. A warning,
though: a replicated icon doesn't work if the server
is not running. Once the replicant is created, it's
no use launching the server: it must be running
before the replicator.

The reason why this is so is that the server does
communicate with the replicants. They are not
standalone views (that would be impossible).

This has a bad consequence: if you drag the icon to
the Deskbar, it won't work if you reboot since the
Deskbar is loaded before anything else. I hope I'll
fix that soon, programmatically; in the meanwhile,
the only solution is to edit a do-not-edit file:
"/boot/system/Bootscript". I've done it, it works fine
here, but I'm not responsible if you make a mistake
(pay special attention to the path !).

Here's the modification; find these lines:
#
# Start the Tracker
#

Then, before these comments, add this line:
/boot/apps/MMServer &

Now it should work.
Once you have replicated the icon, you probably
don't want the server to open a window. To do so,
launch MMServer with one argument "nowindow", like:
/boot/apps/MMServer nowindow &


3- HOW TO PROGRAM WITH THE LIB ?

First: add MMenu.lib to your project. :-)
This library brings one class: WMainMenu.
You have the header in the same directory as the lib.

It's pretty straight forward: take a look at the sample
app (MMTest). The behaviour should always be:
- try to export the main menu
- if failed, add it to the windows

The sample app shows how to do it: there are one or
two things that you might want to steal from the sources
(especially the conversion from BPopUpMenu to BMenu).
It also shows what you should do after the constructor,
i.e. tell the server when your app is activated.

All the communications between your app and the server
are encapsulated in the lib, you don't have to worry about
them (and there are also comms between the server and the
replicants :-).

I haven't solved the problem of apps without icon, yet.
Currently it displays a white square instead of the icon;
for test purposes, I've included with MMTest two ugly
(very ugly) 2D icons with MMTest: App1.rsrc and App2.rsrc.
Just "copyres App1.rsrc Application" before use.


4- THAT'S ALL :)

Thanks to those who will use the lib; thanks to Be for
having given the idea of an exported main menu. ;)

Don't hesitate to contact me at "witt@lenet.fr", to report
bugs, send comments and ideas, or just to say hello.

If you want to put this package on a CD, or if you want
to use the library in a commercial/shareware application,
please inform me.

Enjoy ! And don't forget that I am not responsible for
any damage, BeBox fire, fried hard disk, wasted time,
loss of data, loss of money, loss of brain or whatever.

--Olivier Wittenberg, witt@lenet.fr