starred/terminal
1
0
Fork 0
mirror of https://github.com/microsoft/terminal.git synced 2026-09-25 08:24:54 +00:00
Code Issues 19.0k Packages Projects Releases 20 Wiki Activity

Feature Request: Background image alignment #2736

New Issue
Closed
opened 2026-01-30 23:03:36 +00:00 by claunia · 7 comments
claunia commented 2026-01-30 23:03:36 +00:00
Owner
Copy Link

Originally created by @trigger-segfault on GitHub (Jul 12, 2019).

Originally assigned to: @trigger-segfault on GitHub.

Summary of the new feature/enhancement

When using the backgroundImage profile setting, the image is anchored to the center of the TermControl. Background images that have a primary point of interest that is not the center are not aesthetically pleasing when either... a large part of this focus is cut off via uniformToFill, or the image is centered via uniform or none and there is a abrupt end to the image before the border of the terminal control.

Image Example

Here is a background designed for anchoring to the bottom right. If we rely on uniformToFill, then we run the risk of the image's focus getting completely cut off. If we use none or uniform, then the image will display in the middle and abruptly end on the right while the console display has more room. Alignment anchoring would allow us to display the background image as it is intended.

Preview Figure A (Left) and Figure B (Right)

Figure A (Left), shows an image making use of alignment. Figure B (Right), shows the outcome of using the same background without alignment.

Proposed technical implementation details (optional)

Changes would require two additional profile settings shown below, (with center being the default for both).

"backgroundImageHorizontalAlignment": "center" | "left" | "right",
"backgroundImageVerticalAlignment":   "center" | "top"  | "bottom",

These settings will be needed only once, in this location:

02e8389518/src/cascadia/TerminalControl/TermControl.cpp (L273-L276)

Here, HorizontalAlignment::Center and VerticalAlignment::Center will be replaced with their respective parsed settings of backgroundImageHorizontalAlignment and backgroundImageVerticalAlignment.

These two settings will need constant definitions for of their JSON/serialized values, and Parse/Serialize methods for the enums (in Profile.cpp).

Alternative Setting

One enum setting that combines the flags of HorizontalAlignment and VerticalAlignment could be used. The setting and values would be as follows:

"backgroundImageAlignment": "none" | "left" | "top" | "right" | "bottom"
                 | "topLeft" | "topRight" | "bottomLeft" | "bottomRight"

A value of none, or missing axis alignment, implies that the default action of centering is used. Alternatively none could be labeled center to make this clearer.

There are pros and cons to this alternative. The pros being the setting name is shorter, and can be fully modified from a single line in profiles.json. The longer enum value names are still relatively simple and easy to remember. The cons being we are not referring to a real existing enum anymore, but a combination of enums. We also require more enum definitions and handling cases than if we made each setting separate. Lastly the implied centering with the values of none, left, top, right, and bottom are not as user-friendly.

