Module: VR::ViewCommon

Included in:
ListView, TreeView
Defined in:
lib/treeview/ViewCommon.rb

Overview

The col_<propery>, ren_<property>, col_attr, and ren_attr methods

All of these methods do the same thing:  set the properties of your VR::ListView.

The way to configure a VR::ListView or VR::TreeView is to set the properties
of its columns (and renderers).  For example,
setting the "title" property of a column will set the title that appears at the top.

The normal Gtk approach to setting properties of a GtkTreeViewColumn, (or renderer) is to set
them individually:

 col = Gtk::TreeViewColumn.new()
 col.title = "My Title"

This is slow, and tedious.  However, you can completely configure any VR::ListView or
VR::TreeView object with only a few lines of code using the above methods.  They can set many properties on many columns
at once.  

The first thing to understand is that there are several ways to set properties.  In fact all
of these lines of code do the exact same thing:

 column(:name).title = "Person's Name"
 col_title(:name => "Person's Name")
 ren_title(:name => "Person's Name")
 col_attr(:name, :title => "Person's Name")
 ren_attr(:name, :title => "Person's Name")

All the above lines of code simply set the title of the :name column.  So why
is one method better than another?   Answer:  because you can set multiple
properties on multiple columns with one line of code.  For example, you can set all the titles
with this line:

 col_titles(:name => "Name", :email => "Address", :phone => "Phone Number")

The col_<property> method is very good at setting <b>multiple columns</b>.

Likewise, the VR::ListView#col_attr method is good at setting the same property on multiple columns:

 col_attr(:name, :email, :phone, :width => 200, :weight => 700) #bold

Either way, you can set everything with one line of code.  Also, if you want to set
a propery for all the columns, simply omit any column IDs:

 col_width(200)
 ren_background("yellow")
 col_attr(:font => "Sans")
 ren_attr(:visible => true)

There are many, many possibilities of properties you can set using these methods.
You need to know the name of the property that you want to set from consulting
the docs for GtkTreeViewColumn and the docs for the column's renderer type (listed on the left of this webpage)

Any of the properties of these classes can be set using the above methods.

If you consult, GtkCellRendererText for example, you'll see that it has a "background" property.
Therefore you can use ren_background() to set the color of the background of that column.

Method names like "col_title" are just one possibility of methods you can use.
You could call any of these as well:

 col_width
 col_xalign  # (0.00 to 1.00, 1 = right justify)
 col_weight  # (100 to 900)
 col_background
 col_foreground
 col_font
 col_markup
 col_size
 col_spacing

You'll notice that some of the methods listed above don't look valid.  For example,
col_background doesn't seem to make sense because the GtkTreeViewColumn doesn't
have a <b>background</b> property.  The <b>background</b> property belongs to the
renderer, GtkCellRendererText.  But, the col_<attribute> method is programmed
to try to set the property on the column first, and if the column object doesn't
support the propery, it will look in the renderer.  If the renderer doesn't support it,
it DOES NOTHING.

Likewise, the ren_<property> method will look first in the renderer for the property, then
the column.  The only difference between the ren_<property> and col_<propery> methods
is that the ren_<property> looks in the renderer object first.  These two methods
are almost interchangable.  In fact, I always just use the col_<propery> method
because it looks better.  The only time I have a problem is when the column and the renderer
have the same property (i.e. "visible" and "xalign").  Then, I simply substitute the ren_<property> method.

==Summary

- To set the <b>same attribute value</b> on multiple columns use col_attr() or ren_attr()
- To set <b>different attribute values</b> on multiple columns, use col_<property> or ren_<property>
- The ren_<property> and col_<property> methods are almost interchangable.
- The ren_attr() and col_attr() methods are almost interchangable.
- To set the properties of <b>all</b> the columns, omit any column iDs
- Consult the documentation for GtkTreeViewColumn to learn about properties to set.
- Consult the Gtk docs for the renderer by locating the type on the left of this webpage.

