TUTORIAL: Add a Custom Background in Phosh

I happened to see this very simple how-to, so I gave it a whirl, modifying the instructions to correspond to my L5 and selected background image:

Hat tip to foss2go and the original poster on reddit!

https://foss2go.com/how-to-add-a-custom-background-in-phosh/

Selected background image can be a .jpg or a .png, possibly other file types.

In the terminal, create the file gtk.css using any installed text editor: nano ~/.config/gtk-3.0/gtk.css . Alternately, you can create the file manually in the Files app.

Then add the following to the gtk.css file. (Change the path to point to your chosen image.)

/*
 * Set a background for the lockscreen.
 */
phosh-lockscreen, .phosh-lockshield {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/purism/Pictures/mybackground.jpg');
  background-size: cover;
  background-position: center;
}

/*
 * Set a background for the app grid.
 */
phosh-app-grid {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/purism/Pictures/mybackground.jpg');
  background-size: cover;
  background-position: center;
}

Next: sudo systemctl restart phosh

Selected image (compressed here to accommodate Discourse limitations):

Before:


After:



And yes, Screen Shot works even after you exit to the lockscreen. Cool.

28 Likes

Added to: https://source.puri.sm/Librem5/community-wiki/-/wikis/Tips-&-Tricks

5 Likes

I’m curious why a web scripting language is used to change the background in Phosh?

3 Likes

GNOME shell also uses CSS under the hood so I guess it just made sense to follow that… Wait till you find out, its also based on JavaScript :sweat_smile:

1 Like

… JavaScript? :unamused:

So… what about using Variety? For either regular wallpaper and/or lockscreen?
Or xscreensaver?

Nice ! I was wondering when they would implement this background capability !

You can also play with the transparency by changing all the 0.7 with a number from 0.0 (full transparency) to 1.0 (full opacity)
Here, it’s a linear-gradient effect so the first 0.7 is transparency starting on top, and the second 0.7 is transparency ending to bottom

And to make it more homogenous, you can also change the gnome background with

gsettings set org.gnome.desktop.background picture-uri file:///path/to/picture_file

(In byzantium, you have a graphical option in settings)

2 Likes

Yep. Here are two alternative transparency settings:

0.3

0.0

And this command sets the “desktop” background to the same picture:
gsettings set org.gnome.desktop.background picture-uri file:///home/purism/Pictures/mybackground.png:

I updated the tutorial in the wiki.

Edit: By the way, it’s kinda cool that some of the app icons, like Settings, Geary, Screen Shot, and Backups, have transparent parts where the background peeks through.

4 Likes

@2disbetter not web scriting but plain GTK CSS (which is of course is very similar to ‘web’ CSS). See: https://developer.gnome.org/gtk3/stable/chap-css-overview.html , you can look up style classes here: https://source.puri.sm/Librem5/phosh/-/blob/master/src/style.css . They’re not guaranteed to be stable btw (we don’t try to break them on purpose though).

1 Like

Since you need to restart Phosh, I’m guessing it’s not possible yet to automatically change the background based on orientation?

If I had more free time than I do, I’d be tempted to try to code that up. It sounds like an excellent entry-level community dev project: too much of a niche feature to warrant paid dev time, but not overly complex and still actually useful.

2 Likes

needs a blur parameter not transparency.

Still works in byzantium:



In Settings > Background, you can choose a wallpaper from the approximately 30 included images, or select a personal photo:

A pre-loaded background doesn’t get applied to the lockscreen or the app list/home page. But I suppose it would if you copy one of the images from /usr/share/backgrounds and point to it from the gtk stylesheet as in the OP.

By the way, you can swipe on-screen notifications away, even from the lockscreen:

5 Likes

What are the other possible values for these settings?
In Gnome Tweaks I had one of them set to ‘scaled’ (still have by the way).

Could setting the size to ‘cover’ lead to the image being too big, resulting in an oversized lockscreen in landscape orientation?

I’m not sure what other available settings there are, but I’m guessing they would be similar to what you see in a Debian/Ubuntu/Mint/etc. GUI for selecting background options: Tile, Zoom, Stretch, etc.
I think “cover” means fill the screen from edge to edge; I don’t know if the dimensions of the image (e.g. wider than the height) would cause it to go beyond the edges, but I suspect it would just distort and adapt to the screen size.

You can test with a landscape-oriented photo if you want.

Thanks, amarok.I will play around with it.

BTW, for my background, I started with an image that I first cropped to the screen dimensions.

