Directives 

Formats

Where:

Description

Use the DROP_BOX directive to create and manipulate drop box control objects on the screen. A drop box normally displays a single line on the screen with a down arrow on the right side. The user can select any element from a list of items you assign to the drop box, but variable input is not allowed. That is, the user can only select, not enter, values. To view the list, the user clicks on the down arrow. When the user selects a drop box item, the associated ctl_id is used to generate a CTL value.

See VARDROP_BOX Create/Control Variable Drop Box if you need a drop box that allows both variable input and selection from a list.

Because a drop box list is in drop down form, a drop box takes a smaller amount of space on the screen than a comparable list box. In addition, PxPlus automatically supplies vertical scrollbars if the number of elements overflows the dropdown box size. Combine these features to optimize the screen design when display space is at a premium. 

Drop Box Properties 

The Apostrophe Operator can be used with the unique logical identifier (ctl_id) to dynamically read and alter a wide variety of control attributes (properties) directly from the programming language.

See DROP_BOX Properties for the list of properties available for manipulating a drop box.

Multiple Character Search

Drop boxes provide a multiple character search capability that makes it easier to search for an exact match in a drop box list. To use this capability effectively, the characters must be entered within a ½ second of one another and must exactly match the start of an item in the drop box.

Example:

Assume that a drop box contains the following items:

C10000
C30000
C50000

Typing the character "c" followed within ½ second by the number "3" would select the "C30000" item.

Note:
In drop boxes, searching always starts from the current selection and wraps.

(Multiple character search in drop boxes was added in PxPlus 2019.)

Format 1

Create

DROP_BOX ctl_id,@(col,ln,wth,ht)[,ctrlopt]

Use this format to define or create a drop box and give it a unique identifier in ctl_id. You can use the FNT= option to establish the font for it. If you omit the font option, PxPlus uses the system default font. Use FNT="*" (asterisk) to set the font as standard text mode fixed font.

Example:

This example creates a drop box that generates a CTL=100 when any item is selected from it. It is loaded with the items Cat, Dog and Pig:

drop_box 100,@(2,14,12,6)
drop_box load 100,"Cat/Dog/Pig/"

Format 2

Delete

DROP_BOX REMOVE ctl_id[,ERR=stmtref]

Use the DROP_BOX REMOVE format to delete a drop box.

Format 3

Disable/Enable

DROP_BOX {DISABLE | ENABLE} ctl_id[,ERR=stmtref]

Use DROP_BOX DISABLE to gray out a drop box so that it will be visible but inaccessible to users. To reactivate it, use DROP_BOX ENABLE.

Format 4

Set Focus

DROP_BOX GOTO ctl_id[,ERR=stmtref]

Use the DROP_BOX GOTO format to set the focus on a drop box, ready for the user's next input.

Formats 5, 6 and 7

Load a Drop Box

Use DROP_BOX LOAD to add or delete the elements listed in a drop box. To add elements, you can load them from a delimited string, as an array of string elements, or individually. If you load more items into the list than the drop down box can display at one time (because of its physical size), PxPlus automatically supplies scrollbars.

DROP_BOX LOAD ctl_id,dlm_list$[,ERR=stmtref]

Load List. When you load a drop box from a delimited string, the last character in the string must be the delimiter. That delimiter must be identical to the separator between the elements in the string. For example, in the delimited string below, the delimiter is the slash "/". It ends the string and separates the elements:

drop_box load 12000,"Fox/Cat/Dog/Cow/Sheep/Horse/Pig/Elephant/Ant/"

To clear all elements from a drop box, use a null string:

drop_box load 86, ""

DROP_BOX LOAD ctl_id,array_name${ALL}[,ERR=stmtref]

Load Array. Use this format to load a complete array into the drop box. The curly braces enclosing {ALL} are part of the syntax:

drop_box load 16000,A${ALL}

DROP_BOX LOAD ctl_id,index,{element$ | *}[,ERR=stmtref]

Load Element. When you load individual drop box elements, use an integer value to state the index of the element before which to insert the element being loaded. For example, if index is 1, the new element will be inserted before 1 at the start of the list. If index is 0, the new element will be appended to the end of the list.

To delete or remove a specified element from a drop box, use an * (asterisk) in place of the element string:

drop_box load 86,4,* ! Deletes list element 4 from a drop_box whose ctl_id is 86

Note:
When a DROP_BOX LOAD is issued with no index, the current contents of the drop box will first be cleared and the new data will replace it. Setting the 'LoadPoint property to a non-zero value alters this behavior.

If 'LoadPoint is set to -1, the data included with the DROP_BOX LOAD will be appended to the list.

