DialogAddScrollRegion Function (Macro)

dialogs.h

HANDLE DialogAddScrollRegion (HANDLE Handle, short flags, short x, short y, unsigned short x1, unsigned short y1, unsigned short FirstItem, unsigned short LastItem, unsigned short NumDspItems, unsigned short TotNumItems, unsigned short ItemHeight);

Adds a rectangular item-scrolling region to a dialog box.

DialogAddScrollRegion adds a rectangular item-scrolling region to the dialog structure associated with the handle Handle from the (x, y) position to the (x1, y1) position, where all coordinates are relative to the top-left corner of the dialog box.

A scroll region defines a group of items that will scroll as the user moves through the items. The identification number of the first scrollable should be set in FirstItem and the last scrollable item in LastItem. NumDspItems defines the number of items that are displayed at one time. The total number of scrollable item should be set in TotNumItems and the height of each item in ItemHeight. Every scrollable item must be defined contiguously and have the DF_SCROLLABLE flag set and must not be of MENU, HEADER or XFLAGS type. The coordinates of the scrollable items are relative to the dialog box except that they may extend beyond the bottom coordinate of the dialog box. They are defined assuming a virtual scroll region.

It's very easy to cause display bugs using this function (of course, that won't crash your calculator, but the dialog can easily become ugly), so here is a method you can use to avoid those bugs: First, the standard item height is the height of the biggest item (often the EDIT item which is 10 pixel high), so the minimum value in ItemHeight should be 10 in most cases. Then, to avoid any display bugs, the y axis should be the y value of your first displayed item - 2 and y1 axis should be the y value of your last displayed item + 8. I.e. if you wish to scroll 8 items and only display items 3 by 3 (but please use the available screen space: don't just restrict the items displayed at a time to 3 just because everyone else does it), and the first scrollable item is item number 4 (the last displayed item at the beginning is therefore item 6), the calculation should be: y=(item 4 y axis)-2 and y1=(item 6 y axis)+8). The difference x1-x should also be greater than the width of the largest item (else it will result in display bugs). I don't really understand the utility of such a TotNumItems parameter as it should always be equal to LastItem-FirstItem+1. The flag DF_CLR_ON_REDRAW is very useful and should be set in most cases (see below).

Note: If you use a SCROLL_REGION, it must be the first item defined in the dialog box. A dialog box can therefore have at most one scroll region.

The order of item creation is very important, as it automatically gives each item an identification number (the first created item will get an identification number of 0, the second one will get 1, and so on). Every function that creates an item (i.e. every function beginning with 'DialogAdd...') will increase this identification number.

The parameter flags can be a combination of the following, defined in the DialogFlags enumeration:
DF_SKIP This item is skipped when browsing through items with the arrow keys.
DF_SCREEN_SAVE The dialog code saves the area underneath the dialog box when it is started, DB_MEMFULL returned if it cannot. If you wish to use this flag, you must then set it with the first item you created in the dialog box.
DF_CLR_ON_REDRAW Clears the entire visible scroll region when redrawn. If you do not set this flag, the scroll region will not be cleared before being redrawn, and you might still see the previously drawn items underneath the new ones.


DialogAddScrollRegion returns H_NULL in case of an error, may return DB_MEMFULL if you used DF_SCREEN_SAVE, else returns Handle. This routine (as well as all other 'DialogAdd...' routines) may cause heap compression.

DialogAddScrollRegion is in fact a macro created for your convenience. It calls DialogAdd with D_SCROLL_REGION as the ItemType parameter.


Uses: DialogAdd