GtkSharp Quick Reference

This quick reference lists classes and methods that you can use to develop simple programs in GtkSharp, targeting GTK 3.

If you want to go beyond what's listed here, unfortunately there is no API documentation for GtkSharp for GTK 3. You can look at the Gtk# 2 documentation, since most GTK 2 classes and methods also exist in GTK 3. Or you could look at the GTK 3 API documentation for C or for Python, since most GTK class/method names in C# will be similar (especially to the Python-based API).

All properties and methods below are public unless otherwise specified.

== Index ==

Cairo
Gdk
GLib
Gtk

== Cairo namespace ==

Cairo is a library for drawing 2-dimensional graphics. GTK integrates closely with Cairo, and most GTK applications use Cairo for visual output.

Context

A Context is used for drawing graphics. Typically you will use a Context object to draw on a window in the OnDrawn handler of a Widget subclass.

Be aware that methods such as Arc(), LineTo() and Rectangle() do not draw - they merely add a geometric shape to the current path. After you call these methods, you must call either Stroke() or Fill() to draw to the output surface.

Context (Surface surface): Create a Cairo context that will draw on the given Surface.
void Arc (double x, double y, double radius, double angle1, double angle2);: Add an arc from angle1 to angle2 to the current path, centered at (x, y). To draw a circle, pass angle1 = 0.0 and angle2 = 2 * Math.PI.
void ClosePath ();: Close the current path, returning to its starting point.
void Fill ();: Fill in the current path with the current color.
void LineTo (double x, double y); void LineTo (PointD p);: Add a line from the current point to the given point.
double LineWidth { set; get; }: Set or get the width of the stroke.
void MoveTo (double x, double y); void MoveTo (PointD p);: Begin a new path at the given point.
void Paint();: Paint the current source everywhere in the the current clip region. Typically you will use this method for drawing an image that you have selected using CairoHelper.SetSourcePixbuf().
void Rectangle (double x, double y, double width, double height);
void Rectangle (Rectangle rectangle);: Add a rectangle to the current path.
void Scale (double sx, double sy);: Add a scaling transformation to the context's transformation matrix.
void SelectFontFace (string family, FontSlant slant, FontWeight weight);: Select a font to use for drawing text.

family should be a generic font family such as "serif", "sans-serif" or "monospace", or the name of a specific font family available on your system.
slant should be FontSlant.Normal or FontSlant.Italic.
weight should be FontWeight.Normal or FontWeight.Bold.

void SetFontSize (double scale);: Set the font size to use for drawing text.
void SetSourceRGB (double red, double green, double blue);: Set the color to be used for drawing to a Cairo context. (To set the color to a GDK color, see SetSourceColor, below.)
void SetSourceSurface (Surface source, int x, int y);: Set the given Surface as a source for drawing at the position (x, y) in the destination. Typically you will make a following call to Paint() to perform the actual drawing operation.
void ShowText (string text);: Draw text. The current position (the "reference point" or "origin") is at the left side of the text to be drawn, along the baseline, so the text will appear above and to the right of the current position.
void Stroke ();: Draw the current path without filling it.
TextExtents TextExtents (string text);: Get a TextExtents object with information about the size of the given text in the currently selected font.
void Translate (double tx, double ty);: Add a translation to the context's transformation matrix.

ImageSurface : Surface

An ImageSurface is a Cairo surface that holds pixel data in memory. You can draw onto an ImageSurface, and then later use the ImageSurface as a source for other drawing operations.

ImageSurface (Format format, int width, int height);: Create an ImageSurface with the given width and height. Typically Format will be either Format.Rgb24, meaning 24-bit color with 8 bits for each color channel (red, green, blue), or Format.Argb32, which is similar but also includes an 8-bit alpha (transparency) channel.

PointD

A PointD represents an (x, y) point. (The "D" stands for "double".)

PointD (double x, double y);: Construct a point from its x and y components.

Rectangle

A Rectangle represents a rectangle on the (x,y) plane. Note that this class (Cairo.Rectangle) is distinct from Gdk.Rectangle, which appears below.

