TListWindow

Die Klasse TListWindow kapselt das Listenansicht Steuerelement von Windows 95 (WC_LISTVIEW). Da die OWL bereits eine Klasse TListView (Views für Listenfenster) enthält, wurde die Klasse TListWindow genannt, um Probleme mit bereits bestehendem Programmcode zu vermeiden. Ein TListWindow erzeugt eine äußerst flexible Listenansicht, die aus einem Symbol und einer Beschreibung bestehen und auf unterschiedliche Weise dargestellt werden kann. Der Explorer von Windows 95 benutzt beispielsweise im rechten Fensterabschnitt ein solches Kontrollelement.

TListWindow Teilhierarchie

Übersicht

Konstruktor zur direkten Erzeugung
Konstruktor zur Erzeugung aus einer Ressource
Wichtige Elementfunktionen

Konstruktor zur direkten Erzeugung

TListWindow(TWindow* parent, int id, int x, int y, int w, int h, TModule* module = 0);

Konstruktor zur Erzeugung aus einer Ressource

TListWindow(TWindow* parent, int resourceId, TModule* module = 0);

Wichtige Elementfunktionen der Klasse TListWindow

Es folgt nun eine Auflistung von Elementfunktionen der Klasse TListWindow. Diese fällt etwas ausführlicher aus, da die Online-Hilfe der ObjectWindows Bibliothek nur sehr spärliche und teilweise fehlerhafte Informationen enthält. Es sei an dieser Stelle nochmals angemerkt, daß diese Klasse aufgrund ihrer Flexibilität auch entsprechende Komplexität in sich birgt. Es bedarf schon einiger Experimente um die Funktionsweise verstehen zu lernen. Sie sollten dabei so vorgehen, daß Sie zuerst einfache Operationen anwenden und sich erst zu einem späteren Zeitpunkt mit den spezielleren Eigenschaften beschäftigen. Weiterhin stehen eine Vielzahl von Klassen und Aufzählunstypen im Zusammenhang mit TListWindow zur Verfügung wie beispielsweise TLwFindInfo, TLwHitTestInfo, TLwComparator, TListWindItem, TListWindColumn, TNextItemCode usw.

bool Arrange(TArrangeCode code);
(Botschaft LVM_ARRANGE)
Ordnet das Listenfenster entsprechend code neu an. TArrangeCode ist ein Aufzählungstyp der die Werte Default (LVA_DEFAULT), Left (LVA_ALIGNLEFT), Top (LVA_ALIGNTOP) und SnapToGrid (LVA_SNAPTOGRID) enthält. Bei erfolgreicher Ausführung wird true zurückgeliefert.

HIMAGELIST CreateDragImage(int itemIndex, TPoint* upLeft);
(Botschaft LVM_CREATEDRAGIMAGE)
Erzeugung eines Zieh-Bildes (Drag-Image). itemIndex bezeichnet den Index des Eintrages und upLeft enthält einen Zeiger auf ein TPoint, welches die anfängliche Position der oberen rechten Ecke des Bildes in View-Koordinaten enthält. Bei Erfolg wird ein Handle vom Typ HIMAGELIST zurückgeliefert, welches gelöscht werden sollte. Ist der Aufruf nicht erfolgreich, wird 0 zurückgeliefert.

bool DeleteAllItems();
(Botschaft LVM_DELETEALLITEMS)
Löscht alle Einträge des Listenfensters. Bei Erfolg wird true, ansonsten false zurückgegeben.

bool DeleteAnItem(int itemIndex);
(Botschaft LVM_DELETEITEM)
Löscht den Eintrag mit dem Index itemIndex des Listenfensters. Bei Erfolg wird true, ansonsten false zurückgegeben.

bool DeleteColumn(int colNum);
(Botschaft LVM_DELETECOLUMN)
Löscht in einer Spaltenüberschrift den an der Position colNum befindlichen Eintrag. Bei Erfolg wird true, ansonsten false zurückgegeben.

