[Main]
Name=DialogAddScrollRegion
Type=Function
Subtype=Macro
Header Files=dialogs.h
Definition=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);
Real Definition=#define DialogAddScrollRegion(h,f,x,y,w,g,z,t,p,u,m) DialogAdd(h,f,x,y,D_SCROLL_REGION,(short)(w),(short)(g),(short)(z),(short)(t),(short)(p),(short)(u),(short)(m))

[Description]
Adds a rectangular item-scrolling region to a dialog box.

[Explanation]
DialogAddScrollRegion adds a rectangular item-scrolling region to the dialog
structure associated with the handle <I>Handle</I> from the
(<I>x</I>, <I>y</I>) position to the (<I>x1</I>, <I>y1</I>) position, where
all coordinates are relative to the top-left corner of the dialog box.
<BR><BR>
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 <I>FirstItem</I> and the last scrollable item in <I>LastItem</I>.
<I>NumDspItems</I> defines the number of items that are displayed at one time.
The total number of scrollable item should be set in <I>TotNumItems</I> and
the height of each item in <I>ItemHeight</I>. 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.
<BR><BR>
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 <I>ItemHeight</I> should be 10 in most cases. Then, to
avoid any display bugs, the <I>y</I> axis should be the y value of your first
displayed item - 2 and <I>y1</I> 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:
<I>y</I>=(item 4 y axis)-2 and <I>y1</I>=(item 6 y axis)+8). The difference
<I>x1</I>-<I>x</I> 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 <I>TotNumItems</I> parameter as it should always be equal to
<I>LastItem</I>-<I>FirstItem</I>+1. The flag DF_CLR_ON_REDRAW is very useful
and should be set in most cases (see below).
<BR><BR>
<B>Note:</B> 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.
<BR><BR>
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.
<BR><BR>
The parameter <I>flags</I> can be a combination of the following, defined in
the <A HREF="$$LINK(dialogs.h/DialogFlags)">DialogFlags</A> enumeration:
<TABLE BORDER CELLPADDING="3">
<TR>
  <TD>DF_SKIP</TD>
  <TD>This item is skipped when browsing through items with the arrow keys.</TD>
</TR>
<TR>
  <TD>DF_SCREEN_SAVE</TD>
  <TD>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.</TD>
</TR>
<TR>
  <TD>DF_CLR_ON_REDRAW</TD>
  <TD>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.</TD>
</TR>
</TABLE>
<BR><BR>
DialogAddScrollRegion returns <A HREF="$$LINK(alloc.h/H_NULL)">H_NULL</A> in case
of an error, may return <A HREF="$$LINK(dialogs.h/DialogMessages)">DB_MEMFULL</A> if you
used <A HREF="$$LINK(dialogs.h/DialogFlags)">DF_SCREEN_SAVE</A>, else returns
<I>Handle</I>. This routine (as well as all other 'DialogAdd...' routines) may
cause heap compression.
<BR><BR>
DialogAddScrollRegion is in fact a macro created for your convenience. It calls
<A HREF="$$LINK(dialogs.h/DialogAdd)">DialogAdd</A> with D_SCROLL_REGION as the
<I>ItemType</I> parameter.

[References]
Out=dialogs.h/DialogAdd
