File:  [mozdev] / chameleon / www / documentation / chameleon-dev-map.html
Revision 1.43: download - view: text, annotated - select for diffs - revision graph
Fri Mar 2 02:43:25 2001 UTC (19 years, 2 months ago) by mondo
Branches: MAIN
CVS tags: HEAD, CHAMELEON_0_02B_BRANCH
changes in style sheets organization

        <b><font size="+1">Chameleon Dev Map (a method to the madness)</font></b>
               
<p>
contributors:
<br>Pavol Vaskovic aka Mondo


<ol>
                                     
  <li> <a href="#Introduction">Introduction</a></li>
                                      
  <li> <a href="#Basic_Design">Basic Design</a></li>
                                      
  <li> <a href="#ui">UI</a></li>
                                      
  <li> <a href="#file_and_directory_structure">File and Directory Structure</a></li>
                                      
  <li> <a href="#Javascript_Classes">Javascript Classes</a></li>
              
  <ul>
                       
    <li><a href="#Javascript_Classes"></a><a href="#PreviewControl_Class">
  PreviewControl</a></li>
                       
    <li><a href="#General_Class">General</a></li>
                       
    <li><a href="#Size_Class">Size</a></li>
                       
    <li><a href="#Font">Font</a></li>
                       
    <li><a href="#Color">Color</a></li>
                       
    <li><a href="#Padding_Class">Padding</a></li>
                       
    <li><a href="#Margin_Class">Margin</a></li>
                       
    <li><a href="#Border_Class">Border</a></li>
                       
    <li><a href="#IO_Class">IO</a></li>
                   
    <li><a href="#Top_Level_Functions">Top Level Functions</a><br>
      </li>
                   
    <li><a href="#Global_Consts">Global Consts</a><br>
     </li>
             
  </ul>
                                      
  <li> <a href="#Edit_Area">Edit Area</a></li>
     
  <ul>
           
    <li><a href="#Browser_Component_Classes">Browser Component Classes</a></li>
        
    <ul>
            
      <li><a href="#Toolbar_Class">Toolbar Class</a></li>
            
      <li><a href="#Menubar_Class">Menubar Class</a></li>
            
      <li><a href="#Personalbar_Class">Personalbar Class</a></li>
            
      <li><a href="#Statusbar_Class">Statusbar Class</a></li>
            
      <li><a href="#Taskbar_Class">Taskbar Class</a></li>
         
    </ul>
    
  </ul>
    
  <li><a href="#Browser_Component_Classes"></a></li>
               
</ol>
         <br>
       &nbsp; <br>
       &nbsp; <br>
       &nbsp; <br>
       &nbsp; <br>
       &nbsp; <br>
       &nbsp; <br>
       &nbsp; <br>
       &nbsp; <br>
       &nbsp; <br>
       &nbsp;        
<p><a name="Introduction"></a> <br>
       <b>Introduction</b> <br>
 The purpose of this document is a feeble attempt to explain some of&nbsp;
the "design" and functionality of Chameleon.&nbsp; I am doing this for two
reasons. I would like to maybe get other developers involved or interested
in the project (you can't really help out on something without some minimal
documentation).&nbsp; I am also doing this for myself while things are still
somewhat fresh in my head. A week from now i will be totally lost in my own
code because i would have forgotten just about everything by then. <br>
       <a name="Basic_Design"></a> <br>
       <b>Basic Design</b> <br>
 Chamelon started out very simply. It was just a sketch on a piece of&nbsp;
paper, which was revised a few times and then i stared coding. I knew the
app needed a menubar, toolbar, edit area, preview area, palate/toolarea and
a status bar. All of the basics found in many client apps these days.&nbsp;
So the UI frame was created first based on boxes drawn on a piece of paper.
I have later come to learn that this method is know as "top down&nbsp; design".
What ever it's called, you have to frame the house before you put up the sheet
rock. </p>
             
<p><a name="ui"></a> <br>
       <b>UI</b> <br>
       <b><font color="#006600">theme_builder.xul</font></b> <br>
       <font color="#000000">This is the parent xul file. </font>All of the
 application  overlays are referenced from this file. <br>
       This is the file used when the app is launched. </p>
       Overlays:       