HWND EditLabel(int itemIndex);
(Botschaft LVM_EDITLABEL)
Editieren des Texteintrags an Position itemIndex. Mit der Übergabe von -1 in itemIndex, kann ein Editiervorgang abgebrochen werden. Der Rückgabewert ist entweder ein Handle des Editier Kontrollelements oder 0.
WICHTIG: Das Kontrollelement muß den Fokus besitzen, bevor diese Funktion aufgerufen wird.

bool EnsureVisible(int index, bool partialOk);
(Botschaft LVM_ENSUREVISIBLE)
Sorgt dafür, daß der Eintrag index vollständig oder wenigstens teilweise sichtbar ist und scrollt falls nötig das Listenfenster Kontrollelement. In partialOk wird angegeben, ob der betroffene Eintrag vollständig sichtbar sein soll (partialOk = false). Bei Angabe von true für partialOk, ist auch eine nur teilweise Anzeige des Eintrags erlaubt. Bei Erfolg wird true, ansonsten false zurückgegeben.

int FindItem(int startIndex, const TLvFindInfo far* findInfo);
(Botschaft LVM_FINDITEM)
Sucht nach einem Eintrag mit den in findInfo angegebenen Eigenschaften. startIndex legt fest, wo die Suche beginnen soll. Soll vom Anfang aus gesucht werden, kann der Wert in startIndex der Wert -1 verwendet werden. Der Rückgabewert entspricht dem Index des gefundenen Eintrags. Tritt ein Fehler auf oder wurde kein passender Eintrag gefunden ist der Rückgabewert -1 (siehe auch LV_FINDINFO).

uint GetCallBackMask();
(Botschaft LVM_GETCALLBACKMASK)
Liefert die Callback-Maske zurück.

bool GetColumn(int index, LV_COLUMN *column);
(Botschaft LVM_GETCOLUMN)
Liefert Informationen einer Spaltenüberschrift mit dem angegebenen index zurück.

bool GetColumn(int index, TListWindColumn& column) const;
(Botschaft LVM_GETCOLUMN)
Liefert Informationen einer Spaltenüberschrift mit dem angegebenen index zurück.

int GetColumnWidth(int index);
(Botschaft LVM_GETCOLUMNWIDTH)
Liefert bei Erfolg die Breite einer Spaltenüberschrift mit dem angegebenen index einer Report- oder Listendarstellung zurück oder andernfalls den Wert 0. Bei einer Listendarstellung wird index ignoriert.

int GetCountPerPage();
(Botschaft LVM_GETCOUNTPERPAGE)
Liefert die Anzahl der vollständig sichtbaren Einträge zurück, die vertikal in die Listen- oder Reportdarstellung passen. Ist die aktuelle Ansicht Icons oder kleine Icons, ist der Rückgabewert die Gesamtanzahl von Einträgen im Kontrollelement.

HWND GetEditControl();
(Botschaft LVM_GETEDITCONTROL)
Gibt ein Handle auf ein Editier-Kontrollelement zurück, in dem Beschriftungen editiert werden. Wenn keine Beschriftung editiert wird, wird der Wert 0 zurückgegeben.

HIMAGELIST GetImageList(TImageListType type);
(Botschaft LVM_GETIMAGELIST)
Gibt bei erfolgreicher Ausführung ein Handle auf eine Bildliste (Image List) zurück, die zum Zeichnen von Listenanzeigen verwendet werden oder den Wert 0. Die zurückzugebende Bildliste wird in type festgelegt. TImageListType ist ein Aufzählungstyp, der die Werte Normal, Small und State definiert, die den Win32 LVSIL_XXXX Konstanten entsprechen.

(Botschaft LVM_GETISEARCHSTRING)
Nach einer Wrapper-Funktion zu dieser Botschaft habe ich in der OWL vergeblich gesucht. Sie können aber auch das Win32 Makro ListView_GetISearchString verwenden.

