GAMBAS-BUCH 3.19.1

Die Klasse Paint (gb.qt4) besitzt nur (statische) Methoden. Die vielen Methoden sind in den u.a. Tabellen gruppiert notiert, um so Zusammenhänge besser sichtbar werden zu lassen. Nach den Tabellen finden Sie Hinweise zur Verwendung ausgewählter Methoden und Beschreibungen der Parameter.

Das Projekt Painting aus den Gambas-Beispielen sollten Sie sich unbedingt ansehen, weil es nicht nur das Zeichnen mit der Klasse Paint demonstriert, sondern auch den verwendeten (Paint-)Quelltext für die 22 Linien und Flächen anzeigt:

Abbildung 23.3.2.1: Projekt Painting – Beispiel 9: Füllstil

Die Klasse Paint verfügt über diese Methoden:

Methode	Beschreibung
Begin ( Device As Object [ Area As RectF ])	Startet das Zeichnen auf dem angegebenen Device (Zeichenfläche: DrawingArea, Picture, Image, Printer, SVGImage). Der Aufruf kann verschachtelt werden.
End ( )	Beendet das Zeichnen. Sie müssen diese Methode genauso oft aufrufen, wie die Paint.Begin(..)-Methode.
NewPath ( )	Löscht den aktuellen Zeichen-Pfad. Nach dem Aufruf existiert weder ein Pfad und noch ein aktueller (Start-)Punkt.
ClosePath ( )	Fügt ein Linien-Segment zum aktuellen Pfad hinzu und zwar vom aktuellen Punkt bis zum Startpunkt des aktuellen Teil-Pfades (das ist der Punkt, der zuletzt an Paint.MoveTo() übergeben wurde). So wird der aktuelle Pfad geschlossen und der aktuelle Punkt wird zum gemeinsamen Anfangs- und Endpunkt des Pfades.
Scale ( SX As Float, SY As Float )	Ändert die aktuelle Transformationsmatrix (CTM) durch Skalierung der x- und y-User-Space-Achsen mit den Faktoren SX und SY. SX: Skalierungsfaktor für die x-Richtung, SY: Skalierungsfaktor für die y-Richtung
Translate ( TX As Float, TY As Float )	Ändert die CTM durch Verschieben des Koordinatenursprungs um TX und TY. TX: Verschiebungsweite in x-Richtung, TY: Verschiebungsweite in y-Richtung
Rotate ( Angle As Float )	Ändert die CTM durch Drehen der Koordinaten-Achsen bei gegebenem Drehwinkel Angle (Bogenmaß). Die Drehrichtung für positive Drehwinkel entspricht einer Drehung von der positiven x-Achse in Richtung der positiven y-Achse (mathematisch positiv).
Clip ( [ Preserve As Boolean ] )	Erstellt eine neue Clip-Region, indem die aktuelle Clip-Region mit dem aktuellen Pfad geschnitten wird – unter Beachtung der aktuellen FillRule. Nach der Anwendung von Clip() wird der aktuelle Pfad gelöscht, außer das Preserve-Argument ist TRUE. Die aktuelle Clip-Region beeinflusst alle Zeichenoperationen: alle Änderungen außerhalb dieser Region werden ignoriert. Ein Aufruf von Clip() kann die Clip-Region nur kleiner machen, niemals größer, aber der aktuelle Clip ist eine Eigenschaft des Paint-Zustands. Eine temporäre Clip-Einschränkung können Sie erreichen, indem Sie innerhalb eines Paint.Save()-/Paint.Restore()-Paares clippen. Nur Paint.ResetClip() vergrößert die Clip-Region wieder.
ResetClip ( )	Setzt die aktuelle Clip-Region auf ihren ursprünglichen, uneingeschränkten Zustand zurück.
Reset()	Setzt die CTM auf die Identitätsmatrix (Ausgangsmatrix).
Save ( )	Erstellt eine Kopie des aktuellen Paint-Zustands und speichert diese in einem internen Stapel der gespeicherten Zustände. Wenn Wiederherstellen aufgerufen wird, so wird der Zeichnung-Zustand aus dem gespeicherten Zustand wieder hergestellt. Mehrere Aufrufe zum Speichern und Wiederherstellen können verschachtelt werden.
Restore ( )	Stellt den Paint-Zustand wieder her, indem der gespeicherte Zustand aufgerufen wird. Anschließend wird der gespeicherte Zustand aus dem Stapel der gespeicherten Zustände gelöscht.

