updates for pending 0.9 release. Added ChangeLog

git-svn-id: https://svn.o-hand.com/repos/matchbox/trunk/matchbox-documentation@903 b067294f-1dea-0310-9683-c47a78595994

ChangeLog

@@ -0,0 +1,7 @@
+2004-11-19  mallum,,,  <mallum@handhelds.org>
+
+	* developers/matchbox-key.txt:
+	* manual/matchbox-manual.sgml:
+	* theme-howto/theme.howto.docbook:
+	Updated in preperation for 0.9 release. 
+

developers/matchbox-key.txt

@@ -1,4 +1,4 @@
-Matchbox Communication Details v0.6.1           - Matthew Allum 2003 
+Matchbox Communication Details v0.7            - Matthew Allum 2004 
 =====
 
 This document acts as a key and provides details to the mechanisms
@@ -30,6 +30,9 @@ an entire display, with all other windows being its decendants. As the
 root window is always present, it provides a useful location to
 'broadcast' set properties and sent messages to any interested client.
 
+This document is relevant to the 0.9 matchbox release. Anything marked
+'EXPERIMENTAL' is subject to change between matchbox releases.
+
 
 Recommended Background Reading
 =======
@@ -111,7 +114,7 @@ supports the following;
 _NET_WORKAREA              - Defines workarea dimentions, 
 _NET_ACTIVE_WINDOW         - Specifys current active window XID, 
 _NET_CLIENT_LIST_STACKING  - Lists the stacking order of managed clients, 
