Τα αρχεία .hg και .ccg

Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για έναν τύπο που παράγεται από την GObject, αλλά του οποίου ο συσκευαστής δεν παράγεται από την Gtk::Object.

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

For instance, from accelgroup.hg:

_CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP, Glib::Object, GObject)

Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για έναν τύπο του οποίου ο συσκευαστής παράγεται από την Gtk::Object, όπως ένα γραφικό συστατικό ή διάλογο.

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

For instance, from button.hg:

_CLASS_GTKOBJECT(Button, GtkButton, GTK_BUTTON, Gtk::Bin, GtkBin)

Θα χρησιμοποιήσουμε τυπικά αυτή τη μακροεντολή όταν η κλάση παράγεται ήδη από την Gtk::Object. Για παράδειγμα, θα την χρησιμοποιήσετε όταν συσκευάζετε ένα γραφικό συστατικό GTK+, επειδή η Gtk::Widget παράγεται από Gtk::Object.

Μπορείτε επίσης να παράξετε κλάσεις μη γραφικού συστατικού από Gtk::Object έτσι ώστε να μπορεί να χρησιμοποιηθεί χωρίς Glib::RefPtr. Για παράδειγμα, μπορούν έπειτα να αρχικοποιηθούν με Gtk::manage() ή στη στοίβα ως μεταβλητή μέλους. Αυτό είναι βολικό, αλλά θα πρέπει να χρησιμοποιήσετε αυτό μόνον όταν είσαστε σίγουροι ότι η αληθινή μέτρηση αναφορών δεν χρειάζεται. Το θεωρούμε χρήσιμο για γραφικά συστατικά.

Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για μια δομή μη GObject, καταχωρισμένη με g_boxed_type_register_static().

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

For instance, from Gdk::RGBA:

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

Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για μια απλή μεταβιβάσιμη δομή όπως GdkRectangle. Είναι παρόμοια με την _CLASS_BOXEDTYPE, αλλά η δομή C δεν παραχωρείται δυναμικά.

_CLASS_BOXEDTYPE_STATIC( C++ class, C class )

For instance, for Gdk::Rectangle:

_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)

Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για μια αδιαφανή δομή που έχει ελεύθερες συναρτήσεις και συναρτήσεις αντιγραφής. Οι νέες και ελεύθερες συναρτήσεις καθώς και οι συναρτήσεις αντιγραφής θα χρησιμοποιηθούν για αρχικοποίηση του προεπιλεγμένου κατασκευαστή, για αντιγραφή κατασκευαστή και καταστροφέα.

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

For instance, from Glib::Checksum:

_CLASS_OPAQUE_COPYABLE(Checksum, GChecksum, NONE, g_checksum_copy, g_checksum_free)

Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για μια αδιαφανή δομή μετρημένης αναφοράς. Ο συσκευαστής C++ δεν μπορεί να είναι άμεσα αρχικοποιημένος και μπορεί μόνο να χρησιμοποιηθεί με την Glib::RefPtr.

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

For instance, for Pango::Coverage:

_CLASS_OPAQUE_REFCOUNTED(Coverage, PangoCoverage, pango_coverage_new, pango_coverage_ref, pango_coverage_unref)

Αυτή η μακροεντολή μπορεί να χρησιμοποιηθεί για να συσκευάσει δομές που δεν προσαρμόζονται σε οποιαδήποτε ειδική κατηγορία.

_CLASS_GENERIC( C++ class, C class )

For instance, for Pango::AttrIter:

_CLASS_GENERIC(AttrIter, PangoAttrIterator)

Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για έναν τύπο που παράγεται από GTypeInterface.

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

For instance, from celleditable.hg:

_CLASS_INTERFACE(CellEditable, GtkCellEditable, GTK_CELL_EDITABLE, GtkCellEditableIface)

Two extra parameters are optional, for the case that the interface derives from another interface, which should be the case when the GInterface has another GInterface as a prerequisite. For instance, from loadableicon.hg:

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

Αυτή η μακροεντολή δημιουργεί έναν προεπιλεγμένο κατασκευαστή χωρίς ορίσματα.

Αυτή η μακροεντολή δημιουργεί έναν κατασκευαστή με ορίσματα, ισοδύναμο με μια συνάρτηση C *_new(). Στην πραγματικότητα δεν καλεί τη συνάρτηση *_new(), αλλά θα δημιουργήσει απλά έναν ισοδύναμο κατασκευαστή με τους ίδιους τύπους ορίσματος. Παίρνει μια υπογραφή κατασκευαστή C++ και ένα όνομα συνάρτησης C.

It also takes an optional 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))
{}

Αυτή η μακροεντολή παράγει τη μέθοδο C++ για να συσκευάσει μια συνάρτηση C.

_WRAP_METHOD( C++ method signature, C function name)

