New POP.UP functionality (TB#17) (Functions/Subroutines/Programs)

New POP.UP Functionality

 

With the release of Advanced Revelation 1.1, new functionality was added to one of the most useful system functions, POP.UP. This bulletin lists six new features of POP.UP and provides a sample program demonstrating how to:

 

_    show two popups at once

 

_    save a pre-popup display image

 

_    pre-tag selections

 

_    limit the number of rows per page

 

_    load the popup with a code and command to be executed by [Ctrl-F2].

 

_    force execution of the pre-loaded code and command

 

_    call row-sensitive help

 

Using these additional features of POP.UP, together with those documented in the System Subroutines book, will make an Advanced Revelation application both more powerful and easier to use.

 

The PTYPE Parameter

 

The last of the twelve calling parameters for POP.UP, commonly known as PTYPE, is used to tell POP.UP what to return to the calling program. The first field of PTYPE may be 'K', returning a list of keys selected; 'P', returning row numbers; (null), returning the row number plus data; or 'R', for a read-only popup.

 

In addition to these settings, one may now use PTYPE to instruct POP.UP to perform additional functions.

 

Example Program

 

An example program POPUP.FILES (Figure 1) is provided to illustrate the features discussed in this bulletin. POPUP.FILES uses the system file FILES to list attached files, and the system variable @VOLUMES to list attached volumes. When the user chooses the list files option from the FILES.OR.VOLUMES popup, the WHICH.VOLUMES popup appears beside it, allowing one to choose which account to list the files from and additionally, whether or not to show dictionary files.

 

 

Sticky Popups

 

By setting PTYPE<1,1,2> to TRUE$ before calling POP.UP, a programmer instructs the function to leave the popup displayed after it is exited. This is used by the first two popups in the example program both for clarity and to make the program more effective visually. Sticky popups enable the user to view the criteria they provided to reach listings presented in subsequent popups.

 

Saving the Pre-popup Image and Coordinates

 

If PTYPE<1,1,4> is set to TRUE$, POP.UP returns the image beneath the popup for later use by the system subroutine VIDEO.RW. This image may be used to erase the sticky popup at the appropriate time. The pre-popup image is returned via PTYPE and the coordinates of the image are returned in COL and ROW, the first and second parameters of POP.UP. ROW<1,1> and ROW<1,2> are set to X1 and Y1 respectively and COL<1,1> and COL<1,2> are set to X2 and Y2. When using sticky popups it is often necessary to use this feature for cleanup.

 

The previous two features work together in the example program in the following manner. The FILES.OR.VOLUMES popup is called as a sticky popup. If the list files option is chosen, the WHICH.ACCOUNT popup is displayed below and to the right of this first popup. The image and coordinates of this second popup are stored away so that upon exit from the final POP.FILES.UP popup, the WHICH.ACCOUNT popup may be taken down by using VIDEO.RW to overwrite it with its pre-popup image.

 

It is not necessary to store the image of FILES.OR.VOLUMES because it is overwritten with another call to POP.UP if the user chooses to execute the cycle again.

 

Limiting a Popup's Display Length

 

Setting PTYPE<1,1,3> to an integer before calling POP.UP will cause the popup to display only that number of rows per page. In the sample program this feature is used to limit the display length of the POP.FILES.UP popup. This feature is especially useful when you plan to place a popup below a sticky popup that may otherwise extend to the bottom of the screen.

 

Pre-tagging Items in a Popup

 

For a multiple selection popup, a program may pass a list of rows to be selected by default to the popup. This is done by setting PTYPE<1,1,6> equal to an @TM-delimited list of row numbers. For example, to preselect rows 1, 7, and 8, set PTYPE as follows before calling POP.UP:

 

            PTYPE<1,1,6>=1:@TM:7:@TM:8

 

In the WHICH.ACCOUNT popup this feature is used to tag the no dict option automatically. The selection bar is placed on the second row of the popup by setting COLUMN<2> equal to 2.

 

Assigning a Code and Command to [Ctrl-F2]

 

Setting PTYPE<1,1,8> to a comma delimited code and command causes that code and command to be executed when the user presses [Ctrl-F2] from within the popup. This gives a way of providing the user with concept help or any other function accessible by a code and command.

 

The following example illustrates how a help message can be assigned to the [Ctrl-F2] key:

 

            PTYPE<1,1,8>='HL,Help Message'

 

If calling a subroutine, a branch parameter can be passed by adding it to the command with a comma:

 

            PTYPE<1,1,8>='S,TEST.SUB,BRANCH'

 

Forcing Execution of the Code and Command

 

Setting PTYPE<1,1,9> to TRUE$ executes the code and command saved in PTYPE<1,1,8> automatically after the popup is displayed, but before the user enters anything. In the program, this feature is used in conjunction with the code and command assignment to automatically display a literal help message after the FILES.OR.VOLUMES popup is displayed.

 

Row-sensitive Help

 

A new feature has also been added to popup help functionality, accessible through the tenth calling parameter of POP.UP, HELP. This parameter may be loaded with a comma-delimited code and command executed when [F1] is pressed.

 

In addition, in Version 1.1, the literal <@POS> may be placed in this string. POP.UP swaps this special string on the fly with the first column of the currently highlighted row before executing the HELP code and command via CATALYST.

 

<@POS> can be used in the following manner:

 

            HELP = 'HF,<@POS>'

 

Loading the HELP parameter in this way causes the popup to call a help record with the row-dependent key <@POS> from either the SYS.HELP or HELP file. This feature may also be used to call a cataloged subroutine with a row-dependent parameter when [F1] is pressed. For example:

 

            HELP = 'S,MY.BP,<@POS>'

 

In the example program POPUP.FILES, <@POS> is used in a help literal. Pressing [F1] in the WHICH.ACCOUNT popup will display the help with (EXCLUDE DICT), GLOBAL or @ACCOUNT depending which row is highlighted at the time.

 

Figure 1

 

* program POPUP.FILES, demonstrating new features available in AREV 1.1 * popups.

 

DECLARE FUNCTION POP.UP

DECLARE SUBROUTINE MSG,VIDEO.RW

 

LISTING = ORIG.IMAGE =

RESP = 'Y'                                          ;* POP.FILES first tells FILES.OR.VOLUMES

POP.FILES = 'FIRST TIME THROUGH'                        ;* to display [Ctrl-F2] code and is used

 

 

EQU TRUE$ TO 1

EQU FALSE$ TO 0                                           ;* to flag display of the POP.FILES.UP popup.

 

 

VIDEO.RW(0,0,@CRTWIDE-1, @CRTHIGH-1,'R',ORIG.IMAGE)

PRINT @(-1)                            ; * these two lines store and clear screen for later restoring

 

LOOP

GOSUB FILES.OR.VOLUMES

GOSUB WHICH.ACCOUNT

GOSUB DO.SELECT

IF POP.FILES EQ TRUE$ AND ANS NE THEN GOSUB POP.SELECTED.FILES.UP MSG('ANOTHER TIME?','RC',RESP,)

UNTIL RESP = 'N'

 

* If POP.FILES is set it is necessary to take down the WHICH.ACCOUNT popup.

 

IF POP.FILES EQ TRUE$ THEN VIDEO.RW(X1,Y1,X2,Y2,'W',WHICH.ACCOUNT.IMAGE)

REPEAT

 

VIDEO.RW(0,0,@CRTWIDE-1, @CRTHIGH-1,'W',ORIG.IMAGE)

STOP

 

 

FILES.OR.VOLUMES:

COL = 0

ROW = 0

FILE = LIST =

FORMAT = 25

MODE = 'R'

MULTIPLE = 0

PTITLE = ATTR =

HELP = COLUMN =

PTYPE = LIST<1> = 'LIST FILES' LIST<2> = 'LIST VOLUMES' TITLE = 'FILES OR VOLUMES?' PTYPE<1,1,2> = TRUE$          ;* make this a sticky popup.   * code and command are set and forced to execute the first time through.   PTYPE<1,1,8> = 'HL,Any code and command here|executable with [CTRL-F2].' IF POP.FILES = 'FIRST TIME THROUGH' THEN PTYPE<1,1,9> = TRUE$ ANS=POP.UP(COL,ROW,FILE,LIST,FORMAT,MODE,MULT,TITLE,ATTR,HELP,COLUMN,PTYPE) RETURN     WHICH.ACCOUNT: COL = 5; ROW = 6 PTYPE<1,1,2> = TRUE$ ;* make the popup stick and… PTYPE<1,1,4> = TRUE$ ;* trigger return of the pre-popup image in PTYPE. PTYPE<1,1,9> = FALSE$ ;* disable the forced execution of cd and command. POP.FILES = FALSE$ ;* default is not to execute POP.FILES.UP.   IF ANS = THEN RETURN ;* traps for [ESC] from FILES.OR.VOLUMES popup.

IF ANS = 'LIST VOLUMES' THEN

TITLE = 'ATTACHED VOLUMES'

PTYPE = 'R'

LIST = @VOLUMES

END ELSE ;* clause executes when ANS = 'LIST FILES'

POP.FILES = TRUE$ ;* enable display of POP.FILES.UP popup

MULT = 1

TITLE = 'FILES IN WHICH ACCOUNT?'

PTYPE<1,1,6> = 1 ;* pretags the first row, EXCLUDE DICT, by default.

COLUMN<2> = 2 ;* moves selection bar to second row, working with pretag.

LIST<1> = '(EXCLUDE DICT)'

LIST<2> = 'GLOBAL'

LIST<3> = @ACCOUNT

HELP = 'HL,<@POS> help could have been called here' ;* row sensitive help

END

 

ANS=POP.UP(COL,ROW,FILE,LIST,FORMAT,MODE,MULT,TITLE,ATTR,HELP,COLUMN,PTYPE)

WHICH.ACCOUNT.IMAGE = PTYPE ; * image is stored away as are its…

X1 = COL<1>; Y1 = COL<2>; X2 = ROW<1>; Y2 = ROW<2> ;* coordinates.

RETURN

*—————————

 

DO.SELECT:

 

BEGIN CASE

CASE ANS = RETURN CASE ANS<1>= '(EXCLUDE DICT)' PERFORM 'SELECT FILES WITHOUT @ID ]DICT (S)'; ANS = DELETE(ANS,1,0,0);* Strips 'EXCLUDE DICT' from ANS. END CASE   BEGIN CASE ;* The appropriate filter builds on the exclude dict filter. CASE ANS<1> = 'GLOBAL' AND ANS<2> =

PERFORM 'SELECT FILES WITH ACCOUNT.VOLUME = GLOBAL (S)'

CASE ANS<1> = @ACCOUNT

PERFORM 'SELECT FILES WITH ACCOUNT.VOLUME = ':QUOTE(@ACCOUNT):'(S)'

END CASE

 

RETURN

 

POP.SELECTED.FILES.UP:

 

COL = 35;

ROW = 0

FILE = '@FILES'

LIST = MODE = 'T' FORMAT = '0:14:L::FILES\1:9:L::VOLUME\3:7:L::ACCOUNT' TITLE = 'FILES' PTYPE = 'K' PTYPE<1,1,3> = 12 ;* restricts rows in popup to 12 ANS =

 

POP.UP(COL,ROW,FILE,LIST,FORMAT,MODE,MULT,TITLE,ATTR,HELP,COLUMN,PTYPE)

RETURN