[sigc] tutorial docs...

[David Greaves <david dgreaves com>]

Hi

I just had a problem using sigc::bind

Fails:
 m_refActionGroup->add(
	  Gtk::Action::create("Full",
						  Gtk::Stock::NEW, "Full",
						  "Show everything I need"),
	  sigc::bind( sigc::mem_fun(*this, &MainWindow::on_action_set_state), obj, 2 ) );

void MainWindow::on_action_set_state(MyList &obj, int s)



Perfect:
m_refActionGroup->add(
	  Gtk::Action::create("Out",
						  Gtk::Stock::NEW, "Out",
						  "Show out"),
	  sigc::mem_fun(*this, &MainWindow::on_action_set_state_out));

void MainWindow::on_action_set_state_out()

The reason is that I should have used sigc::ref() to wrap the obj - even though
my on_action_set_state() has &obj.

This is not at all easy to find from the docs...

There is a glossary - I was wondering if there could be something similar for
the main function calls - the api reference is completely useless from a
self-teaching PoV!!!

eg:

sigc::bind()
============

Typically used to pass additional parameters to a slot.
So 3 menu items may call the same handler with different variables.
eg:
sigc::bind(&handler_function, "a")
sigc::bind(&handler_function, "b")

Up to 7 extra parameters may be passed (after that, check your design!)

If any of the parameters are expected to be object references they should be
wrapped in a sigc::ref().
eg:
given:
  void myhandler(Class &obj, int a);
then:
  sigc::bind(&myhandler, object, cnt)...
would silently pass a reference to a copy of object to myhandler.

To get the expected behaviour use:
  sigc::bind(&myhandler, sigc::ref(object), cnt)...


sigc::ref()
===========

Used to make sure objects in a sigc::bind() are passed by reference. See
sigc::bind()

etc etc

David