blob: 074b8203b5eb2e8e17b7d7eb92b864c575496005 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
/*---------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/
import { createDecorator } from 'vs/platform/instantiation/common/instantiation';
import { IDisposable } from 'vs/base/common/lifecycle';
import { IMarkdownString } from 'vs/base/common/htmlContent';
import { HoverPosition } from 'vs/base/browser/ui/hover/hoverWidget';
export const IHoverService = createDecorator<IHoverService>('hoverService');
/**
* Enables the convenient display of rich markdown-based hovers in the workbench.
*/
export interface IHoverService {
readonly _serviceBrand: undefined;
/**
* Shows a hover, provided a hover with the same options object is not already visible.
* @param options A set of options defining the characteristics of the hover.
* @param focus Whether to focus the hover (useful for keyboard accessibility).
*
* **Example:** A simple usage with a single element target.
*
* ```typescript
* showHover({
* text: new MarkdownString('Hello world'),
* target: someElement
* });
* ```
*/
showHover(options: IHoverOptions, focus?: boolean): IHoverWidget | undefined;
/**
* Hides the hover if it was visible. This call will be ignored if the the hover is currently
* "locked" via the alt/option key.
*/
hideHover(): void;
}
export interface IHoverWidget extends IDisposable {
readonly isDisposed: boolean;
}
export interface IHoverOptions {
/**
* The content to display in the primary section of the hover. The type of text determines the
* default `hideOnHover` behavior.
*/
content: IMarkdownString | string | HTMLElement;
/**
* The target for the hover. This determines the position of the hover and it will only be
* hidden when the mouse leaves both the hover and the target. A HTMLElement can be used for
* simple cases and a IHoverTarget for more complex cases where multiple elements and/or a
* dispose method is required.
*/
target: IHoverTarget | HTMLElement;
/**
* A set of actions for the hover's "status bar".
*/
actions?: IHoverAction[];
/**
* An optional array of classes to add to the hover element.
*/
additionalClasses?: string[];
/**
* An optional link handler for markdown links, if this is not provided the IOpenerService will
* be used to open the links using its default options.
*/
linkHandler?(url: string): void;
/**
* Whether to hide the hover when the mouse leaves the `target` and enters the actual hover.
* This is false by default when text is an `IMarkdownString` and true when `text` is a
* `string`. Note that this will be ignored if any `actions` are provided as hovering is
* required to make them accessible.
*
* In general hiding on hover is desired for:
* - Regular text where selection is not important
* - Markdown that contains no links where selection is not important
*/
hideOnHover?: boolean;
/**
* Whether to hide the hover when a key is pressed.
*/
hideOnKeyDown?: boolean;
/**
* Position of the hover. The default is to show above the target. This option will be ignored
* if there is not enough room to layout the hover in the specified position, unless the
* forcePosition option is set.
*/
hoverPosition?: HoverPosition;
/**
* Force the hover position, reducing the size of the hover instead of adjusting the hover
* position.
*/
forcePosition?: boolean;
/**
* Whether to show the hover pointer
*/
showPointer?: boolean;
/**
* Whether to show a compact hover
*/
compact?: boolean;
/**
* Whether to skip the fade in animation, this should be used when hovering from one hover to
* another in the same group so it looks like the hover is moving from one element to the other.
*/
skipFadeInAnimation?: boolean;
}
export interface IHoverAction {
/**
* The label to use in the hover's status bar.
*/
label: string;
/**
* The command ID of the action, this is used to resolve the keybinding to display after the
* action label.
*/
commandId: string;
/**
* An optional class of an icon that will be displayed before the label.
*/
iconClass?: string;
/**
* The callback to run the action.
* @param target The action element that was activated.
*/
run(target: HTMLElement): void;
}
/**
* A target for a hover.
*/
export interface IHoverTarget extends IDisposable {
/**
* A set of target elements used to position the hover. If multiple elements are used the hover
* will try to not overlap any target element. An example use case for this is show a hover for
* wrapped text.
*/
readonly targetElements: readonly HTMLElement[];
/**
* An optional absolute x coordinate to position the hover with, for example to position the
* hover using `MouseEvent.pageX`.
*/
x?: number;
/**
* An optional absolute y coordinate to position the hover with, for example to position the
* hover using `MouseEvent.pageY`.
*/
y?: number;
}
|
