8000 docs: add documentation for `ImageView` (#47298) · electron/electron@1487f5d · GitHub
[go: up one dir, main page]
Skip to content

Commit 1487f5d

Browse files
trop[bot]itsananderson
trop[bot]
and
itsananderson
authored
docs: add documentation for ImageView (#47298)
* docs: Add documentation for ImageView * docs: Add ImageView main process module list in README.md * test: Add some basic tests for ImageView * test: Fill out Window embedding tests to better reflect how someone might use an ImageView * docs: Add notes about using ImageView as a splash screen * docs: Update ImageView example to show a more complete splash screen example * docs: Remove view resizing logic since the ImageView automatically gets resized --------- Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com> Co-authored-by: Will Anderson <andersonw@dropbox.com>
1 parent d647bb4 commit 1487f5d

File tree

4 files changed

+149
-0
lines changed

4 files changed

+149
-0
lines changed

‎docs/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@ These individual tutorials expand on topics discussed in the guide above.
113113
* [dialog](api/dialog.md)
114114
* [globalShortcut](api/global-shortcut.md)
115115
* [inAppPurchase](api/in-app-purchase.md)
116+
* [ImageView](api/image-view.md)
116117
* [ipcMain](api/ipc-main.md)
117118
* [Menu](api/menu.md)
118119
* [MenuItem](api/menu-item.md)

‎docs/api/image-view.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# ImageView
2+
3+
> A View that displays an image.
4+
5+
Process: [Main](../glossary.md#main-process)
6+
7+
This module cannot be used until the `ready` event of the `app`
8+
module is emitted.
9+
10+
Useful for showing splash screens that will be swapped for `WebContentsView`s
11+
when the content finishes loading.
12+
13+
Note that `ImageView` is experimental and may be changed or removed in the future.
14+
15+
```js
16+
const { BaseWindow, ImageView, nativeImage, WebContentsView } = require('electron')
17+
const path = require('node:path')
18+
19+
const win = new BaseWindow({ width: 800, height: 600 })
20+
21+
// Create a "splash screen" image to display while the WebContentsView loads
22+
const splashView = new ImageView()
23+
const splashImage = nativeImage.createFromPath(path.join(__dirname, 'loading.png'))
24+
splashView.setImage(splashImage)
25+
win.setContentView(splashView)
26+
27+
const webContentsView = new WebContentsView()
28+
webContentsView.webContents.once('did-finish-load', () => {
29+
// Now that the WebContentsView has loaded, swap out the "splash screen" ImageView
30+
win.setContentView(webContentsView)
31+
})
32+
webContentsView.webContents.loadURL('https://electronjs.org')
33+
```
34+
35+
## Class: ImageView extends `View`
36+
37+
> A View that displays an image.
38+
39+
Process: [Main](../glossary.md#main-process)
40+
41+
`ImageView` inherits from [`View`](view.md).
42+
43+
`ImageView` is an [EventEmitter][event-emitter].
44+
45+
### `new ImageView()` _Experimental_
46+
47+
Creates an ImageView.
48+
49+
### Instance Methods
50+
51+
The following methods are available on instances of the `ImageView` class, in
52+
addition to those inherited from [View](view.md):
53+
54+
#### `image.setImage(image)` _Experimental_
55+
56+
* `image` NativeImage
57+
58+
Sets the image for this `ImageView`. Note that only image formats supported by
59+
`NativeImage` can be used with an `ImageView`.
60+
61+
[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter

‎filenames.auto.gni

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ auto_filenames = {
2525
"docs/api/extensions-api.md",
2626
"docs/api/extensions.md",
2727
"docs/api/global-shortcut.md",
28+
"docs/api/image-view.md",
2829
"docs/api/in-app-purchase.md",
2930
"docs/api/incoming-message.md",
3031
"docs/api/ipc-main-service-worker.md",

‎spec/api-image-view-spec.ts

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
import { nativeImage } from 'electron/common';
2+
import { BaseWindow, BrowserWindow, ImageView } from 'electron/main';
3+
4+
import { expect } from 'chai';
5+
6+
import * as path from 'node:path';
7+
8+
import { closeAllWindows } from './lib/window-helpers';
9+
10+
describe('ImageView', () => {
11+
afterEach(async () => {
12+
await closeAllWindows();
13+
});
14+
15+
it('can be instantiated with no arguments', () => {
16+
// eslint-disable-next-line no-new
17+
new ImageView();
18+
});
19+
20+
it('can set an empty NativeImage', () => {
21+
const view = new ImageView();
22+
const image = nativeImage.createEmpty();
23+
view.setImage(image);
24+
});
25+
26+
it('can set a NativeImage', () => {
27+
const view = new ImageView();
28+
const image = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'logo.png'));
29+
view.setImage(image);
30+
});
31+
32+
it('can change its NativeImage', () => {
33+
const view = new ImageView();
34+
const image1 = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'logo.png'));
35+
const image2 = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'capybara.png'));
36+
view.setImage(image1);
37+
view.setImage(image2);
38+
});
39+
40+
it('can be embedded in a BaseWindow', () => {
41+
const w = new BaseWindow({ show: false });
42+
const view = new ImageView();
43+
const image = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'capybara.png'));
44+
view.setImage(image);
45+
w.setContentView(view);
46+
w.setContentSize(image.getSize().width, image.getSize().height);
47+
view.setBounds({
48+
x: 0,
49+
y: 0,
50+
width: image.getSize().width,
51+
height: image.getSize().height
52+
});
53+
});
54+
55+
it('can be embedded in a BrowserWindow', () => {
56+
const w = new BrowserWindow({ show: false });
57+
const image = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'logo.png'));
58+
const view = new ImageView();
59+
view.setImage(image);
60+
w.contentView.addChildView(view);
61+
w.setContentSize(image.getSize().width, image.getSize().height);
62+
view.setBounds({
63+
x: 0,
64+
y: 0,
65+
width: image.getSize().width,
66+
height: image.getSize().height
67+
});
68+
69+
expect(w.contentView.children).to.include(view);
70+
});
71+
72+
it('can be removed from a BrowserWindow', async () => {
73+
const w = new BrowserWindow({ show: false });
74+
const image = nativeImage.createFromPath(path.join(__dirname, 'fixtures', 'assets', 'logo.png'));
75+
const view = new ImageView();
76+
view.setImage(image);
77+
78+
w.contentView.addChildView(view);
79+
expect(w.contentView.children).to.include(view);
80+
81+
await w.loadFile(path.join(__dirname, 'fixtures', 'api', 'blank.html'));
82+
83+
w.contentView.removeChildView(view);
84+
expect(w.contentView.children).to.not.include(view);
85+
});
86+
});

0 commit comments

Comments
 (0)
0