<table border="1" cellspacing="0" cellpadding="2">
       <tbody>
          <tr valign="Top">
            <td valign="Top" bgcolor="#cccccc">UI <br>
            </td>
            <td valign="Top" bgcolor="#cccccc"><br>
            </td>
            <td valign="Top" bgcolor="#cccccc">File<br>
            </td>
          </tr>
          <tr valign="Top">
        <td valign="Top">menubar</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">menus.xul&nbsp;</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">toolbar</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">toolbar.xul</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">editbar</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">browser.xul</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">tool palate&nbsp;</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">palate.xul</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">statusbar</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">statusbar.xul</td>
        </tr>
                                     
  </tbody>       
</table>
                
<p>These overlays are named and grouped based on the UI. The css style sheets
  are grouped the same way.<br>
     menus.css, toolbar.css, palate.css etc . . . </p>
             
<p><font color="#006600">keyset.xul</font> and <font color="#006600">broadcasterset.xul</font>
        are overlays that contain the keyset and broadcaster elements.<br>
     So they to can be found in one logical place. </p>
             
<p>There is a browser (iframe) element that has <font color="#006600">browser.xul</font>
     &nbsp; as it's initial source file. <br>
      This is so other component bars can be loaded in later by just changing
  the location of the frame.<br>
      For example mail-news.xul, aim.xul etc . . .&nbsp; <br>
     These files are also parent files containing their own overlays. <br>
      This part of the UI content is where the toolbar editable templates
are   displayed.&nbsp; <br>
      When you click on an element in a template it will then be displayed
 in  the preview box. </p>
             
<p><a name="file_and_directory_structure"></a> <br>
       <b>File and Directory</b> <b>Structure</b> <br>
       I tried to lay out the files and directory structure for Chameleon
as  logical  as i could. <br>
       First you have the cvs source directories and then the actual application
    file structure. <br>
       The cvs source is really only a few extra folders up. </p>
             
<p>It looks like this: <br>
       <font color="#660000">chameleon</font> <br>
       &nbsp;&nbsp; <font color="#000099">www</font> &nbsp;&nbsp; &lt;- This is the web site.<br>
       &nbsp;&nbsp; <font color="#000099">scripts</font> &nbsp;&nbsp; &lt;- This is where build and other usefull shell script are kept for Chameleon.<br>
       <font color="#000099">&nbsp;&nbsp; theme_builder</font> &nbsp;&nbsp; &lt;- This is where install.js and the top level dir for xpinstall.<br>
       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <font color="#006600">theme_builder</font>
       &nbsp;&nbsp; &lt;- This is the application root.&nbsp; This folder
is  installed  into the mozilla chrome dir. </p>
             
<p>So starting from the 2nd <i>theme_builder</i> dir we begin the root files
   bundled w/ Chameleon. </p>
             
<p><b>Chameleon Directory Structure</b></p>

