APPEND TO LIST

4D - Documentation   Français   English   German   4D Programmiersprache, Befehle nach Themen   4D Programmiersprache, Befehle alphabetisch   4D Programmiersprache, Konstanten nach Themen   Back   Previous   Next

Version 2003 (Geändert)


APPEND TO LIST (Liste; EintragText; EintragRef{; Unterliste{; Erweitert}})

ParameterTypBeschreibung
ListeListenRefReferenznummer für Liste
EintragTextStringText für neuen Listeneintrag (max. 255 Zeichen)
EintragRefNumerischEinmalige Referenznummer für neuen Eintrag
in Liste
UnterlisteListenRefOptionale Unterliste für neuen Eintrag in Liste
ErweitertBooleanGibt an, ob die optionale Unterliste
erweitert oder geschlossen ist

Beschreibung

Der Befehl APPEND TO LIST fügt in der hierarchischen Liste einen neuen Eintrag an mit der in Liste übergebenen Referenznummer.

In EintragText übergeben Sie den Text für den Eintrag. Sie können bis zu 255 Zeichen vom Typ alphanumerisch übergeben. Längere Ausdrücke werden abgeschnitten.

In EintragRef übergeben Sie die Referenznummer für den Eintrag. Die Referenznummer ist zwar einmalig, Sie können jedoch einen beliebigen Wert übergeben. Weitere Informationen finden Sie im nachfolgenden Abschnitt über Referenznummern.

Soll ein Eintrag auch untergeordnete Einträge haben, übergeben Sie in Unterliste eine gültige Referenznummer. In diesem Fall müssen Sie auch den Parameter Erweitert setzen. Übergeben Sie TRUE oder FALSE, damit die Unterliste erweitert bzw. zugeklappt erscheint.

Die in Unterliste angegebene Referenznummer muss sich auf eine bestehende Liste beziehen. Das kann eine Liste auf einer Ebene oder eine Liste mit Unterlisten sein. Wollen Sie dem neuen Eintrag keine Liste zuordnen, übergeben Sie keinen Parameter oder den Wert Null (0).

Tipps

Mit dem Befehl INSERT LIST ITEM fügen Sie einen neuen Eintrag in die Liste ein. Mit dem Befehl SET LIST ITEM ändern Sie den Text eines vorhandenen Eintrags oder der zugeordneten Unterliste und ihres Status erweitert bzw. geschlossen.

Mit dem Befehl SET LIST ITEM PROPERTIES ändern Sie die Darstellung des neu hinzugefügten Eintrags.

WARNUNG: Fügen Sie einen Eintrag einer Liste in einem Formular hinzu oder einer Unterliste zu einem Eintrag dieser Liste, MÜSSEN Sie anschließend REDRAW LIST aufrufen; 4D berechnet die Liste dann neu und berücksichtigt die Änderungen. Die Regel ist einfach, egal auf welcher Ebene der Liste Sie arbeiten, rufen Sie REDRAW LIST immer für die Hauptliste auf. Das ist die Liste, die dem Objekt im Formular zugewiesen ist.

Wozu dienen Referenznummern für Einträge?

Jeder Eintrag einer hierarchischen Liste hat eine Referenznummer vom Typ Lange Ganzzahl. Dieser Wert ist für Ihren persönlichen Gebrauch: 4th Dimension führt diesen nur auf.

Achtung: Sie können als Referenznummer jeden Wert vom Typ Lange Ganzzahl, außer 0 (Null) verwenden. Der Grund dafür ist, dass für die meisten Befehle unter diesem Thema über den Wert 0 (Null) das zuletzt in der Liste hinzugefügte Element bezeichnet wird.

Die Verwendung von einmaligen Referenznummern wird an den folgenden Beispielen erläutert:

1. Sie selbst benötigen keine Nummer, um jeden Eintrag als einmalig zu identifizieren (einfach).

