Table of Contents

theSharedObj.flush()
theSharedObj.flush(minimumDiskSpace);

Arguments

minimumDiskSpace

An optional integer specifying the amount of local disk space requested for the current domain, in bytes. This allows you to request more disk space than is required by theSharedObj. If minimumDiskSpace is omitted, flush( ) requests the amount of space returned by theSharedObj.getSize( ).

Returns

The string value "pending" if more disk space is required to store the object, or a Boolean: true if the save succeeded, false if it failed.

Description

The flush( ) method attempts to save theSharedObj.data's properties to an .sol file, as described under SharedObject.getLocal( ). Functionally, it is similar to the automatic save that occurs when the movie is unloaded from the Player, but it offers a movie the chance to ask the user for more disk space if required.

When flush( ) executes, Flash checks the local storage settings for the domain from which the movie was loaded. If local storage is set to "Never" for the domain, flush( ) simply returns false and the SharedObject is not saved. If the allowed local storage space is greater than both the size of the SharedObject and the value of minimumDiskSpace, flush( ) returns true and the SharedObject is saved. If the allowed local storage space is less than either the size of the SharedObject or the value of minimumDiskSpace, flush( ) returns "pending" and Flash prompts the user to increase the local storage space limit. Once the user has either allowed or denied the request to increase the limit, theSharedObj.onStatus( ) handler is invoked with an infoObject that indicates whether the save attempt succeeded.

The minimumDiskSpace argument is used to force Flash to request from the user more space than the SharedObject actually requires. This prevents Flash from repeatedly requesting space each time a SharedObject grows.

Example

The following code shows a typical Save button for a game. The game stores a large amount of game data in a SharedObject. When the Save button is pressed, the movie reports save progress and, if necessary, asks the user to authorize space to save the game. The getSize( ) method is used to show the user the game's space requirements. Notice that a complete save interface requires an implementation for onStatus( ):

// Create the SharedObject.
var gameData_so = SharedObject.getLocal("gameData");
// Assign a large map object as a property (assume mapObj holds the game data).
gameData_so.data.customUserMap = mapObj;
// Call saveGame() when save_btn is pressed.
save_btn.onRelease = saveGame;
   
// The saveGame() function attempts to save the shared object
function saveGame () {
  // Create a text field to tell the user what's happening.
  this._parent.createTextField("output_txt", 1, 0, 0, 300, 100);
  output_txt.border = true;
  output_txt.wordWrap = true;
   
  // Tell the user that saving has started.
  output_txt.text =  "Saving game...please wait...\n";
  // Request space based on getSize(). Divide by 1024 to convert bytes to KB, and
  // ask for 10 KB extra up front to prevent repeated requests for more room.
  output_txt.text += "Space required: "
                  + (Math.floor(gameData_so.getSize() / 1024) + 10) + "KB.\n";
   
  // Save the SharedObject and store the return value in a local variable.
  var saveAttempt = gameData_so.flush(gameData_so.getSize() + 10240);
  // If flush( ) returned...
  if (saveAttempt =  = true) {
    // ...true, the save was successful, and we're done.
    output_txt.text += "Game saved.\n";
  } else if (saveAttempt =  = "pending") {
    // ..."pending", Flash asks the user for more disk space.
    // The user's decision is reflected by the infoObject
    // passed to onStatus() when the user closes the settings dialog box.
    output_txt.text += "Please increase disk space to continue.\n";
  } else if (saveAttempt =  = false) {
    // ...false, the user has permanently disabled.
    // local storage for this domain. Ask the user to enable local storage.
    output_txt.text += "Save failed. To enable saving, "
                    +  "uncheck 'Never' under Local Settings.\n";
    // Just to make our point, open the local storage settings dialog box
    // where the user can reenable storage by unchecking the Never option.
    System.showSettings(1);
  }
}
   
// Callback invoked after a flush() overflow precipitated a
// "pending" condition. User has been prompted and either increased
// the domain's disk space limit or denied the request.
gameData_so.onStatus = function (infoObject) {
  // The infoObject.code property tells us what happened.
  if (infoObject.code =  = "SharedObject.Flush.Success") {
    // Yay! They gave us space!
    output_txt.text += "Required disk space added. Game saved.";
  } else if (infoObject.code =  = "SharedObject.Flush.Failed") {
    // Oh well. No space granted. We can't save the game.
    output_txt.text += "Insufficient disk space. Save failed.";
  }
}

See Also

SharedObject.getSize( ), SharedObject.onStatus( ), System.showSettings( )

Table of Contents