path: root/doc/man/man3/qaxscriptmanager.3qt

'\" t
.TH QAxScriptManager 3qt "2 February 2007" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2007 Trolltech ASA.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QAxScriptManager \- Bridge between application objects and script code
.SH SYNOPSIS
This class is part of the \fBQt ActiveQt Extension\fR.
.PP
\fC#include <qaxscript.h>\fR
.PP
Inherits QObject.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQAxScriptManager\fR ( QObject * parent = 0, const char * name = 0 )"
.br
.ti -1c
.BI "\fB~QAxScriptManager\fR ()"
.br
.ti -1c
.BI "void \fBaddObject\fR ( QAxBase * object )"
.br
.ti -1c
.BI "void \fBaddObject\fR ( QObject * object )"
.br
.ti -1c
.BI "QStringList \fBfunctions\fR ( QAxScript::FunctionFlags flags = QAxScript::FunctionNames ) const"
.br
.ti -1c
.BI "QStringList \fBscriptNames\fR () const"
.br
.ti -1c
.BI "QAxScript * \fBscript\fR ( const QString & name ) const"
.br
.ti -1c
.BI "QAxScript * \fBload\fR ( const QString & code, const QString & name, const QString & language )"
.br
.ti -1c
.BI "QAxScript * \fBload\fR ( const QString & file, const QString & name )"
.br
.ti -1c
.BI "QVariant \fBcall\fR ( const QString & function, const QVariant & var1 = QVariant ( ), const QVariant & var2 = QVariant ( ), const QVariant & var3 = QVariant ( ), const QVariant & var4 = QVariant ( ), const QVariant & var5 = QVariant ( ), const QVariant & var6 = QVariant ( ), const QVariant & var7 = QVariant ( ), const QVariant & var8 = QVariant ( ) )"
.br
.ti -1c
.BI "QVariant \fBcall\fR ( const QString & function, QValueList<QVariant> & arguments )"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBerror\fR ( QAxScript * script, int code, const QString & description, int sourcePosition, const QString & sourceText )"
.br
.in -1c
.SS "Static Public Members"
.in +1c
.ti -1c
.BI "bool \fBregisterEngine\fR ( const QString & name, const QString & extension, const QString & code = QString ( ) )"
.br
.ti -1c
.BI "QString \fBscriptFileFilter\fR ()"
.br
.in -1c
.SH DESCRIPTION
This class is defined in the \fBQt ActiveQt Extension\fR, which can be found in the \fCqt/extensions\fR directory. It is not included in the main Qt API.
.PP
The QAxScriptManager class provides a bridge between application objects and script code.
.PP
The QAxScriptManager acts as a bridge between the COM objects embedded in the Qt application through QAxObject or QAxWidget, and the scripting languages available through the Windows Script technologies, usually JScript and VBScript.
.PP
Create one QAxScriptManager for each separate document in your application, and add the COM objects the scripts need to access using addObject(). Then load() the script sources and invoke the functions using call().
.PP
\fBWarning:\fR This class is not available with the bcc5.5 and MingW compilers.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QAxScriptManager::QAxScriptManager ( QObject * parent = 0, const char * name = 0 )"
Creates a QAxScriptManager object. \fIparent\fR and \fIname\fR are passed on to the QObject constructor.
.PP
It is usual to create one QAxScriptManager for each document in an application.
.SH "QAxScriptManager::~QAxScriptManager ()"
Destroys the objects, releasing all allocated resources.
.SH "void QAxScriptManager::addObject ( QAxBase * object )"
Adds \fIobject\fR to the manager. Scripts handled by this manager can access the object in the code using the object's name property.
.PP
You must add all the necessary objects before loading any scripts.
.SH "void QAxScriptManager::addObject ( QObject * object )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Adds a generic COM wrapper for \fIobject\fR to the manager. \fIobject\fR must be exposed as a COM object using the functionality provided by the QAxServer module.. Applications using this function you must link against the qaxserver library.
.SH "QVariant QAxScriptManager::call ( const QString & function, const QVariant & var1 = QVariant ( ), const QVariant & var2 = QVariant ( ), const QVariant & var3 = QVariant ( ), const QVariant & var4 = QVariant ( ), const QVariant & var5 = QVariant ( ), const QVariant & var6 = QVariant ( ), const QVariant & var7 = QVariant ( ), const QVariant & var8 = QVariant ( ) )"
Calls \fIfunction\fR, passing the parameters \fIvar1\fR, \fIvar1\fR, \fIvar2\fR, \fIvar3\fR, \fIvar4\fR, \fIvar5\fR, \fIvar6\fR, \fIvar7\fR and \fIvar8\fR as arguments and returns the value returned by the function, or an invalid QVariant if the function does not return a value or when the function call failed. The call returns when the script's execution has finished.
.PP
In most script engines the only supported parameter type is "const QVariant&", for example, to call a JavaScript function
.PP
.nf
.br
    function setNumber(number)
