Programmieren mit C++

Das Drucken und Bedrucken von Formularen ist eine so häufig benötigte Anwendung, daß es sinnvoll ist, eine spezielle, leistungsfähige Druck-Engine für Formulare zu entwickeln. Diese sollte einerseits flexibel und universell einsetzbar sein, andererseits sollte sie jedoch alle Standardaufgaben selbständig abwickeln können, ohne daß in abgeleiteten Objekten Eingriffe des Programmierers notwendig sind.

Die nachfolgend vorgestellte Lösung ist modular aufgebaut. Auf der untersten Ebene steht ein einzelnes druckbares Element. Dieses besitzt spezielle Attribute wie

Modularer Aufbau

• Elementart (Linie, Text etc.)
• Farben (Linie, Füllung etc.)
• Druckposition (linke obere Ecke)
• Inhalt (Wert eines Strings)

Diese Attribute werden als Record definiert. Die Speicherung auf externe Medien erfolgt nicht in binärer Form, sondern als ANSI-Textdatei. Dieses Format ermöglicht das Erstellen und Ändern von Formularen mit jedem beliebigen Texteditor, so daß nicht zwangsläufig immer ein vorgegebener Formular-Editor verwendet werden muß.

Elementattribute

Das Verwalten der einzelnen druckbaren Elemente erfolgt in einer Kollektion. Diese kann nach den Ausgabepositionen sortiert sein, was dann zu einem kontinuierlichen Ausgabefluß von links oben nach rechts unten führt. Allerdings können sortierte Kollektionen nicht dahingehend optimiert werden, daß nur die tatsächlich notwendigen Formatmerkmale gespeichert werden. Wenn z. B. mehrere Zeichenketten mit der gleichen Schriftart zu drucken sind, würde es genügen, einmal einen Schriftarten-Record aufzunehmen und diese Schrift zu verwenden, bis eine neue Schrift selektiert wird.

Elementverwaltung

Die Klasse TPrintEngine geht einen Mittelweg zwischen der vollständigen Speicherung und der ablaufgesteuerten Aufzeichnung, indem Schriften separat gespeichert und über Index adressiert werden. Dazu speichert TPrintEngine entsprechende Schriftenbeschreibungs-Records, die zur Laufzeit in einer separaten Liste gehalten werden.

Schriftindizierung

In der Klasse TPrintEngine werden sowohl die Schriftenliste als auch die Beschreibung der zu druckenden Formulare verwaltet. TPrintEngine übernimmt auch die komplette Ablaufsteuerung des Druckvorgangs, der über Methoden und Members kontrolliert wird.

Speicherformat

Die Klasse TPrintEngine und ihre Objekte speichern alle Informationen über die Formularbeschreibungen in Textdateien, die mit jedem ANSI-Editor bearbeitet werden können. Das Format ist grundsätzlich:

Klasse TPrintEngine

@ELEMENTNAME; Attribut 1; Attribut 2; …;
Attribut N

@ELEMENTNAME ist ein eindeutiger Bezeichner, der das jeweilige Druckelement identifiziert. Die zugehörigen Attribute werden als Zahlenwerte oder als reiner Text durch Semikolon getrennt aufgeführt. Die Anzahl der Attribute darf variieren und muß nur von der eingesetzten Print-Engine korrekt interpretiert werden. Aus diesem Grund ist der erste Satz jeder Formulardatei eine Signatur, die die Versionsnummer der verwendeten Print-Engine enthält. Elemente, die von der lesenden Print-Engine nicht erkannt werden können, werden einfach überlesen.

Alle Positionsangaben erfolgen in Millimeter, bezogen auf den linken oberen Rand des Formulars. Eventuelle Offsets infolge eines nicht bedruckbaren Randes werden hierbei nicht berücksichtigt, sondern über spezielle Members der Klasse TPrintEngine gehandhabt.

Druckelemente

Die Druckelemente beschreiben jedes einzelne Element des Formulars. Intern verwendet die Klasse TPrintEngine zur temporären Speicherung eine Liste mit Zeigern auf Druckelementbeschreibungen, so daß die einzelnen Elementbeschreibungen unterschiedliche Längen und Strukturen haben können. Die Identifikation des jeweiligen Elementtyps erfolgt über das erste Wort der Struktur, das als WORD wie folgt zu interpretieren ist:

Record-Aufbau

Durch Erweiterung dieser Elementtypen kann die Engine jederzeit um neue Befehle erweitert werden. Analog dazu müssen dann jedoch auch die Module zum Einlesen, Speichern und Bearbeiten der Elementtypen erweitert werden.

Die speziellen Attribute der jeweiligen Druckelemente werden nachfolgend beschrieben.

Elementtypen

Das Element TPE_Version dient als Signatur und Versionskontrolle der Druck-Engine. Das Format lautet:

@TPEVERSION; Hauptversion; Nebenversion

In Hauptversion steht die Hauptversionsnummer als Integer-Wert. Dieser ist in der vorliegenden Implementation „1“. Die Nebenversionsnummer wird aktuell mit „0“ angegeben und kann kleinere Abweichungen innerhalb einer Implementationsstufe als Integer-Wert erfassen.

Element TPE_Version

typedef struct tagTPEVersion {
  int Major, 
  int Minor
} TTPEVersion;

Struktur TTPEVersion

Schriften werden über den Namen der Schrift, der Schriftfamilie und der speziellen Attribute beschrieben:

@FONT; Name; Familie; Punkt; Fett; Kursiv; Underline; Index

Als Name wird der übliche Name der Schrift wie „Arial“ oder „Times New Roman“ gespeichert. Als Familie ist der numerische Wert der Schriftfamilie anzugeben, wie er gemäß Windows-SDK vorgegeben ist. Das Objekt akzeptiert jedoch auch die entsprechenden Symbole:

Die Schriftgröße wird in Punkt angegeben, damit eine Umrechnung der Größe in Abhängigkeit von der Druckauflösung jederzeit möglich ist. Fett, Kursiv und Underline sind Boolesche Werte, die als Wörter „TRUE“ oder „FALSE“ gespeichert werden. Alternativ kann man für Boolesche Werte auch „0“ (FALSE) und „1“ (TRUE) verwenden.

Index bezeichnet den Index in die Schriftenliste, auf die sich nachfolgende Einträge beziehen, die Schriften verwenden. Ist kein Wert für Index vergeben, numeriert das Objekt die Schriften während des Einlesens des Formulars in der Reihenfolge des Vorkommens durch.

Element TPE_Font

typedef struct tagTPEFont {
  char[255] Name,
  int       Familie,
  int       Punkt,
  BOOL      Fett,
  BOOL      Kursiv,
  BOOL      Underline,
  int       Index
} TTPEFont;

Struktur TTPEFont

Das Element TPE_Line beschreibt eine Linie. Linien können beliebige Richtungen haben und Zeichenattribute besitzen.

@LINE; Left; Top; Right; Bottom; Width;
Style; Color

Element TPE_Line

typedef struct tagTPELine {
  int Left, int Top,
  int Right, int Bottom,
  int Width,
  int Style,
  DWORD Color
} TTPELine;

Left, Top, Right und Bottom bezeichnen die beiden Endpunkte der Linie. Width gibt die Breite des Stifts in virtuellen Einheiten an. Style bezeichnet den Stil des verwendeten Stifts gemäß Windows-SDK. Unterstützt werden neben den numerischen Werten auch die üblichen Symbole als Klartext:

Color nimmt die Farbe der Linie als LongInt-Wert im RGB-Format auf.

Struktur TTPELine

Rechtecke können mit und ohne Füllung gezeichnet werden. Die entsprechenden Attribute sind entsprechend komplex:

Element TPE_Rect

Left, Top, Right und Bottom spezifizieren die linke obere und die rechte untere Ecke des Rechtecks. Die Attribute LineWidth, LineStyle und LineColor entsprechen den Attributen des Elements TPE_Line.

Als FillStyle werden derzeit nur zwei Werte akzeptiert:

Die Farbe der Füllung wird in FillColor als LongInt-Wert im RGB-Format definiert. Damit ergibt sich der Record zur internen Verwaltung wie folgt:

typedef struct tagTPERect {
  int   Left,  int Top,
  int   Right, int Bottom
  int   LineWidth,
  int   LineStyle
  DWORD LineColor,
  int   FillStyle,
  DWORD FillColor
} TTPERect;

Struktur TTPERect

Als Variante zum Standard-Rechteck unterstützt die Print-Engine auch abgerundete Rechtecke nach Windows-Norm. Gegenüber normalen Rechtecken kommen nur zwei Parameter zur Spezifikation der Ellipse für die Eckenrundung hinzu:

Element TPE_RoundRect

Der Verwaltungs-Record besitzt den Aufbau:

typedef struct tagTPERoundRect {
  int   Left,  int Top,
  int   Right, int Bottom,
  int   EX,    int EY,
  int   LineWidth,
  int   LineStyle,
  DWORD LineColor,
  int   FillStyle,
  DWORD FillColor
} TTPERoundRect;

Struktur TPERoundRect

Das Druckelement Kreis schließt die Variante Ellipse mit ein. Beide werden unter Windows über das umschließende Rechteck spezifiziert. Der Aufbau des Records wie auch das Textformat lauten daher analog zum Rechteck:

Element TPE_Circle

typedef struct tagTPECircle {
  int   Left,  int Top,
  int   Right, int Bottom,
  int   LineWidth,
  int   LineStyle,
  DWORD LineColor,
  int   FillStyle,
  DWORD FillColor
} TTPECircle;

Struktur TTPECircle

Mit dem Druckelement TPE_Text werden Standardtexte definiert, die als feste Textbausteine auf dem Formular plaziert werden sollen. Das Format lautet:

@TEXT; Left; Top; Adjust; Value; Index

Die Ausgabeposition wird immer über die Basislinie angegeben, damit sich verschiedene Schriften auf gleicher Schreiblinie höhengleich zeichnen lassen. (Left, Top) gibt daher den entsprechenden Fixpunkt an, der durch den Parameter Adjust zusätzlich interpretiert wird. Adjust bezeichnet die Ausrichtung des Textes. Möglich sind:

Der Inhalt des auszugebenden Texts wird in Value als unveränderbarer Text spezifiziert, während Index die einzusetzende Schrift adressiert. Ist die Schrift in der Schriftenliste nicht vorhanden, verwendet die Print-Engine eine Standardschrift.

Element TPE_Text

typedef struct tagTPEText {
  int   Left, int Top,
  int   Adjust,
  char[255] Value,
  int   Index
} TTPEText;

Das Druckelement nimmt keinen Zeilenumbruch vor. Es wird erwartet, daß Texte entsprechend dem Formularaussehen definiert werden.

Struktur TTPEText

Über das Element TPE_Variable können Texte mit variablem Inhalt ausgegeben werden. Der Aufbau des Formats und des Records entspricht dem des Elements TPE_Text, jedoch ist die Angabe eines Default-Werts überflüssig. Dafür wird zusätzlich der Name der Variable spezifiziert:

@VARIABLE; Left; Top; Adjust; Index; Name

Zur Laufzeit kann das Druckelement mit der Bezeichnung Name in der Liste der Druckelemente gefunden und der Inhalt von Value besetzt werden.

Element TPE_Variable

typedef struct tagTPEVariable {
  int Left, int Top,
  int Adjust,
  char[255] Value,
  int Index,
  char[255] Name
} TTPEVariable;

Der gesetzte Inhalt der Variable ist wiederum ein Text. Sind variable numerische Werte auszugeben, müssen diese zuvor von der Anwendung in einen String umgewandelt werden.

Die Schreibweise des Namens wird ignoriert. TPrintEngine setzt alle Variablennamen in Großbuchstaben um.

Struktur TPEVariable

Bitmaps lassen sich an jede beliebige Position plazieren. Bei der Formulardefinition ist zu beachten, daß die Print-Engine keinerlei Überprüfungen bezüglich eventueller Überlappungen vornimmt. Die Druckelemente werden in der Reihenfolge ausgegeben, in der sie in der Formulardatei enthalten sind.

@BITMAP; Left; Top; Right; Bottom; RC; Datei