Erstes Beispiel: Sie erstellen per Programmierung eine Registerkarte, z.B. ein Adressbuch. Da das Register die Zahl des gewählten Registers zurückgibt, benötigen Sie wahrscheinlich keine weiteren Informationen. Übergeben Sie für EintragRef eine fortlaufende Nummer (außer 0). Für ein Adressenregister genügt es zwar bereits, in der Designumgebung eine Liste mit den Buchstaben A, B,..., Z zu definieren. Wollen Sie jedoch bestimmte Buchstaben ausschließen, für die es keine Datensätze gibt, z.B. den Buchstaben Q, müssen Sie das Register per Programmierung erstellen.

Zweites Beispiel: Beim Arbeiten mit einer Datenbank erstellen Sie nach und nach eine Liste mit Schlüsselwörtern. Diese Liste können Sie am Ende jeder Sitzung mit den Befehlen SAVE LIST oder LIST TO BLOB abspeichern und bei der nächsten Sitzung mit Load list oder BLOB to list wieder laden. Sie wird in einem Palettenfenster angezeigt. Wenn Sie einen Eintrag anklicken, wird das Schlüsselwort in den aktuellen Bereich des vordersten Prozesses eingefügt. Sie können aber auch mit Drag&Drop-Technik arbeiten. In jedem Fall arbeiten Sie mit dem ausgewählten Eintrag, d.h. dem angeklickten oder bewegten Eintrag, da die Befehle Selected list Item (Klick) und DRAG AND DROP PROPERTIES die Position des entsprechenden Eintrags angibt. Über die Position erhalten Sie mit dem Befehl GET LIST ITEM den Text dieses Eintrags. Damit haben Sie alles. Übergeben Sie für EintragRef wieder eine fortlaufende Nummer (außer 0).

2. Sie müssen die Einträge der Liste teilweise als einmalig identifizieren. (mittlere Ebene)

Sie verwenden Referenznummern für Einträge zum Speichern von Information, die Sie beim Bearbeiten des Eintrags benötigen. Hier verwenden wir Referenznummern für Einträge zum Speichern von Datensatznummern. Wir müssen jedoch zwischen Einträgen der Datensätze aus [Departments] und [Employees] unterscheiden können. Wie das funktioniert, sehen Sie im nächsten Beispiel.

3. Sie müssen die Einträge der Liste als einmalig identifizieren. (komplex)

Sie programmieren eine komplexe Verwaltung von hierarchischen Listen, deren Einträge auf jeder Ebene als einmalig identifiziert werden müssen. Das bewerkstelligen Sie am einfachsten mit einem persönlichen Zähler. Nehmen wir an, Sie erstellen mit der Funktion New list eine Liste mit Namen hlList. Hier initialisieren Sie einen Zähler mit dem Wert 1. Diesen Zähler erhöhen Sie, immer wenn Sie die Befehle APPEND TO LIST oder INSERT LIST ITEM aufrufen (vlhCounter:=vlhCounter+1) und übergeben ihn als Referenznummer für den Eintrag. Der Trick dabei ist, dass der Zähler beim Löschen von Einträgen nicht zurückgesetzt wird - er kann nur ansteigen. Damit sind Ihre Referenznummern für Einträge garantiert einmalig. Da Referenznummern vom Typ Lange Ganzzahl sind, können Sie einen Eintrag viele Male in eine neu initialisierte Liste ein- oder anfügen. Arbeiten Sie jedoch mit Tausenden von Einträgen, sollten Sie anstatt der Liste eine Tabelle verwenden.

Hinweis: Mit Bit Operatoren können Sie Referenznummern auch zum Speichern von Informationen verwenden, die in einen Wert vom Typ Lange Ganzzahl passen, also 2 Werte vom Typ Ganzzahl, 4 Werte vm Typ Byte oder 32 Werte vom Typ Boolean.

Einmalige Referenznummern einsetzen

