=========
Workbench
=========

.. contents::

About
=====

The Workbench plugin is an extension that makes it possible to manage
multiple projects in geany. You can add geany projects to a workbench.
From there you can add directories to the project to manage the files
belonging to the project.

Usage
=====

Enabling the plugin
-------------------
The plugin can be enabled in the plugin manager. After enabling the plugin
a new tab will be displayed in the Sidebar. There will also be a new entry
in the "Tools" menu. Both are labeled "Workbench".

The Workbench menu
------------------
The Workbench menu is the starting point for creating your first workbench.
Choose "New" from the menu to create your workbench file. Workbench files
use the prefix ".geanywb". Just like Geany project files they are also
simple text files containing key-value pairs.

The complete managment of the Workbench file is done using the Workbench
menu:

**Item "New"**
  As explained above, creates a new Workbench.
**Item "Open"**
  Open a Workbench.
**Item "Save"**
  Save the opened Workbench. This "only" saves any changes
  in the Workbench file. It does not save any changes of the projects
  belonging to the Workbench.
**Item "Settings"**
  Open the Workbench settings dialog.
**Item "Close"**
  Closes the opened Workbench.

The new Workbench
-----------------
A newly created Workbench is completely empty. In the Workbench tab of
the sidebar you should see the hint "Add a project using the context
menu". Anything which is dealing with projects and their Workbench
related settings is done using the context menu on the sidebar. Some
items in the context menu will only be active if you right click inside
a project, directory or bookmark.

The Workbench context menu
--------------------------

These are the available items:

**Add project**
  Add an existing Geany project to the Workbench. Create your projects
  with Geany. The Workbench plugin does not help you with that. After
  adding a project you need to save the workbench settings by selecting
  "Workbench / Save" in the menubar.

**Save project**
  Selecting this item will save the Workbench related project settings in
  the Geany project file. It is only available if you right clicked inside
  of a project. It will only save the settings of the project that you
  clicked on.

**Remove project**
  Remove the project from the Workbench. It is only available if you
  right clicked inside of a project.  After removing a project you need
  to save the workbench settings by selecting "Workbench / Save" in the
  menubar.

**Fold/unfold project**
  Fold or unfold the items belonging to the project. It is only available
  if you right clicked inside of a project.

**Add directory**
  Add a directory to the project. It is only available
  if you right clicked inside of a project. After selecting it a dialog
  will be opened. Choose the directory which shall be added. After that
  the directory will be shown inside the project folder. After adding a
  new directory, all files and sub-directories beneath the directory will be
  displayed. See "Directory settings" for more information.

**Remove directory**
  Remove the directory from the project. It is only available if you
  right clicked inside of a project directory.

**Rescan directory**
  Rescan the directory for files and update the sidebar accordingly.
  It is only available if you right clicked inside of a project directory.
  If the content of a directory changes, e.g. a new file is added, then
  the new file will only be visible in the sidebar after a rescan.

**Directory settings**
  Select this item to change the directory settings. It is only available
  if you right clicked inside of a project directory. In the directory
  settings you can set a filter which controls the files and sub-directories
  that will be displayed or not.

**Fold/unfold directory**
  Fold or unfold the items belonging to the directory. It is only available
  if you right clicked inside of a directory.

**Unfold All**
  Select this item to unfold all projects, directories and sub-directories.

**Collapse All**
  Select this item to collpase/fold all projects, directories and sub-directories.

**Add to Workbench Bookmarks**
  Add the file to the Workbench Bookmarks. It is only available
  if you right clicked on a file. After adding a file to the Workbench
  bookmarks a ribbon will be shown for the file in the Workbench sidebar
  tab in front of the first project. Clicking on it will open the file.
  Workbench bookmarks give you quick access to files which you often need.

**Add to Project Bookmarks**
  Add the file to the Project Bookmarks. It is only available
  if you right clicked on a file. After adding a file to the Project
  bookmarks a ribbon will be shown for the file in the Workbench sidebar
  tab in front of the first directory of the project. Clicking on it will
  open the file. Project bookmarks give you quick access to files which
  you often need in that project.

**Remove from Bookmarks**
  Remove file from the Workbench or project bookmarks. It is only available
  if you right clicked on a bookmark.

**Create file here...**
  Select this item to create a new file at the current selected position
  in the file tree. Available since version 1.02 of the workbench plugin.

**Create directory here...**
  Select this item to create a new directory at the current selected position
  in the file tree. Available since version 1.02 of the workbench plugin.

The Workbench settings
----------------------
The following settings exist for a workbench:

**Rescan all projects on open**
  If the option is activated (default), then all projects will be re-scanned
  on opening of a workbench.

**Enable live update**
  If the option is activated (default), then the list of files and the sidebar
  will be updated automatically if a file or directory is created, removed or renamed.
  A manual re-scan is not required if the option is enabled. This feature is available
  since version 1.03 of the workbench plugin. If you open a workbench file
  which has been created with an older version of the workbench plugin
  then the option will be added with value "activated".

Live update
-----------
From version 1.03 on the workbench plugin supports an automatic live update
of the file list and the sidebar.

This feature will only work if your system supports directory file monitoring.
If the workbench plugin cannot setup file monitoring for a directory then it
will output a message in the message window. The message has the following form::

    Could not setup file monitoring for directory: "exampledir". Error: <some error message>

Known issues
============

None.

License
=======

The Workbench plugin is distributed under the terms of the GNU General
Public License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.  A copy
of this license can be found in the file COPYING included with the source
code of this program.

Downloads
=========

The Workbench plugin is part of the combined Geany Plugins release.
For more information and downloads, please visit
http://plugins.geany.org/geany-plugins/

Development Code
================

Get the code from::

    git clone https://github.com/geany/geany-plugins.git

Ideas, questions, patches and bug reports
=========================================

Please post any ideas, feature requests, questions and bugs in the
github issue tracker.