For instance, from entry.hg:

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

Η συνάρτηση C (π.χ. gtk_entry_set_text) περιγράφεται πληρέστερα στο αρχείο .defs και τα αρχεία convert*.m4 περιέχουν την απαραίτητη μετατροπή από τον τύπο παραμέτρου C++ στον τύπο παραμέτρου C. Αυτή η μακροεντολή επίσης παράγει σχόλια τεκμηρίωσης doxygen με βάση τα αρχεία *_docs.xml και *_docs_override.xml.

There are some optional extra arguments:

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:

Αυτή η μακροεντολή είναι παρόμοια με την _WRAP_METHOD(), αλλά δημιουργεί μόνο την τεκμηρίωση για τη μέθοδο C++ που συσκευάζει μια συνάρτηση C. Χρησιμοποιήστε το όταν πρέπει να κωδικοποιήσετε με το χέρι τη μέθοδο, αλλά θέλετε να χρησιμοποιήσετε την τεκμηρίωση που πρέπει να δημιουργηθεί αν η μέθοδος είχε δημιουργηθεί.

_WRAP_METHOD_DOCS_ONLY(C function name)

For instance, from container.hg:

_WRAP_METHOD_DOCS_ONLY(gtk_container_remove)

There are some optional extra arguments:

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(), _IGNORE_PROPERTY() or _IGNORE_CHILD_PROPERTY() macro to make gmmproc stop complaining.

For instance, from 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)

Αυτή η μακροεντολή παράγει το σήμα τεχνοτροπίας libsigc++ της C++ για να συσκευάσει ένα σήμα GObject. Στην πραγματικότητα παράγει μια δημόσια μέθοδο στοιχείου πρόσβασης, όπως signal_clicked(), που επιστρέφει ένα αντικείμενο μεσολάβησης. Η gmmproc χρησιμοποιεί το αρχείο .defs για να ανακαλύψει τους τύπους παραμέτρου C και το .m4 μετατρέπει αρχεία για να ανακαλύψει τον κατάλληλο τύπο μετατροπών.

_WRAP_SIGNAL( C++ signal handler signature, C signal name)

For instance, from button.hg:

_WRAP_SIGNAL(void clicked(),"clicked")

Τα σήματα συνήθως έχουν δείκτες συνάρτησης στη δομή GTK, με μια αντίστοιχη τιμή απαρίθμησης και μια g_signal_new() στο αρχείο .c.

There are some optional extra arguments:

Αυτή η μακροεντολή δημιουργεί μια μέθοδο C++ για συσκευασία μιας ιδιότητας GObject C. Πρέπει να ορίσετε το όνομα της ιδιότητας και τον επιθυμητό τύπο C++ για την ιδιότητα. Η gmmproc χρησιμοποιεί το αρχείο .defs για να ανακαλύψει τον τύπο C και να μετατρέψει τα αρχεία .m4 για να βρει κατάλληλες μετατροπές τύπου.

_WRAP_PROPERTY(C property name, C++ type)

For instance, from button.hg:

_WRAP_PROPERTY("label", Glib::ustring)

There are some optional extra arguments:

Αυτή η μακροεντολή παράγει τη μέθοδο C++ για να συσκευάσει μια εικονική συνάρτηση C.

_WRAP_VFUNC( C++ method signature, C function name)

For instance, from 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.

There are some optional extra arguments:

Ένας κανόνας στον οποίον ενδέχεται να υπάρχουν εξαιρέσεις: Αν η εικονική συνάρτηση C επιστρέφει έναν δείκτη σε ένα αντικείμενο που παράγεται από την GObject, δηλαδή ένα αντικείμενο με μετρημένες αναφορές, τότε η εικονική συνάρτηση C++ θα επιστρέψει ένα αντικείμενο Glib::RefPtr<>. Ένα από τα πρόσθετα ορίσματα refreturn ή refreturn_ctype απαιτείται.

This macro generates the C++ method to wrap a GtkContainer child property. (See GtkContainer for more information about child properties). Similarly to _WRAP_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_CHILD_PROPERTY(C child property name, C++ type)

For instance, from notebook.hg:

_WRAP_CHILD_PROPERTY("tab-expand", bool)

_WRAP_CHILD_PROPERTY() accepts the same optional arguments as _WRAP_PROPERTY().

Αυτή η μακροεντολή δημιουργεί έναν κώδικα αρχικοποίησης για τη διεπαφή.

_IMPLEMENTS_INTERFACE(C++ interface name)

For instance, from button.hg:

_IMPLEMENTS_INTERFACE(Activatable)

There is one optional extra argument:

Αυτή η μακροεντολή δημιουργεί μια απαρίθμηση C++ για να συσκευάσει μια απαρίθμηση C. Πρέπει να ορίσετε το επιθυμητό όνομα C++ και το όνομα της υποκείμενης απαρίθμησης C.

