Metadata-Version: 2.1
Name: ruamel.bws
Version: 0.4.1
Summary: browser restore to workspace
Home-page: https://sourceforge.net/p/ruamel-bws/code/ci/default/tree
Author: Anthon van der Neut
Author-email: a.van.der.neut@ruamel.eu
License: MIT license
Keywords: browser multiple workspace restore
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Requires-Python: >=3
Description-Content-Type: text/x-rst
License-File: LICENSE


**********
ruamel.bws
**********


.. image:: https://sourceforge.net/p/ruamel-bws/code/ci/default/tree/_doc/_static/license.svg?format=raw
     :target: https://opensource.org/licenses/MIT

.. image:: https://sourceforge.net/p/ruamel-bws/code/ci/default/tree/_doc/_static/pypi.svg?format=raw
     :target: https://pypi.org/project/ruamel.bws

.. image:: https://sourceforge.net/p/oitnb/code/ci/default/tree/_doc/_static/oitnb.svg?format=raw
   :target: https://sourceforge.net/p/oitnb/code


The Problem
===========

On Linux, after a re-login, Firefox and Chrome can restore their
previous windows' contents and positions. However they do not normally
restore these windows in the different workspaces/desktops that you
may be using.

If the desktop manager implements workspaces by using offsets (wider or
higher than the desktop resolution) restoration works as offsets "push" the
window to the right workspace on restoration. Such a workspace setup often
implies you see a window that you moveover the edge of one workspace show up
on the next one. KDE seems to have used such a scheme in the period
2010-2013.

Browsers would need to be `EWMH
<https://en.wikipedia.org/wiki/Extended_Window_Manager_Hints>`_ aware, which
they currently aren't.

A partial solution
==================

Browser windows usually have the name of the page
visited in the title, which makes instances of the browser windows relatively
uniquely identifiable. Based on that, you can save the state of the browser
windows in a file, and restore windows with matching titles to the original
workspace.

This program will not work correctly if a browser window has the same title
on multiple workspaces and only has differing secondary tabs. If two, single
tab windows have the same title, they probably point to the same URL, and in
that case which one gets restored to what workspace, is less important (unless
the history makes a difference).

Installation
============

First, make sure your linux version has ``wmctrl`` installed.

You can use ``pip`` to install the program::

    pip install ruamel.bws

You can also install the
`configobj <http://www.voidspace.org.uk/python/configobj.html>`_ library
(with ``pip``) and directly download and use the main Python file.

Usage
=====

Run ``bws save`` to save the current browser windows, ``bws restore``
to restore the latest saved setup. Before restoring using ``bws
restore``, reopen the browser windows and select [Restore] as
necessary.

Chrome needs to be configured to allow restoring by selecting "Continue where
you left off", in the `settings menu
<chrome://settings/#startup-section-content>`_. Firefox always seems to ask
when a crash occured, but you can also explicitly `set the preferences
<about:preferences#general>`_ to "Show my windows and tabs from last time"

number of saved .bws files
++++++++++++++++++++++++++

The number of different old configurations saved, can be specified by
the ``--keep`` commandline option, or in the configuration file. It
is set to 10 by default. After saving a file ``bws`` compares the new
file to the previous one, **if the contents are the same, it deletes the new one 
and touches the previous one**. If there are more ``.bws`` files than the keep option
specifies, the oldest that are in excess of that are deleted.

From the filename of the `.bws` you can see when it was first saved, and
from it timestamp (``st_mtime``, when ``bws save`` was last run.

Configuration
=============

The program keeps configuration defaults and restore information in (by
default) ``~/.config/bws`` in ``bws.ini`` resp. ``*.bws`` files. Multiple
restore settings are kept (which might be a privacy issue for you), and ``bws list``
will show you which ones are kept (with a date-time-stamp). ``bws restore`` can take
an argument to select a specific "save"

The config file allows to expand the patterns that are matched on where
``/proc/PID/exe`` points to, to identify the windows for which information
needs saving. A minimum number of windows can be specified that are necessary
for restoring (in the configuration file or on the commandline; the
commandline overrules the configuration file). This minimum prevents saves of
browser windows when a single window is open, e.g. the one asking you for confirmation to
restore all previously opened windows.

Chrome
++++++

Chrome's executable used to be called ``chromium-browser`` and that is what you find 
in config files of pre-0.3.3 installations. You might want to upgrade and either
remove the ``bws.ini`` file (so it will be regenerated), or make the chrome entry read::

  [br-chrome]
  basenamestart = chromium-browser, chrome


Cron
====

I run ``bws`` from crontab file every five minutes like this::

  */5 *  *   *   *     DISPLAY=:0 /home/anthon/bin/bws save --check

the ``--check`` only works if the file specified with ``--unlock-file`` exists. This
defaults to ``/tmp/bws.restored`` (which is usually on a temporary filesystem, so
will not be availalbe after restart, thus preventing further saves).

Issuing ``bws restore`` removes this unlock file, unless you specify `--unlock`, which I do
on the last run, after Firefox has reloaded all pages, and restoring is complete..

This unlock-file prevents cron from writing save files that will eventually overwrite useful 
information from before a restart.

ToDo
====

- check windows position for multiple occuring same strings (assuming positions
  differ, this gives additional info for workspace determination)

----

Firefox
+++++++
https://bugzilla.mozilla.org/show_bug.cgi?id=372650
https://bugs.launchpad.net/ubuntu/+source/firefox/+bug/684982

Chrome
++++++
https://code.google.com/p/chromium/issues/detail?id=18596
https://groups.google.com/a/chromium.org/forum/#!topic/chromium-discuss/h8tY-p-gXIE

KDE used to work
++++++++++++++++

https://code.google.com/p/chromium/issues/detail?id=297864



