Userguide

Table of Contents

• Introduction
  • Which properties are handled?
• Getting started
  • Add a library reference
  • Tagging controls
  • Control names
• Start coding!
• Code examples

Introduction

UIPSnap (User Interface Property Snap) is a library for serializing the state of windows forms and controls recursively to XML by reading and writing properties of certain types on a best-effort basis using reflection. It's very simple to use and yet provides some interesting possibilities of customizing.

Which properties are handled?

There are some rules:

• Properties that have simple data types (such as integer, double, string, datetime) or collections of these types.
• All properties that actually can be saved and restored (e.g., if a property describes a read-only collection, it will be skipped)
• Properties of controls (or child-controls) that are tagged. Tagging a control is done in the visual studio form's property grid by entering an integer number into the property field Tag. The number also defines the order in which controls are handled!
• Properties that you want to be saved. Filters can be defined.

Getting started

Add a library reference

The first thing to do is to download the library and copy the UIPSnap.dll into your VS Windows Forms project folder. The add a project reference to the dll.

Tagging controls

The next thing to do is to to select each control in the form's edtior and enter a number into the Tag field. The number defines the order in which controls are handled! If the order is not important, just set every tag field to 0.

Control names

Furthermore, please ensure that each control has a unique Name property! This is important since each control is identified by its name.

Start coding!

Having all controls tagged, you can start coding. Use the toXML and fromXML methods to save and restore the UI state of your controls. You may also use some of the filter methods to gain more control over which properties you actually want to handle. Please refer to the API documentation of the UIPSnap class for this and see the code examples below.

Code examples

Example 1: Save UI state in form closing handler.

private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
  UIPSnap snap = new UIPSnap();
  string xml = snap.toXML(this);
  File.WriteAllText("uistate.xml", xml);
}

Example 2: Restore UI state in form shown handler.

private void Form1_Shown(object sender, EventArgs e)
{
  UIPSnap snap = new UIPSnap();
  snap.register("<name>", "<key>");  // Your personal registration key
  if (File.Exists("uistate.xml"))
  {
    string xml = File.ReadAllText("uistate.xml");
    snap.fromXML(this, xml);
  }
}

Example 3: Remove string type from default type list (no string type properties will be handled).

UIPSnap snap = new UIPSnap();
snap.TypeList.Remove(typeof(string));
snap.toXML(...);

Example 4: Add visibility property name no exclude list (no visibility states will be handled).

UIPSnap snap = new UIPSnap();
snap.ExcludeList.Add("Visible");
snap.toXML(...);

Example 5: Add visibility property name no include list (Only visibility states will be handled).

UIPSnap snap = new UIPSnap();
snap.IncludeList.Add("Visible");
snap.toXML(...);