For instance, from enums.hg:

_WRAP_ENUM(WindowType, GtkWindowType)

Αν η απαρίθμηση δεν είναι μια GType, πρέπει να περάσετε μια τρίτη παράμετρο NO_GTYPE. Αυτή είναι η περίπτωση όταν δεν υπάρχει συνάρτηση *_get_type() για την απαρίθμηση C, αλλά προσέξτε ότι δεν χρειάζεται μόνο να συμπεριλάβετε μια πρόσθετη κεφαλίδα για αυτήν τη συνάρτηση. Θα πρέπει επίσης να στείλετε ένα σφάλμα στην API C, επειδή όλες οι απαριθμήσεις πρέπει να καταχωριστούν ως GTypes.

_WRAP_ENUM() accepts the optional newin parameter. See _WRAP_METHOD().

For example, from icontheme.hg:

_WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)

Αυτή η μακροεντολή δημιουργεί μια ομάδα τεκμηρίωσης Doxygen για την απαρίθμηση. Αυτό είναι χρήσιμο για απαριθμήσεις που δεν μπορούν να συσκευαστούν με _WRAP_ENUM() επειδή ορίζονται σύνθετα (ίσως χρησιμοποιώντας μακροεντολές C), αλλά η συμπερίληψη της δημιουργούμενης τεκμηρίωσης απαρίθμησης είναι ακόμα επιθυμητή. Χρησιμοποιείται με την ίδια σύνταξη ως _WRAP_ENUM() και επεξεργάζεται επίσης τις ίδιες επιλογές (αν και ο NO_GTYPE αγνοείται απλά επειδή δεν κάνει καμιά διαφορά όταν δημιουργεί μόνο την τεκμηρίωση απαρίθμησης).

Αυτή η μακροεντολή δημιουργεί μια κλάση εξαίρεσης C++, που παράγεται από Glib::Error, με μια απαρίθμηση κώδικα και μια μέθοδο code(). Πρέπει να ορίσετε το επιθυμητό όνομα C++, το όνομα της αντίστοιχης απαρίθμησης C και το πρόθεμα για τις τιμές απαρίθμησης C.

Αυτή η εξαίρεση μπορεί τότε να δημιουργηθεί από μεθόδους που δημιουργούνται από _WRAP_METHOD() με επιλογή δημιουργία σφάλματος (errthrow).

_WRAP_GERROR() accepts the optional newin parameter. See _WRAP_METHOD().

For instance, from pixbuf.hg:

_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)

Χρησιμοποιήστε αυτές τις μακροεντολές αν συσκευάζετε μια απλή δομή ή τύπου πλαισίου που παρέχει άμεση πρόσβαση στα μέλη δεδομένων, για να δημιουργήσετε λήπτες και μεταλλάκτες (getters and setters) για τα μέλη δεδομένων.

_MEMBER_GET(C++ name, C name, C++ type, C type)

_MEMBER_SET(C++ name, C name, C++ type, C type)

For example, in rectangle.hg:

_MEMBER_GET(x, x, int, int)

Χρησιμοποιήστε αυτές τις μακροεντολές για αυτόματη παροχή ληπτών και μεταλλακτών (getters and setters) για ένα μέλος δεδομένων που είναι τύπου δείκτη. Για τη συνάρτηση δεκτών, θα δημιουργήσει δύο μεθόδους, μια σταθερή και μια μη σταθερή.

_MEMBER_GET_PTR(C++ name, C name, C++ type, C type)

_MEMBER_SET_PTR(C++ name, C name, C++ type, C type)

For example, for Pango::Analysis in item.hg:

// _MEMBER_GET_PTR(engine_lang, lang_engine, EngineLang*, PangoEngineLang*)
// It's just a comment. It's difficult to find a real-world example.

χρησιμοποιήστε αυτές τις μακροεντολές για να δώσετε λήπτες και μεταλλάκτες (getters and setters) για ένα μέλος δεδομένων που είναι τύπου GObject που πρέπει να αναφερθεί πριν επιστραφεί.

_MEMBER_GET_GOBJECT(C++ name, C name, C++ type, C type)

_MEMBER_SET_GOBJECT(C++ name, C name, C++ type, C type)

For example, in 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 rect:

        gboolean gtk_icon_view_get_cell_rect(GtkIconView* icon_view,
        GtkTreePath* path, GtkCellRenderer* cell, GdkRectangle* rect);
      

        _WRAP_METHOD(bool get_cell_rect(const TreeModel::Path& path, const
        CellRenderer& cell, Gdk::Rectangle& rect{>>}) const,
        gtk_icon_view_get_cell_rect)
      

        _INITIALIZATION(`Gdk::Rectangle&',`GdkRectangle', `$3 =
        Glib::wrap(&($4))')