-_NET_CLIENT_LIST           - Lists all managed clients, 
+_NET_CLIENT_LIST           - Lists all managed clients in age order. 
 _NET_SUPPORTING_WM_CHECK   - Specifys window manager has EWMH support,
 _NET_SUPPORTED             - Lists window manager EWMH supported features, 
 _NET_NUMBER_OF_DESKTOPS    - Number of desktops ( 1 in matchbox's case ),
@@ -166,16 +169,21 @@ by standard xlib functions.
 Matchbox also supports the following EWMH properties on clients;
 
 _NET_WM_WINDOW_TYPE          - Set to one of the below to indicate
-_NET_WM_WINDOW_TYPE_TOOLBAR    how matchbox should manage the window.
+                               how matchbox should manage the window.
+_NET_WM_WINDOW_TYPE_TOOLBAR  \
+_NET_WM_WINDOW_TYPE_INPUT    / Both treated the same ( as input window - xkbd )
 _NET_WM_WINDOW_TYPE_DOCK
 _NET_WM_WINDOW_TYPE_DIALOG
 _NET_WM_WINDOW_TYPE_SPLASH
 _NET_WM_WINDOW_TYPE_DESKTOP
 
 _NET_WM_STATE                - Used to toggle full-screen state. 
+_NET_WM_STATE_ABOVE          - Supported only for dialog windows.  
+_NET_WM_STATE_MODAL          /
 _NET_WM_STATE_FULLSCREEN       ( Note: matchbox currently has little
 			               support for EWMH states )
 
+
 _NET_WM_NAME                 - Specify window title as UTF8 data.
 _NET_WM_ICON                 - Specify the window icon with rgba data.
 
@@ -183,7 +191,11 @@ See http://www.freedesktop.org/standards/wm-spec/1.3/html/x231.html
 for more detailed information.
 
 _NET_WM_PID                  - Used for hung application detection
-_NET_WM_PING                 -/
+_NET_WM_PING                 /
+
+Clients supporting the above will have the 'ping protocol' initiated on them 
+when a window is requestd to close via matchbox. This feature can be disabled 
+at compile time. 
 
 See http://www.freedesktop.org/standards/wm-spec/1.3/html/x351.html
 For infomation.
@@ -215,8 +227,10 @@ When an 'extended' button is pressed, the Window Manager will send a client
 message with its data set as the appropriate atom to the interested
 client.
 
-_MB_WM_WINDOW_TYPE_MESSAGE
+_
-_MB_WM_WINDOW_TYPE_MESSAGE_TIMEOUT
+
+_MB_WM_WINDOW_TYPE_MESSAGE          ( EXPERIMENTAL )
+_MB_WM_WINDOW_TYPE_MESSAGE_TIMEOUT  ( EXPERIMENTAL )
 
 If matchbox is built with the --enable-message-wins option, matchbox
 will offer support for the _NET_WM_WINDOW_TYPE, '_MB_WM_WINDOW_TYPE_MESSAGE'.
@@ -231,6 +245,14 @@ displayed at any time. The optional _MB_WM_WINDOW_TYPE_MESSAGE_TIMEOUT
 seconds it should stay visable. If this property is not set or set to
 0, the window will stay active indefinitely until it closes itself.
 
+*NOTE* *NOTE* *NOTE*
+
+The above is depreciated in 0.9 full release. For an dialog to now get
+message window style decorations ( if defined in theme ), the window
+should set the ICCCM 'urgency' in WM_HINTS. The queueing mechanism is
+now depricated, if required its recommended it be handled outside of
+the WM.
+
 _MB_WM_STATE_DOCK_TITLEBAR
 
 A matchbox only specific _NET_WM_STATE. Intended to be used by panels
@@ -241,6 +263,11 @@ Also you may set '_MB_DOCK_TITLEBAR_SHOW_ON_DESKTOP' in the panels
 state property to not hide an embedded title panel when the desktop is
 visible.
 
+_MB_WIN_SUB_NAME ( EXPERIMENTAL )
+
+Sets a another window name which may be shown dependant on theme
+configuration.
+
 
 [5] Client / Window Manger X message Communication.
 ======
@@ -263,6 +290,12 @@ for more information.
 
 Matchbox only message types;
 
+_MB_GRAB_TRANSFER ( EXPERIMENTAL )
+
+Signals the current client that mb has released a button grab on the
+press state so the application can handle release. Intended to be used
+with _NET_WM_CONTEXT_CUSTOM. Theme configuration sets up this behaviour. 
+
 _MB_COMMAND                  
 
 Sent to the root window to request matchbox perform a specific
@@ -280,6 +313,7 @@ following values to perform an associated action;
 
 _NET_WM_CONTEXT_HELP
 _NET_WM_CONTEXT_ACCEPT
+_NET_WM_CONTEXT_CUSTOM
 
 Sent to a window when a help / accept button has been pressed. 
 
@@ -326,8 +360,8 @@ They are;
 /MATCHBOX/CURSOR	- Attempt to hide X Cursor.
 
 It is planned to hopefully soon drop XSettings support in favour 
-of gconf/D-BUS.
+of gconf/D-BUS. GConf can currently be used to specify the theme 
-
+and keyboard shortcuts, changeable on the fly. 
 
 References / Standards.
 =======

manual/matchbox-manual.sgml

@@ -11,7 +11,7 @@
     <title>Matchbox Project Manual</title>
     <copyright>
       <year>2004</year>
-      <holder>Matthew Allum</holder>
+      <holder>Matthew Allum, Openedhand LTD</holder>
     </copyright>
 
     <legalnotice>
@@ -38,7 +38,7 @@
     </legalnotice>
 
     <releaseinfo>
-       This is version 0.8 of The Matchbox manual.
+       This is version 0.9 of The Matchbox manual.
     </releaseinfo>
 
   </artheader>
@@ -106,7 +106,7 @@
 
    Matchbox window manager is included in the
    <filename>matchbox-window-manager</filename> package, which is part of the
-   Matchbox project. This document describes version 0.8 of 
+   Matchbox project. This document describes version 0.9 of 
    Matchbox window manager.
 
    </para>
@@ -236,7 +236,7 @@
 	          
 
             Enables an effect to make modal dialog windows 'super' modal. All
-            other windows are lowlighted out. 
+            other windows are lowlighted out. This option is <emphasis>EXPERIMENTAL</<emphasis>
 
            </para>
 
@@ -266,7 +266,7 @@
             <para>
 
             Decides the strategy the window manager uses to position and resize
-            dialogs. 
+            dialogs. By default, dialogs will be restrained to fit on the display not covering any panels or input/toolbar windows.
 	    </para>
 
 	    <para>
@@ -276,8 +276,7 @@
 
 	    <para>
 
-	    <emphasis>const</emphasis>, will restrain oversized 
+	    <emphasis>static</emphasis>, the user cannot change dialog position or stacking order.
-            dialog windows to the available screen space. The is the default.
 
 	    </para>
 	    <para>	    
@@ -345,6 +344,21 @@
       </listitem> 
      </varlistentry>
 
+	<varlistentry>
+          <term><userinput>-force-dialogs &lt;comma seperated name list&gt;</userinput></term>
+	  <listitem>
+            <para>
+	    Specify a comma seperated list of window titles, whose windows when matched are <emphasis>forced</<emphasis> to be treated as dialogs rather than application windows. 
+            </para>
+	    <para>
+	    The corresponding X Resource key is
+	    <emphasis>matchbox.forcedialogs</emphasis> .  
+
+	    </para>
+      </listitem> 
+     </varlistentry>
+
+
 	<varlistentry>
           <term><userinput>-help</userinput></term>
 	  <listitem>

theme-howto/theme.howto.docbook

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <article>
 <artheader>
-<title>Designing Matchbox Themes HOWTO. Version 0.4</title>
+<title>Designing Matchbox Themes HOWTO. Version 0.5</title>
 <author><firstname>Matthew</firstname>
 <surname>Allum</surname>
 <email>matthew@openedhand.com</email>
@@ -26,6 +26,9 @@ Matchbox must be compiled *without* the --enable-standalone for themeing.
 Its assumed the reader is familiar with using xml or xml-like mark up languages 
 such as html. 
 </para>
+<para>
+This document is relevant for matchbox 0.9 release. 
+</para>
 </section>
 <section><title>Getting started</title>
 <para>
@@ -48,6 +51,9 @@ Alternatively you can also use 'matchbox-remote -t [theme_name]' to switch theme
 on the fly whilst matchbox is executing.  
 </para>
 <para>
+If enabled enabled both GConf and XSettings can also be used to change the matchbox theme.
+</para>
+<para>
 If matchbox fails to parse a theme file, it will switch to its default theme 
 and print basic error information on why it failed to stdout.  
 </para>
@@ -206,12 +212,20 @@ The window types are;
    <para>
      Can also optionally have a dialog-north frame. This is used for border-only dialogs.  
    </para>
+   <para>
+
+   You can also optionally specify 'message' alternate window
+   decorations. These are dialogs with The WM_HINTS 'urgency' bit
+   set. They are defined just like dialogs with there frame id set to
+   'message', 'message-south', 'message-east' etc.
+
+   </para>
 </listitem>
 
 </varlistentry>
 
 <varlistentry>
-<term>Toolbar window frames</term>
+<term>Toolbar/Input window frames</term>
 <listitem>
    <para>
      Defines the decorations for toolbar windows - such as xkbd
@@ -221,6 +235,12 @@ The window types are;
    <para>
      Has 2 states maximized and minimized, both are defined separately.</para>
 </listitem>
+<listitem>
+   <para>
+<emphasis>Note</<emphasis>, an matchbox window manager built with 'alternate input manager windows' does not provide any themeing for these windows. The windows are decoration free.	
+   </para>
+</listitem>
+
 </varlistentry>
 
 <varlistentry>
@@ -430,7 +450,7 @@ Buttons are painted above any layers. Valid button actions include;
 <term>custom</term>
 <listitem>
   <para>
-  A misc platform specific button. 
+  A misc 'platform' specific button. 
   </para>
 </listitem>
 
@@ -457,7 +477,8 @@ Buttons are painted above any layers. Valid button actions include;
 <term>minimise</term>
 <listitem>
   <para>
-  used by a maximized toolbar window frame type
+  used by a maximized toolbar window frame type.
+  Also works for app windows in matchbox 0.9
   </para>
 </listitem>
 </varlistentry>
@@ -784,7 +805,7 @@ PanelBgTrans
 </term>
 <listitem>
    <para>
-   Sets the transparency of matchbox-panel. Ranges from 0-255, 0 being totally transparent.
+   Sets the transparency of matchbox-panel. Ranges from 0-255, 0 being totally transparent. This option is UNSUPPORTED, use at your own risk. 
    </para>
 </listitem>
 </varlistentry>
@@ -795,7 +816,7 @@ PanelBgPixmap
 </term>
 <listitem>
    <para>
-   Sets a titled background image for mbdock. Set to the full path of a supported image file. 
+   Sets a titled background image for matchbox-panel. Set to the full path of a supported image file. 
    </para>
 </listitem>
 </varlistentry>
@@ -993,6 +1014,27 @@ signal-81-100.png
 </programlisting>
 
 </section>
+</section>
+<section>
+<title>Experimental Features</title>
+<para>
+
+Themeing containing a number of 'experimental' features, these
+features are likely to change between matchbox releases.
+
+</para>
+<para>
+<emphasis>buttons</<emphasis> can have 'pressonly' in there options attribute.
+If this is set the button will get activated on press, rather than release.
+</para>
+
+<para> 
+
+<emphasis>subname</empasis> is another label type which will be
+populated with the text from the window property _MB_WIN_SUB_NAME.
+
+</para>
+
 </section>
 <section>
 <title>Faq</title>
@@ -1092,7 +1134,7 @@ Use a 'panel' tag in the the main frame definition. eg;
 
 </programlisting>
 
-Note, mbdock must be run with '--titlebar' for it to reparent in this
+Note, matchbox-panel must be run with '--titlebar' for it to reparent in this
 defined area.
 
 </para>
@@ -1100,10 +1142,15 @@ defined area.
 </section>
 <section><title>Where can I find more infomation ?</title>
 <para>
-See the various themes included with the matchbox distrubution ( in data/themes ) and the matchbox-themes package. 
+See the various themes included with the matchbox distrubution ( in data/themes ) and the matchbox-themes-extras package. 
 
 'Blondie' is a fairly advanced 'heavy' theme that uses many themeing properties. Bluebox is a lighter XPM based theme. Borillo is a relatively simple theme designed more for larger displays, using few (2) external images.
 </para>
+
+<para>
+Also the matchbox-tests package contains the 'mbtest' theme which uses many of the experimental features.
+</para>
+
 </section>
 
 </section>