nextcloud-desktop/doc/visualtour.rst

Visual Tour
===========

.. index:: visual tour, usage

ownCloud Client stays in the background, and is visible as an
icon in your system tray (Windows, KDE), status bar (Mac OS X)
or notification area (Ubuntu), like so:

.. image:: images/icon.png

If a setup is still required, it will open the setup. Otherwise, the
main menu is opened, which provides several options and displays
progress information:

.. image:: images/menu.png

Here is an explanation of the individual items in the menu:

* ``Open ownCloud in browser``: Opens the ownCloud web interface
* ``Open folder 'ownCloud'``: Opens the local folder. If you have
  defined multiple sync targets, you should see multiple entries
  here.
* **Disk space indicator**: Shows how much space is used up on the server.
* Operation indicator: Shows the status of the current sync process, or
  ``Up to date`` if server and client are in sync.
* **Recent Changes**: shows the last six files modified by sync operations,
  and provides access to the Sync Protocol, which lists all changes
  since the last restart of ownCloud Client.
* ``Settings...``: provides access to the settings menu.
* ``Help``: Opens a browser to display this help.
* ``Quit ownCloud``: Quits ownCloud, ending a currently running sync run.

The settings dialog is split up in three categories: ``Account Settings``,
``General Settings`` and ``Network Settings``:

Account Settings
~~~~~~~~~~~~~~~~

.. index:: account settings, user, password, Server URL

The ``Account Settings`` tab provides an executive summary about the synced
folders in your account and allows to modify them. It also provides a more
detailed report about the storage usage. Finally, it allows to change
the files that ownCloud Client should ignore (for details, see the
``Ignored Files Editor`` section below), and to modify various aspects
of the current account settings, such as user name, password and server URL.

.. image:: images/settings_account.png
   :scale: 50 %

General Settings
~~~~~~~~~~~~~~~~

.. index:: general settings, auto start, startup, desktop notifications

The tab provides several useful options:

.. image:: images/settings_general.png
   :scale: 50 %

* **Launch on System Startup**: This option is automatically activated
  once a user has conimaged his account. Unchecking the box will cause
  ownCloud client to not launch on startup for a particular user.
* **Show Desktop Nofications**: Do not show bubble notifications whenever
  a set of sync operations has been performed.
* **Use Monochrome Icons**: Use less obstrusive icons. Especially useful
  on Mac OS.

The acout menu provides information about authors as well as detailed
information about the build conditions. Those are particularly valuable
when filing a bug report.

Network Settings
~~~~~~~~~~~~~~~~

.. index:: proxy settings, SOCKS, bandwith, throttling, limiting

This tab consollidates ``Proxy Settings`` and ``Bandwith Limiting``:

.. image:: images/settings_network.png
   :scale: 50 %

Proxy Settings
^^^^^^^^^^^^^^

* ``No Proxy``: Check this if ownCloud Client should circumvent the default
  proxy conimaged on the system.
* ``Use system proxy``: Default, will follow the systems proxy settings.
  On Linux, this will only pick up the value of the variable ``http_proxy``.
* ``Specify proxy manually as``: Allows to specify custom proxy settings.
  If you require to go through a HTTP(S) proxy server such as Squid or Microsoft
  Forefront TMG, pick ``HTTP(S)``. ``SOCKSv5`` on the other hand is particulary
  useful in special company LAN setups, or in combination with the OpenSSH
  dynamic application level forwarding feature (see ``ssh -D``).
* ``Host``: Enter the host name or IP address of your proxy server, followed
  by the port number. HTTP proxies usually listen on Ports 8080 (default) or
  3128. SOCKS server usually listen on port 1080.
* ``Proxy Server requires authentication``: Should be checked if the proxy
  server does not allow anonymous usage. If you check this option, you must
  provide username and password in the fields below, or ownless Cloud will no
  longer be able to connect successfully.

Bandwidth Limiting
^^^^^^^^^^^^^^^^^^

The ``Download Bandwidth`` (i.e. the bandwidth available for data flowing
from the ownCloud Server to the client) can be either ``Unlimited``
(the default), or limited to a custom value, specified in bytes

The ``Upload Bandwith`` (i.e. the bandwith available for data flowing
from the ownCloud Client to the server) additionally has the option
to ``Limit automatically``: When this option is checked, the ownCloud
Client will surrender available upstream bandwith to other applications.
Use this option if you expirience problems with real time communication,
such as Skype or other VoIP software, in conjunction with ownCloud Client.
This is commonly the case with asymmetric internet connection, such as
certain DSL lines with very limited upstream capacity.

ownCloud Client will pick up changes immediately, but ongoing operations
will finish using the old settings.

The Sync Protocol
~~~~~~~~~~~~~~~~~

.. index:: sync protocol

The ``Sync Protocol`` window, which can be invoked from either from the main
menu (``Recent Changes`` -> ``Details...``) or the ``Account Settings``
(``Info`` button), will provide you with an in-depth summary of the recent
sync activity. It will also show files that have not been synched (ignored
files). Those are ignored either because they are listed in the ignored
files list (see ``Ignored Files Editor`` section below), or because they
cannot be synced in a cross-platform manner because they contain special
characters that cannot be stored on certain file systems.

.. image:: images/sync_protocol.png
   :scale: 50 %

.. _ignoredFilesEditor-label:

The Ignored Files Editor
~~~~~~~~~~~~~~~~~~~~~~~~

.. index:: ignored files, exclude files, pattern

The ignored files editor allows adding patterns for files or directories
that should be excluded from the sync process. Next to normal characters,
wildcards can be used to match an arbitrary number of characters, designated
by an asterisk (``*``) or a single character, designated by a question mark
(``?``).

Global defaults cannot be directly modified within the editor. Hovering
with the mouse will reveal the location of the global exclude definition
file.

In addition to this list, ownCloud Client always excludes files with
characters that cannot be synched down to other file systems,
see :ref:`ignored-files-label`.

.. note:: Modifying the global exclude definition file might render the
   client unusable or cause undesired behavior.

.. note:: Custom entries are currently not validated for syntactical
   correctness by the editor, but might fail to load correctly.

.. image:: images/ignored_files_editor.png
   :scale: 50%

Pattern Matching
^^^^^^^^^^^^^^^^

To match file names against the exclude patterns, the unix standard C
library function fnmatch is used. It checks the filename against the pattern
using standard shell wildcard pattern matching. Check `The opengroup website
<http://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_01>`
for the gory details.

The path that is checked is the relative path unter the sync root directory.

Examples:
^^^^^^^^^
+-----------+------------------------------+
| Pattern   | Matches                      |
+===========+==============================+
| ``~$*``   | ``~$foo``, ``~$example.doc`` |
+-----------+------------------------------+
| ``fl?p``  | ``flip``, ``flap``           |
+-----------+------------------------------+