← Back to branch summary

~ubuntu-branches/ubuntu/quantal/netbeans/quantal

« back to all changes in this revision

Viewing changes to openide/arch/arch-openide-actions.xml

  • Committer: Bazaar Package Importer
  • Author(s): Marek Slama
  • Date: 2008-01-29 14:11:22 UTC
  • Revision ID: james.westby@ubuntu.com-20080129141122-fnzjbo11ntghxfu7
Tags: upstream-6.0.1
Import upstream version 6.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
openide/arch/arch-openide-actions.xml
 
1
<?xml version="1.0" encoding="UTF-8"?>
 
2
<!--
 
3
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 
4
 
 
5
Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
 
6
 
 
7
 
 
8
The contents of this file are subject to the terms of either the GNU
 
9
General Public License Version 2 only ("GPL") or the Common
 
10
Development and Distribution License("CDDL") (collectively, the
 
11
"License"). You may not use this file except in compliance with the
 
12
License. You can obtain a copy of the License at
 
13
http://www.netbeans.org/cddl-gplv2.html
 
14
or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
 
15
specific language governing permissions and limitations under the
 
16
License.  When distributing the software, include this License Header
 
17
Notice in each file and include the License file at
 
18
nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this
 
19
particular file as subject to the "Classpath" exception as provided
 
20
by Sun in the GPL Version 2 section of the License file that
 
21
accompanied this code. If applicable, add the following below the
 
22
License Header, with the fields enclosed by brackets [] replaced by
 
23
your own identifying information:
 
24
"Portions Copyrighted [year] [name of copyright owner]"
 
25
 
 
26
Contributor(s):
 
27
 
 
28
The Original Software is NetBeans. The Initial Developer of the Original
 
29
Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
 
30
Microsystems, Inc. All Rights Reserved.
 
31
 
 
32
If you wish your version of this file to be governed by only the CDDL
 
33
or only the GPL Version 2, indicate your decision by adding
 
34
"[Contributor] elects to include this software in this distribution
 
35
under the [CDDL or GPL Version 2] license." If you do not indicate a
 
36
single choice of license, a recipient has the option to distribute
 
37
your version of this file under either the CDDL, the GPL Version 2 or
 
38
to extend the choice of license to its licensees as provided above.
 
39
However, if you add GPL Version 2 code and therefore, elected the GPL
 
40
Version 2 license, then the option applies only if the new code is
 
41
made subject to such option by the copyright holder.
 
42
-->
 
43
<!DOCTYPE api-answers PUBLIC "-//NetBeans//DTD Arch Answers//EN" "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch.dtd" [
 
44
  <!ENTITY api-questions SYSTEM "../../nbbuild/antsrc/org/netbeans/nbbuild/Arch-api-questions.xml">
 
45
]>
 
46
 
 
47
<api-answers
 
48
  question-version="1.12"
 
49
  author="pzavadsky@netbeans.org"
 
50
>
 
51
 
 
52
  &api-questions;
 
53
 
 
54
 
 
55
<!-- Question: arch-what
 
56
 
 
57
     <question id="arch-what">
 
58
            What is this project good for?
 
59
            <hint>
 
60
            Please provide here few lines describing the the project,
 
61
            what problem it should solve, provide links to documentation, 
 
62
            specifications, etc.
 
63
            </hint>
 
64
        </question>
 
65
-->
 
66
<answer id="arch-what">
 
67
<em>Actions</em> provides system of support and utility classes 
 
68
for 'actions' usage in NetBeans.
 
69
</answer>
 
70
 
 
71
<answer id="arch-usecases">
 
72
        First see the <a href="@TOP@/org/openide/actions/doc-files/api.html">API description</a>. Here is just
 
73
    a list of frequently asked or interesting questions slowly expanding as
 
74
    people ask them:
 
75
    
 
76
    <h3>Actions faq:</h3>
 
77
    
 
78
    <usecase id="context-action-shortcuts" name="How to define configurable Shortcut for Component based shortcut?" >
 
79
<em><b>Q:</b>
 
80
The usual Swing way of defining Actions for your component is to create an Action instance and put it into the Input and Action maps of your component.
 
81
However how to make this Action's shortcut configurable from the Tools/Keyboard Shortcuts dialog?</em>
 
82
<p>
 
83
In order for the action to show up in Keyboards Shortcut dialog you need the action defined in the 
 
84
layer file under "Actions" folder and have the shortcut defined there under "Keymaps/&lt;Profile Name&gt;" linking to your action.
 
85
</p>
 
86
<pre>
 
87
    &lt;folder name="Actions" &gt;
 
88
        &lt;folder name="Window"&gt;
 
89
            &lt;file name="org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
 
90
        &lt;/folder&gt;
 
91
    &lt;/folder&gt;
 
92
 
 
93
    &lt;folder name="Keymaps"&gt;
 
94
        &lt;folder name="NetBeans"&gt;
 
95
            &lt;file name="S-A-Left.shadow"&gt;
 
96
                &lt;attr name="originalFile" stringvalue="Actions/Window/org-netbeans-core-actions-PreviousViewCallbackAction.instance"/&gt;
 
97
            &lt;/file&gt;
 
98
        &lt;/folder&gt;
 
99
    &lt;/folder&gt;
 
100
</pre>
 
101
<p>
 
102
The mentioned Action has to be a subclass of <code>org.openide.util.actions.CallbackSystemAction</code>. It does not necessarily has to 
 
