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

Copyright (C) 2006, 2007 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, 5, 6, 7, 2005 und 2006.

Hinweis: Delphi 3 benötigt einen Eingriff von Hand - siehe Kasten in
  Abschnitt 2.1.

Hinweis 2: Delphi 4 sollte mit einem der Pakete für Delphi 3 oder 5
  funktionieren, das habe ich aber bis jetzt nicht testen können.

Hinweis 3: 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


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 den Menübefehl `Datei´ / `Projekt öffnen...´ anwählen, den
Dateityp auf `Delphi-Package (*.dpk)´ ändern und das entsprechende Package
`RtfLabel_D#.dpk´ für die jeweilige Delphi-Version öffnen
(D9 = Delphi 2005, D10 = Delphi 2006).

+------------------------------------------------------------------------+
| DELPHI 3:                                                              |
|                                                                        |
| Öffnet jetzt jeweils die Dateien `RichEdit2.pas´, `RichOle.pas´ und    |
| `TextServ.pas´ und ersetzt dort (über Suchen und Ersetzen) den Text    |
| "{$EXTERNALSYM" durch "//{$EXTERNALSYM", da dieses Feature von dieser  |
| Delphi-Version noch nicht unterstützt wird. Danach sollte es auch      |
| unter Delphi 3 problemlos funktionieren.                               |
+------------------------------------------------------------------------+

- 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. Hier muss man über das
  Kontextmenü den Befehl `Installieren´ auswählen.

Man sollte nach der Installation die Meldung bekommen, dass die Komponente
`TRtfLabel´ zur Palette `Flocke´ 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 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.