FLASHCARD TUTORIAL

This file is divided in several sections, explaining how each section works. The final section is a series of advice on how to accomplish upgrades to the system. Please see the GALLERY section for information on uploading images to the background image galleries, and also adding/editing gallery names.

			_____________________________

CONFIG
______

This is what the basic config file looks like:

	<config>
		<skin name="default" src="skins/default.swf" cfg="skins/default.xml"/>
		<loader
			font="Verdana"
			fontSize="10"
			fontColor="000000"
			border="aaaaaa"
			bar="0000aa"
			background="ffffff"
			width="250"
		/>
		<strings
			loadApp="loading card application"
			gallery="loading gallery"
			fonts="loading fonts"
			strings="loading strings"
			skin="loading skin"
			skinConfig="loading skinConfiguration"
			initialising="initialising..."
		/>
	</config>


The config file will be parsed by the loader to create the initial loading screen. It tells Flash which font to use, its size, its color, the border of the square bars, the background color of the bars, and the color of the loading bars themselves. The width parameter means the total width of the string plus the loadBar.

The strings element contains the strings to be used for the loading of each different element. Note that loading gallery refers to the gallery.php script. The pics won't be loaded till the user tries to select a background. This is the same with the fonts. Font files won't be loaded till one of them is used.

You can use different language files by calling the movie using loader.swf?lang=es. This will tell the system to load config_es.xml, and strings_es.xml. If no lang parameter is sent to the loader, it'll just load config.xml and strings.xml, which in this case are english, but could be set by the user to be any language.

The config file also tells the user what skin and skin configuration file to use.


			_____________________________

HTML TEMPLATE
_____________

This is just a plain html file. The strings %to, %from and %img will be substitued by the saveImage.php for the appropiate values. %to and %from can be used in the subject string in config.inc as well.

			_____________________________

GALLERY
_______

The background galery is organized by directories. Each directory is an image category. The name of the directory is not important in itself, although they MUST all begin with an integer number, followed by a -, then a descriptive name. The numbers cannot repeat themselves. The actual names shown by the application are found in the appropiate strings_xx.xml file, and the association between these names and the galleries is made using the number before the "-" symbol in the gallery name.

So for example, if we have the gallery

1-my photos

we'll have an entry in the english language file like this:

<string name="1" value="my photos"/>

and in the spanish language file (note: do not use accented letters or non-Latin symbols):

<string name="1" value="mis photographias"/>

Please note that your images must be (a) JPG format, (b) non-progressive, and (c) optimized. Flash is somewhat picky about the JPGs that it loads, so if it doesn't work for you, try using a more advanced image editor, like Photoshop or Fireworks, which produce 'cleaner' JPGs.

			_____________________________

STRINGS
_______

This is basically an xml file with lots of <string/> elements, each of them with two attributes, name and value.

The name is how the app knows where to put the value. So the name parameter should not change. All the strings found in the current files should be included in any localization of the app. The first group of strings are used mainly as window titles and texts, the next 2 groups are tooltips for the buttons.

An important note. There's also a <strings> section in each skin's config file. These tell the app what's the name of the text field into which to put a certain string value from the strings.xml file. Note that these strings will be set only once when the skin is loaded. Thus, they cannot point to an object that will be created dynamically. If a new string was to be added to the skins (as a copyright notice), a new entry should appear in the strings configuration file, and in the skin configuration file.
			__________________________________

SKINS
_____

Each skin aims to have all the visual elements needed right in the screen when opened in the flash authoring environment. No hidden objects in the library that will be attached later.

For resizing, the skin is divided in 9 separate sections, lefttop, middletop, righttop...the four corners are never resized, they're just moved when the window is resized. The other sections can be composed by any number of internal movieclips, and the name of these movieclips must be specified to the application by means of the skin config file. The sections themselves will never be resized, only the specified movieclips in the top, left, right, bottom and center part will. You'll find the configuration for these clips in the window tag. The 5 elements inside the window element are compulsory. The attribute resize takes as value the names of the movieclips inside the GUI sections that'll be resized. Plenty of effects can be achieved using this method.

Most of the other parts of the config file modify the colors of different clips in the skin.

These are the tags that can be found in a skin config file:

* WINDOW

	<window>
		<top resize="mask,gradient,back" />
		<left resize="mask,gradient,back" />
		<drawArea resize="back" />
		<right resize="mask,gradient,back" />
		<bottom resize="mask,gradient,back" />
	</window>

* CONFIG

	<config drag="title" defaultColor="aaaaaa" />

	This node defines config parameters. The drag attribute can be either title or window. It defines what part of childwindow is draggable, either the title, or the whole background of the window. defaultColor sets the color of the card, in case the user selects no background picture.