<dl class="dir">
  <dt><b>theme_builder</b></dt>

  <dl>
    <dt><b><u>content</u></b></dt>
		<dd> this is the main xul and js directory. There is also other content such
		as xml, html and txt files.</dd>

    <dl>
		  <dt>dialogs</dt>
			<dd>this is where the xul files are stored for the dialogs used in the 
			app.</dd>

		  <dt>html</dt>
			<dd>this is where html and txt files used in the "info" menu are 
			stored.</dd>
		
		  <dt>include</dt>
			<dd>this is where the main xul overlays are stored. These overlays are 
			first children.</dd>
			
			<dl>
			  <dt>include</dt>
				<dd>this is where overlays used by first child overlays are stored. 
				These are 2nd child include/overlay files.</dd>
			</dl>

		  <dt>js</dt>
			<dd>this is where all of the main application javascript files are 
			located. Separate template js files are not stored here.</dd>

		  <dt>templates</dt>
			<dd>this is where the main template files used for preview go. Right now 
			there is only the browser template file.</dd>

		  <dl>
			  <dt>browser</dt>
			  	<dd>this is where the edit templates overlays live.
					The directories in this one are no longer used.</dd>
		  </dl>

		  <dt>toolbars</dt>
			<dd>this is where the main xul files for the main edit
			object bars live. Right now it is just the browser.</dd>

      <dl>
			  <dt>js</dt>
				<dd>this is where the js classes are for the toolbars states normal, 
				hover, active and disabled. This is a major workaround which will be 
				changed.</dd>
      </dl>
			
		  <dt>xbl</dt>
			<dd>this is where xbl files for bound ui widgets live such as the 
			colorpicker.</dd>

		</dl>

		<dt><b><u>locale</u></b></dt>
			<dd>this is where the localization dtd files are stored for various 
			language translations.</dd>
		
		<dl>
		  <dt>en-US</dt>
			<dd>this is where the english strings used in the xul files are 
			abstracted out into entities.</dd>
		</dl>
		
		<dt><b><u>skin</u></b></dt>
			<dd>this is where all of the css, images and templates files are stored for
			the tool.</dd>
		
		<dl>
		  <dt>default</dt>
			<dd>this is where the css and images for the default gray theme of the 
			app live.</dd>
			
			<dl>
			  <dt>images</dt>
				<dd>this is where the images to Chameleon's toolbars are.</dd>
				
			  <dt>style</dt>
				<dd>this is where the css files for Chameleon's UI live.</dd>
				
			</dl>
			
		  <dt>images</dt>
			<dd>this is where the bg grid images and toolbar images for Chameleon 
			live. It is supposed to be toolkit type of images that other skins can 
			use.</dd>

		  <dt>source</dt>
			<dd>this is where the source css files used in preview mode are kept.</dd>
			
			<dl>
			  <dt>navigator</dt>
				<dd>this is where the css preview files  for the navigator component 
				are stored.</dd>
				
				<dl>
				  <dt>skin</dt>
					<dd>this directory i don't think is  used any more.</dd>
					
				  <dt>tmp</dt>
					<dd>this is where the generated navigator.css file is stored for 
					preview.</dd>
					
				  <dt>xbl</dt>
					<dd>this is not used anymore.</dd>
					
				</dl>
				
			</dl>
			
		  <dt>templates</dt>
			<dd>this is where the toolbar template css files are stored.</dd>
			
			<dl>
			  <dt>browser</dt>
				<dd>this is where the browser module css files are kept.</dd>
				
				<dl>
				  <dt>images</dt>
					<dd>template specific images.</dd>
					
				  <dt>style</dt>
					<dd>browser template css files.</dd>
					
					<dl>
					  <dt>ORIG</dt>
						<dd>old stuff need to get rid of.</dd>
						
					  <dt>xbl</dt>
						<dd>need to remove old stuff.</dd>
						
					</dl>
					
				</dl>
				
			  <dt>style</dt>
				<dd>this is old. I think i can get rid of this also.</dd>
				
			</dl>

		  <dt>widgits</dt>
			<dd>widgit toolkit stuff</dd>
			
			<dl>
			  <dt>images</dt>
				<dd>grippy and color picker style images are in here.</dd>
				
			  <dt>style</dt>
				<dd>widgit css style sheets</dd>
				
			</dl>
			
		</dl>
		
	</dl>

</dl>

<p><a name="Javascript_Classes"></a> <br>
       <b>Javascript Classes</b> <br>
       The main js file for Chameleon is <b><font color="#006600">palate.js</font></b>
        . <br>
      This file is pretty much the meat and potatoes of the app. It is broken
  down into a number of javascript classes or objects. 
       Most of these objects are also based on the UI as well. <br>
       &nbsp; </p>
             
<p><b><font color="#006600">palate.js</font></b> classes </p>
         
<table border="1" cellspacing="0" cellpadding="2">
        <tr valign="Top">
        <td valign="Top" bgcolor="#cccccc">Description</td>
         <td valign="Top" bgcolor="#cccccc"><br>
             </td>
         <td valign="Top" bgcolor="#cccccc">JS Class</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">Preview</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">PreviewControl</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">General</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">General</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">Size Tab</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">Size</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">Font Tab</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">Font</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">Color Tab</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">Color</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">Padding Tab</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">Padding</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">Margin Tab</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">Margin</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">Border</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">Border</td>
        </tr>
         <tr valign="Top">
        <td valign="Top">IO</td>
         <td valign="Top">-&gt;</td>
         <td valign="Top">IO</td>
        </tr>
</table>
                
<p><br>
 So very simply the idea is this. <br>
       The preview area has a js class w/ methods and member vars related
