matchbox/matchbox-documentation
1
0
Fork 0
mirror of https://git.yoctoproject.org/matchbox-documentation synced 2025-11-05 05:25:48 +08:00
Code Issues Packages Projects Releases Wiki Activity

various updates. better docbooking. etc etc

Browse Source 
git-svn-id: https://svn.o-hand.com/repos/matchbox/trunk/matchbox-documentation@1190 b067294f-1dea-0310-9683-c47a78595994
This commit is contained in:
mallum
2005-08-08 18:38:20 +00:00
parent 092d6aac92
commit 39c5d05c63
1 changed files with 104 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

217
manual/matchbox-manual.xml
View File

@@ -38,7 +38,7 @@
</articleinfo> </articleinfo>
<section> <section id="intro">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
The Matchbox project aims to increase X Windows practicality and The Matchbox project aims to increase X Windows practicality and
@@ -49,9 +49,9 @@
</para> </para>
<para> <para>
This includes; at its a core a stack based PDA style window This includes at its a core a stack based PDA style window
manager, a panel or dock, PDA style launcher, software input manager. Also included is a panel or dock, a PDA style launcher,
methods and more. software input methods and more.
</para> </para>
<para> <para>
@@ -64,18 +64,17 @@
</section> </section>
<section> <section id="rational">
<title>Rational</title> <title>Rational</title>
<para> <para>
With the creation of <ulink With the creation of <ulink
url="http://handhelds.org">Handhelds.org</ulink> and its work with other to url="http://handhelds.org">Handhelds.org</ulink> and its communitys work with to
make Linux and X Windows run efficiently on iPaq devices it soon make Linux and X Windows run efficiently on iPaq devices it soon
became apparent to me, as an avid handhelds.org hacker, that pre became apparent to me, as an avid handhelds.org hacker, that pre
existing X11 window managers were a poor fit on a device with existing X11 window managers were a poor fit on a device with
such low resources, a small 240x320 display and very limited such low resources, a small 240x320 display and very limited
input mechanisms ( no keyboard, touchscreen ). To improve on input mechanisms ( no keyboard, touchscreen ). To improve on
this situation, Matchbox was started, initially with the this situation, Matchbox window manager was born.
window manager.
</para> </para>
<para> <para>
The plan was to leverage the huge amount of existing X11 The plan was to leverage the huge amount of existing X11
@@ -90,10 +89,11 @@
practical, more support for other desktop standards and practical, more support for other desktop standards and
protocols ( see <ulink protocols ( see <ulink
url="http://freedesktop.org">freedesktop.org</ulink> ) were added as url="http://freedesktop.org">freedesktop.org</ulink> ) were added as
well as new supporting applications. well as new supporting applications such as the matchbox panel and desktop.
</para> </para>
<para> <para>
Nowadays matchbox is used on a wide range of non desktop type embedded devices. Matchbox's build and run time flexibility allow it to well fit a target platforms resources, feature requirements and physical form.
Nowadays matchbox is used on a wide range of non desktop type embedded devices. Matchbox's build and run time flexibility allow it to be tailored to a target platforms resources, feature requirements and physical form.
</para> </para>
@@ -106,12 +106,13 @@
client window geometry and stacking order, as well as providing client window geometry and stacking order, as well as providing
decorations and controls to the window borders. Matchbox's style decorations and controls to the window borders. Matchbox's style
of management is restrictive in nature, setting application of management is restrictive in nature, setting application
windows with a maximized static geometry in a brows-able stack windows with a maximized static geometry in a browsable stack or
with only one application being visible at any time. Different, deck with only one application being visible at any
though fitting, rules and support apply to other window types time. Different, though applicable, rules apply to
such as dialogs, panels and input method windows. The design is other window types such as dialogs, panels and input method
such as to make platforms with small displays and limited input windows. The design is such as to make application
mechanisms more use-able. management on platforms with small displays and limited input
mechanisms more useable.
</para> </para>
<para> <para>
@@ -145,29 +146,25 @@
</para> </para>
<para> <para>
<screen> <userinput>
matchbox-window-manager [options] matchbox-window-manager [options]
</screen> </userinput>
</para> </para>
<para> <para>
Matchbox window manager supports optional configuration via Matchbox window manager supports optional configuration via
command line options and/or X Resource settings command line options and/or X Resource settings (
<footnote> if X Resource support is disabled at build time this will
<para> not work. ). For general usage one should not need to set any
If X Resource support is disabled at build time this will
not work.
</para>
</footnote>. For general usage one should not need to set any
command line options. command line options.
</para> </para>
<para> <para>
X Resources are usually set options per user in ~/.Xdefaults X Resources are usually set options per user in <filename>~/.Xdefaults</filename>
and globally in (install prefix)/share/matchbox/defaults. and globally in <filename>(install prefix)/share/matchbox/defaults</filename>.
</para> </para>
@@ -202,36 +199,13 @@
<para> <para>
Specify the theme name to use, describing the window Specify the theme name to use, describing the window
managers' look and feel'. The directory's; managers' look and feel'. The directory's; <filename>
~/.theme/[theme name]/matchbox</filename> and
</para> <filename>(install prefix)/share/themes/[themename]/matchbox</filename> will be checked for a valid
<para> theme.xml file. If the file is not found or invalid,
matchbox will revert to its default theme (
<screen> <filename>(install
prefix)/share/themes/Default/matchbox</filename> )
~/.theme/[theme name]/matchbox
$PREFIX/share/themes/[theme name]/matchbox
</screen>
<footnote>
<para>
<envar>$PREFIX</envar> is the optional path passed
to the --prefix option of the build configure. By
default it is likely to be
<filename>/usr</filename> or
<filename>/usr/local</filename>.
</para>
</footnote>
</para>
<para>
will be checked for a valid theme.xml file. If the
file is not found or invalid, matchbox will revert to
its default theme (
<filename>$PREFIX/share/themes/Default/matchbox</filename>
)
</para> </para>
@@ -437,7 +411,7 @@
<listitem> <listitem>
<para> <para>
Specify the session manager client ID. Only used if Specify the session manager client ID. Only used if
build with session manager support. built with session manager support.
</para> </para>
<para> <para>
The corresponding X Resource key is The corresponding X Resource key is
@@ -491,7 +465,6 @@
</variablelist> </variablelist>
</para> </para>
</section> </section>
@@ -499,14 +472,8 @@
<para> <para>
The window manager is fully theme-able. Themeing is configured by The window manager is fully theme-able. Themeing is configured by
simple XML files found in; simple XML files found in
<filename>(install prefix)/share/themes/[selected theme name]/matchbox</filename> .
</para>
<para>
<screen>
$PREFIX/share/themes/[selected theme name]/matchbox
</screen>
</para> </para>
<para> <para>
@@ -524,8 +491,8 @@
</para> </para>
<para> <para>
If you compiled Matchbox without libxsettings support, use The easiest way is to use
matchbox-remote to change the current theme. matchbox-remote to change the current theme;
</para> </para>
@@ -538,7 +505,8 @@
Alternatively if you compiled with XSettings support, you will be Alternatively if you compiled with XSettings support, you will be
able to use the Gnome2 / GPE / KDE3 desktop configuration tools to able to use the Gnome2 / GPE / KDE3 desktop configuration tools to
change the theme. The XSettings key used is change the theme. The XSettings key used is
<filename>Net/ThemeName</filename> <filename>Net/ThemeName</filename>. Using XSettings allows the
window manager theme to change with the toolkit theme.
</para> </para>
@@ -557,8 +525,8 @@
The window manager has redefinable shortcut keys which can be used The window manager has redefinable shortcut keys which can be used
to perform window operations or launch applications. The location of to perform window operations or launch applications. The location of
the config file is PREFIX/share/matchbox/kbdconfig , this can be the config file is <filename>(install prefix)/share/matchbox/kbdconfig</filename> , this can be
overridden by the user having a ~/.matchbox/kdbconfig file. overridden by the user having a <filename>~/.matchbox/kdbconfig</filename> file.
</para> </para>
<para> <para>
@@ -591,15 +559,15 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
! Launch application with just a standard fork-exec. <userinput>!</userinput> Launch application with just a standard fork-exec.
</para> </para>
</listitem> </listitem>
<listitem><para>!! Launch application with <listitem><para><userinput>!!</userinput> Launch application with
'startup-notification' - provides feedback of application 'startup-notification' - provides feedback of application
startup cycle.</para> <para>Application must support startup startup cycle.</para> <para>Application must support startup
notification ( eg uses GTK 2.2 or above )</para></listitem> notification ( eg uses GTK 2.2 or above )</para></listitem>
<listitem><para>!$ Launch or raise preexisting application, <listitem><para><userinput>!$</userinput> Launch or raise preexisting application,
keeping just a single instance running. [1] keeping just a single instance running. [1]
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
@@ -663,23 +631,20 @@
<section><title>matchbox-session</title> <section><title>matchbox-session</title>
<para> <para>
A very simple shell script to start Matchbox window manager, desktop A very simple shell script to start Matchbox window manager, desktop
and panel ( if available ). and panel ( if available ). Run as part of your X startup scripts ( eg. <filename>~/.xinitrc</filename> or from the command line via;
</para> </para>
<para> <para>
The file will check for in order and exec the following files if they <userinput>matchbox-session</userinput>
</para>
<para>
The file will check for in order and exec <filename>~/.matchbox/session</filename> and <filename>/etc/matchbox/session</filename> if they
exist. exist.
</para> </para>
<para>
<programlisting>
$HOME/.matchbox/session /etc/matchbox/session
</programlisting>
</para>
<para> <para>
If they don't exist sensible defaults will be run. The reasoning If they don't exist sensible defaults will be run. The reasoning
behind this file is that distributions containing Matchbox can easily behind this file is that distributions containing Matchbox can easily
tailor startup options ( by supplying a /etc/matchbox/session ) for tailor startup options ( by supplying a <filename>/etc/matchbox/session</filename> ) for
their platform. their platform.
</para> </para>
@@ -693,7 +658,13 @@
</section> </section>
<section><title>matchbox-remote</title> <section><title>matchbox-remote</title>
<para> <para>
A command line tool to externally control Matchbox. A command line tool to externally control Matchbox. Launch via;
</para>
<para>
<userinput>matchbox-remote [options]</userinput>
</para>
<para>
options are;
</para> </para>
<para> <para>
<table> <table>
@@ -764,8 +735,7 @@
Matchbox window manager uses the EWMH hints and tranciency to identify how a window should be managed and stacked. Matchbox window manager uses the EWMH hints and tranciency to identify how a window should be managed and stacked.
</para> </para>
<para> <para>
<emphasis>TO COMPLETE</emphasis>
</para> </para>
</section> </section>
@@ -823,9 +793,18 @@
<section><title>Usage And Configuration</title> <section><title>Usage And Configuration</title>
<para> <para>
<screen> With an X Server running and the DISPLAY environment variable set correctly, run matchbox panel via;
</para>
<para>
<userinput>matchbox-panel [options]</userinput> <userinput>matchbox-panel [options]</userinput>
</screen> </para>
<para>
Options are;
</para>
<para>
<table> <table>
<title>Matchbox Panel command line options</title> <title>Matchbox Panel command line options</title>
<tgroup cols="3" align="left" colsep="10" rowsep="10"> <tgroup cols="3" align="left" colsep="10" rowsep="10">
@@ -950,9 +929,9 @@
</para> </para>
<para> <para>
<programlisting> <userinput>
matchbox-panel --size 60 --orientation east --bgtrans yes &amp; matchbox-panel --size 60 --orientation east --bgtrans yes &amp;
</programlisting> </userinput>
</para> </para>
<para> <para>
@@ -962,10 +941,9 @@
</para> </para>
<para> <para>
<programlisting> <userinput>
matchbox-panel --orientation north &amp; matchbox-panel --id matchbox-panel --orientation north &amp; matchbox-panel --id 2 --orientation south &amp;
2--orientation south &amp; </userinput>
</programlisting>
</para> </para>
<para> <para>
@@ -975,10 +953,9 @@
</para> </para>
<para> <para>
<programlisting> <userinput>
matchbox-panel --titlebar --no-menu --no-session --default-apps matchbox-panel --titlebar --no-menu --no-session --default-apps minitime &amp;
minitime &amp; </userinput>
</programlisting>
</para> </para>
<para> <para>
@@ -1072,14 +1049,14 @@
<para> <para>
A menu based application launcher. Reads .desktop files found in A menu based application launcher. Reads .desktop files found in
$PREFIX/share/applications/ ( and ~/.applications ). <filename>(install prefix)/share/applications/</filename> ( and <filename>~/.applications</filename> ).
</para> </para>
<para> <para>
The menu structure is defined by .directory files found in The menu structure is defined by .directory files found in
$PREFIX/share/matchbox/vfolders ( See the section on matchbox-desktop for <filename>(install prefix)/share/matchbox/vfolders</filename> ( See the section on matchbox-desktop for
more info ). more info ).
</para> </para>
@@ -1111,15 +1088,20 @@
</section> </section>
<section><title>mb-applet-launcher </title> <section><title>mb-applet-launcher </title>
<para> <para>
mb-applet-launcher can be used to create simple panel launchers. mb-applet-launcher can be used to create simple panel launchers. Launch via;
</para> </para>
<para> <para>
<screen> <userinput>mb-applet-launcher [options..] &lt;xpm|png filename&gt; &lt;command&gt; ]</userinput>
<userinput>mb-applet-launcher [options..] [ [ &lt;xpm|png filename&gt;
&lt;command&gt; ] [ --desktop &lt;.desktop file&gt; ]</userinput> </para>
</screen> <para>
or alternatively;
</para>
<para>
<userinput>mb-applet-launcher --desktop &lt;.desktop file&gt;</userinput>
</para> </para>
<para> <para>
@@ -1213,7 +1195,7 @@
</section> </section>
</section> </section>
<section><title>Matchbox Desktop</title> <section id="mbdesktop"><title>Matchbox Desktop</title>
<para> <para>
The desktop is kept at the very bottom of the window stack. It is The desktop is kept at the very bottom of the window stack. It is
provided primarily as an application launcher but can be extended for numerous other uses. provided primarily as an application launcher but can be extended for numerous other uses.
@@ -1221,9 +1203,16 @@
</para> </para>
<section><title>Usage And Configuration</title> <section><title>Usage And Configuration</title>
<para> <para>
<screen>
matchbox-desktop [options] With an X Server running and the DISPLAY environment variable set correctly, run matchbox desktop via;
</screen>
</para>
<para>
<userinput>matchbox-desktop [options]</userinput>
</para>
<para>
Options are;
</para> </para>
<para> <para>
<table> <table>
@@ -1320,7 +1309,7 @@
file browser. file browser.
</para> </para>
<para> <para>
What modules are used are set in $PREFIX/lib/matchbox/mbdesktop_modules or set per user in ~/.matchbox/mbdesktop_modules. What modules are used are set in <filename>(install prefix)/lib/matchbox/mbdesktop_modules</filename> or set per user in <filename>~/.matchbox/mbdesktop_modules</filename>.
</para> </para>
<para> <para>
@@ -1341,7 +1330,7 @@
</para> </para>
<para> <para>
The directory's PREFIX/share/applications and HOME/applications are checked for the existence of 'INI style' .desktop files. A .desktop contains information about a program entry including its name, icon, executable string etc. The directory's <filename>(install prefix)/share/applications</filename> and <filename>~/applications</filename> are checked for the existence of 'INI style' .desktop files. A .desktop contains information about a program entry including its name, icon, executable string etc.
</para> </para>
<para> <para>
@@ -1358,12 +1347,12 @@
</para> </para>
<para> <para>
The Icon entry should not specify a path, just the filename of the required image located in PREFIX/share/pixmaps. Locale based entrys can be added by appending a [contry_code] to the required key. The Icon entry should not specify a path, just the filename of the required image located in <filename>(install prefix)/share/pixmaps</filename>. Locale based entrys can be added by appending a [contry_code] to the required key.
</para> </para>
<para> <para>
Information for what and how matchbox-desktop should create folders for the above entries is stored in $PREFIX/share/matchbox/vfolder and overridden by $HOME/.matchbox/vfolders/ . Information for what and how matchbox-desktop should create folders for the above entries is stored in <filename>(install prefix)/share/matchbox/vfolder</filename> and overridden by <filename>~/.matchbox/vfolders/</filename> .
</para> </para>
<para> <para>