====== VSCode Wrapper API ======

Pascal-Wrapper für die VS Code Extension API.

===== Übersicht =====

Die WvdS.VSCode.* Units bieten typsichere Pascal-Wrapper für die VS Code API.

<code>
sources/common/web/vscode/
├── VSCode.API.pas          # Basis-API
├── VSCode.Commands.pas     # Command-Registrierung
├── VSCode.Configuration.pas # Einstellungen
├── VSCode.Documents.pas    # Text-Dokumente
├── VSCode.Languages.pas    # Sprachfeatures
├── VSCode.WebView.pas      # WebView-Panels
├── VSCode.Window.pas       # Fenster-API
├── VSCode.Workspace.pas    # Workspace-API
└── VSCode.ExtensionExports.pas # Entry-Point-Export
</code>

===== VSCode.Commands =====

==== RegisterCommand ====

<code pascal>
function RegisterCommand(
  const ACommand: string;
  AHandler: TCommandHandler
): TDisposable;

type
  TCommandHandler = procedure(Args: TJSValueDynArray);
</code>

**Beispiel:**

<code pascal>
uses VSCode.Commands;

procedure HandleMyCommand(Args: TJSValueDynArray);
begin
  ShowInfoMessage('Command executed!');
end;

// Bei Aktivierung:
Context.Subscriptions.Push(
  RegisterCommand('myext.mycommand', @HandleMyCommand)
);
</code>

==== ExecuteCommand ====

<code pascal>
function ExecuteCommand(const ACommand: string): TJSPromise;
function ExecuteCommand(
  const ACommand: string;
  const AArgs: array of JSValue
): TJSPromise;
</code>

===== VSCode.Window =====

==== Nachrichten ====

<code pascal>
procedure ShowInfoMessage(const AMessage: string);
procedure ShowWarningMessage(const AMessage: string);
procedure ShowErrorMessage(const AMessage: string);

function ShowInfoMessageWithItems(
  const AMessage: string;
  const AItems: array of string
): TJSPromise;  // Resolves to selected item or undefined
</code>

==== Input ====

<code pascal>
function ShowInputBox(AOptions: TInputBoxOptions): TJSPromise;

type
  TInputBoxOptions = record
    Prompt: string;
    PlaceHolder: string;
    Value: string;
    Password: Boolean;
  end;
</code>

<code pascal>
function ShowQuickPick(
  const AItems: array of string;
  AOptions: TQuickPickOptions
): TJSPromise;

type
  TQuickPickOptions = record
    PlaceHolder: string;
    CanPickMany: Boolean;
  end;
</code>

==== Output Channel ====

<code pascal>
function CreateOutputChannel(const AName: string): TOutputChannel;

type
  TOutputChannel = class
    procedure Append(const AText: string);
    procedure AppendLine(const AText: string);
    procedure Show;
    procedure Hide;
    procedure Clear;
    procedure Dispose;
  end;
</code>

==== StatusBar ====

<code pascal>
function CreateStatusBarItem(
  AAlignment: TStatusBarAlignment;
  APriority: Integer
): TStatusBarItem;

type
  TStatusBarAlignment = (sbaLeft, sbaRight);

  TStatusBarItem = class
    Text: string;
    Tooltip: string;
    Command: string;
    procedure Show;
    procedure Hide;
    procedure Dispose;
  end;
</code>

===== VSCode.WebView =====

==== WebviewPanel ====

<code pascal>
function CreateWebviewPanel(
  const AViewType: string;
  const ATitle: string;
  AShowOptions: TViewColumn;
  AOptions: TWebviewOptions
): TWebviewPanel;

type
  TViewColumn = (vcOne, vcTwo, vcThree, vcBeside, vcActive);

  TWebviewOptions = record
    EnableScripts: Boolean;
    LocalResourceRoots: TStringArray;
  end;

  TWebviewPanel = class
    Webview: TWebview;
    Title: string;
    OnDidDispose: TEvent;
    procedure Reveal;
    procedure Dispose;
  end;

  TWebview = class
    Html: string;
    OnDidReceiveMessage: TMessageHandler;
    procedure PostMessage(AMessage: TJSObject);
  end;
</code>

===== VSCode.Documents =====

==== Text-Dokumente ====

<code pascal>
function GetActiveTextEditor: TTextEditor;
function OpenTextDocument(const APath: string): TJSPromise;

type
  TTextEditor = class
    Document: TTextDocument;
    Selection: TSelection;
    procedure Edit(ACallback: TEditBuilderCallback);
  end;

  TTextDocument = class
    Uri: string;
    FileName: string;
    LanguageId: string;
    LineCount: Integer;
    function GetText: string;
    function LineAt(ALine: Integer): TTextLine;
  end;
</code>

==== Events ====

<code pascal>
procedure OnDidOpenTextDocument(AHandler: TDocumentHandler);
procedure OnDidSaveTextDocument(AHandler: TDocumentHandler);
procedure OnDidCloseTextDocument(AHandler: TDocumentHandler);
procedure OnDidChangeTextDocument(AHandler: TDocumentChangeHandler);
</code>

===== VSCode.Workspace =====

<code pascal>
function GetWorkspaceFolders: TWorkspaceFolderArray;
function GetConfiguration(const ASection: string): TWorkspaceConfiguration;

type
  TWorkspaceFolder = record
    Uri: string;
    Name: string;
    Index: Integer;
  end;

  TWorkspaceConfiguration = class
    function Get(const AKey: string; ADefault: JSValue): JSValue;
    procedure Update(
      const AKey: string;
      AValue: JSValue;
      ATarget: TConfigurationTarget
    );
  end;
</code>

===== VSCode.Languages =====

==== CompletionProvider ====

<code pascal>
procedure RegisterCompletionItemProvider(
  const ASelector: TDocumentSelector;
  AProvider: TCompletionProvider;
  const ATriggerCharacters: array of string
);

type
  TCompletionProvider = class abstract
    function ProvideCompletionItems(
      ADocument: TTextDocument;
      APosition: TPosition
    ): TCompletionList; virtual; abstract;
  end;
</code>

==== HoverProvider ====

<code pascal>
procedure RegisterHoverProvider(
  const ASelector: TDocumentSelector;
  AProvider: THoverProvider
);

type
  THoverProvider = class abstract
    function ProvideHover(
      ADocument: TTextDocument;
      APosition: TPosition
    ): THover; virtual; abstract;
  end;
</code>

===== VSCode.ExtensionExports =====

<code pascal>
procedure ExportActivateDeactivate(
  AActivate: TActivateProc;
  ADeactivate: TDeactivateProc
);

type
  TActivateProc = procedure(AContext: TExtensionContext);
  TDeactivateProc = procedure;
</code>

**Verwendung:**

<code pascal>
initialization
  ExportActivateDeactivate(@Activate, @Deactivate);
</code>

===== Typen-Mapping =====

^ VS Code (JS) ^ Pascal ^
| string | string |
| number | Double / Integer |
| boolean | Boolean |
| undefined | nil |
| object | TJSObject |
| array | TJSArray |
| Promise | TJSPromise |
| Disposable | TDisposable |

===== Siehe auch =====

  * [[.:core-api|Core API]]
  * [[.:meta-api|Meta API]]
  * [[.:extension-entwicklung|Extension-Entwicklung]]