103
perform the action, it's just a placeholder for linking the shortcut. You might want to override it's <code>getActionMapKey()</code> and give it a 
 
104
reasonable key.
 
105
</p>
 
106
<p>
 
107
The actual action that does the work in your component (preferably a simple Swing <code>javax.swing.Action</code>)
 
108
is to be put into your <code>TopComponent</code>'s <code>ActionMap</code>. The key for the <code>ActionMap</code> 
 
109
has to match the key defined in the global action's <code>getActionMapKey()</code> method.
 
110
</p>
 
111
<pre>
 
112
        getActionMap().put("PreviousViewAction", new MyPreviousTabAction());
 
113
</pre>
 
114
<p>
 
115
This way even actions from multiple <code>TopComponent</code>s with the same gesture (eg. "switch to next tab") can share the same configurable shortcut.
 
116
</p>
 
117
<p>
 
118
Note: Don't define your action's shortcut and don't put it into any of the <code>TopComponent</code>'s
 
119
<code>javax.swing.InputMap</code>. Otherwise the component would not pick up the changed shortcut from the
 
120
global context.
 
121
</p>
 
122
 
 
123
    </usecase>
 
124
</answer>  
 
125
 
 
126
 
 
127
<!-- Question: compat-i18n
 
128
 
 
129
     <question id="compat-i18n">
 
130
            Is your module correctly internationalized?
 
131
            <hint>
 
132
            Correct internationalization means that it obeys instuctions 
 
133
            at <a href="http://www.netbeans.org/devhome/docs/i18n/index.html">
 
134
            NetBeans I18N pages</a>.
 
135
            </hint>
 
136
        </question>
 
137
-->
 
138
<answer id="compat-i18n">
 
139
Yes.
 
140
</answer>
 
141
 
 
142
 
 
143
 
 
144
<!-- Question: compat-standards
 
145
 
 
146
     <question id="compat-standards">
 
147
            Does the module implements or defines any standards? Is the 
 
148
            implementation exact or it deviates somehow?
 
149
        </question>
 
150
-->
 
151
<answer id="compat-standards">
 
152
Before the Actions was build on <code>org.openide.util.actions.SystemAction</code>, this
 
153
was recently changed that Actions supports <code>javax.swing.Action</code> which
 
154
is java API standard, and Actions will be improving towards this more and more.
 
155
</answer>
 
156
 
 
157
 
 
158
 
 
159
<!-- Question: compat-version
 
160
 
 
161
     <question id="compat-version">
 
162
            Does your module properly coexists with earlier and future
 
163
            versions? Can you correctly read settings? Will future
 
164
            versions be able to read settings?
 
165
            
 
166
            <hint>
 
167
            Very helpful for reading settings is to store version number
 
168
            there, so future versions can decide whether how to read/convert
 
169
            the settings and older versions can ignore the new ones.
 
170
            </hint>
 
171
        </question>
 
172
-->
 
173
<answer id="compat-version">
 
174
Yes up to now it is supposed to be compatible with older versions.
 
175
</answer>
 
176
 
 
177
 
 
178
 
 
179
<!-- Question: dep-jre
 
180
 
 
181
     <question id="dep-jre">
 
182
            Which version of JRE you need (1.2, 1.3, 1.4, etc.)?
 
183
            <hint>
 
184
            It is expected that if your module runs on 1.x that it will run 
 
185
            on 1.x+1 if no, state that please. Also describe here cases where
 
186
            you run different code on different versions of JRE and why.
 
187
            </hint>
 
188
        </question>
 
189
-->
 
190
<answer id="dep-jre">
 
191
It uses JRE 1.3.
 
192
</answer>
 
193
 
 
194
 
 
195
 
 
196
<!-- Question: dep-jrejdk
 
197
 
 
198
     <question id="dep-jrejdk">
 
199
            Do you require JDK or is JRE enough?
 
200
        </question>
 
201
-->
 
202
<answer id="dep-jrejdk">
 
203
JRE is enough.
 
204
</answer>
 
205
 
 
206
 
 
207
 
 
208
<!-- Question: dep-nb
 
209
 
 
210
     <question id="dep-nb">
 
211
            What other NetBeans projects this one depends on?
 
212
            <hint>
 
213
            If you want, describe such projects as imported API using
 
214
            the <code>&lt;api name="identification" type="import or export" category="stable" url="where is the description" /&gt;</code>
 
215
            </hint>
 
216
        </question>
 
217
-->
 
218
<answer id="dep-nb">
 
219
It uses various kinds of API's:
 
220
<ul>
 
221
<li>
 
222
    <api 
 
223
        name="NodesAPI"
 
224
        group="java"
 
225
        type="import"
 
226
        category="official"
 
227
        url="@org-openide-nodes@/overview-summary.html"
 
228
    />
 
229
    The support class <code>NodeAction</code>.
 
230
</li>
 
231
<li>
 
232
    <api 
 
233
        name="WindowSystemAPI"
 
234
        group="java"
 
235
        type="import"
 
236
        category="official"
 
237
        url="@org-openide-windows@/overview-summary.html"
 
238
    />
 
239
    <code>NodeAction</code> uses <code>TopComponent.Registry</code>.
 
240
</li>
 
241
<li>
 
242
    <api 
 
243
        name="ExplorerAPI"
 
244
        group="java"
 
245
        type="import"
 
246
        category="official"
 
247
        url="@org-openide-explorer@/overview-summary.html"
 
248
    />
 
