Προβολές και σημείωσης πρωτογενούς κώδικα

Η λειτουργία επεξεργασίας και η αντίστοιχη προβολή κειμένου ευθύνονται κυρίως για την υλοποίηση της παρουσίασης του εγγράφου και τη ρύθμιση των κλάσεων βοήθειας που μπορεί να χρειάζονται.  (Ανατρέξτε στην ενότητα Προβολές αν δεν είστε εξοικειωμένοι με την έννοια της προβολής.)  

Η κλάση TextViewer χειρίζεται όλες τις λεπτομέρειες χαμηλού επιπέδου για την αντιστοίχιση του μοντέλου εγγράφου και των διαμερισμάτων του στο χρωματισμένο και μορφοποιημένο κείμενο που βλέπει ο χρήστης.  Για λειτουργίες επεξεργασίας πρωτογενούς κώδικα, παρέχεται η κλάση SourceViewer.  Η προβολή πρωτογενούς κώδικα παρουσιάζει την έννοια των σημειώσεων πρωτογενούς κώδικα.  Αυτές οι σημειώσεις μπορούν να παρουσιαστούν σε έναν κάθετο χάρακα στην αριστερή πλευρά του κειμένου, έναν χάρακα επισκόπησης στη δεξιά πλευρά του κειμένου,  ή ως χρωματισμένοι κυματισμοί κάτω από το κείμενο.

Η κλάση SourceViewer και οι κλάσεις βοήθειας χρησιμοποιούνται σε ολόκληρη την ιεραρχία AbstractTextEditor .  Το πακέτο org.eclipse.jface.text.source ορίζει αυτή την προβολή και τις άλλες κλάσεις που υποστηρίζουν την παρουσίαση σημειώσεων.

Σημειώσεις και χάρακες

Οι σημειώσεις όπως και τα διαμερίσματα εξαρτώνται σε μεγάλο βαθμό από το είδος του εγγράφου στο οποίο γίνεται τροποποίηση. Η διεπαφή IAnnotationModel ενός εγγράφου περιέχει τις σημειώσεις, τις αριθμεί όταν αυτό ζητηθεί και πραγματοποιεί ακρόαση για αλλαγές κειμένου έτσι ώστε οι σημειώσεις να είναι πάντα ενημερωμένα με βάση το κείμενο. Τα μοντέλα σημειώσεων είναι καταχωρημένα στην επέκταση org.eclipse.core.filebuffers.annotationModelCreation. Αυτό το σημείο επέκτασης επιτρέπει στις πρόσθετες λειτουργίες να καταχωρήσουν μια κλάση που θα δημιουργήσει ένα μοντέλο σημειώσεων κατάλληλο για μια δεδομένη επέκταση αρχείου. Το παράδειγμα λειτουργίας επεξεργασίας Java δεν χρησιμοποιεί αυτό το σημείο επέκτασης και έτσι μεταβιβάζεται σε αυτό το μοντέλο σημειώσεων που ορίζεται από την πλατφόρμα.

<extension
	point="org.eclipse.core.filebuffers.annotationModelCreation">
	<factory
		extensions="*"
		class="org.eclipse.ui.texteditor.ResourceMarkerAnnotationModelFactory">
	</factory>
</extension>

Η παρεχόμενη κλάση μεθόδου κατασκευής θα δημιουργήσει μια κλάση ResourceMarkerAnnotationModel για αρχεία κάθε επέκτασης. Η κλάση αυτή εμφανίζει σημειώσεις που αντιπροσωπεύουν ένα δείκτη σε έναν πόρο του χώρου εργασίας.  (Ανατρέξτε στην ενότητα Δείκτες πόρων για περισσότερες πληροφορίες σχετικά με τους δείκτες.)  Αντιστοιχίζει μια εικόνα και μια περιγραφή σε κάθε δείκτη και παρακολουθεί τον πόρο του για αλλαγές στους δείκτες.

Για να δείτε πώς εμφανίζεται ένα μοντέλο σημειώσεων σε μια λειτουργία επεξεργασίας κειμένου, θα εξετάσουμε τη λειτουργία επεξεργασίας κειμένου πλατφόρμας και τη χρήση των χαράκων και των σημειώσεων.  Οι λεπτομέρειες σχετικά με τον τρόπο παρουσίασης των διαφόρων σημειώσεων στους χάρακες και το κείμενο μπορούν να ελεγχθούν από το χρήστη στις προτιμήσεις Γενικά > Λειτουργίες επεξεργασίας > Λειτουργίες επεξεργασίας κειμένου> Σημειώσεις.

