$:.unshift File.dirname(__FILE__)
=begin
This is a sample (but useable) app for maintaining a reading list that takes
its reading options directly from Alexandria. At the moment it allows you to
move books to the reading list, remove them, mark them as read, and reorder
them. It's commented so as to be a kind of tutorial. The reader is encouraged
to play with it and try to add functionality.
This code demonstrates some of the most common operations in a Gtk app:
creating menus, hooking up a treeview and syncing it to data, and widget
packing. Of these, working with the TreeView will probably be the most
confusing. The basic concept behind treeviews is that a treeview is the
graphical widget that administers a "store" or short-term database (usually
either a ListStore or a TreeStore) which in turn is concerned with managing
either a list-like or tree-like structure of TreeIters. In the case of a
ListStore, a TreeIter represents a row that you see in the TreeView, and the
indices of the TreeIter (like iter[0], etc.) return the values for the columns
in that row. One thing to know about GTK Iter objects is that they like to get
"invalidated" whenever the managing View changes, so for example if you get the
iter for the user's selection of the third row of a TreeView and store it for
later, you'll find that the iter itself (as opposed to its TreePath, or
"absolute" location) is no longer available. Clear? It's definitely recommended
that you take a look at this tutorial:
http://ruby-gnome2.sourceforge.jp/hiki.cgi?tut-treeview
=end
module Readinglist
require 'yaml'
require 'alexandria'
require 'gtk2'
class ReadingListApp
FILE_FORMAT = {:to_read => [], :have_read => []}
READING_LIST_FILE = File.join(ENV["HOME"], ".reading_list.yml" )
# I try to decompose methods as much as possible to show the procedural
# skeleton of the program. I name the methods to read like sentences.
def initialize
load_reading_list
get_books
setup_gui
load_books_into_listview
end
# We use YAML as the "serialization" strategy. That is, we make sure a hash
# is stored in a file in the user's home directory. We load it into memory,
# manipulate it, and always make sure to sync it back to the file. This is
# exactly how books are loaded in Alexandria. Alexandria even stores the
# class instance to the file.
def load_reading_list
unless File.exist?(READING_LIST_FILE)
File.open(READING_LIST_FILE, 'w') do |file|
file.write(FILE_FORMAT.to_yaml)
end
end
database = YAML.load_file(File.join(ENV["HOME"], ".reading_list.yml" ))
@reading_list = database[:to_read]
@have_read = database[:have_read]
puts @reading_list.inspect
end
# I have to make sure the listview and the data store are in sync, and I
# want to make sure that when the program finishes the latest changes are
# committed to file. This could get too expensive with enough books,
# though. In Alexandria, some changes happen immediately (changes in book
# attributes, covers) while others only occur on a clean program shutdown
# (deleting, saving certain preferences).
def save_to_yaml
database = FILE_FORMAT
database[:to_read] = @reading_list
database[:have_read] = @have_read
File.open(READING_LIST_FILE, 'w') do |file|
file.write(database.to_yaml)
end
end
# I initialize the Libraries simpleton (available through the above
# require) and ask it to reload its list of libaries. Then the loadall class
# method on Library gives me an array of arrays of books, which I then
# flatten; that is, make into one long array.
def get_books
libraries_simpleton = Alexandria::Libraries.instance
libraries_simpleton.reload
libraries = Alexandria::Library.loadall
@books = libraries.flatten
end
# More declarative-style methods for erecting the GUI. This type of code
# ends up being very mechanical to write, which is why people like to use
# tools like Glade. In fact, keeping this gui layout code in the open is
# probably a better idea for long-term maintenance.
def setup_gui
setup_window
setup_menus
setup_current_reading_list
setup_available_books_list
refresh_reading_list
Alexandria::UI::Icons.init
setup_callbacks
@window.show_all # This needs to be called after widgets are packed.
end
# For information on packing, see
# http://ruby-gnome2.sourceforge.jp/hiki.cgi?tut-gtk2-packing-intro . Here
# @window, which can only contain one child widget, gets a VBox. I'll put
# several widgets inside @vbox, including more "container" widgets (like
# HBox), in which I put yet more widgets.
def setup_window
@window = Gtk::Window.new("Reading List")
@window.set_width_request(800)
@window.set_height_request(600)
@window.add(@vbox = Gtk::VBox.new)
end
# For information on callbacks in Gtk see
# http://ruby-gnome2.sourceforge.jp/hiki.cgi?tut-gtk-signals . Ruby-gnome2
# callbacks use the Ruby do/end block syntax. Since I don't like to define
# the callback method inside the block, I use the method() function to turn
# the method into a proc, and use the & syntax for passing in a "proc"
# object to the block.
def setup_callbacks
@available_treeview.signal_connect("row-activated", &method(:on_row_activated))
@window.signal_connect("delete-event", &method(:on_quit))
end
# Pretty straight-forward, if wordy. The ImageMenuItems can use a
# Gtk::Stock:: constant to save some work and get pretty icons. :expand =>
# false is used to keep widgets from bulging out.
def setup_menus
@vbox.add(menubar = Gtk::MenuBar.new, :expand => false)
menubar.append(file_menu = Gtk::MenuItem.new("_File"))
menubar.append(edit_menu = Gtk::MenuItem.new("_Edit"))
menubar.append(help_menu = Gtk::MenuItem.new("_Help"))
file_menu.submenu = file_submenu = Gtk::Menu.new
edit_menu.submenu = edit_submenu = Gtk::Menu.new
help_menu.submenu = help_submenu = Gtk::Menu.new
file_submenu.add(Gtk::ImageMenuItem.new(Gtk::Stock::SAVE_AS))
file_submenu.add(quit_item = Gtk::ImageMenuItem.new(Gtk::Stock::QUIT))
quit_item.signal_connect("activate", &method(:on_quit))
edit_submenu.add(Gtk::MenuItem.new("Mark selected _read"))
help_submenu.add(about_submenu = Gtk::ImageMenuItem.new(Gtk::Stock::ABOUT))
end
# To setup the "current reading list" on top. The TreeView is connected
# directly to the ListStore, but the TreeViewColumns and the CellRenderer*s
# connected to them are responsible for telling the TreeView _how_ to
# display the data within the ListStore. The argument :text => n is a
# shorthand to tell the TreeViewColumn to associate with a position or
# index in the TreeIter (row).
def setup_current_reading_list
@vbox.add(Gtk::Label.new("Books I am reading:"), :expand => false)
@vbox.add(hbox = Gtk::HBox.new)
hbox.add(scrolley1 = Gtk::ScrolledWindow.new)
hbox.add(@button_vbox = Gtk::VButtonBox.new, :expand => false)
setup_side_buttons
scrolley1.add(@reading_treeview = Gtk::TreeView.new)
@reading_treeview.model = @reading_store = Gtk::ListStore.new(Integer, String, String)
renderer = Gtk::CellRendererText.new
reading_column1 = Gtk::TreeViewColumn.new("Order", renderer, :text => 0)
@reading_treeview.append_column(reading_column1)
reading_column2 = Gtk::TreeViewColumn.new("Title", renderer, :text => 1)
@reading_treeview.append_column(reading_column2)
reading_column3 = Gtk::TreeViewColumn.new("Author", renderer, :text => 2)
@reading_treeview.append_column(reading_column3)
end
def setup_side_buttons
@button_vbox.layout_style = Gtk::VButtonBox::START
@button_vbox.add(up_button = Gtk::Button.new(Gtk::Stock::GO_UP))
@button_vbox.add(down_button = Gtk::Button.new(Gtk::Stock::GO_DOWN))
@button_vbox.add(read_button = Gtk::Button.new("Read"))
@button_vbox.add(remove_button = Gtk::Button.new(Gtk::Stock::REMOVE))
up_button.signal_connect("clicked", &method(:on_click_up))
down_button.signal_connect("clicked", &method(:on_click_down))
remove_button.signal_connect("clicked", &method(:on_click_remove))
read_button.signal_connect("clicked", &method(:on_click_read))
end
# Same as above, except with the added wrinkle that a TreeModelSort, using
# a TreeModelFilter, is acting as a kind of proxy for the ListStore. This
# is to support sorting of columns. This code is ripped off wholesale from
# Alexandria.
def setup_available_books_list
@vbox.add(Gtk::Label.new("Available books:"), :expand => false)
@vbox.add(scrolley2 = Gtk::ScrolledWindow.new)
scrolley2.add(@available_treeview = Gtk::TreeView.new)
@list_store = Gtk::ListStore.new(Gdk::Pixbuf, String, String)
@filter = Gtk::TreeModelFilter.new(@list_store)
@available_treeview.model = @available_books_model = Gtk::TreeModelSort.new(@filter)
setup_available_books_title_column
renderer = Gtk::CellRendererText.new
column2 = Gtk::TreeViewColumn.new("Author", renderer, :text => 2)
column2.resizable = true
column2.sort_column_id = 2
@available_treeview.append_column(column2)
end
# This TreeViewColumn has two widgets, a CellRendererPixbuf for the book's
# icon, and a regular CellRendererText for the book's Title. I have to tell
# the CellRendererPixBuf how to display itself int the set_cell_data_func.
# The convert_iter_to_child_iter is some kind of bookkeeping for the
# TreeModelFilter.
def setup_available_books_title_column
column = Gtk::TreeViewColumn.new("Title")
renderer = Gtk::CellRendererPixbuf.new
column.sizing = Gtk::TreeViewColumn::FIXED
column.fixed_width = 200
column.widget = Gtk::Label.new("Title").show
column.pack_start(renderer, expand = false)
column.set_cell_data_func(renderer) do |column, cell, model, iter|
iter = @available_treeview.model.convert_iter_to_child_iter(iter)
iter = @filter.convert_iter_to_child_iter(iter)
cell.pixbuf = iter[0]
end
renderer = Gtk::CellRendererText.new
renderer.ellipsize = Pango::ELLIPSIZE_END if Pango.ellipsizable?
column.pack_start(renderer, expand = true)
column.add_attribute(renderer, :text, 1)
column.sort_column_id = 1
column.resizable = true
@available_treeview.append_column(column)
end
# This supplies the actual data to @available_treeview. Icons.cover creates
# a Gdk::PixBuf (image object) from cover files stored in the .alexandria
# directory.
def load_books_into_listview
@books.each do |book|
icon = Alexandria::UI::Icons.cover(book.library, book)
icon = icon.scale(20,25)
iter= @list_store.append
iter[0] = icon
iter[1] = book.title
iter[2] = book.authors.join(" ")
end
end
# Call this when you want to repopulate and reorder the reading_list.
def refresh_reading_list
@count = 0
@reading_store.clear
@reading_list.each do |item|
iter = @reading_store.append # Gets a new iter (row) to work with.
iter[0] = @count += 1
iter[1] = item[0]
iter[2] = item[1]
end
end
# @reading_treeview.selection.selected is the iter of the selected row.
def on_click_remove widget
selection = @reading_treeview.selection.selected
@reading_list.delete_at(selection[0].to_i - 1)
save_to_yaml
refresh_reading_list
end
def on_click_read widget
selection = @reading_treeview.selection.selected
@have_read << @reading_list.delete_at(selection[0].to_i - 1)
save_to_yaml
refresh_reading_list
end
# The idea is to swap the iters in the TreeView and mirror the swap in the
# reading list. The iter's path is like its current map coordinates. Since
# iters are always getting invalidated, it's a good plan to work with the
# path.
def on_click_up widget
selection = @reading_treeview.selection.selected
position = selection[0].to_i - 1
previous_path = selection.path
previous_path.prev!
previous = @reading_store.get_iter(previous_path)
@reading_store.move_before(selection, previous)
unless (position - 1) < 0
@reading_list.insert(position - 1, @reading_list.delete_at(position))
refresh_reading_list
end
@reading_treeview.selection.select_path(previous_path)
end
# on_click_up and on_click_down call for refactoring to reduce duplicated
# code. Try it for yourself if you're interested.
def on_click_down widget
selection = @reading_treeview.selection.selected
position = selection[0].to_i - 1
previous_path = selection.path
after_path = selection.path
after_path.next!
after = @reading_store.get_iter(after_path)
unless (position + 1) == @reading_list.length
@reading_store.move_after(selection, after)
@reading_list.insert(position + 1, @reading_list.delete_at(position))
refresh_reading_list
@reading_treeview.selection.select_path(after_path)
end
end
# This is the callback for when a row in the lower available books listview
# gets clicked.
def on_row_activated widget, path, column
iter = @available_treeview.model.get_iter(path)
puts "#{iter[0]} #{iter[1]} #{iter[2]}"
reading_list_item = []
reading_iter = @reading_store.append
reading_iter[0] = @count += 1
reading_iter[1] = iter[1]
reading_list_item << iter[1]
reading_iter[2] = iter[2]
reading_list_item << iter[2]
@reading_list << reading_list_item
save_to_yaml
end
# This method is called when the window is closed and when the quit menu
# option is activated. Event is used for when the window connects to the
# 'delete-event' signal and requires both parameters. Gtk.main_quit kills
# the Gtk.main loop.
def on_quit widget, event = nil
Gtk.main_quit
end
end
def self.main
ReadingListApp.new
Gtk.main
end
end
=begin
Some features that could be added:
* connect up menu items
* figure out how save to... works; does it export to one specific format or
several?
* Not a feature, but can the code be made cleaner, cleaner, more testable?
* Something indescribably awesome...
A couple random tips:
install ruby-debug gem to step through this code to see how it works
See http://cheat.errtheblog.com/s/rdebug/ for more information
install the utility_belt gem for colorized irb and add
require 'rubygems'
require 'utility_belt'
to a file ~/.irbrc
=end
if __FILE__ == $0
Readinglist.main
end