syntaxdialogdm-script

What is the purpose of the container_items argument in box, tab, or group creation?

I'm working with a UI library where I create containers such as tabs, boxes, and groups. These functions take a parameter called container_items (or items) as one of their arguments:

DLGCreateTab( TagGroup &tab_items, string label )
DLGCreateBox( String title, TagGroup &items )
DLGCreateGroup( TagGroup &items )
DLGCreateRadioList( TagGroup &items )

Originally, I believed I had to use container_items.DLGAddElement() to add elements to these containers. However, I discovered that calling container.DLGAddElement() achieves the same result.

Additionally, for some widgets like radio buttons, the constructor also accepts a container_items argument.

My Question: Could someone explain when and why we should use the container_items (or items) argument versus adding elements directly to the container using DLGAddElement()? What is the intended use case for this parameter?

Any insights or documentation references would be greatly appreciated.

Solution

  • (Nearly) all DLG... commands are essentially utility methods that build a tagGroup, where the tagGroup describes what the dialog will be like. For debugging or learning purpose it is often helpful to show this tagGroup. If different commands yield the same tagGroup, they indeed are identical in function.

    To display a TagGroup, you can use

    TagGroupOpenBrowserWindow(tagGroup myTags, string Name, bool isFileBased)

    with mytags being the TagGroup to be displayed (the one you create with DLGCreateDialog) and

    with Name just being the title of the shown dialog and

    with isFileBased indicating whether or not the tags (if changed) should be saved once the dialog is closed.

    number addToContainer = 1

string infoStr = "Items added to " + (addToContainer?"Container":"ContainerItems")

taggroup dlg, dlgItems
dlg = DLGCreateDialog("Test",dlgItems)

taggroup box, boxItems
box = DLGCreateBox("Box 1",boxItems)

if ( addToContainer )
{
    box.DLGAddElement(DLGCreateLabel(infoStr))
    dlg.DLGAddElement(box)
}
else
{
    boxItems.DLGAddElement(DLGCreateLabel(infoStr))
    dlgItems.DLGAddElement(box)
}

dlg.TagGroupOpenBrowserWindow(infoStr,0)

Alloc(UIFrame).Init(dlg).Display(infoStr)

    gives youResults:

    As you can see, both methods give you the same dialog and (nearly) the same tag structure, but adding to the container instead of the container items tags adds an "invalid" flag. I would guess, adding to the items is the "correct" way, but when adding to the container itself, the underlying code 'fixes' it for your. Quite likely some convenience behavior added at later state.

    Example regarding comment on tabs:

    taggroup dlg,dlgitems
dlg=DLGCreateDialog("Dialog",dlgitems)

taggroup box,boxitems
box=DLGCreateBox("Box",boxitems)
box.DLGAddElement(DLGCreateLabel("Just some boxy stuff"))

dlgitems.DLGAddElement(box)

taggroup tablist1,tabitems1
tablist1=DLGCreateTabList(tabItems1)

taggroup tab1 = tabitems1.DLGAddTab("Tab1")
tab1.DLGAddElement(DLGCreateLabel("Page #1"))

taggroup tab2 = tabitems1.DLGAddTab("Tab2")
tab2.DLGAddElement(DLGCreateLabel("Page #2"))
dlgitems.DLGAddElement(tablist1)


taggroup tablist2,tabitems2
tablist2=DLGCreateTabList(tabItems2)

taggroup tab3 = tabitems2.DLGAddTab("Tab3")
tab3.DLGAddElement(DLGCreateLabel("Page #3"))

taggroup tab4 = tabitems2.DLGAddTab("Tab4")
tab4.DLGAddElement(DLGCreateLabel("Page #4"))
dlgitems.DLGAddElement(tablist2)


dlg.TagGroupOpenBrowserWindow("Tab",0)
Alloc(UIFrame).Init(dlg).pose()