249
    <code>PasteAction</code> uses <code>ExplorerManager</code>.
 
250
</li>
 
251
<li>
 
252
    <api 
 
253
        name="FilesystemsAPI"
 
254
        group="java"
 
255
        type="import"
 
256
        category="official"
 
257
        url="@org-openide-filesystems@/overview-summary.html"
 
258
    />
 
259
    E.g. <code>FileSystemAction</code> uses <code>FileSystem</code>.
 
260
</li>
 
261
<li>
 
262
    <api 
 
263
        name="LoadersAPI"
 
264
        group="java"
 
265
        type="import"
 
266
        category="official"
 
267
        url="@org-openide-loaders@/overview-summary.html"
 
268
    />
 
269
    E.g. <code>FileSystemAction</code> uses <code>DataObject</code>.
 
270
</li>
 
271
<li>
 
272
    <api 
 
273
        name="UtilitiesAPI"
 
274
        group="java"
 
275
        type="import"
 
276
        category="official"
 
277
        url="@org-openide-util@/overview-summary.html"
 
278
    />
 
279
</li>
 
280
</ul>
 
281
</answer>
 
282
 
 
283
 
 
284
 
 
285
<!-- Question: dep-non-nb
 
286
 
 
287
     <question id="dep-non-nb">
 
288
            What other non-NetBeans projects this one depends on?
 
289
            
 
290
            <hint>
 
291
            Some non-NetBeans projects are packaged as NetBeans modules
 
292
            (see <a href="http://libs.netbeans.org">libraries</a>) and
 
293
            it is prefered to use this approach when more modules may
 
294
            depend on such third-party library.
 
295
            </hint>
 
296
        </question>
 
297
-->
 
298
<answer id="dep-non-nb">
 
299
No.
 
300
</answer>
 
301
 
 
302
 
 
303
 
 
304
<!-- Question: dep-platform
 
305
 
 
306
     <question id="dep-platform">
 
307
            On which platforms your module run? Any? Does it run in the same
 
308
            way?
 
309
            <hint>
 
310
            If your module is using JNI or deals with special differences of
 
311
            OSes like filesystems, etc. please describe here what they are.
 
312
            </hint>
 
313
        </question>
 
314
-->
 
315
<answer id="dep-platform">
 
316
100% pure Java. It should run anywhere.
 
317
</answer>
 
318
 
 
319
 
 
320
 
 
321
<!-- Question: deploy-jar
 
322
 
 
323
     <question id="deploy-jar">
 
324
            Do you deploy just module JAR file(s) or some other files?
 
325
            <hint>
 
326
            If your module consist just from one module JAR file, just confirm that.
 
327
            If it uses more than one JAR, describe where there are located, how
 
328
            they refer to each other. 
 
329
            If it consist of module JAR(s) and other files, please describe
 
330
            what is their purpose, why other files are necessary. Please 
 
331
            make sure that installation/deinstallation leaves the system 
 
332
            in state as it was before installation.
 
333
            </hint>
 
334
        </question>
 
335
-->
 
336
<answer id="deploy-jar">
 
337
Classes belonging to this module do not reside in standalone library.
 
338
They are bundled together with other parts of the openide in <code>openide.jar</code>.
 
339
</answer>
 
340
 
 
341
 
 
342
 
 
343
<!-- Question: deploy-nbm
 
344
 
 
345
     <question id="deploy-nbm">
 
346
            Can you deploy NBM via AutoUpdate center?
 
347
            <hint>
 
348
            If not why?
 
349
            </hint>
 
350
        </question>
 
351
-->
 
352
<answer id="deploy-nbm">
 
353
Whole openide can be deployed via AU center.
 
354
</answer>
 
355
 
 
356
 
 
357
 
 
358
<!-- Question: deploy-packages
 
359
 
 
360
     <question id="deploy-packages">
 
361
            Are packages of your module made inaccessible by not declaring them
 
362
            public?
 
363
            
 
364
            <hint>
 
365
            NetBeans module system allows restriction of access rights to
 
366
            public classes of your module from other modules. This prevents
 
367
            unwanted dependencies of others on your code and should be used
 
368
            whenever possible (<a href="http://www.netbeans.org/download/apis/org/openide/doc-files/upgrade.html#3.4-public-packages">
 
369
            public packages
 
370
            </a>). 
 
371
            </hint>
 
372
        </question>
 
373
-->
 
374
<answer id="deploy-packages">
 
375
<!-- XXX what does this mean? -->
 
376
No, ther are <api name="ActionsAPI" group="java" type="export" category="official" url="@TOP@/overview-summary.html"/>.
 
377
</answer>
 
378
 
 
379
 
 
380
 
 
381
<!-- Question: deploy-shared
 
382
 
 
383
     <question id="deploy-shared">
 
384
            Do you need to be installed in shared location or only in user directory?
 
385
            <hint>
 
386
            Installation location shall not matter, if it does explain why.
 
387
            </hint>
 
388
        </question>
 
389
-->
 
390
<answer id="deploy-shared">
 
391
<code>openide.jar</code> needs to be in the system directory. 
 
392
</answer>
 
393
 
 
394
 
 
395
 
 
396
<!-- Question: exec-classloader
 
397
 
 
398
     <question id="exec-classloader">
 
399
            Does your code uses own classloader?
 
400
            <hint>
 
401
            A bit unusual. Please explain why and what for.
 
402
            </hint>
 
403
        </question>
 
404
-->
 