bool GetItem(TListWindItem& item, int index = -1,int subitem = -1) const;
(Botschaft LVM_GETITEM)
Liefert Attribute des durch index und subitem angegebenen Eintrags in item zurück. TListWindItem ist eine Hülle um eine LV_ITEM Struktur, dessen Element iItem auf index und iSubItem auf subitem gesetzt wird, bevor die Botschaft LVM_GETITEM versendet wird.

int GetItemCount() const;
(Botschaft LVM_GETITEM)
Liefert Attribute des durch index und subitem angegebenen Eintrags in item zurück. TListWindItem ist von der LV_ITEM Struktur abgeleitet, dessen Element iItem auf index und iSubItem auf subitem gesetzt wird, bevor die Botschaft LVM_GETITEM versendet wird.

bool GetItemPosition(int index, POINT far*);
bool GetItemPosition(int index, TPoint& pt) const;
(Botschaft LVM_GETITEMPOSITION)
Diese Funktionen geben die Position der oberen linken Ecke des in index angegebenen Eintrags zurück. In der ersten Funktionsvariante wird ein Zeiger auf eine POINT-Struktur übergeben, in der zweiten eine Referenz auf ein TPoint Objekt. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool GetItemRect(int index, RECT far* r, TItemRectType type);
(Botschaft LVM_GETITEMRECT)
Gibt ein umschließendes Rechteck für den in index angegebenen Eintrag in r zurück. type legt den Rechtecktyp fest, der zurückgeliefert werden soll und kann die Werte Bounds, Icon, Label oder SelectBounds des TItemRectType Aufzählunsgtyp annehmen, welche den LVIR_XXXX Konstanten entsprechen. r->left wird vor dem Senden der Botschaft LVM_GETITEMRECT auf type gesetzt, wie vom Windows SDK verlangt. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

uint GetItemState(int index, uint mask) const;
(Botschaft LVM_GETITEMSTATE)
Gibt den aktuellen Zustand des durch index festgelegten Eintrags zurück. mask legt fest, welche Statusflags zurückgeliefert werden sollen.

int GetItemText(int index, int subItem, char* text, int size) const;
(Botschaft LVM_GETITEMTEXT)
Gibt den Text des durch index und subItem festgelegten Eintrags in text zurück. Ist subItem 0, wird die Bezeichnung des Eintrags index in text geliefert. size bestimmt die Größe des durch text festgelegten Puffers. Der Rückgabewert entspricht der Länge der in text zurückgegebenen Zeichenkette.

int GetNextItem(int index, TNextItemCode code) const;
(Botschaft LVM_GETNEXTITEM)
Gibt bei erfolgreicher Ausführung den Index des nächsten Eintrags nach dem durch index festgelegten Eintrags zurück, der den durch code festgelegten Eigenschaften entspricht. TNextItemCode ist ein Aufzählungstyp, der folgende Relations- und Statusflaggen - entsprechend der LVNI_XXXX Konstanten - zur Verfügung stellt. War der Aufruf nicht erfolgreich, wird -1 zurückgegeben.

bool GetOrigin(POINT far* p);
(Botschaft LVM_GETORIGIN)
Ermittlung der aktuellen Darstellung und Ursprung des Listenfensters. p ist ein Zeiger auf eine POINT Struktur, in welcher der Ursprung übergeben werden soll. Bei erfolgreicher Ausführung ist das Funktionsergebnis true. Wird das Listenfenster als Liste oder Report dargestellt ist das Funktionsergebnis false.

int GetSelCount() const;
(Botschaft LVM_GETSELECTEDCOUNT)
Liefert die Anzahl der selektierten Einträge zurück.

