GtkBuilder               package:RGtk2               R Documentation

_G_t_k_B_u_i_l_d_e_r

_D_e_s_c_r_i_p_t_i_o_n:

     Build an interface from an XML UI definition

_M_e_t_h_o_d_s _a_n_d _F_u_n_c_t_i_o_n_s:

     'gtkBuilderNew()'
      'gtkBuilderAddFromFile(object, filename, .errwarn = TRUE)'
      'gtkBuilderAddFromString(object, buffer, length, .errwarn =
     TRUE)'
      'gtkBuilderGetObject(object, name)'
      'gtkBuilderGetObjects(object)'
      'gtkBuilderConnectSignals(object, user.data)'
      'gtkBuilderConnectSignalsFull(object, func, user.data)'
      'gtkBuilderSetTranslationDomain(object, domain)'
      'gtkBuilderGetTranslationDomain(object)'
      'gtkBuilderGetTypeFromName(object, type.name)'
      'gtkBuilderValueFromString(object, pspec, string, .errwarn =
     TRUE)'
      'gtkBuilderValueFromStringType(object, type, string, .errwarn =
     TRUE)'
      'gtkBuilder()'

_H_i_e_r_a_r_c_h_y:

     GObject
        +----GtkBuilder 

_D_e_t_a_i_l_e_d _D_e_s_c_r_i_p_t_i_o_n:

     A GtkBuilder is an auxiliary object that reads textual
     descriptions of a user interface and instantiates the described
     objects. To pass a  description to a GtkBuilder, call
     'gtkBuilderAddFromFile' or  'gtkBuilderAddFromString'. These
     functions can be called multiple times; the builder merges the
     content of all descriptions. 

     A GtkBuilder holds a reference to all objects that it has
     constructed and drops these references when it is finalized. This
     finalization can  cause the destruction of non-widget objects or
     widgets which are not  contained in a toplevel window. For
     toplevel windows constructed by a  builder, it is the
     responsibility of the user to call 'gtkWidgetDestroy'  to get rid
     of them and all the widgets they contain.

     The functions 'gtkBuilderGetObject' and 'gtkBuilderGetObjects' can
     be used to access the widgets in the interface by the names
     assigned  to them inside the UI description. Toplevel windows
     returned by these functions will stay around until the user
     explicitly destroys them with 'gtkWidgetDestroy'. Other widgets
     will either be part of a  larger hierarchy constructed by the
     builder (in which case you should not have to worry about their
     lifecycle), or without a parent, in which  case they have to be
     added to some container to make use of them.   Non-widget objects
     need to be reffed with 'gObjectRef()' to keep them beyond the
     lifespan of the builder.

     The function 'gtkBuilderConnectSignals' and variants thereof can
     be  used to connect handlers to the named signals in the
     description.