405
<answer id="exec-classloader">
 
406
No.
 
407
</answer>
 
408
 
 
409
 
 
410
 
 
411
<!-- Question: exec-component
 
412
 
 
413
     <question id="exec-component">
 
414
            Is execution of your code influenced by (string) property
 
415
            of any of your components?
 
416
            
 
417
            <hint>
 
418
            Often <code>JComponent.getClientProperty</code>, <code>Action.getValue</code>
 
419
            or <code>PropertyDescriptor.getValue</code>, etc. are used to influence
 
420
            a behaviour of some code. This of course forms an interface that should
 
421
            be documented. Also if one depends on some interface that an object
 
422
            implements (<code>component instanceof Runnable</code>) that forms an
 
423
            API as well.
 
424
            </hint>
 
425
        </question>
 
426
-->
 
427
<answer id="exec-component">
 
428
There are used three values (via <code>Action.getValue()</code>).
 
429
<ul>
 
430
    <li><api name="OpenIDE-Transmodal-Action" group="property" category="devel" type="export">Inidicates action can be performed
 
431
    (typicaly via shortcut) even when dialog is popped out (modal or modeless).</api></li>
 
432
    <li><api name="delegates" group="property" category="devel" type="export">Used internaly in <code>PasteAction</code> delegate action
 
433
    which serves to pass an array of <code>PasteType</code> or <code>Action</code> to global instance (it is the only one
 
434
    which actually performs paste operation).</api></li>
 
435
    <li><api name="iconBase" group="property" category="devel" type="export">Used in companion to Actions.SMALL_ICON. Because there
 
436
    is no way to specify values for other types of icons the value of "iconBase" is used
 
437
    to construct the resource names of disabled, pressed and rollover icons. The value is
 
438
    expected to contain a resource path of the normal icon. Strings "_pressed",
 
439
    "_disabled" and "_rollover" are inserted before the suffix when searching for
 
440
    the other types of icons.</api></li>
 
441
    <li><api name="noIconInMenu" group="property" category="devel" type="export"> 
 
442
    Allowed value <code>Boolean.TRUE</code>.
 
443
    Influences the display of the action in the main menu, the item will have no icon there. Works for Actions that don't define custom MenuPresenter.
 
444
    </api></li>    
 
445
    <li><api name="PreferredIconSize" group="property" category="devel" type="export">
 
446
    Used to support 24x24 icons in toolbars. If toolbar button has client property "PreferredIconSize"
 
447
    set to Integer(24) button tries to load icon with name "iconBase" + "24" eg. "cut24.gif".
 
448
    Strings "_pressed","_disabled" and "_rollover" are inserted before the suffix when searching for
 
449
    the other types of icons eg.:"cut24_pressed.gif".</api></li>
 
450
    <li>
 
451
        <api name="waitFinished" group="property" category="friend" type="export">
 
452
             There is a new contract established between the caller of an action that
 
453
             allows mutual communication and possible synchronous execution even for 
 
454
             actions that by default perform their operations asynchronously. If the
 
455
             action's <code>actionPeformed</code> method is passed <code>ActionEvent</code>
 
456
             with command <q>waitFinished</q> the action shall be executed synchronously.
 
457
             The code:
 
458
             <pre>
 
459
             action.actionPerformed (new ActionEvent (this, 0, "waitFinished"))
 
460
             </pre>
 
461
             shall be executed synchronously, even if the action by default runs asynchronously.
 
462
             All asynchronous actions are asked to obey this contract, <code>CallableSystemAction</code>
 
463
             does it by default. However this contract is defined as friend one 
 
464
             and may be abandoned in future.
 
465
        </api>
 
466
    </li>
 
467
</ul>
 
468
 
 
469
<api name="ActionMapKeys" category="stable" group="property" type="export" >
 
470
<code>CallableSystemAction</code> uses its <code>getActionMapKey()</code> method
 
471
(usually overriden by subclasses) to get a key which is then searched in the
 
472
<code>ActionMap</code> obtained from the action's context. Other modules can
 
473
register their own action then: 
 
474
<pre>
 
475
topComponent.getActionMap ().put (theKey, new YourOwnSwingAction ());
 
476
</pre>
 
477
Here is the list of special keys:
 
478
<ul>
 
479
    <li><code>"cloneWindow"</code> - an action to be executed when a top component is to be cloned</li>
 
480
    <li><code>"closeWindow"</code> - an action when a view is about to be closed</li>
 
481
    <li><code>DefaultEditorKit.copyAction</code> - copy action handler</li>
 
482
    <li><code>DefaultEditorKit.cutAction</code> - cut action handler</li>
 
483
    <li><code>"delete"</code> - delete action handler</li>
 
484
    <li><code>DefaultEditorKit.pasteAction</code> - paste action handler</li>
 
485
    
 
486
    <!-- new since 5.8 -->
 
487
    <li><code>"jumpNext"</code> - when a next element shall be selected</li>
 
488
    <li><code>"jumpPrev"</code> - when a previous element shall be selected</li>
 
489
</ul>
 
490
</api>
 
491
 
 
492
</answer>
 
493
 
 
494
 
 
495
 
 
496
<!-- Question: exec-privateaccess
 
497
 
 
498
     <question id="exec-privateaccess">
 
499
            Are you aware of any other part of the system calling some of 
 
500
            your methods by reflection?
 
501
            <hint>
 
502
            If so, describe the "contract" as an API. Likely private or friend one, but
 
