Debian Codegraph @

workbench/README

raw
1 =========
2 Workbench
3 =========
4
5 .. contents::
6
7 About
8 =====
9
10 The Workbench plugin is an extension that makes it possible to manage
11 multiple projects in geany. You can add geany projects to a workbench.
12 From there you can add directories to the project to manage the files
13 belonging to the project.
14
15 Usage
16 =====
17
18 Enabling the plugin
19 -------------------
20 The plugin can be enabled in the plugin manager. After enabling the plugin
21 a new tab will be displayed in the Sidebar. There will also be a new entry
22 in the "Tools" menu. Both are labeled "Workbench".
23
24 The Workbench menu
25 ------------------
26 The Workbench menu is the starting point for creating your first workbench.
27 Choose "New" from the menu to create your workbench file. Workbench files
28 use the prefix ".geanywb". Just like Geany project files they are also
29 simple text files containing key-value pairs.
30
31 The complete managment of the Workbench file is done using the Workbench
32 menu:
33
34 **Item "New"**
35 As explained above, creates a new Workbench.
36 **Item "Open"**
37 Open a Workbench.
38 **Item "Settings"**
39 Open the Workbench settings dialog. After the settings have been
40 confirmed with "OK" they will be written back to the workbench file
41 (if any value was changed).
42 **Item "Search projects"**
43 Search for projects to add them to the Workbench. This lets the user
44 select a directory to search through. The directory and it's sub-directories
45 are scanned for project files (".geany"). All found files are listed and
46 after scanning is done the user can select the projects which shall be
47 added to the Workbench.
48 **Item "Close"**
49 Closes the opened Workbench.
50
51 The new Workbench
52 -----------------
53 A newly created Workbench is completely empty. In the Workbench tab of
54 the sidebar you should see the hint "Add a project using the context
55 menu". Anything which is dealing with projects and their Workbench
56 related settings is done using the context menu on the sidebar. Some
57 items in the context menu will only be active if you right click inside
58 a project, directory or bookmark.
59
60 The Workbench context menu
61 --------------------------
62
63 These are the available items:
64
65 **Add project**
66 Add an existing Geany project to the Workbench. Create your projects
67 with Geany. The Workbench plugin does not help you with that. After
68 adding a project you need to save the workbench settings by selecting
69 "Workbench / Save" in the menubar.
70
71 **Remove project**
72 Remove the project from the Workbench. It is only available if you
73 right clicked inside of a project. After removing a project you need
74 to save the workbench settings by selecting "Workbench / Save" in the
75 menubar.
76
77 **Fold/unfold project**
78 Fold or unfold the items belonging to the project. It is only available
79 if you right clicked inside of a project.
80
81 **Add directory**
82 Add a directory to the project. It is only available
83 if you right clicked inside of a project. After selecting it a dialog
84 will be opened. Choose the directory which shall be added. After that
85 the directory will be shown inside the project folder. After adding a
86 new directory, all files and sub-directories beneath the directory will be
87 displayed. See "Directory settings" for more information.
88
89 **Remove directory**
90 Remove the directory from the project. It is only available if you
91 right clicked inside of a project directory.
92
93 **Rescan directory**
94 Rescan the directory for files and update the sidebar accordingly.
95 It is only available if you right clicked inside of a project directory.
96 If the content of a directory changes, e.g. a new file is added, then
97 the new file will only be visible in the sidebar after a rescan.
98
99 **Directory settings**
100 Select this item to change the directory settings. It is only available
101 if you right clicked inside of a project directory. In the directory
102 settings you can set filters which control the files and sub-directories
103 that will be displayed or not. You can choose between a filter mechanism
104 controlled by the workbench plugin or controlled by git. In the later case
105 the .gitignore settings decide which files are displayed and which not.
106 This option is only available if the directory is/contains a git
107 repository.
108
109 **Fold/unfold directory**
110 Fold or unfold the items belonging to the directory. It is only available
111 if you right clicked inside of a directory.
112
113 **Unfold All**
114 Select this item to unfold all projects, directories and sub-directories.
115
116 **Collapse All**
117 Select this item to collpase/fold all projects, directories and sub-directories.
118
119 **Add to Workbench Bookmarks**
120 Add the file to the Workbench Bookmarks. It is only available
121 if you right clicked on a file. After adding a file to the Workbench
122 bookmarks a ribbon will be shown for the file in the Workbench sidebar
123 tab in front of the first project. Clicking on it will open the file.
124 Workbench bookmarks give you quick access to files which you often need.
125
126 **Add to Project Bookmarks**
127 Add the file to the Project Bookmarks. It is only available
128 if you right clicked on a file. After adding a file to the Project
129 bookmarks a ribbon will be shown for the file in the Workbench sidebar
130 tab in front of the first directory of the project. Clicking on it will
131 open the file. Project bookmarks give you quick access to files which
132 you often need in that project.
133
134 **Remove from Bookmarks**
135 Remove file from the Workbench or project bookmarks. It is only available
136 if you right clicked on a bookmark.
137
138 **Create file here...**
139 Select this item to create a new file at the current selected position
140 in the file tree. Available since version 1.02 of the workbench plugin.
141
142 **Create directory here...**
143 Select this item to create a new directory at the current selected position
144 in the file tree. Available since version 1.02 of the workbench plugin.
145
146 The Workbench settings
147 ----------------------
148 The following settings exist for a workbench:
149
150 **Rescan all projects on open**
151 If the option is activated (default), then all projects will be re-scanned
152 on opening of a workbench.
153
154 **Enable live update**
155 If the option is activated (default), then the list of files and the sidebar
156 will be updated automatically if a file or directory is created, removed or renamed.
157 A manual re-scan is not required if the option is enabled. This feature is available
158 since version 1.03 of the workbench plugin. If you open a workbench file
159 which has been created with an older version of the workbench plugin
160 then the option will be added with value "activated".
161
162 **Expand on hover**
163 If the option is activated, then a tree node in the sidebar
164 will be expanded or collapsed by hovering over it with the mouse cursor.
165
166 **Enable tree lines**
167 If the option is activated, lines will be drawn between the nodes in
168 the sidebar tree.
169
170 Live update
171 -----------
172 From version 1.03 on the workbench plugin supports an automatic live update
173 of the file list and the sidebar.
174
175 This feature will only work if your system supports directory file monitoring.
176 If the workbench plugin cannot setup file monitoring for a directory then it
177 will output a message in the message window. The message has the following form::
178
179 Could not setup file monitoring for directory: "exampledir". Error: <some error message>
180
181 Styling the sidebar
182 -------------------
183
184 On linux based systems using GTK3 the workbench sidebar can be styled using CSS.
185 For general information on how to setup CSS with Geany please see the manual under
186 https://www.geany.org/manual/current/index.html#customizing-geany-s-appearance-using-gtk-3-css.
187
188 To style the workbench sidebar use the CSS ID *"workbench"*. Here is a small
189 example::
190
191 /* Style the label over the treeview. */
192 #workbench label {
193 color: black;
194 background-color: silver;
195 border-bottom: 2px solid red;
196 font-size: 20pt;
197 }
198
199 /* Style the treeview: the border-color specifies the color of the
200 treeview lines (if enabled in the workbench settings). */
201 #workbench treeview {
202 color: black;
203 background-color: linen;
204 border-color: darkviolet;
205 font-size: 12pt;
206 }
207
208 /* The following changes the text and background color for the selected
209 row in the workbench treeview. */
210 #workbench treeview:selected {
211 color: white;
212 background-color: red;
213 }
214
215 /* The following changes the text and background color for a row in the
216 workbench treeview if the user hovers over it with the mouse pointer. */
217 #workbench treeview:hover {
218 color: white;
219 background-color: orange;
220 }
221
222 Known issues
223 ============
224
225 None.
226
227 License
228 =======
229
230 The Workbench plugin is distributed under the terms of the GNU General
231 Public License as published by the Free Software Foundation; either
232 version 2 of the License, or (at your option) any later version. A copy
233 of this license can be found in the file COPYING included with the source
234 code of this program.
235
236 Downloads
237 =========
238
239 The Workbench plugin is part of the combined Geany Plugins release.
240 For more information and downloads, please visit
241 http://plugins.geany.org/geany-plugins/
242
243 Development Code
244 ================
245
246 Get the code from::
247
248 git clone https://github.com/geany/geany-plugins.git
249
250 Ideas, questions, patches and bug reports
251 =========================================
252
253 Please post any ideas, feature requests, questions and bugs in the
254 github issue tracker.
255
256 History
257 =======
258
259 This is a short release history showing the major changes:
260
261 **1.09:**
262 Added option to let git decide which files to display
263 **1.08:**
264 Auto-save project on change
265 **1.07:**
266 Added option to enable or disable tree lines
267 **1.06:**
268 Save workbench settings immediately
269 **1.05:**
270 Added option "Expand on hover"
271 **1.04:**
272 Use simple/old file monitor events only (remove dependency of GLib version 2.46)
273 **1.03:**
274 Support live update
275 **1.02:**
276 Added "Create file here..."/"Create directory here..."
277 **1.01:**
278 Fixed not closed file handles on directory scanning (thanks to techee). Fixes #607.
279 **1.00:**
280 Created plugin