The Ruby-Gnome Application Library

Library files common to the Ruby-Gnome applications listed in sites.google.com/site/gtk2applib/home/gtk2applib-applications. Makes writing Ruby-Gnome (ruby-gnome2.sourceforge.jp) applications faster. Runs on Linux, Maemo/Hildon (maemo.org), and Windows.

The main entry point of the library is:

  • lib/gtk2applib.rb

The library provides the initial application stub:

  • Tested on Linux, Maemo (Nokia N800 and N900), and Windows (NT)

  • Parses standard initial -options from ARGV.

  • Sets up the application user's hidden directory and configuration.

  • Creates the application's main menu and icon.

  • Provides the main Gtk (or Hildon) window.

  • Creates :SIGINT, :SIGTERM signal traps for a clean exit.

  • Provides an alternate widget api, extended widgets, and dialogs.

  • Creates a lock to prevent unintended multiple instances.

  • Provides a system call, Gtk2AppLib.run, that works on both Linux and Windows.

  • Provides a process listing, Gtk2AppLib.processes{|pid,command|…}, that works on Linux, Maemo, and Windows.

Example

The application, say name, is expected to be built from a versioned directory (like /path-to/name-1.2.3) with a bin, pngs, and lib/name directory, and a README.txt file (which will be the help). The following is a template for the executable, ./bin/name.

#!/usr/bin/env ruby
require 'rubygems'
gems 'gtk2applib', '~> 15.0'
require 'gtk2applib'

# initialize...
program = Gtk2AppLib::Program.new(
  # need the "about" info as follows...
  about = {
    'name'           => "Application Name",
    'authors'        => ['email@my.net'],
    'website'        => 'http://my.net/application/home.html',
    'website-label' => 'My Application Home',
    'license'       => 'GPL',
    'copyright'     => '2010-08-03 17:08:29', # <= I like timestamping
})

begin
  # get the main app window
  program.window do |window|
    # do stuff with  window...
    ...
  window.show_all
  end
rescue Exception
  $!.puts_bang! # this is a method Gtk2AppLib adds to Exception
ensure
  # final cleanups
  program.finalyze
end

With the provided window one can proceed normally (Gtk), but Gtk2AppLib also provides it's own Widgets versions you can use. You should create a configuration file in ./lib/name/appconfig.rb which gets copied over to the user's hidden directory and allows the user to configure the application. The hidden directory will be in like ~/.name-1.

Gtk2AppLib Widgets

There's a general mapping between Gtk's Widgets and Gtk2AppLib's Widgets.

# Gtk is like...
widget = Gtk::Widget.new( *parameters0 ) # where parameters0 = [ parameter0_1, parameter0_2, ... ]
widget.method1( *parameters1 )
widget.method2( *parameters2 )
...
widget.signal_connect( signal1 ) {|*emits| ... }
widget.signal_connect( signal2 ) {|*emits| ... }
...
# Gtk2AppLib is like
widget = Gtk2AppLib::Widgets::Widget.new(*[parameters0,{:method1=>parameters1,:method2=>parameters2,...},signal1,signal2,...]) do |is,signal,*emits|
  # do stuff...
end
# by default, widget.is is set to self, but here you can override that value.
widget.is = value # if value is nil or false, signals are disabled.

Gtk2AppLib Widget's constructer has some shortcuts to the above form, see the code for that.

Gtk2AppLib Dialogs

And there are some prefab dialogs, for example:

# ask user for a username and password
username, password = Gtk2AppLib::DIALOGS.auth(username='',password='',options=Gtk2AppLib::HNIL)

Out of Beta?

LOL!!!