Κατακόρυφος χάρακας

Ο κατακόρυφος χάρακας στην αριστερή πλευρά της περιοχής επεξεργασίας χρησιμοποιείται από τις λειτουργίες επεξεργασίας του κειμένου πλατφόρμας για να δείξει τις περιοχές τιμών του κειμένου και τις σημειώσεις που αναφέρονται σε γραμμή και βρίσκονται δίπλα στην αντίστοιχη γραμμή του κειμένου.

Κατακόρυφος χάρακας

Αυτές οι σημειώσεις περιγράφονται στην παρεχόμενη κλάση ResourceMarkerAnnotationModel.  Αυτό το μοντέλο ρυθμίζεται στην κλάση SourceViewer κατά την απόδοση αρχικών τιμών της προβολής πρωτογενούς κώδικα από τη λειτουργία επεξεργασίας.  Το ακόλουθο τμήμα κώδικα από την κλάση AbstractTextEditor δείχνει τον τρόπο σύνδεσης του εγγράφου και του μοντέλου σημειώσεων με την προβολή.

private void initializeSourceViewer(IEditorInput input) {
		
	IAnnotationModel model= getDocumentProvider().getAnnotationModel(input);
	IDocument document= getDocumentProvider().getDocument(input);
		
	if (document != null) {
		fSourceViewer.setDocument(document, model);
		...

Μετά την παραμετροποίηση της προβολής πρωτογενούς κώδικα με το κατάλληλο έγγραφο και μοντέλο σημειώσεων, διαθέτει αρκετές πληροφορίες για την παρουσίαση του εγγράφου και τη διασφάλιση της εμφάνισης των σωστών σημειώσεων στον κατακόρυφο χάρακα στα αριστερά.  Το μοντέλο συνδέεται με τον χάρακα κατά τη ρύθμιση του εγγράφου.  Το ακόλουθο τμήμα κώδικα δείχνει τι συμβαίνει όταν ένα έγγραφο ρυθμιστεί στην προβολή πρωτογενούς κώδικα.  Έχει γίνει απλοποίηση του πραγματικού κώδικα που βρίσκεται στην κλάση SourceViewer για λόγους σαφήνειας:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// create visual annotation model from the supplied model and store 
	// in fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

Με αυτό τον τρόπο, ο χάρακας συνδέεται με το κατάλληλο μοντέλο σημειώσεων.  

Ας εξετάσουμε τον ίδιο το χάρακα.  Ο χάρακας δημιουργείται από τη λειτουργία επεξεργασίας κειμένου και στη συνέχεια συνδέεται με την προβολή της λειτουργίας επεξεργασίας.  Εφόσον το παράδειγμα λειτουργίας επεξεργασίας Java δεν ορίζει συγκεκριμένη συμπεριφορά για τους χάρακες, μεταβιβάζεται σε αυτό ο χάρακας όπως ορίζεται στην κλάση TextEditor.

protected IVerticalRuler createVerticalRuler() {
	CompositeRuler ruler= new CompositeRuler();
	ruler.addDecorator(0, new AnnotationRulerColumn(VERTICAL_RULER_WIDTH));
	if (isLineNumberRulerVisible())
		ruler.addDecorator(1, createLineNumberRulerColumn());
	return ruler;
}

Η λειτουργία επεξεργασίας κειμένου χρησιμοποιεί ένα στοιχείο CompositeRuler. Αυτός ο χάρακας δεν έχει δική του οπτική παρουσίαση.  Η παρουσίαση παρέχεται από μια λίστα διακριτικών που δείχνουν στήλες(IVerticalRulerColumn) μέσα στο χάρακα.  Σε αυτό το παράδειγμα, προστίθεται πάντα μια στήλη χάρακα που παρουσιάζει σημειώσεις (AnnotationRulerColumn) και μια στήλη χάρακα αριθμού γραμμής με βάση τις προτιμήσεις του χρήστη. Η στήλη του χάρακα σημειώσεων χειρίζεται τις λεπτομέρειες εμφάνισης των εικόνων σημειώσεων στις κατάλληλες θέσεις.

Πέρα από τις κλάσεις που σχετίζονται με την εμφάνιση ενός χάρακα, να σημειωθεί ότι το παράδειγμα λειτουργίας επεξεργασίας χρειάζεται μόνο να δημιουργήσει υποκλάση των κλάσεων πλαισίου για να αντλήσει μια συμπεριφορά χάρακα.  Στην κλάση JavaDocumentProvider μεταβιβάζεται ένα κατάλληλο μοντέλο σημειώσεων δείκτη από την κλάση FileDocumentProvider.  Στην κλάση JavaTextEditor μεταβιβάζεται η παρουσίαση χάρακα από την κλάση TextEditor.

Χάρακας επισκόπησης

Ο χάρακας επισκόπησης που βρίσκεται στη δεξιά πλευρά της περιοχής επεξεργασίας χρησιμοποιείται για την παρουσίαση σημειώσεων που αφορούν ολόκληρο το έγγραφο.Αυτές οι σημειώσεις παρουσιάζονται σε σχέση με τη θέση τους στο έγγραφο και δεν μετακινούνται όσο ο χρήστης πραγματοποιεί κύλιση στο έγγραφο.  Συνήθως υπάρχει μια αντίστοιχη σημείωση στον κατακόρυφο χάρακα όταν είναι ορατό αυτό το τμήμα του εγγράφου.  

Ο κατακόρυφος χάρακας που ακολουθεί δείχνει ότι υπάρχουν δύο εργασίες στο έγγραφο και ένας σελιδοδείκτης.  Εφόσον είναι ορατό το κείμενο με το σελιδοδείκτη, η σημείωσή του παρουσιάζεται και στα αριστερά.

Κατακόρυφος χάρακας επισκόπησης σε "Λειτουργία επεξεργασίας Java"

Ο χρήστης μπορεί να εκτελέσει πλοήγηση στη θέση της σημείωσης στον κώδικα πατώντας επάνω στην ίδια τη σημείωση.

Τα είδη των σημειώσεων που εμφανίζονται στο χάρακα επισκόπησης καθορίζονται από την προσθήκη ειδών σημειώσεων στο χάρακα.  Στο ακόλουθο τμήμα κώδικα της κλάσης SourceViewerDecorationSupport, τα είδη σημειώσεων προστίθενται δυναμικά στο χάρακα.(Ανατρέξτε στην επόμενη ενότητα για περισσότερες πληροφορίες σχετικά με την κλάση SourceViewerDecorationSupport.)

private void showAnnotationOverview(Object annotationType) {
if (fOverviewRuler != null) { Color c= getAnnotationTypeColor(annotationType);
fOverviewRuler.setAnnotationTypeColor(annotationType, c); int l= getAnnotationTypeLayer(annotationType);
fOverviewRuler.setAnnotationTypeLayer(annotationType, l);
fOverviewRuler.addAnnotationType(annotationType);
fOverviewRuler.update();
} }

Ο χάρακας επισκόπησης διαθέτει επίσης μια κλάση IAnnotationAccess που χρησιμοποιείται για να παρέχει πληροφορίες για μια συγκεκριμένη σημείωση, όπως το είδος του και τον τρόπο εμφάνισής του.  Η κλάση TextEditor χρησιμοποιεί μια κλάση DefaultMarkerAnnotationAccess που ερμηνεύει τις σημείωσεις σύμφωνα με τα είδη δεικτών που έχουν και ανατρέχει στις προτιμήσεις του χρήστη για να δει ποια είδη δεικτών θα πρέπει να παρουσιάζονται στο χάρακα επισκόπησης.

protected IAnnotationAccess createAnnotationAccess() {
	return new DefaultMarkerAnnotationAccess(fAnnotationPreferences);
}

Συμβουλευθείτε την υλοποίηση των κλάσεων DefaultMarkerAnnotationAccess και MarkerAnnotation για περισσότερες λεπτομέρειες σχετικά με την παρουσίαση δεικτών στο χάρακα επισκόπησης.

Σημειώσεις κειμένου

Σε συνδυασμό με την παρουσίαση σημειώσεων στους χάρακες, μια προβολή πρωτογενούς κώδικα μπορεί να παρουσιάσει τις σημειώσεις με τη μορφή χρωματιστών κυματιστών συμβόλων στο κείμενο.  

Κυματιστό σύμβολο στη "Λειτουργία επεξεργασίας Java"

Θα εξετάσουμε ξανά τη δημιουργία της προβολής πρωτογενούς κώδικα στην κλάση TextEditor.

protected ISourceViewer createSourceViewer(Composite parent, IVerticalRuler ruler, int styles) {
		
	... 
	ISourceViewer sourceViewer= new SourceViewer(parent, ruler, fOverviewRuler, isOverviewRulerVisible(), styles);
	fSourceViewerDecorationSupport= new SourceViewerDecorationSupport(sourceViewer, fOverviewRuler, fAnnotationAccess, sharedColors);
	configureSourceViewerDecorationSupport();
		
	return sourceViewer;
}

Η κλάση SourceViewerDecorationSupport χειρίζεται πολλά από τα διακριτικά που παρουσιάζονται σε μια προβολή πρωτογενούς κώδικα, μεταξύ των οποίων οι σημειώσεις κειμένου, τα χρωματιστά περιθώρια, τις χρωματιστές γραμμές δρομέα, κ.τ.λ.  Ρυθμίζεται σύμφωνα με τις προτιμήσεις χρήστη έτσι ώστε να ανταποκρίνεται σε δυναμικές ενημερώσεις αλλαγών των προτιμήσεων χρήστη.  Οι περισσότερες λειτουργίες επεξεργασίας δε χρειάζεται να ασχολούνται με τις λεπτομέρειες σχετικά με τον τρόπο σχεδίασης αυτών των διακριτικών.  (Ανατρέξτε στην κλάση SourceViewerDecorationSupport και τις σχετικές κλάσεις όπως AnnotationPainter αν είναι απαραίτητο!).  Αυτό που πρέπει να γνωρίζετε είναι ποιά διακριτικά είναι διαθέσιμα έτσι ώστε η κλάση SourceViewer και η κλάση SourceViewerDecorationSupport που την υποστηρίζει, να ρυθμιστούν σωστά.

Ρύθμιση κλάσης SourceViewerDecorationSupport

Ας δούμε τις ρυθμίσεις που χρησιμοποιεί η κλάση TextEditor για την υποστήριξη των διακριτικών.

protected void configureSourceViewerDecorationSupport() {

	Iterator e= fAnnotationPreferences.getAnnotationPreferences().iterator();
	while (e.hasNext())
		fSourceViewerDecorationSupport.setAnnotationPreference((AnnotationPreference) e.next());
	fSourceViewerDecorationSupport.setAnnotationPainterPreferenceKeys(DefaultMarkerAnnotationAccess.UNKNOWN, UNKNOWN_INDICATION_COLOR, UNKNOWN_INDICATION, UNKNOWN_INDICATION_IN_OVERVIEW_RULER, 0);
		
	fSourceViewerDecorationSupport.setCursorLinePainterPreferenceKeys(CURRENT_LINE, CURRENT_LINE_COLOR);
	fSourceViewerDecorationSupport.setMarginPainterPreferenceKeys(PRINT_MARGIN, PRINT_MARGIN_COLOR, PRINT_MARGIN_COLUMN);
	fSourceViewerDecorationSupport.setSymbolicFontName(getFontPropertyPreferenceKey());
}

Να σημειωθεί ότι οι προτιμήσεις σημειώσεων χρησιμοποιούνται για τον ορισμό ειδών σημειώσεων για όλες τις σημειώσεις που παρουσιάζονται στις προτιμήσεις χρήστη.  Συμπεριλαμβάνονται οι σημειώσεις που συνεισφέρει οποιαδήποτε πρόσθετη λειτουργία και δεν περιορίζονται στις σημειώσεις που παρέχει ο πάγκος εργασίας.  Αν δεν επιθυμείτε να παρουσιάζονται όλες οι διαθέσιμες σημειώσεις στη λειτουργία επεξεργασίας θα πρέπει να αντικαταστήσετε αυτή τη μέθοδο και να ρυθμίσετε την κλάση SourceViewerDecorationSupport μόνο με τα είδη που θέλετε να παρουσιάζονται.