You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>All of the C code used by SWT is generated by the <b>JNIGeneratorApp</b>
@@ -40,31 +36,19 @@ <h1>Generating the SWT JNI Code</h1>
40
36
<h3>Adding native methods</h3>
41
37
42
38
<ol>
43
-
<li>Add the function prototype in <tt>OS.java</tt>, copying the style and structure
44
-
of the other functions in that file. Note that for Mac/Cocoa, portions of <tt>OS.java</tt>
39
+
<li>Add the function prototype in <code>OS.java</code>, copying the style and structure
40
+
of the other functions in that file. Note that for Mac/Cocoa, portions of <code>OS.java</code>
45
41
are also <ahref="macgen.html">generated</a>.
46
-
<p></p>
47
42
<li>Install the latest SWT Tools from the <ahref="https://download.eclipse.org/eclipse/downloads/">Update Site</a>.
48
-
<p></p>
49
43
<li>Restart Eclipse.
50
-
<p></p>
51
44
<li>Use code assist templates like <b>jni*</b> (i.e. <i>jnifield</i> and <i>jnimethod</i>) to add javadoc tags that describe flags and casts for any primitive types. See <ahref="jnigen_metadata.html">metadata</a> for more documentation.
<li>Save the file. This should build the appropriate C files.
56
-
<p></p>
57
-
58
-
<li>Compile the new C code and copy the new libraries to the appropriate fragment. Steps:
59
-
<ul>
60
-
<li>right-click on the <tt>build.xml</tt> file of the appropriate fragment (i. e. org.eclipse.swt.<ws>.<os>.<arch>) depending on the os, platform and architecture being built</li>
61
-
<li>select "Run As -> Ant Build..."</li>
62
-
<li>on the Targets tab check the <tt>build_libraries</tt> target</li>
63
-
<li>on the JRE tab select "Run in the same JRE as the workspace"</li>
64
-
<li>on the Refresh tab check "Refresh resources upon completion" to refresh your workspace
65
-
after running the build; this ensures that Eclipse will pick up the fresh binaries</li>
66
-
<li>press the "Run" button to begin</li>
67
-
<p></p>
46
+
<li>Save the file. This should generate the needed changes in the appropriate C files.
47
+
48
+
<li>Compile the new C code and copy the new libraries to the appropriate fragment by running the <code>Build-SWT-native-binaries-for-running-platform</code> launch configuration.
<p>Annotates a parameter of a native method. The parameter is identified by its name.</p>
55
50
</li>
56
-
57
-
<li><b>@field</b><tt><metadata></tt></li>
58
-
59
-
<p>Annotates a field of a structure class.</p>
51
+
52
+
<li><b>@field</b><code><metadata></code>
53
+
<p>Annotates a field of a structure class.</p>
54
+
</li>
60
55
</ol>
61
56
62
57
<h3> Metadata </h3>
@@ -70,67 +65,144 @@ <h3> Metadata </h3>
70
65
71
66
<h3> Attributes </h3>
72
67
<ol>
73
-
<li><b>cast</b></li>
74
-
<p>Provide the C cast of a structure field <i>@field</i> or native method parameter <i>@param</i>.</p>
75
-
<li><b>accessor</b></li>
76
-
<p>Provide the C, C# or C++ name/identifier to be used instead of the java name. This can be used by structure fields <i>@field</i> or native methods <i>@method</i>.</p>
77
-
<li><b>flags</b></li>
78
-
<p>Provide switches to control how the C code is generated. Any tag may have this attribute.
79
-
Multiple flags are separated by a space character. See below for a list of the known flags.</p>
68
+
<li><b>cast</b>
69
+
<p>Provide the C cast of a structure field <i>@field</i> or native method parameter <i>@param</i>.</p>
70
+
</li>
71
+
<li><b>accessor</b>
72
+
<p>Provide the C, C# or C++ name/identifier to be used instead of the java name. This can be used by structure
73
+
fields <i>@field</i> or native methods <i>@method</i>.</p>
74
+
</li>
75
+
<li><b>flags</b>
76
+
<p>Provide switches to control how the C code is generated. Any tag may have this attribute.
77
+
Multiple flags are separated by a space character. See below for a list of the known flags.</p>
78
+
</li>
80
79
</ol>
81
80
82
-
83
81
<h3> Flags </h3>
84
-
85
-
86
82
<ol>
87
-
<li><b>no_gen</b></li>
88
-
<p>Indicate that the item should not be generated. For example, custom natives are coded by hand. Used in: <i>@jniclass</i>, <i>@method</i>, <i>@field</i></p>
89
-
<li><b>no_in</b></li>
90
-
<p>Indicate that a native method parameter is an out only variable. This only makes sense if the parameter is a structure or an array of primitives. It is an optimization to avoid copying the java memory to C memory on the way in. Used in: <i>@param</i></p>
91
-
<li><b>no_out</b></li>
92
-
<p>Indicate that a native method parameter is an in only variable. This only makes sense if the parameter is a structure or an array of primitives. It is an optimization to avoid copying the C memory from java memory on the way out. Used in: <i>@param</i></p>
93
-
<li><b>critical</b></li>
94
-
<p>Indicate that <tt>GetPrimitiveArrayCritical()</tt> should be used instead of <tt>Get<PrimitiveType>ArrayElements()</tt> when transferring array of primitives from/to C. This is an optimization to avoid copying memory and must be used carefully. It is ok to be used in <tt>MoveMemory()</tt> and <tt>memmove()</tt> natives. Used in: <i>@param</i>
95
-
<p>
96
-
<li><b>dynamic</b></li>
97
-
<p>Indicate that a native method should be looked up dynamically. It is useful when having a dependence on a given library is not desirable.
98
-
The library name is specified in the *_custom.h file. Used in: <i>@method</i>
99
-
<p>
100
-
<li><b>init</b></li>
101
-
<p>Indicate that the associated C local variable for a native method parameter should be initialized with zeros. Used in: <i>@param</i></p>
102
-
<li><b>struct</b></li>
103
-
<p>Indicate that a structure parameter should be passed by value instead of by reference. This dereferences the parameter by prepending *. The parameter must not be NULL. Used in: <i>@param</i></p>
104
-
<li><b>unicode</b></li>
105
-
<p>Indicate that <tt>GetStringChars()</tt>should be used instead of <tt>GetStringUTFChars()</tt> to get the characters of a java.lang.String passed as a parameter to native methods. Used in: <i>@param</i></p>
106
-
<li><b>sentinel</b></li>
107
-
<p>Indicate that the parameter of a native method is the sentinel (last parameter of a variable argument C function). The generated code is always the literal <tt>NULL</tt>. Some compilers expect the sentinel to be the literal <tt>NULL</tt> and output a warning if otherwise. Used in: <i>@param</i></p>
108
-
<li><b>const</b></li>
109
-
<p>Indicate that the native method represents a constant or global variable instead of a function. This omits <tt>()</tt> from the generated code. Used in: <i>@method</i></p>
110
-
<li><b>cast</b></li>
111
-
<p>Indicate that the C function should be casted to a prototype generated from the parameters of the native method. Useful for variable argument C functions. Used in: <i>@method</i></p>
112
-
<li><b>jni</b></li>
113
-
<p>Indicate that the native is part of the Java Native Interface. For example: <tt>NewGlobalRef()</tt>. Used in: <i>@method</i></p>
114
-
<li><b>address</b></li>
115
-
<p>Indicate that the native method represents a structure global variable and the address of it should be returned to Java. This is done by prepending &. Used in: <i>@method</i></p>
116
-
<li><b>no_wince</b></li>
117
-
<p>Indicate that the item should be #ifdef out in the Windows CE platform, but not in the regular win32 platform. Used in: <i>@field</i></p>
118
-
<li><b>cpp</b></li>
119
-
<p>Indicate that the platform source is in C++. Used in: <i>@jniclass</i>, <i>@method</i></p>
120
-
<li><b>new</b></li>
121
-
<p>Indicate that the native method is a C++ constructor that allocates an object on the heap. Used in: <i>@method</i></p>
122
-
<li><b>delete</b></li>
123
-
<p>Indicate that the native method is a C++ destructor that deallocates an object from the heap. Used in: <i>@method</i></p>
124
-
<li><b>gcnew</b></li>
125
-
<p>Indicate that the native method is a C# constructor that allocates an object on the managed (i.e. garbage collected) heap. Used in: <i>@method</i></p>
126
-
<li><b>gcobject</b></li>
127
-
<p>Indicate that the native method's return value or parameter is a C# managed object. Used in: <i>@method</i>, <i>@param</i></p>
128
-
<li><b>setter</b></li>
129
-
<p>Indicate that the native method represents a setter for a field in an object or structure. Used in: <i>@method</i></p>
130
-
<li><b>getter</b></li>
131
-
<p>Indicate that the native method represents a getter for a field in an object or structure. Used in: <i>@method</i></p>
132
-
<li><b>adder</b></li>
133
-
<p>Indicate that the native method takes 2 arguments, a collection and an item, and the += operator is used to add the item to the collection. Used in: <i>@method</i></p>
83
+
<li><b>no_gen</b>
84
+
<p>Indicate that the item should not be generated. For example, custom natives are coded by hand.<br>Used in:
85
+
<i>@jniclass</i>, <i>@method</i>, <i>@field</i>
86
+
</p>
87
+
</li>
88
+
<li><b>no_in</b>
89
+
<p>Indicate that a native method parameter is an out only variable. This only makes sense if the parameter is a
90
+
structure or an array of primitives. It is an optimization to avoid copying the java memory to C memory on
91
+
the way
92
+
in.<br>Used in: <i>@param</i></p>
93
+
</li>
94
+
<li><b>no_out</b>
95
+
<p>Indicate that a native method parameter is an in only variable. This only makes sense if the parameter is a
96
+
structure
97
+
or an array of primitives. It is an optimization to avoid copying the C memory from java memory on the way
98
+
out.<br>Used
99
+
in: <i>@param</i></p>
100
+
</li>
101
+
<li><b>critical</b>
102
+
<p>Indicate that <code>GetPrimitiveArrayCritical()</code> should be used instead of
103
+
<code>Get<PrimitiveType>ArrayElements()</code> when transferring array of primitives from/to C. This
104
+
is an
105
+
optimization to avoid copying memory and must be used carefully. It is ok to be used in
106
+
<code>MoveMemory()</code>
107
+
and <code>memmove()</code> natives.<br>Used in: <i>@param</i>
108
+
</p>
109
+
</li>
110
+
<li><b>dynamic</b>
111
+
<p>Indicate that a native method should be looked up dynamically. It is useful when having a dependence on a
112
+
given
113
+
library is not desirable.
114
+
The library name is specified in the *_custom.h file.<br>Used in: <i>@method</i>
115
+
</p>
116
+
</li>
117
+
<li><b>init</b>
118
+
<p>Indicate that the associated C local variable for a native method parameter should be initialized with zeros.
119
+
<br>Used
120
+
in: <i>@param</i>
121
+
</p>
122
+
</li>
123
+
<li><b>struct</b>
124
+
<p>Indicate that a structure parameter should be passed by value instead of by reference. This dereferences the
125
+
parameter by prepending *. The parameter must not be NULL. <br>Used in: <i>@param</i></p>
126
+
</li>
127
+
<li><b>unicode</b>
128
+
<p>Indicate that <code>GetStringChars()</code>should be used instead of <code>GetStringUTFChars()</code> to get
129
+
the
130
+
characters of a java.lang.String passed as a parameter to native methods. <br>Used in: <i>@param</i></p>
131
+
</li>
132
+
<li><b>sentinel</b>
133
+
<p>Indicate that the parameter of a native method is the sentinel (last parameter of a variable argument C
134
+
function).
135
+
The generated code is always the literal <code>NULL</code>. Some compilers expect the sentinel to be the
136
+
literal
137
+
<code>NULL</code> and output a warning if otherwise. <br>Used in: <i>@param</i>
138
+
</p>
139
+
</li>
140
+
<li><b>const</b>
141
+
<p>Indicate that the native method represents a constant or global variable instead of a function. This omits
142
+
<code>()</code> from the generated code. <br>Used in: <i>@method</i>
143
+
</p>
144
+
</li>
145
+
<li><b>cast</b>
146
+
<p>Indicate that the C function should be casted to a prototype generated from the parameters of the native
147
+
method.
148
+
Useful for variable argument C functions. <br>Used in: <i>@method</i></p>
149
+
</li>
150
+
<li><b>jni</b>
151
+
<p>Indicate that the native is part of the Java Native Interface. For example: <code>NewGlobalRef()</code>.
152
+
<br>Used
153
+
in:
154
+
<i>@method</i>
155
+
</p>
156
+
</li>
157
+
<li><b>address</b>
158
+
<p>Indicate that the native method represents a structure global variable and the address of it should be
159
+
returned to
160
+
Java. This is done by prepending. <br>Used in: <i>@method</i></p>
161
+
</li>
162
+
<li><b>no_wince</b>
163
+
<p>Indicate that the item should be #ifdef out in the Windows CE platform, but not in the regular win32
164
+
platform. <br>Used
165
+
in: <i>@field</i></p>
166
+
</li>
167
+
<li><b>cpp</b>
168
+
<p>Indicate that the platform source is in C++. <br>Used in: <i>@jniclass</i>, <i>@method</i></p>
169
+
</li>
170
+
<li><b>new</b>
171
+
<p>Indicate that the native method is a C++ constructor that allocates an object on the heap. <br>Used in:
172
+
<i>@method</i>
173
+
</p>
174
+
</li>
175
+
<li><b>delete</b>
176
+
<p>Indicate that the native method is a C++ destructor that deallocates an object from the heap. <br>Used in:
177
+
<i>@method</i>
178
+
</p>
179
+
</li>
180
+
<li><b>gcnew</b>
181
+
<p>Indicate that the native method is a C# constructor that allocates an object on the managed (i.e. garbage
182
+
collected)
183
+
heap. <br>Used in: <i>@method</i></p>
184
+
</li>
185
+
<li><b>gcobject</b>
186
+
<p>Indicate that the native method's return value or parameter is a C# managed object. <br>Used in:
187
+
<i>@method</i>,
188
+
<i>@param</i>
189
+
</p>
190
+
</li>
191
+
<li><b>setter</b>
192
+
<p>Indicate that the native method represents a setter for a field in an object or structure. <br>Used in:
193
+
<i>@method</i>
194
+
</p>
195
+
</li>
196
+
<li><b>getter</b>
197
+
<p>Indicate that the native method represents a getter for a field in an object or structure. <br>Used in:
198
+
<i>@method</i>
199
+
</p>
200
+
</li>
201
+
<li><b>adder</b>
202
+
<p>Indicate that the native method takes 2 arguments, a collection and an item, and the += operator is used to
203
+
add the
204
+
item to the collection. <br>Used in: <i>@method</i></p>
0 commit comments