GridList

(System Library)

Description:	Draws a list in the style of a spreadsheet.
Returns:	Nothing
Usage:	Steady State only.
Function Groups:	Graphics
Related to:	GUITransform | Bevel | CheckBox | ColorSelect | DropList | DropTree | Edit | GridList | HScrollbar | Listbox | RadioButtons | SpinBox | SplitList | TextBox |ToolBarTreeControl | VScrollbar
Format:	System.GridList(Titles, Data, DataFormat, ColWidthsParm [, NumDataRowsParm, NumDataColsParm, GridListBGndParm, GridColorParm, GridLineWidthParm, GridStyleParm, RowHeightParm, TitleHeightParm, HCellPaddingParm, VCellPaddingParm, HScrollPosParm, VScrollPosParm, DisableVScroll, DisableHScroll, DisableColumnSizing, DisableSorting, DisableSelectedCell, DisableVGridLines, DisableHGridLines, LockFirstColumn , Sort, SelectedRow, SelectedColumn, GridFontParm, GetSortKeyScope, EnableBorderParm, CellTextColorParm, TitleTextColorParm, TitleBackColorParm, TitleGridColorParm, LockFirstColColorParm, CaseSortParm, DisableControlsParm, IsFocusableParm])
Parameters:

  Data[I]      = Self()      { Module in which the CallBack exists };
  DataForms[I] = "DrawCell"  { The CallBack module used to display a cell in this column };

GetSortKey
(
  Row         { Row index to get the sort key for         };
  Column      { Column index to get the sort key for      };
  Inverted    { Bool: TRUE if the order is being reversed };
)
Main [
  If 1;
  [
     Return(ToUpper(Data[Row][Column]));  
  ]
]

Examples:

(See also, an example in GUITransform)

Example 1) An extremely simple grid of data:

