Editing TkMadagascar (section)

== General workflow ==

=== A new session === 

When a new instance of tkMadagascar is opened, the user is presented with an empty Sandbox.  To get started, the user should open the '''Program browser''' from the '''View''' menu.  The user may then browse, select, and add as many Flows, Plots or Results as they would like from the Program browser.  

=== Interacting with Flows, Plots and Results === 

Flows, Plots and Results appear in the Sandbox after they are added by the Program browser.  All behaviors and actions that we describe are equally valid for Flows, Plots, and Results.  For simplicity, we refer to only Flows from here on.

You may move Flows by clicking and dragging with the left mouse-button.  Additionally, all Flows are initially added to the Sandbox in the '''unconfigured''' state.  To configure a Flow you must edit its parameters, selecting valid values for the parameters that you wish to set.  To edit a Flow's parameters, you can '''right-click''' over the Flow, which will bring up a drop-down menu.  Select '''Edit parameters''' from this drop-down menu, which opens a menu with a list of parameters and entry boxes.

=== Configuring Flows ===

Once the '''Edit parameters:''' window is open, you can simply input values for the parameters that you want to set.  You only need to enter the value, you do not need to enter the value in "key=val" format.  There are some special parameters that every Flow has:

'''output''' - the name or names of files that you want to output to.  If multiple files, then separate the names with a space.  You do not need to include '.rsf' on the end of file names.

'''input'''  - the name or names of files that you want to input to.  Same rules as above.

'''custom''' - a raw string of any additional parameters that you want to set.  You must set these parameters in "key=val" format, unlike the other parameters.  There is no parameter checking for parameters set this way.  Multiple parameters should be separated by spaces.

Additionally, some programs have parameters that work on any axis.  For example, sfspike allows the user to set the number of samples (n#) for any axis.  These parameters are listed as the parameter name, with the # still attached.  These parameters must be set with "key=val" formatting as well. 

For sfspike's n# parameter, you might set:  n#=   n1=100 n2=100

Once a Flow is configured, the Flow will change color to have a green background and the name of the output file will appear inside the flow.  A green Flow is good-to-go, and does not require any additional configuration.  It will be automatically saved, exported, or executed.  Unconfigured Flows may be saved, but will not be exported or executed.

Click '''Accept''' to save your parameter selections.
Click '''Preview''' to see how the Flow would look in an SConstruct (useful for debugging).
Click '''Self-documentation''' to see the Programs self-documentation while editing parameters.

=== Linking Flows === 

One of the nicest features of Madagascar is that programs can pipe their output to other programs, greatly reducing the need for intermediate files.  This functionality is fully supported by tkMadagascar.  To link two Flows, right click on the flow that you want to link to another Flow, and select ''' Link'''.  The cursor will change to a cross-hair to indicate that you are in '''Link''' mode.  Once in '''Link''' mode, click on the Flow that you want to link to.  The Flow that is selected for linking is assumed to have desired output for the Flow that you right-clicked on.  

Once Linked, the two Flows move together, their borders change color, and their input and output parameters are automatically changed to reflect the fact that one is piping into the other.  The border colors change as follows:
Flows  become light gray,
Plots become light purple,
Results become light blue.

To '''Unlink''' a Flow, simply '''right-click''' on the Flow you wish to unlink, and then select unlink.  The Flow will be detached.  The other Flows in the Linked Flow will be detached as well, or placed into separate Linked Flows.

=== Deleting Flows === 

To delete a Flow from the Sandbox simply '''right-click''' on the Flow, and select '''Delete'''.  If you select '''Delete''' for a Linked Flow, then you will delete all Flows linked to it.