RtfLabel.pas
VCL Komponente, die das fensterlose ITextServices-Interface des Windows
RichEdit Controls Version 3.0+ benutzt, um ein Label zu implementieren,
das formatierten Text darstellen kann.
Unterstützte Features sind u.a.:
* vollständige RTF-Formatierung wie WordPad,
* eingebettete Bilder und OLE-Objekte,
* transparenter Hintergrund,
* Zooming zwischen 2% und 6400% und
* automatische Größeanpassung an den Inhalt.
Version 1.3d - die aktuelle Version gibt's immer unter
http://flocke.vssd.de/prog/code/pascal/rtflabel/
Copyright (C) 2006-2009 Volker Siebert <flocke@vssd.de>
Alle Rechte vorbehalten.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
---------------------------------------------------------------------------
Delphi-Versionen: 3, 4, 5, 6, 7, 2005, 2006, 2007, and 2009.
Hinweis: wenn man in der Datei `Rich3Conf.inc´ ganz unten die Zeile
{$DEFINE LANG_GERMAN} aktiviert, dann sind die Fehlermeldungen auf
deutsch.
0. INHALT
1. Anforderungen
2. TRtfLabel
2.1 Installation
2.2 Erläuterung
2.3 Eigenschaften
2.4 Methoden
3. DrawRtfText
3.1 Erläuterung
3.2 Parameter
4. Beispielanwendungen
1. ANFORDERUNGEN
Man braucht entweder eine RICHED20.DLL ab Version 3.0 oder die neuere (und
bessere) MSFTEDIT.DLL (die in Wirklichkeit ein RichEdit 4.1 ist). Die Unit
`RichEditDll.pas´ lädt die beste der vorhandenen Versionen.
Für beide Dateien gilt, dass Microsoft nicht erlaubt, sie in eigenen
Setups weiterzuverteilen.
Eine aktuelle Version von RICHED20.DLL kann man installieren bzw.
aktualisieren, indem man das MSI-Installer Setup ausführt (instmsia.exe /
instmsiw.exe). Weitere Informationen dazu findet man bei Microsoft unter
http://support.microsoft.com/default.aspx?scid=kb;en-us;Q308310.
MSFTEDIT.DLL wurde mit Windows XP SP 1 eingeführt und es ist traurig aber
wahr: es gibt keinen korrekten (legalen) Weg, diese Datei auf anderen
(älteren) Systemen zu installieren.
2. TRTFLABEL
2.1 INSTALLATION
Zuallererst sollte man eine evtl. vorhandene alte Version löschen.
Danach sollte man das Verzeichnis `Source´ aus diesem Archiv zu Delphis
Bibliothekspfad hinzufügen.
Danach muss man den Menübefehl `Datei´ / `Projekt öffnen...´ anwählen, den
Dateityp auf `Delphi-Package (*.dpk)´ ändern und aus dem Verzeichnis
`Packages´ die Datei für die benutzte Delphi-Version öffnen:
RtfLabel_D3.dpk : Delphi 3
RtfLabel_D4.dpk : Delphi 4
RtfLabel_D5.dpk : Delphi 5
RtfLabel_D6.dpk : Delphi 6
RtfLabel_D7.dpk : Delphi 7 oder höher
- In Delphi-Versionen bis einschließlich 7 kommt man in das Package-
Fenster und muss dort den Button `Installieren´ anklicken.
- In Delphi-Versionen ab 2005 muss man zunächst bestätigen, dass es sich
um ein Win32-Projekt handelt. Danach wird das Package wie jedes andere
Projekt in der Projektverwaltung geöffnet. Dort muss man im Kontextmenü
den Befehl `Installieren´ auswählen.
Man sollte nach der Installation die Meldung bekommen, dass die Komponente
`TRtfLabel´ zur Palette hinzugefügt wurde.
Wenn ihr auch den Editor für die Eigenschaft `Caption´ haben wollt, dann
müsst ihr auf dieselbe Weise das Package `RtfLabel_D#D.dpk´ installieren
(derselbe Name wie oben, nur mit einem `D´ am Ende). Dieser Schritt ist
optional und bietet nur eine etwas komfortablere Art, den RTF-Text im
Objektinspektor zu bearbeiten.
2.2 ERLÄUTERUNG
Die Komponente kann zunächst wie ein normales Label benutzt werden. Wenn
in `Caption´ einfacher Text steht, dann wird dieser auch so dargestellt.
Fängt der Text jedoch mit der Zeichenfolge "{\rtf1" an, dann wird der
Inhalt von `Caption´ als formatierter RTF-Text interpretiert. Dabei muss
es sich nicht um so vollständig ausgeprägtes RTF handeln, wie man es aus
Dateien kennt - es geht auch ganz einfach. Der Text
{\rtf1{Der Text enthält \ul unterstrichene\ul0 \b Fettschrift\b0 .}}
wird so dargestellt, wie man es erwartet - teilweise unterstrichen und
teilweise in fetter Schrift. Die Basisinformationen nimmt die Komponente
aus der Standard-Eigenschaft `Font´ (Schriftart, -größe, -farbe).
Man kann aber auch komplette RTF-Dateien laden (Methode: LoadFromFile),
die Bilder und OLE-Objekte enthalten können.
2.3 EIGENSCHAFTEN
Die Komponente verfügt über die folgenden speziellen Eigenschaften:
property AutoSize: Boolean
Wenn gesetzt passt die Komponente seine Größe automatisch an den Inhalt
an. Ist `WordWrap´ gesetzt, dann wird nur der untere Rand angepasst,
ansonsten werden sowohl Breite als auch Höhe entsprechend gesetzt.
property Caption: string
Der Inhalt der Komponente - entweder einfacher Text oder mittels
RTF formatiert.
property Document: ITextDocument2
Liefert die ITextDocument2-Schnittstelle des RichEdit-Controls. Um es
benutzen zu können, müsst ihr `RichTom.pas´ zur uses-Klausel hinzufügen.
Darüber hat man alle Möglichkeiten, den Text programmtechnisch zu
modifizieren. Zur Dokumentation einfach unter http://msdn.microsoft.com/
nach dem Begriff "ITextDocument" suchen (norm. der erste Treffer).
property Padding: TRtfLabelPadding
Hier kann man über die Elemente `Left´, `Top´, `Right´ und `Bottom´ die
für die Formatierung benutzten inneren Ränder angeben.
property Transparent: Boolean
Wenn gesetzt ist der Hintergrund transparent, die Komponente erscheint
also durchsichtig.
property WordWrap: Boolean
Wenn gesetzt wird der Text am rechten Rand der Komponente umgebrochen,
ansonsten nicht. Hat auch Einfluss auf die Eigenschaft `AutoSize´.
property Zoom: Integer
Setzt den Zoom-Faktor für die Anzeige in Prozent. Der Wert darf zwischen
2 und 6400 liegen, der Standardwert ist 100.
Hinweis: Auch das `Padding´ unterliegt diesem Faktor.
2.4 METHODEN
Die Komponente besitzt die folgenden speziellen Methoden:
procedure LoadFromStream(Stream: TStream);
Lädt den Inhalt der Komponente (`Caption´) aus dem angegebenen Stream.
procedure LoadFromFile(const Name: string);
Lädt den Inhalt der Komponente (`Caption´) aus der angegebenen Datei.
Alternativ könnt ihr die Methode `Open´ der Eigenschaft `Document´
benutzen.
3. DRAWRTFTEXT
3.1 ERLÄUTERUNG
Für den Fall, dass man kein Steuerelement benötigt sondern einfach nur
formatierten Text in einen Canvas ausgeben will, findet ihr in der Datei
`DrawRichText.pas´ die Funktion
procedure DrawRtfText(Canvas: TCanvas; var Rect: TRect;
const Text: string; TextFormat: TRtfTextFormat = [];
Zoom: Integer = 100);
3.2 PARAMETER
Canvas: TCanvas
Die Zeichenfläche für die Ausgabe.
Rect: TRect
Das Ausgaberechteck, in das gezeichnet werden soll. Wenn `TextFormat´
das Flag `tfCalcRect´ beinhaltet, dann wird keine Ausgabe erzeugt
sondern stattdessen wird dieses Rechteck angepasst, um die Größe der
Ausgabe widerzuspiegeln. Ansonsten wird dieser Parameter nicht
verändert. Es erfolgt keine Ausgabe außerhalb des Rechtecks.
Text: string
Der RTF-Text, der dargestellt werden soll. Kann alles beinhalten von
einem einzelnen Zeichen bis hin zu ganzen Dokumenten mit Grafiken und
Objekten.
TextFormat: TRtfTextFormat
Gibt weitere Optionen für die Ausgabe:
Horizontale Ausrichtung: rtfLeft, rtfCenter oder rtfRight
Diese Optionen haben nur dann einen Effekt, wen `tfWordBreak´ *NICHT*
angegeben wird und richten die gesamte Ausgabe entsprechend aus.
Vertikale Ausrichtung: rtfTop, rtfVerticalCenter oder rtfBottom
Gibt die vertikale Ausrichtung für die gesamte Ausgabe an.
Zeilenumbruch: rtfWordBreak
Schaltet den Zeilenumbruch am rechten Rand des Ausgaberechtecks ein.
Berechnung der Größe: rtfCalcRect
Ist diese Option angegeben, dann wird die Ausrichtung ignoriert und es
wird keinerlei Ausgabe erzeugt. Stattdessen werden die Felder `Right´
und `Bottom´ von `Rect´ so angepasst, dass sie die Größe der gesamten
Ausgabe widerspiegeln.
Zoom: Integer
Gibt den Zoom-Faktor für die Ausgabe an in Prozent an. Darf zwischen
2 und 6400 liegen.
4. BEISPIELANWENDUNGEN
Im Verzeichnis `Sample´ findet ihr zwei Beispielanwendungen. Ihr könnt sie
ausprobieren, ohne die Komponente installiert zu haben, ihr müsst nur das
Verzeichnis in den Bibliothekspfad aufnehmen (ihr könnt es später leicht
wieder entfernen, falls ihr die Komponente nicht behalten wollt).
`RtfLabelExample´ zeigt den Gebrauch des `TRtfLabel´-Steuerlements und
`DrawRtfTextExample´ ist eine ähnliche Anwendung, die die Benutzung der
Funktion `DrawRtfText´ aus der Unit `DrawRichText.pas´ zeigt.
Fehler wegen unbekannter Eigenschaften beim Öffnen der Formulare könnt ihr
ignorieren. Dabei handelt es sich um Eigenschaften, die in früheren
Delphi-Versionen noch nicht vorhanden waren.
Ab Delphi 2005 müsst ihr beim ersten Öffnen auswählen, dass es sich um
Win32-Projekte handelt. |
