ruby/krossruby/rubyextension.h

   1 /***************************************************************************
   2  * rubyinterpreter.cpp
   3  * This file is part of the KDE project
   4  * copyright (C)2005,2007 by Cyrille Berger (cberger@cberger.net)
   5  * copyright (C)2006 by Sebastian Sauer (mail@dipe.org)
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  * You should have received a copy of the GNU Library General Public License
  16  * along with this program; see the file COPYING.  If not, write to
  17  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18  * Boston, MA 02110-1301, USA.
  19  ***************************************************************************/
  20
  21 #ifndef KROSS_RUBYRUBYEXTENSION_H
  22 #define KROSS_RUBYRUBYEXTENSION_H
  23
  24 #include "rubyconfig.h"
  25
  26 #include <QStringList>
  27 #include <QVariant>
  28 #include <QObject>
  29
  30 namespace Kross {
  31
  32     class RubyFunction;
  33     class RubyExtensionPrivate;
  34
  35     /**
  36     * This class wraps a QObject into the world of ruby.
  37     *
  38     * @author Cyrille Berger
  39     */
  40     class RubyExtension {
  41             friend class RubyInterpreter;
  42             friend class RubyModule;
  43             friend class RubyScript;
  44             friend class RubyScriptPrivate;
  45         public:
  46
  47             /**
  48             * Constructor.
  49             *
  50             * @param object The QObject instance this extension provides access to.
  51             */
  52             explicit RubyExtension(QObject* object);
  53
  54             /**
  55             * Destructor.
  56             */
  57             ~RubyExtension();
  58
  59             /**
  60             * \return the QObject this \a RubyExtension wraps.
  61             */
  62             QObject* object() const;
  63
  64         private:
  65
  66             /**
  67             * Initialize our extension object.
  68             */
  69             static void init();
  70
  71             /**
  72             * Create and return a new \a RubyFunction instance.
  73             */
  74             RubyFunction* createFunction(QObject* sender, const QByteArray& signal, const VALUE& method);
  75
  76             /**
  77             * Handle the function call.
  78             */
  79             VALUE callMetaMethod(const QByteArray& funcname, int argc, VALUE *argv, VALUE self);
  80
  81             /**
  82             * This function will catch functions that are undefined, extracts
  83             * the matching @a RubyExtension instance and redirects the call
  84             * to @a call_method_missing .
  85             *
  86             */
  87             static VALUE method_missing(int argc, VALUE *argv, VALUE self);
  88
  89             /**
  90             * This function will call a function in a \a RubyExtension object.
  91             *
  92             * @param extension the \a RubyExtension object which contains the function
  93             * @param argc the number of argument
  94             * @param argv the lists of arguments (the first argument is the Ruby ID of the function)
  95             */
  96             static VALUE call_method_missing(RubyExtension* extension, int argc, VALUE *argv, VALUE self);
  97
  98             /**
  99              * This function override the clone function behaviour.
 100              */
 101             static VALUE clone(VALUE self);
 102
 103             /**
 104              * Return a (void*) wraped objects of this.
 105              */
 106             static VALUE toVoidPtr(VALUE self);
 107             /**
 108              * @return a RubyExtension from an void* object
 109              */
 110             static VALUE fromVoidPtr(VALUE self, VALUE obj);
 111
 112             /**
 113              * Find and return a child object of this object.
 114              */
 115             static VALUE callFindChild(int argc, VALUE *argv, VALUE self);
 116
 117             /**
 118              * @return the a list of names of all properties this object provides.
 119              */
 120             static VALUE propertyNames(VALUE self);
 121
 122             /**
 123              * @return the value of a property.
 124              */
 125             static VALUE property(int argc, VALUE *argv, VALUE self);
 126
 127             /**
 128              * Set the value of a property.
 129              */
 130             static VALUE setProperty(int argc, VALUE *argv, VALUE self);
 131
 132             /**
 133              * Connect was called. This does connect a signal with
 134              * a slot or a scripting function.
 135              */
 136             static VALUE callConnect(int argc, VALUE *argv, VALUE self);
 137
 138             /**
 139              * Disconnect was called.
 140              */
 141             static VALUE callDisconnect(int argc, VALUE *argv, VALUE self);
 142
 143 #if 0
 144             /**
 145             * This function handles "each" calls in a \a RubyExtension object to
 146             * provide access to children QObject's the wrapped QObject instance has.
 147             */
 148             static VALUE call_each(int argc, VALUE *argv, VALUE self);
 149 #endif
 150
 151             /**
 152             * This function is called by ruby to delete a RubyExtension object.
 153             */
 154             static void delete_object(void* object);
 155
 156 #if 0
 157             /**
 158             * This function is called by ruby to delete a RubyException object.
 159             */
 160             static void delete_exception(void* object);
 161 #endif
 162
 163         public:
 164
 165             /**
 166             * Test if the ruby object is a \a RubyExtension object.
 167             */
 168             static bool isRubyExtension(VALUE obj);
 169
 170 #if 0
 171             /**
 172             * Test if the ruby object is an exception.
 173             */
 174             static bool isOfExceptionType(VALUE obj);
 175
 176             /**
 177             * Convert a ruby object to the exception type.
 178             * @return 0 if the object wasn't an exception.
 179             */
 180             static Kross::Exception* convertToException(VALUE obj);
 181             /**
 182             * Wrap an exception in a ruby object.
 183             */
 184             static VALUE convertFromException(Kross::Exception::Ptr exc);
 185 #endif
 186
 187             /**
 188             * Converts the VALUE to a \a RubyExtension .
 189             * \param value The VALUE object.
 190             * \return The RubyExtension instance or NULL if cast
 191             * was not possible.
 192             */
 193             static RubyExtension* toExtension(VALUE value);
 194
 195             /**
 196             * Converts a \a RubyExtension to a VALUE.
 197             *
 198             * \param extension The \a RubyExtension object to convert.
 199             * \param owner if true the returned value will take over
 200             * the ownership of the extension. That means, once the
 201             * Ruby gc removes the returned VALUE instance we will
 202             * also delete the extension.
 203             * \return The to a VALUE converted RubyExtension.
 204             */
 205             static VALUE toVALUE(RubyExtension* extension, bool owner);
 206
 207         private:
 208             /// @internal private d-pointer.
 209             RubyExtensionPrivate * const d;
 210             /// @internal unwanted copy-ctor.
 211             RubyExtension(const RubyExtension&);
 212     };
 213
 214 }
 215
 216 #endif