RtfLabel, Version 1.3a (alt)

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.3a - die aktuelle Version gibt's immer unter
http://flocke.vssd.de/prog/code/pascal/rtflabel/

Copyright (C) 2006 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: 7, 2005 und 2006.
Die Versionen 5 und 6 *KÖNNTEN* funktionieren, aber das habe ich nicht 
getestet (Bitte um Rückmeldungen).

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


`TRtfLabel´ ist eine Komponente, daher muss sie in ein Package installiert
werden. Danach kann man sie aus der Palette `Flocke´ auswählen und wie ein
Label benutzen. Alternativ kann man auch zur Laufzeit ein entsprechendes
Element erzeugen (siehe dazu die Beispielanwendung).

Zunächst sollte man das Verzeichnis der Dateien aus diesem Archiv zu
Delphis Bibliothekspfad hinzufügen. Alternativ kann man die Dateien
natürlich einfach in ein Verzeichnis kopieren, dass schon im Bibliotheks-
pfad steht. Danach muss man die Datei `RtfLabel.pas´ zu einem Laufzeit-
package seiner Wahl hinzufügen, normalerweise nimmt man `Borland Anwender-
komponenten´ dafür. Abschließend muss das Package kompiliert und
installiert werden. Wenn ihr absolute Newbies auf diesem Gebiet seid, dann
findet ihr auf diesen beiden Seiten vielleicht nützliche Informationen:

- http://delphi.about.com/library/howto/htinstallcomponent.htm
- http://delphi.about.com/od/vclusing/ss/installpasvcl.htm

Optional könnt ihr noch den Editor für die Eigenschaft `Caption´
installieren. Dazu müsst ihr die Datei `RtfLabel_Caption_Editor.pas´ zu
einem *ENTWURFSZEITPACKAGE* hinzufügen. Dieser Schritt ist optional und
bietet nur eine etwas komfortablere Art, den RTF-Text im Objektinspektor
zu bearbeiten.

Ich verspreche: in der nächsten Version sind fertige Packages für beide
Dateien dabei ;)


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 stellt der
Inhalt von `Caption´ formatierten RTF-Text dar. 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 beim Öffnen der Fomulare könnt ihr ignorieren. Dabei handelt es sich
um Eigenschaften, die in früheren Delphi-Versionen noch nicht vorhanden
waren.