Originally created by @trigger-segfault on GitHub (Jul 12, 2019). Originally assigned to: @trigger-segfault on GitHub. <!-- 🚨🚨🚨🚨🚨🚨🚨🚨🚨🚨 I ACKNOWLEDGE THE FOLLOWING BEFORE PROCEEDING: 1. If I delete this entire template and go my own path, the core team may close my issue without further explanation or engagement. 2. If I list multiple bugs/concerns in this one issue, the core team may close my issue without further explanation or engagement. 3. If I write an issue that has many duplicates, the core team may close my issue without further explanation or engagement (and without necessarily spending time to find the exact duplicate ID number). 4. If I leave the title incomplete when filing the issue, the core team may close my issue without further explanation or engagement. 5. If I file something completely blank in the body, the core team may close my issue without further explanation or engagement. All good? Then proceed! --> # Summary of the new feature/enhancement <!-- A clear and concise description of what the problem is that the new feature would solve. Describe why and how a user would use this new functionality (if applicable). --> When using the `backgroundImage` profile setting, the image is anchored to the center of the `TermControl`. Background images that have a primary point of interest that is *not* the center are not aesthetically pleasing when either... a large part of this focus is cut off via `uniformToFill`, or the image is centered via `uniform` or `none` and there is a abrupt end to the image before the border of the terminal control. ### Image Example Here is a background designed for anchoring to the bottom right. If we rely on `uniformToFill`, then we run the risk of the image's focus getting completely cut off. If we use `none` or `uniform`, then the image will display in the middle and abruptly end on the right while the console display has more room. Alignment anchoring would allow us to display the background image as it is intended. ![Preview Figure A (Left) and Figure B (Right)](https://i.imgur.com/kUTPL9P.png) *Figure A (Left), shows an image making use of alignment. Figure B (Right), shows the outcome of using the same background without alignment.* # Proposed technical implementation details (optional) <!-- A clear and concise description of what you want to happen. --> Changes would require two additional profile settings shown below, (with center being the default for both). ```json "backgroundImageHorizontalAlignment": "center" | "left" | "right", "backgroundImageVerticalAlignment": "center" | "top" | "bottom", ``` These settings will be needed only once, in this location: https://github.com/microsoft/terminal/blob/02e8389518c7027fa20a99b4642f29f2b6b4ef7a/src/cascadia/TerminalControl/TermControl.cpp#L273-L276 Here, `HorizontalAlignment::Center` and `VerticalAlignment::Center` will be replaced with their respective parsed settings of `backgroundImageHorizontalAlignment` and `backgroundImageVerticalAlignment`. These two settings will need constant definitions for of their JSON/serialized values, and `Parse`/`Serialize` methods for the enums (in `Profile.cpp`). ## Alternative Setting One enum setting that combines the flags of `HorizontalAlignment` and `VerticalAlignment` could be used. The setting and values would be as follows: ```json "backgroundImageAlignment": "none" | "left" | "top" | "right" | "bottom" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight" ``` *A value of `none`, or missing axis alignment, implies that the default action of centering is used. Alternatively `none` could be labeled `center` to make this clearer.* There are pros and cons to this alternative. The pros being the setting name is shorter, and can be fully modified from a single line in `profiles.json`. The longer enum value names are still relatively simple and easy to remember. The cons being we are not referring to a real existing enum anymore, but a combination of enums. We also require more enum definitions and handling cases than if we made each setting separate. Lastly the implied *centering* with the values of `none`, `left`, `top`, `right`, and `bottom` are not as user-friendly.
claunia commented 2026-01-30 23:03:37 +00:00
Author
Owner
Copy Link

@trigger-segfault commented on GitHub (Jul 12, 2019):

This feature also has minor relations to #1936 and the ability to more-thoroughly customize background layout.

@trigger-segfault commented on GitHub (Jul 12, 2019): This feature also has minor relations to #1936 and the ability to more-thoroughly customize background layout.
claunia commented 2026-01-30 23:03:38 +00:00
Author
Owner
Copy Link

@trigger-segfault commented on GitHub (Jul 12, 2019):

I will take a go at writing a PR to implement this as my first contribution. Implementation seems very straight forwards, especially when looking at the structure of the PR that first introduced background images.

@trigger-segfault commented on GitHub (Jul 12, 2019): I will take a go at writing a PR to implement this as my first contribution. Implementation seems very straight forwards, especially when looking at the structure of the PR that first introduced background images.
claunia commented 2026-01-30 23:03:38 +00:00
Author
Owner
Copy Link

@DHowett-MSFT commented on GitHub (Jul 14, 2019):

This seems totally reasonable to me; I'm going to triage it as an accepted feature request. 😄

I'm not averse to the single setting that you've got in PR in #1959; in general I'm worried that we have too many settings and even though this is technically two enums it's one setting. For discussions about schema I'll defer to @zadjii-msft, however, since settings is his area.

Thanks for designing this!

@DHowett-MSFT commented on GitHub (Jul 14, 2019): This seems totally reasonable to me; I'm going to triage it as an accepted feature request. :smile: I'm not averse to the single setting that you've got in PR in #1959; in general I'm worried that we have too many settings and even though this is technically two enums it's _one setting._ For discussions about schema I'll defer to @zadjii-msft, however, since settings is his area. Thanks for designing this!
claunia commented 2026-01-30 23:03:38 +00:00
Author
Owner
Copy Link

@DHowett-MSFT commented on GitHub (Jul 14, 2019):

I've gone ahead and assigned you, as well, so people know this one is claimed!

@DHowett-MSFT commented on GitHub (Jul 14, 2019): I've gone ahead and assigned you, as well, so people know this one is claimed!
claunia commented 2026-01-30 23:03:38 +00:00
Author
Owner
Copy Link

@trigger-segfault commented on GitHub (Jul 14, 2019):

Thanks! I’m definitely happy about the preference towards a single setting. This was a very simple and fun first contribution.

Shall I hold off on undrafting PR #1959 so that the specifics of the JSON setting can be discussed with zadjii-msft here?

