Gambas Documentation
Documents

How To Draw with gb.Cairo

The Cairo component implements the very comprehensive Cairo 2D Graphics library. This is a simple "How To" to get started with drawing using this library.

First ensure you have added the GB.Cairo component to your project.

Before you can draw, you need to have an image. This is your "Canvas". You can use a PictureBox or draw directly onto the form. This HowTo will show you how to draw on the form.

Create an object as a new Image object. Set the Width and Height. Here we use the Form's Width and Height so we have the whole form to draw on. 
Dim hImg As New Image(frmMain.W, frmMain.H)

Tell Cairo to begin. Use the Image Object we have define as the parameter. 
Cairo.Begin(hImg)

Set the colour by using the SolidPattern. Colours are set using the RGB values converted to floating point numbers. Do do this, we divide each value by 255. For Example, if we wanted to make the colour gold (#FFD700 rgb(255,215,0)) we set the Cairo.SolidPattern(1,0.8,0) (255/255, 215/255, 0) 
Cairo.Source = Cairo.SolidPattern(224, 224, 224, 0) ' Background. Pattern is RGB

Paint fills the entire drawing area with the SolidPattern ie colour 
Cairo.Paint()

Now we want to make some text on the page. This example prints the text twice. The first is in black and forms the drop shadow, then we use the same text slightly offset in a different colour. 

Cairo.Font.Name = "Serif" ' Set the Font
Cairo.Font.Slant = Cairo.FontSlantItalic ' Make it Italic
Cairo.Font.Weight = Cairo.FontWeightBold ' Make it Bold
Cairo.Font.Size = 60 ' Set the font size in points

Set the colour to black 
Cairo.Source = Cairo.SolidPattern(0, 0, 0)

Move to the X,Y point where we want to begin the text 
Cairo.MoveTo(40, 60)

Now Draw the text. There are two methods, Cairo.DrawText and Cairo.Text. Cairo.DrawText converts the text to Glyphs. For normal text there is no apparent difference between the two. 
Cairo.DrawText("Gambas is the Greatest")
Now you need to tell Cairo to fill the path you have told it to draw 
Cairo.Fill

Now we do it again, just using the Cairo.Moveto to offset the text slightly and choose a slightly different colour 
Cairo.Source = Cairo.SolidPattern(0.5, 0.5, 0.2)
Cairo.MoveTo(43, 63)
Cairo.Text("Gambas is the Greatest")
Cairo.Fill()

Now we print some different text, in a different colour and with a smaller font 
Cairo.Font.Name = "Serif"
Cairo.Font.Slant = Cairo.FontSlantItalic
Cairo.Font.Weight = Cairo.FontWeightBold
Cairo.Font.Size = 20


Cairo.Source = Cairo.SolidPattern(0, 0, 0)
Cairo.MoveTo(40, 90)
Cairo.DrawText("GAMBAS Almost Means Basic")

Let's draw a rectangle. This is filled shape and we draw it using the Cairo.Rectangle function specifying the X and Y where it must start, and the Width and Height. It is drawn using the colour set in the last Cairo.SolidPattern command, illustrating that these settings persist until changed. 
Cairo.Rectangle(30, 100, 700, 300)
Cairo.Fill

Now we change the colour and draw a new rectangle slightly offset from the first for a nice shadowed effect. 
Cairo.Source = Cairo.SolidPattern(0.4, 0, 0)
Cairo.Rectangle(25, 95, 695, 295)
Cairo.Fill

Set a new colour. Let's draw to boxes with text inside. 
Cairo.Source = Cairo.SolidPattern(1, 0.8, 0) ' Gold (255,215,0)

In order to draw the box we have to draw lines. To reduce the amount of repetitive work, we can use a user defined function and just pass parameters to the function. 
DrawBoxText("Main Menu", 35, 130, 140, 25)
DrawBoxText("Test Text", 190, 130, 160, 25)

Tell Cairo that we have finished drawing 
Cairo.End

Assign the image we have drawn (hImg) to the Picture object. In this case the Picture property of the form. 
frmMain.Picture = hImg.Picture

We could have assigned it to a PictureBox like this -> PictureBox1.Picture = hImg.Picture

Here is the Box Drawing Function

Define the function, setting the parameters to gather the values we need. This is only an example and could also include parameters for the Colours or the text and box and the font size etc 

Public Function DrawBoxText(myText As String, StartX As Float, StartY As Float, myWidth As Float, MyHeight As Float)

Set the width of the line we are going to draw. 
    Cairo.LineWidth = 2

Use the Starting X and Y values to determine where to start drawing the box. Offset it by five from the start position so it leaves room for the text 
    Cairo.MoveTo(StartX - 5, StartY - 20)

Draw the first line. Using the Cairo.RelLine function allows us to start from the last set position and simply specify the X and Y offsets from the last position. In this case, we use the myWidth parameter to determine how long the line should be horizontally, and 0 o indicate it should be a horizontal line, ie not end up or down from the start position 
    Cairo.RelLineTo(myWidth, 0)

Draw the next line, starting where the previous one ended (that's what RelLine does as opposed to how Line works). Don't move the X postition, but draw down myHeight amount. 
    Cairo.RelLineTo(0, myHeight)

Now we want to draw the bottom of the box. Because we were left in the bottom right corner of the box, we need to move left back to underneath where we started from. We do this by using a negative value for the X Axis, the value of myWidth and keep the Y axis the same. 
    Cairo.RelLineTo(-myWidth, 0)

The last thing we want to do is join up the lines to complete the box. We keeo the X axis the same, and move up myHeight using a negative value. 
    Cairo.RelLineTo(0, -myHeight)

The Box is now complete. The last step is to tell Cairo to actually draw it. We do this with the Cairo.Stroke command. This command takes all the line commands we've given, combines them with the Line width as well as any of the other properties we have specified (Join, dash etc) and draws them. 
    Cairo.Stroke

As a last step we now move to the originally specified starting postition 
    Cairo.MoveTo(StartX, StartY)

And draw the text. 
    Cairo.DrawText(myText)

The last thing we have to do is tell Cairo to draw the text with the Cairo.Fill instruction. 
    Cairo.Fill

And we can exit the function with End 
End

Notes

This is the barest minimum of what Cairo can do, but should illustrate How To use some of the basic properties, enough to get you started.