|
1 | | -[](https://github.com/eclipse-platform/eclipse.platform.swt/actions/workflows/maven.yml)  |
| 1 | +# SWT with Custom-Rendered Widgets on Ski(j)a |
2 | 2 |
|
3 | | -# About |
| 3 | +This repository is a fork of the original [SWT repository](https://github.com/eclipse-platform/eclipse.platform.swt) containing prototyping work on exchanging the adaptation of native, basic widgets with custom-drawn widgets based on the rendering engine Skia and its Java bindings [Skija](https://github.com/JetBrains/skija). |
4 | 4 |
|
5 | | -SWT is a cross-platform GUI library for JVM based desktop applications. |
6 | | -The best known SWT-based application is [Eclipse](https://www.eclipse.org). |
| 5 | +In the following, you find information about how to try the prototype out and how its current state is. The custom-drawn widgets are supposed to seemlessly integrate with the other, still native widgets, which is why they are currently implemented to look similar to the existing widgets they replace. But they can be easily replaced with whatever look and feel is desired. |
7 | 6 |
|
8 | 7 | ## Getting Started |
9 | 8 |
|
10 | | -SWT comes with platform-specific jar files. |
11 | | -Download them from https://download.eclipse.org/eclipse/downloads/index.html and add the jar file to your classpath. |
| 9 | +To test the prototype, an Eclipse IDE has to be set up and the SWT projects from this repository have to be imported into it to start example applications. |
12 | 10 |
|
13 | | -### Example |
14 | | - |
15 | | -```java |
16 | | -import org.eclipse.swt.SWT; |
17 | | -import org.eclipse.swt.layout.GridData; |
18 | | -import org.eclipse.swt.layout.GridLayout; |
19 | | -import org.eclipse.swt.widgets.Button; |
20 | | -import org.eclipse.swt.widgets.Display; |
21 | | -import org.eclipse.swt.widgets.Label; |
22 | | -import org.eclipse.swt.widgets.Shell; |
23 | | -import org.eclipse.swt.widgets.Text; |
| 11 | +Note that current development does not target all platforms (Windows, MacOS, Linux). Development usually happens on Windows (and partly MacOS), so the experience will be best there. No implementation and testing for Linux has been performed so far. |
24 | 12 |
|
25 | | -public class HelloWorld { |
| 13 | +### Setup |
26 | 14 |
|
27 | | - public static void main(String[] args) { |
28 | | - final Display display = new Display(); |
| 15 | +1. Set up a recent Eclipse IDE for Committers (currently 2024-09 or newer including nightly builds), e.g.: |
| 16 | + - [Eclipse IDE for Committers 2024-09](https://www.eclipse.org/downloads/packages/release/2024-09/r/eclipse-ide-eclipse-committers) |
| 17 | + - [Eclipse SDK Development Environment](https://github.com/eclipse-platform/eclipse.platform?tab=readme-ov-file#how-to-contribute) |
| 18 | +2. Clone this repository |
| 19 | +3. Start the downloaded IDE and import the following projects: |
| 20 | + - The SWT bundle `org.eclipse.swt` |
| 21 | + - The OS-specific fragment `org.eclipse.swt.$WS.$OS.$ARCH` with the placeholders according to your environment, such as `org.eclipse.swt.win32.win32.x86_64` for the Windows fragment |
| 22 | + - _Optional:_ For testing purposes `org.eclipse.swt.examples` |
29 | 23 |
|
30 | | - final Shell shell = new Shell(display); |
31 | | - shell.setText("Hello World"); |
32 | | - shell.setLayout(new GridLayout(2, false)); |
| 24 | +The resulting workspace should look something like this: |
| 25 | + |
33 | 26 |
|
34 | | - final Label label = new Label(shell, SWT.LEFT); |
35 | | - label.setText("Your &Name:"); |
36 | | - label.setLayoutData(new GridData(SWT.FILL, SWT.CENTER, false, false)); |
| 27 | +### Examples |
37 | 28 |
|
38 | | - final Text text = new Text(shell, SWT.BORDER | SWT.SINGLE); |
39 | | - final GridData data = new GridData(SWT.FILL, SWT.CENTER, true, false); |
40 | | - data.minimumWidth = 120; |
41 | | - text.setLayoutData(data); |
| 29 | +Starting with this, you can try out the SWT implementation with whatever application you want by also importing the according plug-ins into your workspace. Two reasonable, simple starting points are (1) the SWT `ControlExample`, a demo application containing all basic SWT widgets with configurability for most of their functionality, to see how the widgets look like and behave, and (2) a simple Eclipse application to see how it looks in a complete application. |
42 | 30 |
|
43 | | - final Button button = new Button(shell, SWT.PUSH); |
44 | | - button.setText("Say Hello"); |
45 | | - shell.setDefaultButton(button); |
46 | | - button.setLayoutData(new GridData(SWT.END, SWT.CENTER, false, false, 2, 1)); |
| 31 | +#### `ControlExample` |
47 | 32 |
|
48 | | - final Label output = new Label(shell, SWT.CENTER); |
49 | | - output.setLayoutData(new GridData(SWT.FILL, SWT.CENTER, true, false, 2, 1)); |
| 33 | +The `ControlExample` is part of the example project. It is placed in `org.eclipse.swt.examples.controlexample`. You can run this class as a Java application. The application has tabs for the individual widgets. The tab that opens first is for the `Button`, which is completely custom-drawn. So almost everything you see on that page is custom-drawn via code of the prototype. |
50 | 34 |
|
51 | | - button.addListener(SWT.Selection, event -> { |
52 | | - String name = text.getText().trim(); |
53 | | - if (name.length() == 0) { |
54 | | - name = "world"; |
55 | | - } |
56 | | - output.setText("Hello " + name + "!"); |
57 | | - }); |
| 35 | +At the bottom of the application, a toggle button allows to switch between using the native and the Skija-based renderer ( `GC`) at runtime (see [State](#state)). You can currently distinguish the two rendering engines by looking at the edges of buttons, which are currently not rounded when using the Skija-based GC. The following screenshot shows the rendering of that page based on Skija. |
58 | 36 |
|
59 | | - shell.setSize(shell.computeSize(SWT.DEFAULT, SWT.DEFAULT)); |
60 | | - shell.open(); |
| 37 | + |
61 | 38 |
|
62 | | - while (!shell.isDisposed()) { |
63 | | - if (!display.readAndDispatch()) { |
64 | | - display.sleep(); |
65 | | - } |
66 | | - } |
| 39 | +#### Eclipse Application |
67 | 40 |
|
68 | | - display.dispose(); |
69 | | - } |
70 | | -} |
71 | | -``` |
72 | | -First, a `Display` is created which is something like the central place of all GUI-related code. |
73 | | -Then a `Shell` is created which in our example is a top-level window. |
74 | | -Then all child controls and listeners are created, including their layout information. |
75 | | -Finally, we set the window's size determines by its child controls and open the window. |
76 | | -The `while`-loop processes all GUI related events until the shell is disposed which happens when closing. |
77 | | -Before exiting, any claimed GUI resources needs to be freed. |
| 41 | +To start a simple Eclipse application, create a `Run Configuration` via the menu `Run`, menu item `Run Configuration` and in the dialog opening up by double-clicking on the `Eclipse Application` type to create a new configuration that you can launch via the `Run` button: |
| 42 | + |
78 | 43 |
|
79 | | -Contributing to SWT |
80 | | -=================== |
| 44 | +The Eclipse application that starts will automatically use the custom-drawn widgets. To see a page with mostly custom-drawn widgets, you can, for example, open the `Create Java Project` wizard: |
| 45 | + |
81 | 46 |
|
82 | | -Thanks for your interest in this project. |
| 47 | +## State |
83 | 48 |
|
84 | | -For information about contributing to Eclipse Platform in general, see the general [CONTRIBUTING](https://github.com/eclipse-platform/.github/blob/main/CONTRIBUTING.md) page. |
| 49 | +Note that this is work-in-progress prototyping work. The implementation is not (supposed to be) production ready. |
| 50 | +Currently, there are (at least partial) custom implementations for the following basic widgets: |
| 51 | +- Button |
| 52 | +- Label |
| 53 | +- Text |
| 54 | +- Combo |
85 | 55 |
|
| 56 | +For rendering, the custom-drawn widgets only rely on the functionalities of the `GC`, such a drawing text and primities like lines. |
| 57 | +In addition to using the existing, native `GC`, i.e., the rendering engine of the operating system, the implementation also contains a `SkijaGC`, providing (parts of) the same functionality but using Ski(j)a for rendering instead. To make these interchangeable, the common functionality has been extracted into an `IGraphicsCanvas` interface. |
86 | 58 |
|
87 | | -[]( |
88 | | -https://www.eclipse.org/setups/installer/?url=https://raw.githubusercontent.com/eclipse-platform/eclipse.platform.swt/master/bundles/org.eclipse.swt.tools/Oomph/PlatformSWTConfiguration.setup&show=true |
89 | | -"Click to open Eclipse-Installer Auto Launch or drag into your running installer") |
90 | | - |
91 | | - |
92 | | - |
93 | | -Developer resources: |
94 | | --------------------- |
95 | | - |
96 | | -See the following description for how to contribute a feature or a bug fix to SWT. |
97 | | - |
98 | | -- <https://www.eclipse.org/swt/fixbugs.php> |
99 | | - |
100 | | -Information regarding source code management, builds, coding standards, and more and be found under the following link. |
101 | | - |
102 | | -- <https://projects.eclipse.org/projects/eclipse.platform.swt/developer> |
103 | | - |
104 | | -Contributor License Agreement: |
105 | | ------------------------------- |
106 | | - |
107 | | -Before your contribution can be accepted by the project, you need to create and electronically sign the Eclipse Foundation Contributor License Agreement (CLA). |
108 | | - |
109 | | -- <http://www.eclipse.org/legal/CLA.php> |
110 | | - |
111 | | -Contact: |
112 | | --------- |
113 | | - |
114 | | -Contact the project developers via the project's "dev" list. |
115 | | - |
116 | | -- <https://accounts.eclipse.org/mailing-list/platform-dev> |
117 | | - |
118 | | -Search for bugs: |
119 | | ----------------- |
120 | | - |
121 | | -SWT used to track ongoing development and issues in Bugzilla . |
122 | | - |
123 | | -- <https://bugs.eclipse.org/bugs/buglist.cgi?product=Platform&component=SWT> |
124 | | - |
125 | | -Create a new bug: |
126 | | ------------------ |
127 | | - |
128 | | -You can register bugs and feature requests in the Github Issue Tracker. Remember that contributions are always welcome! |
129 | | -- [View existing SWT issues](https://github.com/eclipse-platform/eclipse.platform.swt/issues) |
130 | | -- [New SWT issue](https://github.com/eclipse-platform/eclipse.platform.swt/issues/new) |
131 | | - |
132 | | -Please bear in mind that this project is almost entirely developed by volunteers. If you do not provide the implementation yourself (or pay someone to do it for you), the bug might never get fixed. If it is a serious bug, other people than you might care enough to provide a fix. |
0 commit comments