list_edit

Invokes a list editor window.

Available in:

Apps (win) Apps (char) Reportwriter RPC Standalone PL
X        

Syntax

void list_edit(list-name[,trigger-name[,menu-item1[, ...]]])
list           list-name
trigger        trigger-name
string         menu-item1

Description

This function invokes the windows list editor and displays the specified list from memory. It can only use data that is in memory; to display more data you need to have created a trigger that fetches it.
list-name specifies the list to edit.

trigger-name (optional) specifies the user-written trigger to invoke for customized editing function control. list_edit invokes the trigger with four parameters:
  • parm[0] --- A list that specifies the list to edit.
  • parm[1] --- An int that indicates one of the following event codes, depending on the end-user action:

When Event code Callback returns value
End user edits the data field. list_edit_change The trigger must return char data. If no modifications are made, the trigger returns the contents of (parm.3)
End user selects an item from the edit submenu list_edit_delete
list_edit_insert
list_edit_append
list_edit_dup
-1 --- Let list_edit() handle action
0 --- Nothing done
1 --- Trigger called and actions executed. Requests that list_edit() refresh the screen.
End user presses [PgDown] or [End] and list_eos() is false list_edit_more 0 --- Nothing done
1 --- More data available
End user selects an item from User, as you have defined. list_edit_user
list_edit_user+1
...
Trigger must return char data for field update.
If it returns integer data then the following options can be used:
-1 --- let list_edit() do it
0 --- nothing done
1 --- Trigger called and actions executed. Requests that list_edit() refresh the screen.
  • parm[2] --- (optional) An int that specifies the current column.
  • parm[3] --- char (optional) data from edit field (the text that is being modified).
menu_item1, menu_item2, ... specifies the names of items you can specify in the default User in the menu bar. If you don't specify any items, then the menu item is a single callback event, list_edit_user.

If you define and list some menu_items, then the events are specified as list_edit_user, list_edit_user+1, etc. By returning data of different types (for example, int or char), you can control if a single field is to be updated or the whole grid, which in the Edit window is defined as 128 rows by 256 columns.

Edit menu items

If you don't specify a trigger, or if the trigger returns a -1 for any item on the Edit menu, list_edit uses its default behavior:
Event codeWhat
list_edit_change Updates field (subject to legal conversion)
list_edit_insert Adds blank row before current row
list_edit_append Adds blank row after current row
list_edit_dup Duplicates current row
list_edit_delete Deletes current row
list_edit_more Nothing
list_edit_user
list_edit_user+1
...
Nothing

Edit window behavior with lists

The Edit window can hold the ``maximum grid size,'' which is 128 rows by 256 columns. In this context a grid is a page's worth of data. Because the scrollbar handling is local to the grid, scrollbar actions only move the cursor within the same 128x256 range. Navigate events, which end users can access from the menu or from function (or command) keys, also operate on grids, either within an existing 128x256 range, or by fetching a new grid. For example, paging down actually displays 128 new rows.
Command Action
[Enter] Enters the edit field and invokes the callback trigger the list_edit_change option if the data has changed.
[Home]* Moves the first page of the list into the grid with row 0, column 0, as the active position.
[PgUp]* Moves a new page into the grid.
[PgDn]* This function requires a trigger to handle the action. If you haven't specified a trigger, [PgDn] does nothing. Moves a new page into the grid. If not enough new rows exist in memory and the list_eos() is false then, it needs a callback trigger (that you have provided) with the list_edit_more option, to fetch more data into memory.
[End]* The last page of the list is moved into the grid. If list_eos() is false then a trigger (that you have supplied) is invoked with the list_edit_more option. The last column of the last row becomes the active item.
[Tab] Completes any edits and moves the cursor to the next column in the current row, making it active. It remains in a row and when it reaches the last column, wraps to the first column in the same row.
[Shift,Tab] Completes any edits and moves the cursor to the previous column in the current row, making it active. It remains in a row and when it reaches the first column, wraps to the last column in the same row.
[Down] Moves the cursor to the next row, making it active. When the end user reaches the last row of the page, it stops.
[Up] Moves the cursor to the previous row, making it active. When the end user reaches the first row in the page, it stops.
* These commands are available from menu drop downs, as well as specified keys.

Example

This simple example prompts for a table name and then lets the user edit the list. Entering a empty table name terminate the application. {\small{
/*
** A simple table list editor
*/
{
list LL;
char ss[256];
trigger tt = { if (parm.1 == list_edit_change) return(parm.3);
               if (parm.1 == list_edit_delete) {
                 list_mod(parm.0,0);
                 return(1);
                 }
               if (parm.1 == list_edit_more) {
                 list_more(parm.0,1000,false);
                 return(1);
                 }
               if (parm.1 == list_edit_user+0) return(upper(parm.3));
               if (parm.1 == list_edit_user+1) return(lower(parm.3));
               if (parm.1 == list_edit_user+2) {
                 int i;
                 i = to_int(prompt("How many rows so you want to delete?"));
                 while (i > 0) { list_mod(parm.0,0); i--; }
                 return(1);
                 }
               return(-1);
             };

while (true) {
  ss = prompt("Enter table name");
  if (ss == NULL) break;
  if (trap( { LL = list_open("select * from " ^^ ss,1000); } ))
    prompt(error_msg());
  else list_edit(LL,tt,"Uppercase","Lowercase","DeleteManyRows");
  }
}