.br
    {
.br
        n = number;
.br
    }
.br
.fi
use
.PP
.nf
.br
    QValueList args;
.br
    args << 5;
.br
    script->call("setNumber(const QVariant&)", args);
.br
.fi
As with dynamicCall the parameters can directly be embedded in the function string.
.PP
.nf
.br
    script->call("setNumber(5)");
.br
.fi
However, this is slower.
.PP
Functions provided by script engines that don't support introspection are not available and must be called directly using QAxScript::call() on the respective script object.
.PP
Note that calling this function can be significantely slower than using call() on the respective QAxScript directly.
.SH "QVariant QAxScriptManager::call ( const QString & function, QValueList<QVariant> & arguments )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Calls \fIfunction\fR passing \fIarguments\fR as parameters, and returns the result. Returns when the script's execution has finished.
.SH "void QAxScriptManager::error ( QAxScript * script, int code, const QString & description, int sourcePosition, const QString & sourceText )\fC [signal]\fR"
This signal is emitted when an execution error occured while running \fIscript\fR.
.PP
\fIcode\fR, \fIdescription\fR, \fIsourcePosition\fR and \fIsourceText\fR contain information about the execution error.
.SH "QStringList QAxScriptManager::functions ( QAxScript::FunctionFlags flags = QAxScript::FunctionNames ) const"
Returns a list with all the functions that are available. Functions provided by script engines that don't support introspection are not included in the list. The functions are either provided with full prototypes or only as names, depending on the value of \fIflags\fR.
.SH "QAxScript * QAxScriptManager::load ( const QString & code, const QString & name, const QString & language )"
Loads the script source \fIcode\fR using the script engine for \fIlanguage\fR. The script can later be referred to using its \fIname\fR which should not be empty.
.PP
The function returns a pointer to the script for the given \fIcode\fR if the \fIcode\fR was loaded successfully; otherwise it returns 0.
.PP
If \fIlanguage\fR is empty it will be determined heuristically. If \fIcode\fR contains the string "End Sub" it will be interpreted as VBScript, otherwise as JScript. Additional script engines can be registered using registerEngine().
.PP
You must add all the objects necessary (using addObject()) \fIbefore\fR loading any scripts. If \fIcode\fR declares a function that is already available (no matter in which language) the first function is overloaded and can no longer be called via call(); but it will still be available by calling its script directly.
.PP
See also addObject(), scriptNames(), and functions().
.SH "QAxScript * QAxScriptManager::load ( const QString & file, const QString & name )"
This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
.PP
Loads the source code from the \fIfile\fR. The script can later be referred to using its \fIname\fR which should not be empty.
.PP
The function returns a pointer to the script engine for the code in \fIfile\fR if \fIfile\fR was loaded successfully; otherwise it returns 0.
.PP
The script engine used is determined from the file's extension. By default ".js" files are interpreted as JScript files, and ".vbs" and ".dsm" files are interpreted as VBScript. Additional script engines can be registered using registerEngine().
.SH "bool QAxScriptManager::registerEngine ( const QString & name, const QString & extension, const QString & code = QString ( ) )\fC [static]\fR"
Registers the script engine called \fIname\fR and returns TRUE if the engine was found; otherwise does nothing and returns FALSE.
.PP
The script engine will be used when loading files with the given \fIextension\fR, or when loading source code that contains the string \fIcode\fR.
.SH "QAxScript * QAxScriptManager::script ( const QString & name ) const"
Returns the script called \fIname\fR.
.PP
You can use the returned pointer to call functions directly through QAxScript::call(), to access the script engine directly, or to delete and thus unload the script.
.SH "QString QAxScriptManager::scriptFileFilter ()\fC [static]\fR"
Returns a file filter listing all the supported script languages. This filter string is convenient for use with QFileDialog.
.SH "QStringList QAxScriptManager::scriptNames () const"
Returns a list with the names of all the scripts.

.SH "SEE ALSO"
.BR http://doc.trolltech.com/qaxscriptmanager.html
.BR http://www.trolltech.com/faq/tech.html
.SH COPYRIGHT
Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.
.SH BUGS
If you find a bug in Qt, please report it as described in
.BR http://doc.trolltech.com/bughowto.html .
Good bug reports help us to help you. Thank you.
.P
The definitive Qt documentation is provided in HTML format; it is
located at $QTDIR/doc/html and can be read using Qt Assistant or with
a web browser. This man page is provided as a convenience for those
users who prefer man pages, although this format is not officially
supported by Trolltech. 
.P
If you find errors in this manual page, please report them to
.BR qt-bugs@trolltech.com .
Please include the name of the manual page (qaxscriptmanager.3qt) and the Qt
version (3.3.8).