gCDEmu
3.3.0
~~~~~

Table of Contents:
~~~~~~~~~~~~~~~~~~

1. Introduction
2. Requirements
3. Installation
4. Configuration
5. GtkApplication and AppIndicator mode
6. Troubleshooting
7. Contact information


1. Introduction
~~~~~~~~~~~~~~~

This is gCDEmu, a Gtk3-based GUI for controlling CDEmu daemon. It is part of the
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:
~~~~~~~~~~~~~~~~

 - CMake >= 3.16
 - IntlTool >= 0.21
 - GetText >= 0.15

 - Python >= 3.8
 - PyGObject >= 3.0.0

 - GLib, GObject, GIO >= 2.28 GIR
 - Gtk3 GIR
 - GdkPixbuf GIR

 - libnotify GIR (optional; for notifications)
 - AppIndicator3 GIR (optional; for AppIndicator mode)


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 instead of session bus to connect to the daemon. 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 is 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. Gtk Application and AppIndicator mode:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
gCDEmu can run in either GtkApplication mode or as AppIndicator. The
latter is available only if corresponding GIR files are installed.

GtkApplication mode:
* GtkStatusIcon is used to display gCDEmu icon
+ right-click device load/unload shortcut is supported
- does not implement the new systray specification, so it might not work
  in enviroments that require it, such as the new notification area on
  Cairo dock

AppIndicator mode:
* AppIndicator is used to display gCDEmu icon
- does not support right-click device load/unload shortcut
+ supports new systray specification, so it works with, for example, the
  new notification area on Cairo dock

Due to lack of support for the new systray specification in Gtk, the
AppIndicator mode is preferred, if available; gCDEmu attempts to load
AppIndicator libraries, and if it succeeds, it starts in AppIndicator
mode. Otherwise, GtkApplication mode is used.

This can be overriden using '--tray-mode=' command-line switch.


6. 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.


7. 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.
