Adding scripts to a scrolling window

Several different scripts can be used to control how a scrolling window displays and accesses information. These include window scripts, scrolling window scripts, and field scripts for fields in the scrolling window.

Table buffers for scrolling windows

When writing scripts for scrolling windows, keep in mind that for display purposes, the scrolling window uses a separate table buffer, instead of the table buffers for the form where the scrolling window is located. This means that actions such as scrolling through items in the scrolling window won’t affect the table buffers for the form where the scrolling window is located. For other types of table access, such as saving an item in the scrolling window to a table, the scrolling window uses the form’s table buffer. If you don’t want the scrolling window to use the form’s table buffer, consider using form procedures that have their own table buffers for all tables in the application.

Window scripts

Scripts attached to the window containing the scrolling window and scripts for fields in the same window are used to fill the scrolling window and control how it displays information.

Typically, the window pre script for the window containing the scrolling window contains the fill window statement that fills the scrolling window from the linked table using the table key specified. If no table key is specified, the key selected in the Scrolling Window Options window is used. The fill window statement can also fill a scrolling window from a different table.

The table keys for the table linked to the scrolling window control how the items in the scrolling window are sorted. A drop-down list or other list field can be used to specify which table key will be used to sort the records when displaying information.

Scrolling windows can also display information in normal or expanded mode by using the expand window statement. Typically, push buttons or visual switches on the window control whether the scrolling window displays in normal or expanded mode.

Example 1

The following example shows the window pre script for the window containing the Customer_List_Scroll scrolling window. The pre script sets the Sort By drop-down list to 1, indicating the first key will be used to sort the items in the scrolling window. The fill window statement fills the scrolling window from the linked table using the first key for the table.

'(L) Sort By' = 1;
fill window Customer_List_Scroll by number 1;

Example 2

The following example is the change script for the Sort By drop-down list, which controls how the records in the scrolling window are sorted. It uses the fill window statement to fill the scrolling window using the appropriate table key to sort the records.

if '(L) Sort By' = 1 then
	{Records will be sorted by Customer Number}
	fill window Customer_List_Scroll by number 1;
else
	{Records will be sorted by Name}
	fill window Customer_List_Scroll by number 2;
end if;

Example 3

The following window pre script and change scripts for the normal and expand buttons control whether the scrolling window displays information in normal mode or expanded mode. The normal and expand buttons are visual switches, each with two states indicating the two different modes.

Window pre script:

'Expand Button' = 2;  {The expand button is up.}
'Normal Button' = 1;  {The normal button is down.}
lock 'Normal Button'; {Prevent it from being clicked again.}

Button to display normal mode:

expand window Customer_List_Scroll, false;
lock 'Normal Button';  {Prevent it from being clicked again.}
unlock 'Expand Button';  {Unlock expand so it can be clicked.}
'Expand Button' = 2; 	{The expand button is up.}

Button to display expanded mode:

expand window Customer_List_Scroll, true;
lock 'Expand Button';  {Prevent it from being clicked again.}
unlock 'Normal Button';  {Unlock normal so it can be clicked.}
'Normal Button' = 2; 	{The normal button is up.}

Scrolling window scripts

The Properties window for the scrolling window allows you to attach several scripts to the scrolling window: a line pre script, line change script, line post script, line fill script, line insert script, and line delete script.

To access the scripts for the scrolling window, open the window containing the scrolling window. Double-click the scrolling window to open the scrolling window’s layout. Select the scrolling window, and then click the Script tab in the Properties window. Select the type of script you want to add or edit, and click the lookup button.

Line pre script

The line pre script runs each time the focus moves to a different line in the scrolling window. The pre script is useful for updating other fields in the window based upon the position of the focus in the scrolling window. The following is the line pre script for the Customer_List_Scroll scrolling window. It uses the Customer Number of the current line in the scrolling window to read from the Customer_Comments table and display the appropriate comments.

'Customer Number' of table Customer_Comments = 'Customer Number' of window Customer_List_Scroll;
get table Customer_Comments;
if err() = OKAY then
	copy from table Customer_Comments;
else
	clear Comments of window Customer_List of form Customer_List;
end if;

Line change script

The line change script runs each time any fields in the current line have changed and the focus leaves the line. The line change script is useful for editable scrolling windows, saving any changes to the line when the focus leaves the line. The following script is the line change script for the Customer_List_Scroll scrolling window. It saves any changes made to fields in the current line to the Customer_List table.

