## GtkBuilderScope GtkBuilderScope — Bindings for GtkBuilder |

## Functions

GtkBuilderScope * | gtk_builder_cscope_new ()
void | gtk_builder_cscope_add_callback_symbol ()
void | gtk_builder_cscope_add_callback_symbols ()
GCallback | gtk_builder_cscope_lookup_callback_symbol ()

## Types and Values

| GtkBuilderScope
enum | GtkBuilderClosureFlags
struct | GtkBuilderScopeInterface
| GtkBuilderCScope

## Object Hierarchy

        GInterface
        ╰── GtkBuilderScope
        GObject
        ╰── GtkBuilderCScope

## Prerequisites

GtkBuilderScope requires GObject.

## Implemented Interfaces

GtkBuilderCScope implements GtkBuilderScope.

## Known Implementations

GtkBuilderScope is implemented by GtkBuilderCScope.

## Includes

    #include <gtk/gtk.h>

## Description

GtkBuilderScope is an interface to provide support to GtkBuilder, primarily for looking up programming-language-specific values for strings that are given in a GtkBuilder UI file.

The primary intended audience is bindings that want to provide deeper integration of GtkBuilder into the language.

A GtkBuilderScope instance may be used with multiple GtkBuilder objects, even at once.

By default, GTK will use its own implementation of GtkBuilderScope for the C language which can be created via `gtk_builder_cscope_new()`.

GtkBuilderCScope instances use symbols explicitly added to `builder` with prior calls to `gtk_builder_cscope_add_callback_symbol()`. If developers want to do that, they are encouraged to create their own scopes for that purpose.

In the case that symbols are not explicitly added; GTK will uses GModule’s introspective features (by opening the module `NULL`) to look at the application’s symbol table. From here it tries to match the signal function names given in the interface description with symbols in the application.

Note that unless `gtk_builder_cscope_add_callback_symbol()` is called for all signal callbacks which are referenced by the loaded XML, this functionality will require that GModule be supported on the platform.

## Functions

### gtk_builder_cscope_new ()

    GtkBuilderScope *
    gtk_builder_cscope_new (void);

Creates a new GtkBuilderCScope object to use with future GtkBuilder instances.

Calling this function is only necessary if you want to add custom callbacks via `gtk_builder_cscope_add_callback_symbol()`.

#### Returns

a new GtkBuilderCScope.

[transfer full][type GtkBuilderCScope]

### gtk_builder_cscope_add_callback_symbol ()

    void
    gtk_builder_cscope_add_callback_symbol
                                   (GtkBuilderCScope *self,
                                    const char *callback_name,
                                    GCallback callback_symbol);

Adds the `callback_symbol` to the scope of `builder` under the given `callback_name` .

Using this function overrides the behavior of `gtk_builder_create_closure()` for any callback symbols that are added. Using this method allows for better encapsulation as it does not require that callback symbols be declared in the global namespace.

#### Parameters

self | a GtkBuilderCScope |
callback_name | The name of the callback, as expected in the XML |
callback_symbol | The callback pointer. | [scope async]

### gtk_builder_cscope_add_callback_symbols ()

    void
    gtk_builder_cscope_add_callback_symbols
                                   (GtkBuilderCScope *self,
                                    const char *first_callback_name,
                                    GCallback first_callback_symbol,
                                    ...);

A convenience function to add many callbacks instead of calling `gtk_builder_cscope_add_callback_symbol()` for each symbol.

[skip]

#### Parameters

self | a GtkBuilderCScope |
first_callback_name | The name of the callback, as expected in the XML |
first_callback_symbol | The callback pointer. | [scope async]
... | A list of callback name and callback symbol pairs terminated with `NULL` |

### gtk_builder_cscope_lookup_callback_symbol ()

    GCallback
    gtk_builder_cscope_lookup_callback_symbol
                                   (GtkBuilderCScope *self,
                                    const char *callback_name);

Fetches a symbol previously added to `self` with `gtk_builder_cscope_add_callback_symbol()`.

[skip]

#### Parameters

self | a GtkBuilderCScope |
callback_name | The name of the callback |

#### Returns

The callback symbol in `builder` for `callback_name` , or `NULL`.

[nullable][transfer none]

## Types and Values

### GtkBuilderScope

    typedef struct _GtkBuilderScope GtkBuilderScope;

### enum GtkBuilderClosureFlags

The list of flags that can be passed to `gtk_builder_create_closure()`. New values may be added in the future for new features, so external implementations of GtkBuilderScopeInterface should test the flags for unknown values and raise a %`GTK_BUILDER_ERROR_INVALID_ATTRIBUTE` error when they encounter one.

#### Members

GTK_BUILDER_CLOSURE_SWAPPED | The closure should be created swapped. See `g_cclosure_new_swap()` for details. |

### struct GtkBuilderScopeInterface

    struct GtkBuilderScopeInterface {
      GType                 (* get_type_from_name)                  (GtkBuilderScope        *self,
                                                                     GtkBuilder             *builder,
                                                                     const char             *type_name);
      GType                 (* get_type_from_function)              (GtkBuilderScope        *self,
                                                                     GtkBuilder             *builder,
                                                                     const char             *function_name);

      GClosure *            (* create_closure)                      (GtkBuilderScope        *self,
                                                                     GtkBuilder             *builder,
                                                                     const char             *function_name,
                                                                     GtkBuilderClosureFlags  flags,
                                                                     GObject                *object,
                                                                     GError                **error);
    };

The virtual function table to implement for GtkBuilderScope implementations. Default implementations for each function do exist, but they usually just fail, so it is suggested that implementations implement all of them.

#### Members

`get_type_from_name` () | Try to lookup a GType via the its name. See `gtk_builder_get_type_from_name()` for more details. The C implementation will use `g_type_from_name()` and if that fails try to guess the correct function name for registering the type and then use `dlsym()` to load it. The default implementation just tries `g_type_from_name()` and otherwise fails. |
`get_type_from_function` () | Try to lookup a GType via the given function name, specified explicitly in a GtkBuilder file, like via the "type-func" attribute in the "<object>" tag. This function is very rarely used. The C implementation will use `dlsym()` and call the resulting function as a GTypeFunc. The default implementation will fail and just return `G_TYPE_INVALID`. |
`create_closure` () | Create a closure with the given arguments. See `gtk_builder_create_closure()` for more details on those. The C implementation will try to use `dlsym()` to locate the function name and then `g_cclosure_new()` to create a closure for the symbol. The default implementation just fails and returns `NULL`. |

### GtkBuilderCScope

    typedef struct _GtkBuilderCScope GtkBuilderCScope;

## See Also

GtkBuilder, GClosure