503
            still API and consider rewrite of it.
 
504
            </hint>
 
505
        </question>
 
506
-->
 
507
<answer id="exec-privateaccess">
 
508
No.
 
509
</answer>
 
510
 
 
511
 
 
512
 
 
513
<!-- Question: exec-property
 
514
 
 
515
     <question id="exec-property">
 
516
            Is execution of your code influenced by any environment of
 
517
            system (<code>System.getProperty</code>) property?
 
518
            
 
519
            <hint>
 
520
            If there is a property that can change the behaviour of your 
 
521
            code, somebody will likely use it. You should describe what it does 
 
522
            and the stability category of this API. You may use
 
523
            <PRE>
 
524
                &lt;property name="id" category="private" &gt;
 
525
                    description of the property, where it is used, what it influence, etc.
 
526
                &lt;/property&gt;            
 
527
            </PRE>
 
528
            </hint>
 
529
        </question>
 
530
-->
 
531
<answer id="exec-property">
 
532
        <ul>
 
533
            <li>
 
534
                <api type="export" group="property" name="org.openide.util.actions.CallableSystemAction.synchronousByDefault" category="friend">
 
535
                    If set to <code>true</code>, changes default value of the
 
536
                    <code>asynchronous()</code> method. Useful for unit tests
 
537
                    which would prefer to run all tested actions synchronously.
 
538
                </api>
 
539
            </li>
 
540
        </ul>
 
541
</answer>
 
542
 
 
543
 
 
544
 
 
545
<!-- Question: exec-reflection
 
546
 
 
547
     <question id="exec-reflection">
 
548
            Does your code uses java.lang.reflect to execute some other code?
 
549
            <hint>
 
550
            This usually indicates a missing or unsufficient API in the other
 
551
            part of the system. If the other side is not aware of your dependency
 
552
            this contract can be easily broken.
 
553
            </hint>
 
554
        </question>
 
555
-->
 
556
<answer id="exec-reflection">
 
557
A bit indirectly. <code>SystemAction.get (...)</code> 
 
558
calls to <code>SharedClassObject.findObject</code> which calls constructor by reflection. 
 
559
</answer>
 
560
 
 
561
 
 
562
 
 
563
<!-- Question: format-clipboard
 
564
 
 
565
     <question id="format-clipboard">
 
566
            Which protocols your code reads/inserts when communicating with
 
567
            clipboard?
 
568
        </question>
 
569
-->
 
570
<answer id="format-clipboard">
 
571
Implementations of cut, copy and paste (<code>CutAction</code>, <code>CopyAction</code>
 
572
and <code>PasteAction</code>) reads/writes from/into clipboard. It uses standard
 
573
<a href="http://java.sun.com/j2se/1.4.1/docs/api/java/awt/datatransfer/package-summary.html">java datatransfer mechanism</a>
 
574
and <a href="@org-openide-util@/org/openide/util/datatransfer/package-summary.html">Netbeans extension to the mechanism</a>.
 
575
</answer>
 
576
 
 
577
 
 
578
 
 
579
<!-- Question: format-dnd
 
580
 
 
581
     <question id="format-dnd">
 
582
            Which protocols your code understands during drag-n-drop?
 
583
        </question>
 
584
-->
 
585
<answer id="format-dnd">
 
586
See format-clibpoard.
 
587
</answer>
 
588
 
 
589
 
 
590
 
 
591
<!-- Question: format-types
 
592
 
 
593
     <question id="format-types">
 
594
            Which file formats your code reads or writes on disk?
 
595
        </question>
 
596
-->
 
597
<answer id="format-types">
 
598
None.
 
599
</answer>
 
600
 
 
601
 
 
602
 
 
603
<!-- Question: lookup-lookup
 
604
 
 
605
     <question id="lookup-lookup">
 
606
            Does your module uses <code>org.openide.util.Lookup</code>
 
607
            to find any components to communicate to? Which ones?
 
608
            
 
609
            <hint>
 
610
            Please describe the interfaces you are searching for, where 
 
611
            are defined, whether you are searching for just one or more of them,
 
612
            if the order is important, etc. Also clasify the stability of such
 
613
            API contract.
 
614
            </hint>
 
615
        </question>
 
616
-->
 
617
<answer id="lookup-lookup">
 
618
It uses <code>Lookup</code> as a representation of context in which are certain action
 
619
types <code>ContextAwareAction</code>s used. Current implementations
 
620
lookup in the context for <code>javax.swing.ActionMap</code>
 
621
or <code>org.openide.nodes.Node</code> or <code>org.openide.Node.Cookie</code>
 
622
instances.
 
623
</answer>
 
624
 
 
625
 
 
626
 
 
627
<!-- Question: lookup-register
 
628
 
 
629
     <question id="lookup-register">
 
630
            Do you register anything into the lookup for other to find? 
 
631
            <hint>
 
632
            Do you register using layer file or using <code>META-INF/services</code>?
 
633
            Who is supposed to find your component?
 
634
            </hint>
 
635
        </question>
 
636
-->
 
637
<answer id="lookup-register">
 
638
No. Actions are just clients of some lookups.
 
639
</answer>
 
640
 
 
641
 
 
642
 
 
643
<!-- Question: lookup-remove
 
644
 
 
645
     <question id="lookup-remove">
 
646
            Are removing entries of other modules from the lookup? 
 
647
            <hint>
 
648
            Why? Of course, that is possible, but it can be dangerous. Is the module
 
