add DTD for themes from Ross Burton

2002-11-20  Havoc Pennington  <hp@pobox.com>

	* doc/metacity-theme.dtd: add DTD for themes from Ross Burton

	* doc/Makefile.am: doc subdir

	* doc/theme-format.txt: move to doc subdir

3 files changed, 520 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 00000000..f2c0073d
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,2 @@
+
+EXTRA_DIST=theme-format.txt metacity-theme.dtd
diff --git a/doc/metacity-theme.dtd b/doc/metacity-theme.dtd
new file mode 100644
index 00000000..4c52a1a4
--- /dev/null
+++ b/doc/metacity-theme.dtd
@@ -0,0 +1,273 @@
+<!--
+ DTD for Metacity themes, as of Metacity 2.4.1
+ Author: Ross Burton <ross@burtonini.com>
+ Copyright (C) 2002 Ross Burton
+ Licensed under the GPL, version 2
+-->
+
+<!-- Top-level element -->
+<!ELEMENT metacity_theme (info,(window|frame_style_set|frame_style|frame_geometry|constant|draw_ops|menu_icon)+)>
+
+<!-- Theme metadata -->
+<!ELEMENT info (name?|author?|copyright?|date?|description?)*>
+<!ELEMENT name (#PCDATA)>
+<!ELEMENT author (#PCDATA)>
+<!ELEMENT copyright (#PCDATA)>
+<!ELEMENT date (#PCDATA)>
+<!ELEMENT description (#PCDATA)>
+
+<!ENTITY % xyrequired "
+	x			CDATA #REQUIRED
+	y			CDATA #REQUIRED
+">
+
+<!ENTITY % xyimplied "
+	x			CDATA #IMPLIED
+	y			CDATA #IMPLIED
+">
+
+<!ENTITY % widthheightrequired "
+	width		CDATA #REQUIRED
+	height		CDATA #REQUIRED
+">
+
+<!ENTITY % widthheightimplied "
+	width		CDATA #IMPLIED
+	height		CDATA #IMPLIED
+">
+
+<!ENTITY % boolean "(true|false)">
+
+<!ENTITY % piece_positions "
+(entire_background|titlebar|titlebar_middle|left_titlebar_edge|right_titlebar_edge|top_titlebar_edge|bottom_titlebar_edge|title|left_edge|right_edge|bottom_edge|overlay)
+">
+
+<!ENTITY % gtk-state "
+	state (normal|prelight|active|selected|insensitive) #REQUIRED
+">
+
+<!ENTITY % gtk-shadow "
+	shadow (none|in|out|etched_in|etched_out) #REQUIRED
+">
+
+
+<!-- The actual theme -->
+
+<!ELEMENT window EMPTY>
+<!ATTLIST window
+	type		(normal|dialog|modal_dialog|menu|utility|border) #REQUIRED
+	style_set		CDATA #REQUIRED
+>
+
+
+<!ELEMENT frame_style_set (frame+)>
+<!ATTLIST frame_style_set
+	name		CDATA #REQUIRED
+	parent		CDATA #IMPLIED
+>
+
+<!ELEMENT frame EMPTY>
+<!ATTLIST frame
+	focus		(yes|no) #REQUIRED
+	state		(normal|maximized|shaded|maximized_and_shaded) #REQUIRED
+	resize		(both|horizontal|vertical|none) #REQUIRED
+	style		CDATA #REQUIRED
+>
+
+<!ELEMENT frame_style (piece|button)*>
+<!ATTLIST frame_style
+	name		CDATA #REQUIRED
+	geometry		CDATA #REQUIRED
+	parent		CDATA #IMPLIED
+>
+
+<!ELEMENT piece (draw_ops?)>
+<!ATTLIST piece
+	position		%piece_positions; #REQUIRED
+	draw_ops		CDATA #IMPLIED
+>
+
+<!ELEMENT button (draw_ops?)>
+<!ATTLIST button
+	function		(menu|minimize|maximize|close|left_left_background|left_middle_background|left_right_background|right_left_background|right_middle_background|right_right_background) #REQUIRED
+	state		(normal|prelight|pressed) #REQUIRED
+	draw_ops		CDATA #IMPLIED
+>
+
+<!ELEMENT frame_geometry (border|(aspect_ratio|distance))+>
+<!ATTLIST frame_geometry
+	name		CDATA #REQUIRED
+	parent		CDATA #IMPLIED
+	title_scale		(xx-small|x-small|small|medium|large|x-large|xx-large) #IMPLIED
+	has_title		(true|false) 'true'
+	rounded_top_left		%boolean; #IMPLIED
+	rounded_top_right		%boolean; #IMPLIED
+	rounded_bottom_left	%boolean; #IMPLIED
+	rounded_bottom_right	%boolean; #IMPLIED
+>
+
+<!ELEMENT distance EMPTY>
+<!ATTLIST distance
+	name		(left_width|right_width|bottom_height|title_vertical_pad|right_titlebar_edge|left_titlebar_edge|button_width|button_height) #REQUIRED
+	value		CDATA #REQUIRED
+>
+
+<!ELEMENT border EMPTY>
+<!ATTLIST border
+	name		CDATA #REQUIRED
+	top		CDATA #REQUIRED
+	bottom		CDATA #REQUIRED
+	left		CDATA #REQUIRED
+	right		CDATA #REQUIRED
+>
+
+<!ELEMENT aspect_ratio EMPTY>
+<!ATTLIST aspect_ratio
+	name		CDATA #REQUIRED
+	value		CDATA #REQUIRED
+>
+
+<!ELEMENT draw_ops (line|rectangle|arc|tint|gradient|image|gtk_arrow|gtk_box|gtk_vline|icon|title|clip|include|tile)*>
+<!-- not sure about this.. maybe it should be removed. see #3478 in theme-parser.c -->
+<!ATTLIST draw_ops
+	name		CDATA #IMPLIED
+>
+
+<!ELEMENT line EMPTY>
+<!ATTLIST line
+	color			CDATA #REQUIRED
+	x1			CDATA #REQUIRED
+	y1			CDATA #REQUIRED
+	x2			CDATA #REQUIRED
+	y2			CDATA #REQUIRED
+	width		CDATA #IMPLIED
+	dash_on_length CDATA #IMPLIED
+	dash_off_length CDATA #IMPLIED
+>
+
+<!ELEMENT rectangle EMPTY>
+<!ATTLIST rectangle
+	color			CDATA #REQUIRED
+	%xyrequired;
+	%widthheightrequired;
+	filled			%boolean; 'false'
+>
+
+<!ELEMENT arc EMTPY>
+<!ATTLIST arc
+	color			CDATA #REQUIRED
+	%xyrequired;
+	%widthheightrequired;
+	start_angle	CDATA	#REQUIRED
+	extent_angle	CDATA	#REQUIRED
+	filled			%boolean; 'false'
+>
+
+<!ELEMENT icon EMPTY>
+<!ATTLIST icon
+	%xyrequired;
+	width		CDATA #REQUIRED
+	height		CDATA #REQUIRED
+	alpha		CDATA #IMPLIED
+	fill_type		(tile|scale) 'scale'
+>
+
+<!ELEMENT image EMPTY>
+<!ATTLIST image
+	filename		CDATA #REQUIRED
+	colorize		CDATA #IMPLIED
+	%xyrequired;
+	%widthheightrequired;
+	alpha		CDATA #IMPLIED
+	fill_type		(tile|scale) 'scale'
+>
+
+<!ELEMENT tile EMPTY>
+<!ATTLIST tile
+	name		CDATA #REQUIRED
+	%xyrequired;
+	%widthheightrequired;
+	tile_xoffset	CDATA #IMPLIED
+	tile_yoffset	CDATA #IMPLIED
+	tile_width		CDATA #REQUIRED
+	tile_height	CDATA #REQUIRED
+>
+
+<!ELEMENT clip EMPTY>
+<!ATTLIST clip
+	%xyrequired;
+	%widthheightrequired;
+>
+
+<!ELEMENT title EMPTY>
+<!ATTLIST title
+	color			CDATA #REQUIRED
+	%xyrequired;
+>
+
+<!ELEMENT tint EMPTY>
+<!ATTLIST tint
+	color			CDATA #REQUIRED
+	%xyrequired;
+	%widthheightrequired;
+	alpha		CDATA #REQUIRED
+>
+
+<!ELEMENT gtk_box EMPTY>
+<!ATTLIST gtk_box
+	%gtk-state;
+	%gtk-shadow;
+	%xyrequired;
+	%widthheightrequired;
+>
+
+<!ELEMENT gtk_arrow EMPTY>
+<!ATTLIST gtk_arrow
+	%gtk-state;
+	%gtk-shadow;
+	arrow		(up|down|left|right) #REQUIRED
+	%xyrequired;
+	%widthheightrequired;
+	filed			CDATA #IMPLIED
+>
+
+<!ELEMENT gtk_vline EMPTY>
+<!ATTLIST gtk_vline
+	%gtk-state;
+	x			CDATA #REQUIRED
+	y1			CDATA #REQUIRED
+	y2			CDATA #REQUIRED
+>
+
+<!ELEMENT gradient (color)+>
+<!ATTLIST gradient
+	type		(vertical|horizontal|diagonal) #REQUIRED
+	%xyrequired;
+	%widthheightrequired;
+	alpha		CDATA #IMPLIED
+>
+
+<!ELEMENT color EMPTY>
+<!ATTLIST color
+	value		CDATA #REQUIRED
+>
+
+<!ELEMENT include EMPTY>
+<!ATTLIST include
+	name		CDATA #REQUIRED
+	%xyimplied;
+	%widthheightimplied;
+>
+
+<!ELEMENT constant EMPTY>
+<!ATTLIST constant
+	name		CDATA #REQUIRED
+	value		CDATA #REQUIRED
+>
+
+<!ELEMENT menu_icon (draw_ops?)>
+<!ATTLIST menu_icon
+	function		(close|maximize|minimize|unmaximize) #REQUIRED
+	%gtk-state;
+	draw_ops		CDATA #IMPLIED
+>
diff --git a/doc/theme-format.txt b/doc/theme-format.txt
new file mode 100644
index 00000000..a574e89c
--- /dev/null
+++ b/doc/theme-format.txt
@@ -0,0 +1,245 @@
+Docs on the theme format
+
+Themes are in a simple XML-subset format.
+
+<?xml version="1.0"?>
+<metacity_theme>
+<!-- Only one info section is allowed -->
+<info>
+  <name>Foo</name>
+  <author>Foo P. Bar</author>
+  <copyright>whoever, 2002</copyright>
+  <date>Jan 31 2005</date>
+  <description>A sentence about the theme.</description>
+</info>
+
+<!-- define a frame geometry to be referenced later -->
+<!-- frame_geometry has an optional has_title attribute which 
+     determines whether the title text height is included in the 
+     height calculation. if not specified, defaults to true.
+     It also has an optional text_size="medium" attribute
+     (same sizes as with Pango markup, xx-small thru medium thru
+     xx-large) 
+
+     Finally it has optional args rounded_top_left=true, 
+     rounded_top_right=true, rounded_bottom_left=true,
+     rounded_bottom_right=true.
+
+     -->
+<frame_geometry name="normal" has_title="true" title_scale="medium">
+  <distance name="left_width" value="6"/>
+  <distance name="right_width" value="6"/>
+  <distance name="bottom_height" value="7"/>
+  <distance name="left_titlebar_edge" value="6"/>
+  <distance name="right_titlebar_edge" value="6"/>
+  <distance name="button_width" value="17"/>
+  <distance name="button_height" value="17"/>
+  <!-- alternative to button_width button_height distances -->
+  <aspect_ratio name="button" value="1.0"/>
+  <distance name="title_vertical_pad" value="4"/>
+  <border name="title_border" left="3" right="12" top="4" bottom="3"/>
+  <border name="button_border" left="0" right="0" top="1" bottom="1"/>
+</frame_geometry>
+
+<!-- inheritance is allowed; simply overwrites values from parent -->
+<frame_geometry name="borderless" parent="normal">
+  <distance name="left_width" value="0"/>
+  <distance name="right_width" value="0"/>
+  <distance name="bottom_height" value="0"/>
+  <distance name="left_titlebar_edge" value="0"/>
+  <distance name="right_titlebar_edge" value="0"/>
+</frame_geometry>
+
+<!-- define a constant to use in positions/sizes of draw operations;
+     constant names must start with a capital letter.
+  -->
+<constant name="LineOffset" value="3"/>
+
+<!-- define drawing operations to be referenced later; 
+     these draw-op lists can also be placed inline. 
+
+     Positions/lengths are given as expressions.
+     Operators are: +,-,*,/,%,`max`,`min`
+     All operators are infix including `max` and `min`, 
+      i.e. "2 `max` 5"
+     
+     Some variables are predefined, and constants can also 
+     be used. Variables are:
+
+       width - width of target area
+       height - height of target area
+       object_width - natural width of object being drawn
+       object_height - natural height of object being drawn
+       left_width - distance from left of frame to client window
+       right_width - distance from right of frame to client window
+       top_height - distance from top of frame to client window
+       bottom_height - distance from bottom of frame to client window
+       mini_icon_width - width of mini icon for window
+       mini_icon_height - height of mini icon
+       icon_width - width of large icon
+       icon_height - height of large icon
+       title_width - width of title text
+       title_height - height of title text
+
+    All these are always defined, except object_width/object_height 
+    which only exists for <image> right now.
+
+  -->
+
+<draw_ops name="demo_all_ops">
+  <line color="#00FF00" x1="LineOffset" y1="0" x2="0" y2="height"/>
+  <line color="gtk:fg[NORMAL]" 
+        x1="width - 1" y1="0" x2="width - 1" y2="height" 
+        width="3" dash_on_length="2" dash_off_length="3"/>
+  <rectangle color="blend/gtk:fg[NORMAL]/gtk:bg[NORMAL]/0.7"
+             x="0" y="0" width="width - 1" height="height - 1" filled="true"/>
+  <arc color="dark gray" x="0" y="0" width="width - 1" height="height - 1" 
+       filled="false" start_angle="30" extent_angle="180"/>
+  <tint color="orange" alpha="0.5" x="0" y="0" width="width" height="height"/>
+ <!-- may be vertical, horizontal, diagonal -->
+  <gradient type="diagonal" 
+            x="10" y="30" width="width / 3" height="height / 4">
+    <!-- any number of colors allowed here. A color can be 
+         a color name like "blue" (look at gcolorsel), a hex color
+         as in HTML (#FFBB99), or a color from the gtk theme 
+         given as "gtk:base[NORMAL]", "gtk:fg[ACTIVE]", etc.
+       -->
+    <color value="gtk:fg[SELECTED]"/>
+    <!-- color obtained by a 0.5 alpha composite of the second color onto the first -->
+    <color value="blend/gtk:bg[SELECTED]/gtk:fg[SELECTED]/0.5"/>
+  </gradient>
+  <!-- image has an optional colorize="#color" attribute to give the
+       image a certain color -->
+  <image filename="foo.png" alpha="0.7"
+         x="10" y="30" width="width / 3" height="height / 4"/>
+  <gtk_arrow state="normal" shadow="in" arrow="up"
+             filled="true"
+             x="2" y="2" width="width - 4" height="height - 4"/>
+  <gtk_box state="normal" shadow="out"
+           x="2" y="2" width="width - 4" height="height - 4"/>
+  <gtk_vline state="normal" x="2" y1="0" y2="height"/>
+  <!-- window's icon -->
+  <icon alpha="0.7"
+        x="10" y="30" width="width / 3" height="height / 4"/>
+  <!-- window's title -->
+  <title color="gtk:text[NORMAL]" x="20" y="30"/>
+  <!-- include another draw ops list; has optional x/y/width/height attrs -->
+  <include name="some_other_draw_ops"/>
+  <!-- tile another draw ops list; has optional
+       x/y/width/height/tile_xoffset/tile_yoffset -->
+  <tile name="some_other_draw_ops" tile_width="10" tile_height="10"/>
+</draw_ops>
+
+<frame_style name="normal" geometry="normal">
+  <!-- How to draw each piece of the frame.
+       For each piece, a draw_ops can be given inline or referenced 
+       by name. If a piece is omitted, then nothing will be drawn 
+       for that piece.
+
+       For each piece, the "width" and "height" variables in 
+       coordinate expressions refers to the dimensions of the piece, 
+       the origin is at the top left of the piece.
+  
+       So <rectangle x="0" y="0" width="width-1" height="height-1"/>
+       will outline a piece.
+    -->
+
+  <piece position="entire_background" draw_ops="demo_all_ops"/>
+  <piece position="left_titlebar_edge">
+    <draw_ops>
+      <line color="#00FF00" x1="0" y1="0" x2="0" y2="height"/>
+    </draw_ops>
+  </piece>
+
+  <!-- The complete list of frame pieces:
+
+       entire_background: whole frame
+       titlebar: entire area above the app's window 
+       titlebar_middle: area of titlebar_background not considered
+                        part of an edge
+       left_titlebar_edge: left side of titlebar background
+       right_titlebar_edge: right side of titlebar background
+       top_titlebar_edge: top side of titlebar background
+       bottom_titlebar_edge: bottom side of titlebar background 
+       title: the title area (doesn't include buttons)
+       left_edge: left edge of the frame
+       right_edge: right edge of the frame
+       bottom_edge: bottom edge of the frame
+       overlay: same area as entire_background, but drawn after 
+                drawing all sub-pieces instead of before
+
+   -->
+
+  <!-- For buttons, drawing methods have to be provided for 
+       each of three states: 
+          normal, pressed, prelight
+       and the button function or position must be provided:
+          close, maximize, minimize, menu, 
+          left_left_background, left_middle_background,
+          left_right_background, right_left_background, 
+          right_middle_background, right_right_background
+       So a working theme needs 3*4 = 12 button declarations
+       and a theme may have up to 3*10 = 30 button declarations
+       in order to handle button-rearrangement preferences.
+ 
+       (The name "function" for the attribute is from before the 
+        background values existed.)
+    -->
+
+  <button function="close" state="normal" draw_ops="previously_named"/>
+  <button function="menu" state="normal">
+    <draw_ops>
+      <icon alpha="0.7"
+            x="0" y="0" width="object_width" height="object_height"/>
+    </draw_ops>
+  </button>
+
+</frame_style>
+
+<!-- styles can inherit from each other with the parent="" attribute. 
+     In a subclass anything can be re-specified to override 
+     the parent style. -->
+<frame_style name="focused" parent="normal">
+  <piece position="title">
+    <draw_ops>
+      <rectangle color="gtk:bg[SELECTED]"
+                 x="0" y="0" width="width-1" height="height-1"/>
+      <title color="gtk:fg[SELECTED]" x="(width - title_width) / 2"
+                                      y="(height - title_height) / 2"/>
+    </draw_ops>
+  </piece>
+</frame_style>
+
+<!-- Maps styles to states of frame. 
+
+     Focus: yes (focused), no (not focused)
+     Window states: normal, maximized, shaded, maximized_and_shaded
+     Window resizability: none, vertical, horizontal, both
+
+     Everything unspecified just does the same as
+     unfocused/normal/both.
+
+     only state="normal" needs a resize="" attribute.
+ -->
+<frame_style_set name="normal">
+<frame focus="yes" state="normal" resize="both" style="focused"/>
+<frame focus="no" state="normal" resize="both" style="normal"/>
+</frame_style_set>
+
+<!-- Each window type needs a style set 
+     Types: normal, dialog, modal_dialog, menu, utility, border
+  -->
+<window type="normal" style_set="normal"/>
+
+
+<!-- For menu icons, drawing methods are needed for the same 
+     four types as the buttons, and GTK states
+     (insensitive,prelight,normal,etc.)
+  -->
+
+<menu_icon function="close" state="normal" draw_ops="previously_named"/>
+
+
+</metacity_theme>
+
+