doc/examples/START

EXAMPLES

These files are examples of specific parts of the java-gnome API worked up as complete Java programs.

Source code, especially Java source code, doesn’t always lend itself to being read, certainly not from top to bottom. We have attempted, however, to create some examples which are non-trivial but nonetheless are still readable.

Button in a Window

• ExamplePressMe.java
  It doesn’t get any simpler than this. A Label and a Button in a Window, showing how to connect a listener to handle a Button.Clicked signal from the Button and how to ensure your application terminates when the Window is deleted. Incidentally, this is what runs if you type make demo in a fresh java-gnome build.

Handling keystrokes

• ExampleSnooping.java
  Handling keyboard input is more complicated than it reasonably ought to be. In most cases the existing GTK Widgets already do everything that needs doing (when you type text into an Entry, the text does indeed go into that Entry), focus handling, etc. However, if you need to intercept a keystroke so you can do something special, then you need to work with the Keyval and ModifierType classes in response to the Widget.KeyPressEvent signal. This is how.

Pressed: Keyval.ControlLeft, Modifier: ModifierType.NONE 
Pressed: Keyval.c, Modifier: ModifierType.CONTROL_MASK 

TreeView and TreeModel

• ExampleTrailHeads.java
  While not a complete tutorial, we have an example of a small application which uses a TreeView backed by a ListStore called ExampleTrailHeads. It is heavily commented and meant to serve as an introduction of the incredibly powerful yet very complex TreeView / TreeModel system. It should be read in conjunction with the API documentation for these types. You’ll also want to read about how to setup a ListStore and the explanation of available column types in DataColumn.

TextView and TextBuffer

• ExampleInstantMessenger.java
  This is a more involved sample illustrating use of the TextView / TextBuffer multi-line text display and editing Widget. We set up a conversation window like you’d see in an instant messaging program, and then simulate a conversation with someone — all as a means of demonstrating setting up the view, doing text insertion into the buffer with TextIter as well as more advanced features like managing text formatting via TextTags. The example is more or less readable from the top, but the program is quite dynamic and the most fun will be had if you run the thing.

Drawing with Cairo

• ExampleDrawingInExposeEvent.java
  FIXME this needs a better name. For that matter, it needs something more interesting.
  Using the Cairo Graphics library to draw within a GTK program means following the idiom shown in this example. This program demonstrates drawing lines, rectangles, and gradients using a drawing Context as obtained within a Widget’s Widget.ExposeEvent signal handler.

Creating PDFs with Cairo and drawing text with Pango

• ExampleLinedPaper.java
  All text drawing in java-gnome is done with GNOME’s powerful text rendering library, Pango. This example uses the Layout class to lay out the standard lorem ipsum typesetting text. To make it more interesting we have drawn horizontal rules at the font baseline and a red line at the left margin to create the effect of lined three-hole punch paper, all with Cairo of course.
  
  In this case we have not used Cairo to draw a Widget — we have created a program that writes out a PDF file using Cairo’s PdfSurface and drawn our text there instead!
  
  Of course, no one has ever sat through Latin class without doodling on their notepad… to create the effect we use a transparent image as the source pattern and paint it onto the surface.
  
  The resultant .pdf is shown here as rendered by Evince, GNOME’s excellent PDF viewing program.
  The tank sketch is used with the permission of the artist, Nathan Strum.