Walkthrough: Create a view adornment, commands, and settings (column guides)
Sie können den Visual Studio-Text-/Code-Editor mit Befehlen und Ansichtseffekten erweitern. In diesem Artikel erfahren Sie, wie Sie mit einem beliebten Erweiterungsfeature, Spaltenführungslinien, beginnen. Spaltenführungslinien sind visuell helle Linien, die in der Ansicht des Text-Editors gezeichnet werden, um Den Code für bestimmte Spaltenbreiten zu verwalten. Insbesondere formatierter Code kann für Beispiele wichtig sein, die Sie in Dokumente, Blogbeiträge oder Fehlerberichte einschließen.
In dieser exemplarischen Vorgehensweise:
Erstellen eines VSIX-Projekts
Hinzufügen einer Editoransichtszierer
Hinzufügen von Unterstützung zum Speichern und Abrufen von Einstellungen (wo Spaltenführungslinien und deren Farbe gezeichnet werden sollen)
Befehle hinzufügen (Spaltenführungslinien hinzufügen/entfernen, farbe ändern)
Platzieren der Befehle im Menü "Bearbeiten" und Kontextmenüs für Textdokumenten
Hinzufügen von Unterstützung für das Aufrufen der Befehle aus dem Visual Studio-Befehlsfenster
Sie können eine Version der Funktion "Spaltenführungslinien" mit dieser Visual Studio Gallery-Erweiterung ausprobieren.
Hinweis
In dieser exemplarischen Vorgehensweise fügen Sie einen großen Code in einige Dateien ein, die von Visual Studio-Erweiterungsvorlagen generiert wurden. In Kürze wird diese exemplarische Vorgehensweise jedoch auf eine fertige Lösung auf GitHub mit anderen Erweiterungsbeispielen verweisen. Der fertige Code unterscheidet sich geringfügig davon, dass er echte Befehlssymbole enthält, anstatt generische Vorlagensymbole zu verwenden.
Die Lösung einrichten
Zuerst erstellen Sie ein VSIX-Projekt, fügen eine Editoransichtszierung hinzu und fügen dann einen Befehl hinzu (der einen VSPackage zum Eigenen des Befehls hinzufügt). Die grundlegende Architektur lautet wie folgt:
Sie verfügen über einen Listener für die Textansicht, der ein
ColumnGuideAdornmentObjekt pro Ansicht erstellt. Dieses Objekt lauscht bei Bedarf auf Ereignisse zur Änderung oder Änderung der Ansichtseinstellungen, zum Aktualisieren oder Erneuten Bearbeiten von Spaltenführungslinien.Es gibt ein
GuidesSettingsManagerElement, das das Lesen und Schreiben aus dem Visual Studio-Einstellungsspeicher behandelt. Der Einstellungs-Manager verfügt auch über Vorgänge zum Aktualisieren der Einstellungen, die die Benutzerbefehle unterstützen (Spalte hinzufügen, Spalte entfernen, Farbe ändern).Es gibt ein VSIP-Paket, das erforderlich ist, wenn Sie über Benutzerbefehle verfügen, aber es handelt sich lediglich um Codebausteine, der das Implementierungsobjekt der Befehle initialisiert.
Es gibt ein
ColumnGuideCommandsObjekt, das die Benutzerbefehle ausführt und die Befehlshandler für Befehle bindet, die in der VSCT-Datei deklariert sind.VSIX. Datei verwenden | Neu... Befehl zum Erstellen eines Projekts. Wählen Sie den Erweiterungsknoten unter C# im linken Navigationsbereich aus, und wählen Sie im rechten Bereich VSIX-Projekt aus. Geben Sie den Namen ColumnGuides ein, und wählen Sie "OK " aus, um das Projekt zu erstellen.
Sehen Sie sich Zierer an. Drücken Sie im Projektmappen-Explorer die rechte Zeigerschaltfläche auf dem Projektknoten. Wählen Sie das Add | Neues Element ... Befehl zum Hinzufügen eines neuen Ansichtszierelements. Erweiterbarkeit auswählen | Editor im linken Navigationsbereich, und wählen Sie "Editor Viewport Adornment " im rechten Bereich aus. Geben Sie den Namen ColumnGuideAdornment als Elementnamen ein, und wählen Sie "Hinzufügen" aus, um ihn hinzuzufügen.
Sie können sehen, dass diese Elementvorlage dem Projekt zwei Dateien hinzugefügt hat (sowie Verweise usw.): ColumnGuideAdornment.cs und ColumnGuideAdornmentTextViewCreationListener.cs. Die Vorlagen zeichnen ein violettes Rechteck in der Ansicht. Im folgenden Abschnitt ändern Sie einige Zeilen im Listener für die Ansichtserstellung und ersetzen den Inhalt von ColumnGuideAdornment.cs.
Befehle. Drücken Sie in Projektmappen-Explorer die rechte Zeigerschaltfläche auf dem Projektknoten. Wählen Sie das Add | Neues Element ... Befehl zum Hinzufügen eines neuen Ansichtszierelements. Erweiterbarkeit auswählen | VSPackage im linken Navigationsbereich und wählen Im rechten Bereich den benutzerdefinierten Befehl aus. Geben Sie den Namen ColumnGuideCommands als Elementnamen ein, und wählen Sie "Hinzufügen" aus. Zusätzlich zu mehreren Verweisen wurden die Befehle und das Paket auch ColumnGuideCommands.cs, ColumnGuideCommandsPackage.cs und ColumnGuideCommandsPackage.vsct hinzugefügt. Im folgenden Abschnitt ersetzen Sie den Inhalt der ersten und letzten Dateien, um die Befehle zu definieren und zu implementieren.
Einrichten des Listeners für die Textansichtserstellung
Öffnen Sie ColumnGuideAdornmentTextViewCreationListener.cs im Editor. Dieser Code implementiert einen Handler für jedes Mal, wenn Visual Studio Textansichten erstellt. Es gibt Attribute, die steuern, wann der Handler je nach Merkmalen der Ansicht aufgerufen wird.
Der Code muss auch eine Zierschicht deklarieren. Wenn der Editor Ansichten aktualisiert, ruft er die Verzierungsebenen für die Ansicht ab und ruft daraus die Zierelemente ab. Sie können die Reihenfolge Ihrer Ebene relativ zu anderen mit Attributen deklarieren. Ersetzen Sie die folgende Zeile:
[Order(After = PredefinedAdornmentLayers.Caret)]
mit diesen beiden Zeilen:
[Order(Before = PredefinedAdornmentLayers.Text)]
[TextViewRole(PredefinedTextViewRoles.Document)]
Die ersetzte Linie befindet sich in einer Gruppe von Attributen, die eine Zierebene deklarieren. Die erste Zeile, die Sie geändert haben, ändert sich nur, wo die Spaltenführungslinien angezeigt werden. Das Zeichnen der Zeilen "vor" dem Text in der Ansicht bedeutet, dass sie hinter oder unterhalb des Texts angezeigt werden. Die zweite Zeile deklariert, dass die Säulenführungszierer für Textentitäten gelten, die Ihrem Konzept eines Dokuments entsprechen, aber Sie könnten die Dekoration deklarieren, um beispielsweise nur für bearbeitbaren Text zu funktionieren. Weitere Informationen finden Sie in Sprachdienst- und Editorerweiterungspunkten.
Implementieren des Einstellungs-Managers
Ersetzen Sie den Inhalt der Guides Einstellungen Manager.cs durch den folgenden Code (siehe unten):
using Microsoft.VisualStudio.Settings;
using Microsoft.VisualStudio.Shell;
using Microsoft.VisualStudio.Shell.Settings;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Windows.Media;
namespace ColumnGuides
{
internal static class GuidesSettingsManager
{
// Because my code is always called from the UI thred, this succeeds.
internal static SettingsManager VsManagedSettingsManager =
new ShellSettingsManager(ServiceProvider.GlobalProvider);
private const int _maxGuides = 5;
private const string _collectionSettingsName = "Text Editor";
private const string _settingName = "Guides";
// 1000 seems reasonable since primary scenario is long lines of code
private const int _maxColumn = 1000;
static internal bool AddGuideline(int column)
{
if (! IsValidColumn(column))
throw new ArgumentOutOfRangeException(
"column",
"The parameter must be between 1 and " + _maxGuides.ToString());
var offsets = GuidesSettingsManager.GetColumnOffsets();
if (offsets.Count() >= _maxGuides)
return false;
// Check for duplicates
if (offsets.Contains(column))
return false;
offsets.Add(column);
WriteSettings(GuidesSettingsManager.GuidelinesColor, offsets);
return true;
}
static internal bool RemoveGuideline(int column)
{
if (!IsValidColumn(column))
throw new ArgumentOutOfRangeException(
"column", "The parameter must be between 1 and 10,000");
var columns = GuidesSettingsManager.GetColumnOffsets();
if (! columns.Remove(column))
{
// Not present. Allow user to remove the last column
// even if they're not on the right column.
if (columns.Count != 1)
return false;
columns.Clear();
}
WriteSettings(GuidesSettingsManager.GuidelinesColor, columns);
return true;
}
static internal bool CanAddGuideline(int column)
{
if (!IsValidColumn(column))
return false;
var offsets = GetColumnOffsets();
if (offsets.Count >= _maxGuides)
return false;
return ! offsets.Contains(column);
}
static internal bool CanRemoveGuideline(int column)
{
if (! IsValidColumn(column))
return false;
// Allow user to remove the last guideline regardless of the column.
// Okay to call count, we limit the number of guides.
var offsets = GuidesSettingsManager.GetColumnOffsets();
return offsets.Contains(column) || offsets.Count() == 1;
}
static internal void RemoveAllGuidelines()
{
WriteSettings(GuidesSettingsManager.GuidelinesColor, new int[0]);
}
private static bool IsValidColumn(int column)
{
// zero is allowed (per user request)
return 0 <= column && column <= _maxColumn;
}
// This has format "RGB(<int>, <int>, <int>) <int> <int>...".
// There can be any number of ints following the RGB part,
// and each int is a column (char offset into line) where to draw.
static private string _guidelinesConfiguration;
static private string GuidelinesConfiguration
{
get
{
if (_guidelinesConfiguration == null)
{
_guidelinesConfiguration =
GetUserSettingsString(
GuidesSettingsManager._collectionSettingsName,
GuidesSettingsManager._settingName)
.Trim();
}
return _guidelinesConfiguration;
}
set
{
if (value != _guidelinesConfiguration)
{
_guidelinesConfiguration = value;
WriteUserSettingsString(
GuidesSettingsManager._collectionSettingsName,
GuidesSettingsManager._settingName, value);
// Notify ColumnGuideAdornments to update adornments in views.
var handler = GuidesSettingsManager.SettingsChanged;
if (handler != null)
handler();
}
}
}
internal static string GetUserSettingsString(string collection, string setting)
{
var store = GuidesSettingsManager
.VsManagedSettingsManager
.GetReadOnlySettingsStore(SettingsScope.UserSettings);
return store.GetString(collection, setting, "RGB(255,0,0) 80");
}
internal static void WriteUserSettingsString(string key, string propertyName,
string value)
{
var store = GuidesSettingsManager
.VsManagedSettingsManager
.GetWritableSettingsStore(SettingsScope.UserSettings);
store.CreateCollection(key);
store.SetString(key, propertyName, value);
}
// Persists settings and sets property with side effect of signaling
// ColumnGuideAdornments to update.
static private void WriteSettings(Color color, IEnumerable<int> columns)
{
string value = ComposeSettingsString(color, columns);
GuidelinesConfiguration = value;
}
private static string ComposeSettingsString(Color color,
IEnumerable<int> columns)
{
StringBuilder sb = new StringBuilder();
sb.AppendFormat("RGB({0},{1},{2})", color.R, color.G, color.B);
IEnumerator<int> columnsEnumerator = columns.GetEnumerator();
if (columnsEnumerator.MoveNext())
{
sb.AppendFormat(" {0}", columnsEnumerator.Current);
while (columnsEnumerator.MoveNext())
{
sb.AppendFormat(", {0}", columnsEnumerator.Current);
}
}
return sb.ToString();
}
// Parse a color out of a string that begins like "RGB(255,0,0)"
static internal Color GuidelinesColor
{
get
{
string config = GuidelinesConfiguration;
if (!String.IsNullOrEmpty(config) && config.StartsWith("RGB("))
{
int lastParen = config.IndexOf(')');
if (lastParen > 4)
{
string[] rgbs = config.Substring(4, lastParen - 4).Split(',');
if (rgbs.Length >= 3)
{
byte r, g, b;
if (byte.TryParse(rgbs[0], out r) &&
byte.TryParse(rgbs[1], out g) &&
byte.TryParse(rgbs[2], out b))
{
return Color.FromRgb(r, g, b);
}
}
}
}
return Colors.DarkRed;
}
set
{
WriteSettings(value, GetColumnOffsets());
}
}
// Parse a list of integer values out of a string that looks like
// "RGB(255,0,0) 1, 5, 10, 80"
static internal List<int> GetColumnOffsets()
{
var result = new List<int>();
string settings = GuidesSettingsManager.GuidelinesConfiguration;
if (String.IsNullOrEmpty(settings))
return new List<int>();
if (!settings.StartsWith("RGB("))
return new List<int>();
int lastParen = settings.IndexOf(')');
if (lastParen <= 4)
return new List<int>();
string[] columns = settings.Substring(lastParen + 1).Split(',');
int columnCount = 0;
foreach (string columnText in columns)
{
int column = -1;
// VS 2008 gallery extension didn't allow zero, so per user request ...
if (int.TryParse(columnText, out column) && column >= 0)
{
columnCount++;
result.Add(column);
if (columnCount >= _maxGuides)
break;
}
}
return result;
}
// Delegate and Event to fire when settings change so that ColumnGuideAdornments
// can update. We need nothing special in this event since the settings manager
// is statically available.
//
internal delegate void SettingsChangedHandler();
static internal event SettingsChangedHandler SettingsChanged;
}
}
Der großteil dieses Codes erstellt und analysiert das Einstellungsformat: "RGB(<int,int,int<>><>) <int>, <int>, ...". Die ganzzahligen Zahlen am Ende sind die 1-basierten Spalten, in denen Spaltenführungslinien angezeigt werden sollen. Die Spaltenführungserweiterung erfasst alle Einstellungen in einer einzelnen Einstellungswertzeichenfolge.
Es gibt einige Teile des Codes, der hervorgehoben werden sollte. Die folgende Codezeile ruft den verwalteten Wrapper von Visual Studio für den Einstellungsspeicher ab. Dies wird größtenteils über die Windows-Registrierung abstrahiert, diese API ist jedoch unabhängig vom Speichermechanismus.
internal static SettingsManager VsManagedSettingsManager =
new ShellSettingsManager(ServiceProvider.GlobalProvider);
Der Speicher für Visual Studio-Einstellungen verwendet einen Kategoriebezeichner und einen Einstellungsbezeichner, um alle Einstellungen eindeutig zu identifizieren:
private const string _collectionSettingsName = "Text Editor";
private const string _settingName = "Guides";
Sie müssen nicht als Kategoriename verwenden "Text Editor" . Sie können alles auswählen, was Ihnen gefällt.
Die ersten Funktionen sind die Einstiegspunkte zum Ändern von Einstellungen. Sie überprüfen allgemeine Einschränkungen wie die maximale Anzahl zulässiger Führungslinien. Anschließend rufen sie auf WriteSettings, wodurch eine Einstellungszeichenfolge erstellt und die Eigenschaft GuideLinesConfigurationfestgelegt wird. Durch Festlegen dieser Eigenschaft wird der Einstellungswert im Visual Studio-Einstellungsspeicher gespeichert und das SettingsChanged Ereignis ausgelöst, um alle Objekte zu aktualisieren, die ColumnGuideAdornment jeweils einer Textansicht zugeordnet sind.
Es gibt einige Einstiegspunktfunktionen, z CanAddGuideline. B. zum Implementieren von Befehlen, die Einstellungen ändern. Wenn Visual Studio Menüs anzeigt, werden Befehlsimplementierungen abgefragt, um festzustellen, ob der Befehl derzeit aktiviert ist, was der Name ist usw. Im Folgenden erfahren Sie, wie Sie diese Einstiegspunkte für die Befehlsimplementierungen verbinden. Weitere Informationen zu Befehlen finden Sie unter Erweitern von Menüs und Befehlen.
Implementieren der ColumnGuideAdornment-Klasse
Die ColumnGuideAdornment Klasse wird für jede Textansicht instanziiert, die Schmücken enthalten kann. Diese Klasse lauscht bei Bedarf auf Ereignisse zum Ändern oder Ändern der Einstellungen der Ansicht und der Aktualisierung oder Neuzeichnung von Spaltenführungslinien.
Ersetzen Sie den Inhalt der ColumnGuideAdornment.cs durch den folgenden Code (siehe unten):
using System;
using System.Windows.Media;
using Microsoft.VisualStudio.Text.Editor;
using System.Collections.Generic;
using System.Windows.Shapes;
using Microsoft.VisualStudio.Text.Formatting;
using System.Windows;
namespace ColumnGuides
{
/// <summary>
/// Adornment class, one instance per text view that draws a guides on the viewport
/// </summary>
internal sealed class ColumnGuideAdornment
{
private const double _lineThickness = 1.0;
private IList<Line> _guidelines;
private IWpfTextView _view;
private double _baseIndentation;
private double _columnWidth;
/// <summary>
/// Creates editor column guidelines
/// </summary>
/// <param name="view">The <see cref="IWpfTextView"/> upon
/// which the adornment will be drawn</param>
public ColumnGuideAdornment(IWpfTextView view)
{
_view = view;
_guidelines = CreateGuidelines();
GuidesSettingsManager.SettingsChanged +=
new GuidesSettingsManager.SettingsChangedHandler(SettingsChanged);
view.LayoutChanged +=
new EventHandler<TextViewLayoutChangedEventArgs>(OnViewLayoutChanged);
_view.Closed += new EventHandler(OnViewClosed);
}
void SettingsChanged()
{
_guidelines = CreateGuidelines();
UpdatePositions();
AddGuidelinesToAdornmentLayer();
}
void OnViewClosed(object sender, EventArgs e)
{
_view.LayoutChanged -= OnViewLayoutChanged;
_view.Closed -= OnViewClosed;
GuidesSettingsManager.SettingsChanged -= SettingsChanged;
}
private bool _firstLayoutDone;
void OnViewLayoutChanged(object sender, TextViewLayoutChangedEventArgs e)
{
bool fUpdatePositions = false;
IFormattedLineSource lineSource = _view.FormattedLineSource;
if (lineSource == null)
{
return;
}
if (_columnWidth != lineSource.ColumnWidth)
{
_columnWidth = lineSource.ColumnWidth;
fUpdatePositions = true;
}
if (_baseIndentation != lineSource.BaseIndentation)
{
_baseIndentation = lineSource.BaseIndentation;
fUpdatePositions = true;
}
if (fUpdatePositions ||
e.VerticalTranslation ||
e.NewViewState.ViewportTop != e.OldViewState.ViewportTop ||
e.NewViewState.ViewportBottom != e.OldViewState.ViewportBottom)
{
UpdatePositions();
}
if (!_firstLayoutDone)
{
AddGuidelinesToAdornmentLayer();
_firstLayoutDone = true;
}
}
private static IList<Line> CreateGuidelines()
{
Brush lineBrush = new SolidColorBrush(GuidesSettingsManager.GuidelinesColor);
DoubleCollection dashArray = new DoubleCollection(new double[] { 1.0, 3.0 });
IList<Line> result = new List<Line>();
foreach (int column in GuidesSettingsManager.GetColumnOffsets())
{
Line line = new Line()
{
// Use the DataContext slot as a cookie to hold the column
DataContext = column,
Stroke = lineBrush,
StrokeThickness = _lineThickness,
StrokeDashArray = dashArray
};
result.Add(line);
}
return result;
}
void UpdatePositions()
{
foreach (Line line in _guidelines)
{
int column = (int)line.DataContext;
line.X2 = _baseIndentation + 0.5 + column * _columnWidth;
line.X1 = line.X2;
line.Y1 = _view.ViewportTop;
line.Y2 = _view.ViewportBottom;
}
}
void AddGuidelinesToAdornmentLayer()
{
// Grab a reference to the adornment layer that this adornment
// should be added to
// Must match exported name in ColumnGuideAdornmentTextViewCreationListener
IAdornmentLayer adornmentLayer =
_view.GetAdornmentLayer("ColumnGuideAdornment");
if (adornmentLayer == null)
return;
adornmentLayer.RemoveAllAdornments();
// Add the guidelines to the adornment layer and make them relative
// to the viewport
foreach (UIElement element in _guidelines)
adornmentLayer.AddAdornment(AdornmentPositioningBehavior.OwnerControlled,
null, null, element, null);
}
}
}
Instanzen dieser Klasse halten die zugeordnete IWpfTextView und eine Liste von Line Objekten, die in der Ansicht gezeichnet werden.
Der Konstruktor (der aufgerufen wird ColumnGuideAdornmentTextViewCreationListener , wenn Visual Studio neue Ansichten erstellt) erstellt die Spaltenführungsobjekte Line . Der Konstruktor fügt außerdem Handler für das SettingsChanged Ereignis (definiert in GuidesSettingsManager) und die Ansichtsereignisse LayoutChanged und Closed.
Das LayoutChanged Ereignis wird aufgrund verschiedener Arten von Änderungen in der Ansicht ausgelöst, einschließlich, wenn Visual Studio die Ansicht erstellt. Der OnViewLayoutChanged Handler ruft AddGuidelinesToAdornmentLayer die Ausführung auf. Der Code bestimmt OnViewLayoutChanged , ob Zeilenpositionen basierend auf Änderungen wie Änderungen des Schriftgrads, Ansichtsgitternetzlinien, horizontaler Bildlauf usw. aktualisiert werden müssen. Der Code in UpdatePositions führt dazu, dass Führungslinien zwischen Zeichen oder direkt nach der Textspalte zeichnen, die sich im angegebenen Zeichenoffset in der Textzeile befindet.
Wenn Die Einstellungen die SettingsChanged Funktion ändern, werden alle Line Objekte mit den neuen Einstellungen neu erstellt. Nach dem Festlegen der Zeilenpositionen entfernt der Code alle vorherigen Line Objekte aus der ColumnGuideAdornment Verzierungsebene und fügt die neuen hinzu.
Definieren der Befehle, Menüs und Menüplatzierung
Es kann viel geben, um Befehle und Menüs zu deklarieren, Gruppen von Befehlen oder Menüs in verschiedenen anderen Menüs zu platzieren und Befehlshandler zu verbinden. In dieser exemplarischen Vorgehensweise wird erläutert, wie Befehle in dieser Erweiterung funktionieren, aber ausführlichere Informationen finden Sie unter Erweitern von Menüs und Befehlen.
Einführung in den Code
Die Erweiterung "Spaltenführungslinien" zeigt das Deklarieren einer Gruppe von Befehlen, die zusammen gehören (Spalte hinzufügen, Spalte entfernen, Linienfarbe ändern) und diese Gruppe dann in einem Untermenü des Kontextmenüs des Editors zu platzieren. Die Erweiterung "Spaltenführungslinien" fügt auch die Befehle zum Menü "Standard Bearbeiten" hinzu, behält sie jedoch unsichtbar bei, die unten als allgemeines Muster behandelt werden.
Es gibt drei Teile der Befehlsimplementierung: ColumnGuideCommandsPackage.cs, ColumnGuideCommandsPackage.vsct und ColumnGuideCommands.cs. Der von den Vorlagen generierte Code fügt einen Befehl im Menü "Extras " ein, in dem ein Dialogfeld als Implementierung angezeigt wird. Sie können sich ansehen, wie dies in den DATEIEN ".vsct " und "ColumnGuideCommands.cs " implementiert wird, da sie einfach ist. Sie ersetzen den Code in diesen Dateien unten.
Der Paketcode enthält Deklarationen, die für Visual Studio erforderlich sind, um zu ermitteln, dass die Erweiterung Befehle bietet, und um zu ermitteln, wo die Befehle platziert werden sollen. Wenn das Paket initialisiert wird, instanziiert es die Implementierungsklasse der Befehle. Weitere Informationen zu Paketen zu Befehlen finden Sie unter Erweitern von Menüs und Befehlen.
Ein gängiges Befehlsmuster
Die Befehle in der Erweiterung "Spaltenführungslinien" sind ein Beispiel für ein sehr gängiges Muster in Visual Studio. Sie platzieren verwandte Befehle in einer Gruppe, und sie platzieren diese Gruppe in einem menü Standard, häufig mit "<CommandFlag>CommandWellOnly</CommandFlag>" festgelegt, um den Befehl unsichtbar zu machen. Das Platzieren von Befehlen in den Standard Menüs (z. B. "Bearbeiten") bietet ihnen schöne Namen (z. B. Edit.AddColumnGuide), die beim erneuten Zuweisen von Tastenbindungen in den Tools-Optionen hilfreich sind. Es ist auch hilfreich, den Abschluss beim Aufrufen von Befehlen aus dem Befehlsfenster zu erhalten.
Anschließend fügen Sie die Gruppe von Befehlen zu Kontextmenüs oder Untermenüs hinzu, in denen der Benutzer die Befehle verwenden soll. Visual Studio behandelt nur Standard Menüs als SichtbarkeitskennzeichnungCommandWellOnly. Wenn Sie dieselbe Gruppe von Befehlen in einem Kontextmenü oder Untermenü platzieren, sind die Befehle sichtbar.
Im Rahmen des allgemeinen Musters erstellt die Erweiterung "Spaltenführungslinien" eine zweite Gruppe, die ein einzelnes Untermenü enthält. Das Untermenü enthält wiederum die erste Gruppe mit den Vierspaltenführungsbefehlen. Die zweite Gruppe, die das Untermenü enthält, ist die wiederverwendbare Ressource, die Sie in verschiedenen Kontextmenüs platzieren, wodurch ein Untermenü in diese Kontextmenüs eingefügt wird.
Die VSCT-Datei
Die VSCT-Datei deklariert die Befehle und deren Position, zusammen mit Symbolen usw. Ersetzen Sie den Inhalt der VSCT-Datei durch den folgenden Code (siehe unten):
<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!-- This is the file that defines the actual layout and type of the commands.
It is divided in different sections (e.g. command definition, command
placement, ...), with each defining a specific set of properties.
See the comment before each section for more details about how to
use it. -->
<!-- The VSCT compiler (the tool that translates this file into the binary
format that VisualStudio will consume) has the ability to run a preprocessor
on the vsct file; this preprocessor is (usually) the C++ preprocessor, so
it is possible to define includes and macros with the same syntax used
in C++ files. Using this ability of the compiler here, we include some files
defining some of the constants that we will use inside the file. -->
<!--This is the file that defines the IDs for all the commands exposed by
VisualStudio. -->
<Extern href="stdidcmd.h"/>
<!--This header contains the command ids for the menus provided by the shell. -->
<Extern href="vsshlids.h"/>
<!--The Commands section is where commands, menus, and menu groups are defined.
This section uses a Guid to identify the package that provides the command
defined inside it. -->
<Commands package="guidColumnGuideCommandsPkg">
<!-- Inside this section we have different sub-sections: one for the menus, another
for the menu groups, one for the buttons (the actual commands), one for the combos
and the last one for the bitmaps used. Each element is identified by a command id
that is a unique pair of guid and numeric identifier; the guid part of the identifier
is usually called "command set" and is used to group different command inside a
logically related group; your package should define its own command set in order to
avoid collisions with command ids defined by other packages. -->
<!-- In this section you can define new menu groups. A menu group is a container for
other menus or buttons (commands); from a visual point of view you can see the
group as the part of a menu contained between two lines. The parent of a group
must be a menu. -->
<Groups>
<!-- The main group is parented to the edit menu. All the buttons within the group
have the "CommandWellOnly" flag, so they're actually invisible, but it means
they get canonical names that begin with "Edit". Using placements, the group
is also placed in the GuidesSubMenu group. -->
<!-- The priority 0xB801 is chosen so it goes just after
IDG_VS_EDIT_COMMANDWELL -->
<Group guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup"
priority="0xB801">
<Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_EDIT" />
</Group>
<!-- Group for holding the "Guidelines" sub-menu anchor (the item on the menu that
drops the sub menu). The group is parented to
the context menu for code windows. That takes care of most editors, but it's
also placed in a couple of other windows using Placements -->
<Group guid="guidColumnGuidesCommandSet" id="GuidesContextMenuGroup"
priority="0x0600">
<Parent guid="guidSHLMainMenu" id="IDM_VS_CTXT_CODEWIN" />
</Group>
</Groups>
<Menus>
<Menu guid="guidColumnGuidesCommandSet" id="GuidesSubMenu" priority="0x1000"
type="Menu">
<Parent guid="guidColumnGuidesCommandSet" id="GuidesContextMenuGroup" />
<Strings>
<ButtonText>&Column Guides</ButtonText>
</Strings>
</Menu>
</Menus>
<!--Buttons section. -->
<!--This section defines the elements the user can interact with, like a menu command or a button
or combo box in a toolbar. -->
<Buttons>
<!--To define a menu group you have to specify its ID, the parent menu and its
display priority.
The command is visible and enabled by default. If you need to change the
visibility, status, etc, you can use the CommandFlag node.
You can add more than one CommandFlag node e.g.:
<CommandFlag>DefaultInvisible</CommandFlag>
<CommandFlag>DynamicVisibility</CommandFlag>
If you do not want an image next to your command, remove the Icon node or
set it to <Icon guid="guidOfficeIcon" id="msotcidNoIcon" /> -->
<Button guid="guidColumnGuidesCommandSet" id="cmdidAddColumnGuide"
priority="0x0100" type="Button">
<Parent guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup" />
<Icon guid="guidImages" id="bmpPicAddGuide" />
<CommandFlag>CommandWellOnly</CommandFlag>
<CommandFlag>AllowParams</CommandFlag>
<Strings>
<ButtonText>&Add Column Guide</ButtonText>
</Strings>
</Button>
<Button guid="guidColumnGuidesCommandSet" id="cmdidRemoveColumnGuide"
priority="0x0101" type="Button">
<Parent guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup" />
<Icon guid="guidImages" id="bmpPicRemoveGuide" />
<CommandFlag>CommandWellOnly</CommandFlag>
<CommandFlag>AllowParams</CommandFlag>
<Strings>
<ButtonText>&Remove Column Guide</ButtonText>
</Strings>
</Button>
<Button guid="guidColumnGuidesCommandSet" id="cmdidChooseGuideColor"
priority="0x0103" type="Button">
<Parent guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup" />
<Icon guid="guidImages" id="bmpPicChooseColor" />
<CommandFlag>CommandWellOnly</CommandFlag>
<Strings>
<ButtonText>Column Guide &Color...</ButtonText>
</Strings>
</Button>
<Button guid="guidColumnGuidesCommandSet" id="cmdidRemoveAllColumnGuides"
priority="0x0102" type="Button">
<Parent guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup" />
<CommandFlag>CommandWellOnly</CommandFlag>
<Strings>
<ButtonText>Remove A&ll Columns</ButtonText>
</Strings>
</Button>
</Buttons>
<!--The bitmaps section is used to define the bitmaps that are used for the
commands.-->
<Bitmaps>
<!-- The bitmap id is defined in a way that is a little bit different from the
others:
the declaration starts with a guid for the bitmap strip, then there is the
resource id of the bitmap strip containing the bitmaps and then there are
the numeric ids of the elements used inside a button definition. An important
aspect of this declaration is that the element id
must be the actual index (1-based) of the bitmap inside the bitmap strip. -->
<Bitmap guid="guidImages" href="Resources\ColumnGuideCommands.png"
usedList="bmpPicAddGuide, bmpPicRemoveGuide, bmpPicChooseColor" />
</Bitmaps>
</Commands>
<CommandPlacements>
<!-- Define secondary placements for our groups -->
<!-- Place the group containing the three commands in the sub-menu -->
<CommandPlacement guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup"
priority="0x0100">
<Parent guid="guidColumnGuidesCommandSet" id="GuidesSubMenu" />
</CommandPlacement>
<!-- The HTML editor context menu, for some reason, redefines its own groups
so we need to place a copy of our context menu there too. -->
<CommandPlacement guid="guidColumnGuidesCommandSet" id="GuidesContextMenuGroup"
priority="0x1001">
<Parent guid="CMDSETID_HtmEdGrp" id="IDMX_HTM_SOURCE_HTML" />
</CommandPlacement>
<!-- The HTML context menu in Dev12 changed. -->
<CommandPlacement guid="guidColumnGuidesCommandSet" id="GuidesContextMenuGroup"
priority="0x1001">
<Parent guid="CMDSETID_HtmEdGrp_Dev12" id="IDMX_HTM_SOURCE_HTML_Dev12" />
</CommandPlacement>
<!-- Similarly for Script -->
<CommandPlacement guid="guidColumnGuidesCommandSet" id="GuidesContextMenuGroup"
priority="0x1001">
<Parent guid="CMDSETID_HtmEdGrp" id="IDMX_HTM_SOURCE_SCRIPT" />
</CommandPlacement>
<!-- Similarly for ASPX -->
<CommandPlacement guid="guidColumnGuidesCommandSet" id="GuidesContextMenuGroup"
priority="0x1001">
<Parent guid="CMDSETID_HtmEdGrp" id="IDMX_HTM_SOURCE_ASPX" />
</CommandPlacement>
<!-- Similarly for the XAML editor context menu -->
<CommandPlacement guid="guidColumnGuidesCommandSet" id="GuidesContextMenuGroup"
priority="0x0600">
<Parent guid="guidXamlUiCmds" id="IDM_XAML_EDITOR" />
</CommandPlacement>
</CommandPlacements>
<!-- This defines the identifiers and their values used above to index resources
and specify commands. -->
<Symbols>
<!-- This is the package guid. -->
<GuidSymbol name="guidColumnGuideCommandsPkg"
value="{e914e5de-0851-4904-b361-1a3a9d449704}" />
<!-- This is the guid used to group the menu commands together -->
<GuidSymbol name="guidColumnGuidesCommandSet"
value="{c2bc0047-8bfa-4e5a-b5dc-45af8c274d8e}">
<IDSymbol name="GuidesContextMenuGroup" value="0x1020" />
<IDSymbol name="GuidesMenuItemsGroup" value="0x1021" />
<IDSymbol name="GuidesSubMenu" value="0x1022" />
<IDSymbol name="cmdidAddColumnGuide" value="0x0100" />
<IDSymbol name="cmdidRemoveColumnGuide" value="0x0101" />
<IDSymbol name="cmdidChooseGuideColor" value="0x0102" />
<IDSymbol name="cmdidRemoveAllColumnGuides" value="0x0103" />
</GuidSymbol>
<GuidSymbol name="guidImages" value="{2C99F852-587C-43AF-AA2D-F605DE2E46EF}">
<IDSymbol name="bmpPicAddGuide" value="1" />
<IDSymbol name="bmpPicRemoveGuide" value="2" />
<IDSymbol name="bmpPicChooseColor" value="3" />
</GuidSymbol>
<GuidSymbol name="CMDSETID_HtmEdGrp_Dev12"
value="{78F03954-2FB8-4087-8CE7-59D71710B3BB}">
<IDSymbol name="IDMX_HTM_SOURCE_HTML_Dev12" value="0x1" />
</GuidSymbol>
<GuidSymbol name="CMDSETID_HtmEdGrp" value="{d7e8c5e1-bdb8-11d0-9c88-0000f8040a53}">
<IDSymbol name="IDMX_HTM_SOURCE_HTML" value="0x33" />
<IDSymbol name="IDMX_HTM_SOURCE_SCRIPT" value="0x34" />
<IDSymbol name="IDMX_HTM_SOURCE_ASPX" value="0x35" />
</GuidSymbol>
<GuidSymbol name="guidXamlUiCmds" value="{4c87b692-1202-46aa-b64c-ef01faec53da}">
<IDSymbol name="IDM_XAML_EDITOR" value="0x103" />
</GuidSymbol>
</Symbols>
</CommandTable>
GUIDS. Damit Visual Studio Ihre Befehlshandler finden und aufrufen kann, müssen Sie sicherstellen, dass die in der Datei ColumnGuideCommandsPackage.cs deklarierte Paket-GUID (generiert aus der Projektelementvorlage) mit der paket-GUID übereinstimmt, die in der VSCT-Datei deklariert ist (kopiert von oben). Wenn Sie diesen Beispielcode erneut verwenden, sollten Sie sicherstellen, dass Sie über eine andere GUID verfügen, sodass Sie keinen Konflikt mit anderen Personen haben, die diesen Code kopiert haben.
Suchen Sie diese Zeile in ColumnGuideCommandsPackage.cs , und kopieren Sie die GUID aus den Anführungszeichen:
public const string PackageGuidString = "ef726849-5447-4f73-8de5-01b9e930f7cd";
Fügen Sie dann die GUID in die VSCT-Datei ein, sodass Sie die folgende Zeile in Ihren Symbols Deklarationen haben:
<GuidSymbol name="guidColumnGuideCommandsPkg"
value="{ef726849-5447-4f73-8de5-01b9e930f7cd}" />
Die GUIDs für den Befehlssatz und die Bitmapbilddatei sollten auch für Ihre Erweiterungen eindeutig sein:
<GuidSymbol name="guidColumnGuidesCommandSet"
value="{c2bc0047-8bfa-4e5a-b5dc-45af8c274d8e}">
<GuidSymbol name="guidImages" value="{2C99F852-587C-43AF-AA2D-F605DE2E46EF}">
In dieser exemplarischen Vorgehensweise müssen Sie jedoch die Befehlssatz- und Bitmapbild-GUIDs nicht ändern, um den Code zu verwenden. Die BEFEHLSsatz-GUID muss mit der Deklaration in der Datei ColumnGuideCommands.cs übereinstimmen, aber Sie ersetzen auch den Inhalt dieser Datei. Daher stimmen die GUIDs überein.
Andere GUIDs in der VSCT-Datei identifizieren bereits vorhandene Menüs, denen die Spaltenführungsbefehle hinzugefügt werden, sodass sie nie geändert werden.
Dateiabschnitte. Das VSCT verfügt über drei äußere Abschnitte: Befehle, Platzierungen und Symbole. Der Abschnitt "Befehle" definiert Befehlsgruppen, Menüs, Schaltflächen oder Menüelemente sowie Bitmaps für Symbole. Im Abschnitt "Platzierungen" wird deklariert, wo Gruppen menüs oder zusätzliche Platzierungen auf bereits vorhandenen Menüs platzieren. Der Abschnitt "Symbole" deklariert Bezeichner, die an anderer Stelle in der VSCT-Datei verwendet werden, wodurch der VSCT-Code besser lesbar ist als GUIDs und Hexadenznummern überall.
Befehlsabschnitt, Gruppendefinitionen. Der Abschnitt "Befehle" definiert zuerst Befehlsgruppen. Gruppen von Befehlen sind Befehle, die in Menüs mit leichten grauen Linien angezeigt werden, die die Gruppen trennen. Eine Gruppe kann auch ein gesamtes Untermenü ausfüllen, wie in diesem Beispiel, und in diesem Fall werden die grauen Trennlinien nicht angezeigt. Die VSCT-Dateien deklarieren zwei Gruppen, das GuidesMenuItemsGroup übergeordnete Element zum IDM_VS_MENU_EDIT (Menü Standard Bearbeiten) und das GuidesContextMenuGroup übergeordnete Element IDM_VS_CTXT_CODEWIN (kontextmenü des Code-Editors).
Die zweite Gruppendeklaration hat eine 0x0600 Priorität:
<Group guid="guidColumnGuidesCommandSet" id="GuidesContextMenuGroup"
priority="0x0600">
Die Idee besteht darin, das Untermenü der Spaltenführungslinien am Ende eines kontextmenüs zu platzieren, dem Sie die Untermenügruppe hinzufügen. Aber Sie sollten nicht davon ausgehen, dass Sie das Beste wissen und erzwingen, dass das Untermenü immer mit einer Priorität von 0xFFFF. Sie müssen mit der Zahl experimentieren, um zu sehen, wo sich Ihr Untermenü in den Kontextmenüs befindet, wo Sie es platzieren. In diesem Fall ist hoch genug, 0x0600 um es am Ende der Menüs so weit wie möglich zu platzieren, aber es lässt Platz für eine andere Person, ihre Erweiterung so zu entwerfen, dass sie niedriger als die Spaltenführungserweiterung ist, wenn dies wünschenswert ist.
Befehlsabschnitt, Menüdefinition. Als Nächstes definiert der Befehlsabschnitt das Untermenü GuidesSubMenu, das mit der GuidesContextMenuGroupKlammer versehen ist. Dies GuidesContextMenuGroup ist die Gruppe, die Sie allen relevanten Kontextmenüs hinzufügen. Im Abschnitt "Platzierungen" platziert der Code die Gruppe mit den Vierspaltenführungsbefehlen in diesem Untermenü.
Befehlsabschnitt, Schaltflächendefinitionen. Der Befehlsabschnitt definiert dann die Menüelemente oder Schaltflächen, die die Vierspaltenführungsbefehle sind. CommandWellOnly, oben erläutert, bedeutet, dass die Befehle unsichtbar sind, wenn sie in einem Standard Menü platziert werden. Zwei der Deklarationen der Menüelementschaltfläche (Führungslinie hinzufügen und Führungslinie entfernen) weisen ebenfalls eine AllowParams Kennzeichnung auf:
<CommandFlag>AllowParams</CommandFlag>
Dieses Kennzeichen ermöglicht zusammen mit Standard Menüplatzierung den Befehl zum Empfangen von Argumenten, wenn Visual Studio den Befehlshandler aufruft. Wenn der Benutzer den Befehl über das Befehlsfenster ausführt, wird das Argument an den Befehlshandler in den Ereignisargumenten übergeben.
Befehlsabschnitte, Bitmapsdefinitionen. Schließlich deklariert der Abschnitt "Befehle" die Bitmaps oder Symbole, die für die Befehle verwendet werden. Dieser Abschnitt ist eine einfache Deklaration, die die Projektressource identifiziert und Indizes verwendeter Symbole auflistet. Im Abschnitt "Symbole" der VSCT-Datei werden die Werte der als Indizes verwendeten Bezeichner deklariert. In dieser exemplarischen Vorgehensweise wird die Bitmapleiste verwendet, die mit der dem Projekt hinzugefügten benutzerdefinierten Befehlselementvorlage bereitgestellt wird.
Abschnitt "Platzierungen". Nach dem Befehlsabschnitt handelt es sich um den Abschnitt "Platzierungen". Im ersten wird die oben beschriebene erste Gruppe hinzugefügt, in der die vierspaltigen Führungsbefehle im Untermenü enthalten sind, in dem die Befehle angezeigt werden:
<CommandPlacement guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup"
priority="0x0100">
<Parent guid="guidColumnGuidesCommandSet" id="GuidesSubMenu" />
</CommandPlacement>
Alle anderen Platzierungen fügen die (enthält die GuidesContextMenuGroupGuidesSubMenu) anderen Editor-Kontextmenüs hinzu. Als der Code den GuidesContextMenuGroupCode deklariert hat, wurde er dem Kontextmenü des Code-Editors übergeordnet. Aus diesem Grund wird keine Platzierung für das Kontextmenü des Code-Editors angezeigt.
Abschnitt "Symbole". Wie oben erwähnt, deklariert der Abschnitt "Symbole" Bezeichner, die an anderer Stelle in der VSCT-Datei verwendet werden, wodurch der VSCT-Code besser lesbar ist als GUIDs und Hexnummern überall. Die wichtigen Punkte in diesem Abschnitt sind, dass die Paket-GUID der Deklaration in der Paketklasse zustimmen muss. Außerdem muss die GUID des Befehlssatzes mit der Deklaration in der Befehlsimplementierungsklasse übereinstimmen.
Implementieren der Befehle
Die Datei ColumnGuideCommands.cs implementiert die Befehle und bindet die Handler an. Wenn Visual Studio das Paket lädt und initialisiert, ruft das Paket wiederum die Implementierungsklasse der Befehle auf Initialize . Die Initialisierung der Befehle instanziiert einfach die Klasse, und der Konstruktor bindet alle Befehlshandler an.
Ersetzen Sie den Inhalt der Datei ColumnGuideCommands.cs durch den folgenden Code (siehe unten):
using System;
using System.ComponentModel.Design;
using System.Globalization;
using Microsoft.VisualStudio.Shell;
using Microsoft.VisualStudio.Shell.Interop;
using Microsoft.VisualStudio.TextManager.Interop;
using Microsoft.VisualStudio.Text.Editor;
using Microsoft.VisualStudio;
namespace ColumnGuides
{
/// <summary>
/// Command handler
/// </summary>
internal sealed class ColumnGuideCommands
{
const int cmdidAddColumnGuide = 0x0100;
const int cmdidRemoveColumnGuide = 0x0101;
const int cmdidChooseGuideColor = 0x0102;
const int cmdidRemoveAllColumnGuides = 0x0103;
/// <summary>
/// Command menu group (command set GUID).
/// </summary>
static readonly Guid CommandSet =
new Guid("c2bc0047-8bfa-4e5a-b5dc-45af8c274d8e");
/// <summary>
/// VS Package that provides this command, not null.
/// </summary>
private readonly Package package;
OleMenuCommand _addGuidelineCommand;
OleMenuCommand _removeGuidelineCommand;
/// <summary>
/// Initializes the singleton instance of the command.
/// </summary>
/// <param name="package">Owner package, not null.</param>
public static void Initialize(Package package)
{
Instance = new ColumnGuideCommands(package);
}
/// <summary>
/// Gets the instance of the command.
/// </summary>
public static ColumnGuideCommands Instance
{
get;
private set;
}
/// <summary>
/// Initializes a new instance of the <see cref="ColumnGuideCommands"/> class.
/// Adds our command handlers for menu (commands must exist in the command
/// table file)
/// </summary>
/// <param name="package">Owner package, not null.</param>
private ColumnGuideCommands(Package package)
{
if (package == null)
{
throw new ArgumentNullException("package");
}
this.package = package;
// Add our command handlers for menu (commands must exist in the .vsct file)
OleMenuCommandService commandService =
this.ServiceProvider.GetService(typeof(IMenuCommandService))
as OleMenuCommandService;
if (commandService != null)
{
// Add guide
_addGuidelineCommand =
new OleMenuCommand(AddColumnGuideExecuted, null,
AddColumnGuideBeforeQueryStatus,
new CommandID(ColumnGuideCommands.CommandSet,
cmdidAddColumnGuide));
_addGuidelineCommand.ParametersDescription = "<column>";
commandService.AddCommand(_addGuidelineCommand);
// Remove guide
_removeGuidelineCommand =
new OleMenuCommand(RemoveColumnGuideExecuted, null,
RemoveColumnGuideBeforeQueryStatus,
new CommandID(ColumnGuideCommands.CommandSet,
cmdidRemoveColumnGuide));
_removeGuidelineCommand.ParametersDescription = "<column>";
commandService.AddCommand(_removeGuidelineCommand);
// Choose color
commandService.AddCommand(
new MenuCommand(ChooseGuideColorExecuted,
new CommandID(ColumnGuideCommands.CommandSet,
cmdidChooseGuideColor)));
// Remove all
commandService.AddCommand(
new MenuCommand(RemoveAllGuidelinesExecuted,
new CommandID(ColumnGuideCommands.CommandSet,
cmdidRemoveAllColumnGuides)));
}
}
/// <summary>
/// Gets the service provider from the owner package.
/// </summary>
private IServiceProvider ServiceProvider
{
get
{
return this.package;
}
}
private void AddColumnGuideBeforeQueryStatus(object sender, EventArgs e)
{
int currentColumn = GetCurrentEditorColumn();
_addGuidelineCommand.Enabled =
GuidesSettingsManager.CanAddGuideline(currentColumn);
}
private void RemoveColumnGuideBeforeQueryStatus(object sender, EventArgs e)
{
int currentColumn = GetCurrentEditorColumn();
_removeGuidelineCommand.Enabled =
GuidesSettingsManager.CanRemoveGuideline(currentColumn);
}
private int GetCurrentEditorColumn()
{
IVsTextView view = GetActiveTextView();
if (view == null)
{
return -1;
}
try
{
IWpfTextView textView = GetTextViewFromVsTextView(view);
int column = GetCaretColumn(textView);
// Note: GetCaretColumn returns 0-based positions. Guidelines are 1-based
// positions.
// However, do not subtract one here since the caret is positioned to the
// left of
// the given column and the guidelines are positioned to the right. We
// want the
// guideline to line up with the current caret position. e.g. When the
// caret is
// at position 1 (zero-based), the status bar says column 2. We want to
// add a
// guideline for column 1 since that will place the guideline where the
// caret is.
return column;
}
catch (InvalidOperationException)
{
return -1;
}
}
/// <summary>
/// Find the active text view (if any) in the active document.
/// </summary>
/// <returns>The IVsTextView of the active view, or null if there is no active
/// document or the
/// active view in the active document is not a text view.</returns>
private IVsTextView GetActiveTextView()
{
IVsMonitorSelection selection =
this.ServiceProvider.GetService(typeof(IVsMonitorSelection))
as IVsMonitorSelection;
object frameObj = null;
ErrorHandler.ThrowOnFailure(
selection.GetCurrentElementValue(
(uint)VSConstants.VSSELELEMID.SEID_DocumentFrame, out frameObj));
IVsWindowFrame frame = frameObj as IVsWindowFrame;
if (frame == null)
{
return null;
}
return GetActiveView(frame);
}
private static IVsTextView GetActiveView(IVsWindowFrame windowFrame)
{
if (windowFrame == null)
{
throw new ArgumentException("windowFrame");
}
object pvar;
ErrorHandler.ThrowOnFailure(
windowFrame.GetProperty((int)__VSFPROPID.VSFPROPID_DocView, out pvar));
IVsTextView textView = pvar as IVsTextView;
if (textView == null)
{
IVsCodeWindow codeWin = pvar as IVsCodeWindow;
if (codeWin != null)
{
ErrorHandler.ThrowOnFailure(codeWin.GetLastActiveView(out textView));
}
}
return textView;
}
private static IWpfTextView GetTextViewFromVsTextView(IVsTextView view)
{
if (view == null)
{
throw new ArgumentNullException("view");
}
IVsUserData userData = view as IVsUserData;
if (userData == null)
{
throw new InvalidOperationException();
}
object objTextViewHost;
if (VSConstants.S_OK
!= userData.GetData(Microsoft.VisualStudio
.Editor
.DefGuidList.guidIWpfTextViewHost,
out objTextViewHost))
{
throw new InvalidOperationException();
}
IWpfTextViewHost textViewHost = objTextViewHost as IWpfTextViewHost;
if (textViewHost == null)
{
throw new InvalidOperationException();
}
return textViewHost.TextView;
}
/// <summary>
/// Given an IWpfTextView, find the position of the caret and report its column
/// number. The column number is 0-based
/// </summary>
/// <param name="textView">The text view containing the caret</param>
/// <returns>The column number of the caret's position. When the caret is at the
/// leftmost column, the return value is zero.</returns>
private static int GetCaretColumn(IWpfTextView textView)
{
// This is the code the editor uses to populate the status bar.
Microsoft.VisualStudio.Text.Formatting.ITextViewLine caretViewLine =
textView.Caret.ContainingTextViewLine;
double columnWidth = textView.FormattedLineSource.ColumnWidth;
return (int)(Math.Round((textView.Caret.Left - caretViewLine.Left)
/ columnWidth));
}
/// <summary>
/// Determine the applicable column number for an add or remove command.
/// The column is parsed from command arguments, if present. Otherwise
/// the current position of the caret is used to determine the column.
/// </summary>
/// <param name="e">Event args passed to the command handler.</param>
/// <returns>The column number. May be negative to indicate the column number is
/// unavailable.</returns>
/// <exception cref="ArgumentException">The column number parsed from event args
/// was not a valid integer.</exception>
private int GetApplicableColumn(EventArgs e)
{
var inValue = ((OleMenuCmdEventArgs)e).InValue as string;
if (!string.IsNullOrEmpty(inValue))
{
int column;
if (!int.TryParse(inValue, out column) || column < 0)
throw new ArgumentException("Invalid column");
return column;
}
return GetCurrentEditorColumn();
}
/// <summary>
/// This function is the callback used to execute a command when a menu item
/// is clicked. See the Initialize method to see how the menu item is associated
/// to this function using the OleMenuCommandService service and the MenuCommand
/// class.
/// </summary>
private void AddColumnGuideExecuted(object sender, EventArgs e)
{
int column = GetApplicableColumn(e);
if (column >= 0)
{
GuidesSettingsManager.AddGuideline(column);
}
}
private void RemoveColumnGuideExecuted(object sender, EventArgs e)
{
int column = GetApplicableColumn(e);
if (column >= 0)
{
GuidesSettingsManager.RemoveGuideline(column);
}
}
private void RemoveAllGuidelinesExecuted(object sender, EventArgs e)
{
GuidesSettingsManager.RemoveAllGuidelines();
}
private void ChooseGuideColorExecuted(object sender, EventArgs e)
{
System.Windows.Media.Color color = GuidesSettingsManager.GuidelinesColor;
using (System.Windows.Forms.ColorDialog picker =
new System.Windows.Forms.ColorDialog())
{
picker.Color = System.Drawing.Color.FromArgb(255, color.R, color.G,
color.B);
if (picker.ShowDialog() == System.Windows.Forms.DialogResult.OK)
{
GuidesSettingsManager.GuidelinesColor =
System.Windows.Media.Color.FromRgb(picker.Color.R,
picker.Color.G,
picker.Color.B);
}
}
}
}
}
Korrigieren von Verweisen. An diesem Punkt fehlt ein Verweis. Drücken Sie im Projektmappen-Explorer die rechte Zeigerschaltfläche auf dem Knoten "Verweise". Wählen Sie den Befehl "... hinzufügen" aus. Das Dialogfeld "Verweis hinzufügen" enthält ein Suchfeld in der oberen rechten Ecke. Geben Sie "editor" ein (ohne doppelte Anführungszeichen). Wählen Sie das Element "Microsoft.VisualStudio.Editor " aus (Sie müssen das Kontrollkästchen links neben dem Element aktivieren, nicht nur das Element auswählen), und wählen Sie "OK " aus, um den Verweis hinzuzufügen.
Initialisierung. Wenn die Paketklasse initialisiert wird, wird die Implementierungsklasse der Befehle aufgerufen Initialize . Die ColumnGuideCommands Initialisierung instanziiert die Klasse und speichert die Klasseninstanz und den Paketverweis in Klassenmbern.
Sehen wir uns einen der Befehlshandler-Hooks aus dem Klassenkonstruktor an:
_addGuidelineCommand =
new OleMenuCommand(AddColumnGuideExecuted, null,
AddColumnGuideBeforeQueryStatus,
new CommandID(ColumnGuideCommands.CommandSet,
cmdidAddColumnGuide));
Sie erstellen eine OleMenuCommand. Visual Studio verwendet das Microsoft Office-Befehlssystem. Bei der Instanziierung einer OleMenuCommand Instanziierung handelt es sich um die Funktion, die den Befehl implementiert (AddColumnGuideExecuted), die Funktion, die aufgerufen werden soll, wenn Visual Studio ein Menü mit dem Befehl (AddColumnGuideBeforeQueryStatus) und der Befehls-ID anzeigt. Visual Studio ruft die Abfragestatusfunktion auf, bevor ein Befehl in einem Menü angezeigt wird, damit sich der Befehl für eine bestimmte Anzeige des Menüs unsichtbar oder abgeblendet machen kann (z. B. Deaktivieren von "Kopieren ", wenn keine Auswahl vorhanden ist), ändern Sie das Symbol oder sogar den Namen (z. B. aus "Etwas hinzufügen", um etwas zu entfernen) Und so weiter. Die Befehls-ID muss mit einer Befehls-ID übereinstimmen, die in der VSCT-Datei deklariert ist. Die Zeichenfolgen für den Befehlssatz und die Spaltenführungslinien müssen zwischen der VSCT-Datei und dem ColumnGuideCommands.cs übereinstimmen.
Die folgende Zeile bietet Unterstützung, wenn Benutzer den Befehl über das Befehlsfenster aufrufen (siehe unten):
_addGuidelineCommand.ParametersDescription = "<column>";
Abfragestatus. Die Abfragestatusfunktionen AddColumnGuideBeforeQueryStatus und RemoveColumnGuideBeforeQueryStatus überprüfen einige Einstellungen (z. B. maximale Anzahl von Führungslinien oder max. Spalte) oder wenn eine Spaltenführung entfernt werden soll. Sie aktivieren die Befehle, wenn die Bedingungen richtig sind. Abfragestatusfunktionen müssen effizient sein, da sie jedes Mal ausgeführt werden, wenn Visual Studio ein Menü und für jeden Befehl im Menü anzeigt.
AddColumnGuideExecuted-Funktion. Der interessante Teil des Hinzufügens eines Leitfadens ist das Ermitteln der aktuellen Editoransicht und des Caret-Speicherorts. Zuerst ruft diese Funktion auf GetApplicableColumn, die überprüft, ob ein vom Benutzer bereitgestelltes Argument in den Ereignisargumenten des Befehlshandlers vorhanden ist, und wenn keines vorhanden ist, überprüft die Funktion die Ansicht des Editors:
private int GetApplicableColumn(EventArgs e)
{
var inValue = ((OleMenuCmdEventArgs)e).InValue as string;
if (!string.IsNullOrEmpty(inValue))
{
int column;
if (!int.TryParse(inValue, out column) || column < 0)
throw new ArgumentException("Invalid column");
return column;
}
return GetCurrentEditorColumn();
}
GetCurrentEditorColumn muss ein bisschen graben, um eine IWpfTextView Ansicht des Codes zu erhalten. Wenn Sie die Ablaufverfolgung durch GetActiveTextView, GetActiveViewund GetTextViewFromVsTextView, können Sie sehen, wie dies zu tun ist. Der folgende Code ist der relevante Code abstrahiert, beginnend mit der aktuellen Auswahl, anschließend abrufen des Auswahlframes und anschließendes Abrufen der DocView des Frames als Einfüge IVsTextViewund anschließendes Abrufen einer IVsUserData aus dem IVsTextView- und anschließenden Abrufen eines Ansichtshosts und schließlich der IWpfTextView:
IVsMonitorSelection selection =
this.ServiceProvider.GetService(typeof(IVsMonitorSelection))
as IVsMonitorSelection;
object frameObj = null;
ErrorHandler.ThrowOnFailure(selection.GetCurrentElementValue(
(uint)VSConstants.VSSELELEMID.SEID_DocumentFrame,
out frameObj));
IVsWindowFrame frame = frameObj as IVsWindowFrame;
if (frame == null)
<<do nothing>>;
...
object pvar;
ErrorHandler.ThrowOnFailure(frame.GetProperty((int)__VSFPROPID.VSFPROPID_DocView,
out pvar));
IVsTextView textView = pvar as IVsTextView;
if (textView == null)
{
IVsCodeWindow codeWin = pvar as IVsCodeWindow;
if (codeWin != null)
{
ErrorHandler.ThrowOnFailure(codeWin.GetLastActiveView(out textView));
}
}
...
if (textView == null)
<<do nothing>>
IVsUserData userData = textView as IVsUserData;
if (userData == null)
<<do nothing>>
object objTextViewHost;
if (VSConstants.S_OK
!= userData.GetData(Microsoft.VisualStudio.Editor.DefGuidList
.guidIWpfTextViewHost,
out objTextViewHost))
{
<<do nothing>>
}
IWpfTextViewHost textViewHost = objTextViewHost as IWpfTextViewHost;
if (textViewHost == null)
<<do nothing>>
IWpfTextView textView = textViewHost.TextView;
Sobald Sie über eine IWpfTextView verfügen, können Sie die Spalte abrufen, in der sich das Caret befindet:
private static int GetCaretColumn(IWpfTextView textView)
{
// This is the code the editor uses to populate the status bar.
Microsoft.VisualStudio.Text.Formatting.ITextViewLine caretViewLine =
textView.Caret.ContainingTextViewLine;
double columnWidth = textView.FormattedLineSource.ColumnWidth;
return (int)(Math.Round((textView.Caret.Left - caretViewLine.Left)
/ columnWidth));
}
Mit der aktuellen Spalte, auf die der Benutzer geklickt hat, ruft der Code lediglich den Einstellungs-Manager auf, um die Spalte hinzuzufügen oder zu entfernen. Der Einstellungs-Manager löst das Ereignis aus, auf das alle ColumnGuideAdornment Objekte lauschen. Wenn das Ereignis ausgelöst wird, aktualisieren diese Objekte ihre zugeordneten Textansichten mit neuen Spaltenführungseinstellungen.
Aufrufen des Befehls aus dem Befehlsfenster
Das Beispiel für Spaltenführungslinien ermöglicht Benutzern das Aufrufen von zwei Befehlen aus dem Befehlsfenster als Form der Erweiterbarkeit. Wenn Sie die Ansicht | verwenden Andere Windows | Befehl "Befehlsfenster " wird das Befehlsfenster angezeigt. Sie können mit dem Befehlsfenster interagieren, indem Sie "bearbeiten" eingeben und mit dem Abschluss des Befehlsnamens und dem Angeben des Arguments 120 das folgende Ergebnis haben:
> Edit.AddColumnGuide 120
>
Die Teile des Beispiels, das dieses Verhalten aktivieren, befinden sich in den VSCT-Dateideklarationen , dem ColumnGuideCommands Klassenkonstruktor, wenn er Befehlshandler anbindet, und die Befehlshandlerimplementierungen, die Ereignisargumente überprüfen.
Sie haben "<CommandFlag>CommandWellOnly</CommandFlag>" in der VSCT-Datei sowie Platzierungen im Menü "Bearbeiten Standard" gesehen, obwohl die Befehle nicht in der Benutzeroberfläche des Menüs "Bearbeiten" angezeigt werden. Wenn sie im Menü "Standard Bearbeiten" angezeigt werden, erhalten Sie Namen wie "Edit.AddColumnGuide". Die Befehlsgruppendeklaration, die die vier Befehle enthält, platziert die Gruppe direkt im Menü "Bearbeiten ":
<Group guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup"
priority="0xB801">
<Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_EDIT" />
</Group>
Der Abschnitt "SchaltflächenCommandWellOnly" hat die Befehle später deklariert, um sie im menü Standard unsichtbar zu halten und mit AllowParams:
<Button guid="guidColumnGuidesCommandSet" id="cmdidAddColumnGuide"
priority="0x0100" type="Button">
<Parent guid="guidColumnGuidesCommandSet" id="GuidesMenuItemsGroup" />
<Icon guid="guidImages" id="bmpPicAddGuide" />
<CommandFlag>CommandWellOnly</CommandFlag>
<CommandFlag>AllowParams</CommandFlag>
Sie haben gesehen, dass der Befehlshandler code im ColumnGuideCommands Klassenkonstruktor eine Beschreibung des zulässigen Parameters bereitgestellt hat:
_addGuidelineCommand.ParametersDescription = "<column>";
Sie haben die GetApplicableColumn Funktionsüberprüfung auf OleMenuCmdEventArgs einen Wert gesehen, bevor Sie die Ansicht des Editors auf eine aktuelle Spalte überprüfen:
private int GetApplicableColumn(EventArgs e)
{
var inValue = ((OleMenuCmdEventArgs)e).InValue as string;
if (!string.IsNullOrEmpty(inValue))
{
int column;
if (!int.TryParse(inValue, out column) || column < 0)
throw new ArgumentException("Invalid column");
return column;
}
Probieren Sie Ihre Erweiterung aus
Sie können nun F5 drücken, um die Erweiterung "Spaltenführungslinien" auszuführen. Öffnen Sie eine Textdatei, und verwenden Sie das Kontextmenü des Editors, um Führungslinien hinzuzufügen, sie zu entfernen und ihre Farbe zu ändern. Klicken Sie auf den Text (nicht leerzeichen, die das Ende der Zeile übergeben haben), um eine Spaltenführung hinzuzufügen, oder der Editor fügt ihn der letzten Spalte in der Zeile hinzu. Wenn Sie das Befehlsfenster verwenden und die Befehle mit einem Argument aufrufen, können Sie überall Spaltenführungslinien hinzufügen.
Wenn Sie unterschiedliche Befehlsplatzierungen ausprobieren, Namen ändern, Symbole ändern usw. Haben Sie Probleme mit Visual Studio mit dem neuesten Code in Menüs, können Sie die experimentelle Struktur zurücksetzen, in der Sie debuggen. Öffnen Sie das Windows-Startmenü , und geben Sie "Zurücksetzen" ein. Suchen Sie nach dem Befehl, und führen Sie den Befehl aus, und setzen Sie die nächste Visual Studio Experimental-Instanz zurück. Dieser Befehl sauber die experimentelle Registrierungsstruktur aller Erweiterungskomponenten hoch. Es sauber keine Einstellungen aus Komponenten heraus, sodass alle Führungslinien, die Sie beim Herunterfahren der experimentellen Struktur von Visual Studio hatten, immer noch vorhanden sind, wenn Ihr Code den Einstellungsspeicher beim nächsten Start liest.
Fertiges Codeprojekt
Es wird bald ein GitHub-Projekt von Visual Studio Extensibility-Beispielen geben, und das fertige Projekt wird dort sein. Dieser Artikel wird aktualisiert, um darauf hinzuweisen, wann dies geschieht. Das fertige Beispielprojekt verfügt möglicherweise über unterschiedliche GUIDs und verfügt über einen anderen Bitmapsstreifen für die Befehlssymbole.
Sie können eine Version der Funktion "Spaltenführungslinien" mit dieser Visual Studio Gallery-Erweiterung ausprobieren.