_G_t_k_B_u_i_l_d_e_r _U_I _D_e_f_i_n_i_t_i_o_n_s:

     GtkBuilder parses textual descriptions of user interfaces which 
     are specified in an XML format which can be roughly described  by
     the DTD below. We refer to these descriptions as  GtkBuilder UI
     definitions or just UI definitions if the context is clear. Do not
     confuse GtkBuilder UI Definitions with  GtkUIManager UI
     Definitions,  which are more limited in scope. 

     <!ELEMENT interface object* >
     <!ELEMENT object    (property|signal|child|ANY)* >
     <!ELEMENT property  PCDATA >
     <!ELEMENT signal    EMPTY >
     <!ELEMENT child     (object|ANY*) >

     <!ATTLIST interface  domain                 #IMPLIED >
     <!ATTLIST object     id                     #REQUIRED
                          class                  #REQUIRED
                          type-func              #IMPLIED
                          constructor            #IMPLIED >
     <!ATTLIST property   name                   #REQUIRED
                          translatable           #IMPLIED 
                          comments               #IMPLIED
                          context                #IMPLIED >
     <!ATTLIST signal     name                   #REQUIRED
                          handler                #REQUIRED
                          after                  #IMPLIED
                          swapped                #IMPLIED
                          object                 #IMPLIED
                          last_modification_time #IMPLIED >
     <!ATTLIST child      type                   #IMPLIED
                          internal-child         #IMPLIED >
      The toplevel element is <interface>. It optionally takes a
     "domain" attribute, which will make the builder look for
     translated strings using 'dgettext()' in the domain specified.
     This can also be done by calling 'gtkBuilderSetTranslationDomain'
     on the builder. Objects are described by <object> elements, which
     can contain <property> elements to set properties, <signal>
     elements which connect signals to handlers, and <child> elements,
     which describe child objects (most often widgets inside a
     container, but also e.g. actions in an action group, or columns in
     a tree model). A <child> element contains an <object> element
     which describes the child object.

     Typically, the specific kind of object represented by an <object>
     element is specified by the "class" attribute. If the type has not
     been loaded yet, GTK+ tries to find the '\code{gettype()}' from
     the class name by applying  heuristics. This works in most cases,
     but if necessary, it is possible to specify the name of the
     '\code{gettype()}'  explictly with the "type-func" attribute. As a
     special case,  GtkBuilder allows to use an object that has been
     constructed by a 'GtkUIManager' in another part of the UI
     definition by specifying the id of the 'GtkUIManager' in the
     "constructor" attribute and the name of the object in the "id"
     attribute.

     Objects must be given a name with the "id" attribute, which 
     allows the application to retrieve them from the builder with 
     'gtkBuilderGetObject'. An id is also necessary to use the  object
     as property value in other parts of the UI definition.

     Setting properties of objects is pretty straightforward with the
     <property> element: the "name" attribute specifies the name of the
     property, and the content of the element  specifies the value. If
     the "translatable" attribute is  set to a true value, GTK+ uses
     'gettext()' (or 'dgettext()' if the builder has a translation
     domain set) to find a translation  for the value. This happens
     before the value is parsed, so it can be used for properties of
     any type, but it is probably most useful for string properties. It
     is also possible to specify a context to disambiguate short
     strings, and comments which may help the translators.

     GtkBuilder can parse textual representations for the most common
     property types: characters, strings, integers, floating-point
     numbers, booleans (strings like "TRUE", "t", "yes", "y", "1" are
     interpreted as 'TRUE', strings like "FALSE, "f", "no", "n", "0"
     are interpreted as 'FALSE'), enumerations (can be specified by
     their  name, nick or integer value), flags (can be specified by
     their name,  nick, integer value, optionally combined with "|",
     e.g.  "GTK_VISIBLE|GTK_REALIZED")  and colors (in a format
     understood by  'gdkColorParse'). Objects can be referred to by
     their name.  Pixbufs can be specified as a filename of an image
     file to load. In general, GtkBuilder allows forward references to
     objects -  an object doesn't have to constructed before it can be
     referred to. The exception to this rule is that an object has to
     be constructed before it can be used as the value of a
     construct-only property. 

     Signal handlers are set up with the <signal> element. The "name"
     attribute specifies the name of the signal, and the "handler"
     attribute specifies the function to connect to the signal. By
     default, GTK+ tries to find the handler using 'gModuleSymbol()',
     but this can be changed by passing a custom
     'GtkBuilderConnectFunc' to 'gtkBuilderConnectSignalsFull'. The
     remaining attributes, "after", "swapped" and "object", have the
     same meaning as the  corresponding parameters of the
     'gSignalConnectObject()' or 'gSignalConnectData()' functions. A
     "last_modification_time" attribute is also allowed, but it does
     not have a meaning to the builder.

     Sometimes it is necessary to refer to widgets which have
     implicitly been constructed by GTK+ as part of a composite widget,
     to set  properties on them or to add further children (e.g. the
     'vbox'  of a 'GtkDialog'). This can be achieved by setting the
     "internal-child" propery of the <child> element to a true value.
     Note that GtkBuilder still requires an <object> element for the
     internal child, even if it has already been constructed.

     A number of widgets have different places where a child can be 
     added (e.g. tabs vs. page content in notebooks). This can be
     reflected in a UI definition by specifying the "type" attribute on
     a <child> The possible values for the "type" attribute are
     described in  the sections describing the widget-specific portions
     of UI definitions.

     _A GtkBuilder UI Definition_ <interface>
       <object class="GtkDialog" id="dialog1">
         <child internal-child="vbox">
           <object class="GtkVBox" id="vbox1">
             <property name="border-width">10</property>
             <child internal-child="action_area">
               <object class="GtkHButtonBox" id="hbuttonbox1">
                 <property name="border-width">20</property>
                 <child>
                   <object class="GtkButton" id="ok_button">
                     <property name="label">gtk-ok</property>
                     <property name="use-stock">TRUE</property>
                     <signal name="clicked"
     handler="ok_button_clicked"/>
                   </object>
                 </child>
               </object>
             </child>
           </object>
         </child>
       </object>
     </interface>
      Beyond this general structure, several object classes define
     their own XML DTD fragments for filling in the ANY placeholders in
     the DTD above. Note that a custom element in a <child> element
     gets parsed by the custom tag handler of the parent object, while
     a custom element in an <object> element gets parsed by the custom
     tag handler of the object. 

     These XML fragments are explained in the documentation of the
     respective objects, see  GtkWidget, GtkContainer, GtkDialog,
     GtkCellLayout, GtkColorSelectionDialog, GtkFontSelectionDialog,
     GtkComboBoxEntry, GtkExpander, GtkFrame, GtkListStore,
     GtkTreeStore, GtkNotebook, GtkSizeGroup, GtkTreeView,
     GtkUIManager, GtkActionGroup.

