Εκδοχή 3.2
Το έγγραφο αυτό περιγράφει τη δομή του αρχείου περιεχομένου του φύλλου υποδείξεων, ως μια σειρά τμημάτων κώδικα DTD (σχήμα XML αναγνώσιμο από υπολογιστή).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
Το στοιχείο <cheatsheet> ορίζει το κύριο σώμα του αρχείου περιεχομένου του φύλλο υποδείξεων. Τα γνωρίσματα του <cheatsheet> έχουν ως εξής:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Το στοιχείο <intro> χρησιμοποιείται για την περιγραφή της εισαγωγής του φύλλου υποδείξεων, η οποία θα εμφανιστεί. Το υποστοιχείο <description> περιέχει το κύριο σώμα της εισαγωγής. Τα γνωρίσματα του <intro> έχουν ως εξής:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
Το στοιχείο <description> περιέχει την περιγραφή ενός φύλλου υποδείξεων ή ενός στοιχείου του φύλλου υποδείξεων. Η περιγραφή αποτελείται από ένα κείμενο το οποίο εμπεριέχει απλά προσδιοριστικά μορφοποίησης. Το φύλλο υποδείξεων μορφοποιεί αυτόματα και διατάσσει το κείμενο έτσι ώστε να εμφανίζεται με λογικό τρόπο στο περιβάλλον χρήστη. Εντός του κειμένου, εξίσου διανεμημένα προσδιοριστικά <b>...</b> έχουν ως αποτέλεσμα την απόδοση του περικλειόμενου κειμένου σε έντονη γραφή και το στοιχείο <br/> μπορεί να χρησιμοποιηθεί για την εισαγωγή αλλαγής γραμμής. Αυτά είναι τα μόνα προσδιοριστικά μορφοποίησης που υποστηρίζονται επί του παρόντος (ωστόσο, μελλοντικά ενδέχεται να προστεθούν και άλλα). Ορισμένοι χαρακτήρες μέσα στο κείμενο έχουν ιδιαίτερη σημασία για τις λειτουργίες ανάλυσης XML. Συγκεκριμένα, για να γράψετε to write "<", ">", "&", "'" και """ (διπλά εισαγωγικά), γράψτε "<", ">", "&", "'" και """, αντίστοιχα. Το κενό διάστημα (κενό και αλλαγή γραμμής) θεωρείται ως διαχωριστικό λέξεων, διαδοχικά κενά και αλλαγές γραμμών θεωρούνται ως μία μονάδα και αποδίδονται ως ένα κενό ή μία αλλαγή γραμμής. Το κενό διάστημα αμέσως μετά τα προσδιοριστικά <description> και <br/> παραβλέπεται, όπως και το κενό διάστημα ακριβώς πριν το προσδιοριστικό </description>.
item
<!ELEMENT item (description ([action|command|perform-when] | (subitem|repeated-subitem|conditional-subitem)*) [onCompletion])> <!ATTLIST item title CDATA #REQUIRED dialog ("true" | "false") "false" skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Κάθε στοιχείο <item> περιγράφει ένα ανώτερου επιπέδου βήμα σε ένα φύλλο υποδείξεων. Ένα <item> μπορεί να περιέχει στοιχεία <subitem>. Τα γνωρίσματα του <item> έχουν ως εξής:
Το org.eclipse.ui.cheatsheets.cheatSheetItemExtension επιτρέπει την εμφάνιση στο περιβάλλον χρήστη πρόσθετων προσαρμοσμένων στοιχείων ελέγχου για το συγκεκριμένο στοιχείο. Οι συνεισφορές περιεχομένου του συγκεκριμένου σημείου επέκτασης δηλώνουν τα ονόματα των πρόσθετων γνωρισμάτων, που λαμβάνουν τιμές από σειρές χαρακτήρων, τα οποία θα εμφανίζονται στα στοιχεία <item>.
Τα απλά στοιχεία έχουν μια περιγραφή και μια προαιρετική ενέργεια ή εντολή. Στη συνήθη παρουσίαση, εμφανίζονται στον χρήστη κυρίως οι τίτλοι των στοιχείων φύλλων υποδείξεων. Η περιγραφή ενός στοιχείου εμφανίζεται μόνο κατά τη διάρκεια της εκτέλεσης του βήματος. Η παρουσία ενός στοιχείου <action>, <command> ή <perform-when> συσχετίζεται με ένα κουμπί, το οποίο μπορεί να πατήσει ο χρήστης για την εκτέλεση της ενέργειας ή της εντολής του υπο-βήματος. Εάν δεν υπάρχει καμία ενέργεια ή εντολή, το βήμα αυτό είναι ένα βήμα που ο χρήστης πρέπει να εκτελέσει μη αυτόματα και στη συνέχεια να υποδείξει δημόσια ότι το έχει ολοκληρώσει με επιτυχία.
Τα βήματα μπορούν να χωριστούν σε υπο-βήματα, όπως προσδιορίστηκε για τα υποστοιχεία <subitem>. Σε αντίθεση με τα στοιχεία, τα οποία ο χρήστης πρέπει να ακολουθεί σε αυστηρή διαδοχική σειρά, τα υποστοιχεία ενός δεδομένου στοιχείου μπορούν να εκτελεστούν με οποιαδήποτε σειρά. Η προσπάθεια (ή παράλειψη) για όλα τα υποστοιχεία ενός στοιχείου πρέπει να πραγματοποιείται πριν από τη μετάβαση στο επόμενο στοιχείο. (Αυτό σημαίνει ότι οι ενέργειες οι οποίες πρέπει να εκτελεστούν στην απαραίτητη διαδοχική σειρά δεν μπορούν να αναπαρασταθούν ως υποστοιχεία).
Ένα υποστοιχείο <conditional-subitem> επιτρέπει σε ένα βήμα να προσαρμόσει ένα υπο-βήμα με βάση τις μεταβλητές του φύλλου υποδείξεων, οι τιμές των οποίων λαμβάνονται σε προηγούμενα βήματα. Ένα υποστοιχείο <repeated-subitem> επιτρέπει σε ένα βήμα να συμπεριλάβει ένα σύνολο παρόμοιων υπο-βημάτων. Και σε αυτή την περίπτωση, το ακριβές σύνολο των υπο-βημάτων μπορεί να βασιστεί σε μεταβλητές του φύλλου υποδείξεων, των οποίων οι τιμές λαμβάνονται σε προηγούμενα βήματα.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Κάθε στοιχείο <subitem> περιγράφει ένα υπο-βήμα σε ένα φύλλο υποδείξεων. Ένα <subitem> φέρει μια ετικέτα απλού κειμένου, αλλά δεν περιέχει ούτε μεγάλη περιγραφή ούτε περαιτέρω υποστοιχεία. Τα γνωρίσματα του <subitem> έχουν ως εξής:
Τα υποστοιχεία μπορεί να περιέχουν μια προαιρετική ενέργεια ή εντολή. Η παρουσία ενός στοιχείου <action>, <command> ή <perform-when> συσχετίζεται συνήθως με ένα κουμπί, το οποίο μπορεί να πατήσει ο χρήστης για την εκτέλεση της ενέργειας ή της εντολής του υπο-βήματος. Εάν δεν υπάρχει καμία ενέργεια ή εντολή, το βήμα αυτό είναι ένα υπο-βήμα που ο χρήστης πρέπει να εκτελέσει μη αυτόματα και στη συνέχεια να υποδείξει δημόσια ότι το έχει ολοκληρώσει με επιτυχία.
Σε αντίθεση με τα στοιχεία, τα οποία πρέπει να ακολουθούνται σε αυστηρή διαδοχική σειρά, τα υποστοιχεία ενός δεδομένου στοιχείου μπορούν να εκτελεστούν με οποιαδήποτε σειρά. Η ολοκλήρωση ή παράλειψη όλων των υποστοιχείων ενός στοιχείου πρέπει να πραγματοποιείται πριν από τη μετάβαση στο επόμενο στοιχείο. (Αυτό σημαίνει ότι οι ενέργειες οι οποίες πρέπει να εκτελεστούν στην απαραίτητη διαδοχική σειρά δεν μπορούν να αναπαρασταθούν ως υποστοιχεία).
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Κάθε στοιχείο <conditional-subitem> περιγράφει ένα μοναδικό υπο-βήμα, του οποίου η μορφή μπορεί να διαφέρει ανάλογα με μια συνθήκη που είναι γνωστή τη στιγμή της επέκτασης του στοιχείου. Τα γνωρίσματα του <conditional-subitem> έχουν ως εξής:
Το γνώρισμα condition στο στοιχείο <conditional-subitem> παρέχει μια τιμή σειράς χαρακτήρων (η τιμή αυτή προέρχεται σταθερά από μια μεταβλητή του φύλλου υποδείξεων). Κάθε ένα από τα θυγατρικά <subitem> πρέπει να φέρει ένα γνώρισμα when με μια διακριτή τιμή σειράς χαρακτήρων. Όταν το στοιχείο επεκτείνεται, τότε το στοιχείο <conditional-subitem> αντικαθίσταται από το <subitem> με την αντίστοιχη τιμή. Θεωρείται σφάλμα αν δεν υπάρχει στοιχείο <subitem> με αντίστοιχη τιμή.
Για παράδειγμα, αν η μεταβλητή με το όνομα "v1" του φύλλου υποδείξεων έχει την τιμή "b" όταν επεκτείνεται το ακόλουθο στοιχείο
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>τότε επιλέγεται το δεύτερο υποστοιχείο και το στοιχείο επεκτείνεται σε κάποιο ισοδύναμο με
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Κάθε στοιχείο <repeated-subitem> περιγράφει ένα υποστοιχείο το οποίο επεκτείνεται σε 0, 1 ή περισσότερα παρόμοια υπο-βήματα. Τα γνωρίσματα του <repeated-subitem> έχουν ως εξής:
Το γνώρισμα values παρέχει μια λίστα σειρών χαρακτήρων που διαχωρίζονται με κόμμα. Το θυγατρικό <subitem> παρέχει το πρότυπο. Όταν το στοιχείο επεκτείνεται, τότε το <repeated-subitem> αντικαθίσταται από αντίγραφα του <subitem> με εμφανίσεις της μεταβλητής "this" που έχει αντικατασταθεί από την αντίστοιχη τιμή της σειράς χαρακτήρων.
Για παράδειγμα, αν η μεταβλητή με το όνομα "v1" του φύλλου υποδείξεων έχει την τιμή "1,b,three" όταν επεκτείνεται το ακόλουθο στοιχείο
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>τότε το στοιχείο επεκτείνεται σε κάποιο ισοδύναμο με:
<item ...> <subitem label="Step 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Step b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Step three."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/> </subitem> </item>
action
<!ELEMENT action EMPTY> <!ATTLIST action class CDATA #REQUIRED pluginId CDATA #REQUIRED param1 CDATA #IMPLIED ... param9 CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Κάθε στοιχείο <action> περιγράφει μια ενέργεια σε ένα φύλλο υποδείξεων. Τα γνωρίσματα του <action> έχουν ως εξής:
org.eclipse.jface.action.IAction
.
Εάν η ενέργεια αυτή υλοποιεί επίσης την ενέργεια org.eclipse.ui.cheatsheets.ICheatSheetAction
τότε θα κληθεί μέσω της μεθόδου run(String[],ICheatSheetManager) και θα μεταβιβαστούν σε αυτή η λειτουργία διαχείρισης του φύλλου υποδείξεων και οι παράμετροι της ενέργειας. Το γνώρισμα pluginId πρέπει να υπάρχει όποτε υπάρχει και το γνώρισμα αυτό. Σας συνιστούμε, οι ενέργειες που προορίζονται ώστε να κληθούν από φύλλα υποδείξεων να αναφέρουν ένα αποτέλεσμα επιτυχίας/αποτυχίας, όταν η εκτέλεση της ενέργειας μπορεί να αποτύχει (πιθανώς διότι ο χρήστης ακυρώνει την ενέργεια από το πλαίσιο διαλόγου). (Για περισσότερες λεπτομέρειες, δείτε org.eclipse.jface.action.Action.notifyResult(boolean).)org.eclipse.ui.cheatsheets.ICheatSheetAction
, οι τιμές σειράς χαρακτήρων αυτών των γνωρισμάτων μεταβιβάζονται στην ενέργεια η οποία καλείται. Μπορείτε να μεταβιβάσετε έως και 9 παραμέτρους σε μια ενέργεια φύλλου υποδείξεων (param1, param2, κλπ.). Οι παράμετροι που παρέχονται πρέπει να ξεκινούν με την παράμετρο 1 και πρέπει να είναι συνεχόμενες. Δηλαδή δεν είναι έγκυρος ο προσδιορισμός της param2 χωρίς να υπάρχει ήδη η param1. Εάν η σειρά χαρακτήρων του γνωρίσματος έχει τη μορφή "${var}", τότε θεωρείται ως παραπομπή σε μια μεταβλητή var του φύλλου υποδείξεων και η τιμή της συνθήκης θα είναι η τιμή της μεταβλητής για το φύλλο υποδείξεων κατά την έναρξη της εκτέλεσης του στοιχείου <item> που το περιέχει (ή η κενή σειρά, αν η μεταβλητή είναι μη οριοθετημένη τη στιγμή αυτή).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Κάθε στοιχείο <command> περιγράφει μια εντολή σε ένα φύλλο υποδείξεων. Tα γνωρίσματα <command> έχουν ως εξής:
Ακολουθεί ένα παράδειγμα ενός στοιχείου με μια εντολή που ανοίγει ένα παράθυρο διαλόγου και αποθηκεύει το αποτέλεσμα στη μεταβλητή του φύλλου υποδείξεων "result".
<item title="View Selection"> <description>Select a view which will be opened in the next step.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
Το στοιχείο <onCompletion> περιέχει κείμενο που θα εμφανιστεί όταν ολοκληρωθεί ένα στοιχείο. Αυτό είναι ιδιαίτερα χρήσιμο στο τελευταίο βήμα του φύλλου υποδείξεων που δηλώνει την ολοκλήρωση ολόκληρης της εργασίας. Η περιγραφή αποτελείται από ένα κείμενο το οποίο εμπεριέχει απλά προσδιοριστικά μορφοποίησης που ακολουθούν τους ίδιους κανόνες όπως και για το στοιχείο <description>. Τα στοιχεία <onCompletion> μπορούν επίσης να περιέχουν παραπομπές σε μεταβλητές του φύλλου υποδείξεων της μορφής "${var}", οι οποίες επεκτείνονται χρησιμοποιώντας την πραγματική τιμή της μεταβλητής του φύλλου υποδείξεων var κατά την ολοκλήρωση του βήματος.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Κάθε στοιχείο <perform-when> περιγράφει μια ενέργεια σε ένα φύλλο υποδείξεων. Τα γνωρίσματα του <perform-when> έχουν ως εξής:
Το γνώρισμα condition στο στοιχείο <conditional-subitem> παρέχει μια τιμή σειράς χαρακτήρων (η τιμή αυτή προέρχεται σταθερά από μια μεταβλητή του φύλλου υποδείξεων). Κάθε ένα από τα θυγατρικά <subitem> πρέπει να φέρει ένα γνώρισμα when με μια διακριτή τιμή σειράς χαρακτήρων. Όταν το στοιχείο επεκτείνεται, τότε το στοιχείο <conditional-subitem> αντικαθίσταται από το <subitem> με την αντίστοιχη τιμή. Θεωρείται σφάλμα αν δεν υπάρχει στοιχείο <subitem> με αντίστοιχη τιμή.
Για παράδειγμα, αν η μεταβλητή με το όνομα "v1" του φύλλου υποδείξεων έχει την τιμή "b" όταν επεκτείνεται το ακόλουθο στοιχείο
<item ...> <subitem label="Main step"> <perform-when condition="${v1}"> <action when="a" class="com.xyz.action1" pluginId="com.xyz" /> <action when="b" class="com.xyz.action2" pluginId="com.xyz" /> <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/> </conditional-subitem> </subitem> </item>τότε επιλέγεται η δεύτερη ενέργεια και το στοιχείο επεκτείνεται σε κάποιο ισοδύναμο με
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Ακολουθεί ένα παράδειγμα ενός απλού αρχείου περιεχομένου φύλλου υποδείξεων, το οποίο παρουσιάζει τη χρήση εντολών, του υποστοιχείων perform-when και των υποστοιχείων υπό συνθήκη.
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Sample Cheat Sheet"> <intro> <description>A cheat sheet which demonstrates the use of perform-when and conditional subitems</description> </intro> <item title="View Selection"> <description>Select a view which will be opened in the following steps.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when item" skip = "true"> <description>Uses perform when to open the view seleted previously.</description> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Search View" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when subitem"> <description>Uses perform when to open the view seleted previously.</description> <subitem label="Perform when subitem" skip = "true"> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Search View" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a conditional subitem"> <description>Uses perform when to open the view seleted previously.</description> <conditional-subitem condition="${result}"> <subitem when="Package Explorer" label="Open package explorer."> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Search View" label="Open Search View"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 IBM Corporation και άλλων.
Με την επιφύλαξη παντός δικαιώματος. Αυτό το πρόγραμμα και τα συνοδευτικά του υλικά διατίθενται βάσει των όρων της κοινής άδειας χρήσης Eclipse Public License v1.0 που συνοδεύει αυτή τη διανομή και διατίθεται στην ακόλουθη διεύθυνση: http://www.eclipse.org/legal/epl-v10.html.