.hg- och .ccg-filerna

This macro declares a wrapper for a type that is derived from GObject, but whose wrapper is not derived from Gtk::Object.

_CLASS_GOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )

Till exempel, från adjustment.hg:

_CLASS_GOBJECT(Adjustment, GtkAdjustment, GTK_ADJUSTMENT, Glib::Object, GObject)

Detta makro deklarerar ett omslag för en typ vars omslag härleds från Gtk::Object, som en komponent eller dialogruta.

_CLASS_GTKOBJECT( C++-klass, C-klass, C-typkonverteringsmakro, C++-basklass, C-basklass )

Till exempel, från button.hg:

_CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Widget, GtkWidget)

You will typically use this macro when the class already derives from Gtk::Object. For instance, you will use it when wrapping a GTK Widget, because Gtk::Widget derives from Gtk::Object.

You might also derive non-widget classes from Gtk::Object so they can be used without Glib::RefPtr. For instance, they could then be instantiated with Gtk::make_managed() or on the stack as a member variable. This is convenient, but you should use this only when you are sure that true reference-counting is not needed. We consider it useful for widgets.

This macro declares a wrapper for a non-GObject struct, registered with g_boxed_type_register_static().

_CLASS_BOXEDTYPE( C++ class, C class, new function, copy function, free function )

Till exempel, från Gdk::RGBA:

_CLASS_BOXEDTYPE(RGBA, GdkRGBA, NONE, gdk_rgba_copy, gdk_rgba_free)

This macro declares a wrapper for a simple assignable struct such as GdkRectangle. It is similar to _CLASS_BOXEDTYPE, but the C struct is not allocated dynamically.

_CLASS_BOXEDTYPE_STATIC( C++-klass, C-klass )

Till exempel, för Gdk::Rectangle:

_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)

This macro declares a wrapper for an opaque struct that has copy and free functions. The new, copy and free functions will be used to instantiate the default constructor, copy constructor and destructor.

_CLASS_OPAQUE_COPYABLE( C++ class, C class, new function, copy function, free function )

Till exempel, från Glib::VariantType:

_CLASS_OPAQUE_COPYABLE(VariantType, GVariantType, NONE, g_variant_type_copy, g_variant_type_free)

This macro declares a wrapper for a reference-counted opaque struct. The C++ wrapper cannot be directly instantiated and can only be used with Glib::RefPtr.

_CLASS_OPAQUE_REFCOUNTED( C++ class, C class, new function, ref function, unref function )

Till exempel, för Gtk::CssSection:

_CLASS_OPAQUE_REFCOUNTED(CssSection, GtkCssSection, NONE, gtk_css_section_ref, gtk_css_section_unref)

This macro can be used to wrap structs which don't fit into any specialized category.

_CLASS_GENERIC( C++-klass, C-klass )

Till exempel, för Gdk::TimeCoord:

_CLASS_GENERIC(TimeCoord, GdkTimeCoord)

Detta makro deklarerar ett omslag för en typ som härleds från GTypeInterface.

_CLASS_INTERFACE( C++ class, C class, C casting macro, C interface struct, Base C++ class (optional), Base C class (optional) )

Till exempel, från celleditable.hg:

_CLASS_INTERFACE(CellEditable, GtkCellEditable, GTK_CELL_EDITABLE, GtkCellEditableIface)

Two extra optional parameters were once added, for the case that the interface derives from another interface, which was believed to be the case when the GInterface has another GInterface as a prerequisite. This is a misunderstanding, though. When GInterface A has GInterface B as a prerequisite, it means that every class that implements A shall also implement B. For instance, from loadableicon.hg in glibmm-2.4:

_CLASS_INTERFACE(LoadableIcon, GLoadableIcon, G_LOADABLE_ICON, GLoadableIconIface, Icon, GIcon)

Detta makro skapar en standardkonstruktor utan argument.

This macro creates a constructor with arguments, equivalent to a *_new() C function. It won't actually call the *_new() function, but will simply create an equivalent constructor with the same argument types. It takes a C++ constructor signature, and a C function name.