int GetSelIndexes(int* indexes, int maxCount) const;
Füllt das Integer Array indexes mit den Indexen der selektierten Einträge. maxCount bestimmt die Anzahl der Elemente, die indexes maximal aufnehmen kann. Vor dem Aufruf von GetSelIndexes sollte man mit der Funktion GetSelCount die Anzahl der selektierten Einträge ermitteln und dann ein entsprechend dimensioniertes Array und dessen Größe an GetSelIndexes übergeben. Der Rückgabewert entspricht der Anzahl von Indexen, die in das Array indexes eingetragen wurden. Benutzt die Liste LVS_SINGLESEL, d.h. die Mehrfachselektion ist nicht gestattet, wird -1 zurückgegeben.

int GetSelStrings(char far** strs, int maxCount, int maxChars, int subItem = 0) const;
Füllt das Array strs mit den Strings der selektierten Einträge. maxCount gibt die Größe von des strs[] Arrays an. maxChars ist die Größe eines Array Elements. subItem zeigt an, welcher Eintrags-String geliefert werden soll. Wenn ein Fehler auftritt, wird -1 zurückgeliefert, ansonsten entspricht der Rückgabewert der Anzahl der gelieferten Strings.

int GetStringWidth(char far* text);
(Botschaft LVM_GETSTRINGWIDTH)
Liefert die Breite des in text angegebenen Textes basierend auf der aktuellen Schriftart des Listenfensters zurück.

COLORREF GetTextBkColor();
(Botschaft LVM_GETTEXTBKCOLOR)
Liefert die Hintergrundfarbe von Text des Listenfenster zurück.

COLORREF GetTextColor();
(Botschaft LVM_GETTEXTCOLOR)
Liefert die Textfarbe des Listenfenster zurück.

int GetTopIndex() const;
(Botschaft LVM_GETTOPINDEX)
Gibt den Index des obersten sichtbaren Eintrags zurück. Wenn das Listenfenster Symbole darstellt, wird 0 zurückgegeben.

bool GetViewRect(RECT far* r);
(Botschaft LVM_GETVIEWRECT)
Gibt in r das begrenzende Rechteck aller Einträge im Listenfenster zurück. Das Listenfenster muß (kleine) Symbole darstellen. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

int HitTest(TLwHitTestInfo& info);
(Botschaft LVM_HITTEST)
Gibt den Index des durch info festgelegten Eintrags zurück. TLwHitTestInfo ist von der Struktur LV_HITTESTINFO abgeleitet.

int InsertColumn(int colNum, const TListWindColumn& colItem);
(Botschaft LVM_INSERTCOLUMN)
Fügt eine neue Spalte in dem Listenfensters ein. colNum bestimmt den Index der neuen Spalte und colItem die einzufügende Spalte. Der Rückgabewert entspricht dem Index der neuen Spalte. Bei einem Fehler wird -1 zurückgeliefert.

int InsertItem(TListWindItem& newItem, int index = -1);
(Botschaft LVM_INSERTITEM)
Fügt den in newItem angegebenen Eintrag in dem Listenfensters ein. Mit index kann der Index des neuen Eintrags festgelegt werden; per Vorgabe wird -1 verwendet. Ist index -1, wird dieser Wert einfach ignoriert, ansonsten wird das Element newItem.iItem der TListWindItem Referenz auf den angegebenen Index gesetzt. Der Rückgabewert entspricht dem Index des neuen Eintrags oder ist im Fehlerfall -1.
WICHTIG: Mit InsertItem() lassen sich keine Subeinträge einfügen! Um diese zu setzen, müssen Sie die Funktion SetItem() verwenden.

bool IsSelected(int index) const;
Liefert zurück, ob der durch index bestimmte Eintrag selektiert ist (true) oder nicht (false).

bool RedrawItems(int startIndex, int endIndex);
(Botschaft LVM_REDRAWITEMS)
Bewirkt ein Neuzeichnen der Einträge von startIndex bis endIndex, indem der diese Einträge umschließende Bereich als ungültig erklärt wird. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false. Die Einträge werden aber erst beim Auftreten einer WM_PAINT Botschaft tatsächlich neu gezeichnet. Sollen die Einträge sofort neu gezeichnet werden, so muß das explizit geschehen, beispielsweise durch einen Aufruf von UpdateWindow().

