wxPython/SWIG/typemaps.i

   1 //
   2 // SWIG Typemap library
   3 // Dave Beazley
   4 // May 5, 1997
   5 //
   6 // Python implementation
   7 //
   8 // This library provides standard typemaps for modifying SWIG's behavior.
   9 // With enough entries in this file, I hope that very few people actually
  10 // ever need to write a typemap.
  11 //
  12 // Disclaimer : Unless you really understand how typemaps work, this file
  13 // probably isn't going to make much sense.
  14 //
  15 #ifdef AUTODOC
  16 %section "Typemap Library (Python)",info,after,pre,nosort,skip=1,chop_left=3,chop_right=0,chop_top=0,chop_bottom=0
  17 %text %{
  18 %include typemaps.i
  19
  20 The SWIG typemap library provides a language independent mechanism for
  21 supporting output arguments, input values, and other C function
  22 calling mechanisms.  The primary use of the library is to provide a
  23 better interface to certain C function--especially those involving
  24 pointers.
  25 %}
  26
  27 #endif
  28
  29 // ------------------------------------------------------------------------
  30 // Pointer handling
  31 //
  32 // These mappings provide support for input/output arguments and common
  33 // uses for C/C++ pointers.
  34 // ------------------------------------------------------------------------
  35
  36 // INPUT typemaps.
  37 // These remap a C pointer to be an "INPUT" value which is passed by value
  38 // instead of reference.
  39
  40
  41 #ifdef AUTODOC
  42 %subsection "Input Methods"
  43
  44 %text %{
  45 The following methods can be applied to turn a pointer into a simple
  46 "input" value.  That is, instead of passing a pointer to an object,
  47 you would use a real value instead.
  48
  49          int            *INPUT
  50          short          *INPUT
  51          long           *INPUT
  52          unsigned int   *INPUT
  53          unsigned short *INPUT
  54          unsigned long  *INPUT
  55          unsigned char  *INPUT
  56          float          *INPUT
  57          double         *INPUT
  58
  59 To use these, suppose you had a C function like this :
  60
  61         double fadd(double *a, double *b) {
  62                return *a+*b;
  63         }
  64
  65 You could wrap it with SWIG as follows :
  66
  67         %include typemaps.i
  68         double fadd(double *INPUT, double *INPUT);
  69
  70 or you can use the %apply directive :
  71
  72         %include typemaps.i
  73         %apply double *INPUT { double *a, double *b };
  74         double fadd(double *a, double *b);
  75
  76 %}
  77 #endif
  78
  79 %typemap(python,in) double *INPUT(double temp)
  80 {
  81   temp = PyFloat_AsDouble($source);
  82   $target = &temp;
  83 }
  84
  85 %typemap(python,in) float  *INPUT(float temp)
  86 {
  87   temp = (float) PyFloat_AsDouble($source);
  88   $target = &temp;
  89 }
  90
  91 %typemap(python,in) int            *INPUT(int temp)
  92 {
  93   temp = (int) PyInt_AsLong($source);
  94   $target = &temp;
  95 }
  96
  97 %typemap(python,in) short          *INPUT(short temp)
  98 {
  99   temp = (short) PyInt_AsLong($source);
 100   $target = &temp;
 101 }
 102
 103 %typemap(python,in) long           *INPUT(long temp)
 104 {
 105   temp = (long) PyInt_AsLong($source);
 106   $target = &temp;
 107 }
 108 %typemap(python,in) unsigned int   *INPUT(unsigned int temp)
 109 {
 110   temp = (unsigned int) PyInt_AsLong($source);
 111   $target = &temp;
 112 }
 113 %typemap(python,in) unsigned short *INPUT(unsigned short temp)
 114 {
 115   temp = (unsigned short) PyInt_AsLong($source);
 116   $target = &temp;
 117 }
 118 %typemap(python,in) unsigned long  *INPUT(unsigned long temp)
 119 {
 120   temp = (unsigned long) PyInt_AsLong($source);
 121   $target = &temp;
 122 }
 123 %typemap(python,in) unsigned char  *INPUT(unsigned char temp)
 124 {
 125   temp = (unsigned char) PyInt_AsLong($source);
 126   $target = &temp;
 127 }
 128
 129 %typemap(python,in) signed char  *INPUT(signed char temp)
 130 {
 131   temp = (unsigned char) PyInt_AsLong($source);
 132   $target = &temp;
 133 }
 134
 135 // OUTPUT typemaps.   These typemaps are used for parameters that
 136 // are output only.   The output value is appended to the result as
 137 // a list element.
 138
 139 #ifdef AUTODOC
 140 %subsection "Output Methods"
 141
 142 %text %{
 143 The following methods can be applied to turn a pointer into an "output"
 144 value.  When calling a function, no input value would be given for
 145 a parameter, but an output value would be returned.  In the case of
 146 multiple output values, they are returned in the form of a Python tuple.
 147
 148          int            *OUTPUT
 149          short          *OUTPUT
 150          long           *OUTPUT
 151          unsigned int   *OUTPUT
 152          unsigned short *OUTPUT
 153          unsigned long  *OUTPUT
 154          unsigned char  *OUTPUT
 155          float          *OUTPUT
 156          double         *OUTPUT
 157
 158 A Python List can also be returned by using L_OUTPUT instead of OUTPUT.
 159
 160 For example, suppose you were trying to wrap the modf() function in the
 161 C math library which splits x into integral and fractional parts (and
 162 returns the integer part in one of its parameters).K:
 163
 164         double modf(double x, double *ip);
 165
 166 You could wrap it with SWIG as follows :
 167
 168         %include typemaps.i
 169         double modf(double x, double *OUTPUT);
 170
 171 or you can use the %apply directive :
 172
 173         %include typemaps.i
 174         %apply double *OUTPUT { double *ip };
 175         double modf(double x, double *ip);
 176
 177 The Python output of the function would be a tuple containing both
 178 output values.
 179 %}
 180 #endif
 181
 182 // Helper function for List output
 183
 184 %{
 185 static PyObject* l_output_helper(PyObject* target, PyObject* o) {
 186     PyObject*   o2;
 187     if (!target) {
 188         target = o;
 189     } else if (target == Py_None) {
 190         Py_DECREF(Py_None);
 191         target = o;
 192     } else {
 193         if (!PyList_Check(target)) {
 194             o2 = target;
 195             target = PyList_New(0);
 196             PyList_Append(target, o2);
 197             Py_XDECREF(o2);
 198         }
 199         PyList_Append(target,o);
 200         Py_XDECREF(o);
 201     }
 202     return target;
 203 }
 204 %}
 205
 206 // Force the argument to be ignored.
 207
 208 %typemap(python,ignore) int            *L_OUTPUT(int temp),
 209                         short          *L_OUTPUT(short temp),
 210                         long           *L_OUTPUT(long temp),
 211                         unsigned int   *L_OUTPUT(unsigned int temp),
 212                         unsigned short *L_OUTPUT(unsigned short temp),
 213                         unsigned long  *L_OUTPUT(unsigned long temp),
 214                         unsigned char  *L_OUTPUT(unsigned char temp),
 215                         signed char    *L_OUTPUT(signed char temp),
 216                         float          *L_OUTPUT(float temp),
 217                         double         *L_OUTPUT(double temp)
 218 {
 219   $target = &temp;
 220 }
 221
 222 %typemap(python,argout) int            *L_OUTPUT,
 223                         short          *L_OUTPUT,
 224                         long           *L_OUTPUT,
 225                         unsigned int   *L_OUTPUT,
 226                         unsigned short *L_OUTPUT,
 227                         unsigned long  *L_OUTPUT,
 228                         unsigned char  *L_OUTPUT,
 229                         signed char    *L_OUTPUT
 230 {
 231     PyObject *o;
 232     o = PyInt_FromLong((long) (*$source));
 233     l_output_helper($target,o);
 234 }
 235
 236 %typemap(python,argout) float    *L_OUTPUT,
 237                         double   *L_OUTPUT
 238 {
 239     PyObject *o;
 240     o = PyFloat_FromDouble((double) (*$source));
 241     $target = l_output_helper($target,o);
 242 }
 243
 244 // These typemaps contributed by Robin Dunn
 245 //----------------------------------------------------------------------
 246 //
 247 // T_OUTPUT typemap (and helper function) to return multiple argouts as
 248 // a tuple instead of a list.
 249 //
 250 // Author: Robin Dunn
 251 //----------------------------------------------------------------------
 252
 253 %{
 254 static PyObject* t_output_helper(PyObject* target, PyObject* o) {
 255     PyObject*   o2;
 256     PyObject*   o3;
 257
 258     if (!target) {
 259         target = o;
 260     } else if (target == Py_None) {
 261         Py_DECREF(Py_None);
 262         target = o;
 263     } else {
 264         if (!PyTuple_Check(target)) {
 265             o2 = target;
 266             target = PyTuple_New(1);
 267             PyTuple_SetItem(target, 0, o2);
 268         }
 269         o3 = PyTuple_New(1);
 270         PyTuple_SetItem(o3, 0, o);
 271
 272         o2 = target;
 273         target = PySequence_Concat(o2, o3);
 274         Py_DECREF(o2);
 275         Py_DECREF(o3);
 276     }
 277     return target;
 278 }
 279 %}
 280
 281 // Force the argument to be ignored.
 282 %typemap(python,ignore) int            *T_OUTPUT(int temp),
 283                         short          *T_OUTPUT(short temp),
 284                         long           *T_OUTPUT(long temp),
 285                         unsigned int   *T_OUTPUT(unsigned int temp),
 286                         unsigned short *T_OUTPUT(unsigned short temp),
 287                         unsigned long  *T_OUTPUT(unsigned long temp),
 288                         unsigned char  *T_OUTPUT(unsigned char temp),
 289                         float          *T_OUTPUT(float temp),
 290                         double         *T_OUTPUT(double temp)
 291 {
 292   $target = &temp;
 293 }
 294
 295 %typemap(python,argout) int            *T_OUTPUT,
 296                         short          *T_OUTPUT,
 297                         long           *T_OUTPUT,
 298                         unsigned int   *T_OUTPUT,
 299                         unsigned short *T_OUTPUT,
 300                         unsigned long  *T_OUTPUT,
 301                         unsigned char  *T_OUTPUT
 302 {
 303     PyObject *o;
 304     o = PyInt_FromLong((long) (*$source));
 305     $target = t_output_helper($target, o);
 306 }
 307
 308 %typemap(python,argout) float    *T_OUTPUT,
 309                         double   *T_OUTPUT
 310 {
 311     PyObject *o;
 312     o = PyFloat_FromDouble((double) (*$source));
 313     $target = t_output_helper($target, o);
 314 }
 315
 316 // Set the default output typemap
 317
 318 #ifdef OUTPUT_LIST
 319 %typemap(python,ignore) int                *OUTPUT = int   *L_OUTPUT;
 320 %typemap(python,ignore) short              *OUTPUT = short *L_OUTPUT;
 321 %typemap(python,ignore) long               *OUTPUT = long  *L_OUTPUT;
 322 %typemap(python,ignore) unsigned           *OUTPUT = unsigned *L_OUTPUT;
 323 %typemap(python,ignore) unsigned short     *OUTPUT = unsigned short *L_OUTPUT;
 324 %typemap(python,ignore) unsigned long      *OUTPUT = unsigned long  *L_OUTPUT;
 325 %typemap(python,ignore) unsigned char      *OUTPUT = unsigned char  *L_OUTPUT;
 326 %typemap(python,ignore) signed char        *OUTPUT = signed char    *L_OUTPUT;
 327 %typemap(python,ignore) double             *OUTPUT = double         *L_OUTPUT;
 328 %typemap(python,ignore) float              *OUTPUT = float          *L_OUTPUT;
 329
 330 %typemap(python,argout) int                *OUTPUT = int   *L_OUTPUT;
 331 %typemap(python,argout) short              *OUTPUT = short *L_OUTPUT;
 332 %typemap(python,argout) long               *OUTPUT = long  *L_OUTPUT;
 333 %typemap(python,argout) unsigned           *OUTPUT = unsigned *L_OUTPUT;
 334 %typemap(python,argout) unsigned short     *OUTPUT = unsigned short *L_OUTPUT;
 335 %typemap(python,argout) unsigned long      *OUTPUT = unsigned long  *L_OUTPUT;
 336 %typemap(python,argout) unsigned char      *OUTPUT = unsigned char  *L_OUTPUT;
 337 %typemap(python,argout) signed char        *OUTPUT = signed char    *L_OUTPUT;
 338 %typemap(python,argout) double             *OUTPUT = double         *L_OUTPUT;
 339 %typemap(python,argout) float              *OUTPUT = float          *L_OUTPUT;
 340 #else
 341 %typemap(python,ignore) int                *OUTPUT = int   *T_OUTPUT;
 342 %typemap(python,ignore) short              *OUTPUT = short *T_OUTPUT;
 343 %typemap(python,ignore) long               *OUTPUT = long  *T_OUTPUT;
 344 %typemap(python,ignore) unsigned           *OUTPUT = unsigned *T_OUTPUT;
 345 %typemap(python,ignore) unsigned short     *OUTPUT = unsigned short *T_OUTPUT;
 346 %typemap(python,ignore) unsigned long      *OUTPUT = unsigned long  *T_OUTPUT;
 347 %typemap(python,ignore) unsigned char      *OUTPUT = unsigned char  *T_OUTPUT;
 348 %typemap(python,ignore) signed char        *OUTPUT = signed char    *T_OUTPUT;
 349 %typemap(python,ignore) double             *OUTPUT = double         *T_OUTPUT;
 350 %typemap(python,ignore) float              *OUTPUT = float          *T_OUTPUT;
 351
 352 %typemap(python,argout) int                *OUTPUT = int   *T_OUTPUT;
 353 %typemap(python,argout) short              *OUTPUT = short *T_OUTPUT;
 354 %typemap(python,argout) long               *OUTPUT = long  *T_OUTPUT;
 355 %typemap(python,argout) unsigned           *OUTPUT = unsigned *T_OUTPUT;
 356 %typemap(python,argout) unsigned short     *OUTPUT = unsigned short *T_OUTPUT;
 357 %typemap(python,argout) unsigned long      *OUTPUT = unsigned long  *T_OUTPUT;
 358 %typemap(python,argout) unsigned char      *OUTPUT = unsigned char  *T_OUTPUT;
 359 %typemap(python,argout) signed char        *OUTPUT = signed char    *T_OUTPUT;
 360 %typemap(python,argout) double             *OUTPUT = double         *T_OUTPUT;
 361 %typemap(python,argout) float              *OUTPUT = float          *T_OUTPUT;
 362 #endif
 363
 364 // INOUT
 365 // Mappings for an argument that is both an input and output
 366 // parameter
 367
 368
 369 #ifdef AUTODOC
 370 %subsection "Input/Output Methods"
 371
 372 %text %{
 373 The following methods can be applied to make a function parameter both
 374 an input and output value.  This combines the behavior of both the
 375 "INPUT" and "OUTPUT" methods described earlier.  Output values are
 376 returned in the form of a Python tuple.  To return a Python list,
 377 using L_INOUT instead.
 378
 379          int            *INOUT
 380          short          *INOUT
 381          long           *INOUT
 382          unsigned int   *INOUT
 383          unsigned short *INOUT
 384          unsigned long  *INOUT
 385          unsigned char  *INOUT
 386          float          *INOUT
 387          double         *INOUT
 388
 389 For example, suppose you were trying to wrap the following function :
 390
 391         void neg(double *x) {
 392              *x = -(*x);
 393         }
 394
 395 You could wrap it with SWIG as follows :
 396
 397         %include typemaps.i
 398         void neg(double *INOUT);
 399
 400 or you can use the %apply directive :
 401
 402         %include typemaps.i
 403         %apply double *INOUT { double *x };
 404         void neg(double *x);
 405
 406 Unlike C, this mapping does not directly modify the input value (since
 407 this makes no sense in Python).  Rather, the modified input value shows
 408 up as the return value of the function.  Thus, to apply this function
 409 to a Python variable you might do this :
 410
 411        x = neg(x)
 412
 413 Note : previous versions of SWIG used the symbol 'BOTH' to mark
 414 input/output arguments.   This is still supported, but will be slowly
 415 phased out in future releases.
 416 %}
 417
 418 #endif
 419
 420 %typemap(python,in) int *INOUT = int *INPUT;
 421 %typemap(python,in) short *INOUT = short *INPUT;
 422 %typemap(python,in) long *INOUT = long *INPUT;
 423 %typemap(python,in) unsigned *INOUT = unsigned *INPUT;
 424 %typemap(python,in) unsigned short *INOUT = unsigned short *INPUT;
 425 %typemap(python,in) unsigned long *INOUT = unsigned long *INPUT;
 426 %typemap(python,in) unsigned char *INOUT = unsigned char *INPUT;
 427 %typemap(python,in) float *INOUT = float *INPUT;
 428 %typemap(python,in) double *INOUT = double *INPUT;
 429
 430 %typemap(python,argout) int *INOUT = int *OUTPUT;
 431 %typemap(python,argout) short *INOUT = short *OUTPUT;
 432 %typemap(python,argout) long *INOUT = long *OUTPUT;
 433 %typemap(python,argout) unsigned *INOUT = unsigned *OUTPUT;
 434 %typemap(python,argout) unsigned short *INOUT = unsigned short *OUTPUT;
 435 %typemap(python,argout) unsigned long *INOUT = unsigned long *OUTPUT;
 436 %typemap(python,argout) unsigned char *INOUT = unsigned char *OUTPUT;
 437 %typemap(python,argout) float *INOUT = float *OUTPUT;
 438 %typemap(python,argout) double *INOUT = double *OUTPUT;
 439
 440 %typemap(python,in) int *T_INOUT = int *INPUT;
 441 %typemap(python,in) short *T_INOUT = short *INPUT;
 442 %typemap(python,in) long *T_INOUT = long *INPUT;
 443 %typemap(python,in) unsigned *T_INOUT = unsigned *INPUT;
 444 %typemap(python,in) unsigned short *T_INOUT = unsigned short *INPUT;
 445 %typemap(python,in) unsigned long *T_INOUT = unsigned long *INPUT;
 446 %typemap(python,in) unsigned char *T_INOUT = unsigned char *INPUT;
 447 %typemap(python,in) float *T_INOUT = float *INPUT;
 448 %typemap(python,in) double *T_INOUT = double *INPUT;
 449
 450 %typemap(python,argout) int *T_INOUT = int *T_OUTPUT;
 451 %typemap(python,argout) short *T_INOUT = short *T_OUTPUT;
 452 %typemap(python,argout) long *T_INOUT = long *T_OUTPUT;
 453 %typemap(python,argout) unsigned *T_INOUT = unsigned *T_OUTPUT;
 454 %typemap(python,argout) unsigned short *T_INOUT = unsigned short *T_OUTPUT;
 455 %typemap(python,argout) unsigned long *T_INOUT = unsigned long *T_OUTPUT;
 456 %typemap(python,argout) unsigned char *T_INOUT = unsigned char *T_OUTPUT;
 457 %typemap(python,argout) float *T_INOUT = float *T_OUTPUT;
 458 %typemap(python,argout) double *T_INOUT = double *T_OUTPUT;
 459
 460 %typemap(python,in) int *L_INOUT = int *INPUT;
 461 %typemap(python,in) short *L_INOUT = short *INPUT;
 462 %typemap(python,in) long *L_INOUT = long *INPUT;
 463 %typemap(python,in) unsigned *L_INOUT = unsigned *INPUT;
 464 %typemap(python,in) unsigned short *L_INOUT = unsigned short *INPUT;
 465 %typemap(python,in) unsigned long *L_INOUT = unsigned long *INPUT;
 466 %typemap(python,in) unsigned char *L_INOUT = unsigned char *INPUT;
 467 %typemap(python,in) float *L_INOUT = float *INPUT;
 468 %typemap(python,in) double *L_INOUT = double *INPUT;
 469
 470 %typemap(python,argout) int *L_INOUT = int *L_OUTPUT;
 471 %typemap(python,argout) short *L_INOUT = short *L_OUTPUT;
 472 %typemap(python,argout) long *L_INOUT = long *L_OUTPUT;
 473 %typemap(python,argout) unsigned *L_INOUT = unsigned *L_OUTPUT;
 474 %typemap(python,argout) unsigned short *L_INOUT = unsigned short *L_OUTPUT;
 475 %typemap(python,argout) unsigned long *L_INOUT = unsigned long *L_OUTPUT;
 476 %typemap(python,argout) unsigned char *L_INOUT = unsigned char *L_OUTPUT;
 477 %typemap(python,argout) float *L_INOUT = float *L_OUTPUT;
 478 %typemap(python,argout) double *L_INOUT = double *L_OUTPUT;
 479
 480 // Backwards compatibility
 481
 482 %typemap(python,in) int *BOTH = int *INOUT;
 483 %typemap(python,in) short *BOTH = short *INOUT;
 484 %typemap(python,in) long *BOTH = long *INOUT;
 485 %typemap(python,in) unsigned *BOTH = unsigned *INOUT;
 486 %typemap(python,in) unsigned short *BOTH = unsigned short *INOUT;
 487 %typemap(python,in) unsigned long *BOTH = unsigned long *INOUT;
 488 %typemap(python,in) unsigned char *BOTH = unsigned char *INOUT;
 489 %typemap(python,in) float *BOTH = float *INOUT;
 490 %typemap(python,in) double *BOTH = double *INOUT;
 491
 492 %typemap(python,argout) int *BOTH = int *INOUT;
 493 %typemap(python,argout) short *BOTH = short *INOUT;
 494 %typemap(python,argout) long *BOTH = long *INOUT;
 495 %typemap(python,argout) unsigned *BOTH = unsigned *INOUT;
 496 %typemap(python,argout) unsigned short *BOTH = unsigned short *INOUT;
 497 %typemap(python,argout) unsigned long *BOTH = unsigned long *INOUT;
 498 %typemap(python,argout) unsigned char *BOTH = unsigned char *INOUT;
 499 %typemap(python,argout) float *BOTH = float *INOUT;
 500 %typemap(python,argout) double *BOTH = double *INOUT;
 501
 502 %typemap(python,in) int *T_BOTH = int *T_INOUT;
 503 %typemap(python,in) short *T_BOTH = short *T_INOUT;
 504 %typemap(python,in) long *T_BOTH = long *T_INOUT;
 505 %typemap(python,in) unsigned *T_BOTH = unsigned *T_INOUT;
 506 %typemap(python,in) unsigned short *T_BOTH = unsigned short *T_INOUT;
 507 %typemap(python,in) unsigned long *T_BOTH = unsigned long *T_INOUT;
 508 %typemap(python,in) unsigned char *T_BOTH = unsigned char *T_INOUT;
 509 %typemap(python,in) float *T_BOTH = float *T_INOUT;
 510 %typemap(python,in) double *T_BOTH = double *T_INOUT;
 511
 512 %typemap(python,argout) int *T_BOTH = int *T_INOUT;
 513 %typemap(python,argout) short *T_BOTH = short *T_INOUT;
 514 %typemap(python,argout) long *T_BOTH = long *T_INOUT;
 515 %typemap(python,argout) unsigned *T_BOTH = unsigned *T_INOUT;
 516 %typemap(python,argout) unsigned short *T_BOTH = unsigned short *T_INOUT;
 517 %typemap(python,argout) unsigned long *T_BOTH = unsigned long *T_INOUT;
 518 %typemap(python,argout) unsigned char *T_BOTH = unsigned char *T_INOUT;
 519 %typemap(python,argout) float *T_BOTH = float *T_INOUT;
 520 %typemap(python,argout) double *T_BOTH = double *T_INOUT;
 521
 522 // --------------------------------------------------------------------
 523 // Special types
 524 //
 525 // --------------------------------------------------------------------
 526
 527 #ifdef AUTODOC
 528 %subsection "Special Methods"
 529
 530 %text %{
 531 The typemaps.i library also provides the following mappings :
 532
 533 PyObject *
 534
 535       When a PyObject * appears as either an input value or return
 536       value of a function, SWIG passes it through unmodified.  Thus,
 537       if you want to write a C function that operates on PyObjects,
 538       it is easy to write.  For example :
 539
 540            %include typemaps.i
 541            PyObject *spam(PyObject *obj1, int n);
 542
 543       Unlike normal Python wrapper functions, These functions can
 544       use any combination of parameters that you wish.
 545
 546 %}
 547
 548 #endif
 549
 550
 551 // If a PyObject * appears as either an argument or a function return
 552 // value, simply pass it straight through.
 553
 554 %typemap(python,in) PyObject * {
 555   $target = $source;
 556 }
 557
 558 %typemap(python,out) PyObject * {
 559   $target = $source;
 560 }
 561