#1 [HowTo] Creating a Page and PagePack (2.4 | GERMAN) -> GroupInviteEngine Documentation by Bizzarrus 23.03.2013 21:26

avatar

Hi
Hier schonmal vorab eine Dokumentation zur API "GroupInvite-Engine" bzw ein HowTo zur Seitenerstellung sowie erstellung von PagePacks:

Inhaltsverzeichnis




Einführung


Seit Version 2.3 basiert GroupInvite auf der "GroupInvite-Engine", einer Addon API die extra für GroupInvite programmiert wurde. Diese API stellt neben zahlreichen Funktionen die Möglichkeit zur Verfügung, Addons als sogenannte "Seiten" in den von der API mitgelieferten Main-Frame einzubinden. Hierbei benötigen diese Seiten jedoch keine xml-Datei, sondern können mit Lua-Befehlen auf einfache und schnelle Weise ihren eigenen Frame zusammenbauen, wofür die API zahlreiche Vorlagen zur Verfügung stellt. Ebenso ist das Umblättern innerhalb dieser Seiten möglich, so dass eine Seite mehrere Frames besitzen kann(sollte der Platz für einen nicht ausreichen). Auch die Verarbeitung des Speicherns und Ladens, Tooltips, Beschriftungen, Sprache, etc wird von der API verwaltet und teilweise sogar nahezu komplett automatisiert, sofern man diese Automatisierung wünscht. Mit dem Überarbeiten der API in Version 2.4 wurde diese nicht nur stabiler, sondern bietet den Seiten auch die Möglichkeit, über einen unsichtbaren Chat mit anderen Addon-Nutzern zu kommunizieren. Auch an der Übersichtlichkeit der API wurde gearbeitet, sodass es den Programmierern der Seiten nun leichter fällt, die benötigten Funktionen zu finden. Für den Benutzer der API bietet diese außerdem die Möglichkeit, Seiten ingame zu laden oder zu löschen, ohne dass ein Spielneustart erforderlich wird. Hierbei werden diese Seiten nicht nur deaktiviert, sondern komplett aus dem Speicher gestrichen. Einzig die gespeicherten Variablen bleiben bis zum Spielneustart erhalten. Um dieses komplette löschen der Seiten möglich zu machen, werden alle Funktionen der Seite in eine lokale Table eingespeichert, die von der GroupInvite-Engine eingelesen wird.
Zur Übersichtlichkeit hier eine kleine Aufzählung, zu was die GroupInviteEngine fähig ist:
  • Speichern, Laden und Verarbeiten von Variablen nahezu vollkommen automatisch
  • Frames Ingame via Lua-Befehlen auf einfache Weise erstellbar(sowohl innerhalb des Main-Frames wie auch außerhalb)
  • (De-)aktivieren von Seiten ingame, ein Spielneustart ist nicht erforderlich
  • Aufbau von Listen mit bis zu 3 Spalten, welche nach belieben Alphabetisch sortierbar sind
  • Seiten mit Drag & Drop Systemen
  • Automatisch generiertes Baum-Menü, um zwischen den Seiten zu wechseln
  • Unsichtbare Kommunikationsmöglichkeit zwischen den Benutzern, wobei die Möglichkeit von dem Spieler deaktiviert werden kann
  • Vereinfachtes Hook-System, bei dem die Hook-Funktionen nur in Ausnahmefällen die Originale Funktion aufrufen müssen(in den meisten Fällen geschieht dies automatisch)
  • Automatische Verwaltung der Sprache und Sprachdateien sowie der Farben
  • Ingame veränderbares Layout der Frames
  • Zahlreiche zusätzliche Funktionen, die z.B. Zahlen mathematisch korrekt auf eine beliebige Menge an Nach-Komma-Stellen runden kann, den Namen des Gruppenleiters oder auch auswählbare Klassen zurückgiebt, usw.

Nach oben

Verwenden der Funktionen


Da die GroupInviteEngine entzwischen mehr als 130 API-Funktionen (plus zusätzliche Systemeigene Funktionen) besitzt, werde ich an dieser Stelle der Übersichtlichkeit wegen keine Referenz zu jeder dieser Funktionen geben. Stattdessen wird es nach Release der Version 2.4 eine "DefPage" geben, die den Entwicklern der Seiten eine komplette Referenz aller API-Funktionen bietet und zudem eigene Funktionen wie ein Debug-Nachrichten-System o.ä. beinhalten wird.

