Developer Reference XML Display Settings

The S57DisplaySettings class allows standard control over how an ENC is rendered and a little more besides.

We can turn off, for example, the display of "Radar conspicuous objects".

myDisplaySettings.ViewingGroup[22210] = false;

A new feature for ENCX 2.0 is the ability to get or set the current state of the display settings as a chunk of XML.

Now you can persist and restore display settings without writing a lot of code. You can easily allow the display settings to be tweaked using a config file.

The XML also serves to document the S-52 (display standard for ENC) text for each viewing group e.g. that text viewing group 22 is "bearing for directional lights". You could use this text when building a user interface for the display settings.

Reading the settings

var encDraw = new ENCX.S57Draw();
string xml = encDraw.DisplaySettings.XML;

They look something like below (except I chopped out a bunch of lines to make the article more readable, see the full glorious XML)  

<S57DisplaySettings Schema="1">
    <Version>S-57 Edition 3.1.2, S-52 version 3.4 (including MD07)</Version>
        <MoreDetailedDataAvailable >false</MoreDetailedDataAvailable >
        <ViewingGroup Number="10000" Value="true" Description="Display Base" />
        <ViewingGroup Number="11000" Value="true" Description="Information about the Chart Display" />
        <TextGroup Number="10" Value="true" Description="Important Text" />
        <TextGroup Number="11" Value="true" Description="vertical clearance of bridges,  overhead cable, pipe or conveyor (BRIDGE, CBLOHD, PIPOHD, CONVYR, VERCSA, VERCLR, VERCCL, VERCOP), bearing of  navline, recommended route, deep water route centreline line, recommended track  (NAVLNE, RCRTCL, DWRTCL, RECTRC, ORIENT), name and communications channel of radio calling-in point (RDOCAL, OBJNAM, COMCHA)." />
        <TextGroup Number="20" Value="false" Description="Other text" />
        <TextGroup Number="21" Value="false" Description="names for position reporting: name or number (OBJNAM) of buoys (BOYxxx), beacons(BCNxxx), daymarks (DAYMAR), light vessel, light float  (LITVES, LITFLT), offshore platform (OFSPLF)" />

There is a straightforward mapping between XML elements and the properties of the S57DisplaySettings class.

Writing settings back from XML

Is simple!

encDraw.DisplaySettings.XML = xmlString;

There are a few things to note though:

Some bits of the XML are read only - supplying an alternative string in a Version element will have no affect on ENCX, likewise trying to change the Description attribute of a viewing or text group).

If you omit some elements from the XML then the default value (as if you had created a brand new S57Draw) will be used. Merging (see below) is different in this regard.

You could replace the following code with an XML string...

Private Sub SetupDisplaySettings()
    draw.DisplaySettings.ImprovementsLevel = ENCX.S57DisplayImprovements.S57DisplayImprovements_Max
    CheckEncImprovements.Checked = True
    draw.DisplaySettings.TextGroup(10) = True
    draw.DisplaySettings.TextGroup(26) = True
    draw.DisplaySettings.SafetyContourMetres = 10.0
    draw.DisplaySettings.SafetyDepthMetres = 10.0
    draw.DisplaySettings.ViewingGroup(11000) = False
    draw.DisplaySettings.ViewingGroup(21030) = False
    draw.DisplaySettings.ViewingGroup(33010) = True ' Soundings(SOUNDG)
    draw.DisplaySettings.ViewingGroup(33020) = True ' depth contours (DEPCNT) other than the safety contour, line depth area (DEPARE)
    draw.DisplaySettings.ViewingGroup(33021) = True ' label for the safety contour
    draw.DisplaySettings.ViewingGroup(33022) = False ' label for contours other than the safety contour
    draw.DisplaySettings.SetViewingGroupRange(31000, 31040, False)
    draw.DisplaySettings.TwoColourShadingForDepthZones = False
End Sub

Translates to...

<S57DisplaySettings Schema="1">
        <ViewingGroup Number="11000" Value="false" />
        <ViewingGroup Number="21030" Value="false" />
        <ViewingGroup Number="31000" Value="false" />
        <ViewingGroup Number="31010" Value="false"  />
        <ViewingGroup Number="31011" Value="false" />
        <ViewingGroup Number="31020" Value="false" />
        <ViewingGroup Number="31030" Value="false" />
        <ViewingGroup Number="31040" Value="false" />
        <ViewingGroup Number="33010" Value="true" Description="Soundings (SOUNDG)" />
        <ViewingGroup Number="33020" Value="true" Description="depth contours (DEPCNT) other than the safety contour, line depth area (DEPARE)" />
        <ViewingGroup Number="33021" Value="true" Description="label for the safety contour" />
        <ViewingGroup Number="33022" Value="false" Description="label for contours other than the safety contour" />
        <TextGroup Number="10" Value="true"/>
        <TextGroup Number="26" Value="true"/>

Whether to code property settings individually or use XML is up to you - there's probably not a clear "best" choice, it will depend on your application and your judgement.

Merging settings

Merging is slightly different in that when a setting is omitted the existing state of that setting will get used.

That's in contrast to when you set the XML property of an S57DisplaySettings object with an incomplete XML string omitting some elements where it will use the default values for those elements.