649
            your are masking resource from aware of what you are doing?
 
650
            </hint>
 
651
        </question>
 
652
-->
 
653
<answer id="lookup-remove">
 
654
No.
 
655
</answer>
 
656
 
 
657
 
 
658
 
 
659
<!-- Question: perf-exit
 
660
 
 
661
     <question id="perf-exit">
 
662
            Does your module executes anything on exit?
 
663
        </question>
 
664
-->
 
665
<answer id="perf-exit">
 
666
No.
 
667
</answer>
 
668
 
 
669
 
 
670
 
 
671
<!-- Question: perf-huge_dialogs
 
672
 
 
673
     <question id="perf-huge_dialogs">
 
674
            Does your module contain any dialogs or wizards with huge
 
675
            amount of GUI controls like combo boxes, lists, trees, text
 
676
            areas?
 
677
        </question>
 
678
-->
 
679
<answer id="perf-huge_dialogs">
 
680
Core implementation provides component for customizing shorcuts.
 
681
<code>org.netbeans.core.ShortcutsEditor</code>.
 
682
</answer>
 
683
 
 
684
 
 
685
 
 
686
<!-- Question: perf-limit
 
687
 
 
688
     <question id="perf-limit">
 
689
            Are there any limits in number/size of elements your code
 
690
            can handle?
 
691
        </question>
 
692
-->
 
693
<answer id="perf-limit">
 
694
None is defined.
 
695
</answer>
 
696
 
 
697
 
 
698
 
 
699
<!-- Question: perf-mem
 
700
 
 
701
     <question id="perf-mem">
 
702
            What is the amount of memory your component occupies? Estimate
 
703
            with a relaction to the number of windows, etc.
 
704
        </question>
 
705
-->
 
706
<answer id="perf-mem">
 
707
There is one class in VM per action. Because currently all actions are subclasses 
 
708
of <code>SystemAction</code>. 
 
709
Those kind of actions are singletons.
 
710
That older approach is getting away. There are already newer implementation
 
711
which creates short living action instances (context sensitive actions) 
 
712
when invoking popup menu. 
 
713
<br/>It should be measured how much of memory they take.
 
714
I guess the amount shouldn't be signicant.
 
715
</answer>
 
716
 
 
717
 
 
718
 
 
719
<!-- Question: perf-menus
 
720
 
 
721
     <question id="perf-menus">
 
722
            Does your module use dynamically changing context menus or
 
723
            context sensitive actions with complicated logic for enable/disable?
 
724
        </question>
 
725
-->
 
726
<answer id="perf-menus">
 
727
Actions doesn't use menus, it is vice versa.
 
728
</answer>
 
729
 
 
730
 
 
731
 
 
732
<!-- Question: perf-progress
 
733
 
 
734
     <question id="perf-progress">
 
735
            Does your module executes some long running task?
 
736
            <hint>Typically they are tasks like connecting over
 
737
            network, computing huge amount of data, compilation.
 
738
            Such communication should be done asynchronously (for example
 
739
            using <code>RequestProcessor</code>), definitively it should 
 
740
            not block AWT thread.
 
741
            </hint>
 
742
        </question>
 
743
-->
 
744
<answer id="perf-progress">
 
745
No.
 
746
</answer>
 
747
 
 
748
 
 
749
 
 
750
<!-- Question: perf-scale
 
751
 
 
752
     <question id="perf-scale">
 
753
            Which external criteria influence the performance of your
 
754
            program (size of file in editor, number of files in menu, 
 
755
            in source directory, etc.) and how well your code scales?
 
756
            Please include some estimates.
 
757
        </question>
 
758
-->
 
759
<answer id="perf-scale">
 
760
This should be irrelevant, as far as I know, Actions shouldn't use any collections
 
761
of data or something like that. One exception I know is global keymap implementation
 
762
which scales linear.
 
763
</answer>
 
764
 
 
765
 
 
766
 
 
767
<!-- Question: perf-startup
 
768
 
 
769
     <question id="perf-startup">
 
770
            Does your module executes anything on startup?
 
771
        </question>
 
772
-->
 
773
<answer id="perf-startup">
 
774
No.
 
775
</answer>
 
776
 
 
777
 
 
778
 
 
779
<!-- Question: perf-wakeup
 
780
 
 
781
     <question id="perf-wakeup">
 
782
            Is any piece of your code waking up periodically?
 
783
        </question>
 
784
-->
 
785
<answer id="perf-wakeup">
 
786
No. At least I do not know about that.
 
787
</answer>
 
788
 
 
789
 
 
790
 
 
791
<!-- Question: resources-file
 
792
 
 
793
     <question id="resources-file">
 
794
            Does your module use <code>java.io.File</code> directly?
 
795
            
 
796
            <hint>
 
797
            NetBeans provide a logical wrapper over plain files called 
 
798
            <code>org.openide.filesystems.FileObject</code> that
 
799
            provides uniform access to such resources and is the prefered
 
800
            way that should be used. But of course there can be situations when
 
801
            this is not suitable.
 
802
            </hint>
 
803
        </question>
 
804
-->
 
805
<answer id="resources-file">
 
806
No.
 
807
</answer>
 
808
 
 
809
 
 
810
 
 
811
<!-- Question: resources-layer
 
812
 
 
813
     <question id="resources-layer">
 
814
            Does your module provide own layer? Does it create some files or
 
815
            folders on it? What it is trying to communicate by that and with which 
 
816
            component?
 
