TIP

Resize an image to fit in a container

When adding an ImageComponent, the application will automatically scale it down or up while keeping its ratio until its width or height reaches the container bounds. This ensures that the image is shown in full and not distorted.

Thus, when the window height or width is changed - by moving one corner for example - the image might not fit completely inside its container boundaries, and some background will be visible. This might happen when the image has reached its greatest size, and cannot be scaled up without degrading the quality. Another possibility is that the image has a height with the Height key set to a value: if the container width is updated, the application will try to keep the image height unchanged, which also enforces the image width to not change.

So, when dealing with images, here are a few tips.


Make the window non resizable with a fixed size

This way, you can more easily work on the images to make them fit perfectly inside a container, as explained below. To do so, the Window section is our best ally. Change the key IsResizable to false if the window is in "Simple" OnScreen mode. Otherwise, the window is automatically unresizable.


Choose a window size

When the size of the window is fixed, it automatically uses the MaximumSize key as the size to use. So you can edit it to choose the window size. For example, we define here a window of 1280x960 with a size dictionary.

<key>Window</key>
<dict>
	<key>MaximumSize</key>
	<dict>
		<key>Height</key>
		<integer>960</integer>
		<key>Width</key>
		<integer>1280</integer>
	</dict>
	<key>IsResizable</key>
	<false/>
	<key>OnScreen</key>
	<string>Simple</string>
</dict>


Choose an image size

As the window size is fixed, you can now try several ratios for your image. If the window size is the priority and the image does not fit properly because of its ratio, you can try to crop it. Otherwise, if you want the image to remain unchanged, you can come back to the previous step to give your window a different size to find the best one to hold your image.

As mentionned, the image will be set a maximum height of 200 points. Thus, the image might still be scaled down and the width not be correct. So to make sure the image width is the right one, you can set its Height key value to the real height of the image to get the real image ratio, or simply use the ShouldFillSpace key.

Equation

If you want more granularity, here is the formulae to find a container width depending on the window's width:

( WindowWidth
- (ContainersCount + 1) * padding
-  ContainersCount * ContainerBorderWidth * 2 )
/ ContainersCount
So with the default values in points, as padding = 15, and ContainerBorderWidth = 1, this gives us:
( WindowWidth
- (ContainersCount + 1) * 15
-  ContainersCount * 2)
/ ContainersCount

Retina displays use two pixels for a point. This means that a width of 1280 points is in fact 1280 * 2 = 2560 pixels. The same is applied for other values like the padding or the ContainerBorderWidth in the formulae. Thus the formulae becomes:

( WindowWidth * 2
- (ContainersCount + 1) * padding * 2
-  ContainersCount * ContainerBorderWidth * 2 * 2 )
/ ContainersCount
And with the default values:
( WindowWidth * 2
- (ContainersCount + 1) * 30
-  ContainersCount * 4 )
/ ContainersCount

So with a given WindowWith of 1280 points, two containers and a Retina display, this gives us:

( 1280 * 2
- 3 * 30
-  2 * 4 )
/ 2
Thus, a container width is here 1231 pixels.

Large containers

The formulae is a bit different whit two containers when one has a IsLarge key set to to true. Here is the formulae for the large container (whick takes 2/3 of the available width):

( WindowWidth * 2
- (ContainersCount + 1) * padding * 2
-  ContainersCount * ContainerBorderWidth * 2 * 2 )
* 2 / 3
As for the remaining "non-large" container:
( WindowWidth * 2
- (ContainersCount + 1) * padding * 2
-  ContainersCount * ContainerBorderWidth * 2 * 2 )
/ 3

Reverse the equation

Finally, if you want to find the window size to have your container width matching an image width, the equation - with pixels here - can be reversed:

ImageWidth * ContainersCount
+ ContainersCount * ContainersBorderWidth * 2 * 2
+ (ContainersCount + 1) * padding * 2
Then, do not forget to divide this width by 2 to retrieve it in points.


Go further