« back to all changes in this revision
Viewing changes to debian/README.Debian
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Paul Hedderly
- Date: 2002-03-18 14:02:52 UTC
- Revision ID: james.westby@ubuntu.com-20020318140252-h2icfj2rv2vxsb3c
Tags: upstream-0.1.8
Import upstream version 0.1.8
- files added:
- data
- data/themes
- debian
- doc
- packaging
- packaging/ipkg
- src
- util
added
removed
debian/README.Debian
1
Matchbox X11 Window Manager Documentation
2
3
Matthew Allum
4
5
Copyright � 2002 by Matthew Allum <mallum@handhelds.org>
6
7
-------------------------------------------------------------------------------
8
9
Table of Contents
10
1. Introduction
11
2. Screenshots
12
3. Usage
13
14
3.1. Launching Matchbox
15
3.2. Configuration.
16
3.3. Themes
17
3.4. Shortcut keys.
18
19
4. Included Utilities.
20
5. Compiling and Installing.
21
6. Availability
22
7. FAQ
23
24
7.1. Where's the app launcher menu ?
25
7.2. How do I get that keyboard icon I saw in the screenshots?
26
7.3. Matchbox segfaulted !
27
28
8. Mailing List
29
9. License
30
10. Credits
31
32
1. Introduction
33
34
Matchbox is a X11 window manager designed for computers with little screen real
35
estate, limited input devices and low cpu/storage resources. Touchscreen PDA's
36
fit well into this category.
37
38
Matchbox accomadates for these shortcomings by various means. Most importantly
39
by maximising windows to all available display space and only allowing one
40
'main' window to be visible at a time. The user is able to page through each
41
main window.
42
43
Matchbox does however facilitate other minor windows to share space at the same
44
time, these include toolbar, dockable and dialog windows.
45
46
Toolbar windows occupy space at the bottom of the display with multiple
47
instances stacking on top of each other. They work similar to toolbars in web
48
browser software allowing the space they use to be quickly freed and reclaimed.
49
Xkbd is an example of an application that uses a toolbar window.
50
51
For dockable windows, Matchbox optionally includes a configurable collapse-able
52
dock that holds small apps that are visible at all times. Examples include
53
small clocks, app launchers or resource meters.
54
55
Windows which set there 'transient' property are treated as dialogs. They are
56
set smaller than main windows, are drag-able and stay attached to their
57
'parent' during paging.
58
59
Other Features include;
60
61
* Small binary size.
62
* Only dependent on Xlib, and no other gui toolkits.
63
* Keyboard shortcuts for window navigation / operations.
64
* Theme-able.
65
* Highly configurable.
66
* Survives and adapts well to 'screen rotations'
67
* Optionable compile time Xft ( Anti-Aliased font ) support.
68
* Dist includes various useful apps;
69
70
+ minitime, a docked clock.
71
+ miniapm, a docked battery monitor.
72
+ minisys, a docked mem/cpu monitor.
73
+ monolauch, a simple dockable single program launcher.
74
+ mbcontrol, a tool for managing matchbox externally, used primarily for
75
changing themes on the fly.
76
77
78
79
Matchbox is still in its infancy and should be considered unstable software.
80
There are probably many bugs unfortunately lurking in the code. If you catch
81
one, be sure to report it.
82
83
-------------------------------------------------------------------------------
84
85
2. Screenshots
86
87
Screenshots are kept at http://www.handhelds.org/~mallum/screenshots/.
88
-------------------------------------------------------------------------------
89
90
3. Usage
91
92
Matchbox is designed to be intuitive. Navigation between main windows is
93
accomplished by clicking on the titlebar 'arrow' buttons or clicking on the
94
window title for a clickable dropdown list of currently active main windows.
95
96
Toolbar apps ( such as xkbd ) and the dockbar can be minimised by clicking the
97
small arrow at the side of the window. Once minimised they can be maximised by
98
clicking the collapsed bar. Toolbar apps are closed by clicking the cross at
99
the end of the bar.
100
101
-------------------------------------------------------------------------------
102
103
3.1. Launching Matchbox
104
105
With no other window manager running, simply execute 'matchbox &'. More
106
sensably add matchbox to the end of your X Startup script ( such as .xsession
107
or .xinitrc ).
108
109
-------------------------------------------------------------------------------
110
111
3.2. Configuration.
112
113
Matchbox supports optional configuration via command line options and/or X
114
Resource settings.
115
116
X Resources are set options per user in ~/.Xdefaults and globally in (install
117
prefix)/share/matchbox/defaults. Command line options take precedence over both
118
of these;
119
120
Options, are;
121
122
Table 1. Matchbox options
123
124
+-----------------------------------------------------------------------------+
125
|Command Line |XResource Key |Value |Description |
126
|Switch | |Type | |
127
|-------------+------------------------+-------+------------------------------|
128
|-display |matchbox.display |string |Specify the XServer for |
129
| | | |matchbox to connect to. |
130
| | | |Defaults to $DISPLAY |
131
| | | |environmental variable. |
132
|-------------+------------------------+-------+------------------------------|
133
|-theme |matchbox.theme |string |Specify the theme file to use.|
134
| | | |Defaults to default_theme_rc. |
135
| | | |The theme can also be changed |
136
| | | |whilst matchbox is executing |
137
| | | |using the mbcontrol program. |
138
|-------------+------------------------+-------+------------------------------|
139
|-modifier |matchbox.modifier |mod1| |Specify the modifier key to be|
140
| | |mod2| |used in combination with |
141
| | |ctrl |keyboard shortcut keys. |
142
| | | |Defaults to mod2 ( record |
143
| | | |button on the ipaq ) |
144
|-------------+------------------------+-------+------------------------------|
145
|-use_dock |matchbox.dock |yes|no |Specify whether or not to use |
146
| | | |the dock. Defaults to yes. |
147
|-------------+------------------------+-------+------------------------------|
148
|-dockmax |matchbox.dock.height.max|integer|Specify the height, in pixels,|
149
| | | |of the dock. |
150
|-------------+------------------------+-------+------------------------------|
151
|-dockmin |matchbox.dock.height.min|integer|Specify the height, in pixels,|
152
| | | |of the dock when collapsed. |
153
| | | |defaults to 4. |
154
|-------------+------------------------+-------+------------------------------|
155
|-use_titlebar|matchbox.titlebar |yes|no |Specify whether or not the |
156
| | | |main windows have titlebars. |
157
| | | |Defaults to yes. |
158
|-------------+------------------------+-------+------------------------------|
159
|-help |n/a |n/a |Display a brief help message |
160
| | | |and exit. |
161
+-----------------------------------------------------------------------------+
162
163
-------------------------------------------------------------------------------
164
165
3.3. Themes
166
167
Matchbox supports simple themes to change its look. A single default theme is
168
included with the main distribution. See the mb-themes package for extra ones (
169
blue, rage and yawn ).
170
171
See (install prefix)/share/matchbox/themes for examples. They are pretty self
172
explanatory.
173
174
Themes can be selected on startup via the '-theme' switch or changed on the fly
175
using the included utility 'mbcontrol'.
176
177
-------------------------------------------------------------------------------
178
179
3.4. Shortcut keys.
180
181
Matchbox operation can be controlled with the keyboard by holding the defined
182
modifier key ( default mod2 ) and one of the following;
183
184
* Arrow left or p.
185
186
Go to previous main window.
187
* Arrow right, n or Tab.
188
189
Go to Next main window.
190
* Return.
191
192
Close current main window.
193
* l or Arrow down.
194
195
Collapse all toolbars but not dock
196
* r or Arrow up.
197
198
Raise all toolbars but not dock
199
* R.
200
201
Collapse all toolbars and dock
202
* L.
203
204
Raise all toolbars and dock
205
206
Shortcuts will eventually be user definable.
207
208
-------------------------------------------------------------------------------
209
210
4. Included Utilities.
211
212
* minitime [options ...].
213
214
A dockable clock. Currently supports -f and -c switches for font and colour
215
respectively.
216
* miniapm.
217
218
A dockable battery monitor, currently a little broken :(
219
* minisys [options...].
220
221
A dockable mem/cpu monitor. Run with '-h' to see options.
222
* monolauch [-k] <xpm to use> <window name> <program to run>.
223
224
A single app launcher which sits in the dock with the selected xpm icon.
225
Initial click will launch the selected program, next click will hide the
226
programs window, next will show the window, next will hide, and so on for
227
ever.... Passing -k option will kill the program rather than hide it.
228
Originally based on xsingleinstance.
229
* mbcontrol [ options...].
230
231
When run with a '-r' it will output the current theme file matchbox is
232
using to stdout. When run with '-t <theme_file>', matchbox will switch to
233
that theme. Be aware however if the theme file doesn't exist, matchbox will
234
rudely exit ( To be fixed! )
235
236
-------------------------------------------------------------------------------
237
238
5. Compiling and Installing.
239
240
matchbox uses autoconf, so building it should be straightforward:
241
$./configure
242
$make
243
# This next step might require root access
244
$make install
245
See the INSTALL file for (standard) gory details regarding autoconf.
246
247
Configure currently supports the following options;
248
249
* --enable-debug
250
251
configure for a debug build
252
253
* --enable-xft
254
255
configure to use XFT library for anti-aliased fonts.
256
257
Make also has an 'ipkg' target for building shiny ipkgs.
258
259
A prebuilt ipkg is included in the familiar linux distributions unstable feed.
260
261
-------------------------------------------------------------------------------
262
263
6. Availability
264
265
Source tarballs and debs are available from http://www.handhelds.org/~mallum/
266
downloadables/
267
268
Bleeding edge source is available from handhelds.org cvs under apps/matchbox.
269
See http://www.handhelds.org/sources.html
270
271
ARM binarys for the Compaq Ipaq are available in ipkg from from the familiar
272
distribution unstable feed. See http://familiar.handhelds.org.
273
274
-------------------------------------------------------------------------------
275
276
7. FAQ
277
278
-------------------------------------------------------------------------------
279
280
7.1. Where's the app launcher menu ?
281
282
There isn't one. Use a separate app such as gtk-menu ( lives in the dock ) ,
283
gpe-appmgr ( PDA style launcher ), or lots of monolauch's .
284
285
-------------------------------------------------------------------------------
286
287
7.2. How do I get that keyboard icon I saw in the screenshots?
288
289
monolaunch provides this. Run monolauch like this;
290
291
monolauch /usr/share/xkbd/img/kbd.xpm xkbd xkbd
292
293
Adding the '-k' switch to monolaunch will cause xkbd to completely disappear
294
rather than minimise to a bar.
295
296
-------------------------------------------------------------------------------
297
298
7.3. Matchbox segfaulted !
299
300
Remember matchbox is still in its early stages of development and is known to
301
crash on occasion. The important thing to do is to mail me explaining exactly
302
what happened and how to reproduce it, so I can fix it!
303
304
-------------------------------------------------------------------------------
305
306
8. Mailing List
307
308
Matchbox has a mailing list for both users and developers of matchbox.
309
310
Subscribe at http://www.handhelds.org/mailman/listinfo/matchbox
311
312
Archives are available at http://www.handhelds.org/pipermail/matchbox/
313
314
-------------------------------------------------------------------------------
315
316
9. License
317
318
Matchbox is free software released under the terms of the GNU General Public
319
License, (GPL). You can redistribute it and/or modify it under the terms of the
320
GNU General Public License as published by the Free Software Foundation; either
321
version 2, or (at your option) any later version.
322
323
Matchbox is distributed in the hope that it will be useful, but WITHOUT ANY
324
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
325
PARTICULAR PURPOSE. See the GNU General Public License for more details.
326
327
-------------------------------------------------------------------------------
328
329
10. Credits
330
331
Matchbox is written by Matthew Allum. It was originally based on aewm, but has
332
since undergone rewrites and now bares little resemblance. Thanks also goto
333
Carl Worth and Nils Ferber for initial help with the project.
334
335
Be sure to check out other exciting software by me including; xkbd - a xlib
336
virtual on-screen keyboard, pikpak - a python gtk front end to ipkg, gtksolo -
337
a gtk module which turns held down left clicks into right clicks on gtk apps
338
and jabberpy - a Python library for the Jabber instant messaging protocol.
339
340
Matchbox is copyright Matthew Allum 2002.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1