1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/extensions/activeqt/examples/dotnet/dotnet.doc:1 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Walkthrough: Using Qt objects in Microsoft .NET</title>
<style type="text/css"><!--
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
<a href="index.html">
<font color="#004faf">Home</font></a>
| <a href="classes.html">
<font color="#004faf">All Classes</font></a>
| <a href="mainclasses.html">
<font color="#004faf">Main Classes</font></a>
| <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
| <a href="groups.html">
<font color="#004faf">Grouped Classes</font></a>
| <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Walkthrough: Using Qt objects in Microsoft .NET</h1>
<!-- toc -->
<ul>
<li><a href="#1"> Introduction
</a>
<ul>
<li><a href="#1-1"> Qt vs .NET
</a>
</ul>
<li><a href="#2"> Walkthrough: .NET interop with MC++ and IJW
</a>
<li><a href="#3"> Walkthrough: .NET/COM Interop with ActiveQt
</a>
<ul>
<li><a href="#3-1"> Starting a Project
</a>
<li><a href="#3-2"> Importing Qt Widgets
</a>
<li><a href="#3-3"> Using Qt Widgets
</a>
<li><a href="#3-4"> Handling Qt Signals
</a>
</ul>
<li><a href="#4"> Summary
</a>
<ul>
<li><a href="#4-1"> Limitations
</a>
<li><a href="#4-2"> Performance Considerations
</a>
</ul>
</ul>
<!-- endtoc -->
<p> <h2> Introduction
</h2>
<a name="1"></a><p> In the following walkthrough we will show how Qt objects can be used
in a .NET environment, and how .NET objects can be used in a Qt
environment.
<p> <h3> Qt vs .NET
</h3>
<a name="1-1"></a><p> Qt is a C++ library and is compiled into traditional, native
binaries that make full use of the performance provided by the
runtime environment.
<p> One of the key concepts of .NET is the idea of "intermediate language
code" - the source code is compiled into a bytecode format, and at
runtime, that bytecode is executed in a virtual machine - the <em>Common Language Runtime</em> (CLR).
<p> Another key concept is that of <em>managed code</em>. This is essentially
intermediate language code written in such a way that the CLR can take
care of the memory management, i.e. the CLR will do automatic garbage
collection, so the application code does not need to explicitly free
the memory for unused objects.
<p> The MS compilers for C# and VB.NET will only produce managed
code. Such programs cannot directly call normal, native functions
or classes. <a href="#footnote1"><sup>(1)</sup></a><a name="footnote-call1"></a>
<p> The MS C++ compiler for .NET on the other hand, can produce both
normal and managed code. To write a C++ class that can be compiled
into managed code, the developer must flag the class as managed using
the <tt>__gc</tt> keyword, and restrict the code to only use the subset of
C++ known as "Managed Extensions for C++", or MC++ for short. The
advantage is that MC++ code can freely call and use normal C++
functions and classes. And it also works the other way around: normal
C++ code can call managed functions and use managed classes (e.g. the
entire .NET framework class library), including managed functions and
classes implemented in C# or VB.NET. This feature of mixing managed
and normal C++ code immensely eases the interoperability with .NET,
and is by Microsoft referred to as the "It Just Works" (IJW) feature.
<p> This document demonstrates two different ways of integrating normal
C++ code (that uses Qt) with managed .NET code. First, the manual way
is presented, which includes using a thin MC++ wrapper class around
the normal Qt/C++ class. Then, the automated way is presented, which
utilizes the <a href="activeqt.html#ActiveQt">ActiveQt</a> framework as a generic bridge. The advantage of
the first method is that it gives the application developer full
control, while the second method requires less coding and relieves the
developer of dealing with the conversion between managed and normal
data objects.
<p> The impatient reader, who right away wants to see a <a href="qpushbutton.html">QPushButton</a> and a
custom Qt widget (<a href="qaxserver-example-multiple.html">QAxWidget2</a>) run in a .NET GUI application is referred to the example
directory of ActiveQt. It contains the result of this walkthrough
using both C# and VB.NET, created with Visual Studio.NET (not 2003).
Load <tt>examples/dotnet/walkthrough/csharp.csproj</tt>,
<tt>examples/dotnet/walkthrough/vb.vbproj</tt>
<a href="#footnote2"><sup>(2)</sup></a><a name="footnote-call2"></a>
or <tt>examples/dotnet/wrapper/wrapper.sln</tt> into the IDE and run
the solution.
<p> <h2> Walkthrough: .NET interop with MC++ and IJW
</h2>
<a name="2"></a><p> Normal C++ classes and functions can be used from managed .NET code by
providing thin wrapper classes written in MC++. The wrapper class will
take care of forwarding the calls to the normal C++ functions or
methods, and converting parameter data as necessary. Since the wrapper
class is a managed class, it can be used without further ado in any
managed .NET application, whether written in C#, VB.NET, MC++ or other
managed programming language.
<p>
<pre> // native Qt/C++ class
class Worker : public <a href="qobject.html">QObject</a>
{
<a href="metaobjects.html#Q_OBJECT">Q_OBJECT</a>
Q_PROPERTY(QString statusString READ statusString WRITE setStatusString)
public:
Worker();
<a href="qstring.html">QString</a> statusString() const;
public slots:
void setStatusString(const <a href="qstring.html">QString</a> &string);
signals:
void statusStringChanged(const <a href="qstring.html">QString</a> &string);
private:
<a href="qstring.html">QString</a> status;
};
</pre>
<p> The Qt class has nothing unusual for Qt users, and as even the Qt
specialities like <tt>Q_PROPERTY</tt>, <tt>slots</tt> and <tt>signals</tt> are
implemented with straight C++ they don't cause any trouble when
compiling this class with any C++ compiler.
<p>
<pre> class Worker;
// .NET class
public __gc class netWorker
{
public:
netWorker();
~netWorker();
__property String *get_StatusString();
__property void set_StatusString(String *string);
__event void statusStringChanged(String *args);
private:
Worker *workerObject;
};
</pre>
<p> The .NET wrapper class uses keywords that are part of MC++ to indicate
that the class is managed/garbage collected (<tt>__gc</tt>), and that <tt>StatusString</tt> should be accessible as a property in languages that
support this concept (<tt>__property</tt>). We also declare an event
function <tt>statusStringChanged(String*)</tt> (<tt>__event</tt>), the
equivalent of the respective signal in the Qt class.
<p> Before we can start implementing the wrapper class we need a way to
convert Qt's datatypes (and potentionally your own) into .NET
datatypes, e.g. <a href="qstring.html">QString</a> objects need to be converted into objects
of type <tt>String*</tt>.
<p> When operating on managed objects in normal C++ code, a little extra
care must be taken because of the CLR's garbage collection. A normal
pointer variable should not <a href="#footnote3"><sup>(3)</sup></a><a name="footnote-call3"></a> be used to refer to a managed
object. The reason is that the garbage collection can kick in at any
time and move the object to another place on the heap, leaving you
with an invalid pointer.
<p> However, two methods are provided that solves this problem easily. The
first is to use a <em>pinned</em> pointer, i.e. declare the pointer variable
with the <tt>__pin</tt> keyword. This guarantees that the object pointed to
will not be moved by the garbage collector. It is recommended that
this method not be used to keep a references to managed objects for a
long time, since it will decrease the efficiency of the garbage
collector. The second way is to use the <tt>gcroot</tt> smartpointer
template type. This lets you create safe pointers to managed
objects. E.g. a variable of type <tt>gcroot<String></tt> will always point
to the String object, even if it has been moved by the garbage
collector, and it can be used just like a normal pointer.
<p>
<pre> #include <<a href="qstring-h.html">qstring.h</a>>
#using <mscorlib.dll>
#include <vcclr.h>
using namespace System;
String *QStringToString(const <a href="qstring.html">QString</a> &qstring)
{
<a name="x2467"></a> return new String(qstring.<a href="qstring.html#ucs2">ucs2</a>());
}
</pre>
<p> <pre> QString StringToQString(String *string)
{
wchar_t __pin *chars = PtrToStringChars(string);
return QString::fromUcs2(chars);
}
</pre>
<p> The convertor functions can then be used in the wrapper class
implementation to call the functions in the native C++ class.
<p>
<pre> #include "networker.h"
#include "worker.h"
#include "tools.h"
netWorker::netWorker()
{
workerObject = new Worker();
}
</pre>
<p> <pre> netWorker::~netWorker()
{
delete workerObject;
}
</pre>
<p> The constructor and destructor simply create and destroy the Qt
object wrapped using the C++ operators <tt>new</tt> and <tt>delete</tt>.
<p> <pre> String *netWorker::get_StatusString()
{
return QStringToString(workerObject->statusString());
}
</pre>
<p> The netWorker class delegates calls from the .NET code to the native
code. Although the transition between those two worlds implies a small
performance hit for each function call, and for the type conversion,
this should be negligible since we are anyway going to run within the
CLR.
<p> <pre> void netWorker::set_StatusString(String *string)
{
workerObject->setStatusString(StringToQString(string));
__raise statusStringChanged(string);
}
</pre>
<p> The property setter calls the native Qt class before firing the
event using the <tt>__raise</tt> keyword.
<p> This wrapper class can now be used in .NET code, e.g. using C++, C#,
Visual Basic or any other programming language available for .NET.
<p>
<pre> using System;
namespace WrapperApp
{
class App
{
void Run()
{
netWorker worker = new netWorker();
worker.statusStringChanged += new netWorker.__Delegate_statusStringChanged(onStatusStringChanged);
System.Console.Out.WriteLine(worker.StatusString);
System.Console.Out.WriteLine("Working cycle begins...");
worker.StatusString = "Working";
worker.StatusString = "Lunch Break";
worker.StatusString = "Working";
worker.StatusString = "Idle";
System.Console.Out.WriteLine("Working cycle ends...");
}
private void onStatusStringChanged(string str)
{
System.Console.Out.WriteLine(str);
}
[STAThread]
static void Main(string[] args)
{
App app = new App();
app.Run();
}
}
}
</pre>
<p> <h2> Walkthrough: .NET/COM Interop with ActiveQt
</h2>
<a name="3"></a><p> Fortunately .NET provides a generic wrapper for COM objects, the
<em>Runtime Callable Wrapper</em> (RCW). This RCW is a proxy for the
COM object and is generated by the CLR when a .NET Framework client
activates a COM object. This provides a generic way to reuse COM
objects in a .NET Framework project.
<p> Making a <a href="qobject.html">QObject</a> class into a COM object is easily achieved with
ActiveQt and demonstrated in the <a href="qaxserver-examples.html">examples</a>. The walkthrough will use the Qt classes implemented
in those examples, so the first thing to do is to make sure that those
examples have been built correctly, e.g. by opening the <a href="qaxserver-demo-multiple.html">demonstration pages</a> in Internet
Explorer to verify that the controls are functional.
<p> <h3> Starting a Project
</h3>
<a name="3-1"></a><p> Start Visual Studio.NET, and create a new C# project for writing a
Windows application. This will present you with an empty form in
Visual Studio's dialog editor. You should see the toolbox, which
presents you with a number of available controls and objects in
different categories. If you right-click on the toolbox it allows
you to add new tabs. We will add the tab "Qt".
<p> <h3> Importing Qt Widgets
</h3>
<a name="3-2"></a><p> The category only has a pointer tool by default, and we have to add
the Qt objects we want to use in our form. Right-click on the empty
space, and select "Customize". This opens a dialog that has two
tabs, "COM Components" and ".NET Framework Components". We used
ActiveQt to wrap QWidgets into COM objects, so we select the "COM
Components" page, and look for the classes we want to use, e.g.
"QPushButton" and "QAxWidget2".
<p> When we select those widgets and close the dialog the two widgets
will now be available from the toolbox as grey squares with their
name next to it <a href="#footnote4"><sup>(4)</sup></a><a name="footnote-call4"></a> .
<p> <h3> Using Qt Widgets
</h3>
<a name="3-3"></a><p> We can now add an instance of QAxWidget2 and a <a href="qpushbutton.html">QPushButton</a> to
the form. Visual Studio will automatically generate the RCW for the
object servers. The QAxWidget2 instance takes most of the upper
part of the form, with the QPushButton in the lower right corner.
<p> In the property editor of Visual Studio we can modify the properties
of our controls - QPushButton exposes the <a href="qwidget.html">QWidget</a> API and has many
properties, while QAxWidget2 has only the Visual Studio standard
properties in addition to its own property "lineWidth" in the
"Miscellaneous" category. The objects are named "axQPushButton1" and
"axQAxWidget21", and since especially the last name is a bit
confusing we rename the objects to "resetButton" and "circleWidget".
<p> We can also change the Qt properties, e.g. set the "text" property
of the <tt>resetButton</tt> to "Reset", and the "lineWidth" property of the
<tt>circleWidget</tt> to 5. We can also put those objects into the layout
system that Visual Studio's dialog editor provides, e.g. by setting
the anchors of the <tt>circleWidget</tt> to "Left, Top, Right, Bottom", and
the anchors of the <tt>resetButton</tt> to "Bottom, Right".
<p> Now we can compile and start the project, which will open a user
interface with our two Qt widgets. If we can resize the dialog,
the widgets will resize appropriately.
<p> <h3> Handling Qt Signals
</h3>
<a name="3-4"></a><p> We will now implement event handlers for the widgets. Select the
<tt>circleWidget</tt> and select the "Events" page in the property
editor. The widget exposes events because the QAxWidget2 class has
the "StockEvents" attribute set in its class definition. We implement
the event handler <tt>circleClicked</tt> for the <tt>ClickEvent</tt> to increase
the line width by one for every click:
<p>
<pre> private void circleClicked(object sender, System.EventArgs e)
{
this.circleWidget.lineWidth++;
}
</pre>
<p> In general we can implement a default event handler by double
clicking on the widget in the form, but the default events for
our widgets are right now not defined.
<p> We will also implement an event handler for the <tt>clicked</tt> signal
emitted by <a href="qpushbutton.html">QPushButton</a>. Add the event handler <tt>resetLineWidth</tt> to
the <tt>clicked</tt> event, and implement the generated function:
<p> <pre> private void resetLineWidth(object sender, System.EventArgs e)
{
this.circleWidget.lineWidth = 1;
this.resetButton.setFocus();
}
</pre>
<p> We reset the property to 1, and also call the <tt>setFocus()</tt> slot
to simulate the user style on Windows, where a button grabs focus
when you click it (so that you can click it again with the spacebar).
<p> If we now compile and run the project we can click on the circle
widget to increase its line width, and press the reset button to
set the line width back to 1.
<p> <h2> Summary
</h2>
<a name="4"></a><p> Using ActiveQt as a universal interoperability bridge between the
.NET world and the native world of Qt is very easy, and makes it
often unnecessary to implement a lot of handwritten wrapper classes.
Instead, the <a href="qaxfactory.html">QAxFactory</a> implementation in the otherwise completely
cross-platform Qt project provides the glue that .NET needs to to
generate the RCW.
<p> If this is not sufficient we can implement our own wrapper classes
thanks to the C++ extensions provided by Microsoft.
<p> <h3> Limitations
</h3>
<a name="4-1"></a><p> All the limitations when using ActiveQt are implied when using this
technique to interoperate with .NET, e.g. the datatypes we can use
in the APIs can only be those supported by ActiveQt and COM. However,
since this includes subclasses of <a href="qobject.html">QObject</a> and <a href="qwidget.html">QWidget</a> we can wrap
any of our datatypes into a QObject subclass to make its API
available to .NET. This has the positive side effect that the same
API is automatically available in <a href="http://www.trolltech.com/products/qsa">QSA</a>, the cross platform
scripting solution for Qt applications, and to COM clients in general.
<p> When using the "IJW" method, in priciple the only limitation is the
time required to write the wrapper classes and data type conversion
functions.
<p> <h3> Performance Considerations
</h3>
<a name="4-2"></a><p> Every call from CLR bytecode to native code implies a small
performance hit, and necessary type conversions introduce an
additional delay with every layer that exists between the two
frameworks. Consequently every approach to mix .NET and native
code should try to minimize the communication necessary between
the different worlds.
<p> As ActiveQt introduces three layers at once - the RCW, COM and finally
ActiveQt itself - the performance penalty when using the generic
Qt/ActiveQt/COM/RCW/.NET bridge is larger than when using a
hand-crafted IJW-wrapper class. The execution speed however is still
sufficient for connecting to and modifying interactive elements in a
user interface, and as soon as the benefit of using Qt and C++ to
implement and compile performance critical algorithms into native code
kicks in, ActiveQt becomes a valid choice for making even non-visual
parts of your application accessible to .NET.
<p>
<hr>
<ol> <li><a name="footnote1"></a>
The .NET framework provides Platform Invocation
Services - P/Invoke - that enable managed code to call native C (not
C++) functions located in DLLs directly. The resulting application
then becomes partially unmanaged. <a href="#footnote-call1">Back...</a> <li><a name="footnote2"></a>
You will notice that in the generated code the following line is
commented out: <pre>
' VB is case insensitive, but our C++ controls are not.
' Me.resetButton.enabled = True
</pre>
This line is regenerated without comment whenever you change the
dialog, in which case you have to comment it out again to be able
to run the project. This is a bug in the original version of
Visual Studio.NET, and is fixed in the 2003 edition.
<a href="#footnote-call2">Back...</a> <li><a name="footnote3"></a>
Indeed, the compiler will in
many cases disallow it. <a href="#footnote-call3">Back...</a> <li><a name="footnote4"></a>
Icons could be added by modifying the
way the controls register themselves. <a href="#footnote-call4">Back...</a></ol>
</hr><p>See also <a href="qaxserver-examples.html">The QAxServer Examples</a>.
<!-- eof -->
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright © 2007
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt 3.3.8</div>
</table></div></address></body>
</html>
|