Da die Funktionen seit Version 2.4 nicht mehr Global gespeichert werden, hat sich das Aufrufen der Funktionen leicht gewandelt: Jede API- oder Seiten-Funktion ist nun mit der Funktion GroupInvite_Do aufrufbar. Diese Funktion gewehrleistet - neben dem Aufrufen der Funktionen - zudem die Sicherheit, dass es keinerlei Fehler bei nicht-vorhanden-sein der Funktion auftreten und das Aufrufen der Funktion im Falle, dass die Engine auf einen Fehler gelaufen ist oder deaktiviert wurde, abgebrochen wird. Das Arbeiten mit dieser Funktion ist im Grunde sehr einfach: Das erste Argument, das die Funktion wünscht, ist der Name des Herkunfsortes der Funktion, die du aufrufen willst. Willst du also z.B. eine API Funktion aufrufen, wäre das erste Argument "api", willst du hingegen die Funktion einer Seite aufrufen, wäre es der Name dieser Seite. Anschließend folgt - ebenfalls als String - der Name der aufzurufenden Funktion. Im Anschluss kannst du dann die Argumente an die Funktion durchgeben.

Als Beispiel stellen wir uns folgende Situation vor:
  • Die Seite "seite1" hat die Funktion "GetMyTable", die eine table-variable zurück gibt, wenn das erste Argument der Funktion true ist.
  • Die Seite "seite2" möchte die Anzahl an Objekten in dieser table-variable haben, egal ob es eine numerische table ist oder nicht

Die Umsetzung wäre dann wie folgt:

1
2
 
tab=GroupInvite_Do("seite1","GetMyTable",true)
anzahl=GroupInvite_Do("api","TableMaxn",tab)
 



Da die Funktion "GetMyTable" als erstes Arugment true erhalten hat, gibt diese nach der Beschreibung der Situation eine table-variable zurück. Die API-Funktion "TableMaxn" arbeitet mit 2 Argumenten: das erste ist die table, die gezählt werden soll. Das zweite, optionale Argument ist eine Boolean-Variable. Solange dieses zweite Argument nicht true ist, gibt die Funktion die Anzahl aller Objekte in der Table zurück, unabhängig davon, ob sie numerisch sind oder nicht. Wenn das zweite Argument true ist, gibt es die Anzahl an numerischen Objekten in der Table zurück, allerdings unabhängig von der Bezeichnung des Objektes an sich. Hierzu nochmal ein Beispiel:

tab1={14,7,true,"hust"}Dies ist eine numerische Table-Variable, d.h. tab1[1]=14, tab1[2]=7,usw
tab2={[7]=13,[5]=false,[12]=9,[10]="hust"}Diese Table-Variable enthällt ebenfalls nur Nummern als Bezeichner, jedoch ohne jedliche Ordnung
tab3={[8]=5,["test"]=12,[true]=false,[90]=14}Diese Table-Variabe enthällt zwar auch nummerische Bezeichner, aber auch Bezeichner anderer Typen wie String oder Boolean
tab4={["test"]="hust",[false]=7,[true]=9,[function() return true; end]=2}Diese Table-Variable enthällt nun keine nummerischen Bezeichner mehr


GroupInvite_Do("api","TableMaxn",tab1)=4GroupInvite_Do("api","TableMaxn",tab1,true)=4
tab1 ist eine reine Aufzählung, somit ist das zweite Argument oder überhaupt das Verwenden dieser Funktion anstelle von table.maxn eher sinnfrei
GroupInvite_Do("api","TableMaxn",tab2)=4GroupInvite_Do("api","TableMaxn",tab2,true)=4
tab2 ist keine Aufzählung mehr, aber es sind immer noch alles nummerische Bezeichner, also ist auch hier das zweite Arugment unnötig
GroupInvite_Do("api","TableMaxn",tab3)=4GroupInvite_Do("api","TableMaxn",tab3,true)=2
In tab3 sind nur zwei nummerische Bezeichner vorhanden, also wird die Funktion mit dem zweiten Argument nur diese beiden zählen
GroupInvite_Do("api","TableMaxn",tab4)=4GroupInvite_Do("api","TableMaxn",tab4,true)=0
In tab4 gibt es keine nummerischen Bezeichner, folglich gibt die Funktion mit dem zweiten Argument auch 0 an, während die ohne die gesammte Anzahl an Objekten zurück gibt, auch wenn deren Bezeichner Funktionen, Boolean-Variablen oder Strings sind

