Hierarchische Listen verwalten

Hierarchische Listen sind Formularobjekte zum Anzeigen von Daten in Form einer Liste mit einer oder mehreren Ebenen, die sich auf- oder zuklappen lassen.

In Formularen dienen hierarchische Listen zur Anzeige oder Eingabe von Daten. Jeder Eintrag kann bis zu 2 Millionen Zeichen enthalten (maximale Größe eines Textfeldes) und mit einem Icon versehen werden. Sie unterstützen in der Regel Klicks, Doppelklicks, die Steuerung über Tastatur sowie Drag-and-Drop. Sie können auch nach dem Inhalt einer Liste suchen (Funktion Find in list).

Hierarchische Listen lassen sich komplett per Programmierung erstellen (über die Funktionen New list oder Copy list) oder über Listen, die im Listeneditor des Designmodus definiert wurden (Funktion Load list).

Inhalt und Darstellung hierarchischer Listen werden über die Befehle und Funktionen dieses Kapitels per Programmierung gesteuert. Einige spezifische Darstellungsmerkmale lassen sich auch über die generischen Befehle im Kapitel Objekteigenschaften steuern (siehe unten).

Über den Befehl OBJECT SET LIST BY REFERENCE oder OBJECT SET LIST BY NAME können Sie Referenzen auf hierarchische Listen dynamisch mit Formularobjekten aus Auswahllisten (Quellen, erforderliche und ausgeschlossen Werte) verbinden. Sie können auch Auswahllisten zuweisen, die über die Eigenschaftenliste im Listeneditor mit Formularobjekten definiert wurden.

Eine hierarchische Liste ist sowohl ein Programmierspracheobjekt im Speicher als auch ein Formularobjekt.
Auf das Programmierspracheobjekt wird mit der einmaligen internen ID ListRef vom Typ Lange Ganzzahl verwiesen. Diese ID wird von den Funktionen zurückgegeben, die zum Erstellen von Listen dienen: New list, Copy list, Load list, BLOB to list.

Es gibt im Speicher immer nur eine Instanz des Programmierspracheobjekts und jede Änderung im Objekt erscheint sofort an allen Stellen, wo es verwendet wird.
Das Formularobjekt ist hingegen nicht zwingend einmalig: Es kann mehrere Darstellungen derselben hierarchischen Liste in einem oder verschiedenen Formularen geben. In der Programmiersprache wird das Objekt, wie andere Formularobjekte, mit der Syntax (*;"ListName", etc.) angegeben.

Sie können die hierarchische Liste "Programmierspracheobjekt" mit der hierarchischen Liste "Formularobjekt" über eine Variable mit dem Wert ListRef verbinden. Schreiben Sie zum Beispiel:

... können Sie den Variablennamen mylist einfach mit dem Formularobjekt der hierarchischen Liste in der Eigenschaftenliste verbinden, so dass dieser das Programmierspracheobjekt steuert, dessen ListRef in mylist gespeichert ist.

Jede Darstellung der Liste hat Merkmale, die für alle Darstellungen gleich sind, und solche, die nur für eine bestimmte Darstellung gelten.

Folgende Merkmale sind für jede Darstellung der Liste spezifisch:

• Auswahl
• Status auf-/zugeklappt der einzelnen Zeilen
• Position der Rollbox

Andere Merkmale wie Schrift, Eingabekontrolle, Inhalt der Liste, Icons, etc. und die Attribute, die auf der Ebene des Programmierspracheobjekts (ListRef) definiert sind, sind für alle Darstellungen gleich und lassen sich nicht einzeln ändern.

Verwenden Sie Befehle, die mit auf-/zugeklappten Einträgen oder dem aktuellen Eintrag arbeiten, wie z.B. Count list items (ohne den Parameter *), muss gewährleistet sein, dass die zu verwendende Darstellung in eindeutiger Weise bestimmbar ist.
Wollen Sie die hierarchische Liste im Speicher angeben, müssen Sie die ID ListRef mit Programmiersprachebefehlen verwenden.
Wollen Sie die Darstellung einer hierarchischen Liste auf Formularebene angeben, müssen Sie im Befehl den Objektnamen vom Typ String mit der Syntax (*;"ListName", etc.) verwenden. Das ist dieselbe Syntax wie für die Befehle im Kapitel Objekte. Die meisten Befehle im Kapitel "hierarchische Listen", die mit den Listeneigenschaften arbeiten, verwenden diese Syntax. Ausführliche Informationen dazu finden Sie in der Beschreibung der einzelnen Befehle.

Warnung: Beachten Sie, dass bei Befehlen, die Eigenschaften setzen, die Syntax mit dem Objektnamen nicht bedeutet, dass der Befehl nur das angegebene Formularobjekt ändert. Die Aktion des Befehls richtet sich vielmehr nach dem Status des Objekts. So werden die Merkmale für hierarchische Listen immer in allen Darstellungen geändert.
Übergeben Sie z.B. die Anweisung SET LIST ITEM FONT (*;"mylist1";*;thefont), bedeutet das, dass Sie die Schrift eines Eintrags in der hierarchischen Liste ändern wollen, die dem Formularobjekt mylist1 zugeordnet ist. Der Befehl berücksichtigt den aktuellen Eintrag in mylist1 für die Änderung. Sie wird aber auch auf alle Darstellungen der Liste in allen Prozesse ausgeführt.