If 'LoadPoint is set to -2, the data included with the DROP BOX LOAD will replace the current contents of the list starting at the item number set in the 'Item property, which will be updated to the next item number once the load is complete (new items will be added, if required).

If 'LoadPoint is set to a value > 0, the data will be inserted into the list at the point specified and the value in 'LoadPoint will be reset.

This functionality allows list boxes to load a block of records at a time.

(The LoadPoint property was added in PxPlus v8.11.)
(The LoadPoint setting of -2 was added in PxPlus 2019.)

Format 8

Retrieve Element

DROP_BOX FIND ctl_id,index,var$[,ERR=stmtref]

Use the string variable in DROP_BOX FIND to retrieve a specific element from a drop box.

Retrieve Complete Contents

DROP_BOX FIND ctl_id,0,var$[,ERR=stmtref]

If the index value of 0 is used, PxPlus will return the complete contents of the drop box.

Formats 9 and 10

Read Current Selection

Use the DROP_BOX READ formats to read which element the user has selected from the drop box. You must read the user's selection before your application can use it. Use the (optional) mode$ variable to have PxPlus return the user's method of selecting an item from the drop box.

Some possible return values are:

$01$ for MOUSE-CLICK
$0D$ for Enter
$00$ when the user Tabs away from the drop box
$00$ when the user exits the button control

After this value is read, the value in mode$ is reset to $00$ (null).

DROP_BOX READ ctl_id,var$[,mode$][,ERR=stmtref]

Read Current Element. With this format, PxPlus returns the string contents of the user's currently selected element in var$ and (optionally) the user's method of selection in mode$.

DROP_BOX READ ctl_id,var[,mode$][,ERR=stmtref]

Read Current Index. Use DROP_BOX READ to read the index of the user's current selection and (optionally) the mode$ of selection.

Formats 11 and 12

Write Current Selection

Use the DROP_BOX WRITE formats to update a DROP_BOX to show the current selection.

DROP_BOX WRITE ctl_id,element$[,ERR=stmtref]

Update Current Setting. IfI you use this format to write an element to a drop box as the current selection, the contents of the string must exactly match the value of one of the elements in the drop box; otherwise, PxPlus returns an Error #11: Record not found or Duplicate key on write.

DROP_BOX WRITE ctl_id,index[,ERR=stmtref]

Update Current Index. You can use the element's index number to write it to the drop box as the current selection.

Format 13

Clear Current Selection

DROP_BOX WRITE ctl_id,"" [,ERR=stmtref]

Use this format to clear the currently selected entry in a drop box.

Note:
This behavior can be altered by use of the '+N' & '-N' mnemonics.

Format 14

Set Focus Notification

DROP_BOX SET_FOCUS ctl_id,alt_ctl[,ERR=stmtref]

Use the DROP_BOX SET_FOCUS format to define an alternate CTL value to generate whenever focus shifts to a drop box.

Format 15

Report All Changes

DROP_BOX AUTO ctl_id[,ERR=stmtref]

Use the DROP_BOX AUTO format to have PxPlus generate a CTL value to report all changes whenever the user highlights an element from a drop box list.

Format 16

Hide/Show

DROP_BOX {HIDE | SHOW} ctl_id[,ERR=stmtref]

With the DROP_BOX HIDE format, the drop box remains active but is not displayed. It is still accessible programmatically. Use the DROP_BOX SHOW format to restore the display and user access.

See Also

DROP_BOX Properties
VARDROP_BOX Create/Control Variable Drop Box

Example

0010 ! DROP_BOX Creation and Use
0020 print 'CS'; list
0030 drop_box 88,@(30,18,15,10)
0040 drop_box load 88,"CAT,DOG,PIG,FOX,"
0050 drop_box write 88,"CAT"
0060 let D_BX=88
0070 setctl D_BX:READ_BOX
0080 drop_box goto D_BX
0090 print @(30,24),"Try Mouse and/or keyboard to select. END=<F4>"
0100 obtain (0,siz=1,err=0100)@(0,0),'cursor'("off"),'ME',IN_VAR$,'MN'
0110 let CT=ctl; if CT=4 then goto END
0120 READ_BOX:
0130 drop_box read D_BX,ANIMAL$,STROKE$,err=0001
0140 drop_box read D_BX,IND_NUM
0150 print @(30,20),"HTA(SELECTION) : ",HTA(STROKE$)," AND CTL=",ctl:"#####"
0160 print @(30,21),"Index for ",ANIMAL$,@(44,21)," : ",IND_NUM,""
0170 goto 0100
0180 END:
0190 drop_box remove D_BX
0200 print 'CS'