Situational Awareness Projects > Customize a Project > Add a Generic List to a Page

Add a Generic List to a Page

You can add a generic list to a page using the following Genies:

To apply formatting to the list rows and enable on-click commands, you can also add the List Row Genie.

ClosedAdd a list Genie

To add a list Genie ("genericlist" or "genericlist_v") to a page:

  1. Open a page in Graphics Builder.
  2. Click the Paste Genie button in the objects toolbox.

    3. Or, select Paste Genie from the Edit menu.

  3. In the Paste Genie dialog, select the Library "sa_controls".
  4. Select one of the following from the Genie list and click OK.
    • genericlist = Generic List Genie
    • genericlist_v = Generic List Vertical Genie

    The Genie is pasted onto the graphics page. A dialog box will open, prompting you to configure the parameters for the Genie.

    The Generic List Vertical Genie dialog box will show the following parameters:

    • AN — the number that is displayed is the AN value that was automatically applied to the Genie when it was pasted on the page.
    • GenericListFillFunction — this field specifies the user Cicode function to be called at runtime to populate the list. The function needs to retrieve the data to be displayed.

    In the example below, "Test_GenericListFill" has been entered. To view the custom Cicode that this function calls, see the Cicode examples below.

    The Generic List Genie dialog box will include some additional parameters that enable runtime interaction with the header row. By default, the OnColumnReorderedFunction will display "ArrayView_SetFormat()". This is a system function that allows an operator to rearrange the header row columns at runtime.

  5. Click OK to close the parameters dialog box.

To load data into the list at runtime, you need to call the required Cicode function as an On Page Entry command in the Page Properties dialog.

  1. In Graphics Builder, right-click on the page and select Page Properties from the menu that appears.

    2. Or:

    From the File menu, select Properties.

    The Page Properties dialog box will appear.

  2. On the Events tab, select the On page entry event.
  3. In the On page entry command field, enter the required expression.

    4. In the example above, the "Test_GenericListCreate" function has been entered. To view the custom Cicode that this function calls, see the Cicode examples below.

  4. On the Events tab, select the On page exit event.
  5. In the On page exit command field, enter an expression to destroy the list that has been created. For an example, search locate "Test_GenericListDestroy" in the example Cicode below.
  6. Click OK, and Save your page.
ClosedAdd the List Row Genie
  1. In Graphics Builder, open the page that includes the list to which you want to add a List Row Genie.
  2. Click the Paste Genie button in the objects toolbox.

    3. Or, select Paste Genie from the Edit menu.

  3. In the Paste Genie dialog, select the Library "sa_controls".
  4. Select one of the following from the Genie list, based on the approximate size of the list your require.
    • list_row_x5 – use this to create a list with up to 5 rows.
    • list_row_x10 – use this to create a list with up to 10 rows.
    • list_row_x40 – use this to create a list with up to 40 rows.
    • list_row_x80 – use this to create a list with up to 80 rows.

    The Genie is pasted onto the graphics page. A dialog box will open, prompting you to configure the parameters for the Genie.

    Note: There is no need to adjust the size of the List Row Genie on a graphics page to fill an area. The required space will be determined at runtime by the size of the list with which it is associated.

  5. In the ArrayAN field, enter the AN value for the associated list.

    6. You can use the Cicode function DspGetAnFromName to retrieve the AN. For example:

    DspGetAnFromName("GenericList").

  6. To enable on-click commands, go to the LeftClickCommand and/or RightClickCommand fields and enter the required Cicode.

    7. See the Cicode example Test_GenericListRightClick below.

  7. Click OK, and Save your page.

You can now run your project and view the alarms list.

Cicode Examples

The following Cicode provides an example of how to create the following generic list using Citect SCADA's Array Functions. The list displays random numbers with column and row identifiers.

ClosedTest_GenericListCreate 

FUNCTION Test_GenericListCreate(INT hAn)
   INT bDrawHeader = 1;  // Draw the header row
   INT hFontRow = DspFontHnd("SA_AlmRow");
   INT hFontHeader = DspFontHnd("SA_AlmRow");
   INT nColumn = 1;
   INT nColumns = 5;
   INT nRows = 10;
   INT nRowHeight = 20;  // pixels
   INT nHeight = (nRows + 1) * nRowheight;
   INT nWidth = 280;     // pixels
   INT nWidthTotal = 0;  // Pixels, sum of column widths
   INT nDataColumns = 10;  // Maximum possible number of data columns
   INT nDataRows = 40;  // Maximum possible number of data rows

   INT hArray = ArrayCreateByAn(hAn , nColumns + 1, nRows + 1, ARRAY_ZINDEX_MAX);	
   // +1 for Column0 (hidden), +1 for Row0 (hidden)
   STRING sMapName = ArrayGetMapNameByAn(hAn);

// Set up array attributes

ArraySetIntByAn(hAn, nWidth,      ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_XMAX);
ArraySetIntByAn(hAn, nHeight,     ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_YMAX);
ArraySetIntByAn(hAn, nRowHeight,  ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_ROWHEIGHT);
ArraySetIntByAn(hAn, bDrawHeader, ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_DRAWHEADER);
ArraySetIntByAn(hAn, hFontRow,    ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_FONTROW);
ArraySetIntByAn(hAn, hFontHeader, ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_FONTHDR);