* BACKGROUNDWINDOW

	<backgroundWindow area="999999" shade="aaaaaa" highlight="555555" normal="0099ff" normalShade="0066aa" normalHighlight="33bbff" selected="0066cc" selectedShade="2288ee" selectedHighlight="0033aa"/>

	This node defines some colors for the background selection window:
	
	-area: the container of the thumbnails.
	-shade: shade for the container, bottom and right lines surrounding the area.
	-highlight: highlight for the container, top and left lines surrounding the area.

	-normal and selected define the colors of the squares surrounding the thumbnails, either in normal state, or selected state. Proper shade and highlight arguments work as for the container area.


* GRID

	<grid color="000000" spacing="20"/>

	The color of the lines of the grid when snap to grid is selected, and the spacing among lines. Note that this color is applied with a 50% alpha. This prevents the grid lines from covering totally other lines in the drawing, notably when using the line or rectangle drawing tools.


* CHILDWINDOW

	<childWindow>
		<back resize="mask" />
		<top resize="line,titleBar" />
		<left resize="line" />
		<drawArea resize="mask" />
		<right resize="line" />
		<bottom resize="line" />
		<okButton location="childWindow.mbp.okButton"/>
		<cancelButton location="childWindow.mbp.cancelButton"/>
		<closeButton location="childWindow.rtp.closeButton"/>
		<container location="childWindow.container"/>
		<comboBox location="childWindow.cmb"/>
		<txt location="childWindow.str"/>
		<loadBar location="childWindow.loadBar"/>
		<loadProgress location="childWindow.loadBar.mask"/>
		<emails location="childWindow.emails"/>
	</childWindow>

	Defines the behaviour of the childWindows. The childWindow movieclip in the skin will be used for all the windows in the system: messageboxes, background selection, email sending...The first 6 elements work just as in the main window. For resizing purposes. Note that only the background selection window is resizable, but all the others also have to adjust their size to their contents, so they use resizing as well.
	
	Subsequent elements (after first 6) point to the location of different elements used by the system. The system must know where these elements are to know which ones to hide when showing another window, and to give each element it's proper functionality.


* BUTTONS

	<buttons>
		<button name="mainPane.sendButton" func="send"/>
		<button name="mainPane.undoButton" func="undo"/>
		<button name="mainPane.redoButton" func="redo"/>
		<button name="mainPane.cutButton" func="cut"/>
		<button name="mainPane.copyButton" func="copy"/>
		<button name="mainPane.pasteButton" func="paste"/>
		<button name="toolPane.selectButton" func="select"/>
		<button name="toolPane.pencilButton" func="pencil"/>
		<button name="toolPane.lineButton" func="line"/>
		<button name="toolPane.circleButton" func="circle"/>
		<button name="toolPane.rectButton" func="rect"/>
		<button name="toolPane.textButton" func="text"/>
		<button name="toolPane.bringToFrontButton" func="bringToFront"/>
		<button name="toolPane.sendToBackButton" func="sendToBack"/>
		<button name="toolPane.floatButton" func="float"/>
		<button name="toolPane.sinkButton" func="sink"/>
		<button name="toolPane.gridButton" func="grid"/>
		<button name="toolPane.bgButton" func="bg"/>
		<button name="toolPane.stretchButton" func="stretch"/>
		<button name="toolPane.trashButton" func="trash"/>
	</buttons>

	Tells the system where each button is, and what it's function is. All of them are compulsory, a missing button will mean that a certain functionality is not available in that skin. To allow for different layouts and namings in the skin (although different namings is not advised, for consistency), the system doesn't know where each button is, so it must be told through the name attribute. This means buttons could be anywhere in the resizable sections.
	
	You can put the trash button in the right bottom corner movieclip, for example, and tell the system where it is using these XML tags.


* OPTIONS

	<options>
		<drawOptions name="optionPane.drawOptions" />
		<textOptions name="optionPane.textOptions" />
	</options>

	Similar to buttons, tells the system where the drawOptions and the textOptions are. As these two movieclips are not always visible, the system must know where to find each. So those two tags are compulsory as well.
	
	I haven't tested a posible configuration with both sets of options visible at once, but it might work. However the clips inside the option clips must have the name they have in the current skins, and be directly inside the drawOptions or textoptions movieclips. These includes the bold, italic and underline buttons, as well as the comboboxes, checkboxes and color swatches. They can be in any position you like, as long as they can be reached at [optionMovieClip.Component]


