Eclipse Platform UI: Issues in Light (Preview) Theme #2313

[mai-tran-03]

INTRODUCTION

Over the last month, I became an Eclipse contributor and await feedback on my pull request. I had the opportunity to explore an extensively used codebase supported by thousands of other contributors and reflect on the journey of my first open-source project.

THE PROJECT

The Eclipse Platform provides the frameworks and services that support the functionality of the Eclipse development environment. The Platform UI project specifically focuses on the user interface components, the help and documentation features, and the runtime of those elements. This project aims to maintain a cohesive user experience, allowing developers to build visually consistent and user-friendly Eclipse-based applications.

The Platform UI is a necessary add-on to the Eclipse Platform because its consistency enhances the user experience in learning and navigating the application. It also ensures a broad and diverse audience can use its products by offering built-in assistive functions. For example, the overview, tutorial pages, and icon captions immensely benefit thousands of new users who are starting their coding journey.

THE ISSUE

The reported issue is a color inconsistency in the progress view. If users switch to the light preview of the interface, then texts like “Building” would have a white background. However, it should have a consistent light grey color as its parent outline.

This issue is important to the Platform UI project because maintaining a consistent appearance is vital when users switch between different themes. For a robust platform like Eclipse, exceptional design quality contributes to the overall impression of the platform.

To get started, I replicated the issue and observed how the background color of this progress bar is rendered in different themes. The color is consistent for all other themes, except the light preview. Based on the keywords using the global search tool, I searched for progressBar and setBackground. Then, I looked at any relevant packages and files where the progress bar could be created and the background could be called. Then, I followed this path /bundles/org.eclipse.ui.workbench/Eclipse UI/org.eclipse.ui.internal.progress/ to the key locations of DetailedProgressView.java and ProgressInfoItem.java.

DetailedProgressView.java is designed to display detailed information about ongoing jobs so users can see what is loading. It uses the SWT library to create and manage the UI elements within the progress view. ProgressInfoItem.java creates the loading bar, text label, and other formatting components. It also uses the SWT library to get and set background and foreground colors.

Because I could modify the background from both files, I tested The difference by changing the default color to a more distinct color for each file. Every time I see a SWT.COLOR… I would try modifying it to determine if there is any visible change somewhere in the IDE. The differences when modifying the two files are shown below:

CHALLENGES

Exploring the issue was quite a journey. Changing the background color of some blocks of text seemed simple at first, however, diving into the large codebase is a daunting task for a first-time contributor. Although the Eclipse Platform UI has its README.md and CONTRIBUTING.md pages, they link to the parent Eclipse Platform project and its How to Contribute page. I got through the registering user to Eclipse just fine with instructions to create an Eclipse account and sign a contributor agreement.

I struggled with setting up the pre-configured IDE for a contributor. I followed this page to set up the development environment. Because the page has Auto Launch as the first item, it took me a while to understand that I needed to download and register the Eclipse installer beforehand. To someone unfamiliar with computer hardware, I chose the first option of Mac OS x86_64 instead of Mac OS AArch64 to download the installer. With the help of Lola Egherman, a CodeDay consulting SWE, I could register my installer using the drag-and-drop option because I did not know how to use the Web Links option.

It would have been better if the page had rearranged the order of installation items, more pictures, or made this detailed instruction page more visible. For future reference, please note which Mac OS version to download because it led to an avoidable error Could not load the SWT library. There is a workaround for the error, however, it would be more efficient to know that a user’s Mac silicon chip might be incompatible with loading the SWT library. After resolving these issues, the next steps were running and testing changes to the relevant project files.

THE CODEBASE

I learned from Lola that contributors can see changes by running the Eclipse Platform UI examples written by former developers to implement the UI components with fake data. I also learned from my mentor Akshatha A, an Adobe frontend developer, that the Eclipse Platform UI tests were specifically written to test functionality and would not run properly if new changes were implemented to the original files. I did some test runs on some example products such as the RCP info product and CSS bridge demo.

Before meeting Lola again, I could not understand why I could only launch those example products and the other example folders took me to another Eclipse runtime application. I consulted with my teammates who also encountered the same problems, actively looked online, and met with Akshatha asking how to see changes when modifying the code of Platform UI files. I received additional guidance from Lola on how to look at the codebase as a system diagram.

To sum it up, the Platform UI uses the SWT library to implement the UI components and the Platform UI examples display what those components can look like. Besides the examples, other users such as you, me, and NASA, can use Platform UI as a foundation to create applications. The resulting interface of the CSS bridge demo illustrates the contributors’ abilities to add print statements and functions to modify the interface directly. Another way to make modifications is to alter the code within Platform UI and let the internal workings display the new adjustments.

After having a clearer picture of the workflow, I experimented with any code related to progress and background color in the ProgressInfoItem file. Because the background looked fine in the light theme, I often tested the changes between multiple themes to confirm what worked and what did not work. I also noticed that the runtime application layout looked off even in a light theme, and it was because my computer was in dark mode. None of the changes I made could be applied in light preview.

SOLUTION

Although I could not develop a full solution with my team, I suspect the problem is that not all relevant components of the progress item are synced in the light preview theme. Upon closer inspection of the function setColor, it checks a boolean flag isThemed and applies a default color setting if the variable isThemed is false. This means if there is no custom theme, then the program proceeds to set the background color in alternating order of darker and lighter color to help with readability and foreground color of the text.

My hypothesis is to remove the condition isThemed to see if it affects the light preview theme. First, I checked all the themes, and the progress item with the condition isThemed. Surprisingly, most themes use the default color for their progress components. Then, I checked all the themes again without the condition; the light preview works fine. However, the dark theme had inherited the default color. This means the dark theme is a custom theme, so the condition isThemed is needed but in a different way.

These are views with the condition isThemed and no other modifications.

These are views without the condition isThemed and no other modifications.

My next step is to check how the condition isThemed is being checked. The function getCustomThemeFlag returns isThemed by checking whether the active theme is equal to the default theme; if the current theme is not default, then it returns true, otherwise false. Since the dark theme is the only one affected by the condition isThemed, I modify the function getCustomThemeFlag to return true only when the active theme is equal to the dark theme.

The following code as described above can fix both issues:

However, the concern lies in that this fix does not generalize to other themes. I'm not sure how to create a more robust solution that does not explicitly check for the dark theme in getCustomThemeFlag() and would apply to any future custom themes.

This discussion was initially posted on Linkedin.