[
  Titles;
  Data;
]
Init [
  If 1 Main;
  [
    Titles = New(3);
    Data   = New(1,3);
    Titles[0] = "Title 1";
    Titles[1] = "Title 2";
    Titles[2] = "Title 3";
    
    Data[0][0] = "Three Men in a Boat";
    Data[0][1] = "Heart of a Goof";
    Data[0][2] = "Mostly Harmless";
  ]
]
Main [
  GUITransform(0, 1, 1, 0,
               1 - 100, 500, 500, 1 - (100), 1,
               0, 0, 1, 0,
               0, 0, 0,
               \System\GridList(Titles { Column Titles Array },
                                Data   { Data Array          },
                                "%s"   { Format for Text     }));
...

Where: Titles is a one dimensional array of titles, equal to the number of columns. Data is a two dimensional array of values to display. The format is simply "%s" to display as strings.

Example 2) A sparse array

   {initialize the data array}
   Titles[0] = "Name";
   Titles[1] = "Area";
   Titles[2] = "Description";
   Titles[3] = "I/O Device";
   Titles[4] = "Address";
   Data[0][0] = "Tag1";
   Data[1][0] = "Tag2";
   Data[2][0] = "Tag3";
   Data[0][1] = "Area1";
   Data[1][1] = "Area1";
   Data[2][2] = "I'm a tag";
   Data[1][3] = "PollDrvr1";
   Data[0][4] = "40001";
   DataForm   = "%s";

  GUITransform(50, 500, 350, 50   { Reference rectangle         },
               1                { Scale Left                  },
               1                { Scale Bottom                },
               1                { Scale Right                 },
               1                { Scale Top                   },
               1                { No overall scaling          },
               0, 0, 1, 0       { No movement; visible; res   },
               0, 0, 0          { Not selectable              },
               System.GridList(Titles  { Titles array         },
                                Data    { Data array           },
                                DataForm { Cell format         },
                                60     { Column widths array   },
                                3      { # Data rows           },
                                5      { # Data cols           },
                                15, 8  { Grid BGnd, Grid color },
                                1, 1 { Grid line width, line style},
                                30, 30 { Row/Title height      },
                                0, 0 { Horiz/Vert cell padding },
                                0, 0 { Horiz/Vert Scroll position },
                                1, 1 { Disable V/H scroll bars },
                                1    { Disable column sizing   },
                                1    { Disable Sorting         },
                                1    { Disable selected cell   },
                                0, 0 { Enable V/H grid lines  },
                                1    { LockFirstColumn         },
                                Invalid  { Sort                },
                                0        { SelectedRow         },
                                0        { SelectedColumn      },
                                \_DialogFont { GridFontParm    }));

This code example will create a Grid List that looks like the following:

Example 3) Building a grid with data from an application:

The following is coded in a dedicated page.

[
  Title = "Privileges List";
  Color = "<FFFFFFFF>";
  AllAccounts   { All accounts and roles        };
  NumAccounts   { Count of user accounts        };
  AccountKey    { Key for each dictionary entry };
  LastKey       { Used when looping             };
  Item          { One item from the dictionary  };
  LastItem      { Used when looping             };
  Titles        { Array of column titles        };
  Data          { Data for the grid             };
  I = 0         { Counter                       };

]

Init [
  If 1 Main;
  [
    { GetAccountInfo will return Invalid unless the current account has
       the Manager privilege. We can use that as a test for whether to
       display anything. }
    AllAccounts = \SecurityManager.GetAccountInfo();
    IfThen(Valid(AllAccounts);
      { Parse the dictionary, removing roles }
      Item = GetNextKey(AllAccounts, Invalid, 1, AccountKey);
      WhileLoop(Valid(AccountKey),
        LastKey = AccountKey;
        LastItem = Item;
        Item = GetNextKey(AllAccounts, LastKey, 1, AccountKey);
        IfThen(LastItem.IsRole == 1,
          DictionaryRemove(AllAccounts, LastKey);
        );
      );
      { Get the number of user accounts and make a data array to hold them }
      NumAccounts = GetKeyCount(AllAccounts);
      Data = New(NumAccounts,4);
      { Check each account for privileges: Manager, Administrator, and Remote Data }
      Item = GetNextKey(AllAccounts, Invalid, 1, AccountKey);
      WhileLoop(I <= NumAccounts,
        LastKey = AccountKey;
        LastItem = Item;
        Data[I][0] = Item.AccountName;
        Data[I][1] = \SecurityManager.SecurityCheck(-3, TRUE, Item.AccountName) ? "✓" : "✗";
        Data[I][2] = \SecurityManager.SecurityCheck(-4, TRUE, Item.AccountName) ? "✓" : "✗";
        Data[I][3] = \SecurityManager.SecurityCheck(-47, TRUE, Item.AccountName) ? "✓" : "✗";
        I++;
        Item = GetNextKey(AllAccounts, LastKey, 1, AccountKey);
      );
      { Create titles for the columns }
      Titles = New(4);
      Titles[0] = "Name";
      Titles[1] = "Manager";
      Titles[2] = "Administrator";
      Titles[3] = "Remote Data";
    );
  ]
]

Main [
  Return(Self);

  GUITransform(0, 1, 1, 0,
               1 - 100, 300, 500, 1 - (100), 1,
               0, 0, 1, 0,
               0, 0, 0,
               \System\GridList(Titles    { Column titles array   },
                                Data      { Data array            },
                                "%s"      { Format for all text   }));

]

Assuming that the application has security enabled, the result will be similar to the following. Nothing will appear unless a user who has the Manager privilege is currently signed in. (The check mark and X depend on the file being saved with UTF-8) encoding.

Example 4) A grid that uses a callback with sorting for the title

This example was taken from a script application, starting at the Graphics submodule. Adjust accordingly to use it in a page.

The example illustrates the use of a callback for the title, including the ability to sort the data when any cell in the title row is clicked. If a callback is used for the titles, then one must also be used for the data cells. The callback is deliberately simple for brevity. Note that boundary lines and up/down arrows are missing. If defining a callback to draw the title cells, you must provide for all aspects of the cell's appearance.