Det tar också ett valfritt extra argument:

When a constructor must be partly hand written because, for instance, the *_new() C function's parameters do not correspond directly to object properties, or because the *_new() C function does more than call g_object_new(), the _CONSTRUCT() macro may be used in the .ccg file to save some work. The _CONSTRUCT macro takes a series of property names and values. For instance, from button.ccg:

Button::Button(const Glib::ustring& label, bool mnemonic)
:
  _CONSTRUCT("label", label.c_str(), "use_underline", gboolean(mnemonic))
{}

Undertrycker deklaration och definition av standardkonstruktorn i _CLASS_BOXEDTYPE, _CLASS_BOXEDTYPE_STATIC och _CLASS_OPAQUE_COPYABLE.

Suppresses declaration and definition of the constructor that takes a pointer to the wrapped C object in _CLASS_BOXEDTYPE and _CLASS_BOXEDTYPE_STATIC.

Suppresses definition of the constructor that takes a pointer to the wrapped C object in _CLASS_INTERFACE and _CLASS_OPAQUE_COPYABLE.

Suppresses definition of the constructor that takes a pointer to the wrapped C object and the constructor that takes construct_params in _CLASS_GOBJECT and _CLASS_GTKOBJECT.

Undertrycker definition av destruktorn i _CLASS_GOBJECT och _CLASS_GTKOBJECT.

Suppresses declaration and definition of move constructor and move assignment operator in _CLASS_GOBJECT and _CLASS_GTKOBJECT.

Till exempel:

class Derived : public Glib::Object
{
  _CLASS_GOBJECT(Derived, GDerived, G_DERIVED, Glib::Object, GObject)

  _CUSTOM_MOVE_OPERATIONS

public:
  Derived(Derived&& src) noexcept;
  Derived& operator=(Derived&& src) noexcept;
  // ...
};

Undertrycker definition av Glib::wrap_new()-funktionen i _CLASS_GOBJECT.

Undertrycker definition av Glib::wrap()-funktionen i _CLASS_GOBJECT och _CLASS_GTKOBJECT.

Undertrycker deklaration och definition av Glib::wrap()-funktionen i _CLASS_GOBJECT, _CLASS_BOXEDTYPE, _CLASS_BOXEDTYPE_STATIC, _CLASS_OPAQUE_COPYABLE, _CLASS_INTERFACE och _CLASS_GTKOBJECT.

This macro generates the C++ method to wrap a C function.

_WRAP_METHOD( C++-metodsignatur, C-funktionsnamn)

Till exempel, från entry.hg:

_WRAP_METHOD(void set_text(const Glib::ustring& text), gtk_entry_set_text)

The C function (e.g. gtk_entry_set_text) is described more fully in the .defs file, and the convert*.m4 files contain the necessary conversion from the C++ parameter type to the C parameter type. This macro also generates doxygen documentation comments based on the *_docs.xml and *_docs_override.xml files.

Det finns några valfria extra argument:

Selecting which C++ types should be used is also important when wrapping C API. Though it's usually obvious what C++ types should be used in the C++ method, here are some hints:

This macro is like _WRAP_METHOD(), but it generates only the documentation for a C++ method that wraps a C function. Use this when you must hand-code the method, but you want to use the documentation that would be generated if the method was generated.

_WRAP_METHOD_DOCS_ONLY(C-funktionsnamn)

Till exempel, från recentinfo.hg:

_WRAP_METHOD_DOCS_ONLY(gtk_recent_info_get_applications)

Det finns några valfria extra argument:

gmmproc will warn you on stdout about functions, signals, properties and child properties that you have forgotten to wrap, helping to ensure that you are wrapping the complete API. But if you don't want to wrap some functions, signals, properties or child properties, or if you chose to hand-code some methods then you can use the _IGNORE(), _IGNORE_SIGNAL() or _IGNORE_PROPERTY() macro to make gmmproc stop complaining.