Die Print-Engine plaziert die Bitmap in das durch (Left, Top) und (Right, Bottom) spezifizierte Rechteck. Über RC kann eine der von Windows unterstützten ternären Rasteroperationen gewählt werden. Diese sind in Compiler-Handbüchern bzw. Online-Hilfen ausführlich beschrieben und sollen hier nicht noch einmal aufgelistet werden.

Element TPE_Bitmap

typedef struct tagTPEBitmap {
  int   Left,  int Top,
  int   Right, int Bottom,
  DWORD RC,
  char[255] Datei,
  HANDLE Handle
} TTPEBitmap;

Enthält Handle ein gültiges Handle, verwendet die Print-Engine die zugehörige Bitmap, ansonsten wird die Bitmap aus der Datei geladen. Der Dateiname wird gemäß Windows- bzw. DOS-Richtlinien interpretiert.

Struktur TTPEBitmap

Windows Metafiles lassen sich an jede beliebige Position plazieren, wobei auch Metafiles nach dem ALDUS-Standard akzeptiert werden. Bei der Formulardefinition ist zu beachten, daß die Print-Engine keinerlei Überprüfungen bezüglich eventueller Überlappungen vornimmt. Die Druckelemente werden in der Reihenfolge ausgegeben, in der sie in der Formulardatei enthalten sind.

@METAFILE; Left; Top; Right; Bottom; Datei

Die Skalierung des Metafiles erfolgt immer auf das durch (Left, Top) und (Right, Bottom) gegebene Rechteck. Eine Änderung des Abbildungsmodus zur Anpassung etwaiger Aspektverschiebungen ist in der vorliegenden Implementierung der print-Engine nicht vorgesehen.

Element TPE_Metafile

typedef struct tagTPEMetafile {
  int   Left,  int Top,
  int   Right, int Bottom,
  char[255] Datei,
  HANDLE Handle
} TTPEMetafile;

Enthält Handle ein gültiges Handle, verwendet die Print-Engine das zugehörige Metafile, ansonsten wird das Metafile aus der Datei geladen. Der Dateiname wird gemäß Windows- bzw. DOS-Richtlinien interpretiert.

Struktur TTPEMetafile

Das Druckelement TPE_CheckMark wurde speziell für Formulare eingeführt. Es besitzt das Aussehen eines Kästchens, in das ein Kreuz plaziert werden kann. Im Gegensatz zu den statischen Teilelementen TPE_Rect und TPE_Line, mit denen ein solches Kästchen ebenfalls aufzubauen wäre, ist TPE_CheckMark eine Variable, deren Wert sich ändern kann, was sich auch im Format ausdrückt:

@CHECKMARK; Left; Top; Right; Bottom;
LineWidth; LineColor; Checked; Name

In Checked wird ein Default-Wert gesetzt, wenn z. B. ein Kästchen immer angekreuzt sein soll. Gültige Werte sind „0“ bzw. „FALSE“ und „1“ bzw. „TRUE“.

LineWidth und LineColor entsprechenden den analogen Parametern des Druckelements TPE_Line.

Name bezeichnet den Namen der Variable. Die Schreibweise des Namens wird nicht berücksichtigt. TPrintEngine setzt alle Variablennamen in Großbuchstaben um.

Element TPE_CheckMark

typedef struct tagTPECheckMark {
  int   Left,  int Top,
  int   Right, int Bottom,
  int   LineWidth,
  DWORD LineColor,
  BOOL   Checked,
  char[255] Name
} TTPECheckMark;

Struktur TTPECheckMark

Das Druckelement TPE_CheckCircle entspricht dem Element TPE_CheckMark, nur mit dem Unterschied, daß statt eines Kästchens ein Kreis gezeichnet wird. Das Format lautet:

@CHECKCIRCLE; Left; Top; Right; Bottom;
LineWidth; LineColor; Checked; Name

Die Eckkordinaten werden hierbei als umhüllendes Rechteck für den Kreis verwendet, der auch eine Ellipse sein darf. Das Kreuz läuft von den Eckpunkten zu den jeweils gegenüberliegenden Eckpunkten und ist somit also größer als der Kreis.

Die Datenstruktur lautet:

Element TPE_CheckCircle