Tabellen 23.3.2.4.1 : Methoden der Klasse Paint

Die folgenden Hinweise ergänzen die Inhalte der Tabellen. Es werden Argumente näher beschrieben und auf Besonderheiten hingewiesen. Beispiele und vollständige Projekte dagegen finden Sie in den folgenden beiden → Kapiteln 23.3.3 Paint-Projekte 1 und 23.3.4 Paint-Projekte 2.

ClosePath

• ClosePath() ist verschieden von einem LineTo() mit den geeigneten Koordinaten.
• Wenn ein (mit der ersten Methode) geschlossener Pfad mit Stroke() gezeichnet wird, gibt es keine Kappen (Paint.LineCap) an den Linien-Enden, sondern die Linien werden zusammengeführt (Paint.LineJoin).
• Gibt es keinen aktuellen Punkt wenn ClosePath() aufgerufen wird, bewirkt diese Methode nichts.

Kreis und Kreisbogen

Die Hinweise für einen Kreisbogen sind einerseits sehr umfangreich und andererseits zum Teil nur in bestimmten Kombinationen gültig:

• XM : x-Koordinate des Zentrums des Bogens
• YM : y-Koordinate des Zentrums des Bogens
• Radius : Radius des Kreisbogens
• Angle : Startwinkel - gemessen gegen die positive x-Achse
• Length : Maß für den Zentriwinkel
• Pie : Für True ergibt sich ein geschlossener Sektor ('Tortenstück'). Standard ist ein offener Bogen.
• Wenn Length negativ ist, so wird der Bogen im Uhrzeigersinn gezeichnet.
• Werden Angle und Length nicht angegeben, dann wird ein Vollkreis gezeichnet.
• Wenn der Wert Angle festgelegt ist, aber nicht Length, dann wird nichts gezeichnet. Die aktuelle Position wird auf den (End-)Punkt auf dem Kreisbogen eingestellt.
• Um einen elliptischen Bogen statt eines Kreisbogens zu zeichnen, müssen Sie die Ellipse-Methode mit geeigneten Argumenten verwenden.

Abbildung 23.3.2.4.1: Kreisbogen - Kreissektoren

Quelltext:

Public Sub DrawArcs()
  Paint.AntiAlias = True  
    Paint.LineWidth = 1
    Paint.Brush = Paint.Color(Color.Red)
    Paint.Arc(100, 140, 70, Rad(45), 3 * Pi / 2, False)
    Paint.Stroke
    Paint.Arc(260, 140, 70, Pi / 4, Rad(270), True)
    Paint.Stroke
    Paint.Arc(420, 140, 70, Pi / 4, 3 * Pi / 2, True)
    Paint.Fill
    Paint.Dash = [2, 2]
    Paint.Arc(420, 140, 70, Pi / 4 + 3 * Pi / 2, Rad(90), False)
    Paint.Stroke
    Paint.Dash = []  ' Null    
  Paint.AntiAlias = False  
End

Abgerundete Rechtecke

Wenn das optionale Radius-Argument definiert ist, so wird das Rechteck abgerundete 'Ecken' besitzen. Das Argument Radius bestimmt den Radius der Rundung. Der Radius darf nicht größer als die Hälfte der kürzesten Seite des Rechtecks sein.

Polygon – Spezialfall Dreieck

Mit diesem Quelltext wird ein hellblaues Dreieck ABC gezeichnet:

Paint.LineWidth = 1
Paint.Brush = Paint.Color(&C3DDFF) ' hellblau
Paint.Polygon([20, 20, 30, 160, 200, 70]) ' A(20|20), B(30|160) und C(200|70)
Paint.Fill

Ellipsen

Ellipse ( X As Float, Y As Float, Width As Float, Height As Float [ , Angle As Float, Length As Float, Pie As Boolean ] )

