• Home
• Programs
• Tutorials
• Contact
• About

DCL List Tile Dependency

Introduction

This function is a generalisation of the example shown in my List Box Synchronisation tutorial, wherein the items displayed in a DCL list tile (i.e. either a list_box or popup_list tile) are dependent on the items selected in other list tiles.

The example explained in my tutorial is inherently restricted to only two list tiles, with additional list tiles requiring the code to be rewritten & restructured. In contrast, the function offered here can enable and manage a dependency between any number of list tiles, without needing to alter the code in any way.

Action Function

Function Description

This function performs all of the heavy lifting to enable a dependency between a supplied list of DCL list tile keys, initialising the various list contents, configuring the necessary action_tile expressions to facilitate the dependency, and managing the selections made by the user.

So much of the DCL management is performed by this function that the calling program need only supply a list of DCL tile keys, and two symbols pointing to the list data and initial selection configuration, the function will then modify the value held by the second symbol argument as the user interacts with the dialog interface.

The function will also ensure that the user's selection is retained where possible - that is, if the user has selected the third item in a dependent list, and then changes the selected item in the parent list, the function will automatically attempt to select the third item in the new list of items displayed by the dependent list tile, or the first item if no third item exists.

The list of DCL tile keys supplied to the function should be in order of dependency, that is, if a list tile with key "list1" is to control the items displayed by another list tile with key "list2", then the Action Function should be supplied with a list '("list1" "list2") as DCL tile "list2" depends on "list1".

The lst-sym argument should be a quoted variable (whose symbol is not equal to lst-sym) whose data is a hierarchical list of strings representing the data to be displayed in each list tile.

Such list should take the following format:

(

    (
        "Item 1"
        (
            "Item 1-1"
            (
                "Item 1-1-1"
                (
                    ...
                    (
                        "Item 1-...-N"
                        (
                            "Item 1-...-N-1"
                            "Item 1-...-N-2"
                            ...
                            "Item 1-...-N-N"
                        )
                    )
                    ...
                )
                ...
            )
            ...
        )
        (
            "Item 1-2"
            (
                "Item 1-2-1"
                (
                    "Item 1-2-1"
                    ...
                )
                ...
            )
            ...
        )
        ...
    )
    ...
)

The rtn-sym argument should also be supplied as a quoted variable (again, whose symbol is not equal to rtn-sym), and is both an input & output argument.

The data held by the quoted variable should be a list of positive integers representing the zero-based indexes of the items that are to be initially selected when the dialog is displayed. The number of integers in the list held by the variable should be equal to the number of DCL list tiles that are to be managed by the function.

As the user interacts with the various list tiles, the data held by the supplied rtn-sym variable will be automatically updated by the function to represent the items currently selected by the user.

Example Function Call

The following example demonstrates how the function should be invoked for a dialog comprised of two list tiles with tile keys "list1" & "list2":

(setq lst
   '(
        (
            "Item 1"
            (
                "Item 1-a"
                "Item 1-b"
                "Item 1-c"
            )
        )
        (
            "Item 2"
            (
                "Item 2-a"
                "Item 2-b"
                "Item 2-c"
                "Item 2-d"
                "Item 2-e"
            )
        )
        (
            "Item 3"
            (
                "Item 3-a"
                "Item 3-b"
            )
        )
    )
)
(setq rtn '(0 0)) ;; Initial selection
(LM:dcld:action '("list1" "list2") 'lst 'rtn)

Get Items Function

Function Description

This function is a 'convenience function' included to assist the calling program to interpret the items selected by the user in each of the list tiles controlled by the Action Function.

When supplied with a list of integers representing the zero-based indexes of the selected items from each list tile (as per the data held by the rtn-sym argument above) and the list data (as held by the lst-sym argument above), this function will return a list of items residing at each index in the data.

Example Function Call

Use the list data from the example above, this function may be evaluated in the following way:

_$ (LM:dcld:getitems '(0 1) lst)
("Item 1" "Item 1-b")

Demonstration

The following is a demonstration of the five list example program as part of the demo package available to download from the link at the top of the page.

• Back to Top
• Home
• Programs
• Tutorials
• Contact
• About

Designed & Created by Lee Mac © 2010