This project is unmaintained and has been archived. Information on this page might be outdated and links below might not work anymore.

1. Frequently Asked Questions about gnome-screensaver

Contents

Frequently Asked Questions about gnome-screensaver

1.1. Why gnome-screensaver, what happened to xscreensaver?

gnome-screensaver is a new screensaver that can replace xscreensaver. It is designed to integrate well with the desktop and provide a control interface that is desktop neutral. It simplifies and streamlines the experience for the user and provides more capability for the system administrator and vendor.

It is designed to support:

a desktop neutral control interface via DBus
a desktop neutral and standard way to install and manage screensaver themes
switching users directly from the unlock dialog
allowing a system administrator to set a mandatory policy for any setting
a secure separation of user input processing and authentication from the screen locking window
a separation between the screensaver theme engine and the theme settings
integration with the desktop (themes, fonts, toolkit)
translation into many languages by the GNOME Translation Project
instantly applying settings changes

1.2. Have you read and understood http://www.jwz.org/xscreensaver/toolkits.html?

Yes. gnome-screensaver runs the screen lock password dialog in a separate process and embeds the interface using XEmbed. It maintains a keyboard grab on the toplevel window at all times. This way there is no transfer of grabs to cause a race condition. The screensaver daemon is currently using the GTK+ implementation of the XEmbed protocol. gnome-screensaver links to many more libraries than does xscreensaver. These libraries are a result of using DBUS, GTK+, and GConf. The actual code paths through these libraries are quite small and very well tested.

1.3. Can I use xscreensaver "hacks" with gnome-screensaver?

Yes. Any screensaver theme engines that support using the environment variable XSCREENSAVER_WINDOW should work without modification.

Actually, that seems to no longer be the case in GNOME3, after commit 76d2c9ff6acf4a98bfa1569a62fafe14e89f413e gnome-screensaver only seems to support blanking.

1.4. How come my xscreensaver "hacks" don't show up in the gnome-screensaver configuration tool?

gnome-screensaver uses standard desktop entry (.desktop) files to define the screensaver themes. Xscreensaver XML configuration files can be converted into .desktop files using the migrate-xscreensaver-config.sh script in the data directory of the gnome-screensaver sources has since been removed, see http://git.gnome.org/browse/gnome-screensaver/log/data/migrate-xscreensaver-config.sh.

1.5. Why doesn't the screensaver preferences tool allow me to change the settings for the theme?

We are trying to take a different approach. A gnome-screensaver theme is not directly equivalent to the xscreensaver concept of a "hack". Each gnome-screensaver theme is a combination of a "hack" (or theme engine) and a set of options. This is quite a different design. So, perhaps, a better question is how does one create a new theme for a pre-existing theme engine? For that please see the related section in this FAQ.

So, why use a design that separates the theme from the theme engine? There are many reasons for this approach. I'll try to explain some of them.

There are advantages for the user. It demands that themes simply work and that the defaults make sense. And in the case where no one set of defaults will work it is now possible to simply provide a related theme of a different name. In many cases it makes sense to have multiple themes for the same theme engine. Take for example the slideshow theme engine. Rather than have one slideshow theme which you can configure to look in certain places for images it is now possible to have many slideshow themes - each with a different focus. Or even install new ones!

This may even create a market for new or enhanced themes. I can imagine that such demand will quickly be satisfied by the many third party theme sites such as art.gnome.org.

There are also many advantages for the parent, system administrator, or system distributor.

Under the xscreensaver model the only form of control a parent, system administrator, or vendor had was to remove "hacks" from the system. There was no way to exercise control over any options or groups of options. If they didn't want their child to see pornography the only recourse was to remove web reading "hacks" from the system. If they didn't want someone to put "The CEO is a bastard" in rotating, 3D text on a publicly available computer the only option was to remove it form the system. You get the idea.

So, now it is possible to allow the theme engines but to add restrictions based on sets of parameters.

One of the side effects is that initially, by default, there are fewer options. That is until you go to a website and download and install the "Flickr Fireworks Tag Slideshow" theme.

There are also some technical reasons for the current behavior. gnome-screensaver native themes do not require configuration. So, the themes in question are actually xscreensaver "hacks". For these, gnome-screensaver provides compatibility. There are essentially two different types of xscreensaver "hacks": those that operate on data sources, those that do not operate on data sources. Examples of "hacks" that operate on data sources are: GLSlideshow, GLText, Zoom. Examples of "hacks" that do not operate on data sources are: Flurry, Fuzzy Flakes, Stoner View. It is my contention that xscreensaver "hacks" that operate on data sources have no sensible default configuration because they are really theme engines and not themes. These "hacks" may not be very compatible with gnome-screensaver at the moment.