• X, Y, Width, Height : Begrenzungsrahmen der Ellipse
• Angle : Startwinkel
• Lenght : Überstrichener Winkel
• Pie : Für True ergibt sich ein geschlossener Sektor. Standard ist ein offener Bogen.
• Wenn Length negativ ist, so wird der Ellipsen-Bogen im Uhrzeigersinn gezeichnet.
• Werden Angle und Length nicht angegeben, so wird eine vollständige Ellipse gezeichnet.
• Wenn der Wert Angle festgelegt ist – aber nicht Length – dann wird nichts gezeichnet. Die aktuelle Position wird auf den (End-)Punkt auf dem Ellipsen-Bogen eingestellt.

Kubische Bezier-Kurve

CurveTo ( X1 As Float, Y1 As Float, X2 As Float, Y2 As Float, X3 As Float, Y3 As Float )

• X1 : x-Koordinate des ersten Stütz-Punktes (Start-Punkt)
• Y1 : y-Koordinate des ersten Stütz-Punktes
• X2 : x-Koordinate des zweiten Stütz-Punktes
• Y2 : y-Koordinate des zweiten Stütz-Punktes
• X3 : x-Koordinate des dritten Stütz-Punktes (Endpunkt)
• Y3 : y-Koordinate des dritten Stütz-Punktes

Gab es keinen aktuellen Punkt vor dem Aufruf von Paint.CurveTo(..), so wird sich die Funktion so verhalten, als ob dem Aufruf die Methode Paint.MoveTo(X1|Y1) vorausging, um einen definierten Anfang zu sichern.

Kubische Bezier-Kurve mit relativen Koordinaten – Version von CurveTo(..)

RelCurveTo ( X1 As Float, Y1 As Float, X2 As Float, Y2 As Float, X3 As Float, Y3 As Float )

• DX1 : x-Offset des ersten Stütz-Punktes (Start-Punkt)
• DY1 : y-Offset des ersten Stütz-Punktes
• DX2 : x-Offset des zweiten Stütz-Punktes
• DY2 : y-Offset des zweiten Stütz-Punktes
• DX3 : x-Offset des dritten Stütz-Punktes (Endpunkt)
• DY3 : y-Offset des dritten Stütz-Punktes

Paint.CurveTo(X+DX1, Y+DY1, X+DX2, Y+DY2, X+DX3, Y+DY3) ist logisch äquivalent zum Aufruf Paint.RelCurveTo (DX1, DY1, DX2, DY2, DX3, DY3) bei einem aktuellen Punkt (X|Y).

Text

Text(Text As String [, X As Float,Y As Float,Width As Float,Height As Float,Alignment As Integer ] )

• X, Y, Width, Height : ein Rechteck, in dem der Text gezeichnet wird
• Alignment : Ausrichtung des Textes im Rechteck
• Ist nur der Text angegeben, so wird der Text am aktuellen Punkt gezeichnet. Die y-Koordinate des aktuellen Punktes bestimmt die BaseLine für den Text.
• Der Begriff 'BaseLine' lässt sich sehr einfach am Wort Ärger beschreiben. Ziehen Sie gedanklich eine Linie vom Fußpunkt des Buchstabens A zum Fußpunkt des kleinen r – das ist die BaseLine.
• Sind neben dem Text nur die Argumente X und Y angegeben, dann wird der Text am Punkt P(X|Y) gezeichnet. Die y-Koordinate von P bestimmt die BaseLine für den Text.
• Andernfalls wird der Text innerhalb des angegebenen Rechtecks gezeichnet. Beachten sie, dass das Rechteck den Text nicht abschneidet!

RichText

RichText ( Text As String [ , X As Float, Y As Float, Width As Float, Height As Float, Alignment As Integer ] )

• Für die optionalen Argumente gelten die gleichen Hinweise wie für die Text()-Methode.
• Da nur ein Pfad erstellt wird, werden durch die <font>-Auszeichnung definierte Schrift-Farben nicht berücksichtigt!

TrimText – TrimRichText

TrimText ( Text As String, W As Float [ , H As Float ] ) As String
TrimRichText ( RichText As String, W As Float [ , H As Float ] ) As String

• Text : Text, der anzupassen ist
• W : Länge des (umschließenden) Rechtecks
• H : optionale Höhe des (umschließenden) Rechtecks. Wenn sie nicht angegeben ist, so wird von der Schriftgröße ausgegangen. Mit anderen Worten: Der Text soll in eine einzige Zeile passen.

DrawImage

