Menu.mod
            ==============


Dieses Modul vereinfacht das Erstellen von Menüs in eigenen Programmen.
Es untersützt KickStart 1.3 und 2.0, kann beliebige Zeichensätze (auch
proportionale) verarbeiten und kreiert bei zu kleinem Bildschirm oder
zu großem Zeichensatz bei Bedarf automatisch zweispaltige Menüs.


Benutzung:


  Um die von Menu.mod erzeugte Menüstruktur zu speichern, muß man sich
  zunächst eine Variable deklarieren:

    VAR
      menu: Intuition.MenuPtr;


  Nun muß zunächst ein Fenster geöffnet werden, das mit dem Menü versehen
  werden soll (es können später auch mehrere Fenster, die auf dem selben
  Screen geöffnet wurden, mit dem selben Menü gleichzeitig arbeiten).

    window := I.OpenWindow(...);


  Nun kann das Erzeugen des Menüs gestartet werden:

    Menu.StartMenu(window);


  Nun werden nacheinander die Menüstreifen festgelegt. Dazu ruft man
  zunächst

    Menu.NewMenu("Project");

  auf. In diesem Fall ist das erste Menü das Project Menu.


  Jetzt werden nacheinander die Items erzeugt. Dazu gibt es verschiedene
  Möglichkeiten:


    Menu.NewItem("Open","O");

  Hier wird ein gewöhnliches Item mit dem Namen 'Open' under dem Keyboard-
  Shortcut Amiga+'O' erzeugt.


    Menu.NewItem("About",0X);

  So wird ein Item ohne Keyboard-Shortcut erzeugt.


    Menu.NewItem2("Quit","^Q");

  Dieser Aufruf erzeugt ein Item mit dem Namen 'Quit'. Rechtsbündig wird in
  diesem Menüpunkt zusätzlich '^Q' dargestellt. Dies ist gedacht für den
  Tastatur-Abkürzung Control+'Q'. Solche Abkürzungen werden von Intuition
  nicht automatisch verwaltet und müssen im eigenen Programm selbst 
  überprüft werden (siehe Test.mod).


    Menu.NewItemChecked("Save Icons","I",TRUE);

  Es wird ein Item wie mit NewItem() mit den Namen 'Save Icons' und der
  Abkürzung Amiga+'I' erzeugt. Auch hier kann statt "I" 0X angegeben werden,
  um keine Abkürzung zuzulassen. Zusätzlich bekommt dieses Item ein Häkchen
  (CheckMark). Der letzte Parameter gibt an, ob dieses Häkchen zu beginn
  gesetzt (TRUE) oder nicht gesetzt (FALSE) sein soll.


    Menu.NewItem2Checked("Auto Save all 10 minutes","^A",FALSE);

  Hier wird, ähnlich NewItem2() der Text "^A" rechtsbündig im Menü 
  dargestellt. Ansonsten erzeugt NewItem2Checked() das gleiche Menü wie 
  NewItemChecked().


    Menu.Seperator;

  Dieser Aufruf erzeugt eine horizontale Zick-Zack-Linie, mit der mehrere
  Menüpunkte Gruppiert werden können. Intern ist diese Linie ein deaktiviertes
  MenuItem, so daß für diese Linie eine Menünummer verbraucht wird (Das wird
  beim interpretieren von IntuiMessages vom Typ MenuPick wichtig, siehe
  Test.mod).


  Die letzten 5 Prozeduren können nun beliebig oft nacheinander aufgerufen
  werden. Danach können weitere Menüstreifen mit NewMenu() etc. nach dem
  gleichen Schema erzeugt werden.


  Das Erzeugen des Menüs wird mit

    menu := Menu.EndMenu();

  abgeschlossen.


  Um dieses Menü jetzt zu benutzen, wird es mit

    IF Intuition.SetMenuStrip(window,menu^) THEN ...

  an das Fenster gebunden.


  Eingaben über dieses Menü können wie gewohnt als IntuiMessages vom userPort
  des Fensters gelesen werden.

  Die Menünummern werden folgendermaßen verteilt:

    MenuNum: 1. Streifen: 0
             2. Streifen: 1
             3. Streifen: 2 etc.

    ItemNum: 1. Item: 0
             2. Item: 1
             3. Item: 3 etc.

    Zu beachten ist bei den Items, daß ein Seperator auch als Item zählt. So
    hat folgendes Menü folgende Nummern:

        Project        MenuNum  ItemNum
          Open   O       0        0
          Close  C       0        1
          --------
          Quit   Q       0        3


  Wird das Menü nicht mehr benötigt, kann es mit

    Intuition.ClearMenuStrip(window);
    Menu.DisposeMenu(menu);

  vom Fenster gelöst und der benötigte Speicher freigegeben werden. Dies ist
  jedoch gewöhnlich nicht nötig, da der Speicher bei Programmende automatisch
  freigegeben wird.


Speicher:

  Wie dem aufmerksamen Programmierer vielleicht aufgefallen ist, können die
  gesamten Prozeduren von Menu.mod nicht fehlschlagen und nirgends ist eine
  Abfrage nötig, ob z.B. genügend Speicher vorhanden war.

  Ist nicht genügend Speicher vorhanden, bricht Menu.mod einfach mit HALT(20)
  ab. Ist dies nicht gewünscht, kann man sich selbst einen Speichermangel-
  Handler schreiben, der z.B. folgendermaßen aussieht:


  Diese Prozedur kann natürlich bei bestimmten Anwendungen noch sehr viel
  Intelligenter gestaltet werden, so daß sie z.B. nicht unbedingt benötigten
  Speicher freigibt.

  Menu.mod muß nur noch mitgeteilt werden, daß diese Prozedur bei Speicher-
  mangel aufgerufen werden soll:

    Menu.oom := OutOfMem;

  Zu beachten ist, daß diese Prozedur auf jeden Fall eine Möglichkeit vorsehen
  sollte, daß Programm abzubrechen, da sich das Programm sonst bei Speicher-
  mangel in eine Endlosschleife verrent. Also NICHT:

    PROCEDURE * OutOfMem;
    BEGIN
      IF MyPtr#NIL THEN DISPOSE(MyPtr) END;
    END OutOfMem;

  sondern:

    PROCEDURE * OutOfMem;
    BEGIN
      IF MyPtr#NIL THEN DISPOSE(MyPtr) ELSE HALT(20) END;
    END OutOfMem;

  Bei diesem Beispiel wird beim ersten Aufruf von OutOfMem evtl. Speicher
  freigegeben. war dies jedoch nicht genugt, wird beim zweiten Aufruf das
  Programm abgebrochen.


Viel Spaß!


--- Fridtjof.