@trigger-segfault commented on GitHub (Jul 14, 2019): Thanks! I’m definitely happy about the preference towards a single setting. This was a very simple and fun first contribution. Shall I hold off on *undrafting* PR #1959 so that the specifics of the JSON setting can be discussed with zadjii-msft here? <!-- I wonder if the background image settings would work better as a single `backgroundImage` JSON object within each profile? That way if a background image object is non-null, then all settings related to the image could be serialized under one object. ```json "backgroundImage": null -or- "backgroundImage": { "source": "C:/MyImage.png", "stretchMode": "uniform", "opacity": 0.45, "alignment": "topRight" } ``` -->
claunia commented 2026-01-30 23:03:38 +00:00
Author
Owner
Copy Link

@zadjii-msft commented on GitHub (Jul 16, 2019):

Ah see, I think I am slightly in favor of the two settings, which is a little closer to the raw XAML properties. That being said, I'm not about to start a crusade over this. This seems fine the way it is, so I'll try and take a look at the PR.

@zadjii-msft commented on GitHub (Jul 16, 2019): Ah see, I think I am slightly in favor of the two settings, which is a little closer to the raw XAML properties. That being said, I'm not about to start a crusade over this. This seems fine the way it is, so I'll try and take a look at the PR.
claunia commented 2026-01-30 23:03:38 +00:00
Author
Owner
Copy Link

@ghost commented on GitHub (Aug 3, 2019):

:tada:This issue was addressed in #1959, which has now been successfully released as Windows Terminal Preview v0.3.2142.0.🎉

Handy links:

@ghost commented on GitHub (Aug 3, 2019): :tada:This issue was addressed in #1959, which has now been successfully released as `Windows Terminal Preview v0.3.2142.0`.:tada: Handy links: * [Release Notes](https://github.com/microsoft/terminal/releases/tag/v0.3.2142.0) * [Store Download](https://www.microsoft.com/store/apps/9n0dx20hk701?cid=storebadge&ocid=badge)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
⛺ Reserved
A11yCO
A11yMAS
A11ySev1
A11ySev2
A11ySev3
A11yTTValidated
A11yUsable
A11yVoiceAccess
A11yWCAG
Area-Accessibility
Area-AtlasEngine
Area-AzureShell
Area-Build
Area-Build
Area-Chat
Area-CmdPal
Area-CodeHealth
Area-Commandline
Area-CookedRead
Area-DefApp
Area-Extensibility
Area-Fonts
Area-GroupPolicy
Area-i18n
Area-Input
Area-Interaction
Area-Interop
Area-Localization
Area-Output
Area-Performance
Area-Portable
Area-Quality
Area-Remoting
Area-Rendering
Area-Schema
Area-Server
Area-Settings
Area-SettingsUI
Area-ShellExtension
Area-ShellExtension
Area-ShellExtension
Area-Suggestions
Area-Suggestions
Area-TerminalConnection
Area-TerminalControl
Area-Theming
Area-UserInterface
Area-VT
Area-Windowing
Area-WPFControl
AutoMerge
Blocking-Ingestion
Culprit-Centennial
Culprit-WinUI
Disability-All
Disability-Blind
Disability-LowVision
Disability-Mobility
External-Blocked-WinUI3
Fixed
Gathering-Data
good first issue
HCL-E+D
HCL-WindowsTerminal
Help Wanted
Impact-Compatibility
Impact-Compliance
Impact-Correctness
Impact-Visual
In-PR
InclusionBacklog
InclusionBacklog-Windows TerminalWin32
InclusionCommitted-202206
Issue-Bug
Issue-Docs
Issue-Feature
Issue-Feature
Issue-Question
Issue-Samples
Issue-Scenario
Issue-Task
Needs-Attention
Needs-Author-Feedback
Needs-Bisect
Needs-Discussion
Needs-Repro
Needs-Tag-Fix
Needs-Tag-Fix
Needs-Triage
No-Recent-Activity
Priority-0
Priority-1
Priority-2
Priority-3
Product-Cmd.exe
Product-Colortool
Product-Colortool
Product-Colortool
Product-Conhost
Product-Conpty
Product-Meta
Product-Powershell
Product-Terminal
Product-WSL
pull-request
Mirrored from GitHub Pull Request
 Resolution-Answered
Resolution-By-Design
Resolution-Duplicate
Resolution-External
Resolution-Fix-Available
Resolution-Fix-Committed
Resolution-No-Repro
Resolution-Won't-Fix
Severity-Blocking
Severity-Crash
Severity-DataLoss
spam
this-will-be-a-breaking-change
Tracking-External
WindowsTerminal_Win32
Work-Item
zAskModeBug
zInbox-Bug
No Label Area-TerminalControl Help Wanted Issue-Task Needs-Tag-Fix Product-Terminal Resolution-Fix-Committed
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
claunia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/terminal#2736
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?