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 code	What
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");
  }
}