Gambas Documentation
Application Repository
Code Snippets
Compilation & Installation
Controls pictures
Deprecated components
Developer Documentation
Development Environment Documentation
Error Messages
Gambas Playground
How To's
How To Change the Tab Order of GUI Controls
How To Contribute
How to Create and Open a ".gmail.txt" Archive
How to deal with Git and Gitlab concerning your Project
How to deal with Git and Gitlab for Gambas
How To Deal With Subversion for Gambas
How To Display a Chinese Character
How To Draw with gb.Cairo
How To Enter Data With gb.db.form
How To Get Gambas Web Started (1)
How To Get Started
How To Interface Gambas With External Libraries
How To make a chart with the gb.chart component
How to make a report with Gambas
How To Make KDE Run Gambas Executables Automatically
How To Open, Debug & Compile The IDE
How To Open a MySQL connection and use it
How To Open a SQLite connection and use it
How To Open a Unix ODBC connection and use it
How To Package Gambas
How To Package your Project
How To Print
How to Run Gambas and Gambas Apps on Windows using WSL
How To Run Gambas On Windows using Cygwin
How To Translate A Gambas Project
How To Translate Gambas
How To Translate The Gambas IDE (deprecated)
How To Use Parallel Port
Language Index
Language Overviews
Last Changes
Search the wiki
To Do
Wiki License
Wiki Manual

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.

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

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

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")

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)

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)

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

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.

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

And draw the text.

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

And we can exit the function with End


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.