How To Add A Form Splitter

Why Use A Splitter?

Before explaining form splitters, is important to understand how D365 added a lot of improvements to the way forms are displayed.

In D365, forms naturally will resize themselves based on the size of your browser window. Notice, as you resize your browser window, form controls will automatically resize. Grids will automatically show scroll bars. Fields in field groups will change what columns they appear in to fit. In web design, this is called following a ‘responsive‘ design.

In AX 2012 and before, the system is not run in a browser. Additionally the forms to not automatically resize themselves. Scrollbars are added when the window is too small to see everything. Therefore developers had to do more work to control how to the fields were shown to ensure they were visible.

All that said, in AX 2012 and in D365, splitters allow for more control on what part of the form is given more space in the window. And that is why they are important to know how to create and use.

Form Splitter Examples

Before deciding to add a splitter, it would be helpful to better understand what they do and do not do. To explain, let’s look at a couple examples.

Vertical splitter

First, to see an example of a vertical form splitter, navigate to General ledger>Currencies>Currency exchange rates in D365. Notice, this form has two small lines in between the grid on the left, and the tabs on the right.

Next, move your mouse and hover over these two small lines. The entire vertical bar will change to a dark grey.

Next, click and hold with your mouse. Then, drag either to the right or to the left.

Notice, the form will resize to either have more space on the right or left side. Let go of your mouse when the form is at the desired size.

This functionality is very useful for ensuring you can see all of the columns in the left side grid without needing to use the scroll bars.

In this example, this form uses the form pattern ‘Simple List and Details – Tabular Grid‘. The form is named ‘ExchangeRate‘ in the Application Explorer. I will explain how to add a splitter in Visual Studio later in this article.

It is important to note that the similar form pattern ‘Simple List and Details – List Grid‘ does not have a splitter. This is because the ‘List Grid‘ form pattern will only have two fields in the grid, shown stacked on top of each other. Therefore, there isn’t a need to resize the width of this section of the form.

Horizontal Splitter

Additionally, to see an example of a horizontal form splitter, navigate to Accounts payable>Broker and royalties>Broker claims.

Similar to a vertical splitter, there exist two lines between the two grids on the form.

To use the splitter, move your move and hover over these two small lines. Notice, the entire horizontal bar will change to dark grey.

Next, click and hold with your mouse. Then, drag either up or down.

Notice, the form will resize to either have more space on the top or bottom. Let go of your mouse when the form is at the desired size.

This is very useful when you have a lot of rows in the top or bottom grid that you wish to see without scrolling.

In this example, this form uses the form pattern ‘Task Double‘. The form is named ‘MCRBrokerClaims‘ in the Application Explorer. I will explain how to add a splitter in Visual Studio later in this article.

AX Vs D365

In earlier versions of Microsoft Dynamics AX 2012 and before, adding a form splitter required writing quite a bit of code. However, in later versions of AX 2012 and D365, adding a splitter has become much simpler. And does not require writing any x++ code.

In D365, developers can apply a form pattern to a form. And if the form is either a ‘Task Double‘ form pattern or a ‘Simple List and Details‘ form pattern, no additional code is needed. The system itself handles the functionality as if it were a special control and makes the splitter work.

In the later versions of AX 2012, Microsoft made adding a splitter easier in a similar way. After adding the Group control, a developer just needs to set the ‘Style’ property to ‘SplitterVerticalContainer‘ or ‘SplitterHorizontalContainer‘. See the ‘AssetGroup‘ form for an example.

Setting this style actually adds code to the class declaration and init methods. And this code lets the user use the splitter control. Additionally, see Microsoft’s documentation here.

However, if you are using a trying to add a splitter to an earlier version of AX 2012 you will need to add some code. I will explain the steps for adding a splitter in versions earlier than AX 2012 a little later in the article.

In theory, you could also add this code to a custom form pattern in D365. (I have not tried it). However, this is not recommended. Instead, use one of the form patterns that support adding a splitter without adding code.

Task Double Horizontal Splitter

Fortunately, in D365, adding a horizontal splitter to a form that uses pattern ‘Task Double‘ is very easy.

First, in the form designer, right click the ‘Design’ node. Then, click ‘Apply pattern>Task Double’.

Notice, the ‘Pattern’ window will show you that you need to add a Group control between the parent and child sections of the form. Open the ‘MCRBrokerClaims’ form as an example.

In this example, there is a Group control named ‘CtrlSplitHori‘. Interestingly enough, a splitter is not a special type of control. It is just a Group control with the right properties and form pattern applied.

Next, there are several properties on the Group that must be set.