bool Scroll(int dx, int dy);
(Botschaft LVM_SCROLL)
Rollt den Inhalt des Listenfensters um die in dx und dy angegebenen Werte. Solange keine Report-Anzeige im Listenfenster vorliegt, legt dx den horizontalen Rollwert und dy den vertikalen Rollwert in Pixeln fest. Bei einer Report-Ansicht gibt dx die Anzahl der zu rollenden Spalten und dy die zu rollenden Zeilen an. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool SetBkColor(COLORREF c);
(Botschaft LVM_SETBKCOLOR)
Hintergrundfarbe des Listenfenster auf c festlegen. Soll keine Hintergrundfarbe verwendet werden kann auch CLR_NONE angeben weden. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool SetCallBackMask(uint mask);
(Botschaft LVM_SETCALLBACKMASK)
Setzt die in mask angegebene Callback-Maske. Die verwendbaren LVIS_XXXX Masken finden Sie im Win32 SDK unter der Beschreibung des ListView_SetCallbackMask Makros und LVM_SETCALLBACKMASK. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool SetColumn(int index, const TListWindColumn& column);
(Botschaft LVM_SETCOLUMN)
Setzt die Attribute der durch index festgelegten Spalte in der Spaltenüberschrift eines Listenfensters mit den in column angegeben. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool SetColumnWidth(int index, int width);
(Botschaft LVM_SETCOLUMNWIDTH)
Ändert die Breite einer Spalte in einer Report- oder Listenansicht auf die in width angegebene Breite. In einer Reportansicht kann mit index die zu ändernde Spalte spezifiziert werden. In einer Listenansicht muß als index -1 angegeben werden. Anstelle einer Angabe in View-Koordinaten kann man für width auch einen der Werte LVSCW_AUTOSIZE oder LVSCW_AUTOSIZE_USEHEADER verwenden. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool SetImageList(HIMAGELIST list, TImageListType type)
(Botschaft LVM_SETIMAGELIST)
Setzen der in list festgelegten Bildliste für den in type angegebenen Typ Normal, Small oder State. Der Rückgabewert ist mir allerdings etwas schleierhaft. Im Win32 SDK ist zu sehen, daß der Rückgabewert von LVM_SETIMAGELIST das Handle einer vorherigen Bildliste des angegebenen Typs zurückliefert oder den Wert 0, wenn diesem keine Bildliste zugeordnet wurde. Die OWL beschränkt sich hier lediglich auf einen Vergleich, ob das Funktionsergebnis ungleich 0 ist und liefert in diesem Fall true (d.h. es wurde bereits eine Bildliste zugeordnet), ansonsten false. Das Handle der vorherigen Bildliste wird aber leider nicht zurückgegeben. Normalerweise ist damit zwar auszukommen, aber für den Fall, daß es in Ihrer Anwendung dennoch nötig sein sollte das vorherige Handle in Erfahrung zu bringen, sollten Sie stattdessen die Botschaft LVM_SETIMAGELIST selbst versenden oder auf das Makro ListView_SetImageList zurückgreifen, nachdem die ImageList intanziiert wurde.

HIMAGELIST hImgLst;
hImgLst = ListView_SetImageList(hWindow, hNewImageList, LVSIL_NORMAL);

bool SetItem(TListWindItem& item, int index = -1, int subitem = -1);
(Botschaft LVM_SETITEM)
Setzen von Eintragsattributen. Wird für index oder subItem ein anderer Wert als der Vorgabewert -1 angegeben, werden die Elemente iItem und iSubItem der in item angegebenen TListWindItem Referenz entsprechend eingetragen. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

void SetItemCount(int numItems);
(Botschaft LVM_SETITEMCOUNT)
Bereitet ein Listenfenster zur Aufnahme einer größeren Anzahl von Einträgen vor. numItems ist schließlich die Anzahl der Einträge, die das Listenfenster aufnehmen soll.

