gCDEmu
2.1.1
~~~~~
Table of Contents:
~~~~~~~~~~~~~~~~~~
1. Introduction
2. Requirements
3. Installation
4. Configuration
5. Troubleshooting
6. A note on encrypted images and password supplying
7. On gCDEmu and Unity/GNOME Shell
7.1 Unity
7.2 GNOME Shell
8. Gtk Application and Ubuntu AppIndicator mode
9. Contact information
1. Introduction
~~~~~~~~~~~~~~~
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).
2. Requirements:
~~~~~~~~~~~~~~~~
- Python >= 2.6
- PyGObject >= 3.0.0 (gtk-3, gobject and glib modules are required)
- IntlTool >= 0.21
- GetText >= 0.15
- libnotify GIR files (optional)
- AppIndicator GIR files (optional)
3. Installation:
~~~~~~~~~~~~~~~~
Please read the INSTALL file.
4. Configuration:
~~~~~~~~~~~~~~~~~
The application can be configured via several GSettings keys that can be found under
/apps/gcdemu. While some of the settings can be altered directly from gCDEmu,
for altering the more advanced settings, an editor such as dconf-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-connected: a string containing the name of the icon to show in the
system tray when gCDEmu is connected to the CDEmu daemon. The string can
be either a stock icon name or a pixmap name. Default value: gcdemu-connected
* icon-disconnected: a string containing the name of the icon to show in the
system tray when gCDEmu is disconnected from the CDEmu daemon. The string can
be either a stock icon name or a pixmap name. Default value: gcdemu-disconnected
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.
* icon-disconnected: a string containing the name of the icon to show in the
system tray when gCDEmu is connected to the CDEmu daemon. The string can
be either a stock icon name or a pixmap name.
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-connected
* 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.
5. 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.
6. A note on encrypted images and password supplying:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
7. On gCDEmu and Unity/GNOME Shell:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NOTE: This applies only when running gCDEmu in Gtk application mode (see
next Section).
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.
7.1 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 (Press ALT+F2 and enter 'unity').
Alternatively see chapter 8 for AppIndicator information.
7.2 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 or newer, 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' or 'gnome-shell --replace').
8. Gtk Application and Ubuntu AppIndicator mode:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
gCDEmu can run as Ubuntu AppIndicator, as opposed to classic
Gtk Application mode. In Gtk Application mode, which is used by default,
gCDEmu displays a system tray icon, whose appearance depends on
the settings of your system (see Section 6).
On systems with AppIndicator support, it is possible to run gCDEmu in
AppIndicator mode, by specifying '--indicator' command-line switch.
Note that some GUI features, in particular right-click device load/unload
shortcut, are not supported in AppIndicator mode.
9. 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.