When you talk about configuring xscreensaver "hacks" that operate on data sources you aren't really configuring the "hack" itself - you actually configure xscreensaver to provide data to these "hacks" via command line programs (xscreensaver-getimage-desktop, xscreensaver-getimage-file, xscreensaver-getimage-video, xscreensaver-text). This configuration is shared by all xscreensaver "hacks". One of the consequences of this is that you cannot use different data sources for different "hacks". Also, there is no way to specify that some data sources may be trusted and used and others may not. These are not behaviors that we want gnome-screensaver to copy.

All xscreensaver "hacks" store their configuration in the .xscreensaver file in the Home directory. While it is possible to provide default settings via app-defaults there is no way to specify mandatory settings. This way of doing things isn't ideal. One option might be to convert all "hacks" to use GConf. However, that is both impractical and problematic for establishing a freedesktop standard for screensaver themes.

xscreensaver "hacks" provide an XML file that is used by the screensaver framework to autogenerate a user interface. It appears that xscreensaver does not support including translations in these XML files. It does seem to attempt to translate the contents of these files on the fly but this only works with files that are included within xscreensaver because the translations have already been provided. There doesn't seem to be a way to support translation of third-party screensaver themes. It is not clear that is approach should be supported by gnome-screensaver or that would be appropriate for use in a freedesktop standard for screensaver themes.

1.6. What about settings for themes that are hardware dependent? They are really slow on old machines and really fast on fast machines.

I've been keeping an open mind about it. I just haven't heard a compelling reason for them yet.

I totally agree that these are real problems. These are actually very good examples of what we would like to fix.

There are a few reasons why fixing this by adding settings is not right. Settings should be machine and architecture independent. It is really bad if the user has to change a setting before they lock the screen on a machine with a different CPU. Not to mention that the average user will have no idea what speed the CPU and/or graphics card is. Nor will they have any idea what value to use for the screensaver speed even if they did know the CPU speed. The screensaver theme engine (aka "hack") is in the best position to determine what speed it should run at. If it does not do this correctly then it is a bug that we should fix.

1.7. How can I create a new theme for a pre-existing theme engine?

You may add or modify .desktop files in the gnome-screensaver theme directory on your system. You can determine the path for this location using:

pkg-config --variable themesdir gnome-screensaver

If you are using GNOME 2.16 or newer then you can also drag and drop any screensaver theme (.desktop) file onto the gnome-screensaver preferences dialog. The theme will be automatically installed for you.

There is work to be done to make this simpler. Ask how you can help.

1.8. The "Pictures folder" slideshow theme looks for images in ~/Pictures. Why isn't that translated into my language?

This is fixed in versions 2.19.1 or later. The slideshow theme engine now uses XDG User Dirs to find the Pictures folder.

Some previous discussion:

1.9. How can I switch users from the screensaver unlock dialog?

You can enable the fast user switching feature by setting the /apps/gnome-screensaver/user_switch_enabled GConf key to TRUE.

1.10. Can I have a logout button on the screensaver unlock dialog?

Yes. You can enable a logout button by setting the /apps/gnome-screensaver/logout_enabled GConf key to TRUE, the /apps/gnome-screensaver/logout_delay key to the number of minutes the screen must be locked before the logout option will appear, and the /apps/gnome-screensaver/logout_command key to the command string that will actually perform the logout without any interaction with the user.

If you have GNOME 2.18 or later you can set the /apps/gnome-screensaver/logout_command to "gnome-session-save --kill --silent".

1.11. Does gnome-screensaver support display power management features?

Yes. gnome-screensaver should work automatically with other desktop power management tools such as gnome-power-manager.

1.12. Why does the screensaver unlock dialog always think my password is invalid?

First, make sure that your caps lock key is not on. It may sound silly but this is actually one of the most common reasons for password authentication failure. gnome-screensaver will print a warning if it detects the caps lock key is on.

If you are using a vendor provided package please contact your vendor for help. If you have built gnome-screensaver from source then try the test-passwd command that is located in the src directory of the gnome-screensaver sources. There are typically two reasons for why this command can fail:

* If your system supports PAM authentication, the gnome-screensaver PAM setup may either not be installed or may be incorrect.

To determine if your system supports PAM, look at the summary that is printed at the end of the configure process. You may need to manually install the gnome-screensaver PAM configuration file into /etc/pam.d (GNU/Linux) or add it to /etc/pam.conf (Solaris). There is a warning message to this effect displayed when you do 'make install'. If you use SuSE or Novell GNU/Linux you may have to modify the PAM configuration file that is distributed with gnome-screensaver.

* If your system does not support PAM authentication, you may need to install gnome-screensaver-dialog as setuid to root

To determine if your system requires setuid to root, look at the summary that is printed at the end of the configure process. There is a warning message to this effect displayed when you do 'make install'.

1.13. Why doesn't my screen lock when I'm logged in as root?

gnome-screensaver will blank the screen but will not lock. This is for security reasons. Seriously, it is very unwise to login as root in the first place. Try logging in as an unprivileged user and using sudo or su instead.