typedef struct tagTPECheckCircle {
  int   Left,  int Top,
  int   Right, int Bottom,
  int   LineWidth,
  DWORD LineColor,
  BOOL  Checked,
  char[255] Name
} TTPECheckCircle;

Druckelementverwaltung

Die Verwaltung der Druckelemente erfolgt über die Listenstruktur TPrintItemList, die von TCollection abgeleitet ist.

Die Kollektion TPrintItemList speichert alle Druckelemente in der Reihenfolge, in der sie im Formular gespeichert waren. Eine Sortierung, z. B. nach der Druckposition, findet nicht statt. Jeder Item der Liste enthält einen Zeiger auf einen Record eines Druckelements.

Bearbeitung und Zugriffe auf die einzelnen Records sollten über die Methoden der Klasse TPrintItemList erfolgen.

Struktur TTPECheckCircle

void ClearAllTextVariables();

ClearAllTextVariables löscht den Inhalt aller Text-Variablen, indem der Inhalt des Felds „Value“ auf einen Leerstring gesetzt wird.

Funktion ClearAll-TextVariables

void CheckAllVariables();

CheckAllVariables bearbeitet lediglich die Elementtypen TPE_CheckMark und TPE_CheckCircle. Der Aufruf dieser Methode setzt das Feld „Value“ aller Elemente auf TRUE.

Funktion CheckAllVariables

void UnCheckAllVariables();

UnCheckAllVariables bearbeitet lediglich die Elementtypen TPE_CheckMark und TPE_CheckCircle. Der Aufruf dieser Methode setzt das Feld „Value“ aller Elemente auf FALSE.

Funktion UnCheck-AllVariables

int SetValue(LPSTR Name, 
             LPSTR value)

Mit SetValue kann der Wert der Variable mit dem Bezeichner Name auf den Wert value gesetzt werden. Da in value ein String übergeben wird, kann diese Funktion nur auf Textvariablen angewendet werden.

Das Funktionsergebnis gibt den Erfolg des Aufrufs wieder. Mögliche Werte sind:

Funktion SetValue

int GetValue(LPSTR Name, 
             LPSTR value)

GetValue ermittelt den aktuellen Inhalt der Text-Variable mit dem Bezeichner Name.

Das Funktionsergebnis gibt den Erfolg des Aufrufs wieder. Mögliche Werte sind:

Funktion GetValue

int GetCheck(LPSTR Name)

Mit GetCheck kann der Status einer Check-Variable (TPE_CheckMark, TPE_CheckCircle) ermittelt werden.

Das Funktionsergebnis gibt den Erfolg und das Ergebnis des Aufrufs wieder. Mögliche Werte sind:

Funktion GetCheck

int SaveToText(LPSTR Name)

SaveToText speichert alle Elemente der Kollektion in die Textdatei Name. Dabei werden automatisch alle Records in ein lesbares Textformat konvertiert, das editiert und später wieder mittels ReadFromText geladen werden kann.

Das Funktionsergebnis lautet 0, wenn die Operation erfolgreich abgeschlossen wurde, ansonsten bezeichnet der Rückgabewert den DOS-Fehler.

Funktion SaveToText

int ReadFromText(LPSTR Name)

Mit ReadFromText wird eine in Textformat vorliegende Formularbeschreibung geladen und in das interne Record-Format konvertiert.

Das Funktionsergebnis lautet 0, wenn die Operation erfolgreich abgeschlossen wurde. Ansonsten bezeichnet ein positiver Rückgabewert den DOS-Fehler, während ein negativer Rückgabewert die Zeile spezifiziert, in der ein Konvertierungsfehler auftrat.

Funktion ReadFromText

SaveToBin(LPSTR Name)

SaveToBin speichert alle Druckelemente in einer binären Datei. Dabei werden die Records aufeinanderfolgend abgelegt, wobei die Länge des jeweiligen Records dem Record vorangestellt ist.

Funktion SaveToBin

int ReadFromBin(LPSTR Name)

ReadFromBin liest eine zuvor mittels SaveToBin gespeicherte Kollektion ein.

Das Funktionsergebnis lautet 0, wenn die Operation erfolgreich abgeschlossen wurde, ansonsten bezeichnet der Rückgabewert den DOS-Fehler.

Klasse TPrintEngine

