[Hiki] update - How to Implement Ruby-GNOME2 (ruby-gnome2-doc-cvs) - Ruby-GNOME2

-------------------------
REMOTE_ADDR = 210.249.204.48
REMOTE_HOST = 
        URL = http://ruby-gnome2.sourceforge.jp/?How+to+Implement+Ruby-GNOME2
-------------------------
= How to implement Ruby-GNOME2
This document is introduction how to implement Ruby-GNOME2(Especially, Ruby/GTK, Ruby/GNOME).

== Signals, Properties, Style Properties
Accessors(Setter/Getter methods) for Properties and Style Properties are autogenerated. You do not have to implement it any longer.
Signals/Properties are expressed as string or symbol. Especially SIGNAL_* constants were all removed in Ruby-GNOME2.

(*)Style Properties is unavailable now.

== Deprecated/Obsolete classes/methods
Don't implement them.

== Macros
When you implement new class/module, there are many macro which make easy to implement it. Almost of those macros are in glib/src/rbgobject.h, rbglib.h and gtk/src/rbgtk.h.

=== Define class/interface
They are used in Init_*().

--- G_DEF_CLASS(gtype, name, module)
--- G_DEF_CLASS2(gtype, name, module, mark, free)
    Define a class. If you define with mark,free functions yourself, use G_DEF_CLASS2.

--- G_DEF_INTERFACE(gtype, name, module)
--- G_DEF_INTERFACE2(gtype, name, module, mark, free)
    Define a module. If you define with mark,free functions yourself, use G_DEF_INTERFACE2.

--- void rbgobj_boxed_not_copy_obj(GType gtype)
    Define in Init_* if the GBoxed object shouldn't copy when it convert to RVALUE(e.g. GBOXED2RVAL, G_INITIALIZE).

--- gboolean rbgobj_exist_class(GType gtype)
    Return TRUE if the gtype is already regist as Ruby class.

=== Initialize object
They are used in initialize function.

--- G_INITIALIZE(obj, cobj)
--- RBGTK_INITIALIZE(obj,gtkobj)
    Initialize object. If the class is descendant of GtkObject, use RBGTK_INITIALIZE.

=== Convert Ruby <-> GLib/GTK

--- RVAL2GOBJ(obj)
--- GOBJ2RVAL(gobj)
    VALUE(GLib::Object) <-> GObject

--- RVAL2BOXED(obj)
--- BOXED2RVAL(cobj, gtype)
    VALUE(GLib::Boxed) <-> GBoxed

--- RVAL2CSTR(v)
--- CSTR2RVAL(s)
    VALUE(String) <-> gchar*

--- GVAL2RVAL(v)
    GValue(GLib::Value) -> RValue. RVAL2GVAL(v) is not prepared. If you want to convert RValue to GValue, then use ((<rbgobj_rvalue_to_gvalue()|#Convert RValue to GValue>)).

--- GEV2RVAL(ev)
--- RVAL2GEV(ev)
    VALUE(Gtk::Event) <-> GtkEvent

--- GLIST2ARY(list)
--- GSLIT2ARY(list)
    GList/GSList of GObject -> Array

--- GLIST2ARY2(list)
--- GSLIT2ARY2(list)
    GList/GSList of GBoxed -> Array

=== Convert RGObjClassInfo <-> GType,Ruby class/instance
--- CLASS2CINFO(klass)
    Class -> RGObjClassInfo
--- GTYPE2CINFO(gtype)
    GType -> RGObjClassInfo
--- RVAL2CINFO(obj)
    VALUE -> RGObjClassInfo

=== Convert GType <->Ruby class/instance
--- GTYPE2CLASS(gtype)
    GType -> Class
--- CLASS2GTYPE(klass)
    Class -> GType
--- RVAL2GTYPE(obj)
    VALUE -> GType

=== Relatives
This saves an object from GC. Usually obj is self and rel is child widget/object or proc object.

--- G_RELATIVE(obj, rel)
    Make a relation.
--- G_RELATIVE2(obj, rel, id, hash_key)
    Make a removable relation.
--- G_REMOVE_RELATIVE(obj, id, hash_key)
    Remove a relation.

=== Setter methods
--- G_DEF_SETTER(klass, name)
--- G_DEF_SETTERS(klass)
    When you wrap setter-methods which have an argument like as follows, this macro implement them easily. 
    At first, you implement set_hoge(aParam) yourself, and then call G_DEF_SETTER(S). 
    If your class has plural setter-methods, it is better to use G_DEF_SETTERS(klass) as you only call G_DEF_SETTERS(klass) once a class.

 set_hoge(a)          #return self (implement yourself)
 hoge=(a)             #return a    (created automatically from set_hoge).

=== Block
--- G_BLOCK_PROC()
    This is a macro for rb_f_lambda()(until ruby-1.7.x) or rb_block_proc()(since 1.8.x).
    You shouldn't use rb_f_lambda() and rb_block_proc().

=== Argument of properties as hash
--- G_SET_PROPERTIES(self, properties)
    If you want to implement set_hoge(a, {:foo => 0, :bar =>"hoge"}) for properties, this macro will help you.

=== Symbol properties
--- G_SET_SYMBOL_PROPERTY(gtype, name)
    Define this in Init_*() for properties which use Symbol instead of String (e.g. Gtk::Stock).

=== Convert RValue to GValue
RVAL2GVAL(v) is not prepared. If you want to convert RValue to GValue, then use rbgobj_rvalue_to_gvalue().

  GValue gval = {0,};
  g_value_init(&gval, RVAL2GTYPE(value));

  rbgobj_rvalue_to_gvalue(value, &gval);
  (Then use gval...)

=== Implement class which does not conform to GType system(there are no G*_TYPE_* macros)
If there are a few classes, it may be better to make it as GBoxed object. You can see it in gtk/src/rbgdkatom.c,rbgtk.h.

=== GError handling
--- RAISE_GERROR(GError* error)
    If GError object return error. This macro throws an suitable exception.

=== GLib::Object#signal_connect's block variables set manually
--- G_DEF_SIGNAL_FUNC(klass, signal_name, signal_g2r_func);
--- signal_g2r_func(guint num, const GValue* values);
    These macros are special case for GLib::Object#signal_connect. You can define block variables yourself by this macro.

=== Recommanded editors
I don't care to use any editors, but when you develop Ruby-GNOME2 on Emacs, I recommand you to customize your ~/.emacs as follows.

 (c-add-style
  "ruby"
  '("bsd"
    (c-basic-offset . 4)
    (c-offsets-alist
     (case-label . 2)
     (label . 2)
      (statement-case-open . 2)
      (statement-case-intro . 2))))

 (add-hook 'c-mode-common-hook
           '(lambda () (setq indent-tabs-mode nil)))

- ((<Masao>))

-------------------------
= How to implement Ruby-GNOME2
This document is introduction how to implement Ruby-GNOME2(Especially, Ruby/GTK, Ruby/GNOME).