<
{============================= System\Graphics ===============================}
{ This module handles all of the graphics for the application                 }
{=============================================================================}
Graphics
[
  Data;
  Formats;

  DrawTitle   MODULE          { Callback module to draw titles                };
  DrawCell    MODULE          { Callback module to draw data cells            };
  GetSortKey  MODULE          { Callback module to get sort key               };
]
Init [
  If 1 Main;
  [
    Data    = New(3, 3); 
    Formats = New(3);

    Data[0][0] = 1;          { Simple data values for the example }
    Data[1][0] = 2;
    Data[2][0] = 3;
    Data[0][1] = 16;
    Data[1][1] = 15;
    Data[2][1] = 14;
    Data[0][2] = "b";
    Data[1][2] = "a";
    Data[2][2] = "c";

    Formats[0] = "DrawCell"; { Using the DrawCell call-back }
    Formats[1] = "DrawCell";
    Formats[2] = "DrawCell";
  ]
]

Main [
  GUITransform(0, 1, 1, 0,
               1 - 100, 500, 500, 1 - (100), 1,
               0, 0, 1, 0,
               0, 0, 0,
               \System\GridList("DrawTitle" { Column Titles Array   },
                                Self        { Data Array            },
                                Formats     { Format for Text       },
                                60          { Column widths array   },
                                3           { # Data rows           },
                                3           { # Data cols           }));
]

<
{==================================== DrawTitle ==============================}
{ Callback to draw a custom title row for the Gridlist.                       }
{=============================================================================}
DrawTitle
(
  CallBackScope               { The callback module of GridList               };
  TitleIndex                  { The index of the title to be seen             };
)

[
  Titles                      { Titles will be shown. This could be defined
                                in the parent module, and could be any format
                                besides an array                              };
]

Init [
  If 1 Main;
  [
    Titles = New(3)         { Using a simple array of values for the example };
    Titles[0] = "Title 1";
    Titles[1] = "Title 2";
    Titles[2] = "Title 3";
  ]
]

Main [
   { GUIText or any customized call back module to show the title }
  If GUIText(0, 18, 60, 0         { Unit bounding box           },
             1, 1, 1, 1, 1        { Scaling                     },
             0, 0                 { No movement                 },
             1, 0                 { Visible, Reserved           },
             68                   { Button                      },
             0, 0                 { FocusID, Trigger            },
             -1, 0, 0             { Colors                      },
             4, 4                 { Alignment                   },
             "%s"                 { Format                      },
             Titles[TitleIndex]   { Text to display             });
  [
     { Gridlist will adjust the sorting for us accordingly }
    CallBackScope.TitleClicked();
  ]
]
{ End of DrawTitle }
>

<
{==================================== DrawCell ===============================}
{ Callback to draw a custom cell row for the Gridlist.                        }
{=============================================================================}
DrawCell
(
  Row;
  Col;
)

Main [
   { GUIText or any customized call back module to show the data cell }
  GUIText(0, 18, 60, 0         { Defined unit bounding box   },
          1, 1, 1, 1, 1        { Scaling                     },
          0, 0                 { No movement                 },
          1, 0                 { Visible, Reserved           },
          68                   { Button                      },
          0, 0                 { FocusID, Trigger            },
          -1, 0, 0             { Colors                      },
          4, 4                 { Alignment                   },
          "%s"                 { Format                      },
          Data[Row][Col]       { Text to display             });
]
{ End of DrawCell }
>

<
{=================================== GetSortKey ==============================}
{ Callback to get the sort key for the GridList.                              }
{=============================================================================}
GetSortKey
(
  Row         { Row index to get the sort key for         };
  Column      { Column index to get the sort key for      };
  Inverted    { Bool: TRUE if the order is being reversed };
)

Main [
  If 1;
  [
     Return(ToUpper(Data[Row][Column]));
  ]
]

{ End of GetSortKey }
>

{ End of System\Graphics }
>