Context Navigation

Definition XML file format

Definitions are specified in an XML file (usually .defs). The definitions file contains the specification of all the classes, enums, flags, boxed types and methods that need bindings. RbgTool is able to generate these definition files from header files (although they are often incomplete because RbgTool isn't able to parse everything). The actual bindings are then generated by RbgTool from one or more definition files (for information on how to override specific generation see OverrideSyntax). The actual available elements and attributes in the XML definitions file are described below.

Elements

The root XML element must be <definitions xmlns='http://www.novowork.com/rbgtool'> (mind the namespace). In this root element, the following children can be specified:

<class>
<enum>
<flag>
<boxed>
<method>
<constructor>

Class Element (`<class>`)

The class element represents a GObject class. It has the following attributes:

gtype the object type in camel case (e.g. GtkSourceView)
parent the parent type of the object (e.g. GtkTextView), it is not necessary to specify this as it is currently not used
bind_name the name by which the type should be bound, if not specified, the bind_name is figured out during code generation depending on the specified namespace during the generation (inside its namespace, e.g. SourceView)

A class element can contain the following child elements:

<enum>
<flag>
<method>
<constructor>
<property>

Enum Element (`<enum>`)

The enum element represents a !GEnum. It has the following attributes:

gtype the !GEnum type in camel case (e.g. GtkSourceSearchFlags)
bind_name the name by which the type should be bound, if not specified, the bind_name is figured out during code generation depending on the specified namespace during the generation (inside its namespace, e.g. SourceSearchFlags)

This element has no children, the actual items in the enumeration are automatically picked up.

Flag Element (`<flag>`)

The flag element is actually pretty much the same as the enum element, except that the values are bitwise exclusive. The attributes are the same as for the enum element.

Boxed Element (`<boxed>`)

The boxed element represents a !GBoxed type. It has the same attributes (except for the parent attribute) and possible child elements as the class element, although it is unusual to have flag, enum or constructor types as children of a boxed type.

Method Element (`<method>`)

The method element represents a function. It has the following attributes:

name the function C name (e.g. gtk_source_buffer_ensure_highlight)
bind_name the name by which the method should be bound, if not specified, the bind_name is figured out during code generation depending on the specified namespace/parent during the generation (inside its namespace, e.g. ensure_highlight)
level either class or instance indicating a class method (e.g. gtk_source_style_scheme_manager_get_default) or instance method (e.g. gtk_source_buffer_ensure_highlight) respectively
return_type the C return type of the function in C. If the type is void, this attribute should not be specified
return_const if specified, the return type is const. If the return type is not const, then simply don't specify the attribute
destructive if specified, marks the method as destructive (meaning that it will change its contents). This is used to generate an alias for the function with ! appended (as is common in ruby)

The method element can have the following child elements:

<argument>

For a list of supported return type conversions, see SupportedTypes.

Constructor Element (`<constructor>`)

The constructor element is exactly the same as the method element concerning attributes and child elements. The only difference is the way the constructor is generated (as initialize on the ruby side). There should not be more than one constructor specified in a class.

Argument Element (`<argument>`)

The argument element is used inside constructor and method elements to specify the function arguments. It has the following attributes:

name the name of the argument (e.g. buffer)
type the C type of the argument (e.g. GtkSourceBuffer)
const if specified, the type is const

For a list of supported type conversions, see SupportedTypes.

Property Element (`<property>`)

The property element can be specified inside a class element. It has only one attribute, namely name which specifies the name of the property. This element should be specified because property setters and getters are generated by the gobject bindings for ruby automatically, and any getters/setters for these properties which are explicitly defined in the definitions file need to be ignored. RbgTool is able to do this automatically if you specify these properties with the property element.

Special argument/return types

There are two special argument/return types that can be specified to indicate special type conversion handling by RbgTool. These are:

char**[null], gchar**[null]

This indicates to RbgTool that the type is a NULL terminated array of C strings which are converted to and from ruby arrays properly. The types char** and gchar** can't be automatically handled because it is unknown what the size of these are

GList*[node type], GSList*[node type]

This is used to allow RbgTool to automatically convert a !GList or !GSList to/from ruby arrays. The node type is used to provide the proper conversion for the elements of the !GList (since they can't be inferred from anything). An example would be the type GList[GtkContainer*]

Example definition

<?xml version='1.0'?>
<definitions xmlns='http://www.novowork.com/rbgtool'>
  <!-- ============================================================================== -->
  <!-- | * From file /usr/include/gtksourceview-2.0/gtksourceview/gtksourceview.h * | -->
  <!-- ============================================================================== -->
  <class gtype='GtkSourceView' parent='GtkTextView'>
    <property name='show_line_numbers'/>
    <property name='show_line_marks'/>
    <property name='tab_width'/>
    <property name='indent_width'/>
    <property name='auto_indent'/>
    <property name='insert_spaces'/>
    <property name='show_right_margin'/>
    <property name='right_margin_position'/>
    <property name='smart_home_end'/>
    <property name='highlight_current_line'/>
    <property name='indent_on_tab'/>
    <constructor name='gtk_source_view_new' return-type='GtkWidget*'/>
    <method name='gtk_source_view_get_type' level='class' return-type='GType' bind-name='get_type'/>
    <method name='gtk_source_view_set_show_line_numbers' level='instance' bind-name='set_show_line_numbers'>
      <argument name='show' type='gboolean'/>
    </method>
    <method name='gtk_source_view_get_show_line_numbers' level='instance' return-type='gboolean' bind-name='get_show_line_numbers'/>
    <method name='gtk_source_view_set_tab_width' level='instance' bind-name='set_tab_width'>
      <argument name='width' type='guint'/>
    </method>
    <method name='gtk_source_view_get_tab_width' level='instance' return-type='guint' bind-name='get_tab_width'/>
    <method name='gtk_source_view_set_indent_width' level='instance' bind-name='set_indent_width'>
      <argument name='width' type='gint'/>
    </method>
    <method name='gtk_source_view_get_indent_width' level='instance' return-type='gint' bind-name='get_indent_width'/>
    <method name='gtk_source_view_set_auto_indent' level='instance' bind-name='set_auto_indent'>
      <argument name='enable' type='gboolean'/>
    </method>
    <method name='gtk_source_view_get_auto_indent' level='instance' return-type='gboolean' bind-name='get_auto_indent'/>
    <method name='gtk_source_view_set_insert_spaces_instead_of_tabs' level='instance' bind-name='set_insert_spaces_instead_of_tabs'>
      <argument name='enable' type='gboolean'/>
    </method>
    <method name='gtk_source_view_get_insert_spaces_instead_of_tabs' level='instance' return-type='gboolean' bind-name='get_insert_spaces_instead_of_tabs'/>
    <method name='gtk_source_view_set_indent_on_tab' level='instance' bind-name='set_indent_on_tab'>
      <argument name='enable' type='gboolean'/>
    </method>
    <method name='gtk_source_view_get_indent_on_tab' level='instance' return-type='gboolean' bind-name='get_indent_on_tab'/>
    <method name='gtk_source_view_set_highlight_current_line' level='instance' bind-name='set_highlight_current_line'>
      <argument name='show' type='gboolean'/>
    </method>
    <method name='gtk_source_view_get_highlight_current_line' level='instance' return-type='gboolean' bind-name='get_highlight_current_line'/>
    <method name='gtk_source_view_set_show_right_margin' level='instance' bind-name='set_show_right_margin'>
      <argument name='show' type='gboolean'/>
    </method>
    <method name='gtk_source_view_get_show_right_margin' level='instance' return-type='gboolean' bind-name='get_show_right_margin'/>
    <method name='gtk_source_view_set_right_margin_position' level='instance' bind-name='set_right_margin_position'>
      <argument name='pos' type='guint'/>
    </method>
    <method name='gtk_source_view_get_right_margin_position' level='instance' return-type='guint' bind-name='get_right_margin_position'/>
    <method name='gtk_source_view_set_smart_home_end' level='instance' bind-name='set_smart_home_end'>
      <argument name='smart_he' type='GtkSourceSmartHomeEndType'/>
    </method>
    <method name='gtk_source_view_get_smart_home_end' level='instance' return-type='GtkSourceSmartHomeEndType' bind-name='get_smart_home_end'/>
  </class>
  <enum gtype='GtkSourceSmartHomeEndType'/>
</definitions>

Download in other formats:

Plain Text

`gtype`	the object type in camel case (e.g. `GtkSourceView`)
`parent`	the parent type of the object (e.g. `GtkTextView`), it is not necessary to specify this as it is currently not used
`bind_name`	the name by which the type should be bound, if not specified, the bind_name is figured out during code generation depending on the specified namespace during the generation (inside its namespace, e.g. `SourceView`)

`gtype`	the !GEnum type in camel case (e.g. `GtkSourceSearchFlags`)
`bind_name`	the name by which the type should be bound, if not specified, the bind_name is figured out during code generation depending on the specified namespace during the generation (inside its namespace, e.g. `SourceSearchFlags`)

`name`	the function C name (e.g. `gtk_source_buffer_ensure_highlight`)
`bind_name`	the name by which the method should be bound, if not specified, the bind_name is figured out during code generation depending on the specified namespace/parent during the generation (inside its namespace, e.g. `ensure_highlight`)
`level`	either `class` or `instance` indicating a class method (e.g. `gtk_source_style_scheme_manager_get_default`) or instance method (e.g. `gtk_source_buffer_ensure_highlight`) respectively
`return_type`	the C return type of the function in C. If the type is void, this attribute should not be specified
`return_const`	if specified, the return type is const. If the return type is not const, then simply don't specify the attribute
`destructive`	if specified, marks the method as destructive (meaning that it will change its contents). This is used to generate an alias for the function with ! appended (as is common in ruby)

`name`	the name of the argument (e.g. `buffer`)
`type`	the C type of the argument (e.g. `GtkSourceBuffer`)
`const`	if specified, the type is const

Context Navigation

Definition XML file format

Elements

Class Element (<class>)

Enum Element (<enum>)

Flag Element (<flag>)

Boxed Element (<boxed>)

Method Element (<method>)

Constructor Element (<constructor>)

Argument Element (<argument>)

Property Element (<property>)