bool SetItemPosition(int index, const TPoint& pt);
(Botschaft LVM_SETITEMPOSITION)
Verschiebt den Eintrag mit dem angegebenen Index im Listenfenster auf die in pt angegebene Position. Das Listenfenster muß dabei die Symbolansicht anzeigen. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.
Es gibt weiterhin auch noch eine funktionsgleiche Botschaft LVM_SETITEMPOSITION32, die allerdings 32-Bit-Koordinaten zur Positionsangabe unterstützt und keinen Rückgabewert liefert. Diese wird von der OWL aber nicht bereitgestellt. Sie können aber auch das Win32 Makro ListView_SetItemPosition32 verwenden.

bool SetItemState(int index, uint state, uint mask);
(Botschaft LVM_SETITEMSTATE)
Ändert den Status des Eintrages index auf den Status state und die Maske mask.

bool SetItemText(int index, const TListWindItem& item);
bool SetItemText(int index, int subItem, const char* text);
(Botschaft LVM_SETITEMTEXT)
Diese beiden Funktionen setzen den Text des durch index angegebenen Eintrages. Die erste Funktionsvariante benutzt dazu eine Referenz auf ein TListWindItem und die zweite neben dem Index noch den Index des Subeintrags (subItem) und den zu setzenden Text (text).

bool SetSel(int index, bool select);
Selektiert (select=true) bzw. deselektiert (select=false) den angegebenen Eintrag mit dem angegebenen Index. Der Rückgabewert zeigt an ob der Aufruf erfolgreich war oder nicht.

bool SetSelIndexes(int* indexes, int numSelections, bool select);
Selektiert (select=true) oder deselektiert (select=false) alle im Array indexes enthaltenen Einträge. numSelections gibt die Anzahl der zu bearbeitenden Einträge an. Der Rückgabewert gibt an, ob der Aufruf erfolgreich war oder nicht. Besitzt das Listenfenster beispielsweise die Eigenschaft LVS_SINGLESEL, ist das Ergebnis false, da nur jeweils ein Eintrag selektiert sein darf.

bool SetSelItemRange(bool select, int first, int last);
Selektiert (select=true) oder deselektiert (select=false) alle Einträge in dem durch first und last angegebenen Bereich. Der Rückgabewert gibt an, ob die Operation erfolgreich war oder nicht. Diese Funktion kann mit Listenfenstern, die den Stil LVS_SINGLESEL besitzen, nicht verwendet werden. SetSelItemRange prüft auf diesen Stil und liefert in einem solchen Fall immer false.

bool SetTextBkColor(COLORREF c);
(Botschaft LVM_SETBKCOLOR)
Setzen der Hintergrundfarbe des Listenfensters, wobei c die neue Hintergrundfarbe festlegt. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool SetTextColor(COLORREF c);
(Botschaft LVM_SETTEXTCOLOR
Setzen der Textfarbe für die Einträge des Listenfensters, wobei c die neue Textfarbe festlegt. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool SortItems(const TLwComparator& Comparator, uint32 lParam = 0);
(Botschaft LVM_SORTITEMS)
Sortieren von Einträgen mit einer benutzerdefinierten Vergleichsfunktion. Comparator ist eine Referenz auf ein TLwComparator beziehungsweise davon abgeleitete Klasse, welche die virtuelle Vergleichsfunktion Compare bereitstellt. Mit lParam kann ein anwendungsbezogener Wert übergeben werden, der an die Vergleichsfunktion weitergegeben wird. Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

bool Update(int index);
(Botschaft LVM_UPDATE)
Aktualisierung des durch index festgelegten Eintrags eines Listenfensters. Ist LVS_AUTOARRANGE gesetzt, wird automatisch angeordnet Bei erfolgreicher Ausführung ist das Funktionsergebnis true, ansonsten false.

Übersicht

Stand: 24.02.00 22:00:59
© 1998 by Hans Joachim Kiefer, hajokiefer@handshake.de