Τα αρχεία .hg και .ccg
Τα πηγαία αρχεία .hg και .ccg είναι πολύ παρόμοια. με τα πηγαία αρχεία .h και .cc της C++, αλλά περιέχουν πρόσθετες μακροεντολές, όπως _CLASS_GOBJECT() και _WRAP_METHOD(), από τις οποίες η gmmproc δημιουργεί κατάλληλο πηγαίο κώδικα C++, συνήθως στην ίδια θέση στην κεφαλίδα. Οποιοσδήποτε πρόσθετος πηγαίος κώδικας C++ θα αντιγραφεί κατά λέξη στο αντίστοιχο αρχείο .h ή .cc.
A .hg file will typically include some headers and then declare a class, using some macros to add API or behaviour to this class. For instance, gtkmm's button.hg looks roughly like this:
#include <gtkmm/bin.h> #include <gtkmm/activatable.h> _DEFS(gtkmm,gtk) _PINCLUDE(gtkmm/private/bin_p.h) namespace Gtk { class Button : public Bin, public Activatable { _CLASS_GTKOBJECT(Button,GtkButton,GTK_BUTTON,Gtk::Bin,GtkBin) _IMPLEMENTS_INTERFACE(Activatable) public: _CTOR_DEFAULT explicit Button(const Glib::ustring& label, bool mnemonic = false); _WRAP_METHOD(void set_label(const Glib::ustring& label), gtk_button_set_label) ... _WRAP_SIGNAL(void clicked(), "clicked") ... _WRAP_PROPERTY("label", Glib::ustring) }; } // namespace Gtk
The macros in this example do the following:
- _DEFS()
Specifies the destination directory for generated sources, and the name of the main .defs file that gmmproc should parse.
- _PINCLUDE()
Tells gmmproc to include a header in the generated private/button_p.h file.
- _CLASS_GTKOBJECT()
Tells gmmproc to add some typedefs, constructors, and standard methods to this class, as appropriate when wrapping a widget.
- _IMPLEMENTS_INTERFACE()
Tells gmmproc to add initialization code for the interface.
- _CTOR_DEFAULT
Add a default constructor.
- _WRAP_METHOD(), _WRAP_SIGNAL(), and _WRAP_PROPERTY()
Add methods to wrap parts of the C API.
The .h and .cc files will be generated from the .hg and .ccg files by processing them with gmmproc like so, though this happens automatically when using the above build structure:
$ cd gtk/src $ /usr/lib/glibmm-2.4/proc/gmmproc -I ../../tools/m4 --defs . button . ./../gtkmm
Σημειώστε ότι παρείχαμε την gmmproc με τη διαδρομή στα αρχεία μετατροπής .m4, τη διαδρομή στο αρχείο .defs, το όνομα ενός αρχείου .hg, τον πηγαίο κατάλογο και τον κατάλογο προορισμού.
Θα πρέπει να αποφύγετε να συμπεριλάβετε την κεφαλίδα C της κεφαλίδας σας C++, για να αποφύγετε τη μόλυνση του καθολικού χώρου ονόματος και την εξαγωγή περιττών δημόσιων API. Αλλά θα χρειαστείτε να συμπεριλάβετε τις απαραίτητες κεφαλίδες C από το αρχείο σας .ccg.
Οι μακροεντολές εξηγούνται πιο λεπτομερώς στις παρακάτω ενότητες.
- G.3.1. Μετατροπές m4
- G.3.2. Αρχικοποιήσεις m4
- G.3.3. Μακροεντολές κλάσης
- G.3.4. Μακροεντολές κατασκευαστή
- G.3.5. Μακροεντολές μεθόδου
- G.3.6. Άλλες μακροεντολές
- G.3.7. Επεξεργασία παραμέτρου gmmproc
- G.3.8. Βασικοί τύποι
G.3.1. Μετατροπές m4
The macros that you use in the .hg and .ccg files often need to know how to convert a C++ type to a C type, or vice-versa. gmmproc takes this information from an .m4 file in your tools/m4/ directory. This allows it to call a C function in the implementation of your C++ method, passing the appropriate parameters to that C functon. For instance, this tells gmmproc how to convert a GtkTreeView pointer to a Gtk::TreeView pointer:
_CONVERSION(`GtkTreeView*',`TreeView*',`Glib::wrap($3)')
Η $3 θα αντικατασταθεί από το όνομα παραμέτρου όταν αυτή η μετατροπή χρησιμοποιείται από την gmmproc.
Some extra macros make this easier and consistent. Look in gtkmm's .m4 files for examples. For instance:
_CONVERSION(`PrintSettings&',`GtkPrintSettings*',__FR2P) _CONVERSION(`const PrintSettings&',`GtkPrintSettings*',__FCR2P) _CONVERSION(`const Glib::RefPtr<Printer>&',`GtkPrinter*',__CONVERT_REFPTR_TO_P($3))
G.3.2. Αρχικοποιήσεις m4
Συχνά με τις μεθόδους συσκευασίας, είναι επιθυμητό να αποθηκεύσετε την επιστροφή της συνάρτησης C σε αυτό που λέγεται μια παράμετρος εξόδου. Σε αυτήν την περίπτωση, η μέθοδος C++ επιστρέφει τον void, αλλά μια παράμετρος εξόδου στην οποία αποθηκεύεται η τιμή της συνάρτησης C συμπεριλαμβάνεται στη λίστα ορισμάτων της μεθόδου C++. Η gmmproc επιτρέπει τέτοια λειτουργικότητα, αλλά οι κατάλληλες μακροεντολές αρχικοποίησης πρέπει να συμπεριληφθούν για να πουν στην gmmproc πώς να αρχικοποιήσετε την παράμετρο C++ από την επιστροφή της συνάρτησης C.
For example, if there was a C function that returned a GtkWidget* and for some reason, instead of having the C++ method also return the widget, it was desirable to have the C++ method place the widget in a specified output parameter, an initialization macro such as the following would be necessary:
_INITIALIZATION(`Gtk::Widget&',`GtkWidget*',`$3 = Glib::wrap($4)')
Η $3 θα αντικατασταθεί από το όνομα παραμέτρου εξόδου της μεθόδου C++ και η $4 θα αντικατασταθεί από την επιστροφή της συνάρτησης C όταν αυτή η αρχικοποίηση χρησιμοποιείται από την gmmproc. Για ευκολία, η $1 θα αντικατασταθεί επίσης από τον τύπο C++ χωρίς το συμπλεκτικό (&) και η $2 θα αντικατασταθεί από τον τύπο C.
G.3.3. Μακροεντολές κλάσης
Η μακροεντολή κλάσης δηλώνει την ίδια την κλάση και τη σχέση της με τον υποκείμενο τύπο C. Δημιουργεί κάποιους εσωτερικούς κατασκευαστές, το μέλος gobject_, ορισμούς τύπους, τα στοιχεία πρόσβασης gobj(), καταχώριση τύπου και τη μέθοδο Glib::wrap() μεταξύ άλλων.
Άλλες μακροεντολές, όπως _WRAP_METHOD() και _WRAP_SIGNAL() μπορούν να χρησιμοποιηθούν μόνο μετά από μια κλήση στη μακροεντολή _CLASS_*.
- G.3.3.1. _CLASS_GOBJECT
- G.3.3.2. _CLASS_GTKOBJECT
- G.3.3.3. _CLASS_BOXEDTYPE
- G.3.3.4. _CLASS_BOXEDTYPE_STATIC
- G.3.3.5. _CLASS_OPAQUE_COPYABLE
- G.3.3.6. _CLASS_OPAQUE_REFCOUNTED
- G.3.3.7. _CLASS_GENERIC
- G.3.3.8. _CLASS_INTERFACE
G.3.3.1. _CLASS_GOBJECT
Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για έναν τύπο που παράγεται από την 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)
G.3.3.2. _CLASS_GTKOBJECT
Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για έναν τύπο του οποίου ο συσκευαστής παράγεται από την 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() ή στη στοίβα ως μεταβλητή μέλους. Αυτό είναι βολικό, αλλά θα πρέπει να χρησιμοποιήσετε αυτό μόνον όταν είσαστε σίγουροι ότι η αληθινή μέτρηση αναφορών δεν χρειάζεται. Το θεωρούμε χρήσιμο για γραφικά συστατικά.
G.3.3.3. _CLASS_BOXEDTYPE
Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για μια δομή μη 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)
G.3.3.4. _CLASS_BOXEDTYPE_STATIC
Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για μια απλή μεταβιβάσιμη δομή όπως GdkRectangle. Είναι παρόμοια με την _CLASS_BOXEDTYPE, αλλά η δομή C δεν παραχωρείται δυναμικά.
_CLASS_BOXEDTYPE_STATIC( C++ class, C class )
For instance, for Gdk::Rectangle:
_CLASS_BOXEDTYPE_STATIC(Rectangle, GdkRectangle)
G.3.3.5. _CLASS_OPAQUE_COPYABLE
Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για μια αδιαφανή δομή που έχει ελεύθερες συναρτήσεις και συναρτήσεις αντιγραφής. Οι νέες και ελεύθερες συναρτήσεις καθώς και οι συναρτήσεις αντιγραφής θα χρησιμοποιηθούν για αρχικοποίηση του προεπιλεγμένου κατασκευαστή, για αντιγραφή κατασκευαστή και καταστροφέα.
_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)
G.3.3.6. _CLASS_OPAQUE_REFCOUNTED
Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για μια αδιαφανή δομή μετρημένης αναφοράς. Ο συσκευαστής 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)
G.3.3.7. _CLASS_GENERIC
Αυτή η μακροεντολή μπορεί να χρησιμοποιηθεί για να συσκευάσει δομές που δεν προσαρμόζονται σε οποιαδήποτε ειδική κατηγορία.
_CLASS_GENERIC( C++ class, C class )
For instance, for Pango::AttrIter:
_CLASS_GENERIC(AttrIter, PangoAttrIterator)
G.3.3.8. _CLASS_INTERFACE
Αυτή η μακροεντολή δηλώνει έναν συσκευαστή για έναν τύπο που παράγεται από 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)
G.3.4. Μακροεντολές κατασκευαστή
Οι μακροεντολές _CTOR_DEFAULT() και _WRAP_CTOR() προσθέτουν κατασκευαστές συσκευάζοντας τις συγκεκριμένες συναρτήσεις C *_new(). Αυτές οι μακροεντολές θεωρούν ότι το αντικείμενο C έχει ιδιότητες με τα ίδια ονόματα όπως οι παράμετροι συνάρτησης, όπως συνήθως συμβαίνει, έτσι ώστε να μπορεί να παράσχει τις παραμέτρους άμεσα σε μια κλήση g_object_new(). Αυτοί οι κατασκευαστές στην πραγματικότητα δεν καλούν ποτέ τις συναρτήσεις C *_new(), επειδή η gtkmm πρέπει στην πραγματικότητα να αρχικοποιήσει παράγωγους GTypes και οι συναρτήσεις C *_new() νοούνται μόνο ως συναρτήσεις διευκόλυνσης για προγραμματιστές C.
When using _CLASS_GOBJECT(), the constructors should be protected (rather than public) and each constructor should have a corresponding _WRAP_CREATE() in the public section. This prevents the class from being instantiated without using a RefPtr. For instance:
class TextMark : public Glib::Object { _CLASS_GOBJECT(TextMark, GtkTextMark, GTK_TEXT_MARK, Glib::Object, GObject) protected: _WRAP_CTOR(TextMark(const Glib::ustring& name, bool left_gravity = true), gtk_text_mark_new) public: _WRAP_CREATE(const Glib::ustring& name, bool left_gravity = true)
- G.3.4.1. _CTOR_DEFAULT
- G.3.4.2. _WRAP_CTOR
- G.3.4.3. Κατασκευαστές κωδικοποίησης με το χέρι
G.3.4.1. _CTOR_DEFAULT
Αυτή η μακροεντολή δημιουργεί έναν προεπιλεγμένο κατασκευαστή χωρίς ορίσματα.
G.3.4.2. _WRAP_CTOR
Αυτή η μακροεντολή δημιουργεί έναν κατασκευαστή με ορίσματα, ισοδύναμο με μια συνάρτηση C *_new(). Στην πραγματικότητα δεν καλεί τη συνάρτηση *_new(), αλλά θα δημιουργήσει απλά έναν ισοδύναμο κατασκευαστή με τους ίδιους τύπους ορίσματος. Παίρνει μια υπογραφή κατασκευαστή C++ και ένα όνομα συνάρτησης C.
It also takes an optional extra argument:
- errthrow
-
This tells gmmproc that the C *_new() has a final GError** parameter which should be ignored.
G.3.4.3. Κατασκευαστές κωδικοποίησης με το χέρι
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)) {}
G.3.5. Μακροεντολές μεθόδου
- G.3.5.1. _WRAP_METHOD
- G.3.5.2. _WRAP_METHOD_DOCS_ONLY
- G.3.5.3. _IGNORE / _IGNORE_SIGNAL
- G.3.5.4. _WRAP_SIGNAL
- G.3.5.5. _WRAP_PROPERTY
- G.3.5.6. _WRAP_VFUNC
G.3.5.1. _WRAP_METHOD
Αυτή η μακροεντολή παράγει τη μέθοδο 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:
- refreturn
-
Do an extra reference() on the return value, in case the C function does not provide a reference.
- errthrow
-
Use the last GError** parameter of the C function to throw an exception.
- deprecated
-
Puts the generated code in #ifdef blocks. Text about the deprecation can be specified as an optional parameter.
- constversion
-
Just call the non-const version of the same function, instead of generating almost duplicate code.
- ifdef
-
Puts the generated code in #ifdef blocks.
- slot_name
-
Specifies the name of the slot parameter of the method, if it has one. This enables gmmproc to generate code to copy the slot and pass the copy on to the C function in its final gpointer user_data parameter. The slot_callback option must also be used to specify the name of the glue callback function to also pass on to the C function.
- slot_callback
-
Used in conjunction with the slot_name option to specify the name of the glue callback function that handles extracting the slot and then calling it. The address of this callback is also passed on to the C function that the method wraps.
- no_slot_copy
-
Tells gmmproc not to pass a copy of the slot to the C function, if the method has one. Instead the slot itself is passed. The slot parameter name and the glue callback function must have been specified with the slot_name and slot_callbback options respectively.
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:
- Objects used via RefPtr: Pass the RefPtr as a const reference. For instance, const Glib::RefPtr<Gtk::FileFilter>& filter.
- Const Objects used via RefPtr: If the object should not be changed by the function, then make sure that the object is const, even if the RefPtr is already const. For instance, const Glib::RefPtr<const Gtk::FileFilter>& filter.
- Wrapping GList* and GSList* parameters: First, you need to discover what objects are contained in the list's data field for each item, usually by reading the documentation for the C function. The list can then be wrapped by a std::vector type. For instance, std::vector< Glib::RefPtr<Gdk::Pixbuf> >. You may need to define a Traits type to specify how the C and C++ types should be converted.
- Wrapping GList* and
GSList* return types: You must discover whether
the caller should free the list and whether it should release the items
in the list, again by reading the documentation of the C function. With
this information you can choose the ownership (none, shallow or deep)
for the m4 conversion rule, which you should probably put directly into
the .hg file because the ownership depends on the
function rather than the type. For instance:
#m4 _CONVERSION(`GSList*',`std::vector<Widget*>',`Glib::SListHandler<Widget*>::slist_to_vector($3, Glib::OWNERSHIP_SHALLOW)')
G.3.5.2. _WRAP_METHOD_DOCS_ONLY
Αυτή η μακροεντολή είναι παρόμοια με την _WRAP_METHOD(), αλλά δημιουργεί μόνο την τεκμηρίωση για τη μέθοδο C++ που συσκευάζει μια συνάρτηση C. Χρησιμοποιήστε το όταν πρέπει να κωδικοποιήσετε με το χέρι τη μέθοδο, αλλά θέλετε να χρησιμοποιήσετε την τεκμηρίωση που πρέπει να δημιουργηθεί αν η μέθοδος είχε δημιουργηθεί.
_WRAP_METHOD_DOCS_ONLY(C function name)
For instance, from container.hg:
_WRAP_METHOD_DOCS_ONLY(gtk_container_remove)
G.3.5.3. _IGNORE / _IGNORE_SIGNAL
Η gmmproc θα προειδοποιήσει για την τυπική έξοδο σχετικά με τις συναρτήσεις και τα σήματα που έχετε ξεχάσει να συσκευάσετε, βοηθώντας την εξασφάλιση ότι συσκευάζετε την πλήρη API. Αλλά αν δεν θέλετε να συσκευάσετε κάποιες συναρτήσεις ή σήματα, ή αν διαλέξετε κώδικα με το χέρι μερικές μεθόδους, τότε μπορείτε να χρησιμοποιήσετε την μακροεντολή _IGNORE() or _IGNORE_SIGNAL() για να σταματήσετε να παραπονιέται η gmmproc.
_IGNORE(C function name 1, C function name2, etc)
_IGNORE_SIGNAL(C signal name 1, C signal name2, etc)
For instance, from buttonbox.hg:
_IGNORE(gtk_button_box_set_spacing, gtk_button_box_get_spacing)
G.3.5.4. _WRAP_SIGNAL
Αυτή η μακροεντολή παράγει το σήμα τεχνοτροπίας 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:
- no_default_handler
-
Do not generate an on_something() virtual method to allow easy overriding of the default signal handler. Use this when adding a signal with a default signal handler would break the ABI by increasing the size of the class's virtual function table.
- custom_default_handler
-
Generate a declaration of the on_something() virtual method in the .h file, but do not generate a definition in the .cc file. Use this when you must generate the definition by hand.
- custom_c_callback
-
Do not generate a C callback function for the signal. Use this when you must generate the callback function by hand.
- refreturn
-
Do an extra reference() on the return value of the on_something() virtual method, in case the C function does not provide a reference.
- ifdef
-
Puts the generated code in #ifdef blocks.
G.3.5.5. _WRAP_PROPERTY
Αυτή η μακροεντολή δημιουργεί μια μέθοδο 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)
G.3.5.6. _WRAP_VFUNC
Αυτή η μακροεντολή παράγει τη μέθοδο 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)
Η συνάρτηση C (π.χ. get_request_mode) περιγράφεται πληρέστερα στο αρχείο *_vfuncs.defs και τα αρχεία convert*.m4 περιέχουν την απαραίτητη μετατροπή από τον τύπο παραμέτρου C++ στον τύπο παραμέτρου C.
There are some optional extra arguments:
- refreturn
-
Do an extra reference() on the return value of the something_vfunc() function, in case the virtual C function does not provide a reference.
- refreturn_ctype
-
Do an extra reference() on the return value of an overridden something_vfunc() function in the C callback function, in case the calling C function expects it to provide a reference.
- errthrow
-
Use the last GError** parameter of the C virtual function (if there is one) to throw an exception.
- custom_vfunc
-
Do not generate a definition of the vfunc in the .cc file. Use this when you must generate the vfunc by hand.
- custom_vfunc_callback
-
Do not generate a C callback function for the vfunc. Use this when you must generate the callback function by hand.
- ifdef
-
Puts the generated code in #ifdef blocks.
- slot_name
-
Specifies the name of the slot parameter of the method, if it has one. This enables gmmproc to generate code to copy the slot and pass the copy on to the C function in its final gpointer user_data parameter. The slot_callback option must also be used to specify the name of the glue callback function to also pass on to the C function.
- slot_callback
-
Used in conjunction with the slot_name option to specify the name of the glue callback function that handles extracting the slot and then calling it. The address of this callback is also passed on to the C function that the method wraps.
- no_slot_copy
-
Tells gmmproc not to pass a copy of the slot to the C function, if the method has one. Instead the slot itself is passed. The slot parameter name and the glue callback function must have been specified with the slot_name and slot_callbback options respectively.
Ένας κανόνας στον οποίον ενδέχεται να υπάρχουν εξαιρέσεις: Αν η εικονική συνάρτηση C επιστρέφει έναν δείκτη σε ένα αντικείμενο που παράγεται από την GObject, δηλαδή ένα αντικείμενο με μετρημένες αναφορές, τότε η εικονική συνάρτηση C++ θα επιστρέψει ένα αντικείμενο Glib::RefPtr<>. Ένα από τα πρόσθετα ορίσματα refreturn ή refreturn_ctype απαιτείται.
G.3.6. Άλλες μακροεντολές
- G.3.6.1. _IMPLEMENTS_INTERFACE
- G.3.6.2. _WRAP_ENUM
- G.3.6.3. _WRAP_ENUM_DOCS_ONLY
- G.3.6.4. _WRAP_GERROR
- G.3.6.5. _MEMBER_GET / _MEMBER_SET
- G.3.6.6. _MEMBER_GET_PTR / _MEMBER_SET_PTR
- G.3.6.7. _MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT
G.3.6.1. _IMPLEMENTS_INTERFACE
Αυτή η μακροεντολή δημιουργεί έναν κώδικα αρχικοποίησης για τη διεπαφή.
_IMPLEMENTS_INTERFACE(C++ interface name)
For instance, from button.hg:
_IMPLEMENTS_INTERFACE(Activatable)
There is one optional extra argument:
- ifdef
-
Puts the generated code in #ifdef blocks.
G.3.6.2. _WRAP_ENUM
Αυτή η μακροεντολή δημιουργεί μια απαρίθμηση C++ για να συσκευάσει μια απαρίθμηση C. Πρέπει να ορίσετε το επιθυμητό όνομα C++ και το όνομα της υποκείμενης απαρίθμησης C.
For instance, from enums.hg:
_WRAP_ENUM(WindowType, GtkWindowType)
Αν η απαρίθμηση δεν είναι μια GType, πρέπει να περάσετε μια τρίτη παράμετρο NO_GTYPE. Αυτή είναι η περίπτωση όταν δεν υπάρχει συνάρτηση *_get_type() για την απαρίθμηση C, αλλά προσέξτε ότι δεν χρειάζεται μόνο να συμπεριλάβετε μια πρόσθετη κεφαλίδα για αυτήν τη συνάρτηση. Θα πρέπει επίσης να στείλετε ένα σφάλμα στην API C, επειδή όλες οι απαριθμήσεις πρέπει να καταχωριστούν ως GTypes.
For example, from icontheme.hg:
_WRAP_ENUM(IconLookupFlags, GtkIconLookupFlags, NO_GTYPE)
G.3.6.3. _WRAP_ENUM_DOCS_ONLY
Αυτή η μακροεντολή δημιουργεί μια ομάδα τεκμηρίωσης Doxygen για την απαρίθμηση. Αυτό είναι χρήσιμο για απαριθμήσεις που δεν μπορούν να συσκευαστούν με _WRAP_ENUM() επειδή ορίζονται σύνθετα (ίσως χρησιμοποιώντας μακροεντολές C), αλλά η συμπερίληψη της δημιουργούμενης τεκμηρίωσης απαρίθμησης είναι ακόμα επιθυμητή. Χρησιμοποιείται με την ίδια σύνταξη ως _WRAP_ENUM() και επεξεργάζεται επίσης τις ίδιες επιλογές (αν και ο NO_GTYPE αγνοείται απλά επειδή δεν κάνει καμιά διαφορά όταν δημιουργεί μόνο την τεκμηρίωση απαρίθμησης).
G.3.6.4. _WRAP_GERROR
Αυτή η μακροεντολή δημιουργεί μια κλάση εξαίρεσης C++, που παράγεται από Glib::Error, με μια απαρίθμηση κώδικα και μια μέθοδο code(). Πρέπει να ορίσετε το επιθυμητό όνομα C++, το όνομα της αντίστοιχης απαρίθμησης C και το πρόθεμα για τις τιμές απαρίθμησης C.
Αυτή η εξαίρεση μπορεί τότε να δημιουργηθεί από μεθόδους που δημιουργούνται από _WRAP_METHOD() με επιλογή δημιουργία σφάλματος (errthrow).
For instance, from pixbuf.hg:
_WRAP_GERROR(PixbufError, GdkPixbufError, GDK_PIXBUF_ERROR)
G.3.6.5. _MEMBER_GET / _MEMBER_SET
Χρησιμοποιήστε αυτές τις μακροεντολές αν συσκευάζετε μια απλή δομή ή τύπου πλαισίου που παρέχει άμεση πρόσβαση στα μέλη δεδομένων, για να δημιουργήσετε λήπτες και μεταλλάκτες (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)
G.3.6.6. _MEMBER_GET_PTR / _MEMBER_SET_PTR
Χρησιμοποιήστε αυτές τις μακροεντολές για αυτόματη παροχή ληπτών και μεταλλακτών (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.
G.3.6.7. _MEMBER_GET_GOBJECT / _MEMBER_SET_GOBJECT
χρησιμοποιήστε αυτές τις μακροεντολές για να δώσετε λήπτες και μεταλλάκτες (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*)
G.3.7. Επεξεργασία παραμέτρου gmmproc
Η gmmproc επιτρέπει την επεξεργασία παραμέτρων στην υπογραφή μιας μεθόδου για τις μακροεντολές που επεξεργάζονται τις υπογραφές μεθόδων (όπως _WRAP_METHOD(), _WRAP_CTOR() και _WRAP_CREATE()) με ποικιλία τρόπων:
- G.3.7.1. Αναδιάταξη παραμέτρου
- G.3.7.2. Προαιρετική επεξεργασία παραμέτρου
- G.3.7.3. Επεξεργασία παραμέτρου εξόδου
G.3.7.1. Αναδιάταξη παραμέτρου
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)
Παρακαλούμε σημειώστε ότι όταν αναδιατάσσονται παράμετροι για μια υπογραφή μεθόδου _WRAP_SIGNAL(), τα ονόματα παραμέτρου C πρέπει να είναι πάντα p0, p1, κλπ., επειδή το εργαλείο generate_extra_defs χρησιμοποιεί αυτά τα ονόματα παραμέτρων ανεξάρτητα από το ποια μπορεί να είναι τα ονόματα παραμέτρου της API της C. Έτσι είναι γραμμένο προς το παρόν το βοήθημα.
G.3.7.2. Προαιρετική επεξεργασία παραμέτρου
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)
G.3.7.3. Επεξεργασία παραμέτρου εξόδου
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))')
G.3.8. Βασικοί τύποι
Μερικοί από τους βασικούς τύπους που χρησιμοποιούνται στα APIs της C έχουν καλύτερες εναλλακτικές στη C++. Για παράδειγμα, δεν υπάρχει ανάγκη για έναν τύπο gboolean αφού η C++ έχει bool. Ο παρακάτω κατάλογος δείχνει μερικούς κοινά χρησιμοποιούμενους τύπους στις APIs C και σε τι μπορείτε να τους μετατρέψετε σε μια βιβλιοθήκη συσκευαστή C++.
Τύπος C: gboolean
Τύπος C++: bool
Τύπος C: gint
Τύπος C++: int
Τύπος C: guint
Τύπος C++: guint
Τύπος C: gdouble
Τύπος C++: double
Τύπος C: gunichar
Τύπος C++: gunichar
Τύπος C: gchar*
Τύπος C++: Glib::ustring (or std::string for filenames)