This repository was archived by the owner on Apr 4, 2025. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 9
Expand file tree
/
Copy pathfaq.html
More file actions
1654 lines (1488 loc) · 106 KB
/
faq.html
File metadata and controls
1654 lines (1488 loc) · 106 KB
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
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<title>FAQ | SWT</title>
<meta name="keywords" content="eclipse,swt" />
<link rel="preconnect stylesheet" href="../eclipse/project.css" />
<script src="../eclipse/project.js"></script>
<script src="project.js"></script>
<style>
/* <![CDATA[*/
/*]]>*/
</style>
</head>
<body>
<div data-generate="generateDefaultBreadcrumb(this)">
<a href="index.html">SWT</a>
<span>FAQ</span>
</div>
<div data-generate="generateDefaults(this)">
</div>
<main>
<div id="midcolumn">
<h1>The SWT FAQ</h1>
<p>If you have questions you believe should go in here, please let us know on
the <a href="http://dev.eclipse.org/mailman/listinfo/platform-dev">Platform developer mailing list</a>
or just open a new bug: https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Platform&component=SWT.</p>
<ul>
<li><a href="#swtpatchtestingdetails">What are the testing details that should be accompanied with an SWT patch submitted for review?</a></li>
<li><a href="#whatpackagesinSWT">What packages make up SWT?</a></li>
<li><a href="#supportJavaBeans">Does SWT support JavaBeans?</a></li>
<li><a href="#guibuilder">Is there a GUI Builder for SWT?</a></li>
<li><a href="#whatisasnippet">What is a snippet and why do I care?</a></li>
<li><a href="#swtsource">Where do I find the SWT source?</a></li>
</ul>
<ul>
<li><a href="#howbuildjar">How do I build an SWT jar for my platform?</a></li>
<li><a href="#howbuildplugin">How do I build the SWT Eclipse plug-in for my platform?</a></li>
<li><a href="#howbuilddll">How do I build the SWT JNI libraries for my platform?</a></li>
<li><a href="#howaddnatives">How do I add a new native to the SWT JNI libraries for my platform?</a></li>
<li><a href="#howaddnativescocoa">How do I add a new native to the SWT JNI libraries for Cocoa?</a></li>
<li><a href="#gtk64">How do I build the 64-bit version of SWT GTK?</a></li>
</ul>
<ul>
<li><a href="#gtkstartup">Which GTK version do I need to run SWT?</a></li>
<li><a href="#gtkversion">Which GTK version is being used by SWT?</a></li>
<li><a href="#cocoa64launch">Why do I get an UnsatisfiedLinkError when launching from the 64-bit Cocoa port?</a></li>
</ul>
<ul>
<li><a href="#winexternalmanifestfile">How to enable external manifest file on Windows?</a></li>
<li><a href="#win10dpiawareness">How to enable 'dpiAwareness' setting on Windows 10?</a></li>
<li><a href="#gtkfontsandcolors">On gtk, how do I change the default fonts and colors of widgets?</a></li>
</ul>
<ul>
<li><a href="#missingjar">Why do I get the error "java.lang.NoClassDefFoundError: org/eclipse/swt/internal/XXX/OS."?</a></li>
<li><a href="#missingdll">Why do I get the error "java.lang.UnsatisfiedLinkError: no swt-win32-3232 in java.library.path."?</a></li>
<li><a href="#konquerorUnzip">Why do I get an error beginning with "...SWTException: Unsupported or unrecognized format" on startup?</a></li>
<li><a href="#useUnzip">Why do I get the error "error while loading shared libraries: ./libXm.so.2: file too short" on startup?</a></li>
<li><a href="#missinglibXm">Why do I get the error "java.lang.UnsatisfiedLinkError: libXm.so.2: cannot open shared object file: No such file or directory."?</a></li>
<li><a href="#reflectionX">Why do I get an error beginning with "org.eclipse.swt.SWTError: Font not valid" on startup?</a></li>
<li><a href="#notenoughheap">Why do I get the error "java.lang.OutOfMemoryError: Java heap space" when I try to create a very large Image?</a></li>
<li><a href="#debugmode">How do I enable debug mode in Eclipse for SWT?</a></li>
<li><a href="#cairoRemoved">Why does Eclipse (4.2 and greater) on GTK crash with a call to org.eclipse.swt.internal.C.memmove originating from some graphics call?</a></li>
</ul>
<ul>
<li><a href="#swinginswt">Can I use Swing or AWT inside Eclipse?</a></li>
<li><a href="#subclassing">Why can't I subclass SWT widgets like Button and Table?</a></li>
<li><a href="#printstacktrace">Why don't SWTError and SWTException override all printStackTrace methods?</a></li>
<li><a href="#printOnX">How do I print using my favorite Unix print program?</a></li>
<li><a href="#installedprinters">How can I tell whether or not there are any printers installed?</a></li>
<li><a href="#noprintimage">How do I print a snapshot of a widget?</a></li>
<li><a href="#smallprint">Why does everything I print seem so small?</a></li>
<li><a href="#printertrim">What does computeTrim mean for a Printer?</a></li>
<li><a href="#autotest">How can I implement user interaction tests?</a></li>
<li><a href="#gtkselectiongone">On gtk, why does my widget's selection disappear when it loses focus?</a></li>
<li><a href="#gtkwidgethidden">On gtk and motif, why are some widgets hidden when they are visible on Windows or the Macintosh?</a></li>
<li><a href="#advancedgraphics">Which platforms have advanced graphics support?</a></li>
</ul>
<ul>
<li><a href="#whatisbrowser">What is the SWT Browser widget?</a></li>
<li><a href="#browserplatforms">Which platforms support the SWT Browser, and which native renderers do they use?</a></li>
<li><a href="#browserspecifydefault">How do I specify the default type of native renderer that is used by the Browser?</a></li>
<li><a href="#browsernativeie">Which Internet Explorer version do Browsers on Windows use?</a></li>
<li><a href="#browserlinux">What do I need to run the SWT Browser inside Eclipse on Linux?</a></li>
<li><a href="#howuseedge">How do I explicitly use Edge as the Browser's underlying renderer?</a></li>
<li><a href="#howuseedgeoptions">What configuration options are avaibale for the Edge renderer?</a></li>
<li><a href="#edgelimitations">What are the limitations of the Edge Browser renderer?</a></li>
<li><a href="#browserscrollbar">How do I hide the Browser's scrollbars?</a></li>
<li><a href="#browserproxy">How do I set a proxy for the Browser to use?</a></li>
</ul>
<ul>
<li><a href="#swtawtosxmore">Why does the SWT_AWT bridge not work for me on OS X, even after updating Java or the OS?</a></li>
<li><a href="#printOnGTK">Why is the Print menu item disabled in Eclipse on GTK (Linux, UNIX)?</a></li>
<li><a href="#uithread">Why do I get the error "org.eclipse.swt.SWTException: Invalid thread access"?</a></li>
<li><a href="#noautolayout">Why do I have to resize my shell to get my changed widgets to lay out again?</a></li>
<li><a href="#nographicslibrary">Why do I get "SWTException: Unable to load graphics library" using GC?</a></li>
<li><a href="#decorationHints">Why doesn't my Shell have the trim decorations that I specified in its constructor?</a></li>
<li><a href="#noevents">Why doesn't a widget send events when I change it programmatically?</a></li>
<li><a href="#relayout">Why doesn't my layout update when I create/dispose/move/resize a control?</a></li>
<li><a href="#scrolledcomposite">How do I programmatically scroll a Composite?</a></li>
<li><a href="#copypastewithKlipper">Why does Copy/Paste sometimes not work on Linux?</a></li>
<li><a href="#jumplist">Can I use the TaskItem's menu without the launcher?</a></li>
<li><a href="#multiplatformjar">How do I produce a single jar file that contains all of the various SWT platform jars?</a></li>
<li><a href="#twistieanimation">How do I enable the fade annimation for expando buttons in Trees (Windows Vista and up) ?</a></li>
</ul>
<ul>
<li><a href="#keyboardshortcuts" name="accessibility">What are the standard keyboard shortcuts on Windows, Mac OS X, Linux?</a></li>
<li><a href="#screenreaders">Can I use a screen reader with Eclipse?</a></li>
<li><a href="#oldScreenReaderNotWorking">Why doesn't my old Windows screen reader work with Eclipse 3.6?</a></li>
<li><a href="#tableheaderswithJAWS">How do I get JAWS to read Table column headers?</a></li>
<li><a href="#moreAccessibilityInfo">Where can I get more info on Accessibility in Eclipse/SWT?</a></li>
</ul>
<p></p>
<hr>
<p></p>
<p>
Archive: Questions that are not relevant for the latest SWT versions but may be useful for older versions.
</p>
<ul>
<li><a href="#gtk32">How do I build the 32-bit version of SWT GTK?</a></li>
<li><a href="#javawebstart">How can I deploy my standalone SWT application with Java Web Start?</a></li>
<li><a href="#xpthemes">How do I make SWT use the Windows XP themes?</a></li>
<li><a href="#browserlinuxrcp">What do I need to run the SWT Browser in a standalone application on Linux or Solaris?</a></li>
<li><a href="#browsersolaris">What do I need to run the SWT Browser inside Eclipse on Solaris?</a></li>
<li><a href="#howusemozilla">How do I explicitly use Mozilla as the Browser's underlying renderer?</a></li>
<li><a href="#howusewebkit">How do I explicitly use WebKit as the Browser's underlying renderer?</a></li>
<li><a href="#browserwebkitgtk">How do I use the WebKit renderer on Linux-GTK?</a></li>
<li><a href="#browserapplets">Can I view Java applets in the SWT Browser?</a></li>
<li><a href="#specifyxulrunner">Can I specify which XULRunner installation gets used?</a></li>
<li><a href="#specifyprofile">Can I specify which Mozilla profile gets used?</a></li>
<li><a href="#howdetectmozilla">How does the Browser detect a native Mozilla browser to use?</a></li>
<li><a href="#printmozillapath">How can I determine which installed Mozilla browser is being used to render Browser content?</a></li>
<li><a href="#mozillaplugins">How can my Mozilla-based Browser find my Mozilla plug-ins?</a></li>
<li><a href="#howusejavaxpcom">How do I use JavaXPCOM with the Browser?</a></li>
<li><a href="#swtawtsolaris">Why does the SWT_AWT bridge not work for me on AIX or Solaris?</a></li>
<li><a href="#printOnGTKHangs">Why does Eclipse 3.3 freeze when I open an editor on GTK 2.10 (Linux, UNIX)?</a></li>
<li><a href="#32eclipsegtk64">Why do I get strange drawing behaviour when running 32 bit Eclipse on a 64 bit GTK platform?</a></li>
<li><a href="#rtlgtk28">Why doesn't SWT.RIGHT_TO_LEFT work on some GTK versions (less than 2.8)?</a></li>
</ul>
<p></p>
<hr>
<p></p>
<dl>
<dt><strong><a name="swtpatchtestingdetails"> Q: What are the testing details that should be accompanied with an SWT patch submitted for review?</a></strong></dt>
<dd>A: Testing details that are needed to be accompanied with an SWT patch submitted for review.<br>
<p>The SWT team is happy to receive patches and understand that providing patches is a challenging task for new contributors.</p>
<p>The following is a list that could be associated with the bugzilla bug report:</p>
<ul>
<li>Results of the test snippet (if any) associated with that specified bug.
<li>Results of the Widget's new behavior(if applicable) should be tested with various SWT examples: ControlExample.java, CustomControlExample.java and BrowserExample.java
<li>For changes done to any specific widget, the widget specific SWT snippets from the list of: <a href="https://www.eclipse.org/swt/snippets/">SWT Snippets</a> should be used for testing.
<li>When adding a new API try to add new JUnit tests as separate gerrit patch(as gerrit validation will only succeed when the new API is in master and an IBuild exists)
<li>For Windows only patch, which all operating systems are covered like Windows7, Windows10 (at times specific version of Win10 if applicable)
<li>For MAC only patch, patch should be tested on latest OS version.
<li>For Linux only patch, which all GTK versions are covered (GTK3, GTK4 or both) and also if applicable what all desktop managers(gnome, wayland etc..) are covered.
<li>For patches across multiple platform, the patch should have been tested on all affected platforms, if possible for the contributor
<li>Also if you expect some behavior change in Eclipse, always launch Eclipse in self-hosted mode to verify the behavior.
</ul>
<p><strong>Note: Patches satisfying all the items on the list will be reviewed with priority.</strong>
</dd>
<dt><strong><a name="whatpackagesinSWT"> Q: What packages make up SWT?</a></strong></dt>
<dd>A: Package names in SWT begin with the prefix <strong>org.eclipse.swt</strong>.<br>
<p>Here is the complete list:</p>
<ul>
<li>org.eclipse.swt
<li>org.eclipse.swt.accessibility
<li>org.eclipse.swt.awt
<li>org.eclipse.swt.browser
<li>org.eclipse.swt.custom
<li>org.eclipse.swt.dnd
<li>org.eclipse.swt.events
<li>org.eclipse.swt.graphics
<li>org.eclipse.swt.internal.* (Not API, do not reference classes in these packages)
<li>org.eclipse.swt.layout
<li>org.eclipse.swt.opengl
<li>org.eclipse.swt.ole.win32 (Windows only)
<li>org.eclipse.swt.printing
<li>org.eclipse.swt.program
<li>org.eclipse.swt.widgets
</ul>
<p>Classes that are not in these packages do not belong to SWT.</p>
</dd>
<dt><strong><a name="supportJavaBeans">Q: Does SWT support JavaBeans?</a></strong></dt>
<dd>A: To the extent that it makes sense, given the constraints of operating system
compatibility, SWT mirrors the beans behavior. An example of this is the use
of standard beans mechanisms for event dispatch (EventListener, EventObject and adapter
classes). Some aspects of the beans paradigm, such as the ability to create beans with
null constructors, run counter to the constraints of the underlying operating systems
that SWT runs on. For example, operating systems do not typically support creating a
widget without specifying its parent.
<p></p>
The essence of the problem is that if you allow a widget to be created with a null
constructor, then you can't actually create the o/s resources at the time the constructor
runs (you would have to wait until later, after the parent has been set). We can not
do this, since we <em>always</em> create the o/s resources in the constructor, and for
performance/efficiency/consistency reasons do not keep slots in the object to hold
whatever state would be required if the object were to be created later.
</dd>
<dt><strong><a name="guibuilder">Q: Is there a GUI Builder for SWT?</a></strong></dt>
<dd>A: SWT itself does not provide a GUI Builder (also known as "GUI Designer", "GUI Editor",
"Visual Builder", "Visual Designer", "Visual Editor", or "Visual Composition Editor").
However, there is an Eclipse project called <a href="http://www.eclipse.org/windowbuilder/">WindowBuilder</a>
which integrates an SWT GUI Designer. There are several other mature 'third-party' products listed at
<a href="http://marketplace.eclipse.org/">http://marketplace.eclipse.org/</a>. Search for "GUI Builder".
</dd>
<dt><strong><a name="whatisasnippet">Q: What is a snippet and why do I care?</a></strong>
</dt>
<dd>A: A snippet is a <em>minimal stand alone</em> program that demonstrates functionality or
lack of functionality.
<p>Why is this important? Posting a snippet to the news group is the
quickest way to get help. Including a snippet in a bug report is the fastest
way to get a bug fixed. Taking the time to construct a snippet helps you understand
the API of the library you are calling and focuses your thinking. For example, the
SWT team uses C and Java snippets internally to prove or disprove problems in the operating system.
Often, something you think is a bug is actually caused by something elsewhere
in your program.
<p>Snippets isolate problems. Code speaks louder than words.
<p>Here is a minimal stand alone SWT program to help you get started:
<pre>public static void main (String [] args) {
Display display = new Display ();
Shell shell = new Shell (display);
shell.open ();
while (!shell.isDisposed ()) {
if (!display.readAndDispatch ()) display.sleep ();
}
display.dispose ();
}</pre>
For a list of sample snippets, see the <a href="snippets">SWT snippets page</a>.
</dd>
<dt><strong><a name="swtsource">Q: Where do I find the SWT source?</a></strong>
<dd>A: SWT's source can be retrieved directly from GIT as described in <a href="/swt/git.php">Using SWT from GIT</a>. It's also included
in eclipse as follows:
<ul>
<li>eclipse 3.4 and newer: <code>plugins/org.eclipse.swt.<em><ws></em>.<em><os></em>.<em><arch></em>.source_<em>X.X.X.<version></em>.jar</code></li>
<li>eclipse 3.3.2 and earlier: directory <code>plugins/org.eclipse.rcp.source.<em><os></em>.<em><ws></em>.<em><arch></em>_<em>X.X.X.<version></em>/src/</code></li>
</ul>
</dd>
<dt><strong><a name="howbuildjar">Q: How do I build an SWT jar for my platform?</a></strong>
</dt>
<dd>A: The SWT jar can be built from the eclipse GIT repository using an Ant task:
<ol>
<li> Retrieve SWT directly from GIT as described in <a href="/swt/git.php">Using SWT from GIT</a>
<li>Load the projects <strong>org.eclipse.swt</strong> and <strong>org.eclipse.swt.</strong><em>WS.OS.ARCH</em> where <em>WS.OS.ARCH</em> are the names of the
windowing system, operating system and architecture of interest, respectively. For example, <strong>org.eclipse.swt.gtk.linux.x86</strong>.
<li>In the project <strong>org.eclipse.swt.</strong><em>WS.OS.ARCH</em>, locate the file <strong>build.xml</strong>. This is an Ant script.
<li>Run Ant on the target <strong>build.jars</strong>. If you are using eclipse as your development environment, you can run
Ant by selecting the file in the Navigator or Packages view, then selecting <strong>Run Ant...</strong> from the context
menu.
<li>The script will create file <strong>swt.jar</strong> in the root directory of the <strong>org.eclipse.swt.</strong><em>WS.OS.ARCH</em>
project. When it has finished running you can Refresh this project to bring this jar into your eclipse workspace.
</ol>
</dd>
<dt><strong><a name="howbuildplugin">Q: How do I build the SWT Eclipse plug-in for my platform?</a></strong>
</dt>
<dd>A: The SWT Eclipse plug-in can be built (excluding the signing of the jar) with the steps below.
<ol>
<li> Retrieve SWT directly from GIT as described in <a href="/swt/git.php">Using SWT from GIT</a>
<li> Load the projects org.eclipse.swt and org.eclipse.swt.WS.OS.ARCH where WS.OS.ARCH are the names of the windowing system, operating system and architecture of interest, respectively. For example, org.eclipse.swt.gtk.linux.x86.
<li>(optional) If you wish to compile SWT in your workspace, in the Navigator view rename the <strong>org.eclipse.swt</strong> project's <strong>.classpath_</strong>WS
file to <strong>.classpath</strong>. This is useful if, for instance, you have a patch to apply to the SWT codebase before building the plug-in.
<li>Invoke the File > Export... menu item, then select the "Plug-in Development" - "Deployable Plug-ins and Fragments" wizard, and press Next.
<li>In the resulting wizard's plug-ins list, select the <strong>org.eclipse.swt.</strong><em>WS.OS.ARCH</em> fragment.
<li>Specify a destination for the output.
<li>On the Options tab set the qualifier to the plug-in's desired qualifier string. This will be something like <strong>v3655</strong> and must match the
qualifier of Eclipse's SWT plug-in that is being replaced.
<li>Press Finish to export the plug-in.
</ol>
<p>
<em>Important note</em>: Once the plug-in has been exported, the intermediate files that were created in order to make the plug-in jar are not deleted.
As a result, subsequent exports of the same plug-in will <em>NOT</em> recompile the workspace contents, and therefore will not contain any changes that have
been made in the interim. For such changes to be included in a re-export of the plug-in, these intermediate files must be deleted in order to force
their recompilation. The easiest way to do this is to select the <strong>org.eclipse.swt.</strong><em>WS.OS.ARCH</em> project, press F5 to refresh it, and
then replace its content with the released content.
</dd>
<dt><strong><a name="howbuilddll">Q: How do I build the SWT JNI libraries for my platform?</a></strong>
</dt>
<dd>A: SWT uses JNI to interact with the native widgets in the
operating system. The SWT JNI libraries must be compiled for the
windowing system, operating system and hardware architecture of
interest. The libraries can be built either from the code in the GIT
repository or from an eclipse SDK download.
<p>In order to build the required libraries and run Eclipse, you
will require a JDK (Java Development Kit) version that is supported
by Eclipse. Check eclipse.org for details.</p>
<p><strong>Building the SWT JNI libraries from the eclipse SDK download:</strong>
<ol>
<li>Download an Eclipse distribution from
<a href="http://www.eclipse.org/downloads/index.php">http://www.eclipse.org/downloads/index.php</a>.
</li>
<li>Unzip the distribution. This will create a directory called <tt>eclipse</tt>.
This directory is subsequently referred to as <em><eclipseRoot></em>.
<li>Copy file <tt><em><eclipseRoot></em>/plugins/org.eclipse.swt.<em><ws></em>.<em><os></em>.<em><arch></em>.source_X.X.X.<em><versionString></em>.zip</tt>
to another directory and unzip it.
<li>Edit the file <strong>build.sh</strong> (or <strong>build.bat</strong> on Windows)
in the current directory. Set the environment variables defined in that file to
match the location of your JRE, etc. Save the file and close it.
<li>Run the <tt>build</tt> command (<strong>sh build.sh</strong> for UNIX and Linux
platforms, <strong>build.bat</strong> for Windows). This will create the appropriate
library file(s) in the current directory. For example, this will create
<tt>swt-XXXX.dll</tt> files on windows, or <tt>libswt-XXXX.so</tt> files on Linux
and Solaris.
</ol>
<p><strong>Building the SWT JNI libraries from the eclipse GIT repository:</strong><br>
<strong>NOTE</strong>: These instructions require you to use Eclipse
<ol>
<li>Follow <a href="/swt/git.php">these instructions</a> to get SWT from GIT.
<li>Compile the project. This will create a folder called bin under the org.eclipse.swt project.
<li>Change directory into <tt>org.eclipse.swt/bin/library</tt>
<li>Edit the file <strong>build.sh</strong> (or <strong>build.bat</strong> on Windows)
in the current directory. Set the environment variables defined in that file to
match the location of your JRE, etc. Save the file and close it.
<li>Run the <tt>build</tt> command (<strong>sh build.sh</strong> for UNIX and Linux
platforms, <strong>build.bat</strong> for Windows). This will create the appropriate
library file(s) in the current directory. For example, this will create
<tt>swt-XXXX.dll</tt> files on windows, or <tt>libswt-XXXX.so</tt> files on Linux
and Solaris.
</ol>
<p><strong>Building the SWT natives on Ubuntu 12.04, 14.04, etc. (without XULRunner support)</strong><br>
<ol>
<li>Install dependencies with:<br>
<tt>$ sudo apt-get install libgnomeui-dev libxtst-dev freeglut3-dev libgtk-3-dev libgtk2.0-dev</tt>
<li>Follow <a href="/swt/git.php">these instructions</a> to get SWT from GIT.
<li>Make sure the org.eclipse.swt project is compiled.
<li>Context menu > Run As > Ant Build...
<li>On Targets tab, select "build_libraries" (14th from end of list).
<li>On Properties tab, add these two properties:
<ul>
<li>to make the build succeed even without a XULRunner installation: targets = install
<li>to enable GTK3 support: machine_gtk3 = localmachine
</ul>
<li>On JRE tab, select Execution Environment JavaSE-1.8.
<li>If the JAVA_HOME environment variable is not yet set, go to Environment tab and set it to the root directory of the JDK.
<li>Run the External Tools launch configuration. From now on, this is the only step you have to do to build natives.
</ol>
</dd>
<dt><strong><a name="howaddnatives">Q: How do I add a new native to the SWT JNI libraries for my platform?</a></strong>
</dt>
<dd>A: For the steps to add new natives to the SWT JNI libraries, see <a href="/swt/jnigen.php">
Generating the SWT JNI Code.</a>
</dd>
<dt><strong><a name="howaddnativescocoa">Q: How do I add a new native to the SWT JNI libraries for Cocoa?</a></strong>
</dt>
<dd>A: For the steps to add new natives to the SWT Cocoa JNI libraries, see <a href="/swt/macgen.php">
Generating the SWT PI Code for Cocoa.</a>
</dd>
<dt><strong><a name="gtk64">Q: How do I build the 64-bit version of SWT GTK?</a></strong></dt>
<dd>A: Follow these steps to extract the 64-bit SWT GTK source code from GIT and produce your own build:
<ol>
<li>Start Eclipse and retrieve the <code>org.eclipse.swt</code>, <code>org.eclipse.swt.gtk.linux.x86_64</code> and
<code>org.eclipse.swt.tools</code> projects from dev.eclipse.org (see
<a href="/swt/git.php">How to use SWT from GIT</a>, use <code>.classpath_gtk</code>
as the <code>.classpath</code> file in the <code>org.eclipse.swt</code> project).
</li>
<li><i>Note this is not needed for builds after 4.3 M3 as the code was changed to 64-bit.</i> Convert SWT's Java from its 32-bit form to 64-bit:</li>
<ul>
<li>To convert the Java code in-place, go to the <code>build.xml</code> ant script in the <code>org.eclipse.swt.gtk.linux.x86_64</code>
project and run its "replace.32.to.64" target. Once this target has completed you must refresh (F5)
the <code>org.eclipse.swt</code> project in order to pick up the changes.</li>
<li>Run the "build_libraries" target in the same <code>build.xml</code> file. Refresh (F5)
the <code>org.eclipse.swt.gtk.linux.x86_64</code> project when this target has completed, to pick up the new libraries.</li>
</ul>
<li>You're done! The <code>org.eclipse.swt.gtk.linux.x86_64</code> project will now contain the 64-bit native libraries, and if you're
interested, the 64-bit source code will now be available in the <code>org.eclipse.swt.gtk.linux.x86_64/src</code> folder.
</ol>
</dd>
<dt><strong><a name="gtkstartup">Q: Which GTK version do I need to run SWT?</a></strong></dt>
<dd>A: SWT requires the following GTK+ versions (or newer) to be installed:
<ul>
<li>Eclipse/SWT 4.16.x: GTK+ 3.20.0 and its dependencies</li>
<li>Eclipse/SWT 4.15.x: GTK+ 3.14.0 and its dependencies</li>
<li>Eclipse/SWT 4.11.x - 4.14.x: GTK+ 3.10.0 and its dependencies</li>
<li>Eclipse/SWT 4.10.x: GTK+ 3.8.0 and its dependencies</li>
<li>Eclipse/SWT 4.7.x - 4.9.x: GTK+ 2.24.0 and its dependencies (for GTK+ 2) OR GTK+ 3.0.0 and its dependencies (for GTK+ 3)</li>
<li>Eclipse/SWT 4.5.x - 4.6.x: GTK+ 2.18.0 and its dependencies (for GTK+ 2) OR GTK+ 3.0.0 and its dependencies (for GTK+ 3)</li>
<li>Eclipse/SWT 4.4.x: GTK+ 2.10.0 and its dependencies (for GTK+ 2) OR GTK+ 3.0.0 and its dependencies (for GTK+ 3)</li>
<li>Eclipse/SWT 4.3.x: GTK+ 2.10.0 and its dependencies</li>
<li>Eclipse/SWT 3.8.x: GTK+ 2.6.0 and its dependencies</li>
<li>Eclipse/SWT 3.6.x - 3.7.x: GTK+ 2.4.1 and its dependencies</li>
<li>Eclipse/SWT 3.0.x - 3.5.x: GTK+ 2.2.1 and its dependencies</li>
<li>Eclipse/SWT 2.1.x: GTK+ 2.0.6 and its dependencies</li>
</ul>
Note that Eclipse/SWT 4.3.x includes early access support for GTK+ 3.x.
<p>
Starting from Eclipse/SWT 4.4.x, Linux builds come with GTK+ 3 support enabled by default.
</p>
<p>
Starting from Eclipse/SWT 4.10.x, Linux builds only come with GTK+ 3 support, GTK+ 2 is no longer supported.
</p>
<p>
You can determine which version(s) of GTK you have installed with <tt>rpm -q gtk2</tt> or <tt>rpm -q gtk3</tt>.
</p>
</dd>
<dt><strong><a name="gtkversion">Q: Which GTK version is being used by SWT?</a></strong></dt>
<dd>A: Since Mars (4.5), SWT sets the <code>org.eclipse.swt.internal.gtk.version</code> system property to the version being used.
To display this value in Eclipse, go to <b>Help > Installation Details > Configuration</b>.<br>
Look for the line: <code>org.eclipse.swt.internal.gtk.version=3.14.12</code>,
where 3.14.12 corresponds to the GTK version currently used by Eclipse.
</dd>
<dt><strong><a name="cocoa64launch">Q: Why do I get an UnsatisfiedLinkError when launching from the 64-bit Cocoa port?</a></strong></dt>
<dd>A: You need to be sure that you are forcing your launch to use a 64-bit VM. Apple ships most of their VMs with 32 and
64-bit binaries. To force the VM to run in 64-bit mode, use the -d64 option as VM argument in your launch configuration.
<p>If you are launching with SWT from GIT in your workspace (see
<a href="/swt/git.php">How to use SWT from GIT</a>, use <code>.classpath_cocoa_x86_64</code> or <code>.classpath_cocoa_aarch64</code>
as the <code>.classpath</code> file in the <code>org.eclipse.swt</code> project and make sure you have the
org.eclipse.swt.cocoa.maxosx.x86_64 or org.eclipse.swt.cocoa.maxosx.aarch64 project in your workspace).
</p>
</dd>
<dt><strong><a name="winexternalmanifestfile">Q: How to enable external manifest file on Windows?</a></strong></dt>
<dd> A: Follow below steps(ref. <a href="https://blogs.msdn.microsoft.com/chrisforster/2007/12/11/a-solution-and-workaround-to-the-change-in-manifest-preference-behaviour-in-windows-2003-sp1-and-windows-vista/">MSDN blog</a>)
on Windows to enable external manifest file:
<br>
<ul>
<li>Open Windows Registry Editor.</li>
<li>Locate and then click the following registry subkey:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SideBySide</li>
<li>On the Edit menu, point to New, and then click DWORD Value.</li>
<li>Type PreferExternalManifest, and then press ENTER.</li>
<li>Right-click PreferExternalManifest, and then click Modify.</li>
<li>In the Edit DWORD Value dialog box, click Decimal under Base.</li>
<li>In the Value data box, type 1, and then click OK.</li>
<li>On the File menu, click Exit to close Registry Editor.</li>
<p>The name of the manifest file must match the name of the executable.
In the case of eclipse, the executable is <tt>javaw.exe</tt> and the manifest file
must have the name <tt>javaw.exe.manifest</tt>. The manifest file must be in the
<tt>jre\bin</tt> folder for the VM you use to launch Eclipse. Note: the
<tt>eclipse.exe</tt> executable does not launch Eclipse; <tt>eclipse.exe</tt>
displays a splash screen and then invokes the Java VM.
</p>
<p>Here is a <a href="javaw.exe.manifest">sample manifest file</a> to download.</p>
</dd>
<dt><strong><a name="win10dpiawareness">Q: How to enable 'dpiAwareness' setting on Windows 10?</a></strong></dt>
<dd> A: In order to enable dpiawareness on Windows10, there must be a manifest file
located in the same place as the executable that launches the application.
<br>Here is a <a href="javaw.exe.manifest">sample manifest file</a> to download, for more details on <a href="https://www.eclipse.org/swt/faq.php#winexternalmanifestfile">how to enable external manifest file on Windows</a>
</dd>
<dt><strong><a name="gtkfontsandcolors">Q: On GTK, how do I change the default fonts and colors of widgets?</a></strong></dt>
<dd>A: GTK uses a file called <tt>.gtkrc</tt> which is located in your home directory.
On some versions of Linux, this file is called <tt>.gtkrc-2.0</tt>.
Here is an example of the content of that file which sets the font and colors for Eclipse:
<pre>
style "eclipse" {
font_name = "Sans 12"
bg[NORMAL] = "#d6d3ce"
bg[ACTIVE] = "#c7c2bc"
bg[INSENSITIVE] = "#828282"
bg[PRELIGHT] = "#3a6ea5"
fg[NORMAL] = "#000000"
fg[ACTIVE] = "#000000"
fg[INSENSITIVE] = "#d4d0c8"
fg[PRELIGHT] = "#ffffff"
}
class "GtkWidget" style "eclipse"
</pre>
<p>To turn off anti-aliasing of fonts you should use the facilities
available in your desktop if possible, such as the Gnome Font
Properties dialog. An alternate approach is to ensure that your
~/fonts.conf or system-wide fonts.conf file contains the following:</p>
<pre>
<match target="font">
<edit name="antialias" mode="assign"><bool>false</bool></edit>
<edit name="hinting" mode="assign"><bool>true</bool></edit>
<edit name="autohint" mode="assign"><bool>false</bool></edit>
</match>
</pre>
</dd>
<dt><strong><a name="missingjar">Q: Why do I get the error "java.lang.NoClassDefFoundError: org/eclipse/swt/internal/XXX/OS."?</a></strong></dt>
<dd>A: On some platforms such as GTK, SWT is broken into multiple jars. Therefore,
you must ensure that all required jars are on the classpath. The required jars are:
<ul>
<li>swt.jar (all platforms)</li>
<li>swt-pi.jar (some platforms like GTK and Carbon)</li>
<li>swt-mozilla.jar (for Browser widget on GTK and Motif)</li>
<li>swt-gtk.jar (on Linux Motif)</li>
</ul>
</dd>
<dt><strong><a name="missingdll">Q: Why do I get the error "java.lang.UnsatisfiedLinkError: no swt-win32-3232 in java.library.path."?</a></strong></dt>
<dd>A: The SWT JNI libraries must be found at runtime. As of Eclipse/SWT 3.3 this will happen
automatically if the platform-specific SWT jar is on the java classpath. For older Eclipse/SWT
versions you need to place the SWT JNI libraries in a place where the Java Virtual Machine will
find them.
<p>The SWT JNI libraries are included in the SWT download.
<p>A Java application can be informed of the location of the libraries in several ways:
<p></p>
<ol>
<li>Set the library path in the VM launch arguments.
<p>In the Launch Configuration Dialog of eclipse select the Arguments
page, and in the VM arguments field enter:
<tt>-Djava.library.path={runtime-library-path}</tt>
Where the runtime-library-path is the absolute path to the directory containing
the native code library (see above).
<p>This solution means that the SWT libraries have to be manually
added to every project that uses SWT.</p>
<p></p>
<li>Set the library location in an environment variable.
<p>For Windows this is done by editing the PATH environment variable to
include the above mentioned runtime-library-path.
<br>in Win 9X this is done by editing the autoexec.bat file,
<br>on NT or 2K the variable is edited through <strong>My Computer</strong> > <strong>Properties</strong> > <strong>Advanced</strong> > <strong>Environment Variables</strong>.
<p>On linux/unix, modify the LD_LIBRARY_PATH environment variable to include the runtime-library-path.
<p></p>
<li>Copy the SWT library to a directory that is already on the Java library path. For example, the jre/bin directory.
<p>The disadvantage of this solution is that every time you upgrade eclipse you have to remember to copy the native code library.</p>
</ol>
<p>Starting with Eclipse 3.1, the SWT plugin that comes with Eclipse, includes the JNI libraries in the SWT jar.
This was done to support OSGi and Eclipse RCP. If you are using the plugin you must extract the libraries
to include them in the path.</p>
</dd>
<dt><strong><a name="konquerorUnzip">Q: Why do I get an error beginning with "...SWTException: Unsupported or unrecognized format" on startup?</a></strong></dt>
<dd>A: There is a bug in the Konqueror decompressor which causes Eclipse to be improperly extracted
if used. To avoid this the Eclipse archive should first be downloaded to your machine and
then extracted using unzip at the command line.
</dd>
<dt><strong><a name="useUnzip">Q: Why do I get the error "error while loading shared libraries: ./libXm.so.2: file too short" on startup?</a></strong>
</dt>
<dd>A: You must use unzip, not jar, to extract your eclipse download. Jar does not extract the libXm.so.2 link file properly.
</dd>
<dt><strong><a name="missinglibXm">Q: Why do I get the error "java.lang.UnsatisfiedLinkError: libXm.so.2: cannot open shared object file: No such file or directory."?</a></strong></dt>
<dd>A: On motif, the SWT library links against the open motif library libXm.so.2. On most platforms, the open motif library is installed
and added to the library path by default. However, on some Linux platforms, either open motif is not installed or is not on the default library
path, or lesstif is installed. Eclipse (and the standalone version of SWT) includes the libXm.so.2 library in the root of the Eclipse install.
<p>You need to either launch Eclipse from the installed directory or modify the LD_LIBRARY_PATH environment variable to
include the location of libXm.so.2. </p>
<p>Note <code>-Djava.library.path</code> is used by the VM to locate libraries for System.loadLibrary calls. However, it does
not update the LD_LIBRARY_PATH and therefore does not help libraries locate other libraries.</p>
</dd>
<dt><strong><a name="reflectionX">Q: Why do I get an error beginning with "org.eclipse.swt.SWTError: Font not valid" on startup?</a></strong></dt>
<dd>A: This error occurs if a recognized font cannot be resolved at startup time. The scenario where
this has been observed to sometimes happen is when accessing a remote machine via Reflection X. This
situation can be made to work by changing some settings in Reflection X. For information about how to
do this see <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=33828#c14">bug 33828</a>.
</dd>
<dt><strong><a name="notenoughheap">Q: Why do I get the error "java.lang.OutOfMemoryError: Java heap space" when I try to create a very large Image?</a></strong></dt>
<dd>A: This error occurs if there is not enough Java heap space to create a very large image, for example:<br>
<pre>new Image(display, 10985, 1102);</pre>
<br>To allocate more heap space for the Java VM, start eclipse with a VM argument that allocates more heap, for example:
<pre>eclipse -vmargs -Xmx400m</pre>
<br>allocates 400 Mb of heap space.
</dd>
<dt><strong><a name="debugmode">Q: How do I enable debug mode in Eclipse for SWT?</a></strong></dt>
<dd>A: Follow these steps:
<ol>
<li>Create a .options file in the same directory as your eclipse executable.</li>
<li>Place the following lines in the .options file:
<br>org.eclipse.ui/debug=true
<br>org.eclipse.ui/debug/swtdebugglobal=true
</li>
<li>Start up eclipse from the command line with the debug flag: ./eclipse -debug</li>
</ol>
<p>All messages from SWT will be printed to the console window.</p>
</dd>
<dt><strong><a name="swinginswt">Q: Can I use Swing or AWT inside Eclipse?</a></strong></dt>
<dd>A: Yes. As of Eclipse 3.2, Swing and AWT can be embedded in SWT on Windows, GTK and OS X.
However it is important to note that a supporting JDK is required on some platforms in order for this
to work. Specifically, GTK require that JDK 1.5 or newer be used.
Additionally, AIX and Solaris users must ensure that AWT is using XToolkit, as described in
<a href="#swtawtsolaris">Why does the SWT_AWT bridge not work for me on AIX or Solaris?</a>
<p>See this <a href="https://github.com/eclipse-platform/eclipse.platform.swt/tree/master/examples/org.eclipse.swt.snippets/src/org/eclipse/swt/snippets/Snippet135.java">snippet</a> for an example of how to use the API.</p>
</dd>
<dt><strong><a name="cairoRemoved">Q: Why does Eclipse (4.2 and greater) on GTK crash with a call to org.eclipse.swt.internal.C.memmove originating from some graphics call?</a></strong></dt>
<dd>A: Eclipse 4.2 (and greater) makes use of functions in cairo that were not present in the 1.0.2 version of cairo that shipped with Eclipse by default. Since all modern Linux distributions that ship GTK will ship a more recent version of the Cairo library, it was decided to stop shipping the library.
<p>If you are running an older Linux distribution that does not include cairo, you will have to install the cairo library (any version greater than 1.2)</p>
</dd>
<dt><strong><a name="subclassing">Q: Why can't I subclass SWT widgets like Button and Table?</a></strong></dt>
<dd>A: You can but it is not recommended. The article <a href="http://eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm">Creating Your Own Widget using SWT</a>
describes the reasons in detail:
<h3>Subclassing Widgets Directly</h3>
<p>In extreme circumstances, you may need to subclass a widget other than
<i>Canvas</i> or <i>Composite</i>. We recommend against doing this unless all
other avenues have been explored and exhausted. Try to wrap the widget first,
before subclassing it. Here is why:
</p>
<ul>
<li>Subclasses may inherit a lot of API that makes no sense, and must be
overridden. In Java, you cannot override a method and change the return
type; therefore you cannot reimplement some methods.</li>
<li>Subclassing is typically not the safest way to extend a class that
you do not own. For a simplified list of the common arguments, see the
article by <strong>Bill Venners</strong> in the Nov '98 issue of <i>Java
World</i> called <i>"Inheritance versus composition: Which one should
you choose?"</i> at: <a href="http://www.javaworld.com/javaworld/jw-11-1998/jw-11-techniques.html">
http://www.javaworld.com/javaworld/jw-11-1998/jw-11-techniques.html</a></li>
<li>Widget subclasses are almost certainly guaranteed to be
platform-specific unless great care is taken to ensure that they work on
all platforms.</li>
<li>Subclassed widgets can be affected by changes in the non-API
implementation of the superclass.</li>
<li>Subclassing may cause bad system-level bugs, and runs the risk of
leaking resources. For example, if a subclass reimplements a method
without making certain that dispose code from the superclass method is
still called, then the new method will leak system resources.</li>
<li>Binary incompatibility across releases becomes possible. If a method
signature or field name changes, or new methods or fields are added,
there may be a name conflict in the widget subclass. Only <i>Canvas</i>
and <i>Composite</i> are guaranteed not to have name conflicts in future
releases.</li>
<li>See any paper by Leonid Mikhajlov on the <i>"Fragile Base Class
Problem"</i>. You can find his paper "A Study of The Fragile Base Class
Problem" at: <a href="http://www.cas.mcmaster.ca/~emil/publications/fragile/">http://www.cas.mcmaster.ca/~emil/publications/fragile/</a></li>
</ul>
<p>Subclassing <i>Canvas</i> or <i>Composite</i> is the best way to
ensure that your widget works on all SWT platforms. The 'is-a' test in
this case tests whether your widget is-a basic or compound widget.
Subclassing anything else requires asking if the new widget <b>is an SWT
native widget of the type being subclassed</b>. For example, a 100% Java
portable <i>PictureLabel</i> is not an SWT native <i>Label</i>.</p>
<p>When subclassing anything other than <i>Composite</i> or
<i>Canvas</i> you must override the method <b>protected void
checkSubclass()</b> to do nothing. Make sure you read the method comment
before overriding it.
</p>
</dd>
<dt><strong><a name="noeventfire">Q: Why are some events like Selection not fired in response to programmatic widget changes?</a></strong></dt>
<dd>
<p>A: See <a href="#noevents">Why doesn't a widget send events when I change it programmatically?</a>.</p>
</dd>
<dt><strong><a name="printstacktrace">Q: Why don't SWTError and SWTException override all printStackTrace methods?</a></strong></dt>
<dd>A: SWTError and SWTException each contain a slot which records the original
exception (if it is known) that caused the SWTError or SWTException to be thrown.
The printStackTrace() method in these classes has been overridden to print the
stacktrace of the original exception as well.
<p>The problem with the other two API methods (i.e. printStackTrace(PrintStream) and
printStackTrace(PrintWriter)) is that the classes mentioned in their arguments
(PrintStream and PrintWriter) are not available in the CLDC class library.
Because we need to maintain compatability with CLDC, we can not override them.</p>
</dd>
<dt><strong><a name="printOnX">Q: How do I print using my favorite Unix print program?</a></strong></dt>
<dd>A: You can use the External Tools support in Eclipse to print files using external programs.
Just create a new Program launch config from the External Tools dialog that launches your
favorite printing utility and you can pass the selected resource as a parameter.
<ol>
<li>Select the file you want to print.</li>
<li><i>Run > External Tools > External Tools...</i></li>
<li>Select "Program" in the Configurations: list.</li>
<li>Click New</li>
<li>Type: Print Selected File<br>
in the Name: field.</li>
<li>Type the full path name of your favorite printing program in the Location: field.
For example: /usr/bin/lpr</li>
<li>Type: ${container_loc}/${resource_name}<br>
in the Arguments: field.</li>
<li>Click Apply</li>
<li>Click Run</li>
</ol>
</dd>
<dt><strong><a name="installedprinters">Q: How can I tell whether or not there are any printers installed?</a></strong></dt>
<dd>A: The method <code>org.eclipse.swt.printing.Printer.getPrinterList()</code> can be used to determine
whether or not there are any printers installed on the system. This method returns an array of
<code>PrinterData</code> objects. If the length of the array is 0, then there are no printers available.
If there are 1 or more elements in the array, then each <code>PrinterData</code> object represents an
installed printer.
</dd>
<dt><strong><a name="noprintimage">Q: How do I print a snapshot of a widget?</a></strong></dt>
<dd>A: To print an image, the image needs to be created on the <em>printer</em>.
A common mistake is to try to print an image that was created on a <em>display</em>.
<p>First take the snapshot into an image that was created on the display,
and then get the imageData and create a new Image just for printing.
Something like this:
<pre> // Take the snapshot into a display Image
Point size = myWidget.getSize();
Image image = new Image(display, size.x, size.y);
GC gc = new GC(myWidget);
gc.copyArea(image, 0, 0);
gc.dispose();
// Get the ImageData and create a new printer Image from it
ImageData imageData = image.getImageData();
Image printImage = new Image(printer, imageData);</pre>
<p>Then print using <em>printImage</em>.
(Remember to dispose both images when you are done with them).
<p>This is true for all graphic objects that you want to use for printing:
Fonts, Colors, and Images. You need to recreate them on the printer before
you can use them for drawing on the printer GC. You might get lucky sometimes,
if the printer happens to have this font or that color, but you won't get lucky
on all platforms and for all printers, and you won't get lucky for images.
So get into the habit of thinking "Did I create this graphics resource
on the same device that I am now trying to draw to?"</p>
</dd>
<dt><strong><a name="smallprint">Q: Why does everything I print seem so small?</a></strong></dt>
<dd>A: When you are printing something from the screen to a printer device, you
need to think about scaling. What is happening is that your figure is being drawn
in something like 72 x 72 dots per inch on the screen, but then you are printing
it to something like a 300 x 300 or 600 x 600 DPI printer. What you have to do is
ask both the screen and the printer what their DPI is, and then figure out what
scale factor you need to use when you draw to the printer GC. The code might look
like this:
<pre>
Point screenDPI = display.getDPI();
Point printerDPI = printer.getDPI();
int scaleFactor = printerDPI.x / screenDPI.x;
</pre>
Please see the ImageAnalyzer example in the org.eclipse.swt.examples project
for an example of printing an image to a printer. Look at method
menuPrint(). Note however that this is a pretty rough example, and it does
not take into account what happens if the image is larger than the page - it
just clips.
<p>Text printing takes some thought also. You need to wrap words, put your page
breaks in the right place, know where your margins are, etc. The SWT
StyledText widget does its own text printing. If you need to see a more
complicated example of printing a document, wrapping, margins, multi-page,
etc., then please look at the inner class Printing in StyledText in
org.eclipse.swt.custom. An instance of this class is created by the
StyledText.print(Printer) API method.
<p>Note also that when printing, any graphics objects that you use to draw,
such as fonts, colors, and images, need to be re-created on the printer
device before you can draw them to the printer GC.
<p>We also recommend that you run your print job in a separate thread and not in
the UI thread, because printing a long document to a slow printer can hang
your entire UI while the printer spools.
<p>Unfortunately, printing is not simply a matter of just passing in the
printer GC instead of the screen GC. Printing has to be designed into your
drawing classes. You don't have scrollbars anymore, so you have to either
cut stuff off and print it on another page, or reorganize it, or scale it
down, or wrap it somehow. Maybe you want to give some control to your users,
and let them specify how many inches something should be, or whatever -
maybe give them a ruler. There is no magic bullet - you
will definitely have to give it some thought.</p>
</dd>
<dt><strong><a name="printertrim">Q: What does computeTrim mean for a Printer?</a></strong></dt>
<dd>A: The "trim" is the area of the page that the printer cannot print on.
Usually, computeTrim is used as follows: <br><code>Rectangle trim = printer.computeTrim(0, 0, 0, 0);</code>
<p>A printer that can print edge-to-edge would have a trim.x and trim.y of 0,0.
The trim.width and trim.height would be the same as the width and height of the physical paper.
</p>
<p>A 600 dot per inch printer that cannot print on the leftmost 0.18 inch of the paper would have a trim.x of -108.
So to print starting at precisely 1" from the left edge, take 600 (i.e. 1") and "add" -108 (i.e. subtract 0.18") to get the starting x position.
Trim positions are negative because they are relative to the 0,0 position of the client area (or 'printable area') of the paper.
</p>
</dd>
<dt><strong><a name="autotest">Q: How can I implement user interaction tests?</a></strong></dt>
<dd>A: The method <code>org.eclipse.swt.widgets.Display.post(Event)</code> can be used to post
mouse and keyboard events into the OS, which emulates the user performing the specified action.
This is the typical approach that is used for implementing JUnit test cases.
<p>There are also stand-alone applications available for automating SWT user interaction tests:
<ul>
<li><a href="http://swtbot.sourceforge.net/index.html">SWTBot</a> (open source)</li>
<li><a href="http://sourceforge.net/projects/abbot/">Abbot for SWT</a> (open source)</li>
<li><a href="https://code.google.com/p/windowtester/">Window Tester</a> (open source)</li>
</ul>
</p>
</dd>
<dt><strong><a name="gtkselectiongone">Q: On gtk, why does my widget's selection disappear when it loses focus?</a></strong></dt>
<dd>A: This effect may be seen if KDE color settings are being
utilized. This can be fixed by unchecking the "Apply KDE colors to
non-KDE apps" option in the KDE colors control panel.
</dd>
<dt><strong><a name="gtkwidgethidden">Q: On gtk and motif, why are some widgets hidden when they are visible on Windows or the Macintosh?</a></strong></dt>
<dd>A: The SWT.CENTER, although undefined for composites, has
the same value as SWT.EMBEDDED which is used to embed widgets from
other widget toolkits into SWT. On some operating systems (GTK, Motif), this
may cause the children of this compostite to be obscured. Do not use
the SWT.CENTER style when creating a composite.
</dd>
<dt><strong><a name="advancedgraphics">Q: Which platforms have advanced graphics support?</a></strong></dt>
<dd>A:
<ul>
<li>SWT for Windows uses GDI+ for advanced graphics, which is installed on Windows XP and newer.
Windows 2000 users can download and install a Microsoft package containing GDI+.</li>
<li>SWT for GTK+ and Motif use Cairo for advanced graphics, which is installed on systems with GTK+ 2.8 or newer
(for example RHEL 5).</li>
<li>SWT for OS X uses Quartz for advanced graphics, which is installed on all supported OS X versions.</li>
</ul>
</dd>
<dt><strong><a name="whatisbrowser">Q: What is the SWT Browser widget?</a></strong></dt>
<dd>A: The SWT Browser widget wraps a native web browser engine and can be used to display HTML documents,
provide browser-like experience or create hybrid web/native applications.
</dd>
<dt><strong><a name="browserplatforms">Q: Which platforms support the SWT Browser, and which native renderers are available?</a></strong></dt>
<dd>A: The SWT Browser is currently available on all supported platforms. Available renderers and corresponding widget style flags are:
<p>
<table>
<tr>
<th>Renderer</th>
<th>Platform</th>
<th>Style Flag</th>
<th>Default</th>
</tr>
<tr>
<td>Internet Explorer</td>
<td>Windows</td>
<td><code>SWT.IE</code></td>
<td>Yes</td>
</tr>
<tr>
<td>WebKit</td>
<td>macOS, Linux GTK</td>
<td><code>SWT.WEBKIT</code></td>
<td>Yes</td>
</tr>
<tr>
<td>Edge (Chromium-based)</td>
<td>Windows</td>
<td><code>SWT.EDGE</code></td>
<td>No</td>
</tr>
</table>
<p>
<em>Note:</em> As of Eclipse/SWT 4.8, Mozilla (XULRunner) renderer is no longer supported, <code>SWT.MOZILLA</code> flag is deprecated and has no effect.
<p>
Browser instances created with style <code>SWT.NONE</code> will use the default platform renderer
according to the table above. Default renderer does not require additional software installation.
It is possible to override the default native renderer, see <a href="#browserspecifydefault">How do I specify the default type of native renderer that is used by the Browser?</a>.
<p>
For additional information on specific renderers see <a href="#howuseedge">How do I explicitly use Edge as the Browser's underlying renderer?</a>.
</dd>
<dt><strong><a name="browserspecifydefault">Q: How do I specify the default type of native renderer that is used by the Browser?</a></strong></dt>
<dd>A: The default native renderers that are used for <code>SWT.NONE</code>-style Browsers are listed in
<a href="#browserplatforms">Which platforms support the SWT Browser, and which native renderers do they use?</a>.
Default is chosen to not require additional software installation and to preserve backward-compativle behavior.
<p>
A user can set a property to specify the type of native renderer to use for <code>SWT.NONE</code>-style Browsers.
Setting this property does not affect Browsers that are created with explicit renderer styles such as <code>SWT.WEBKIT</code>.
The property name is <code>org.eclipse.swt.browser.DefaultType</code> and valid values for it currently include "<code>webkit</code>",
"<code>ie</code>" (since 4.3) and "<code>edge</code>" (since 4.19). This property must be set before the <em>first</em> Browser instance is created.
<p>
<em>Note:</em> As of Eclipse/SWT 4.8, Mozilla (XULRunner) renderer is no longer supported, the value <code>mozilla</code> has no effect.
<p>
A user can specify a comma-separated list of native renderers, in order of preference, for the <code>org.eclipse.swt.browser.DefaultType</code> value.
Valus not applicable to a particular platform are ignored. For example, the value of <code>edge,chromium</code> will change the default
to Edge on Windows and Chromium on other platforms.
<p>
The best opportunity for a user to set this property is by launching their application with a <code>-D</code>
VM switch (eg. add to the end of the eclipse.ini file: <code>-Dorg.eclipse.swt.browser.DefaultType=chromium</code>).
<p>
An alternate approach that an eclipse application may use is to provide a <code>BrowserInitializer</code>
implementation that sets this property. This implementation will be invoked when the first Browser instance
is about to be created. The steps to do this are:
<ul>
<li>Create a fragment with host plug-in <code>org.eclipse.swt</code>.</li>
<li>In this fragment create class <code>org.eclipse.swt.browser.BrowserInitializer</code>.</li>
<li>Implement a static initializer in this class that sets the <code>org.eclipse.swt.browser.DefaultType</code> property.
</ul>
</dd>
<dt><strong><a name="browsernativeie">Q: Which Internet Explorer version do Browsers on Windows use?</a></strong></dt>
<dd>A: All supported Windows versions provide Internet Explorer 11.
<p>
An HTML document can override this behavior by including a <code>X-UA-Compatible</code> meta tag as described in
<a href="http://msdn.microsoft.com/en-us/library/cc288325%28v=vs.85%29.aspx">Defining Document Compatibility</a>.
<p>
Additionally, the Browser's default compatibility mode can be overridden by setting Java property <code>org.eclipse.swt.browser.IEVersion</code> to a value
from <a href="http://msdn.microsoft.com/en-us/library/ee330730%28v=vs.85%29.aspx#browser_emulation">Browser Emulation</a> before the first
Browser instance is created. For example, adding the line <code>-Dorg.eclipse.swt.browser.IEVersion=7000</code> to the end of
eclipse's <code>eclipse.ini</code> file will revert all IE-based Browsers to use IE7 compatibility mode by default.</li>
</dd>
<dt><strong><a name="browserlinux">Q: What do I need to run the SWT Browser inside Eclipse on Linux?</a></strong></dt>
<dd>A: Default Browser renderer for Linux GTK is WebKitGTK+ 2. Generally, it will be installed as part of the GTK-based desktop environment.
<p>
Particular package name depends on the distribution. For example:
<ul>
<li>RHEL, Fedora: webkit2gtk3 or webkitgtk4</li>
<li>Debian, Ubuntu: libwebkit2gtk-4.0-37</li>
<li>SLES, openSUSE: libwebkit2gtk-4_0-37</li>
</ul>
<p>
<em>Note: </em> as of Eclipse/SWT 4.8, Mozilla (XULRunner) is no longer supported.
</br>
<em>Note: </em> as of Eclipse/SWT 4.15, WebKitGTK 1.x is no longer supported.
<p>
</dd>
<dt><strong><a name="howuseedge">Q: How do I explicitly use Edge as the Browser's underlying renderer?</a></strong></dt>
<dd>A: To specify that an Edge renderer be used by a Browser instance, create it with style <code>SWT.EDGE</code> (since 4.19) or
set the Java property <code>org.eclipse.swt.browser.DefaultType=edge</code>.
<p>
Edge rendering back-end uses the WebView2 component, which is based on, but distinct from the Edge browser itself.
WebView2 has to be installed separately from one of the following sources:
<ul>
<li>A stand-alone runtime installer, either web or offline
(<a href="https://developer.microsoft.com/en-us/microsoft-edge/webview2/#webview-title">Download the WebView2 Runtime</a> from Microsoft).
<br />
This runtime will be shared between all applications on the machine and will auto-update itself independent of your application.
</li>
<li>
A fixed-version archive with all the necessary files (Same link as above).
<br />
This is a complete, fixed set of files to be included with your application.
Unlike the first option, you have complete freedom in bundling, packaging and updating it.
</li>
<li>
Beta, Dev or Canary version of the Edge browser
(<a href="https://www.microsoftedgeinsider.com/en-us/download">https://www.microsoftedgeinsider.com/en-us/download</a>).
<br />
This option is convenient for testing, but production deployments should use the previous two options.
</li>
</ul>
<p>
<em>Note:</em> Stable Edge browser installations <strong>don't</strong> provide a WebView2 component.
<p>
See also <a href="https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution">Distribution of apps using WebView2</a> on MSDN.
<p>
SWT will automatically locate installed browsers and runtimes.
In case you want to use fixed-version binaries or override the automatically chosen version,
set the <code>org.eclipse.swt.browser.EdgeDir</code> Java property to the directory containing <code>msedgewebview2.exe</code>.
For example:
<pre> java "-Dorg.eclipse.swt.browser.EdgeDir=c:\Program Files (x86)\Microsoft\Edge Beta\Application\88.0.705.29" ...</pre>