Snap Section Settings

Discussions related to SoftPro Select user interface development.

Moderator: Phil Barton

Post Reply
JDavis
Posts: 97
Joined: Mon Sep 22, 2008 5:10 pm

Snap Section Settings

Post by JDavis »

In the MyScreens table, some of the snap section defined in the ScreenData column have a "Settings" node. Some of these have a ^ delimeted string which I assume is used to pass in multiple settings. How can we use this mechanism to pass in settings to our custom snap sections?
Mark McKenna

Re: Snap Section Settings

Post by Mark McKenna »

A SnapSection class that allows for runtime per-instance customizations via screen definition XML (for example) is referred to as partitionable. To be partitionable, your ISnapSection class must implement the IPartitionable interface. This contract will require that you provide two members: an IPartition and an IPartitionManager. You provide the classes that implement both. All of these interfaces are defined inside the SoftPro.UI.Base assembly, by the way.

IPartition
The IPartition class you create will interpret and store the data from, say, the caret-delimited Settings data string in the screen definition. The contract defines two members:
  • StringRepresentation: A string that fully describes the data in its entirety (e.g. "16^HelloWorld^Green")
  • DisplayString: A string that provides a user-friendly descriptor for the instance that characterizes its "uniqueness". The latter property is used more for UI purposes (e.g. screen editors and the like) and may be something like "My Company, Hello World, Green 16". Note to self: come up with better examples.
IPartitionManager
The IPartitionManager class you create will manage the creation of your IPartitions. The contract defines three members:
  • SelectPartition: Selects an IPartition from user input. This is reserved for screen management purposes where you may want to provide a custom UI dialog that allows the settings to be provided that, in turn, indicate which partition to retrieve. This can simply return null if you're not concerned about creating custom dialogs for screen customization management (most of ours do just return null).
  • PartitionFromStringRepresentation: Creates a new IPartition using its string representation.
  • MorePartitionsAvailable: Determines if there are any available IPartitions left. Along the same lines as SelectPartition, this is more for screen management purposes and will often simply return true.
So those are the types that make partitionable SnapSections work. To understand how they come together, let me provide a basic pseudocode example.

Code: Select all

class MySnapSection : SnapSectionBase, IPartitionable
{
  private IPartition _partition;
  private IPartitionManager _partitioner;

  public IPartition Partition
  {
    get { return _partition; }
    set
    {
      _partition = value as MyPartition;
      // you can do other stuff here, like set your title using _partition.Title or set the color of a button using _partition.Color
    }
  }

  public IPartitionManager Partitioner
  {
    get
    {
      if ( _partitioner == null ) _partitioner = new MyPartitionManager();
      return _partitioner;
    }
  }
}

internal class MyPartition : IPartition
{
  public int Number { get; private set; }
  public string Title { get; private set; }
  public string Color { get; private set; }

  public string StringRepresentation
  {
    get
    {
      // join your members using some delimiter ( we commonly use a caret ) - like Number^Title^Color
    }
    set  
    {
      // split the string and set your members (reverses the get process)
    }
  }

  public string DisplayString
  {
    get
    {
      // return something friendly using your partition's members like "Number is 16, Title is Something, Color is Green"
    }
  }
}

internal class MyPartitionManager : IPartitionManager
{
  public IPartition SelectPartition(IPartition[] activePartitions, string context)
  {
    // often this can simply return null - this is reserved for providing a custom UI dialog
    // to a user that is building screens and wants to use your SnapSection in the screen 
    // definition by providing the appropriate values
    return null;
  }
  
  public bool MorePartitionsAvailable( IPartition[] activePartitions)
  {
    // along the same lines as the SelectPartition method, this is screen management related and you can often simply return true
    return true;
  }

  public IPartition PartitionFromStringRepresentation( string s )
  {
    // this one is important because this is how your IPartition class will be instantiated using, say, the Settings string from the screen definition XML
    MyPartition partition = new MyPartition();
    // the following works because the setter on MyPartition.StringRepresentation will split the string
    // and set the class members so the MyPartition instance is "ready to use"
    partition.StringRepresentation = s;
    return partition;
  }
}
I intentionally left out some details to try and give you the general framework that you will need to follow. Once you've digested how partitionable SnapSections work, feel free to return here and follow up with any questions.
Post Reply