XDATA Tutorial

In this tutorial we will make an XDATA editor.
XDATA is extra data that can be stored in any IGEMS entity. This is a powerful tool for app developers to store custom data.

The tutorial covers these tasks.

• Getting and setting XDATA for an entity
• Simple GridView to edit the data

Start by creating an IGEMS API project

Register the APP

In your DLL register an APP using this code.

public class Class1
{
  public static void DLLMain()
  {
    API.RegisterCommand("xdatatutorial", "xdatatutorial", null, XDATATutorial);
  }

  private static void XDATATutorial()
  {
  }
}

Implement the XDATATutorial method

Let's implement the XDATATutorial method.
We will select an entity and call a dialog to edit the XDATA in that entity.

The code looks like this.

private static void XDATATutorial()
{
  var entity = API.PickEntity("Select entity");
  Dictionary<string, string> xdata = API.GetXData(entity);
  if(XdataEditor.Apply(xdata))
  {
    API.ClearXData(entity);
    foreach(var kv in xdata)
      API.SetXData(entity, kv.Key, kv.Value); 
  }
}

First we pick an entity using the API.PickEntity function.
We get the XDATA in the entity using the API.GetXData function.
We then call the XdataEditor dialog to edit the XDATA. (Shown below).
After editing the XDATA we first clear the current XDATA in the entity and then write the new edited data using the functions API.ClearXData and API.SetXData.

XDATA Editor

The editor to edit the XDATA looks like this.

It's a simple form using a DataGridView to edit the XDATA.

Start by adding a New form to your project.

Name the form XdataEditor.

In this form we add a DataGridView and two Buttons (OK and Cancel).

Add two columns to the DataGridView, Name and Value.

You can design the form as you wish, I usually add a panel at the bottom of the form with Dock=Bottom and add the OK and Cancel buttons there. Then I set Dock=Fill on the DataGridView.

I also set the EditMode=EditOnEnter on the DataGridView.

Here is a movie showing how to design the form. Design form.

Code

Here is the full code for the XdataEditor form. What we do is to fill in the DataGridView with the XDATA. Then when pressing OK we simply transfer the rows in the DataGridView to the XDATA dictionary and return.

using System;
using System.Collections.Generic;
using System.Windows.Forms;

namespace XDATATutorial
{
  public partial class XdataEditor : Form
  {
    Dictionary<string, string> xdata;
    public XdataEditor(Dictionary<string,string> xdata)
    {
      InitializeComponent();
      this.xdata = xdata;
    }

  public static bool Apply(Dictionary<string, string> xdata)
  {
    using(XdataEditor xdataEditor = new XdataEditor(xdata)) 
    {
      if (xdataEditor.ShowDialog() == DialogResult.OK)
        return true;
    }
    return false;
  }

  private void XdataEditor_Load(object sender, EventArgs e)
  {
    foreach (var kv in xdata)
      dataGridView1.Rows.Add(kv.Key, kv.Value);
  }

  private void button1_Click(object sender, EventArgs e)
  {
    xdata.Clear();
    foreach(DataGridViewRow row in dataGridView1.Rows) 
    {
      if (row.Cells[0].Value != null && row.Cells[0].Value.ToString().Trim() != "" && row.Cells[1].Value != null)
        {
          string key = row.Cells[0].Value.ToString();
          string val = row.Cells[1].Value.ToString();
          xdata.Add(key, val);
        }
      }
    }
  }
}

Full code of Class1

And here is the full code of Class1.

using IGEMSAPI;
using System.Collections.Generic;

namespace XDATATutorial
{
  public class Class1
  {
    public static void DLLMain()
    {
      API.RegisterCommand("xdatatutorial", "xdatatutorial", null, XDATATutorial);
    }

    private static void XDATATutorial()
    {
      var entity = API.PickEntity("Select entity");
      Dictionary<string, string> xdata = API.GetXData(entity);
      if(XdataEditor.Apply(xdata))
      {
        API.ClearXData(entity);
        foreach(var kv in xdata)
          API.SetXData(entity, kv.Key, kv.Value); 
      }
    }
  }
}