Mine is too (it fits the portrait screen). But it blows up beyond that in landscape mode. I can’t recall it doing that when I had my backgrounds set in Gnome Tweaks (in which I had, and still have them set to ‘scaled’).
I do not know whether ‘scaled’ can be used in gtk.css as well (alas, no documentation).

Thanks for documenting this and keeping it up to date!

Note that with the transparency patches you will have your desktop background by default: https://social.librem.one/@agx/109902619533367879 - it’s then just the one you select via Settings then.

1 Like

Don’t forget to mention your cool Phosh blog post that shows how to change the GUI interactively…

It shows a great way to explore the CSS!

2 Likes

I also played a little bit around with backgrounds and will make a follow up tutorial. Why? Because I made a seamless picture for a full-screen-background image.


The lock-screen image was not perfectly designed (top and bottom), so it’s an issue of my picture, not of the technique, that there is a black stripe. I could look like the top of the desktop screen.

More pics from different views (click me)

It just has one downside. On Landscape it doesn’t match anymore, because images get scaled to double length each direction. Not sure, but I don’t think there is a way to fix this yet.

However, who want to get that advanced background, here is the guide:

First of all you have to find a picture that is big enough (and that will be not easy to find). It has to be 720 x 2832 pixel minimum. You also can try to find something half as big in both dimensions: 360 x 1418 pixel. But it will be a bit less sharp and you have to half all the numbers I will tell. As long as the dimensions are correctly also every other size would be okay, but it will make things even more hard to get it work.
I used stable diffusion to let my graphics card generate that image from my screenshots.

Okay, now we have to edit that gtk.css file from amaroks first post.

/*
 * Set a background for the lockscreen.
 */
phosh-lockscreen, .phosh-lockshield {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/purism/Pictures/MyLockScreenBackground.jpg');
  background-size: cover;
  background-position: center;
}
/*
 * Set a background for the app grid.
 */
phosh-app-grid {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/purism/Pictures/MyBackground.jpg');
  background-size: cover;
  background-position: center;
}
/*
 * Set a background for the top panel.
 */
phosh-top-panel {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/purism/Pictures/MyTopPanelBackground.jpg');
  background-size: cover;
  background-position: center;
}
/*
 * Set a background for the app-grid slider.
 */
phosh-home {
  background-image: linear-gradient(rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.7)),
                    url('file:///home/purism/Pictures/MyHomeBackground.jpg');
  background-size: cover;
  background-position: center;
}

As before, you are able to change directory and rgba-values. I myself created a folder “Backgrounds” in ~/Pictures and can setup new images just with replacing them.

That was the easy part. The next part needs precision, time and gimp (or something similar). We have to cut that one big picture into 4 pieces of the exact length and position. Each part has to be 720 x 1440 pixel (doesn’t matter how much will be displayed later) or any scale of 1:2 relation. But like I said before, it’s easier to have same numbers as I say.

Not cut parts in following positions:
Top panel image (also top of the image): pixel 1 - 1440
lockscreen image: 1392 - 2832
App-grid slider image: 1416 - 2856
App-grid image: 1446 - 2886

Wait: Did I say the image should be 2832 pixel high and I tell you to cut 2 images even longer than this? No worries, you can fill the bottom with what ever you want, it will be out of the screen and not be displayed. But it is important to get that length for the correct position and scale.

Now just name and copy all images to the directory as you wrote in your script. Finish your setup with one command sudo systemctl restart phosh (like amarok told before) or just restart your L5.

I guess you also can combine it with the real background (you can change in gnome settings), but I haven’t tried yet. But for those who just want the simple backgrounds like in the first tutorial, I also edited 2 other images to fit better to phoshs design (including better view in landscape mode):

Click me to view pictures


Turned pic 90° and cut it in a nice way that it makes still sense. Also faded into back on the top, but I did it in gimp, not in gtk.css file, because i needed more control and not just a linear gradient. .


Cut, changed color-curve-values, copied top of image, mirrored it and used stamp tool to look more natural to expend image. At least I added a black-transparency gradient to the top that it fades out to my “favorite apps” section.


If I would like to have a sharp picture on landscape, I would have to scale it up to 2880 x 1440 pixel (could do it with stable diffusion on my graphics card), but it would also be double as big on normal screen.

2 Likes

Just note that you are very-limited to put any wallpaper on background on mobile otherwise will look very-bad overall, i really recommend do not change the wallpaper in background on phosh to keep the good limited look. I just say… and i really nervous for the future phosh & “opensourced-@guido.gunther” ui desing. :grimacing: @dos