"Fossies" - the Fresh Open Source Software Archive

Member "glibmm-2.74.0/docs/internal/using_gmmproc.txt" (19 Sep 2022, 10162 Bytes) of package /linux/misc/glibmm-2.74.0.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 
    2 Command Summary
    3 ==================
    4  #m4               (meta)  one line m4 escape
    5  #m4begin          (meta)  multi line m4 escape
    6  #m4end            (meta)  end of multi line escape
    7  _CTOR_CAST        (class) implement the cast constructor automatically
    8  _CTOR_DEFAULT     (class) implement a constructor taking no arguments
    9  _DTOR             (class) implement the dtor automatically
   10  _MEMBER           (class) implement a member
   11  _POP              (base)  save current section and switch to another
   12  _PINCLUDE         (base)  specify the parents private header name
   13  _PUSH             (base)  restore current section
   14  _SECTION          (base)  change sections
   15  _WRAP             (meta)  wrap various C types
   16  _DEFS             (meta)  load a defs file
   17  _IGNORE           (?)     tells gtkmmproc not to complain this function not wrapped
   18  _CLASS_GOBJECT    (meta)  derive from GObject
   19  _CLASS_GTKOBJECT  (meta)  derive from GtkObject
   20 
   21 
   22 M4 macro escaping <meta>
   23 -----------------
   24 At times it is useful to be able to issue commands directly to
   25 m4 preprocessor underneith gtkmmproc.  However, for safety
   26 the single quote and backtick were hiden.  Thus you must
   27 enter a special environment to be about to issue m4 commands
   28 without interpretation.
   29 
   30 single line m4 statements are any line proceed with a #m4.
   31   #m4 don't eat my `backticks'
   32 
   33 Multiline m4 statements can be done with #m4begin/#m4end
   34 
   35   #m4begin
   36   define(`convert', `dnl
   37   gtkmm_convert($1,$2->obj);
   38   ')
   39   #m4end
   40 
   41 _DEFS (module name, definition filename)
   42 ----------------------------------------
   43 Takes two arguments, a module name (e.g., gtkmm, gnomemm, ...) and the
   44 filename of an API definition file sans ".defs" extension.
   45 
   46 Debugging
   47 ---------
   48 If you see m4 errors, you can set the GTKMMPROC_DEBUG environment variable like so:
   49 # export GTKMMPROC_DEBUG=1
   50 This will ensure that the intermediate m4 files are not deleted, so that you can examine them.
   51 
   52 
   53 _WRAP_METHOD( C++ declaration, C function name )
   54 ------------------------------------------------
   55 
   56 e.g. From entry.hg:
   57 _WRAP_METHOD(void set_text(const string &text),gtk_entry_set_text)
   58 
   59 The C function (e.g. gtk_entry_set_text) is described in gtk/src/gtk.defs,
   60 which is generated automatically by the h2defs.py script from pygtk. (see below)
   61 
   62 There are some optional extra arguments:
   63 refreturn: Do an extra reference() on the return value, in case the C function does not provide a reference.
   64 deprecated: Puts the generated code in #ifdef blocks.
   65 constversion: Just call the non-const version of the same function, instead of generating almost duplicate code.
   66 
   67 _WRAP_METHOD_DOCS_ONLY( C function name )
   68 ------------------------------------------------
   69 
   70 e.g. From treestore.hg:
   71 _WRAP_METHOD_DOCS_ONLY(gtk_list_store_insert)
   72 
   73 Linke _WRAP_METHOD_DOCS_ONLY(), but only outputs the doxygen documentation comments, based on
   74 the gtk_docs.xml and gtk_docs_override.xml files. Use this when you must hand-code the method,
   75 but you want to use the documentation that would be generated if the method was generated.
   76 
   77 _WRAP_SIGNAL( C++ handler declaration, "signal name" )
   78 ------------------------------------------------------
   79 
   80 e.g. From button.hg:
   81 _WRAP_SIGNAL(void clicked(),"clicked")
   82 
   83 Signals are function pointers in the GTK Class struct, with a
   84 corresponding enum value. and a gtk_signal_new.
   85 
   86 from gtkbutton.h:
   87 
   88 struct _GtkButtonClass
   89 {
   90   GtkBinClass        parent_class;
   91  
   92   void (* pressed)  (GtkButton *button);
   93   void (* released) (GtkButton *button);
   94   void (* clicked)  (GtkButton *button);
   95   ...
   96 };
   97 
   98 from gtkbutton.c:
   99 
  100 enum {
  101   PRESSED,
  102   RELEASED,
  103   CLICKED,
  104   ENTER,
  105   LEAVE,
  106   ACTIVATE,
  107   LAST_SIGNAL
  108 };
  109 
  110 and
  111 
  112 button_signals[CLICKED] =
  113     gtk_signal_new ("clicked",
  114                     GTK_RUN_FIRST | GTK_RUN_ACTION,
  115                     GTK_CLASS_TYPE (object_class),
  116                     GTK_SIGNAL_OFFSET (GtkButtonClass, clicked),
  117                     gtk_marshal_VOID__VOID,
  118     GTK_TYPE_NONE, 0);
  119 
  120 
  121 The signals are described in gtk_signals.defs using the define-signal
  122 command. This file was created by the tools/extra_defs_gen utility.
  123 You might need to modify the defs slightly.
  124 
  125 You might find a similarly named method. Just wrap it separately as a
  126 method, and don't worry about the names clashing.
  127 e.g _WRAP_METHOD(void clicked(), gtk_button_clicked)
  128 
  129 
  130 _MEMBER_GET(gtkmm name, gtk+ name, C++ type, C type)
  131 ----------------------------------------------------
  132 
  133 e.g. from window.hg:
  134 _MEMBER_GET(window_type, type, GtkWindowType, GtkWindowType)
  135 
  136 In GTK+, you're sometimes supposed to read from an object data field directly.
  137 This macro creates a get_*() method for use with C++.
  138 
  139 
  140 _MEMBER_SET(gtkmm name, gtk+ name, C++ type, C type)
  141 ----------------------------------------------------
  142 
  143 e.g. from buttonbox.hg:
  144 _MEMBER_SET(child_min_width, child_min_width, int, gint)
  145 
  146 In GTK+, you're sometimes supposed to write to an object data field directly.
  147 This macro creates a set_*() method for use with C++.
  148 
  149 
  150 _MEMBER_GET_PTR(gtkmm name, gtk+ name, C++ pointer type, C pointer type)
  151 ------------------------------------------------------------------------
  152 
  153 e.g. from progress.hg:
  154 _MEMBER_GET_PTR(adjustment, adjustment, Gtk::Adjustment*, GtkAdjustment*)
  155 
  156 Similar to _MEMBER_GET(), but this macro create two access methods:
  157 A non-const method that returns a pointer to a writable object, and
  158 a const method returning a pointer to a read-only object.
  159 
  160 
  161 _MEMBER_GET_GOBJECT(gtkmm name, gtk+ name, C++ type, C pointer type)
  162 --------------------------------------------------------------------
  163 
  164 e.g. from window.hg:
  165 _MEMBER_GET_GOBJECT(frame, frame, Gdk::Window, GdkWindow*)
  166 
  167 Similar to _MEMBER_GET_PTR(), this macro creates two access methods.
  168 The difference is that the return types will actually be
  169 Glib::RefPtr<C++ type> and Glib::RefPtr<const C++ type>.
  170 
  171 Also, the methods call object->reference() before
  172 returning it to the caller.
  173 
  174 
  175 _WRAP_PROPERTY("property name", C++ type)
  176 -----------------------------------------
  177 
  178 e.g. From Widget.hg:
  179 _WRAP_PROPERTY("name", Glib::ustring)
  180 
  181 The properties are described in gtk_signals.defs using the
  182 define-property command. This file was created by the
  183 tools/extra_defs_gen utility. You might need to modify the defs
  184 slightly.
  185 
  186 Properties have enum values in the .c file. e.g from gtkwidget.c:
  187 
  188 enum {
  189   PROP_0,
  190   PROP_NAME,
  191   PROP_PARENT,
  192 ...
  193 
  194 These enums are used in a call to g_object_class_install_property().
  195 e.g. from gtkwidget.c:
  196 
  197   g_object_class_install_property (gobject_class,
  198 				   PROP_NAME,
  199 				   g_param_spec_string ("name",
  200  							_("Widget name"),
  201 							_("The name of the widget"),
  202 							NULL,
  203 							G_PARAM_READWRITE));
  204 
  205 This sometimes shows the type of the property, but sometimes you
  206 need to look for the use of the property enum to see what type
  207 of values are being used with it. For instance, from gtkwidget.c:
  208 
  209 static void
  210 gtk_widget_get_property (GObject         *object,
  211 			 guint            prop_id,
  212 			 GValue          *value,
  213 			 GParamSpec      *pspec)
  214 {
  215   GtkWidget *widget;
  216 
  217   widget = GTK_WIDGET (object);
  218 
  219   switch (prop_id)
  220     {
  221       gint *eventp;
  222       GdkExtensionMode *modep;
  223 
  224     case PROP_NAME:
  225       if (widget->name)
  226 ...
  227 
  228 By looking at GtkWidget::name you can see the type.
  229 
  230 The defs file also shows the types of the properties, but
  231 when the type is an enum, flag, or object, it doesn't show
  232 the exact type.
  233 
  234 
  235 _WRAP_VFUNC( C++ declaration, vfunc C name )
  236 --------------------------------------------
  237 
  238 e.g. From checkbutton.hg:
  239 _WRAP_VFUNC(void draw_indicator(GdkRectangle* area),"draw_indicator")
  240 
  241 These are quite unusual, but you'll probably find one or two. They
  242 are function pointers in the GTK Class struct, which have no
  243 gtk_signal_new().
  244 
  245 For instance, from gtkcheckbutton.h:
  246 
  247 struct _GtkCheckButtonClass
  248 {
  249   GtkToggleButtonClass parent_class;
  250 
  251   void (* draw_indicator) (GtkCheckButton *check_button,
  252    GdkRectangle   *area);
  253 };
  254 
  255 And from gtkcheckbutton.c:
  256 
  257 class->draw_indicator = gtk_real_check_button_draw_indicator;
  258 
  259 The virtual functions are described in gtk_vfuncs.defs using the
  260 define-vfunc command. This file was created manually so you will
  261 need to add a section to it for each new virtual function that you find.
  262 
  263 
  264 _CLASS_GOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )
  265 -----------------------------------------------------------------------------------
  266 
  267 e.g. From accelgroup.hg:
  268 _CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP,Glib::Object,GObject)
  269 
  270 FIXME (2002-09-18 chrisime) text goes here.
  271 
  272 
  273 _CLASS_GTKOBJECT( C++ class, C class, C casting macro, C++ base class, C base class )
  274 -------------------------------------------------------------------------------------
  275 
  276 e.g. From button.hg:
  277 _CLASS_GTKOBJECT(Button,GtkButton,GTK_BUTTON,Gtk::Bin,GtkBin)
  278 
  279 Button is the class which derives from Gtk::Bin in gtkmm.
  280 GtkButton is the class which derives from GtkBin in gtk+.
  281 GTK_BUTTON is the casting macro in gtk+:
  282 
  283 GtkWidget *button;
  284 ... GTK_BUTTON (button);
  285 
  286 
  287 Boxed Types:
  288 ----------------------
  289 
  290 _CLASS_BOXEDTYPE()
  291 For non-GObject structs, registed with g_boxed_type_register_static().
  292 For example, Gdk::Color.
  293 
  294 _CLASS_BOXEDTYPE_STATIC()
  295 For simple assignable structs like GdkRectangle. Similar to _CLASS_BOXEDTYPE,
  296 but the C struct is not allocated dynamically.
  297 
  298 _CLASS_OPAQUE_COPYABLE()
  299 For opaque structs with corresponding copy/free functions.
  300 Very similar to _CLASS_BOXEDTYPE, but without a get_type() method.
  301 
  302 _CLASS_OPAQUE_REFCOUNTED()
  303 For reference-counted opaque structs.  The C++ wrappers can not be
  304 instantiated and can only be used with Glib::RefPtr<>.
  305 
  306 _CLASS_GENERIC()
  307 To wrap structs which don't fit into any specialized category.  Currently,
  308 it is only needed to wrap PangoLayoutIter.
  309 
  310 
  311 Re-generating the gtk_methods.defs interface definition files.
  312 ------------------------------------------------------
  313 
  314 Use h2defs.py from the pygtk module in gnome cvs. e.g.:
  315 
  316 ./h2def.py /gnome/head/cvs/gtk+/gtk/*.h > gtk_methods.defs
  317 
  318 The tools/enums.pl script works in the same way.
  319 
  320 Use your tools/extra_defs_gen utility to generate the .defs for the signals and properties.
  321 
  322 
  323