* STYLE

	<style name="GUIComponents">
		<items>
			<item name="optionPane.textOptions.cmbFont" />
			<item name="optionPane.textOptions.cmbSize" />
			<item name="optionPane.drawOptions.lineOpt.chk" />
			<item name="optionPane.drawOptions.lineOpt.cmb" />
			<item name="optionPane.drawOptions.fillOpt.chk" />
			<item name="childWindow.cmb" />
		</items>
		<properties>
			<property name="face" value="f3f3de" />
		</properties>
	</style>

	You can have as many style tags as you want. They define styles for components that can be styled using flash MX (flash player 6) style handling functions. Each style tag has 2 elements, an "items" element, and a "properties" element. Inside the items element you can include as many elements as you want, with the complete path to them. In the properties element you'll find tags with a property style name, and the value it has to be set to. There's a whole list of the different style options in the docs directory (styles.txt). Styles will be applied to checkboxes and comboboxes.
	
	The name attribute in the style tag is not used within the system and it can have any value.


* COLORGROUP

	<colorGroup name="over light color buttons">
		<items>
			<item name="mainPane.sendButton.over" />
		</items>
		<colors>
			<color element="line" value="ff0000" />
		</colors>
	</colorGroup>

	This is a more generic kind of styling, usable to set colors of every movieclip in the skin. Basically, if you want a movieclip to be uniformily of any particular color, you define the elements to be affected (within the items tag), and then which movieclips inside these elements will have their color changed. So in the example above mainPane.sendButton.over.line would be set to bright red. If you try to set the color of a clip that doesn't exist nothing will happen.


* STRINGS

	<strings>
		<string str="ok" location="childWindow.mbp.okButton.str"/>
		<string str="cancel" location="childWindow.mbp.cancelButton.str"/>
		<string str="backgroundWindowTitle" location="childWindow.str"/>
		<string str="childWindowTitle" location="childWindow.title"/>
	</string>

	Allows the system to identify strings that must be set when the movie is first loaded. The str parameter is the string identifier, and the location is where the textfield is within the skin movie. The actual string that will be shown must be in the appropiate language strings_xx.xml file.

			__________________________________


ADVICE FOR UPGRADERS
____________________

	* new skins:

	As you'll need to add code and modify the already existing skins, I wouldn't recommend creating the new skins right away. Instead of that, use one of the existing skins to add any new elements to it and test the code. Once everything's working, add elements to the other skin, then create the new ones. For creating new skins, I find most useful to create a copy of one of the existing ones, then replace each movieclip by turn. This makes sure nothing's forgotten, and things skins keep a similar structure among themselves. Try to use the same names for the instantiated movieclips as the ones in the skins, as this will make it easier for you to write new config files for the skins, and it'll make sure the system works properly.

	* rotate text:

	This touches several sections in the code. Basically you should go to the selectElement function, and see how elements on the screen are selected, and the selection area drawn over them. Then you can figure a way to add new rotation handles to the selection areas. All the resizing handles are currently drawn in drawSelectArea or drawLineSelectArea (for lines, as the selection handles work differently). Maybe you can use the side handles for resizing and the corners for rotating.

	To rotate, take a look at handleResize, this is how the resize handles work.

	Take a look at how the undo/redo system works too, follow the comments in the code on this topic, as you'll have to integrate element rotation into it. cut/copy/paste will need some retouching as well. Also the serialize function (that transforms the image into xml to send it to the php script) would need modifications.

	* shadows or embossing:

	Probably can be done through duplicateMovieClips, but this one would be the toughest I think. Each element upon creation is assigned a redraw function (you can find the redraw functions of all the elements in the endPaint function, where they are assigned). You should probably modify redraw so that when an element has an emboss option set, the proper action is taken. Depending on the element this might be one thing or another, for example with text you can create 4 overlaying textfields below the original one, a bit displaced to surround it, and with different colors. That's just a suggestion...

	* installer

	The installer should also modify the variables in config.inc for the php scripts. Depending on the reach of the installer, it can be simple or quite complex. Basically, if it's just for creating the main config file, it should be easy to do. If the installer is supposed to allow you to modify the skin configuration files, that might do things more difficult. I guess you'd need a description file for each skin, saying where each component is, and what subitems it has. Then the skin could be loaded into some kind of GUI that allowed the user to select each component in turn, zoom on the skin to see the little components, switch between the normal, over and press state of every button, and allow the user multiple selections...to finally output a skin config file. This looks like a difficult project, but probably very interesting as well. Maybe the components of the skins should be linked in the library so that they can be attached (with attachMovie) separately to some kind of disection table where the user picks the color for each part of the component.


That's all, folks!

Thanks for using FlashCard,

Darren