Some examples are:
 ren_background(:name => "yellow", :email => black)  #renderer for :name bg = yellow
 col_editable(false) #makes all columns un-editable
 col_width(:name => 300, email => 200)
 ren_xalign(:email => 1)  # right justify email 
 ren_attr(:name, :email, :font => "Courier") 
 ren_attr(:font => "Sans") # all columns now Sans font
 col_attr(:name, :email, :visible => true)

Instance Method Summary collapse

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(meth, *args) ⇒ Object

:nodoc:



130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/treeview/ViewCommon.rb', line 130

def method_missing(meth, *args) # :nodoc:
	unless m = /^(ren_|col_)(.+)$/.match(meth.to_s)
super
return
			end     
if args.first.is_a? Hash
	args.first.each_pair { |key, val| method(m[1] + "attr").call(key, m[2] => val) }
else
	method(m[1] + "attr").call(m[2] => args.first) 
end
end

Instance Method Details

#col_attr(*args) ⇒ Object 



180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/treeview/ViewCommon.rb', line 180

def col_attr(*args)
	cols = args.select { |arg| !arg.is_a? Hash }
	return unless hash = args.detect { |arg| arg.is_a? Hash }
	cols = @column_keys if cols.empty?
		cols.each do |c|
			hash.each_pair do | key, val |
				if column(c).respond_to?(key.to_s + "=")
					column(c).send(key.to_s + '=', val)
				elsif renderer(c).respond_to?(key.to_s + "=")  
 					renderer(c).send(key.to_s + '=', val) 
				end 
			end
	end		
end

#column(id) ⇒ Object 



278
279
280
 
# File 'lib/treeview/ViewCommon.rb', line 278

def column(id)
	renderer(id).column 
end

#each_renderer ⇒ Object 



282
283
284
285
286
287
288
 
# File 'lib/treeview/ViewCommon.rb', line 282

def each_renderer
	self.columns.each do |c|
		c.cell_renderers.each do |r| 
			yield r 
		end
	end
end

#each_row ⇒ Object

Enumerates each row in the model and returns an instance of GtkTreeIter.

However, the iters returned have been converted into a "row" using VR::ViewCommon#vr_row
so they will respond to colum IDs (symbols).  Like this:

 @view.each_row { |row| puts row[:name] }  # works!



248
249
250
 
# File 'lib/treeview/ViewCommon.rb', line 248

def each_row
	self.model.each { |mod, pth, itr| yield vr_row(itr) }
end

#flatten_hash(hash) ⇒ Object

:nodoc:



229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/treeview/ViewCommon.rb', line 229

def flatten_hash(hash) # :nodoc:
	h = {}
	hash.each do | k, v |
		if v.class == Hash
			v.each_pair { |key, val| h[key] = val }
		else
			h[k] = v
		end
	end 
		return h
end

#id(id) ⇒ Object

Returns the number of the given column ID. This is very useful when you’re

working with Gtk's methods because they require column numbers (not Column IDs)
This method converts the column ID symbols from the VR::ListView#new constructor
to Integers:

 @view = VR::ListView.new(:name => String, :date => VR::CalendarCol)

 Later in code...

 iter = get_iter(path)
 col_num = id(:date)  # 1
 iter[col_num]

You won't need to use this when adding rows with VR::ListView#add_row, and
you also have the option of converting the whole iter to use column IDs (symbols)
using VR::ViewCommon#vr_row.



346
347
348
 
# File 'lib/treeview/ViewCommon.rb', line 346

def id(id)
	return (id.is_a? Fixnum or id.is_a? Integer) ? id : @column_keys.index(id)
end

#load_columns(cols) ⇒ Object

:nodoc:



119
120
121
122
123
124
125
126
127
128
 
# File 'lib/treeview/ViewCommon.rb', line 119

def load_columns(cols) # :nodoc:
	model_col = 0
	cols.each_pair do | sym, type|
		col = VR::TreeViewColumn.new(self, model_col, sym, type)
		model_col = model_col + (type.class == Hash ? type.size : 1)
		self.append_column(col)
	end
	turn_on_comboboxes()