Till exempel, från flowbox.hg:

_IGNORE(gtk_flow_box_set_filter_func, gtk_flow_box_set_sort_func)
_IGNORE_SIGNAL(activate-cursor-child, toggle-cursor-child, move-cursor)

This macro generates the C++ libsigc++-style signal to wrap a C GObject signal. It actually generates a public accessor method, such as signal_clicked(), which returns a proxy object. gmmproc uses the .defs file to discover the C parameter types and the .m4 convert files to discover appropriate type conversions.

_WRAP_SIGNAL( C++-signalhanterarsignatur, C-signalnamn)

Till exempel, från button.hg:

_WRAP_SIGNAL(void clicked(),"clicked")

Signals usually have function pointers in the GTK struct, with a corresponding enum value and a g_signal_new() in the .c file.

Det finns några valfria extra argument:

This macro generates the C++ method to wrap a C GObject property. You must specify the property name and the wanted C++ type for the property. gmmproc uses the .defs file to discover the C type and the .m4 convert files to discover appropriate type conversions.

_WRAP_PROPERTY(C-egenskapsnamn, C++-typ)

Till exempel, från button.hg:

_WRAP_PROPERTY("label", Glib::ustring)

Det finns några valfria extra argument:

This macro generates the C++ method to wrap a virtual C function.

_WRAP_VFUNC( C++-metodsignatur, C-funktionsnamn)

Till exempel, från widget.hg:

_WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)

The C function (e.g. get_request_mode) is described more fully in the *_vfuncs.defs file, and the convert*.m4 files contain the necessary conversion from the C++ parameter type to the C parameter type. Conversions can also be written in the .hg file. Virtual functions often require special conversions that are best kept local to the .hg file where they are used.

Det finns några valfria extra argument:

A rule to which there may be exceptions: If the virtual C function returns a pointer to an object derived from GObject, i.e. a reference-counted object, then the virtual C++ function shall return a Glib::RefPtr<> object. One of the extra arguments refreturn or refreturn_ctype is required.

Detta makro genererar initieringskod för gränssnittet.

_IMPLEMENTS_INTERFACE(C++-gränssnittsnamn)

Till exempel, från grid.hg:

_IMPLEMENTS_INTERFACE(Orientable)

Det finns ett valfritt extra argument:

This macro generates a C++ enum to wrap a C enum. You must specify the desired C++ name and the name of the underlying C enum.

Till exempel, från enums.hg:

_WRAP_ENUM(Orientation, GtkOrientation)

Det finns några valfria extra argument:

This macro just generates a Doxygen documentation block for the enum. This is useful for enums that can't be wrapped with _WRAP_ENUM() because they are complexly defined (maybe using C macros) but including the generated enum documentation is still desired. It is used with the same syntax as _WRAP_ENUM() and also processes the same options (though NO_GTYPE, gtype_func <function_name> and CONV_TO_INT are ignored because they make no difference when just generating the enum's documentation).

This macro generates a C++ exception class, derived from Glib::Error, with a Code enum and a code() method. You must specify the desired C++ name, the name of the corresponding C enum, and the prefix for the C enum values.

This exception can then be thrown by methods which are generated from _WRAP_METHOD() with the errthrow option.

Till exempel, från pixbuf.hg:

_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)

_WRAP_GERROR() accepts the same optional arguments as _WRAP_ENUM() (though CONV_TO_INT is ignored because all exception class enums are plain enums within a class).

Use these macros if you're wrapping a simple struct or boxed type that provides direct access to its data members, to create getters and setters for the data members.

_MEMBER_GET(C++-namn, C-namn, C++-typ, C-typ)

_MEMBER_SET(C++-namn, C-namn, C++-typ, C-typ)

Till exempel, i rectangle.hg:

_MEMBER_GET(x, x, int, int)

Use these macros to automatically provide getters and setters for a data member that is a pointer type. For the getter function, it will create two methods, one const and one non-const.