Die Klasse TPrintEngine bildet die Schnittstelle zwischen der Print-Engine und dem Programm. Alle Ablaufsteuerungen sowie Zugriffe auf die einzelnen Druckelemente erfolgen über TPrintEngine.

Intern verwaltet die Klasse die Liste der Druckelemente sowie eine Liste der benötigten Schriften in Form zweier Kollektionen, auf die über Members und Methoden zugegriffen werden kann.

Funktion ReadFromBin

int Error

In Error wird der jeweils zuletzt aufgetretene Fehlercode gespeichert. Mögliche Fehlercodes sind:

Nachdem ein Wert abgefragt wurde, wird er auf 0 zurückgesetzt.

Member Error

int DruckOffsetX

In DruckOffsetX wird der nicht bedruckbare linke Rand des Druckers in mm spezifiziert. Alle Ausgaben werden um diesen Wert korrigiert. Ist der Offset 0, erfolgt die Ausgabe gemäß der Definition der Druckelemente.

Member DruckOffsetX

int DruckOffsetY

In DruckOffsetY wird der nicht bedruckbare obere Rand des Druckers in mm spezifiziert. Alle Ausgaben werden um diesen Wert korrigiert. Ist der Offset 0, erfolgt die Ausgabe gemäß der Definition der Druckelemente.

Member DruckOffsetY

TPrintItemList PrintItems

PrintItems enthält die Liste der Druckelemente. Alle Methoden und Elemente der TPrintItemList können über PrintItems erreicht werden. Zugunsten der Kompatibilität mit späteren erweiterten Versionen sollten Direktzugriffe jedoch sehr restriktiv erfolgen und, wo immer möglich, der offizielle Weg über die Methoden der Klasse bzw. der TPrintItemList gewählt werden.

Member PrintItems

HDC PrintDC

In PrintDC wird der zu verwendende Ausgabekontext gespeichert. Dies ermöglicht der Klasse, den Kontext beliebig zu wechseln und z. B. auf eine Vorschau zu drucken.

Veröffentlichte Methoden

Member PrintDC

LoadFormular(LPSTR Name)

Über LoadFormular wird die Klasse veranlaßt, eine Formularbeschreibung, die im Textformat vorliegt, neu einzulesen. Ein eventuell im Speicher vorliegendes Formular wird dabei zerstört.

Methode LoadFormular

void ClearAllTextVariables()

ClearAllTextVariables löscht den Inhalt aller Text-Variablen, indem der Inhalt des Felds „Value“ auf einen Leerstring gesetzt wird.

Methode ClearAll-TextVariables

void CheckAllVariables()

CheckAllVariables setzt das Feld „Value“ aller Check-Variablen auf TRUE.

Methode CheckAllVariables

void UnCheckAllVariables()

UnCheckAllVariables setzt das Feld „Value“ aller Check-Variablen auf FALSE.

Methode UnCheck-AllVariables

int SetValue(LPSTR Name, 
             LPSTR value)

Mit SetValue kann der Wert der Variable mit dem Bezeichner Name auf den Wert value gesetzt werden. Da in value ein String übergeben wird, kann diese Funktion nur auf Textvariablen angewendet werden. Ein möglicher Fehler wird in Error gespeichert.

Funktion SetValue

int GetValue(LPSTR Name, 
             LPSTR value)

GetValue ermittelt den aktuellen Inhalt der Text-Variable mit dem Bezeichner Name.

Funktion GetValue

int GetCheck(LPSTR Name)

Mit GetCheck wird der Status der Check-Variable Name ermittelt. Der Rückgabewert enthält das Ergebnis 0 oder 1 für FALSE bzw. TRUE oder einen negativen Fehlercode.

Funktion GetCheck

void PrintItem(int Index)

Mit PrintItem wird das in Index adressierte Element auf den aktuell in PrintDC spezifizierten Ausgabekontext ausgegeben. Über Index können alle Elemente der Liste PrintItems adressiert werden. Die Liste beginnt an Indexposition 0.

Methode PrintItem

void PrintAll();

Print druckt das gesamte Formular auf den aktuell in PrintDC spezifizieten Ausgabekontext.

Methode PrintAll