to  preview  specific tasks. <br>
       General covers generilized tasks, arrays etc . . . <br>
       The various css tool control tabs have grouped classes relating to
specific functionality from that part of the tool. <br>
       IO class handles all of the io for the app.<b> </b></p>
 

  <br>
  <a name="PreviewControl_Class"></a><br>
  <b>PreviewControl Class</b><br>
  This js class handles all of the functionality related to the Preview section
 of the tool. This section in the UI is broken down in subsections.<br>
   
<ol>
           
  <li>Object Preview</li>
           
  <li>Object Layers</li>
           
  <li>Background Image</li>
           
  <li>Foreground Image</li>
           
  <li>State</li>
           
  <li>Reset</li>
           
  <li>Clear</li>
           
  <li>Attributes<br>
    </li>
   
</ol>
   
<p>So all of these UI pieces have specific relational functionality associated
 with them.&nbsp; There is functionality specific to this area of the tool
 as well as other areas. All of the classes depend on each other to makeup
 the whole of the tool.<br>
  </p>
   
<p><b><a name="General_Class"></a>General Class</b><br>
  This class takes care of generized functionality that is shared by all of
 the other classes. Again there are member vars, arrays and functions in this
 class.</p>
   
<p><b><a name="Size_Class"></a><br>
  Size Class</b><br>
  This class handles all of the functionality for the size tab in the palate
 section of the tool. This is where the css size style rules are stored.The
 actual rules (width:, max-width:, etc) are stored in a member array and the
 settings (1px, 2px, etc) are dynamically drawn from a hidden attribute pool
 in the drop down menus.</p>
   
<p><b><a name="Font"></a><br>
  Font Class</b><br>
  This class handles all of the functionality for the font tab.</p>
   
<p><b><a name="Color"></a><br>
  Color</b> <b>Class</b><br>
  This class handles all of the functionality for the color tab.</p>
 
<p><b><a name="Padding_Class"></a><br>
 Padding Class</b><br>
 This class handles all of the functionality for the padding tab.</p>
 
<p><b><a name="Margin_Class"></a><br>
 Margin Class</b><br>
 This class handles all of the functionality for the margin tab.</p>
 
<p><b><a name="Border_Class"></a><br>
 Border Class</b><br>
 This class handles all of the functionality for the border tab.</p>
 
<p><b><a name="IO_Class"></a><br>
 IO Class</b><br>
 This class handles all I/O for the app. Things like "Save theme", "Preview",
"Load" etc . . .&nbsp; <br>
 This class relies heavily on io.js lib. <br>
 </p>
 
<p><br>
   <b><a name="Top_Level_Functions"></a><br>
  Top Level Functions<br>
 </b>There are a number of top level or global functions<b> </b>here.<br>
 </p>
   
<p>A lot of these classes are big and need to be broken down some more into
   sub classes. This is on my todo list. <br>
       Perhaps these classes should be in their own files as well. <br>
       &nbsp; </p>
 
<p> </p>
   
<p><b><font color="#006600"><font color="#000000"><a name="Global_Consts"></a>
  Global Consts</font><br>
  globals.js</font></b> contains most of the reuseable string consts used
by <font color="#006600">palate.js</font>. <br>
       I use the js const type like a #define. <br>
       Both of these js files are included in the overlay file <font color="#006600">
       palate.xul</font> which is an overlay for <font color="#006600">theme_builder.xul</font>
        .</p>
 
<p> </p>
             
<p> </p>
             
<p> </p>
             
<p><br>
 <a name="Edit_Area"></a> <br>
     <b>Edit Area</b> </p>
             
<p>The edit area is the part of the app where the editable templates are displayed.
This idea is this. You prep a xul file stripping out all of the event handlers
and attributes accept for class and id. If the element is anonymous content
(xbl) then you need to bring that content into the templateas well. Thisis
really all a work around and needs a better implementation.This was also not
part of the scope for the first generation of the application.&nbsp;It would
be nice to parse a xul file get the content tree and the associated&nbsp;
  attributes that Chameleon needs and generate a new editable xul template
 file.The only problem i can see doing this is dealing w/ anonymous content.
 This needs looking into in the future. I think this can be a seperate module
 of the tool and part of an import or transpose feature.</p>
           