Nach oben

Seitenbasis


Eine Seite ist grob in 3 Bereiche einteilbar: Die Definition der Seiteninformationen, die Definition der Funktionen und die Registration der Seite, wobei die Definition der Funktionen verständlicher Weise den größten Teil einer Seite ausmacht.

  • Die Seiteninformationen
    Die Seiteninformationen werden in einer lokalen Table gespeichert, auf die innerhalb der Funktionen häufiger Zugegriffen wird. Darin enthalten sind beispielsweise Seitenname und -version. Bei der späteren Regestrierung der Seite wird außerdem eine automatisch generierte ID in die table hinzugefügt, die vorallem beim Handling der Frames von Bedeutung ist. Sowohl der Seitenname als auch die Seiten-ID sind eindeutig mit der Seite verknüpft, heißt es gibt keine zweite Seite gleichen Namens oder ID. Sollte der Name der Seite bereits vergeben sein, wird während der Regestrierung eine Zahl an den Seitennamen angehängt, um ihn so wie eindeutig zu machen. Daher ist es zu Empfehlen, die Funktionen der eigenen Seite immer mit GroupInvite_Do(page.name,...) auszuführen, anstatt den Namen direkt als String anzugeben.

    Meistens wird in diesem Bereich auch die lokalen Variablen der Seite geladen, sowie die default-table erstellt. Die default-table ist eine Art Modell der Speichervariablen, beim Starten von GroupInvite werden alle gespeicherten Variablen, die nicht zu diesem Modell passen, gelöscht, und alle die fehlen erstellt. Auf diese Weise wird sicher gestellt, dass es keine Fehler wegen fehlender Speicherdaten gibt. Trägt hierbei ein Wert/eine Table den Bezeichner "$__def", bedeutet dies, dass alle numerischen Variablen in der table, in der dieser Wert ist, als Modell diesen Wert haben. Ähnliches gillt für den Bezeichner "$__all", wobei dieser jedoch für ausnahmslos alle Variablen in der table zutrifft. Auf diese Weise lassen sich Modelle für Listen an gepseicherten Variablen erstellen, ohne dass man die genaue Anzahl kennt (bei der Blockliste z.B. sähe das dann so aus: ["Blocklist"]={["$__def"]="",} das bedeutet, dass alle numerischen Werte in der table "Blocklist" vom typ String sein werden. Trifft das auf einen numerischen Wert nicht zu, wird er "". Exestieren keine numerischen Werte, wird der erste numerische Wert mit dem Index 1 automatisch festgelegt. Diese automatische erstellung eines Wertes, sollte keiner exestieren, gibt es bei "$__all" nicht!). Die Werte $__all und $__def selbst werden NICHT in die gespeicherten Variablen mit aufgenommen!
    Zusätzlich zu $__all und $__def gibt es auchnoch den Begriff "$__inh" bzw "$__inh[n]", wobei [n] für eine beliebige Ganzzahl steht. Dieser Wert ist immer vom Typ String und gibt einen Pfad an, von dem der Inhalt kopiert werden soll. Bei den AutoAccept bzw AutoDecline listen sieht das dann z.B. so aus:
    • local default={
      • AAD = {
        • ["Accept"]={
          • ["Active"] =false,
          • ["Guild"] =false,
          • ["Friend"] =false,
          • ["Other"] ={["$__def"]="",},
          • ["All"] =false,

          },

        • ["Decline"]={
          • ["$__inh"]="AAD.Accept",

          },

        },

      }

    was dem hier entspricht:
    • local default={
      • AAD = {
        • ["Accept"]={
          • ["Active"] =false,
          • ["Guild"] =false,
          • ["Friend"] =false,
          • ["Other"] ={["$__def"]="",},
          • ["All"] =false,

          },

        • ["Decline"]={
          • ["Active"] =false,
          • ["Guild"] =false,
          • ["Friend"] =false,
          • ["Other"] ={["$__def"]="",},
          • ["All"] =false,

          },

        },

      }

    In dem Pfad werden unterschiedliche Bezeichner stets und aussschließlich mit . getrennt, der Pfad bezieht sich jeweils auf die default-table. Die verwendung von "$__inh[n]" erlaubt zudem, von mehreren Quellen die Variablen zu kopieren, z.B. ["$__inh1"]="AAD.Accept.Other.$__def", ["$__inh2"]="AAD.Decline.Active" . Das letztliche Resultat ist eine Ersparnis der Schreibarbeit sowie der Sicherstellung, dass zwei tabels genau das gleiche Modell besitzen, was z.B. Schreibfehler ausschließt. Ähnlich wie $__def und $__all werden auch die $__inh bzw $__inh[n] Werte an sich nicht in das Modell mit aufgenommen.

  • Die Seitenfunktionen
    Die Funktionen einer Seite werden ebenfalls in einer Table gespeichert. Diese beinhaltet außerdem zusätzlich den Wert "ClickModes", welcher als String angibt, welche Arten an Click-Modes von der Seite wahrgenommen werden. Ist der Wert nicht vorhanden oder der String leer, wird nur der Click-Mode "CLICK" wahrgenommen, ansonsten nur die in dem String aufgezählten, wobei die Aufzählung mit Leerzeichen getrennt ist. Vorhandene Click-Modes sind:
    • CLICK (wird beim Clicken auf einen Frame ausgelöst)
    • ENTER (wird ausgelöst, wenn die Maus über den entsprechenden Frame gleitet)
    • LEAVE (wird ausgelöst, wenn die Maus den Frame wieder verlässt)
    • UP (wird ausgelöst, wenn die Maus nach einem Klick losgelassen wird)
    • DOWN (wird beim herunterdrücken der Maustaste über dem Frame ausgelöst)
    • WHEEL (wird beim verwenden des Mausrades über dem Frame ausgelöst, in diesem Fall wird als "key" je nach Bewegungsrichtung des Mausrades 1 oder -1 angegeben)

    Als Erklräung zu der zuvor beschriebenen Funktionsweise hier ein paar Beispiele:
    ClickModes = "" ist gleichwertig mit ClickModes="CLICK", heißt es wird nur das CLICK-Event wahrgenommen
    ClickModes = "ENTER" bedeutet, dass nur das "ENTER"-Event wahrgenommen wird, jedoch nicht das CLICK-Event
    ClickModes = "CLICK ENTER" bedeutet, dass sowohl das ENTER-Event als auch das CLICK-Event wahrgenommen wird

    Zu den in der Table vorhandenen Funktionen fügt die Regestrierung noch die folgenden Funktionen "GetPage" und GetCmds" hinzu. Sollten bereits Funktionen mit diesen Namen vorhanden sein, werden diese bei der Regestrierung überschrieben! Diese zwei Funktionen sind die einzige Funktionen, die die Seite haben MUSS, um zu funktionieren, daher werden sie automatisch erstellt. Das heißt, du musst sie NICHT defenieren
    Zusätzlich gibt es eine Reihe von Funktionen, die optional vorhanden sein können. Sind sie vorhanden, werden diese Funktionen automatisch von GroupInvite entsprechend ausgeführt, eine explezite Regestrierung ist hierzu nicht notwendig, sie werden automatisch erkannt:
    • OnLoad() (wird ausgeführt, sobald die Seite regestriert und alle Variablen geladen sind)
    • OnUpdate(etime) (wird regelmäßig ausgeführt, wobei etime die vergangene Zeit in Sekunden seit der letzten Ausführung wiedergibt)
    • OnEvent(event,arg1,arg2,arg3,arg4) (ähnlich wie die standart-OnEvent-Funktion von Frames mit dem unterschied, dass auch GroupInvite-eigene Events ausgeführt werden. Diese Events fangen alle mit "GROUPINVITE_" an, eine komplette Liste der Events wird in der DevPage vorhanden sein)
    • OnSetText(func) (Diese Funktion wird ausgeführt, wenn die Texte der Frames gesetzt werden. In den meisten Fällen geschieht dies automatisch, die Funktion kommt erst dann zum Einsatz, wenn sich die Texte verändern können. Der Wert func ist eine Funktion, um die Texte zu setzen, und benötigt als erstes Argument den Namen des Frames als String, als zweites Argument die ID der Seite und als drittes Arugment den zu setzenden Text bzw den Text-Key, wie z.B. "GUI_GrpSave_ChooseGrpList")
    • OnDataControl(func,mode) (Diese Funktion wird sowohl beim Speichern als auch beim Laden von Variablen aufgerufen. func ist auch hier eine Funktion, welche als Argumente (in dieser Reihenfolge) den Namen des Frames, die Seiten-ID und die zu speichernde Variable benötigt, und die geladene Variable zurückgibt. Im Einsatz sieht dies also wie folgt aus: myVariable = func("myFrame",page.ID,myVariable). Diese eine Zeile speichert und läd die Variabe automatisch in den Frame, es ist nichts weiter notwendig. Der wert mode ist entweder "save" oder "load" und wird benutzt, wenn die Seite eigene Funktionen zum Speichern und Laden nutzen sollte. Gibt die Funktion OnDataControl true zurück, wird das Laden wiederhohlt, was dazu eingesetzt werden kann, falsche Eingaben zu korregieren)
    • OnBtnClick(name,key,mode) (Diese Funktion wird aufgerufen, sobald eine der oben genannten ClickModes eintritt, sofern der entsprechende ClickMode auch von der Seite wahrgenommen wird. Der Wert mode beinhaltet den ausgeführten ClickMode, der Wert key ist entweder "LBUTTON" oder "RBUTTON", je nachdem ob es die linke oder die rechte Maustaste war, und der Wert name beinhaltet den namen des Frames)
    • OnDropDown(this,name) (OnDropDown funktioniert im Grunde ähnlich wie OnBtnClick, mit dem Unterschied dass es keine ClickModes gibt und die Funktion beim öffnen eines DropDownMenüs aufgerufen wird, wobei der Wert name wieder den Namen des Frames beinhaltet, während der Wert this den Frame selbst beinhaltet)
    • OnTooltipReplace(_gsub,name,text) (Diese Funktion ist dafür zuständig, Variablen in Tooltips anzuzeigen. _gsub ist hierbei eine Funktion, die mit zwei oder drei Werten zurecht kommt: Bei zwei Werten ist der erste Wert der Textteil, der im Tooltip ersetzt wird (achtung: Im Tooltip sind "<"...">" um diesen Textteil herum, die Funktion fügt diese Zeichen automatisch hinzu, weshlab man sie im Wert weglassen sollte), der zweite Wert ist der zu setzende Text bzw Text-Key (siehe OnSetText), optional kann man vor den ersten Wert noch den Frame-Namen hinzufügen(der dann der erste Wert ist), in diesem Fall wird die Funktion nur bei diesem Frame ausgeführt)
    • OnShowFrame(pid) (Diese Funktion wird ausgeführt, sobald die Seite angezeigt werden soll. Der Wert pid gibt hierbei den "Part" an, der gezeigt werden soll(falls die Seite aus mehreren Seiten besteht. pid ist numerisch, beginnend mit 1). Meistens werden in dieser Funktion die Frames defeniert)

    Wie bereits oben erwähnt ist jede dieser Funktionen optional, es wird keine Fehlermeldung geben, sollte eine Funktion nicht vorhanden sein. Funktionen wie OnBtnClick, OnDataControl, OnSetText,etc werden nur ausgeführt, wenn es nötig ist, heißt wenn mindestens ein Frame der Seite sichtbar ist.

  • Seitenregestration
    Zuletzt wird die Seite regestriert. Hierzu wird zum einen eine Regestrierungstable genutzt, die alle wichtigen Informationen beinhaltet, wie unter anderem die default- und die Seiten-table, sowie die Funktions-table. Zusätzlich können zu speichernde Farben oder Slash-Befehle festgelegt werden, sowie zusätzliche Sprachdateien regestriert werden. Letzteres ist für externe Seiten sehr wichtig, um die eigenen Texte einzufügen.
    Die Farben sind wie folgt festzulegen, wobei diese Festlegung auch genau so in der default-table stattfinden kann:
    Innerhalb der Table "Colors" gibt es eine Reihe von Tabels, die die Farben in Kategorien unterteilen. Beinhaltet die Table Colors direkt die Farben, werden sie automatisch der Standart-Kategorie hinzugefügt. Innerhalb der Kategorien werden dann die Farben als ["Farbenname"]="|cff[Hexadezimaler Farbcode]" festgelegt. Alle auf diese Weise regestrierten Farben lassen sich mit der Funktion GroupInvite_Do("api","GetColors","Farbenname") erhalten, und können ingame von dem Spieler geändert werden.
    Die Slash-Befehle sind in der Table Cmds festgelegt, wobei der Bezeichner einer Table oder Funktion dem entsprechenden Befehlsteil, mit leerzeichen getrennt von den Vorrausgehenden, wiederspiegelt. Beginnt der Bezeichner mit "<" und endet mit ">" bedeutet dies, dass es eine Variable ist, die der Benutzer frei wählen kann. Der Wert dieser Variable wird als der x-te Wert an den letztlichen Befehl weitergegeben, wobei x die anzahl an vorrausgehenden Variablen plus der jetzigen entspricht. Würde also in der Table Cmds die table "test" sein, in dieser die table "" und in dieser die funktionen mytest(n) und xxx(n), wären die Slash-Befehle, um diese Funktionen auszuführen: /gic test [hier ein beliebiger Wert] mytest bzw /gic test [hier ein beliebiger Wert] xxx Die Groß- und Kleinschreibung ist hierbei irrelevant. Was immer der Benutzer statt dem "[hier ein beliebiger Wert]" eingibt, wird als erstes Argument an die jeweilige Funktion gesendet. Gibt es außerdem in einer table eine Funktion mit dem Bezeichner "" entspricht dies dem Slash-Befehl, in dem man nur diese table aufruft. (eine bessere Verdeutlichung ist in der Beispielseite "test", die in GroupInvite enthalten ist. Diese Seite wird nicht geladen und dient nur als Beispiel für Seitenentwickler)
    Um zusätzliche Sprachen hinzuzufügen, muss es in der Regestrierungs-table die table "AddLanguages" geben, welche eine Reihe weitere tables als numerische Aufzählung beinhaltet. Jeder dieser aufgezählten Tabels beinhaltet dann folgende Werte:
    Der erste Wert ist der Pfad zu dem Ordner, der die Sprachdateien enthällt (nicht zu einer bestimmten Sprachdatei direkt!). Der zweite Wert ist eine Funktion, die die table, die die Sprachdateien beinhalten, zurückgibt. Der dritte Wert ist optional, sofern er angegeben ist, muss er eine table sein. Diese table beinhaltet die Sprachkürzel(nur zwei Großbuchstaben) aller Sprachen, die enthalten sind (z.B {"EN","DE","ES"} für "englisch","deutsch","spanisch"). Ist eine Sprache angegeben, die GroupInvite nicht standartmäßig unterstützt, wird diese Sprache automatisch zu der Liste auswählbarer Sprachen hinzugefügt. Die Sprachdatei sollte jedoch dann mindestens den Wert "GUI_Language" mit dem Namen der Sprache beinhalten, besser noch eine Komplette Übersetzung des gesammten Addons. Damit die Sprachdateien ordentlich funtionieren, muss mindestens eine englische Sprachdatei vorhanden sein, da in dem Falle, dass ein Wert in der ausgewählten Sprache nicht vorhanden ist, stattdessen der Wert aus der englischen Sprachdatei ausgewählt wird.

    Die Regestration selbst verläuft dann über die Funktion page=GroupInvite_Do("api","RegisterPage",add), wobei add die Regestrierungs-table ist. Die Funktion gibt die überarbeitete Seiten-Table zurück, welche neue Werte wie die Seiten-ID beinhaltet, ebenso wie den überarbeiteten Namen der Seite(sollte es bereits eine Seite dieses Namens geben). Die Regestrierungsfunktion wird außerhalb jeder anderen Funktion direkt am Ende der Seite aufgerufen, um die Regestrierung beim Laden der Seite zu ermöglichen.