if empty('Customer Number' of window Customer_List_Scroll) then
	{Customer doesn't have a number.}
	warning "A customer must have a customer number.";
	focus 'Customer Number' of window Customer_List_Scroll;
else
	{Save the current line to the table.}
	copy to table Customer_List;
	save table Customer_List;
end if;

Line post script

The line post script runs each time the focus leaves a line in the scrolling window. The line post script is useful for preparing fields to be updated when the focus moves to a new line. The following script is the line post script for the Customer_List_Scroll scrolling window. It clears the Comments field that was filled by the line pre script, preparing it to display another comment.

clear field Comments of window Customer_List;

Line fill script

The line fill script runs each time a new line is displayed in the scrolling window. When the scrolling window first fills, the fill script runs repeatedly until the scrolling window is full. The fill script also runs when a new line is added to the scrolling window from the link file, such as by scrolling, or when the user clicks an existing line in the scrolling window. The fill script runs before the line pre script.

The reject record statement can be used in the line fill script to keep specified records from being displayed in the scrolling window. You should avoid rejecting a large number of records using the line fill script because this can reduce application performance considerably.

Fill scripts are also useful for reading information from tables other than the scrolling window’s link table. The following script uses the Part Number field from the Inventory_Data file to read a description from the Item_List file.

'Part Number' of table Item_List = 'Part Number' of table Inventory_Data;
{Read from the additional table.}
get table Item_List;
if err() = OKAY then
	{Copy the information to the scrolling window.}
	Description of window Inventory_Scroll = Description of table Item_List;
end if;

Line insert script

The line insert script runs when the Insert Row menu item is chosen or when the insert line statement is run. Insert Row is a menu item that can be inherited by application-level menus. Refer to Form-based Menus for more information. The insert line script is used to insert a line into the scrolling window, just above the currently-selected record.

The line insert script should be used only for scrolling windows that have the order of the items controlled by sequence numbers. For example, the line items for an invoice entry window typically use sequence numbers. Sequence numbers are currency values that are stored as part of the table and are also part of the table key. They act as reference values when the scrolling window displays information, ensuring that the records are displayed in the proper order.

The following example shows the line items for an invoice.

The line items are stored in a table that has the Invoice Number and Sequence Number as keys. Note that the sequence number for each line item increased by 512. This was done by the line change script in the scrolling window when the line items were saved. Having the sequence numbers in the table key ensures that the invoice items will always be displayed in the order they were entered.

The following script is the line insert script for the scrolling window displaying the invoice line items. It calculates a new sequence number based upon where the focus is currently located in the scrolling window and saves a new record in the table, allowing the user to add a line item. The scrolling window will be redrawn automatically.

local currency temp;

if not empty('Sequence Number' of table Invoice_Data) then
	{Store the sequence number of the current record.}
	temp = 'Sequence Number' of table Invoice_Data;
	{Read the sequence number of the previous record.}
	get prev table Invoice_Data;
	if err() <> EOF then
		temp = temp + 'Sequence Number' of table Invoice_Data;
	end if;
	temp = temp / 2;
	clear table Invoice_Data;
	{Save the new record in the table.}
	'Invoice Number' of table Invoice_Data = 'Invoice Number';
	'Sequence Number' of table Invoice_Data = temp;
	save table Invoice_Data;
end if;

If this focus were on the last item in the scrolling window, Steel Wool, and the user chose to insert a row, a new record would be created in the Invoice_Data table with the Invoice Number 4510 and the Sequence Number 768. This ensures that the new item will appear in the scrolling window before Steel Wool and after the Torx Screwdriver.

Line delete script

The line delete script runs when the Delete Row menu item is chosen or when the delete line statement is run. Delete Row is a menu item that can be inherited by application-level menus. Refer to Form-based Menus for more information. The line delete script is used to delete the current record from the linked table. It automatically removes the line from the scrolling window. The following script is the line delete script for the Customer_List_Scroll scrolling window. It deletes the currently-selected customer from the Customer_List table.

if ask("Are you sure you want to delete this item?", "Delete", "Cancel","") = ASKBUTTON1 then
	remove table Customer_List.
end if.

Context menu script

The context menu script runs when the user right-clicks on the active line in the scrolling window. It is used for context menus. For browse-only scrolling windows, the context menu applies to the entire active line. For editable and adds-allowed scrolling windows, the line-level context menu items are added after any items for the field-level context menus. Refer to Context Menus for details about using context menus.

Scrolling window field scripts

Pre, change and post scripts can be applied directly to fields in the scrolling window when the layout window for the scrolling window is open. Field scripts for scrolling windows are typically used in the same manner as field scripts for standard windows. For example, a field change script could be used to verify that the contents of the field are valid.

Documentation Feedback

---