Rectangle (double x, double y, double width, double height);: Construct a Rectangle.
double Height { get; }
double Width { get; }
double X { get; }
double Y { get; }: Retrive the components of a Rectangle.

Surface

Any kind of surface on which Cairo can draw.

TextExtents

A TextExtents structure represents layout information about a particular piece of text. Be aware that the values in this structure are sizes in screen pixels, independent of any coordinate transformation in the graphics context.

double Height { get; }: The height of the text.
double Width { get; }: The width of the text.
double XBearing { get; }: The horizontal distance from the origin (i.e. the point specified by MoveTo before a call to ShowText) to the leftmost part of the text glyphs.
double YBearing { get; }: The vertical distance from the origin to the topmost part of the text glyphs. Typically this will be negative.; In the image below, the red dot is the origin, and blue line represents the bearing. YBearing is negative, and XBearing is slightly negative:

Here is how to draw a string s centered at the point (x, y):

TextExtents te = context.TextExtents(s);
context.MoveTo(x - (te.Width / 2 + te.XBearing),
               y - (te.Height / 2 + te.YBearing));
context.ShowText(s);

== Gdk namespace ==

GDK is a low-level library that sits underneath GTK.

CairoHelper

This class contains a few static utility methods for working with Cairo. (There's also a CairoHelper class in the Gtk namespace, so type "Gdk.CairoHelper" to use this one.)

static void SetSourcePixbuf(Cairo.Context context, Pixbuf pixbuf, double x, double y);: Select a Pixbuf to use for drawing to a Cairo context at position (x, y). Typically you will follow this with a call to context.Paint() to draw the image.
static void SetSourceRgba(Cairo.Context context, RGBA color);: Set the color to be used for drawing to the given Cairo context.

Pixbuf

A Pixbuf holds an image in memory. You can read a Pixbuf from a file and use Cairo to render it to the display.

Pixbuf (string filename);: Read a Pixbuf from a file in JPG, PNG or TIFF format. Throws an exception if the file is not found.
Pixbuf ApplyEmbeddedOrientation ();: Create a new Pixbuf in which the pixel data matches the orientation recorded by the camera for this image.
int BitsPerSample { get; }: The number of bits per color sample in this Pixbuf. This will usually be 8.
bool HasAlpha { get; }: True if this image includes an alpha channel.
int Height { get; }: The height of the image in pixels.
int NChannels { get; }: The number of channels of color data. This will be usually be 3 (for RGB encoding) or 4 (for RGB plus an alpha channel).
IntPtr Pixels { get; }: A pointer to the underlying C data that holds the image pixels. You may read or write the pixel data by copying it to/from a C# array using Marshal.Copy, or by using unsafe C# language constructs that let you access C data directly.
int Rowstride { get; }: The number of bytes in each row of pixel data. This may be NChannels * Width, but may be a larger value if there are padding bytes at the end of each row.
bool Save (string filename, string type);: Save the image to a file. type can be "jpeg" or "png". Return true if the save succeeded.
Pixbuf ScaleSimple (int dest_width, int dest_height, InterpType interp_type): Resize an image to a new width and height, returning a new PixBuf. InterpType is an interpolation type, and can be e.g. InterpType.Bilinear for a reasonable balance between quality and speed, or InterpType.Hyper which produces a higher-quality image but is slower.
int Width { get; }: The width of the image in pixels.

Rectangle

A Rectangle represents a rectangle on the (x,y) plane. Note that this class (Gdk.Rectangle) is distinct from Cairo.Rectangle, which appears above.

Rectangle (int x, int y, int width, int height): Construct a Rectangle.
int Height, Width; int X, Y;: Retrieve the components of a Rectangle.

RBGA

An RGBA represents a color.

RGBA(): Construct a color whose components are all initially 0.
double Red, Green, Blue, Alpha;: The color components, each ranging from 0.0 to 1.0.
bool Parse(string spec): Create a color from a string, which can be either be a standard X11 color name such as "red" or a hexadecimal value in the form “#rrggbb”, e.g. "#6f889f".

== GLib namespace ==

Timeout

static uint Add (uint interval, TimeoutHandler handler);: Request that the given TimeoutHandler be called at regular intervals of interval milliseconds.

TimeoutHandler

delegate bool TimeoutHandler ();: Return true if calls to this TimeoutHandler should continue, or false to cancel the calls.

== Gtk namespace ==

Application

static void Init ();: Initialize GTK. Call this before calling any other GTK methods in your application.
static void Run ();: Run the application's main loop.
static void Quit ();: Quit the application.

Box : Widget

An HBox or VBox, used for arranging child widgets.

void PackStart (Widget child, bool expand, bool fill, uint padding);: Add a widget to a Box.; If expand is true, the child widget will expand to use as much space as it is given. If fill is true, the child widget will request as much space as is available. padding is the size (in pixels) of a border to place around the child widget.

Button : Widget

Button (string label);: Construct a Button with the given label.
event EventHandler Clicked;: Called when the user has clicked this button.

Dialog

A dialog box.

Dialog (string title, Window parent, DialogFlags flags, params object[] button_data): Create a dialog box. flags will typically be DialogFlags.Modal to create a modal dialog. button_data indicates a set of buttons to display at the bottom of the dialog. Each such button is represented by a pair of values: a button text string (typically a stock string such as Stock.Add) followed by a value to be returned if that button is selected (typically a response code such as ResponseType.Ok or ResponseType.Cancel).
void Destroy ();: Destroy a dialog.
int Run ();: Run a dialog, returning when the user has chosen a response button. Typically the return value will a response code such as ResponseType.Accept or ResponseType.Cancel, cast to an int.; After a dialog returns, you must call Destroy() to destroy it - otherwise it will remain visible on the screen.

DrawingArea : Widget

A DrawingArea is a canvas where the program can draw graphics. Use a Cairo context to draw on a DrawingArea.

public DrawingArea ();: Create a DrawingArea.

FileChooserDialog : Dialog

A standard dialog box that prompts the user to select a file to be opened or created.

FileChooserDialog (string title, Window parent, FileChooserAction action, params object[] button_data): Create a FileChooserDialog.

title is a string that will appear in the dialog box's title bar.
parent is the top-level window that will own this dialog, typically the application's main window.
action is a FileChooserAction, an enumeration whose values include Open (open mode: the user can only choose an existing file) or Save (save mode: the user can either choose an existing file, or type in a new filename).
The remaining arguments are a series of pairs indicating buttons to be added to the dialog box. Each pair includes a string (typically a predefined constant such as Stock.Open or Stock.Cancel) and a response code to be returned when that button is selected (e.g. ResponseType.Accept or ResponseType.Cancel).

A typical call to this constructor might look like this:

new FileChooserDialog(
    "Open...", this, FileChooserAction.Open,
    Stock.Cancel, ResponseType.Cancel, Stock.Open, ResponseType.Accept);

string Filename { get; }: The filename that the user chose.

HBox : Box

An HBox contains one or more widgets that are arranged in a horizontal row.

HBox ();: Create an HBox.

Label : Widget

A widget that displays a text label, which is often a fixed string.

Label (string str): Create a Label that will display the given string.

MenuBar : Widget

The menu bar that appears at the top of a window.

MenuBar ();: Create an empty MenuBar.
void Append (MenuItem child);: Add an item that holds a top-level menu.

MenuItem : Widget

A MenuItem is an item that appears in a menu. It may itself contain a submenu of child MenuItem objects.

MenuItem (string label);: Create a MenuItem with the given label.
event EventHandler Activated;: An event that a MenuItem fires when the user selects it.
Menu Submenu { get; set; }: A submenu contained in this MenuItem.

VBox : Box

A VBox contains one or more widgets that are arranged in a vertical column.

VBox ();: Create a VBox.

Widget

A widget is a visual element such as a button, check box, scrollbar, or text area. (In Windows programming these are called controls, but "widget" is the usual Unix term.) A top-level window also counts as a widget.

void AddEvents (int events);: Ask to receive the given event(s). The events should be cast from a Gdk.EventMask, which is an enumeration with one value for each possible event type, including ButtonPressMask,ButtonReleaseMask and PointerMotionMask.; For example, if you want to receive all of these kinds of events, make this call:

AddEvents((int) (EventMask.ButtonPressMask |
                 EventMask.ButtonReleaseMask |
                 EventMask.PointerMotionMask));

Gdk.Rectangle Allocation { get; set; }: The Allocation property is a Gdk.Rectangle representing the widget's current size and position within its parent widget.; If this is a top-level widget, i.e. a Window, then Allocation.X and Allocation.Y will be 0, and Allocation.Width and Allocation.Height will be the size of the client area of the window.
bool CanFocus { set; get; }: Set this property to true to allow the widget to receive the focus, which will allow it to receive keyboard input.
void GrabFocus(): Set the focus to this widget so that it can receive keyboard input.
virtual bool OnButtonPressEvent (EventButton e); virtual bool OnButtonReleaseEvent (EventButton e);: Called when the user has pressed or released a mouse button. An EventButton object has the following properties:; ModifierType State { get; }

A value indicating which modifier key(s) (e.g. Control, Shift) were held down as the mouse button was pressed. ModifierType is an enumeration including values ControlMask and ShiftMask.

EventType Type { get; }

One of the following values indicating the type of click:

EventType.ButtonPress
EventType.TwoButtonPress (a double click)
EventType.ThreeButtonPress (a triple click)

Note that if the user double-clicks the mouse, you will receive a ButtonPress event for each click, and also a TwoButtonPress event.

double X { get; }

double
	Y { get; }

The X and Y coordinates of a button press, relative to the window.

Return true to indicate that the event has been handled.
virtual bool OnDrawn (Context c);: Runs when it is time for a widget to repaint itself.; Typically the event handler will use the provided Cairo context to draw graphics.; Return true to indicate that the event has been handled.
virtual bool OnKeyPressEvent (EventKey e);: Called when the user has pressed a key. An EventKey object has the following properties:; Gdk.Key Key { get; }

The key that the user pressed or released. Gdk.Key is an enumeration with one value for each physical key on a keyboard. Some useful values include Gdk.Key.Left and Gdk.Key.Right (the left and right arrow keys), Gdk.Key.space, Gdk.Key.Return and Gdk.Key.Delete. See the full list of values here.

Return true to indicate that the event has been handled.
virtual bool OnMotionNotifyEvent (EventMotion e);: Called when the user has moved the mouse. An EventMotion object has the following properties:; double X { get; } double Y { get; }

The X and Y coordinates of the mouse pointer, relative to the window.

Return true to indicate that the event has been handled.
virtual void OnSizeAllocated (Gdk.Rectangle allocation);: Called when this widget's size has changed. If this widget is a Window, this handler will be called when the user has resized the window.
bool Sensitive { get; set; }: If true, the widget is available. If false, the widget is grayed out and the user cannot interact with it.
void ShowAll ();: Show this widget and any widgets it contains.
void QueueDraw ();: Ask for this widget to be redrawn. This will cause the system to call the OnDrawn handler in the near future.

Window : Widget

A window that appears on the user's desktop. (There's also a Window class in the Gdk namespace, so type "Gtk.Window" to use this one.)

Window (string title);: Construct a window with the given title. The window will not initially be visible; you must call ShowAll() to make it appear.
void Add (Widget widget);: Add the given widget to this Window. A Window can directly contain only a single widget; to hold more widgets, add a container widget such as a VBox and place the child widgets in that container.
virtual bool OnDeleteEvent (Gdk.Event evnt);: Called when the user has clicked a window's close button. Typically you will exit the application in reponse to this notification.
void Resize (int width, int height);: Set a window's width and height in pixels.
string Title { get; set; }: The window's title.