DrawImage ( Image As Image, X As Float, Y As Float [ , Width As Float, Height As Float, Opacity As Float, Source As Rect ] )

• Image : Bild, das gezeichnet werden soll
• X, Y : Koordinaten des Anfangspunktes (oben links)
• Width, Height : Wenn angegeben, so wird das Bild auf Breite und Höhe skaliert
• Opacity : Die Deckkraft, die für die Erstellung des Bildes verwendet wird, liegt zwischen 0 (völlig transparent) und 1,0 (völlig undurchsichtig). Standardmäßig liegt der Wert bei 1.
• Source : Wenn angegeben (Datentyp Rect), so wird nur der durch das Rechteck beschriebene Bild-Teil berücksichtigt.

DrawPicture

DrawPicture ( Picture As Picture, X As Float, Y As Float [ , Width As Float, Height As Float, Source As Rect ] )

• Picture : Bild, das gezeichnet werden soll
• X, Y : Koordinaten des Anfangspunktes
• Width, Height : Wenn angegeben, so wird das Bild auf Breite und Höhe skaliert
• Source : Wenn angegeben (Datentyp Rect), so wird nur der durch das Rechteck beschriebene Bild-Teil berücksichtigt.

DrawTextShadow

DrawTextShadow ( Text As String, X As Float, Y As Float, W As Float, H As Float [ , Alignment As Integer, Radius As Integer, Opacity As Float ] )
DrawRichTextShadow ( Text As String, X As Float, Y As Float, W As Float, H As Float [ , Alignment As Integer, Radius As Integer, Opacity As Float ] )

• X, Y, W, H : Definieren das Rechteck, in dem gezeichnet wird
• Alignment : Bestimmt die Ausrichtung des Textes, Standard ist Align.Left
• Radius : Überblendradius in Pixeln. Standardmäßig ist der Wert 1/8 der Schrifthöhe
• Opacity : Die Deckkraft liegt zwischen 0,0 und 1,0. Standardmäßig beträgt der Wert 0,5 (50% transparent)
• Sie müssen Paint.DrawText() oder Paint.RichText() aufrufen, um den eigentlichen Text zum Schatten zu zeichnen.

LinearGradient

LinearGradient ( X0 As Float, Y0 As Float, X1 As Float, Y1 As Float, Colors As Integer[], Positions As Float[] [ , Extend As Integer ] ) As PaintBrush

• X0 : x-Koordinate Startpunkt
• Y0 : y-Koordinate Startpunkt
• X1 : x-Koordinate Endpunkt
• Y1 : y-Koordinate Endpunkt
• Durch die Punkte (X0, Y0) und (X1, Y1) wird eine Strecke der Länge L definiert, die beide Punkte verbindet.
• Colors : Array von Farbwerten
• Positions : Array von Farb-Positionen; 0 für Gradient-Start und 1 für Gradient-Ende. Eine Position q (Float) zwischen 0 und 1 entspricht dem Punkt Q auf der definierten Strecke, der q*L weit vom Startpunkt und (1-q)*L weit vom Endpunkt entfernt ist. Eine Position im Positions-Array wird auch Stopper genannt. Zu einem Stopper gehört die Farbe mit gleichem Index aus dem Colors-Array. Am Stopper hat diese Farbe die größte Intensität.
• Die folgende Abbildung zeigt einen LinearGradient von (0|0) nach (200|70) über die Farben Schwarz, Gelb und Blau. Die Stopper sind bei 0 und 0,3 sowie 1,0 als rote Punkte eingezeichnet.

Abbildung 23.3.2.4.2: LinearGradient

RadialGradient

RadialGradient (CX As Float,CY As Float,Radius As Float,FX As Float,FY As Float,Colors As Integer[],Positions As Float[] [,Extend As Integer ]) As PaintBrush

• CX : x-Koordinate Kreis-Mittelpunkt
• CY : y-Koordinate Kreis-Mittelpunkt
• Radius : Radius des Kreises
• FX : x-Koordinate für den Gradienten-Mittelpunkt
• FY : y-Koordinate für den Gradienten-Mittelpunkt
• Colors : Array von Farbwerten (Stop)
• Positions : Array von Farb-Positionen; 0 für Gradient-Start und 1 für Gradient-Ende