In den meisten Fällen verwenden Sie hierarchische Listen für die Benutzeroberfläche und arbeiten nur mit dem ausgewählten Eintrag, d.h. mit dem angeklickten oder bewegten Eintrag. Dafür benötigen Sie keine Referenznummern. Mit den Befehlen Selected list Item und GET LIST ITEM können Sie den aktuell ausgewählten Eintrag komplett verwalten. Mit den Befehlen INSERT LIST ITEM und DELETE LIST ITEM steuern Sie die hierarchische Liste.

Sie benötigen für Einträge nur Referenznummern, wenn Sie per Programmierung direkt auf einen beliebigen Eintrag der Liste zugreifen wollen, der nicht unbedingt der aktuell ausgewählte Eintrag ist.

Beispiel

Hier ist die Teilansicht einer Datenbankstruktur:

Die beiden Tabellen [Departments] und [Employees] enthalten folgenden Datensätze:

Sie wollen eine hierarchische Liste mit Namen hlList anzeigen, die die Abteilungen auflistet und für jede Abteilung eine untergeordnete Liste mit den jeweiligen Angestellten. Die Objektmethode von hlList lautet:

      ` Objektmethode hierarchische Liste hlList

   Case of 
 
      : (Form event=On Load)
         C_LONGINT(hlList;$hSubList;$vlDepartment;$vlEmployee)
            ` Erstelle neue leere hierarchische Liste
         hlList:=New list
            ` Wähle alle Datensätze aus der Tabelle [Departments]
         ALL RECORDS([Departments])
            ` Wähle für jede Abteilung
         For ($vlDepartment;1;Records in selection([Departments]))
               ` die dazugehörigen Angestellten
            RELATE MANY([Departments]Name)
               ` Wie viele sind es?
            $vlNbEmployees:=Records in selection([Employees])
               ` Gibt es in dieser Abteilung mindestens einen Angestellten?
            If ($vlNbEmployees>0)
                  ` Erstelle untergeordnete Liste für Eintrag Abteilung
               $hSubList:=New list
                  ` Füge für jeden Angestellten
               For ($vlEmployee;1;Records in selection([Employees]))
                     ` Eintrag Angestellter in die untergeordnete Liste ein 
                     ` Die Nummer des Datensatzes aus [Employees]
                     ` wird als Referenznummer für den Eintrag übergeben
                  APPEND TO LIST($hSubList;[Employees]Last Name+", "+
                        [Employees]First Name;Record number([Employees]))
                     ` Gehe zum nächsten Datensatz [Employees]
                  NEXT RECORD([Employees])
               End for 
            Else 
               ` Keine Angestellten, folglich keine untergeordnete Liste für den 
                                          Eintrag Abteilung 
               $hSubList:=0
            End if 
               ` Füge Eintrag Abteilung in übergeordnete Liste ein
               ` Die Nummer des Datensatzes aus [Departments]
               ` wird als Referenznummer für den Eintrag übergeben. Das Bit #31
               ` der Referenznummer für den Eintrag wird auf Eins gesetzt,
               ` um die Einträge Abteilung und Angestellte voneinander zu unterscheiden.
               ` Siehe auch Fußnote, wie dieses Bit zusätzliche Informationen über 
               ` den Eintrag liefern kann.
            APPEND TO LIST(hlList;[Departments]Name;
                           0x80000000 | Record number
                                    ([Departments]);$hSublist;$hSubList # 0)
               ` Setze den Eintrag Abteilung zur Hervorhebung der Hierarchie in Fettschrift
            SET LIST PROPERTIES(hlList;0;False;Bold;0)
               ` Gehe zur nächsten Abteilung
            NEXT RECORD([Departments])
         End for 
            ` Sortiere die ganze Liste in aufsteigender Reihenfolge 
         SORT LIST(hlList;>)
            ` Zeige die Liste in Windows-Darstellung an
            ` Lege als Mindesthöhe für Zeilen 14 Pts fest
         SET LIST PROPERTIES(hlList;ala Windows;Windows node;14)
 
      : (Form event=On Unload)
            ` Die Liste wird nicht mehr benötigt; vergessen Sie nicht, sie zu entfernen!
         CLEAR LIST(hlList;*)
 
      : (Form event=On Double Clicked)
            ` Ein Doppelklick ist erfolgt
            ` Erhalte Position des gewählten Eintrags
         $vlItemPos:=Selected list item(hlList)
            ` Prüfe auf alle Fälle die Position
         If ($vlItemPos # 0)
               ` Hole Information über Eintrag der Liste  
            GET LIST ITEM(hlList;$vlItemPos;$vlItemRef;$vsItemText;$vltemSubList;
                                          $vbItemSubExpanded)
               ` Ist es ein Eintrag Abteilung?
            If ($vlItemRef ?? 31)
                  ` Wenn ja, ist es ein Doppelklick auf einen Eintrag in Abteilung 
               ALERT("Sie haben auf den Eintrag Abteilung doppelgeklickt
                                 "+Char(34)+$vsItemText+Char(34)+".")
            Else 
                  ` Wenn nicht, ist es Doppelklick auf einen Eintrag in Angestellte 
                  ` Finde den Datensatz aus [Departments] mit der übergeordneten 
                                             Referenznummer
               GOTO RECORD([Departments];
                                 List item parent(hlList;$vlItemRef) ?- 31)
                  ` Teile mit, wo der Angestellte arbeitet und wer der Vorgesetzte ist
               ALERT("Sie haben auf den Eintrag Angestellte doppelgeklickt                                          "+Char(34)+$vsItemText+Char(34)+
               " wer arbeitet in der Abteilung "+Char(34)+[Departments]Name+Char(34)+
               " mit dem Vorgesetzten "+Char(34)+[Departments]Manager+Char(34)+".")
            End if 
         End if 
 
   End case 

      ` Hinweis: 4th Dimension kann pro Tabelle bis zu 16 Millionen Datensätze
      ` speichern (exakt 16,777,215). Das ist der Wert 2^24 minus Eins.
      ` Datensatznummern passen in 24 bits. Wir verwenden hier das Bit #3 des
      ` unbenutzten hohen Bits zur Unterscheidung der Eintrags Angestellte und Abteilung.

In diesem Beispiel gibt es nur einen Grund, die Einträge aus [Departments] von den Einträgen [Employees] zu unterscheiden:

1. Wir speichern Datensatznummern in den Referenznummern für Einträge. Das kann zur Folge haben, dass Einträge aus [Departments] dieselben Referenznummer wie Einträge aus [Employees] haben.

2. Mit der Funktion List parent item finden Sie den Eintrag, der dem ausgewählten Eintrag übergeordnet ist. Klicken wir auf einen Eintrag in [Employees] mit der Datensatznummer #10 und gibt es auch einen Eintrag in [Departments] mit #10, findet List parent item beim Durchlaufen der Listen zuerst den Eintrag [Departments], da nach der dem Eintrag übergebenen Referenznummer gesucht wird. Die Funktion gibt die Überordnung zum Eintrag in [Departments] und nicht die Überordnung zum Eintrag in [Employees] zurück.

Wir haben also einmalige Referenznummern für Einträge angelegt, um zwischen den Datensätzen [Departments] und [Employees] unterscheiden zu können.

Die Liste in der Benutzer- oder Runtime-Umgebung sieht folgendermaßen aus:

Hinweis: Dieses Beispiel eignet sich für die Benutzeroberfläche für kleine Mengen an Datensätzen. Beachten Sie, dass Listen im Speicher gehalten werden—erstellen Sie deshalb keine hierarchischen Listen mit Tausenden von Einträgen.

Referenz

INSERT LIST ITEM, SET LIST ITEM, SET LIST ITEM PROPERTIES.

Anwendung des Befehls

Display Icons in a Hierarchical List, Setup a Hierarchical List, XML hierarchische Listen


4D - Documentation   Français   English   German   4D Programmiersprache, Befehle nach Themen   4D Programmiersprache, Befehle alphabetisch   4D Programmiersprache, Konstanten nach Themen   Back   Previous   Next