Nach oben

Erstellung eines Frames


Der erste Schritt beim erstellen einer Seite ist häufig die Erstellung eines Frames, also des vom Spieler verwendbaren Interfaces. Bei normalen Addons wäre dieser Abschnitt umständlich in XML-Dateien zu regeln, wie bereits oben erwähnt unterstützt die GroupInviteEngine jedoch auch das erstellen eines Interfaces ohne die Verwendung irgendwelcher XML-Dateien. Hierzu werden in erster Linie 3 Funktionen pro Objekt benötigt, welche Name und Art des Objektes festlegen, sowie seine Position, Größe, Beschriftung und Tooltip. Für Typspezifische Einstellungen gibt es dann meist weitere Funktionen, dazu jedoch später mehr Das erstellen eines Frames wäre theoretisch jederzeit möglich, wird jedoch meistens in der OnShowFrame-funktion abgehandelt. Sobald die Seite gewechselt wird, werden alle Objekte, die nicht als "AllwaysShown" oder "OutsideShown" markiert sind, wieder gelöscht, um Speicherplatz für die Objekte der neuen Seite zu machen. Beim Schließen des Einstellungsfensters werden zudem alle "AllwaysShown" objekte gelöscht, weshalb diese meist - durch ein Event gesteuert - bereits beim öffnen des Einstellungsfensters erstellt werden.