Set the ‘Height Mode‘ property to ‘Auto‘
Set the ‘Hide if Empty‘ property to ‘No‘
Set the ‘Width Mode‘ property to ‘SizeToAvailable‘

As can be seen, that is all that is needed to make the splitter form. Behind the scenes, the system will add what is needed to make this control work as a splitter.

Simple List and Details Vertical Splitter

Similarly, in D365, adding a vertical splitter to a form that uses pattern Simple List and Details is very easy. For instructions on how to create a form see my article ‘Simple List and Details Form in D365‘.

First, in the form designer, right click the ‘Design’ node. Then, click ‘Apply pattern>Simple List and Details – Tabular Grid‘. Or if using a tree control click ‘Apply pattern>Simple List and Details – Tree‘. Importantly, the form pattern ‘Simple List and Details – List Grid’ does not use a splitter.

Notice, the ‘Pattern’ window will show you that you need to add a Group control between the parent and child sections of the form. Open the ‘ExchangeRate‘ form as an example.

In this example, there is a Group control named ‘ListDetailSplitter‘. Again, it is interesting to see that a splitter is not a special type of control. It is just a Group control with the right properties and form pattern applied.

Next, there are several properties on the Group that must be set.

Set the ‘Height Mode‘ property to ‘Auto‘
Set the ‘Hide if Empty‘ property to ‘No‘
Set the ‘Width Mode‘ property to ‘Auto‘

Notice, that the ‘Width Mode‘ property is set to ‘Auto‘ in the case of a vertical splitter. Whereas with a horizontal splitter it is set to ‘SizeToAvailable‘.

Adding A Form Splitter Before AX 2012

In earlier versions of AX 2012, and before, you had to add several pieces of code in order to add a splitter. With most people using D365 now, it is unlikely you will need to know this. However, for the sake of being complete, I will include those steps here.

The BOMTable is a form that I found in AX 2012, that still uses the old way to add a horizontal splitter. Let’s look at the code as an example.

AutoDeclaration

First, set the AutoDeclaration property on the splitter Group control and the Group above the splitter control to ‘Yes‘. In this example, the BomTable form’s splitter control is named ‘VersionGrp‘. And the group about it is named ‘TableGrp‘.

Additionally, set the Width property to ‘Column width‘, and the ‘Height‘ property to ‘Column height‘.

Class Declaration

Second, add the following line of code to the class declaration method on the form for a horizontal splitter.

SysFormSplitter_Y               formSplitter;

To add a vertical splitter, instead, declare a variable of type ‘SysFormSplitter_X‘.

Init Method

Third, add the following line to the ‘init‘ method on the form, anywhere after the line of code that calls super().

formSplitter = new SysFormSplitter_Y(versionGrp,tableGrp,this);

The first parameter of the constructor, is the name of the Group control that is the splitter. The second parameter is the name of the group control that is above the splitter. Lastly, the third parameter should always be passed ‘this‘, which refers to the form object itself.

MouseDown, MouseMove, and MouseUp

Fourth, right click on the ‘Methods‘ node under the splitter Group control, and select ‘New Method‘. Add the mouseDown method:

int mouseDown(int x, int y, int button, boolean ctrl, boolean shift)
{
    int ret;

    ret = super(x, y, button, ctrl, shift);

    return formSplitter.mouseDown(x, y, button, ctrl, shift);
}

Repeat the steps to add a method to splitter group, and add the mouseMove method:

int mouseMove(int x, int y, int button, boolean ctrl, boolean shift)
{
    int ret;

    ret = super(x, y, button, ctrl, shift);

    return formSplitter.mouseMove(x,y,button,ctrl,shift);
}

One more time, repeat the steps to add a method to the splitter group. Add the mouseUp method:

int mouseUp(int x, int y, int button, boolean ctrl, boolean shift)
{
    int ret;

    ret = super(x, y, button, ctrl, shift);

    return formSplitter.mouseUp(x, y, button, ctrl, shift);
}

In summary, I have shown below all of the methods and groups you need to modify to add a form splitter in earlier versions of AX 2012 and before.

Conclusion

While splitters often go un-noticed, they can be a very useful tool in helping make form as easy to use as possible. They allow users to resize areas of the form to show more of what they need to see. And reduce time scrolling back and forth. The way splitters are implemented have changed multiple times. My hope is this article will help you understand how to add a form splitter no matter what version of Dynamics you are using.

Peter Ramer

Peter Ramer is a part of the Managed Application Services team at RSM working on Microsoft Dynamics 365. He focuses on the Retail and Commerce industries. When he is not solving problems and finding ways to accelerate his clients' business, he enjoys time with his three kids and amazing wife.