-Scroll bars usually appear only when Range is higher than Page, i.e. when the -entire content cannot be shown at the same time. See the scroll bar -properties in TScrollingWinControl for more details. +Scroll bars usually appear only when Range is larger than Page, i.e. when the +entire content cannot be shown in the visible area for a control. See the +scroll bar properties in TScrollingWinControl for more details.
-The length of the bar is the Width (or Height) of the Parent Control, the -Size is the other (free) coordinate. +Size is a read-only Integer property with the width or +height in pixels for the scroll bar indicated in the Kind property. For a +horizontal scroll bar (Kind is sbHorizontal), the return value is the height +of the scroll bar. Conversely, for a vertical scroll bar (Kind is sbVertical) +the value is the width of the scroll bar. +
++Size calls the GetScrollbarSize routine in the LCL interface to get the +return value when the Handle for the control has been allocated. Otherwise, +the GetSystemMetrics method in the widgetset class is called to get +the return value. +
++Use ControlSize, ClientSize, ClientSizeWithBar, and ClientSizeWithoutBar methods to get the control or client width for the control.
Increment is a TScrollBarInc property which indicates the amount the client area in the associated control is scrolled when the -Up or Down navigation arrows on the scroll bar are clicked. The -default value is 8. +Up or Down navigation arrows on the scroll bar are clicked. It is also used for movements of the mouse wheel on the control. The default +value is 8 pixels.
The value in Increment may be automatically recalculated in the
@@ -1044,14 +1064,26 @@ control, such as:
-The amount by which the scroll indicator moves if the cursor selects the
-scroll bar above, below or on either side of the scroll indicator. The
-default value is 80.
+Page is a TScrollBarInc property with the number of
+pixels needed for a page using the orientation in Kind for the scroll bar.
+This is the amount that the associated control is scrolled when the track bar
+or direction indicators are clicked on the scroll bar. The default value for
+the property is 80 pixels.
+
+When the associated control is a TScrollingWinControl descendant, the scroll
+information is retrieved using the Handle for the control. The property value
+may be changed when the associated control calls its UpdateScrollbars method.
+This can occur when the handle is created for the associated control, or when
+its AutoScroll property is changed.
+
+Changing the value for the property causes the ControlUpdateScrollBars method
+to be called to update the scroll bars in the associated control.
The Position reflects the top coordinate of the slider, which is Range-Page
@@ -1101,19 +1133,44 @@ when the slider is at the bottom of the bar.
+Range is an Integer property with the number of pixels
+needed for the logical display area on the control where the scroll bar is
+used. It measures the size of the scrolled content in the direction indicated
+by the Kind property. The default value for the property is 0, and indicates
+the dimensions for the scrollable content is smaller than the Page size for
+the scroll bar.
+
+The values in Range and other properties are updated when the associated
+control recalculates sizes and positions for its scroll bars.
+
+Use Position to determine the origin for the scrollable content displayed in
+the visible area on the associated control.
+
+Use Page to determine the number of pixels along the scroll bar orientation
+needed for the visible area on the associated control.
+
-When it takes a significant amount of time to repaint the parent control at a
-new position, Tracking should be False to prevent flicker. This causes
-the control to be updated only when the slider is released.
+If it takes a significant amount of time to repaint the associated control at
+a new position, Tracking should be set to False to prevent flicker.
+This causes the control to be updated when the slider is released.
-The scroll bar widget is visible only if (Visible=True) and
-(Range>Page).
+The scroll bar is visible only if (Visible = True) and
+(Range > Page).
-Set Visible to False to disallow the user to scroll the content, while
-the content still can be scrolled by code.
+Set Visible to False to hide the scroll bar. The content on the associated control can still be scrolled in program code.
-Use IsScrollBarVisible to get the current visible state of the widget.
+Use IsScrollBarVisible to get the current visible state for the scroll bar.
This class introduces a logical (virtual) client area, part of which is
@@ -1191,21 +1247,21 @@ progress.
Calls the inherited method to align the specified control and its children to
the parent control. Ensures that the page, range, and position in the scroll
bars are recalculated when AutoScroll is enabled and both
-HorzScrollBar and VertScrollBar are in use.
+HorzScrollBar and VertScrollBar are assigned.
Use the AutoSize property to enabled or disable automatic control
resizing. Set the UseDockManager property to False to
-disable use of the DockSite for the control.
+disable using the control as a DockSite for other controls.
+CalculateAutoRanges calculates the preferred size for the control
+- both with and without scroll bars. The Range properties in HorzScrollBar
+and VertScrollBar are updated to reflect the logical (virtual) size for the
+content on the control. The Range value is set to 0 if the scroll bar is not
+visible.
+
Used in the implementation of the ComputeScrollbars method.
-Ensures that the scroll bar page, range, and visibility are established when
+Ensures that the scroll bar page, range, and visibility are assigned when
the handles for the windowed control are created. Temporarily disables
auto-sizing in the method, and re-enables auto-sizing prior to exit. Calls
the inherited method to create the window and its handles.
@@ -1276,18 +1341,30 @@ the inherited method to create the window and its handles.
+GetLogicalClientRect is an overridden method in
+TScrollingWinControl; it re-implements the method introduced in
+the ancestor class. The return value contains the value in the ClientRect
+property. It ensures that the Right and Bottom members in the return value
+are updated (when needed) to reflect the current Range values for the
+respective visible scroll bars.
+
+DoOnResize is an overridden method in
+TScrollingWinControl. It calls the inherited method on entry to
+signal the OnResize event handler (when assigned). Other OnResize handlers
+for the application are also signalled.
+
+When AutoScroll is enabled, the UpdateScrollbars method is called to
+recalculate the page, range, and visibility for the scroll bars on the
+control. This action is not performed if either VertScrollBar or
+HorzScrollBar has not been assigned.
+
+ScreenToClient is an overridden method in
+TScrollingWinControl.
+
+ScreenToClient calls the inherited method to get the TPoint instance with the
+client coordinates used in the return value. The X and Y members in the
+return value are updated to reflect the current scroll offsets for the
+control. This gives the origin on the logical display area for the visible
+area on the control.
+
+ScreenToClient is used, along with ClientToScreen, in inherited methods which
+respond to changes in the mouse pointer position for a control. This includes
+context menu display and drag-and-dock operations.
+
+ClientToScreen is an overridden method in
+TScrollingWinControl.
+
+ClientToScreen calls the inherited method to get the TPoint instance with the
+screen coordinates for the client coordinates in APoint. The X and Y members
+in the return value are updated to reflect the current scroll offsets for the
+control. This gives the screen coordinates where the origin for the logical
+display area is located on the control.
+
+ClientToScreen is used, along with ScreenToClient, in inherited methods which
+respond to changes in the mouse pointer position for a control. This includes
+context menu display and drag-and-dock operations.
+
No actions are performed in the method if a handle has not been allocated for @@ -1577,7 +1733,7 @@ the control, or when either HorzScrollBar or VertScrollBar has not been assigned.
-Recursive calls to the method are also ignored. +Recursive calls to the method are ignored.
TScrollBox is a TScrollingWinControl descendant that -implements a windowed control with scroll bars. TScrollBox sets the -visibility for properties inherited from the ancestor class. TScrollBox -includes an overridden constructor which sets the default values for -properties in the class instance. +implements a windowed control with scroll bars. It uses the logical and +physical display areas introduced in the ancestor class, and allows a +scrollable area to be displayed on a form or panel. The logical (or virtual) +client area represents the dimensions needed for the child Controls added to +the class instance. When the logical display area is larger than the visible +area for the control, scroll bars allow the content to be moved into the +visible area for the control. +
++TScrollBox sets the visibility for properties inherited from the ancestor +class. TScrollBox includes an overridden constructor which sets the default +values for properties in the class instance. +
++Child Controls can be added to the class instance at design-time, or at +run-time by setting the scroll box as the Parent for a control. +
++The AutoScroll property indicates whether the scroll bars are automatically +displayed (or hidden) as needed when the control is resized, or when child +Controls are updated. This includes setting the page, range, and visibility +for the scroll bars. Use the HorzScrollBar and VertScrollBar properties to +access scroll bar page, range, and visibility when AutoScroll is not enabled. +
+
+An example application using TScrollBox is located in the
+