@column_keys = flatten_hash(cols).keys
end

#ren_attr(*args) ⇒ Object

Sets properties on renderers (and columns) See VR::ViewCommon#col_attr for more.



144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/treeview/ViewCommon.rb', line 144

def ren_attr(*args)
	cols = args.select { |arg| !arg.is_a? Hash }
	return unless hash = args.detect { |arg| arg.is_a? Hash }
	cols = @column_keys if cols.empty?
		cols.each do |c|
			hash.each_pair do | key, val |
				if renderer(c).respond_to?(key.to_s + "=")  
 					renderer(c).send(key.to_s + '=', val) 
				elsif column(c).respond_to?(key.to_s + "=")
					column(c).send(key.to_s + '=', val) 
				end 
			end
	end		
end

#renderer(id) ⇒ Object

Returns the renderer for a given column ID.

In VR::ListView#new (and VR::TreeView#new) method, a data model (VR::ListStore or VR::TreeStore) is automatically contstructed. Then the class will automatically assign a renderer to show it on the screen. These renderers simply convert a piece of data to something visual on the screen. For example, a column in the model might contain a value “true,” but the renderer converts it to a GtkCheckButton which shows a check-mark. The VR::ListView class will automatically assign renderers to each column based on its type:

String, Fixnum, Integer, Float => VR::CellRendererText TrueClass => VR::CellRendererToggle GdkPixbuf => VR::CellRendererPixbuf DateTime => VR::CellRendererDate VR::CalendarCol, VR::TextCol => VR::CellRendererObject VR::SpinCol => VR::CellRendererSpin VR::ProgressCol => VR::CellRendererProgress VR::ComboCol => VR::CellRendererCombo

The renderer() method will return one of these renderers:

ren = @view.renderer(:ok) puts ren.class.name # VR::CellRendererToggle (:ok column is a TrueClass) puts @view.renderer(:name).class.name # => VR::CellRendererText

All the types of renderers are subclasses of Gtk renderers. For example, VR::CellRendererText is a subclass of Gtk::CellRendererText. So, you can use these objects just as you would use a normal Gtk renderer:

@view.renderer(:name).width = 100

This is perfectly valid even though there are better ways of setting these properties in visualruby.



322
323
324
325
326
327
 
# File 'lib/treeview/ViewCommon.rb', line 322

def renderer(id)
	each_renderer do |r| 
		return r if r.model_col == id(id) 
	end
	return nil
end

#selected_rows ⇒ Object

Returns an array of rows that are selected in the VR::TreeView or VR::ListView.

If nothing is selected, it returns an empty array.  If you've configured your
listview to accept multiple selections, it will return all of them.  In single 
selection mode, it will return an array with one row.  These rows are
able to respond to column IDs.  They are the same types of rows as returned by
VR::ViewCommon#vr_row.



203
204
205
206
207
208
209
 
# File 'lib/treeview/ViewCommon.rb', line 203

def selected_rows()
	rows = []
	selection.selected_each do |model, path, iter|
		rows << vr_row(iter) 
	end
	rows
end

#turn_on_comboboxes ⇒ Object

:nodoc:



211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/treeview/ViewCommon.rb', line 211

def turn_on_comboboxes() # :nodoc:
	#detect if comboboxes are present:
	found = false
	self.each_renderer do |r|
		if r.is_a? VR::CellRendererCombo
			found = true
			break
		end
	end	
	return unless found
 	self.signal_connect("cursor_changed") do |view|
   	next unless iter = view.selection.selected 
 		view.each_renderer do |r|
 			r.set_model( iter[r.model_col] ) if r.is_a? VR::CellRendererCombo
		end
 	end		
end

#vr_row(iter) ⇒ Object 



258
259
260
261
262
 
# File 'lib/treeview/ViewCommon.rb', line 258

def vr_row(iter)
	iter.extend(VR::IterMethods)
	iter.column_keys = @column_keys
	return iter
end