Die genannten 3 Hauptfunktionen sind folgende:

  • this=GroupInvite_Do("api","GetNext[Objekttyp]",page.ID,"[Objektname]");

    Diese Funktion "erstellt" dir das Objekt erstmal, und benennt es nach dem eingegebenen Objektnamen. Dieser Objektname muss innerhalb deiner Seite eindeutig sein, es darf also kein anderes Objekt dieses Namens geben(kann es auch garnicht, da es stets das bereits exestierende stattdessen auswählen würde). GroupInviteEngine unterstützt nur ganz bestimmte Objekttypen, wobei von jedem Objekttyp nur eine bestimmte Anzahl zur Verfügung steht. Ist diese Anzahl aufgebraucht, wird er statt den neuen Objekten immer wieder das zuletzt verwendete nehmen, was zu verwirrenden Fehlern führen kann.
    Eine komplette Liste aller unterstützten Objekttypen wird in der Entwicklungsseite vorhanden sein, hier sind nur ein paar Beispiele: Button, Editbox, List, EmptyButton,...
    Ein Button beispielsweise ist ein sehr einfacher Objekttyp, welcher keine zusätzlichen Angaben anbietet oder benötigt. Gleiches trift auch auf den EmptyButton hinzu, wobei letzterer jedoch die Eingeschaft hat, keine eigene Textur zu besitzen. Es ist also ein unsichtbares Druckfeld, das jedoch z.B. Klicks regestrieren oder Tooltips anzeigen kann. Eine Editbox hingegen kann zusätzlich mit einer maximalen Zeichenzahl oder dem Wert "numeric"(also dass du Zahlen eingebbar sind) ausgestattet werden. Diese Eigenschaften sind jedoch komplett optional, das Objekt würde auch ohne die Eigenschaften fehlerfrei arbeiten. Eine List(englisch für Liste) hingegen benötigt zusätzliche Angaben wie die Höhe einer in der Liste befindlichen Zeile, sowie zumindest einer Funktion, die die anzuzeigende Liste ausgibt. Ohne diese Werte kann es evt. zu Fehlern kommen oder die Liste wird nicht ordentlich gefüllt.
    Soll das Objekt außerdem via Drag&Drop verschiebbar sein, oder auch eine "Andock-Station" für ein solches Objekt darstellen, muss dies ebenfalls in einer zusätzlichen Funktion deklariert werden.
    Wie bereits angedeutet ist, gibt die Funktion außerdem das Objekt selbst zurück, da dieses in den weiteren Funktionen benötigt wird.

  • GroupInvite_Do("api","SetFrameSizeAndPossition",this,width,height,achorPoint,relativeAnchorPoint,relativeAnchor,xOffset,yOffset,lineHeight)

    Diese Funktion bestimmt mit width(=Breite) und height(=Höhe) die Größe des Objektes, während anchorPoint, relativeAnchorPoint, relativeAnchor, xOffset und yOffset Werte zur Positionsbestimmung sind. Gibt man als relativeAnchor den Wert nil an, wird die Position übrigens Relativ zu dem Einstellungsfenster berechnet, gibt man hingegen "$parent" an, wird die Position relativ zum Bildschirm bestimmt. Der Wert lineHeight ist ausschließlich für Listen und bestimmt einen Anhaltswert für die Höhe jeder Zeile in der Liste. Die tatsächliche Höhe jeder Zeile wird annährend identisch mit dem Angegebenen Wert sein, jedoch aufgrund der Miteinberechnung des Randes und der Beabsichtigung, die komplette Höhe zu nutzen, kann sie etwas abweichen. Außerdem kann eine Liste nicht mehr als 20 Zeilen - den Listentitel mit eingeschlossen - anzeigen, was ebenfalls in die Berechnung einfließt, sollte die Höhe zu niedrig sein.
    Es sind auch die Funktionen "SetFrameSize" und "SetFramePossition" vorhanden, bei welchen man nur die entsprechenden Werte eingeben kann. Sollte sich die Position oder Größe eines Objektes verändern, während es angezeigt wird (Sofern dies nicht mit dem Drag&Drop system in verbindung steht), lassen sich alle drei Funktionen jederzeit dazu nutzen, die Werte nach Wunsch anzupassen.

  • GroupInvite_Do("api","SetFrameTextAndTooltip",this,text,tooltip)

    Diese Funktion ist vergleichsweise simpel: Du kannst hiermit die Beschriftung und den Tooltip eines Objektes bestimmen. Sofern die Beschriftung auch während das Objekt angezeigt wird verändert werden könnte, wird zum Bestimmen der Beschriftung bevorzugt die Funktion "OnSetText" genommen. In diesem Fall sollte man bei dem Wert text nil angeben.
    Gibt man bei dem text oder dem tooltip den Wert true an, werden diese automatisch nach folgendem Algorhythmus erstellt: der text wird lauten: GUI_[Seitenname]_[Objektname], der Tooltip Tooltip_[Seitenname]_[Objektname]_..., ansonsten sind diese entsprechend manuell als String einzugeben. Ist ein String in keiner Sprachdatei zu finden, wird er so ausgegeben wie er eingegeben wurde, ansonsten wird er anhand der Sprachdatei übersetzt. Bei der Angabe des Tooltips sind allerdings die Aufzählungsziffern am ende sowie das "Tooltip_" am Anfang weg zu lassen, diese werden automatisch hinzugefügt. Beim Anzeigen des Tooltips wird das Tooltipobjekt mit der Ziffer 1 als Tooltip-Titel genommen, alle direkt nachfolgenden Ziffern als Inhalt des Tooltips, wobei jede Ziffer einen Zeilenumbruch bedeutet. Als beispiel hätte das Objekt "MeinObjekt" von der Seite "MeineSeite" nach der Angabe beider Werte als true die Beschriftung "GUI_MeineSeite_MeinObjekt" bzw eine übersetzung dieses Textes entsprechend den Sprachdateien, als Tooltip-Titel dann die Übersetzung von Tooltip_MeineSeite_MeinObjekt_1, als fließtext (als Beispiel nehm ich jetzt mal nur 3, die Anzahl ist jedoch beliebig auswählbar) im Tooltip dann die Übersetzungen von Tooltip_MeineSeite_MeinObjekt_2 und Tooltip_MeinSeite_MeinObjekt_3. Die suche nach Tooltip-texten wird abgebrochen, sobald das erste nicht mehr gefunden werden konnte(wie hier z.B. Tooltip_MeineSeite_MeinObjekt_4, welches in unserem beispiel nicht vorhanden ist). Ist der Tooltip-Titel nicht vorhanden, wird folglich garkein Tooltip angezeigt.

Nach oben

Mehr folgt in Kürze

MfG

Xobor Einfach ein eigenes Xobor Forum erstellen