Τα φύλλα υποδείξεων καθοδηγούν το χρήστη μέσω μιας σειράς πολύπλοκων εργασιών για την
επίτευξη ενός συνολικού στόχου. Για παράδειγμα, ένα φύλλο υποδείξεων μπορεί να χρησιμοποιηθεί για να βοηθήσει στην καθοδήγηση του χρήστη μέσα στα αναγκαία βήματα για τη δημιουργία, μεταγλώττιση και εκτέλεση ενός απλού προγράμματος Java.
Τα φύλλα υποδείξεων εκκινούνται από το στοιχείο
μενού
Βοήθεια > Φύλλα υποδείξεων.... Τα φύλλα υποδείξεων μπορούν επίσης να εκκινηθούν από μια σελίδα εισαγωγής.
Τα φύλλα υποδείξεων ορίζονται χρησιμοποιώντας το σημείο επέκτασης org.eclipse.ui.cheatsheets.cheatSheetContent. Το ίδιο το περιεχόμενο του φύλλου υποδείξεων ορίζεται σε ξεχωριστό αρχείο, ώστε να μπορεί να μεταφραστεί εύκολα σε άλλες γλώσσες.
Η συνεισφορά ενός φύλλου υποδείξεων είναι αρκετά ξεκάθαρη. Ας εξετάσουμε ένα φύλλο υποδείξεων το οποίο συνεισφέρει το JDT για τη δόμηση μιας απλής εφαρμογής Java.
<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent"> <cheatsheet name="%cheatsheet.helloworld.name" contentFile="$nl$/cheatsheets/HelloWorld.xml" id="org.eclipse.jdt.helloworld"> <description>%cheatsheet.helloworld.desc</description> </cheatsheet> ...Όπως και άλλες συνεισφορές του πάγκου εργασίας, είναι δυνατός ο καθορισμός ονόματος, περιγραφής και ταυτότητας για το φύλλο υποδείξεων. Το όνομα και η περιγραφή εμφανίζονται όταν ο χρήστης προσπελάσει τη λίστα
Η πραγματική δουλειά για τα φύλλα υποδείξεων γίνεται στο αρχείο περιεχομένου. Το αρχείο περιεχομένου είναι ένα αρχείο XML του οποίου το όνομα και η θέση καθορίζονται στο γνώρισμα contentFile. Η διαδρομή για το αρχείο είναι σχετική με τον κατάλογο της πρόσθετης λειτουργίας. (Προσέξτε τη χρήση της μεταβλητής $nl$ στο όνομα καταλόγου, που σημαίνει ότι το αρχείο θα βρίσκεται σε έναν ειδικό κατάλογο για την εθνική γλώσσα του περιβάλλοντος προορισμού.)
Η ίδια η μορφή του αρχείου περιλαμβάνει πληροφορίες επισκόπησης σχετικά με το φύλλο υποδείξεων που συνοδεύονται από περιγραφή κάθε βήματος (που ονομάζεται στοιχείο) το οποίο θα εκτελέσει ο χρήστης. Στην πιο απλή μορφή, ένα στοιχείο είναι απλά μια λεπτομερής περιγραφή του βήματος που θα κάνει ο χρήστης. Ωστόσο, ένα στοιχείο μπορεί επίσης να προσδιορίσει μια ενέργεια που μπορεί να εκτελεστεί για την πραγματοποίηση του βήματος για λογαριασμό του χρήστη. Ας εξετάσουμε το πρώτο τμήμα του αρχείου περιεχομένου (HelloWorld.xml) για το φύλλο υποδείξεων Java.
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Simple Java Application"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Welcome to the Hello, World Java tutorial. It will help you build the famous "hello world" application and try it out. You will create a java project, and a java class that will print "hello world" in the console when run. Let's get started! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Open the Java Perspective"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Select Window->Open Perspective->Java in the menu bar at the top of the workbench. This step changes the perspective to set up the Eclipse workbench for Java development. You can click the "Click to Perform" button to have the "Java" perspective opened automatically. </description> </item> ...
Οι πληροφορίες τίτλου και εισαγωγής εμφανίζονται στην κορυφή του φύλλου υποδείξεων. Στη συνέχεια, περιγράφονται τα στοιχεία. Το πρώτο στοιχείο για αυτό το φύλλο υποδείξεων περιγράφει πώς ανοίγει η προοπτική Java. Ακόμα καλύτερα, το γνώρισμα action προσδιορίζει μια κλάση που μπορεί να χρησιμοποιηθεί για την εκτέλεση της ενέργειας για λογαριασμό του χρήστη. Η κλάση αυτή πρέπει να υλοποιεί την IAction. Αυτό εξυπηρετεί ιδιαίτερα καθώς σας επιτρέπει να επαναχρησιμοποιήσετε τις κλάσεις ενέργειας που έχουν γραφεί για συνεισφορές μενού και γραμμών εργαλείων.
Η κλάση αυτή πρέπει να υλοποιεί την ICheatSheetAction εάν η ενέργεια χρησιμοποιεί παραμέτρους ή ανάγκες οι οποίες πρέπει να γνωρίζουν το φύλλο υποδείξεων και την κατάστασή του. Στην περίπτωση αυτή, η ενέργεια θα μεταβιβαστεί σε έναν πίνακα παραμέτρων και μια παραπομπή στην ICheatSheetManager, ώστε να μπορεί να ζητήσει επιπλέον πληροφορίες για το φύλλο υποδείξεων. Κάθε απαραίτητη παράμετρος μπορεί να μεταβιβαστεί στη μέθοδο εκτέλεσης της ενέργειας με χρήση των γνωρισμάτων paramN.
Συνιστάται ιδιαίτερα η αναφορά επιτυχούς/ανεπιτυχούς αποτελέσματος από ενέργειες που κλήθηκαν από φύλλα υποδείξεων εάν υπάρχει πιθανότητα αποτυχίας στην εκτέλεση της ενέργειας. (Για παράδειγμα, ο χρήστης μπορεί να ακυρώσει την ενέργεια από το πλαίσιο διαλόγου της.) Δείτε την IAction.notifyResult(boolean) για περισσότερες λεπτομέρειες.
Τα στοιχεία δεν χρειάζεται να ορίζουν ενέργειες. Εάν το στοιχείο πρέπει να εκτελεστεί μη αυτόματα από το χρήστη, δεν χρειάζεται να προσδιορίσετε καμία ενέργεια. Παρακάτω ακολουθεί το τρίτο βήμα του φύλλου υποδείξεων Java, το οποίο μόνο λέει στο χρήστη πώς να κωδικοποιήσει την απλή εφαρμογή. Όταν δεν προσδιορίζεται ενέργεια, η περιγραφή στοιχείου πρέπει να δίνει οδηγίες στο χρήστη να πατήσει το κατάλληλο κουμπί μετά την ολοκλήρωση της εργασίας.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Add a System.out.println line in your main method"> <description> Now that you have your HelloWorld class, In the "public static void main" method, add the following statement: System.out.println("Hello world!"); and save your changes. Press the "click when done" button below when finished. </description> </item>Πρόσθετα γνωρίσματα ελέγχουν εάν μπορεί να παραληφθεί το στοιχείο και ποιο έγγραφο πρέπει να εκκινηθεί εάν ο χρήστης ζητήσει βοήθεια κατά τη διάρκεια του βήματος. Δείτε την τεκμηρίωση του σημείου επέκτασης org.eclipse.ui.cheatsheets.cheatSheetContent για περιγραφή όλων των γνωρισμάτων που μπορεί να ορίζονται σε ένα φύλλο υποδείξεων.
Τα υποστοιχεία μπορεί να οριστούν για περαιτέρω οργάνωση της παρουσίασης ενός στοιχείου. Αντίθετα με τα στοιχεία, δεν είναι απαραίτητη η επίσκεψη των υποστοιχείων με κάποια συγκεκριμένη σειρά. Τα υποστοιχεία μπορούν επίσης να ορίσουν ενέργειες που εκτελούν αυτόματα την υποεργασία για το χρήστη. Οι ενέργειες υποστοιχείων περιγράφονται με τον ίδιο τρόπο όπως και οι ενέργειες στοιχείων.
Οι εκφράσεις υπό συνθήκη μπορούν να χρησιμοποιηθούν για τον ορισμό στοιχείων φύλλων υποδείξεων, των οποίων το περιεχόμενο ή η συμπεριφορά εξαρτάται από το αν μια συγκεκριμένη συνθήκη είναι true. Οι συνθήκες περιγράφονται στο στοιχείο condition ενός υποστοιχείου χρησιμοποιώντας αυθαίρετες τιμές σειράς χαρακτήρων που αντιστοιχούνται με το γνώρισμα when κάθε επιλογής. Οι συνθήκες συνήθως παραπέμπουν σε μεταβλητές φύλλων υποδείξεων χρησιμοποιώντας τη μορφή ${var}, όπου var αναφέρεται στο όνομα της μεταβλητής φύλλου υποδείξεων. Μερικά απλά παραδείγματα θα βοηθήσουν στην παρουσίαση του τρόπου λειτουργίας των εκφράσεων υπό συνθήκη.
Τα υποστοιχεία υπό συνθήκη μπορούν να χρησιμοποιηθούν για την επιλογή ενός υποστοιχείου από μια λίστα πιθανών υποστοιχείων. Μόνο το πρώτο υποστοιχείο του οποίου το γνώρισμα when αντιστοιχεί με το γνώρισμα της συνθήκης περιλαμβάνεται στο φύλλο υποδείξεων. Για παράδειγμα:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>Αυτό το στοιχείο προσδιορίζει δύο πιθανά υποστοιχεία που εξαρτώνται από την τιμή της μεταβλητής v1. Εάν η τιμή της μεταβλητής είναι a, τότε θα περιληφθεί το πρώτο υποστοιχείο. Εάν η τιμή της μεταβλητής είναι a, τότε θα περιληφθεί το πρώτο υποστοιχείο. Εάν η μεταβλητή δεν έχει καμία τιμή, τότε θεωρείται σφάλμα.
Οι ενέργειες υπό συνθήκη είναι παρόμοιες με τα υποστοιχεία υπό συνθήκη. Το στοιχείο perform-when προσδιορίζει μια συνθήκη για την εκτέλεση μιας ενέργειας μεταξύ μιας λίστας δυνατών ενεργειών. Η συνθήκη περιγράφεται με τον ίδιο τρόπο, χρησιμοποιώντας μια αυθαίρετη σειρά χαρακτήρων που συχνά παραπέμπει σε μια μεταβλητή. Η ενέργεια της οποίας το γνώρισμα when αντιστοιχεί στη συνθήκη είναι αυτή που θα εκτελεστεί. Για παράδειγμα:
<item ...> <perform-when condition="${v1}"> <action when="a" class="com.example.actionA" pluginId-"com.example" /> <action when="b" class="com.example.actionB" pluginId-"com.example" /> </perform-when> </item>Η ενέργεια προς εκτέλεση επιλέγεται με βάση την τιμή της μεταβλητής v1. Εάν η μεταβλητή δεν έχει τιμή a ούτε b, τότε θεωρείται σφάλμα.
Τα επαναλαμβανόμενα υποστοιχεία περιγράφουν ένα υποστοιχείο που μπορεί να επεκταθεί σε 0, 1 ή περισσότερα παρόμοια υποβήματα. Τα υποβήματα εξειδικεύονται χρησιμοποιώντας την ειδική μεταβλητή ${this}. Αυτή η μεταβλητή θα αντικατασταθεί από τις τιμές που προσδιορίζονται στο γνώρισμα values. Το γνώρισμα "values" είναι μια σειρά από τιμές που χωρίζονται με κόμμα. Μια μεταβλητή που αναπτυχθεί σε μια λίστα τιμών μπορεί να χρησιμοποιηθεί στο γνώρισμα "values" . Για παράδειγμα:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}" /> </repeated-subitem> </item>Εάν η τιμή της μεταβλητής είναι 1,b,three, τότε θα εμφανιστούν τρία υποστοιχεία στο φύλλο υποδείξεων, έχοντας το καθένα μια μοναδική ετικέτα ("Step 1," "Step b," "Step three"). Η μεταβλητή μπορεί να χρησιμοποιηθεί στην τιμή της παραμέτρου ετικέτας ή ενέργειας. Μπορεί να επίσης να προσπελαστεί από τη ICheatSheetManager ενώ εκτελείται η ενέργεια.
Σε μερικές περιπτώσεις, ίσως θέλετε να αλλάξετε άλλα τμήματα του περιβάλλοντος χρήστη εάν είναι ενεργό ένα φύλλο υποδείξεων. Για παράδειγμα, μπορεί να έχετε μια λειτουργία επεξεργασίας που εμφανίζει ειδικές σημειώσεις εάν ένα φύλλο υποδείξεων καθοδηγεί το χρήστη στην εργασία τροποποίησης. Στην περίπτωση αυτή, μπορεί να προσδιοριστεί μια λειτουργία ακρόασης ως γνώρισμα του φύλλου υποδείξεων. Το γνώρισμα "listener" πρέπει να είναι το πλήρες όνομα κλάσης Java που αποτελεί υποκλάση της CheatSheetListener. Οι λειτουργίες ακρόασης θα λάβουν ειδοποιήσεις μαζί με μια ICheatSheetEvent όταν υπάρξει αλλαγή στον κύκλο ζωής του φύλλου υποδείξεων, όπως άνοιγμα, κλείσιμο ή ολοκλήρωση.
Το σημείο επέκτασης org.eclipse.ui.cheatsheets.cheatSheetItemExtension μπορεί να χρησιμοποιηθεί για τη συνεισφορά αυθαίρετων γνωρισμάτων σε προϋπάρχον φύλλο υποδείξεων. Σκοπός αυτού του σημείου επέκτασης είναι να επιτρέψει σε μια πρόσθετη λειτουργία να προσθέσει κουμπιά που θα βοηθήσουν το χρήστη σε ένα δεδομένο βήμα. Αυτά τα πρόσθετα κουμπιά εμφανίζονται δίπλα στο εικονίδιο βοήθειας.
Για τη χρήση του μηχανισμού αυτού, μπορείτε να ορίσετε κάθε αυθαίρετο γνώρισμα στον ορισμό ενός στοιχείου στο αρχείο XML του φύλλου υποδείξεων. Το όνομα του γνωρίσματος θα αντιστοιχιστεί με κάθε γνώρισμα που συνεισφέρθηκε σε επεκτάσεις στο org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Δείτε την τεκμηρίωση σημείων επέκταση για περισσότερες λεπτομέρειες.
Εργασία
με φύλλα υποδείξεων
Δημιουργία σύνθετων φύλλων υποδείξεων
Σύνταξη οδηγιών
Σημείο επέκτασης org.eclipse.ui.cheatsheets.cheatSheetContent
Προδιαγραφή
αρχείου περιεχομένου του φύλλου υποδείξεων