Ruby/GTK2 Tutorial

This document covers the Ruby/GTK2 library used to ease creation of graphical user interfaces (GUIs). GTK+ can create native application on the GNOME Desktop, and also runs great on almost any desktop environment: Linux, Windows, OSX, FreeBSD and more; and using ruby all without and modifications or recompilation! This tutorial is currently being translated from the Japanese version by Laurent Sansonetti.

As of January 2009, brand new material mainly based on Andrew Krause's book Foundations of GTK+ Development is currently being added by Igor Pirnovar. The numbers at the beginning of the top level lines refer to the chapters in Andrew's book, the "warning" street signs (!) mark places where there may be a problem area with the current Ruby 1.8/GNOME2 2-0.17.0-rc1 release used to test examples in this tutorial.

• Introduction
• Getting Started
  • Hello World
  • Theory of Signals and Callbacks
  • Events
  • Stepping Through Hello World
• Moving On
  • More on Signals Handlers
  • An Upgraded Hello World
• Packing Widgets
  • Theory of Packing Boxes
  • Details of Boxes
  • Packing Demonstration Program
  • Packing Using Tables
  • Table Packing Example
• (3) Container Widgets
  • (based on Andrew Krause's book Foundations of GTK+ Development)
    • Decorator Containers
    • Layout Containers
  • Horizontal and Vertical Boxes
  • Horizontal and Vertical Panes
  • Tables
  • Fixed Containers
  • Expanders
  • Handle Boxes
  • Notebooks
  • Event Boxes
• (4) Basic Widgets
  • 4.1 Toggle Button
    • 4.1.1 Mnemonics
  • 4.2 Check Button
    • 4.3 Using Stock Items
    • 4.5 Callbacks And Event Handling
  • 4.6 Radio Button
  • 4.7 ** Not a button but vaguely related Button Box
  • 4.8 ** Font Button (bellow undeer Selector And Chooser ...) (!)
  • 4.9 Numeric - Text Data Entry
  • 4.10 Single Line Entry Field
  • 4.11 Spin Buttons
    • 4.11.1Adjutments
  • 4.12 Horizontal And Vertical Scales
  • 4.13 Selector And Chooser Interface And Widgets
  • 4.15 File Chooser Button
  • 4.16 Colour Button
    • 4.16.1 Modifying the foreground colour of a widget
  • 4.17 Font Button (!)
  • 4.18 Test Your Understanding
• (5) Dialogs
  • Creating Your Own Dialogs
    • Modal Or Nonmodal Message Dialogs
    • ** The Gtk::Image Widget
  • Message Dialogues
  • Provide Info About Your Application
    • ** Pixbuf
    • Help Menu Option
  • Types Of File Chooser Dialogues
    • Saving Files
    • Creating a Folder (!)
    • Selecting Multiple Files
  • Collecting Information With Font And Colour Selection Dialogues
    • Colour Selection Dialogues
    • Font Selection Dialogues
    • Modifying font by programmatic means
  • Dialogues With Multiple Pages Using Gtk::Assistant (!)
    • Progress Bar
  • Test Your Understanding
• (6) GLib Short Introduction
  • Environment Variables
  • Timers
  • File Manipulation
    • Error Handling
  • Main Loop
  • Input-Output Channels
• (7) The Text View Widget
  • 7.1 Scrolled Windows
  • 7.2 Text Views
    • 7.2.1 Text Buffers
    • 7.2.2 Text View Properties
    • 7.2.3 Pango Tab Arrays
  • 7.3 Text Iterators and Marks
    • 7.3.1 Editing the Text Buffer (!,f)
    • 7.3.2 Retrieving Text Iterators and Marks
    • 7.3.3 Changing Text Buffer Contents
    • 7.3.4 Cutting, Copying and Pasting
    • 7.3.5 Searching in the Text Buffer
    • 7.3.6 Scrolling the Text Buffer
  • 7.4 Text Tags
  • 7.5 Inserting Images
  • 7.6 Inserting Child Widgets
  • 7.7 GtkSourceView
  • 7.8 Test Your Understanding
• (8) The Tree View Widget
  • 8.1 Parts of a Tree View
    • 8.1.1 Gtk::TreeModel
    • 8.1.2 Gtk::TreeViewColumn and Gtk::CellRenderer
    • 8.1.3 Using Gtk::ListStore
    • 8.1.4 Renderers and Columns
      • 8.1.4.1 Don't confuse model columns with a view columns
      • 8.1.4.2 TreeViewColumn and CellRenderer
    • 8.1.5 Creating the Gtk::ListStore
    • 8.1.6 Sorting tree view
  • 8.2 Using Gtk::TreeStore
    • 8.2.1 Data Organization Within a Tree Store
      • 8.2.1.1 Building a Multilayered Tree Store
    • 8.2.2 Cell Data Function
    • 8.2.3 Multidimensional Tree Store
      • 8.2.3.1 Tedious Job Of Loading Multidimensional Tree Store
    • 8.2.4 Multi-item Super Columns
  • 8.3 Referencing Rows
    • 8.3.1 Tree Path
    • 8.3.2 Tree Iterators
    • 8.3.3 Tree Row References
  • 8.4 Adding Rows and Handling Selections
    • 8.4.1 Single Selections
    • 8.4.2 Multiple Selections
    • 8.4.3 Adding New Rows
    • 8.4.4 Combo Box
    • 8.4.5 Removing Multiple Rows
  • 8.5 Editable Text Renderers
  • 8.6 Cell Data Functions [II (redundant/see: 2.2 above)]
  • 8.7 Cell Renderers
    • 8.7.1 Toggle Button Renderers
      • 8.7.1.1 Toggle Button Renderers May Effect Other Related Values In Tree View
      • 8.7.1.2 Data Dependencies Between Cells In Different Columns And Rows In Tree View
    • 8.7.2 Pixbuf Renderers
    • 8.7.3 Spin Button Renderers
    • 8.7.4 Combo Box Renderers
      • 8.7.4.1 Progress Bar Renderers
    • 8.7.5 Keyboard Accelerator Renderers (!)
• (9) Menus and Toolbars
  • 9.1 Pop-up Menus
    • 9.1.1 Creating Pop-up Menus (!)
      • 9.1.1.1 Menu Item Separators
      • 9.1.1.2 Pop-up Menu Callbacks
  • 9.2 Keyboard Accelerators
    • 9.2.1 Accelerator Path
  • 9.3 Status Bar
    • 9.3 1 Status Bar Hints
    • 9.3.2 The Status Bar Widget
      • 9.3.2.1 Status Bar Context and Message Identifiers
    • 9.3.3 Menu Item Information
  • 9.4 Menu Items
    • 9.4.1 Submenus
      • 9.4.1.1 The Mechanics Of Building Submenu Hierachies
        • 9.4.1.1.1 The Tear Off Item (!)
      • 9.4.1.2 Signal Handling Mechanisms And Callbacks With Sub-menus
        • 9.4.1.2.1 Menu Program Design Based On a Hash Of Items and Callbacks
    • 9.4.2 Different Kinds Of Menu Items
      • 9.4.2.1 Image Menu Items
      • 9.4.2.2 Check Menu Items
      • 9.4.2.3 Radio Menu Items
  • 9.5 Menu Bars
    • 9.5.1 Adding Keyboard Accelerators To Menu Items
    • 9.5.2 Keyboard Accelerators And Their Relationships With Menus And Other Widgets
      • 9.5.2.1 Using Accelerator Path In Menus
  • 9.6 Tool Bars
    • 9.6.1 Some +toolbar-item-menu.rb+ Program Notes
      • 9.6.1.1 Tool Bar Style
      • 9.6.1.2 Icon Size On Your Tool Bars
    • 9.6.2 Dragging And Dropping Tool Bars
      • 9.6.2.1 Detached Toolbar Example
        • 9.6.2.1.1 Orientation Of Detached Toolbar
      • 9.6.2.2 Dragging a Toolbar Within a Window
  • 9.7 Toolbar Items (!)
  • 9.8 Dynamic Menu Creation
    • 9.8.1 Creating UI Files
    • 9.8.2 Loading UI Files
      • 9.8.2.1 Additional Action Types
      • 9.8.2.2 Placeholders
  • 9.9 Custom Stock Items (!)
  • 9.10 Test Your Understanding
• (10) Drag And Drop
  • 10.1 DnD Introduction
    • 10.1.1 Identifying the DnD Objects
    • 10.1.2 The DnD Source And Destination Objects
      • 10.1.2.1 Why Do the DnD Widgets Need a Gdk::Window Of Their Own
      • 10.1.2.2 There Are Three Different Source And Destination DnD Set-Up Scenarios
  • 10.2 Setting DnD For Widgets Without Their Own Gdk::Window
    • 10.2.1 Dragging a Button Onto a Label
      • 10.2.1.1 Time To Start Using Object-Oriented Programming Paradigm
        • 10.2.1.1.1 Notes About the DnD Debugging Module
    • [(10.2.2) 9.6.2.2 Dragging a Toolbar Within a Window]
    • 10.2.2 Dragging a Toolbar Within a Window (oo version)
      • 10.2.2.1 'dnd-toolbar-oo.rb' program example notes
  • 10.3 DnD Widgets With Their Own Gdk::Window
    • 10.3.1 DnD In Text View Widget
    • 10.3.2 DnD Tree View Items
      • 10.3.2.1 Built-in DnD Tree View Mechanism
      • 10.3.2.2 Custom DnD In Tree View
    • 10.3.3 DnD Icon View Items
      • 10.3.3.1 Custom DnD In Text View
    • 10.3.4 Dragging And Dropping Onto Drawable Widgets
      • 10.3.4.1 DnD Onto Gtk::DrawingArea
      • 10.3.4.2 DnD And Cairo
• (11) Additional GTK+ Widgets
  • Drawing Widgets
  • Calendars
  • Status Icons
• (12) Drawing Area and Cairo
  • 12.1 Intro
  • 12.2 Writing Image Of Drawing Area Into a Pixbuf File

• 12.3 Ruby Cairo Tutorial (top page)
  • 12.3.0 Intro To Ruby Cairo Tutorial
    • 12.3.0.1 Establishing Gtk-Cairo Framework To Run the Tutorial Example Code
      • 12.3.0.1.1 Cairo Backends
        • 12.3.0.1.1.1 Programmer's Note
          • 12.3.0.1.1.1.1 Student's Note
      • 12.3.0.1.2 The Template Ruby File To Run Arbitrary Cairo Code
        • 12.3.0.1.2.1 A Real Life Example With Runing Cairo Code
      • 12.3.0.2 Running Cairo Code From Non-Gtk Ruby Environment
      • 12.3.0.3 Hiki Gtk With Cairo Module Download File
  • 12.3.1 Cairo's Drawing Model
    • 12.3.1.1 Nouns
      • 12.3.1.1.1 Destination
      • 12.3.1.1.2 Source
      • 12.3.1.1.3 Mask
      • 12.3.1.1.4 Path
      • 12.3.1.1.5 Context
    • 12.3.1.2 Verbs
      • 12.3.1.2.1 Stroke
        • 12.3.1.2.1.A1 Scale
        • 12.3.1.2.1.A2 Default Scale Example
        • 12.3.1.2.1.A3 Rule of thumb
      • 12.3.1.2.2 Fill
      • 12.3.1.2.3 Show Text - Glyphs
      • 12.3.1.2.4 Paint
        • 12.3.1.2.4.A1 Paint And Colour Transparency In Ruby Cairo Library
      • 12.3.1.2.5 Mask
        • 12.3.1.2.5.A1 Ruby Gtk-Cairo Library Fails To Support Gradient Patterns
  • 12.3.2 Drawing with Cairo
    • 12.3.2.1 Preparing and Selecting a Source
    • 12.3.2.2 Creating a Path
  • 12.3.3 Understanding Text
  • 12.3.4 Working with Transforms
  • 12.3.5 Where to Go Next
  • 12.3.6 Tips and Tricks
    • 12.3.6.1 Line Width
    • 12.3.6.2 Text Alignment

• (13) Dynamic User Interfaces
  • The Glade User Interface Builder
    • Main Glade window with its menus
  • Building Example UI With Glade
    • Creating the Window
    • Adding a Toolbar
    • Completing the File Browser
    • Making Changes
    • Widget Signals
    • Creating a Menu
  • Using Libglade
  • Test Your Understanding
    • The Issues With Flexible Menu Designs
• (A) Appendix
  • (A12.3) Digital Colour Theory For Computer Professionals