817
            
 
818
            <hint>
 
819
            NetBeans allows automatic and declarative installation of resources 
 
820
            by module layers. Module register files into appropriate places
 
821
            and other components use that information to perform their task
 
822
            (build menu, toolbar, window layout, list of templates, set of
 
823
            options, etc.). 
 
824
            </hint>
 
825
        </question>
 
826
-->
 
827
<answer id="resources-layer">
 
828
No in fact. Just concrete action implementation provided by this module
 
829
are typically used in xml layers.
 
830
</answer>
 
831
 
 
832
 
 
833
 
 
834
<!-- Question: resources-mask
 
835
 
 
836
     <question id="resources-mask">
 
837
            Does your module mask/hide/override any resource provided by another one in
 
838
            module layer? 
 
839
            
 
840
            <hint>
 
841
            If you mask a file provided by another module, you probably depend
 
842
            on that and do not want the other module to (for example) change
 
843
            the file's name. That module shall thus make that file available as an API
 
844
            of some stability category.
 
845
            </hint>
 
846
        </question>
 
847
-->
 
848
<answer id="resources-mask">
 
849
No.
 
850
</answer>
 
851
 
 
852
 
 
853
 
 
854
<!-- Question: resources-read
 
855
 
 
856
     <question id="resources-read">
 
857
            Does your module read any resources from layers? For what purpose?
 
858
            
 
859
            <hint>
 
860
            As this is some kind of intermodule dependency, it is a kind of API.
 
861
            Please describe it and clasify according to 
 
862
            <a href="http://openide.netbeans.org/tutorial/api-design.html#categories">
 
863
            common stability categories</a>.
 
864
            </hint>
 
865
        </question>
 
866
-->
 
867
<answer id="resources-read">
 
868
There are special folders containing actions in xml layers.
 
869
<ul>
 
870
<li><em>Menu</em> contains actions which are present in menu.</li>
 
871
<li><em>Toolbars</em> contains actions which will be present in toolbars.</li>
 
872
<li><em>Shortcuts</em> contains actions which will have assigned shortcuts.</li>
 
873
<li><em>Actions</em> contains actions which are possible to manipulate with (via Options).</li>
 
874
</ul>
 
875
<em>Note:</em> Those layers are not necessarily read by Actions module. Probably 
 
876
it belongs to <em>Window system module</em>.
 
877
</answer>
 
878
 
 
879
 
 
880
 
 
881
 
 
882
<!--
 
883
        <question id="arch-overall" when="init">
 
884
            Describe the overall architecture. 
 
885
            <hint>
 
886
            What will be API for 
 
887
            <a href="http://openide.netbeans.org/tutorial/api-design.html#design.apiandspi" shape="rect">
 
888
                clients and what support API</a>? 
 
889
            What parts will be pluggable?
 
890
            How will plug-ins be registered? Please use <code>&lt;api type="export"/&gt;</code>
 
891
            to describe your general APIs.
 
892
            If possible please provide 
 
893
            simple diagrams. 
 
894
            </hint>
 
895
        </question>
 
896
-->
 
897
 <answer id="arch-overall">
 
898
  <p>
 
899
   XXX no answer for arch-overall
 
900
  </p>
 
901
 </answer>
 
902
 
 
903
 
 
904
 
 
905
<!--
 
906
        <question id="arch-quality" when="init">
 
907
            How will the <a href="http://www.netbeans.org/community/guidelines/q-evangelism.html" shape="rect">quality</a>
 
908
            of your code be tested and 
 
909
            how are future regressions going to be prevented?
 
910
            <hint>
 
911
            What kind of testing do
 
912
            you want to use? How much functionality, in which areas,
 
913
            should be covered by the tests? 
 
914
            </hint>
 
915
        </question>
 
916
-->
 
917
 <answer id="arch-quality">
 
918
  <p>
 
919
   XXX no answer for arch-quality
 
920
  </p>
 
921
 </answer>
 
922
 
 
923
 
 
924
 
 
925
<!--
 
926
        <question id="arch-time" when="init">
 
927
            What are the time estimates of the work?
 
928
            <hint>
 
929
            Please express your estimates of how long the design, implementation,
 
930
            stabilization are likely to last. How many people will be needed to
 
931
            implement this and what is the expected milestone by which the work should be 
 
932
            ready?
 
933
            </hint>
 
934
        </question>
 
935
-->
 
936
 <answer id="arch-time">
 
937
  <p>
 
938
   XXX no answer for arch-time
 
939
  </p>
 
940
 </answer>
 
941
 
 
942
 
 
943
 
 
944
<!--
 
945
        <question id="arch-where" when="init">
 
946
            Where one can find sources for your module?
 
947
            <hint>
 
948
                Please provide link to the CVS web client at
 
949
                http://www.netbeans.org/download/source_browse.html
 
950
                or just use tag defaultanswer generate='here'
 
951
            </hint>
 
952
        </question>
 
953
-->
 
954
 <answer id="arch-where">
 
955
  <defaultanswer generate='here' />
 
956
 </answer>
 
957
 
 
958
 
 
959
 
 
960
 <answer id="deploy-dependencies">
 
961
  <p>
 
962
   Nothing.
 
963
  </p>
 
964
 </answer>
 
965
 
 
966
 
 
967
 
 
968
<!--
 
969
        <question id="exec-ant-tasks" when="impl">
 
970
            Do you define or register any ant tasks that other can use?
 