// Set up column headers

FOR nColumn = 1 TO nColumns DO
   ArraySetStringByAn(hAn, "Column" + nColumn:#,  nColumn, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_COLUMN_VALUE);
   ArraySetIntByAn(hAn, 70,                       nColumn, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_COLUMN_WIDTH);
   ArraySetIntByAn(hAn, ARRAY_COLUMN_TYPE_STRING, nColumn, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_COLUMN_TYPE);
   nWidthTotal = nWidthTotal + 70;
END

ArraySetIntByAn(hAn, nWidthTotal, ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_XTOTAL);
ArraySetIntByAn(hAn, 0,  ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_YTOTAL);

INT hDataArray = ArrayCreate("Test_Data", nDataColumns, nDataRows, 1); 
// Data Array; 10 fields x 40 rows
MapValueSet(sMapName, "DataArray",   hDataArray);
MapValueSet(sMapName, "DataColumns", nDataColumns);
MapValueSet(sMapName, "DataRows",    nDataRows);
MapValueSet(sMapName, "Offset",      -1);

TaskNew("Test_Task_GetData", hAn:#, 1 + 8);
END


FUNCTION Test_GenericListDestroy(INT hAn)
   INT hDataArray = -1;
   STRING sMapName = "";

   IF (ArrayExistsByAn(hAn)) THEN
      sMapName = ArrayGetMapNameByAn(hAn);
      hDataArray = MapValueGet(sMapName, "DataArray");
      ArrayDestroy(hDataArray);
      GenericListDestroy(hAn);
   END
END


FUNCTION Test_Task_GetData(STRING sArg);
   INT hAn = StrToInt(sArg);
   INT nDataColumn = 0;
   INT nDataRow = 0;
   INT nDataColumns = 0;
   INT nDataRows = 0;
   INT hDataArray = -1;
   STRING sMapName = "";
   STRING nRandom = 0;
   STRING sValue = "";

   WHILE (TRUE) DO
      IF (ArrayExistsByAn(hAn)) THEN
         sMapName = ArrayGetMapNameByAn(hAn);
         hDataArray = MapValueGet(sMapName, "DataArray");
         nDataColumns = MapValueGet(sMapName, "DataColumns");
         nDataRows = MapValueGet(sMapName, "DataRows");

         ArraySetIntByAn(hAn, nDataRows, ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_YTOTAL);

         FOR nDataRow = 1 TO nDataRows DO
             FOR nDataColumn = 1 TO nDataColumns DO
                 nRandom = Rand(99);
                 sValue = "C" + nDataColumn:# + "R" + nDataRow:# + ">" + nRandom:#;
                 ArraySetString(hDataArray, sValue, nDataColumn - 1, nDataRow -1, 0);
             END
         END
      END

      SleepMS(30000);
   END

END
ClosedTest_GenericListFill 

FUNCTION Test_GenericListFill(INT hAn)
   INT nRow = 0;
   INT nRows = 10;
   INT nColumn = 0;
   INT nColumns = 5;
   INT nOffset = 0;
   INT nOffset_Previous = 0;
   INT nDataColumns = 0;
   INT nDataRows = 0;
   INT hDataArray = -1;
   STRING sMapName = "";
   STRING sValue = "";

   IF (ArrayExistsByAn(hAn)) THEN
      _ArrayView_Header_Run(hAn);
      _ArrayView_VScroll_Run(hAn);
      _ArrayView_HScroll_Run(hAn);

      sMapName = ArrayGetMapNameByAn(hAn);
      hDataArray = MapValueGet(sMapName, "DataArray");
      nOffset_Previous = MapValueGet(sMapName, "Offset");
      nOffset = ArrayGetIntByAn(hAn, ARRAY_INFORMATION_COLUMN, ARRAY_INFORMATION_ROW, ARRAY_ZINDEX_ARRAY_YOFF);

      hDataArray = MapValueGet(sMapName, "DataArray");
      IF ((ArrayIsDirty(hDataArray)) OR (nOffset <> nOffset_Previous)) THEN
         nDataColumns = MapValueGet(sMapName, "DataColumns");
         nDataRows = MapValueGet(sMapName, "DataRows");

         FOR nRow = 1 TO nRows DO
            FOR nColumn = 1 TO nColumns DO
               sValue = ArrayGetString(hDataArray, nColumn - 1, (nOffset + nRow) - 1, 0);
               ArraySetStringByAn(hAn, sValue, nColumn, nRow, ARRAY_ZINDEX_CELL_VALUE);
            END
         END

         MapValueSet(sMapName, "Offset", nOffset);
         ArraySetIsDirty(hDataArray, FALSE);
      END
   END
END

FUNCTION Test_GenericListRightClick(INT hAn)
   Message("TestGenericListRightClick", "Add context menu code here", 0);
END
ClosedTest_GenericListRightClick 

FUNCTION Test_GenericListRightClick(INT hAn)
   Message("TestGenericListRightClick", "Add context menu code here", 0);
END

See Also

Situational Awareness Key Components
Configure Content

Published June 2018