_S_t_r_u_c_t_u_r_e_s:


     '_G_t_k_B_u_i_l_d_e_r' _undocumented _


_C_o_n_v_e_n_i_e_n_t _C_o_n_s_t_r_u_c_t_i_o_n:

     'gtkBuilder' is the equivalent of 'gtkBuilderNew'.

_E_n_u_m_s _a_n_d _F_l_a_g_s:


     '_G_t_k_B_u_i_l_d_e_r_E_r_r_o_r' _undocumented _

          '_i_n_v_a_l_i_d-_t_y_p_e-_f_u_n_c_t_i_o_n' _undocumented _

          '_u_n_h_a_n_d_l_e_d-_t_a_g' _undocumented _

          '_m_i_s_s_i_n_g-_a_t_t_r_i_b_u_t_e' _undocumented _

          '_i_n_v_a_l_i_d-_a_t_t_r_i_b_u_t_e' _undocumented _

          '_i_n_v_a_l_i_d-_t_a_g' _undocumented _

          '_m_i_s_s_i_n_g-_p_r_o_p_e_r_t_y-_v_a_l_u_e' _undocumented _

          '_i_n_v_a_l_i_d-_v_a_l_u_e' _undocumented _


_U_s_e_r _F_u_n_c_t_i_o_n_s:


     '_G_t_k_B_u_i_l_d_e_r_C_o_n_n_e_c_t_F_u_n_c(_b_u_i_l_d_e_r, _o_b_j_e_c_t, _s_i_g_n_a_l._n_a_m_e, _h_a_n_d_l_e_r._n_a_m_e, _c_o_n_n_e_c_t._o_b_j_e_c_t, _f_l_a_g_s, _u_s_e_r._d_a_t_a)' 
          This is the signature of a function used to connect signals. 
          It is used by the 'gtkBuilderConnectSignals' and
          'gtkBuilderConnectSignalsFull' methods.  It is mainly
          intended for interpreted language bindings, but could be
          useful where the programmer wants more control over the
          signal connection process.  

          Since  2.12

          '_b_u_i_l_d_e_r' ['GtkBuilder']  a 'GtkBuilder'

          '_o_b_j_e_c_t' ['GObject']  object to connect a signal to

          '_s_i_g_n_a_l._n_a_m_e' [character]  name of the signal

          '_h_a_n_d_l_e_r._n_a_m_e' [character]  name of the handler

          '_c_o_n_n_e_c_t._o_b_j_e_c_t' ['GObject']  a 'GObject', if non-'NULL', use
               'gSignalConnectObject()'

          '_f_l_a_g_s' ['GConnectFlags'] 'GConnectFlags' to use

          '_u_s_e_r._d_a_t_a' [R object]  user data


_P_r_o_p_e_r_t_i_e_s:


     '_t_r_a_n_s_l_a_t_i_o_n-_d_o_m_a_i_n' [_c_h_a_r_a_c_t_e_r : _R_e_a_d / _W_r_i_t_e] The translation
          domain used when translating property values that have been
          marked as translatable in interface descriptions. If the
          translation domain is 'NULL', 'GtkBuilder' uses 'gettext()',
          otherwise 'dgettext()'.  

          Default value: NULL  Since  2.12


_A_u_t_h_o_r(_s):

     Derived by RGtkGen from GTK+ documentation

_R_e_f_e_r_e_n_c_e_s:

     <URL: http://developer.gnome.org/doc/API/2.0/gtk/GtkBuilder.html>