_MEMBER_GET_PTR(C++-namn, C-namn, C++-typ, C-typ)

_MEMBER_SET_PTR(C++-namn, C-namn, C++-typ, C-typ)

Till exempel, för Pango::Analysis i item.hg:

// _MEMBER_GET_PTR(engine_lang, lang_engine, EngineLang*, PangoEngineLang*)
// Det är bara en kommentar. Det är svårt att hitta ett exempel i verkligheten.

Use these macros to provide getters and setters for a data member that is a GObject type that must be referenced before being returned.

_MEMBER_GET_GOBJECT(C++-namn, C-namn, C++-typ, C-typ)

_MEMBER_SET_GOBJECT(C++-namn, C-namn, C++-typ, C-typ)

Till exempel, i Pangomm, layoutline.hg:

_MEMBER_GET_GOBJECT(layout, layout, Pango::Layout, PangoLayout*)

For all the macros that process method signatures, it is possible to specify a different order for the C++ parameters than the existing order in the C function, virtual function or signal. For example, say that the following C function were being wrapped as a C++ method for the Gtk::Widget class:

void gtk_widget_set_device_events(GtkWidget* widget, GdkDevice* device,
  GdkEventMask events);

_WRAP_METHOD(void set_device_events(Gdk::EventMask events{events},
  const Glib::RefPtr<const Gdk::Device>& device{device}),
  gtk_widget_set_device_events)

_WRAP_METHOD(void set_device_events(Gdk::EventMask events{.},
  const Glib::RefPtr<const Gdk::Device>& device{.}),
  gtk_widget_set_device_events)

For all macros processing method signatures except _WRAP_SIGNAL() and _WRAP_VFUNC() it is also possible to make the parameters optional so that extra C++ methods are generated without the specified optional parameter. For example, say that the following *_new() function were being wrapped as a constructor in the Gtk::ToolButton class:

GtkToolItem* gtk_tool_button_new(GtkWidget* icon_widget, const gchar* label);

_WRAP_CTOR(ToolButton(Widget& icon_widget, const Glib::ustring& label{?}),
  gtk_tool_button_new)

With _WRAP_METHOD() it is also possible for the return of the wrapped C function (if it has one) to be placed in an output parameter of the C++ method instead of having the C++ method also return a value like the C function does. To do that, simply include the output parameter in the C++ method parameter list appending a {OUT} to the output parameter name. For example, if gtk_widget_get_request_mode() is declared as the following:

GtkSizeRequestMode gtk_widget_get_request_mode(GtkWidget* widget);

_WRAP_METHOD(void get_request_mode(SizeRequestMode& mode{OUT}) const,
  gtk_widget_get_request_mode)

_INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 = (SizeRequestMode)($4)')

_INITIALIZATION(`SizeRequestMode&',`GtkSizeRequestMode',`$3 = ($1)($4)')

_WRAP_METHOD() also supports setting C++ output parameters from C output parameters if the C function being wrapped has any. Suppose, for example, that we want to wrap the following C function that returns a value in its C output parameter out_mime_type:

GInputStream* gdk_clipboard_read_finish(GdkClipboard* clipboard,
  GAsyncResult* result, const char** out_mime_type, GError** error)

_WRAP_METHOD(Glib::RefPtr<Gio::InputStream> read_finish(
  const Glib::RefPtr<Gio::AsyncResult>& result,
  Glib::ustring& out_mime_type{>>}), gdk_clipboard_read_finish, errthrow)

_INITIALIZATION(`Glib::ustring&',`const char*',`$3 = Glib::convert_const_gchar_ptr_to_ustring($4)')

A string-valued input parameter in a C++ method is usually a const Glib::ustring& or a const std::string&. In C code it's a const gchar*. When an empty string is converted to const gchar*, it can be converted either to nullptr or to a pointer to an empty string (with c_str()). Some parameters in some C functions accept a nullptr, and interpret it in a special way. Other parameters must not be nullptr.

The default conversion in _WRAP_METHOD() and similar macros is