Mailing List |
Source Code |
Pavol Vaskovic aka Mondo
- Browser Component Classes
The purpose of this document is a feeble attempt to explain some of the "design" and functionality of Chameleon. 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). 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.
Chamelon started out very simply. It was just a sketch on a piece of 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. 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 design". What ever it's called, you have to frame the house before you put up the sheet rock.
These overlays are named and grouped based on the UI. The css style sheets
are grouped the same way.
menus.css, toolbar.css, palate.css etc . . .
keyset.xul and broadcasterset.xul
are overlays that contain the keyset and broadcaster elements.
So they to can be found in one logical place.
There is a browser (iframe) element that has browser.xul
as it's initial source file.
This is so other component bars can be loaded in later by just changing the location of the frame.
For example mail-news.xul, aim.xul etc . . .
These files are also parent files containing their own overlays.
This part of the UI content is where the toolbar editable templates are displayed.
When you click on an element in a template it will then be displayed in the preview box.
File and Directory Structure
I tried to lay out the files and directory structure for Chameleon as logical as i could.
First you have the cvs source directories and then the actual application file structure.
The cvs source is really only a few extra folders up.
It looks like this:
www <- This is the web site.
scripts <- This is where build and other usefull shell script are kept for Chameleon.
theme_builder <- This is where install.js and the top level dir for xpinstall.
theme_builder <- This is the application root. This folder is installed into the mozilla chrome dir.
So starting from the 2nd theme_builder dir we begin the root files bundled w/ Chameleon.
Chameleon Directory Structure
- this is the main xul and js directory. There is also other content such as xml, html and txt files.
- this is where the xul files are stored for the dialogs used in the app.
- this is where html and txt files used in the "info" menu are stored.
- this is where the main xul overlays are stored. These overlays are first children.
- this is where overlays used by first child overlays are stored. These are 2nd child include/overlay files.
- this is where the main template files used for preview go. Right now there is only the browser template file.
- this is where the edit templates overlays live. The directories in this one are no longer used.
- this is where the main xul files for the main edit object bars live. Right now it is just the browser.
- 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.
- this is where xbl files for bound ui widgets live such as the colorpicker.
- this is where the localization dtd files are stored for various language translations.
- this is where the english strings used in the xul files are abstracted out into entities.
- this is where all of the css, images and templates files are stored for the tool.
- this is where the css and images for the default gray theme of the app live.
- this is where the images to Chameleon's toolbars are.
- this is where the css files for Chameleon's UI live.
- 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.
- this is where the source css files used in preview mode are kept.
- this is where the css preview files for the navigator component are stored.
- this directory i don't think is used any more.
- this is where the generated navigator.css file is stored for preview.
- this is not used anymore.
- this is where the toolbar template css files are stored.
- this is where the browser module css files are kept.
- template specific images.
- browser template css files.
- old stuff need to get rid of.
- need to remove old stuff.
- this is old. I think i can get rid of this also.
- widgit toolkit stuff
- grippy and color picker style images are in here.
- widgit css style sheets
The main js file for Chameleon is palate.js .
So very simply the idea is this.
The preview area has a js class w/ methods and member vars related to preview specific tasks.
General covers generilized tasks, arrays etc . . .
The various css tool control tabs have grouped classes relating to specific functionality from that part of the tool.
IO class handles all of the io for the app.
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.
- Object Preview
- Object Layers
- Background Image
- Foreground Image
So all of these UI pieces have specific relational functionality associated
with them. 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.
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.
A lot of these classes are big and need to be broken down some more into
sub classes. This is on my todo list.
Perhaps these classes should be in their own files as well.
globals.js contains most of the reuseable string consts used by palate.js.
I use the js const type like a #define.
Both of these js files are included in the overlay file palate.xul which is an overlay for theme_builder.xul .
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. It would be nice to parse a xul file get the content tree and the associated 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.
After you have preped a template file, you need to place an event handler on the container of this file that points to the main edit API method for the app. It is called parseElement(event.target) . This method takes the dom element object from the template xul file and creates a duplicate of that element (using the dom call createElement) in the preview area for editing. There are associated hidden attributes and attribute flags used as well. The template files for the browser component are toolbar.xul, menubar.xul , personalbar.xul, etc . . . and they live in the templates/browser dir. toolbar.xul 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.
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.
This is a very basic overview here. The rules are all stored depending
on what state you are editing in (normal, hover, etc) as js arrays hidden
in attributes of the element being edited. The default style rules
of these templates are also stored in js arrrays in classes named to reflect
the state you are in. Ex: normal.js has a Normal class, hover.js has aHover
class. These classes are created and initialized when you startup the app.
These "default" style objects hang out and are calledon when youshift
So for when example you choose hover as a mode to edit, the defaultstyle in the the toolbar will come from the Hover object which isin hover.js. The style attributesfor all of the editable elements in the template toolbar will beset with the predefined style rules stored in the js array. This would be the modern theme in this case.
So now since any of the edits you have made are all stored in js arrays
we can do whatever we want with this data like save it to a css file. Which
is the whole purpose of the tool. Generating css files.
Browser Component Classes
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.
This i am waiting until i implement an entirely new component just to be sure.
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.
This class is the same as the Toolbar class it holds an array of id's for the menubar template xul file.
This class is the same as the Toolbar class it holds an array of id's for the personalbr template xul file.
This class is the same as the Toolbar class it holds an array of id's for the statusbar template xul file.
This class is the same as the Toolbar class it holds an array of id's for the taskbar template xul file.