A new construct in the DocumentTools:-Components package called State allows you to manage computation state that will survive through a saved worksheet and through restart.  Programming your applications using this construct also makes it easier to embed multiple different versions of the same application, with different data and options. Consider the following two interactive pie chart examples created using the package below.  

$\mathrm{PieChartPlot}\left(\left[''A'' \= 5\, ''B'' \= 4\, ''C'' \= 3\, ''D'' \= 2\, ''E'' \= 3\, ''F'' \= 4\, ''G'' \= 5\right]\right)\;$

Options Annular: 3-D: Color: blueblue/rosebrightbrowndark graydefaultgreengreen/bluegreen/violetlight bluelight graypurpleredtanyellowyellow/red Explode: none ABCDEFG Labels: defaultnonerelativeabsolute Outline: Sector: 0..3600..180180..3600..90

$\mathrm{PieChartPlot}\left(\left[1\,1\,3\,4\,4\,5\,5\,5\,7\right]\right)\;$

Options Annular: 3-D: Color: blueblue/rosebrightbrowndark graydefaultgreengreen/bluegreen/violetlight bluelight graypurpleredtanyellowyellow/red Explode: none 13457 Labels: defaultnonerelativeabsolute Outline: Sector: 0..3600..180180..3600..90

The PieChartPlot command module is defined below.  The SetDefaults command creates a state variable, which is used to hold all mutable information relating to this application, including the plot data and options settings.  Additionally, the InsertContent command now accepts a state option that can be used with the state component variable name.  When reexecuting—even with different data—the application can call GetProperty("",'contentstate') in order to access the state of the application that is being replaced.  In this way it can inherit whatever properties it wants from the previous application and preserve them when displaying the new data.

Small Example with Explanation

This example defines an application that uses a slider to move along the $x$-axis of a plot.  When you drag the slider to the right, the plot view will move to the right along the $x$-axis.  The slider will then snap back to the middle position, allowing you to grab it and move it to the right again.  In this way you can move further and further along the $x$-axis.

Tip: To interact with this example, open this help page as a worksheet.

The application can be described as follows:

The action handler—the code that gets run when someone moves the slider—is defined below.  It gets passed the state variable, from which it can see and update the current position offset.  The position records how far left or right we have scrolled along the $x$-axis.  We get the slider value, adjust our position, redraw the moved plot, and snap the slider back to the middle.

Note that the above two procedures could be put in startup code (via Edit>Startup Code), or they can be auto-initialized by setting Format>AutoExecute>Set.  If either is done, when this worksheet is loaded both of these procedure definitions will be executed.

Now that the app and handler are defined, we can run a command to insert the content:

Peeking into Existing Content To "Remember" Settings

In the following modification to moveLeftRightApp, we call DocumentTools:-GetProperty("",'contentstate');   This will return non-NULL if the content that we are inserting is going to replace existing content. We then additionally check if we are about to replace the same kind of content—by putting a unique signature on the state variable.  If the signatures match, then we can initialize the new app based on some of the settings of the old app.  For example, here we start at the same position that was previously left.

Two things need to happen:

If you open this help page as a worksheet you can try reexecuting the following example with different values for the negative exponent.  Notice that the $x$-axis offset remains the same between executions.