Sie können, wie in Routinen zur Verwaltung von Objekteigenschaften, im Parameter Objektname das Zeichen “@” verwenden. Damit bestimmen Sie in der Regel einen Satz Objekte im Formular. Bei Befehlen für hierarchische Listen ist das jedoch nicht für alle Fälle geeignet. Diese Syntax hat je nach Befehlsart zwei unterschiedliche Auswirkungen:

• Bei Befehlen, die Eigenschaften setzen, bezeichnet diese Syntax standardmäßig alle Objekte mit dazu passendem Namen. So bestimmt der Parameter "LH@" alle Objekte des Typs hierarchische Liste, deren Name mit “LH” beginnt. Das gilt für folgende Befehle:
  DELETE FROM LIST
  INSERT IN LIST
  SELECT LIST ITEMS BY POSITION
  SET LIST ITEM
  SET LIST ITEM FONT
  SET LIST ITEM ICON
  SET LIST ITEM PARAMETER
  SET LIST ITEM PROPERTIES
  

• Bei Befehlen und Funktionen, die Eigenschaften liefern, bezeichnet diese Syntax das erste Objekt mit dem dazu passenden Namen. Das gilt für folgende Befehle und Funktionen:
  Count list items
  Find in list
  GET LIST ITEM
  Get list item font
  GET LIST ITEM ICON
  GET LIST ITEM PARAMETER
  GET LIST ITEM PROPERTIES
  List item parent
  List item position
  Selected list items
  

Sie können die Darstellung einer hierarchischen Liste in einem Formular mit mehreren generischen 4D Befehlen verändern. Sie übergeben in diesen Befehlen entweder den Objektnamen der hierarchischen Liste (mit dem Parameter *) oder ihren Variablennamen (Standardsyntax).

Hinweis: Bei hierarchischen Listen enthält die Variable des Formulars den Wert ListRef. Führen Sie einen Befehl aus, der ein Attribut über die Variable der hierarchischen Liste verändert, lässt sich bei mehrfacher Darstellung keine Zielliste festlegen. Nur der Objektname ermöglicht die individuelle Unterscheidung zwischen den verschiedenen Darstellungen.

Folgende Befehle lassen sich mit hierarchischen Listen verwenden:
OBJECT SET FONT
OBJECT SET FONT STYLE
OBJECT SET FONT SIZE
OBJECT SET COLOR
OBJECT SET FILTER
OBJECT SET ENTERABLE
OBJECT SET SCROLLBAR
OBJECT SET SCROLL POSITION
OBJECT SET RGB COLORS

Hinweis: Diese Befehle verändern alle Darstellungen derselben Liste, auch wenn Sie nur eine Liste über ihren Objektnamen angeben. Davon ausgenommen ist der Befehl OBJECT SET SCROLL POSITION.

Bestimmte Eigenschaften einer hierarchischen Liste, wie z.B. das Attribut „Eingebbar“ oder die Farbe, lassen sich auf drei Arten setzen: Über die Eigenschaftenliste im Designmodus, über einen Befehl aus dem Kapitel “Objekte” oder einen Befehl aus dem Kapitel “Hierarchische Listen”.

Dabei gilt folgende Priorität in der Reihenfolge:

1. Befehle aus dem Kapitel “Hierarchische Listen”
2. Generische Befehle aus dem Kapitel “Objekte”
3. Optionen der Eigenschaftenliste

Diese Priorität gilt unabhängig von der Reihenfolge, in der die Befehle aufgerufen werden. Ändern Sie die Eigenschaft einer Zeile individuell mit einem Befehl für hierarchische Listen, hat der entsprechende Befehl für Objekteigenschaft keine Auswirkung auf diese Zeile, selbst wenn er danach aufgerufen wird. Ändern Sie z.B. die Farbe einer Zeile mit dem Befehl SET LIST ITEM PROPERTIES, hat der Befehl OBJECT SET COLOR keine Auswirkung auf diese Zeile.

Es gibt zwei Möglichkeiten, um mit dem Inhalt hierarchischer Listen zu arbeiten: nach Position oder nach Referenz.

• Bei Position verwendet 4D zum Identifizieren die Position in Bezug auf die Einträge der Liste auf dem Bildschirm. Das Ergebnis ist unterschiedlich, je nachdem, ob Einträge in der Liste aufgeklappt oder zugeklappt sind. Beachten Sie, dass bei mehrfachen Darstellungen jedes Formularobjekt eine eigene Konfiguration auf- bzw. zugeklappter Einträge hat.
• Bei Referenz verwendet 4D die ID EintragRef der Listeneinträge. Jeder Eintrag lässt sich so individuell bestimmen, unabhängig von seiner Position oder der Darstellung in der hierarchischen Liste.