1.14. I'm developing an application that has a fullscreen mode. Is there a way that I can disable the screensaver?

Yes. gnome-screensaver has a simple to use DBus API for this. The way it works is that your application will request that the screensaver activation on idle be "inhibited" until your application says that activation can be "allowed" or your application exits.

Please be warned that the gnome-screensaver DBus API is currently unstable and may change in the future. Nonetheless it should be useful and is documented in the documentation included with the gnome-screensaver sources. You can see an example of this in action in the Totem Movie Player sources.

1.15. I'm a systems administrator. How can I set policies for all users of my system?

You can set mandatory policies in GConf. Here are some typical policies for a "locked down" system:

gconftool-2 --direct \
  --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
  --type bool \
  --set /apps/gnome-screensaver/idle_activation_enabled true
gconftool-2 --direct \
  --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
  --type bool \
  --set /apps/gnome-screensaver/lock_enabled true
gconftool-2 --direct \
  --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
  --type string \
  --set /apps/gnome-screensaver/mode blank-only
gconftool-2 --direct \
  --config-source xml:readwrite:/etc/gconf/gconf.xml.mandatory \
  --type int \
  --set /apps/gnome-screensaver/idle_delay 10

You can find some more information at the following sources:

1.16. Is there a way to perform actions when the screensaver activates or deactivates? Or when the session becomes idle?

One way is to watch for the D-Bus signals from gnome-screensaver. Here's an example of how to perform actions when the screensaver activiates or deactivates using the Perl language:

my $cmd = "dbus-monitor --session \"type='signal',interface='org.gnome.ScreenSaver',member='ActiveChanged'\"";

open (IN, "$cmd |");

while (<IN>) {
    if (m/^\s+boolean true/) {
        print "*** Screensaver is active ***\n";
    } elsif (m/^\s+boolean false/) {
        print "*** Screensaver is no longer active ***\n";
    }
}

As for detecting idle state: SessionIdleChanged is long gone (2009) and it's not clear what replaced it (perhaps something from gnome-session).

1.17. How can I remove some themes from the list of themes shown in the preferences?

Eventually this feature will be added to the preferences dialog itself. But for now the not so elegant solution is to run the following from a command-line:

% PATH="${PATH}:`pkg-config --variable privlibexecdir gnome-screensaver`:/usr/libexec/xscreensaver" \
gmenu-simple-editor gnome-screensavers.menu

1.18. Something has gone wrong. What can I do?

Please submit a bug to report to GNOME Bugzilla under the gnome-screensaver product.

Please include in your report:

Your OS distribution name and version
The output of the "gnome-screensaver --version" command
Whether you have built gnome-screensaver yourself or are using a vendor supplied package
The diagnostic information from gnome-screensaver (described below)
The details of the problem and how to reproduce it
If the problem involves unlocking the screen, also include the output of the "test-passwd" command that is included in the gnome-screensaver sources.

It is important to include diagnostic information obtained while reproducing the problem. You can get diagnostic information from the following:

gnome-screensaver-command --exit
gnome-screensaver --no-daemon --debug

If the daemon crashes we will also need a stack trace. You can get one by doing the following:

Ensure that you have debug info packages installed - see http://live.gnome.org/GettingTraces for help
Log in to your GNOME session as usual
Use SSH or a virtual console to login to the system separately
Run http://cvs.gnome.org/viewcvs/*checkout*/gnome-screensaver/src/debug-screensaver.sh
At the "(gdb) " prompt type "run"

Then reproduce the problem and when it crashes:

(gdb) set logging on
(gdb) bt
(gdb) set logging off

Then attach the generated gdb.txt file to a bug report.

More information can be found at http://live.gnome.org/GettingTraces.

1.19. Can I embed an on-screen keyboard for use with mobile devices?

Yes. A software keyboard that supports XEmbed should work. Here is one example:

Install libfakekey http://svn.o-hand.com/view/matchbox/trunk/libfakekey/
Install matchbox-keyboard http://projects.o-hand.com/matchbox/?p=1
set /apps/gnome-screensaver/embedded_keyboard_enable=TRUE
set /apps/gnome-screensaver/embedded_keyboard_command="matchbox-keyboard --xid"

And it looks something like this.

1.20. I want to write a screensaver theme, how do I do that?

You can either write a native gnome-screensaver, or an xscreensaver one. For the latter, follow the instructions in the xscreensaver FAQ, or you can write a stand-alone Gtk+ application, using the GsThemeWindow from gnome-screensaver for your top-level window.

A couple of things to bear in mind:

Your screensaver will not play if the binary isn't in a known location (see the find_command() function in gs-theme-manager.c)
Make sure your application does not eat any mouse or keyboard events, gnome-screensaver captures those to display the unlock dialogue.
Make sure your application behaves well when resizing (for the preferences dialogue) or when hidden and shown again (when cancelling the unlock for example)