gCDEmu
v.1.5.0
~~~~~~~~~~~~

This is gCDEmu, a Gtk+ based GUI for controlling CDEmu daemon. It is part of the
userspace-cdemu suite, a free, GPL CD/DVD-ROM device emulator for linux.

It provides a graphic interface that allows performing the key tasks related to
controlling the CDEmu daemon, such as loading and unloading devices, displaying
devices' status and retrieving/setting devices' debug masks.

In addition, it listens to signals emitted by CDEmu daemon and provides
notifications via libnotify (provided that python bindings are installed).


Requirements:
~~~~~~~~~~~~~

 - python 2.4 or newer
 - PyGObject 3.0.0 or newer; (gtk-3, gobject and glib modules are required)
 - intltool

 - libnotify (optional)


Installation:
~~~~~~~~~~~~~

Installation process is generic ./configure, make, make install as described in
INSTALL file.


Note that if during make, you get the following error:
    make[1]: Entering directory `/tmp/gcdemu-1.1.0/po'
    file=`echo sl | sed 's,.*/,,'`.gmo \
    && rm -f $file && -o $file sl.po
    /bin/sh: -o: not found
    make[1]: *** [sl.gmo] Error 127
it means you don't have intltool installed.


Configuration:
~~~~~~~~~~~~~~
The application can be configured via several GConf keys that can be found under
/apps/gcdemu/prefs. While some of the settings can be altered directly from gCDEmu,
for altering the more advanced settings, an editor such as gconf-editor is required.

The configuration keys are:

 * show_notifications: a boolean value indicating whether gCDEmu should display
    notifications for events such as daemon start/stop and changes made
    to devices. This options can be altered from the application's context
    menu. Default value: true

 * use_system_bus: a boolean value indicating whether gCDEmu should use the
    system bus to connect to the daemon. This option can be altered from
    the application's context menu. Default value: false

 * icon_name: a string containing the name of the icon to show in the system tray.
    The corresponding pixmap should be installed in the standard pixmap path
    (such as /usr/share/pixmaps; the list of used search paths can be obtained
    by gtk.IconTheme().get_search_path()). Note: the name should be provided
    without the suffix. If invalid name is specified, the theme-specific icon
    for missing image will be shown. Default value: gcdemu

 * daemon_autostart: a boolean value indicating whether gCDEmu should, after
        connecting to the bus, attempt to start the CDEmu daemon (if it's not
        already running). This is done using D-BUS service facility and requires
        the daemon's .service files to be installed for the appropriate bus.
        Default value: True

 * icon_policy: a string value indicating the gCDEmu's icon display policy. Valid
        values are 'always', 'never' and 'when_connected'. With, 'always', icon
        is always shown; with 'never', it is never shown (and essentially renders
        the application useless). With 'when_connected', the icon is shown only
        when gCDEmu is connected to the CDEmu daemon.


Troubleshooting:
~~~~~~~~~~~~~~~~

Q: gCDEmu's tray icon is greyed and the applet does nothing!
A: Greyed-out icon means that the applet failed to connect to the CDEmu daemon.
   Please make sure the daemon is running and that you're connecting via
   appropriate bus.


A note on encrypted images and password supplying:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As of version 1.2.0, CDEmu daemon offers support for encrypted images. When password
is required to load an image, gCDEmu will prompt for it and then send it to daemon.

NOTE, HOWEVER, THAT THE PASSWORD IS SENT OVER D-BUS IN A PLAIN STRING FORM, WITHOUT
ANY PROTECTION. DEPENDING ON YOUR PRIVACY CONCERNS YOU MIGHT WISH TO AVOID LOADING
SUCH IMAGES.

On gCDEmu and Unity/GNOME Shell:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Both Unity and GNOME Shell by default put only icons from a selected few
applications in the system tray on the top panel, while the rest of the icons
end up in the so called message tray on the bottom panel.

If you wish to put the gCDEmu icon in the top panel's system tray, follow the
instructions below. Note that the instructions are not applicable only to gCDEmu,
but to any application with systray icon.


Unity:
------
In Unity, you need to whitelist the gCDEmu icon. This can be done either by adding
'gcdemu' to the list of applications that are whitelisted by default:

gsettings set com.canonical.Unity.Panel systray-whitelist "['JavaEmbeddedFrame', 'Mumble', 'Wine', 'Skype', 'hp-systray', 'gcdemu']"

or whitelisting all the applications:

gsettings set com.canonical.Unity.Panel systray-whitelist "['all']"

Restart Unity (either relog or use 'unity --replace').


GNOME Shell:
------------
Moving the gCDEmu icon to system tray in GNOME Shell requires a bit more work.

First, get and install the IconManager shell extension written by Jakub Krajniak.
The git source tree can be found at:
https://github.com/MrTheodor/gnome-shell-ext-icon-manager
Make sure you get version that's compatible with your GNOME Shell version! At
the time of writing, the repository's head is compatible with GNOME Shell 3.2;
if you are using an older version, find the appropriate version in the history.
Or, if possible, find the packaged version for your distribution (e.g. in Fedora,
the package is called gnome-shell-extension-icon-manager).

If using GNOME Shell 3.2, you must enable the extension before it can be used.
Either use gnome-tweak-tool, or use the following command:

gsettings set org.gnome.shell enabled-extensions "['icon-manager@krajniak.info']"

(Please note that the above command overwrites the currently enabled extensions,
so you should first get the list, add the above mentioned extension to it, and
then set it. It is generally easier to use gnome-tweak-tool...)

Now, similarly as with Unity, you need to add gcdemu to the list of applications
that should have their icons displayed in the system tray:

gsettings set org.gnome.shell.extensions.icon-manager top-bar "['gcdemu']"

Alternatively, you can install dconf-editor and use it to edit the key:
'/org/gnome/shell/extensions/icon-manager/top-bar'

Reload the GNOME Shell (press Alt+F2 and enter "r").


Contact information:
~~~~~~~~~~~~~~~~~~~~

CDEmu project's web page: http://cdemu.sourceforge.net
CDEmu project's mailing list: cdemu-devel@lists.sourceforge.net

Author can be directly contacted via e-mail address listed in AUTHORS file.
