RtfLabel, Version 1.3a (alt)

Hinweis: dies ist nicht die neueste Version!

Zurück zur Übersicht

Datei: README.txt

RtfLabel.pas

VCL component using the windowless ITextServices interface of the windows
richedit control version 3.0+ to implement a label that displays rich text.

Supported features include:
  * full RTF formatting like WordPad,
  * embedded pictures and OLE objects,
  * transparent background,
  * zooming from 2% to 6400%, and
  * automatic sizing to fit the content.

Version 1.3a - always find the most current version at
http://flocke.vssd.de/prog/code/pascal/rtflabel/

Copyright (C) 2006 Volker Siebert <flocke@vssd.de>
All rights reserved.

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 versions: 7, 2005, and 2006.
Versions 5 and 6 *MAY* work but I haven't tested that (Infos welcome).


0.  CONTENTS

    1. Requirements
    2. TRtfLabel
       2.1 Installation
       2.2 Usage
       2.3 Properties
       2.4 Methods
    3. DrawRtfText
       3.1 Usage
       3.2 Parameters
    4. Sample Applications


1.  REQUIREMENTS

You need either a RICHED20.DLL version 3.0 on your system or the newer
(and better) MSFTEDIT.DLL (which is in fact a richedit version 4.1). The
module `RichEditDll.pas´ looks for the installed versions and takes the
best one.

For both files, it is not allowed from Microsoft to redistribute them with
your own setups.

The latest version of RICHED20.DLL can be installed or updated by simply
installing a windows MSI installer setup (instmsia.exe / instmsiw.exe).
Look at http://support.microsoft.com/default.aspx?scid=kb;en-us;Q308310
for more information about this from Microsoft.

MSFTEDIT.DLL was introduced in Windows XP SP 1, and it is sad to say that
there is no proper (legal) way to get it installed on other systems.


2.  TRTFLABEL

2.1  INSTALLATION

`TRtfLabel´ is a component, so it must be installed in a package. After
that it will be available from the palette `Flocke´ and can be used like
other controls. Alternatively you can create it at runtime (see the sample
application).

First, add the path to the source files in this archive to Delphi's library
path. Alternatively you can simply copy all files over to a directory that
is already in the library path. Then you must add the file `RtfLabel.pas´
to a runtime package of your choice, normally `Borland User Components´ is
used for this. After that, the package has to be compiled and installed. If
you are an absolute newbie, you might find some useful information at these
pages:

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

If you'd like to install the property editor for the `Caption´ property,
you have to install the file `RtfLabel_Caption_Editor.pas´ into a *DESIGN
TIME* package. This is optional and just provides a more convinient way to
edit the RTF source in the object inspector.

I promise the next release has ready-to-go packages for both files ;)


2.2  USAGE

The component can be used like a normal label. If there's plain text in the
`Caption´ property, then plain text is displayed.

If the text starts with "{\rtf1", then it is interpreted as formatted RTF
text (`rich text´). It does not have to be fully qualified RTF like you can
see in files created by some text applications - it can be quite simple.
The following text

{\rtf1{This contains \ul underlined\ul0 \b bold\b0  text.}}

will be displayed as you might expect it: partially underlined and also
partially bold. The basic information to format the text is taken from the
components `Font´ property (font name, size, color).

You can also load complete RTF files into the component (using the method
LoadFromFile) that may contain pictures and OLE objects.


2.3  PROPERTIES

property AutoSize: Boolean

  If set the component automatically adjusts its size to fit its content.
  If `WordWrap´ is set, only the height is adjusted, otherwise both width
  and height.

property Caption: string

  The content of the component - either plain text or formatted using RTF.

property Document: ITextDocument2

  Returns the ITextDocument2 interface of the richedit control. You have to
  add `RichTom.pas´ to your uses clause in order to use it.

  Through this interface it is possible to modify the component's contents
  programmatically. Doc. is available from http://msdn.microsoft.com -
  just search for the phrase "ITextDocument" (try the first hit).
  
property Padding: TRtfLabelPadding

  Use the four elements `Left´, `Top´, `Right´, and `Bottom´ to set an
  inner border used for formatting the text.

property Transparent: Boolean

  If set the component is transparent.

property WordWrap: Boolean

  If set text is wrapped at the right margin, otherwise not. Also has
  influence on the `AutoSize´ property.

property Zoom: Integer

  Sets the zoom factor to the specified value in percent. Possible values
  are between 2 to 6000, the default value is 100.
  Note: the zooming is also applied to the `Padding´.


2.4  METHODS

procedure LoadFromStream(Stream: TStream);

  Load the contents (`Caption´) from the given stream.

procedure LoadFromFile(const Name: string);

  Load the contents (`Caption´) from the given file. Alternatively you can
  use the method `Open´ of the `Document´ property.


3.  DRAWRTFTEXT

3.1  USAGE

In case you don't need a control but just want to paint some formatted
text onto a canvas, use the included unit `DrawRichText.pas´. It contains
the only public procedure

  procedure DrawRtfText(Canvas: TCanvas; var Rect: TRect;
    const Text: string; TextFormat: TRtfTextFormat = [];
    Zoom: Integer = 100);


3.1  PARAMETERS

Canvas: TCanvas

  The canvas to paint upon.

Rect: TRect

  The rectangle to paint into. If `TextFormat´ contains `tfCalcRect´, no
  output is painted but this rectangle is updated to reflect the size of
  painted text. Otherwise, this parameter is not modified. Nothing is
  painted outside this rectangle.

Text: string

  The RTF text to paint. Can contain anything from a single character up
  to a complete document with images and objects.

TextFormat: TRtfTextFormat

  Specifies some options for the output:

  Horizontal alignment: rtfLeft, rtfCenter, or rtfRight

    This only has an effect when tfWordBreak is *NOT* specified and aligns
    the whole output (not each line).

  Vertical alignment: rtfTop, rtfVerticalCenter, or rtfBottom

    This aligns the whole output vertically.

  Word break: rtfWordBreak

    Switches on word break (word wrap) at the right edge of `Rect´.

  Output size calculation: rtfCalcRect

    If this option is given, the alignment parameters are ignored and no
    output is painted onto the canvas. Instead, the fields `Right´ and
    `Bottom´ of `Rect´ are adjusted to reflect the dimensions of the
    output.

Zoom: Integer

  Specifies a zoom factor from 2 to 6000 in percent.


4.  SAMPLE APPLICATIONS

There are two sample applications in the sub-directory `Sample´. You can
try them without installing the component, you just have to add the path
to them to Delphi's library path (you can remove if later easily if you
don't want to keep the components).

`RtfLabelExample´ demonstrates the usage of the `TRtfLabel´ control and
`DrawRtfTextExample´ is a similar application that shows the use of the
`DrawRtfText´ function from `DrawRichText.pas´.

You can ignore errors you get when opening the forms. Their origin are
properties that didn't exist in older Delphi versions.
Flocke's Garage
Valid HTML 4.01 Transitional Valid CSS!
(C) 2005-2013 Volker Siebert.
Creative Commons-LizenzvertragDer gesamte Inhalt dieser Webseite steht unter einer Creative Commons-Lizenz (sofern nicht anders angegeben).