<p>After you have preped a template file, you need to place an event handler&nbsp;
  on the container of this file that points to the main edit API method for&nbsp;
  the app. It is called <font color="#000099">parseElement(event.target)</font>
    . This method takes the dom element object from the template xul file
and&nbsp;  creates a duplicate of that element (using the dom call createElement)
in&nbsp;  the preview area for editing. There are associated hidden attributes
and attribute flags used as well. The template files for the browser component
 are <font color="#006600"> toolbar.xul</font>, <font color="#006600">menubar.xul</font>
   , <font color="#006600"> personalbar.xul</font>, etc . . .&nbsp; and they
 live in the templates/browser dir. <i>toolbar.xul</i> is the actual file
that displays the navigator toolbar in the edit area of the tool. These files
have specific css files as well. You guesed it, these files are called toolbar.css,
 menubar.css, personalbar.css, etc . . . you get the idea. They live in the
 skin/templates/browser/style. </p>
       
<p> </p>
           
<p>So when you use the tool, you are applying css style rules to the newly
  created element that is in the preview window by using the palate widgits
  to the right. Then you apply these changes back to the original element
in  the edit area. This is done with a simple dom call to setAttribute.&nbsp;
  </p>
           
<p>This is a very basic overview here. The rules are all stored depending&nbsp;
  on what state you are editing in (normal, hover, etc) as js arrays hidden&nbsp;
  in&nbsp; attributes of the element being edited. The default style rules
 of these templates are also stored in js arrrays in classes named to reflect&nbsp;
  the state you are in. Ex: normal.js has a Normal class, hover.js has aHover&nbsp;
  class. These classes are created and initialized when you startup the app.
  These "default"&nbsp; style objects hang out and are calledon when youshift
 through modes.<br>
     So for when example you choose hover as a mode to edit, the defaultstyle&nbsp;
  in the the toolbar will come from the Hover object which isin <font color="#006600">
    &nbsp; hover.js</font>. The style attributesfor all of the editable elements
  in&nbsp; the template toolbar will beset with the predefined style rules
  stored in&nbsp; the js array.&nbsp;This would be the modern theme in this
  case.</p>
           
<p>So now since any of the edits you have made are all stored in js arrays&nbsp;
  we can do whatever we want with this data like save it to a css file. Which&nbsp;
  is the whole purpose of the tool. Generating css files. <br>
       &nbsp;</p>
 <b><a name="Browser_Component_Classes"></a><br>
 Browser Component Classes<a href="#Edit_Area"></a></b><br>
<font color="#006600"><b>toolbars/js/browser.js</b></font><br>
This file is the main js file for all of the browser component templates.
The dir is named poorly and i will change it. It should be toolbars/browser/js
or something along those lines. Anyway, here is where all of the specific
functionality for the editable templates live. Most of the functions aretop
level. I probably should create a general class, because these functionsare
generic and will be resused. That is providing all of the other template xul
files are based on this stucture.<br>
This i am waiting until i implement an entirely new component just to be sure.<br>
<br>
<b><a name="Toolbar_Class"></a><br>
Toolbar Class</b><br>
This class has an array of id's used in the toolbar xul template. These id's
are cycled through in loops in many functions. If you want to reset the toolbar
back to it's defalut style for example, you need to loop through the elements
that have style attributes set and unset them. Or if you want to hightlight
the borders of each element in the toolbar, same thing. <br>
<br>
<b><a name="Menubar_Class"></a><br>
Menubar Class</b><br>
This class is the same as the Toolbar class it holds an array of id's for
the menubar template xul file.<br>
<br>
<b><a name="Personalbar_Class"></a><br>
Personalbar Class</b><br>
This class is the same as the Toolbar class it holds an array of id's for
the personalbr template xul file.<br>
<br>
<b><a name="Statusbar_Class"></a><br>
Statusbar Class</b><br>
This class is the same as the Toolbar class it holds an array of id's for
the statusbar template xul file.<br>
<br>
<b><a name="Taskbar_Class"></a><br>
Taskbar Class</b><br>
This class is the same as the Toolbar class it holds an array of id's for
the taskbar template xul file.<br>
<br>
 
<p>      &nbsp; <br>


<?php require(ANNOTATE); ?>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>