AddExtraLook()
==============

AddExtraLook()
varargs int AddExtraLook(string look, [int duration, string key,
                         string lookende, object ob]);
--------------------------------------------------------------------------------------------------------------------------------------
::

DEFINIERT IN
------------
::

   /std/living/description.c

BESCHREIBUNG
------------
::

   Der Extralook erscheint in der Langbeschreibung des Lebewesens.
   Eintraege koennen mit dieser Funktion hinzugefuegt werden. Dies ist der
   bevorzugte Weg, wenn ansonsten extra ein Objekt im Spielerinventar abgelegt
   werden muesste.

   

   Alle Parameter bis auf <look> sind optional.

ARGUMENTE
---------
::

  - string look:
    String, der in der Langbeschreibung des Lebewesens zusaetzlich ausgegeben
    wird.
    Kann auch ein Funktionsname sein, wenn <ob> angegeben wird (s.u.).
  - int duration:
    > 0: Wie lang bleibt der Extralook gueltig (in Sekunden)? Anschliessend 
         wird er automatisch geloescht.
    0:   Dieser Eintrag bleibt unbegrenzt gueltig.
    < 0: Dieser Eintrag bleibt bis zum Ende/Reboot bestehen.
  - string key:
    Schluesselwort, unter dem der Eintrag registriert wird und mit dem man ihn
    auch mittels RemoveExtraLook() entfernen kann. Sollte natuerlich
    moeglichst eindeutig sein. ;-) Wenn <key> nicht angeben wird, wird der 
    Objektname (object_name()) benutzt.
  - string lookende:
    String, der an das Lebewesen (nur bei Spielern) ausgegeben wird, wenn der
    eingetragene Extralook abgelaufen ist.
    Kann auch ein Funktionsname sein, wenn <ob> angegeben wird.
  - object ob:
    Wenn hier ein Objekt angegeben wird, werden <look> und <lookende> als
    Funktonsnamen aufgefasst. Diese Funktionen werden in <ob> aufgerufen, wenn
    der Extralook des Lebewesen angezeigt wird bzw. der eingetragene Extralook
    abgelaufen ist. Diese Funktionen bekommen das jeweilige Lebenwesen als
    Objekt uebergeben. Sie muessen einen String zurueckliefern, der ausgegeben
    wird. Dieser String wird direkt so ausgeben, also selber fuer Zeilenumbruch
    etc. sorgen!
    WICHTIG: Das Objekt sollte nach Moeglichkeit eine Blueprint sein, da das
    ganze nix mehr ausgibt, sobald der Clone zerstoert wird, falls hier 
    einer angeben wird. Wenn ihr keine BP uebergebt: Wisst, was ihr tut. ;-)

RUECKGABEWERTE
--------------
::

  > 0, falls der Eintrag erfolgreich registriert wurde.
  < 0 sonst.
    -1: <key> war nicht gueltig und es konnte keiner ermittelt werden.
    -2: <look> war kein gueltiger String.
    -3: <duration> war kein Integer.
    -4: unter <key> gibt es schon einen Eintrag.

BEMERKUNGEN
-----------
::

  Die Strings <look> und <lookende> werden vor Ausgabe durch
  replace_personal() geschickt, daher ist die Verwendung von @WER1, @WESSEN1
  usw. moeglich (s. replace_personal). Dies gilt aber _nicht_ fuer den Fall,
  dass die entsprechenden Funktionen in <ob> gerufen werden, dann muessen die
  Funktionen selber umbrechen, etc.
  Nach replace_personal() werden die Strings noch von break_string() auf 78
  Zeilen umgebrochen, allerdings bleiben dabei vorhandene Umbrueche erhalten.
  Die Meldung von <lookende> bzw. der Funktionsaufruf erfolgt, wenn der
  Extralook der Lebewesen das erste Mal nach Ablauf der Gueltigkeit aufgerufen
  wird.

BEISPIELE
---------
::

  # einfacher Eintrag, "fuer die Ewigkeit"
  living->AddExtraLook("@WER1 hat den Drachengott der SSP besiegt.");

  # Eintrag der nach 1h automatisch weg ist.
  living->AddExtraLook("@WER1 ist ganz mit Marmelade bedeckt.", 3600);

  

  # Eintrag mit bestimmten Schluessel, damit man ihn wieder entfernen kann.
  living->AddExtraLook("@WER1 ist ganz mit Marmelade bedeckt.", 3600,
                       "humni_marmeladen_look");

  

  # Mit "Ende"-Meldung, aber kein eigener Schluessel.
  living->AddExtraLook("@WER1 ist patschnass.", 1200, 0,
                       "Du bist endlich wieder trocken. Puuh.");

  

  # Mit Objekt, was den Extralook dynamisch erzeugt
  living->AddExtraLook("get_my_special_extralook", 3600, 0, 0, this_object());
    In diesem Fall muss this_object() natuerlich die Funktion
    "get_my_special_extralook()" definieren, die einen String zurueckgibt.

  # Mit Objekt, was den Extralook und die Endemeldung dynamisch erzeugt
  living->AddExtraLook("get_my_special_extralook", 3600, 0,
                       "extralookende", this_object());

SIEHE AUCH
----------
::

   RemoveExtraLook(),
   replace_personal(), break_string()
   P_INTERNAL_EXTRA_LOOK

14.05.2007, Zesstra