971
            
 
972
            <hint>
 
973
            If you provide an ant task that users can use, you need to be very
 
974
            careful about its syntax and behaviour, as it most likely forms an
 
975
                  API for end users and as there is a lot of end users, their reaction
 
976
            when such API gets broken can be pretty strong.
 
977
            </hint>
 
978
        </question>
 
979
-->
 
980
 <answer id="exec-ant-tasks">
 
981
  <p>
 
982
   XXX no answer for exec-ant-tasks
 
983
  </p>
 
984
 </answer>
 
985
 
 
986
 
 
987
 
 
988
<!--
 
989
        <question id="exec-introspection" when="impl">
 
990
            Does your module use any kind of runtime type information (<code>instanceof</code>,
 
991
            work with <code>java.lang.Class</code>, etc.)?
 
992
            <hint>
 
993
            Check for cases when you have an object of type A and you also
 
994
            expect it to (possibly) be of type B and do some special action. That
 
995
            should be documented. The same applies on operations in meta-level
 
996
            (Class.isInstance(...), Class.isAssignableFrom(...), etc.).
 
997
            </hint>
 
998
        </question>
 
999
-->
 
1000
 <answer id="exec-introspection">
 
1001
  <p>
 
1002
   XXX no answer for exec-introspection
 
1003
  </p>
 
1004
 </answer>
 
1005
 
 
1006
 
 
1007
 
 
1008
<!--
 
1009
        <question id="exec-process" when="impl">
 
1010
            Do you execute an external process from your module? How do you ensure
 
1011
            that the result is the same on different platforms? Do you parse output?
 
1012
            Do you depend on result code?
 
1013
            <hint>
 
1014
            If you feed an input, parse the output please declare that as an API.
 
1015
            </hint>
 
1016
        </question>
 
1017
-->
 
1018
 <answer id="exec-process">
 
1019
  <p>
 
1020
   XXX no answer for exec-process
 
1021
  </p>
 
1022
 </answer>
 
1023
 
 
1024
 
 
1025
 
 
1026
<!--
 
1027
        <question id="exec-threading" when="impl">
 
1028
            What threading models, if any, does your module adhere to?
 
1029
            <hint>
 
1030
                If your module calls foreign APIs which have a specific threading model,
 
1031
                indicate how you comply with the requirements for multithreaded access
 
1032
                (synchronization, mutexes, etc.) applicable to those APIs.
 
1033
                If your module defines any APIs, or has complex internal structures
 
1034
                that might be used from multiple threads, declare how you protect
 
1035
                data against concurrent access, race conditions, deadlocks, etc.,
 
1036
                and whether such rules are enforced by runtime warnings, errors, assertions, etc.
 
1037
                Examples: a class might be non-thread-safe (like Java Collections); might
 
1038
                be fully thread-safe (internal locking); might require access through a mutex
 
1039
                (and may or may not automatically acquire that mutex on behalf of a client method);
 
1040
                might be able to run only in the event queue; etc.
 
1041
                Also describe when any events are fired: synchronously, asynchronously, etc.
 
1042
                Ideas: <a href="http://core.netbeans.org/proposals/threading/index.html#recommendations" shape="rect">Threading Recommendations</a> (in progress)
 
1043
            </hint>
 
1044
        </question>
 
1045
-->
 
1046
 <answer id="exec-threading">
 
1047
  <p>
 
1048
   XXX no answer for exec-threading
 
1049
  </p>
 
1050
 </answer>
 
1051
 
 
1052
 
 
1053
 
 
1054
<!--
 
1055
        <question id="perf-spi" when="init">
 
1056
            How the performance of the plugged in code will be enforced?
 
1057
            <hint>
 
1058
            If you allow foreign code to be plugged into your own module, how
 
1059
            do you enforce that it will behave correctly and quickly and will not
 
1060
            negatively influence the performance of your own module?
 
1061
            </hint>
 
1062
        </question>
 
1063
-->
 
1064
 <answer id="perf-spi">
 
1065
  <p>
 
1066
   XXX no answer for perf-spi
 
1067
  </p>
 
1068
 </answer>
 
1069
 
 
1070
 
 
1071
 
 
1072
<!--
 
1073
        <question id="security-grant" when="final">
 
1074
            Does your code grant additional rights to some other code?
 
1075
            <hint>Avoid using a class loader that adds extra
 
1076
            permissions to loaded code unless really necessary.
 
1077
            Also note that your API implementation
 
1078
            can also expose unneeded permissions to enemy code by
 
1079
            calling AccessController.doPrivileged().</hint>
 
1080
        </question>
 
1081
-->
 
1082
 <answer id="security-grant">
 
1083
  <p>
 
1084
   XXX no answer for security-grant
 
1085
  </p>
 
1086
 </answer>
 
1087
 
 
1088
 
 
1089
 
 
1090
<!--
 
1091
        <question id="security-policy" when="final">
 
1092
            Does your functionality require modifications to the standard policy file?
 
1093
            <hint>Your code might pass control to third-party code not
 
1094
            coming from trusted domains. This could be code downloaded over the
 
1095
            network or code coming from libraries that are not bundled
 
1096
            with NetBeans. Which permissions need to be granted to which domains?</hint>
 
1097
        </question>
 
1098
-->
 
1099
 <answer id="security-policy">
 
1100
  <p>
 
1101
   XXX no answer for security-policy
 
1102
  </p>
 
1103
 </answer>
 
1104
 
 
1105
</api-answers>