Jeder Eintrag einer hierarchischen Liste hat eine Referenznummer (itemRef) vom Typ Lange Ganzzahl. Dieser Wert dient nur für Ihren eigenen Gebrauch: 4D stellt diesen lediglich bereit.

Warnung: Sie können als Referenznummer einen beliebigen Wert vom Typ Lange Ganzzahl verwenden, außer 0 (Null). Die meisten Befehle dieses Kapitels verwenden den Wert 0 zur Angabe des zuletzt in der Liste hinzugefügten Eintrags.

Hier ein paar Tipps zur Verwendung von Referenznummern:

1. Sie müssen nicht jeden Eintrag mit einer einmaligen Nummer identifizieren (Anfängerebene).

• Erstes Beispiel: Sie erstellen per Programmierung ein System mit Registerkarten, z.B. ein Adressbuch. Da das System die Zahl der gewählten Registerkarte zurückgibt, benötigen Sie keine Referenznummern für die Einträge: Übergeben Sie im Parameter itemRef einen beliebigen Wert außer 0. Für ein Adressbuch können sich auch im Designmodus eine Liste mit A, B, ... vordefinieren. Sie können diese auch per Programmierung erstellen, um die Buchstaben, für die es keine Datensätze gibt, zu entfernen.
• Zweites Beispiel: Beim Arbeiten mit einer Datenbank bauen Sie nach und nach eine Liste mit Kennwörtern auf. Sie können diese Liste am Ende jeder Sitzung über den Befehl SAVE LIST oder LIST TO BLOB speichern und zu Beginn der nächsten Sitzung über die Funktionen Load list oder BLOB to list erneut laden. Sie können diese Liste in einem Palettenfenster anzeigen. Klickt ein Benutzer dann auf ein Kennwort in der Liste, wird der gewählte Eintrag in den eingebbaren Bereich eingefügt, der im Prozess im Vordergrund ausgewählt ist. Sie können auch Drag&Drop verwenden. In jedem Fall ist es wichtig, dass Sie nur den ausgewählten Eintrag bearbeiten (per Klick oder Drag-and-Drop), da die Routinen Selected list items (bei Klick) und DRAG AND DROP PROPERTIES die Position des Eintrags zurückgeben, den Sie bearbeiten müssen. Verwenden Sie den Wert dieser Position, um den Titel des Eintrags über den Befehl GET LIST ITEM zu erhalten. Auch hier müssen Sie nicht jeden Eintrag individuell identifizieren, im Parameter itemRef können Sie einen beliebigen Wert - außer 0 (Null) - übergeben.

2. Sie müssen die Einträge der Liste z.T. identifizieren (mittlere Ebene).
Verwenden Sie die Referenznummer der Einträge zum Speichern von Informationen, müssen Sie mit dem Eintrag arbeiten. Weitere Informationen dazu finden Sie im Beispiel zum Befehl APPEND TO LIST. In diesem Beispiel verwenden wir die Referenznummern zum Speichern von Datensatznummern. Es muss jedoch möglich sein, zwischen Einträgen in Datensätzen zur Tabelle [Abteilung] und [Angestellte] zu unterscheiden.

3. Sie müssen alle Einträge der Liste individuell identifizieren (fortgeschrittene Ebene).
Sie programmieren eine fortgeschrittene Verwaltung für hierarchische Listen, die ermöglicht, jeden Eintrag auf jeder Ebene der Liste individuell zu identifizieren. Der einfachste Weg ist ein eigener Zähler. Angenommen Sie erstellen eine Liste hlList mit der Funktion APPEND TO LIST. In diesem Stadium initialisieren Sie einen Zähler vhlCounter auf 1. Immer wenn Sie APPEND TO LIST oder INSERT IN LIST aufrufen, erhöhen Sie diesen Zähler um 1 (vhlCounter:=vhlCounter+1) und übergeben den Zählerwert als Referenznummer des Eintrags. Der Trick dabei ist, dass der Zähler nie zurückgestuft wird, wenn Einträge gelöscht werden — der Zähler kann nur erhöht werden. Da diese Nummern vom Typ Lange Ganzzahl sind, können Sie in einer initialisierten Liste bis zu 2 Millionen Einträge einfügen. (Bei solch einer hohen Anzahl von Einträgen empfehlen wir jedoch, nicht mehr mit einer Liste, sondern mit einer Tabelle zu arbeiten.)

Hinweis: Verwenden Sie Bit Operatoren, können Sie Referenznummern für Einträge auch zum Speichern von Information verwenden, die sich in eine Lange Ganzzahl setzen lässt, z.B. 2 Ganzzahlen, 4-byte Werte oder 32 Booleans.

In den meisten Fällen, bei Verwendung hierarchischer Listen für Benutzerzwecke und wenn nur der aktuelle Eintrag bearbeitet wird (der angeklickte oder per Drag-and-Drop bewegte Eintrag), benötigen Sie überhaupt keine Referenznummern für Einträge. Hier reichen die Routinen Selected list items und GET LIST ITEM vollkommen aus. Außerdem ermöglichen die Befehle INSERT IN LIST und DELETE FROM LIST die Bearbeitung der Liste in Bezug auf den gewählten Eintrag.

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