How can I layout this class to make it easier to use for API developers?

I have an application that allows the user to place a string of text into a PDF document. I have three different ways that they can do this:

• Use a Form Field. Then they have four properties to define:

• Provide field name

• provide instance of the field

• provide an X-axis Offset

• provide a Y-axis Offset

• Search for a string of text. Then they have four properties to define:

• Provide string of text to search for

• provide instance of that string of text

• provide an X-axis Offset

• provide a Y-axis Offset

• Define Page Coordinates. Then they have three properties to define:

• Provide page number

• provide an X-axis Offset

• provide a Y-axis Offset

In my API, I want the object to be setup intuitively so that it is clear they are choose one of the three different methods and then whichever one they choose, they have the options for each.

In my old API, all of those options are grouped together as a list of properties like this:

Placement.FormField_FieldName
Placement.FormField_Instance
Placement.SearchText_Text
Placement.SearchText_Instance
Placement.PageCoordinates_PageNumber
Placement.XOffset
Placement.YOffset

I find this to be a little confusing for the developer using the API because you could never use all of the properties together.

You would either use Form Field like this:

Placement myPlacement = new Placement();
myPlacement.FormField_FieldName = "MyPdfFormFieldName";
myPlacement.FormField_Instance = ;
myPlacement.XOffset = 0;
myPlacement.YOffset = 0;

Or use Text Search like this:

Placement myPlacement = new Placement();
myPlacement.SearchText_Text = "My String Of Text";
myPlacement.FormField_Instance = 1;
myPlacement.XOffset = 0;
myPlacement.YOffset = 0;

Or use Page Coordinates like this:

Placement myPlacement = new Placement();
myPlacement.PageCoordinates_PageNumber = "My String Of Text";
myPlacement.XOffset = 0;
myPlacement.YOffset = 0;

Is there a better way to setup the class (or sub cla

not very sure about your placement class, whether it's a pure class designed to encapsulate options, or a win-form.

If it's the former, i would suggest you use Polymorphism to have certain abstract layer, a quick sample:

At your side:

public abstract class Placement
{
    public int XOffset { get; set; }
    public int YOffset { get; set; }

    public class FrmField:Placement
    {
        public string FieldName { get; set; }
        public int Instance { get; set; }
    }

    public class TextSearch:Placement
    {
        public TextSearch(){}
        public string Text { get; set; }
        public int Instance { get; set; }
    }

    public class PageCoord : Placement
    {
        public string PageNumber { get; set; }
    }
}

public class SomeObjRequriePlacement
{
    public void DoSomething(Placement pla)
    {
        // this class and method may be a winform that do something based on given options
    }
}

Other dev using your api:

public class TestAtDev
{
    public void TestGeneric()
    {
        Placement pla = null;
        if (false) //some condition
        {
            pla = new Placement.FrmField() { FieldName = "", Instance = 1, XOffset = 1, YOffset = 2 };
        }
        else if (true) // some condition
        {
            pla = new Placement.PageCoord() { PageNumber = "xxx", XOffset = 1, YOffset = 2 };
        }
        else
        {
            pla = new Placement.TextSearch() { Text = "", XOffset = 1, YOffset = 2 };
        }

        var someObj = new SomeObjRequriePlacement();
        someObj.DoSomething(pla);        
    }
}

if your Placement class is already an UI components, i would then suggest you separate the options away and wrap them as PlacementOption and use it in your placement class.

and if necessary, you may define an interface to make the code more independent. And Generic (like Type constraint) could make your code even tidier.

EDIT:

use type constraint to have strong typed object where necessary - but the basic implementation of the placement is still the same.

public abstract class HandlePlacement where T:Placement
{
    public virtual void DoWork(T thePlacement) { }
}

public class HandleTextSearch : HandlePlacement
{
    public override void DoWork(Placement.TextSearch thePlacement)
    {
        // do some specific work for text search option
    }
}

/*implementations for other placement options*/
/* ... */

public class TestAtDev
{
    public void DoTextSearch()
    {
        Placement.TextSearch ts = new Placement.TextSearch() { XOffset = 0, YOffset = 1, Instance = 2, Text = "" };
        HandlePlacement hanlder = new HandleTextSearch();
        hanlder.DoWork(ts);
    }
}

another sample:

public abstract class SomeHandler
{
    public virtual void DoWork() { }
}

public abstract class SomeHandler:SomeHandler where T : Placement
{
    protected SomeHandler(T thePlacement)
    {
        this.Placement = thePlacement;
    }

    protected T Placement { get; set; }
}

public class SomeHandlerForTextSearch : SomeHandler
{
    public SomeHandlerForTextSearch(Placement.TextSearch ts):base(ts){}

    public override void DoWork()
    {
        // some specific handling for text search
    }
}

public class SomeHandlerForPageCoord : SomeHandler
{
    public SomeHandlerForPageCoord(Placement.PageCoord pc) : base(pc) { }

    public override void DoWork()
    {
        // some specific handling for page coordinates
    }
}

public class TestAtDev2
{
    public void DoSomeTest()
    {
        SomeHandler h = null;
        if (true) // some condition
        {
            h = new SomeHandlerForTextSearch(new Placement.TextSearch() { XOffset = 1, YOffset = 2, Instance = 3, Text = "test" });
        }
        else if (true) // some condition
        {
            h = new SomeHandlerForPageCoord(new Placement.PageCoord() { XOffset = 1, YOffset = 2, PageNumber = "PageNo." }); 
        }
        h.DoWork();
    }
}

StackExchange Code Review Q#42382, answer score: 4