C64 OS PROGRAMMER'S GUIDE

Class Reference: TKScroll:TKView:TKObj

Overview

TKScroll is a container class. It inherits from TKView and requires one content view. Its content view should be one which overflows the visible bounds of the TKScroll view either vertically or horizontally. Common examples include, TKText or TKList, but could also be a TKView that is used with an unconstrained layout of child views.

The TKScroll may activate either one or two scroll bars, instances of TKSBar to allow the user to scroll the content either vertically or horizontally.

When calculating the minimum memory requirements for a view hierarchy, you must take into consideration the size of the TKSBar objects that will be activated on all TKScroll objects.

Subclassing notes

Although it can be complicated to subclass TKScroll, this can occasionally be done to good effect. For example, TKTable is a subclass of TKScroll. Other opportunities may exist.

Class Definition

//os/tk/h/:tkscroll.h

Init (init_)

During initiation, TKScroll is initialized as a standard TKView. By default both of its scroll bars are disabled.

Content Methods

Method	Description	Offset
setctnt_	Set content view	61
setbar_	Set Scroll Bar Visibility	64

Set content view (setctnt_)

Input	Description
RegPtr	TKView node to add to this node
Output	Description
-	None

With TKScroll the addchild_ method should not be used. A TKScroll view may have 1, 2 or 3 child views, but these consist of a single content view whose scroll offsets are managed by the TKScroll object, plus the horizontal or vertical scroll bars may be activated using the setbar_ method.

A TKScroll view requires its content view, and if it already has a content view and setctnt_ is called again, an exception is raised.

When a content view is added to TKScroll its rsmask and offsets are automatically managed. The content view is configured to resize its own children and to be anchored top, bottom, left and right.

The bottom and right offsets of the content view are automatically adjusted when scroll bars are activated or deactivated with calls to the setbar_ method.

Although technically any TKView or subclass of TKView can be added as the content view, it only makes sense to add a content view whose contents will naturally overflow its bounds. For example, a TKList will typically have more rows of content than its own height. Depending on how the content is wrapped, a TKText may usefully take advantage of a vertical and horizontal scroll bar.

Set scroll bar visibility (setbar_)

Input	Description
X → 0	Hide horizontal scroll bar
X → 1	Show horizontal scroll bar
Y → 0	Hide vertical scroll bar
Y → 1	Show vertical scroll bar
Output	Description
-	None

The setbar_ method is used to configure the horizontal and vertical scroll bars. For inputs, the value of the X register controls the horizontal scroll bar and the value of the Y register controls the vertical scroll bar. A value of 0 turns the corresponding scroll bar off, and any value other than zero turns that scroll bar on.

The scroll bars are instances of the TKSBar class. When a scroll bar is enabled a new TKSBar object is created. When disabled the scroll bar object is deleted, not merely hidden. Therefore, in the Toolkit memory pool, space only needs to be accounted for the scroll bars that will be turned on.

The TKScroll should have its content view set using setctnt_ before calling setbar_. After calling setbar_ the offsets of the content view are adjusted automatically to make room for scroll bars or to fill the space where a scroll bar is not showing.

TKScroll view with different scroll bar configurations

Scroll Methods

Method	Description	Offset
adjust_	Adjust scroll offsets	67
setoff_	Set scroll offsets	67

Adjust scroll offsets (adjust_)

Input	Description
RegPtr	TKSBar Object
Output	Description
-	None

The adjust_ method is called as the targeted action of one of the scroll bars that belong to this TKScroll view.

When the scroll bars are turned on by calling setbar_ the new TKSBar objects, which are subclasses of TKCtrl have their target object set to this TKScroll, and the action method offset set to the offset of adjust_.

As the user manipulates a scroll bar using the mouse or keyboard, the scroll bar continually calls this method. The only input to this method is a pointer to the scroll bar object. This is the standard behavior of any TKCtrl action. The TKScroll reads properties from the TKSBar and uses that information to adjust the scroll offsets of the content view.

This method should not be called manually. To programmatically change the scroll offsets, call setoff_ instead.

If adjust_ is called while the TKScroll has no content view, an exception is raised.

Set scroll offsets (setoff_)

Input	Description
RegWrd	New scroll offset
C → SET	Set the vertical offset
C → CLR	Set the horizontal offset
Output	Description
-	None

To programmatically scroll the content, call the setoff_ method. The carry is used to specify the direction of scroll that is being affected. Carry set to affect the vertical scroll, or clear to affect the horizontal scroll. The new scroll offset is passed as a 16-bit RegWrd.

The scroll bars are automatically updated to reflect the new scroll offsets of the TKScroll's content view.

If setoff_ is called while the TKScroll has no content view, an exception is raised.

---

Object Definition

//os/tk/s/:tkscroll.s

Object Size: 46 (+3) bytes

Content Properties

Property	Description	Size	Offset
ctntview	Content view	2	39
hsbar	Horizontal scroll bar	2	41
vsbar	Vertical scroll bar	2	43
inset	Content view insets	1	45

Content view (ctntview)

When a content view is set by calling the setctnt_ method, the pointer to the content view object is assigned to this property. It is also added to the TKScroll as a child node, but this pointer is used internally to more efficiently reference the content view.

Horizontal scroll bar (hsbar)

When the horizontal scroll bar is enabled by calling the setbar_ method, this pointer is set to the new horizontal scroll bar object. It is also added to the TKScroll as a child node, but this pointer is used internally to more efficiently reference the horizontal scroll bar.

When the horizontal scroll bar is disabled, the high byte of this property only is set to zero. Checking the high byte for zero is sufficient to determine whether the horizontal scroll bar exists.

Vertical scroll bar (hsbar)

When the vertical scroll bar is enabled by calling the setbar_ method, this pointer is set to the new vertical scroll bar object. It is also added to the TKScroll as a child node, but this pointer is used internally to more efficiently reference the vertical scroll bar.

When the vertical scroll bar is disabled, the high byte of this property only is set to zero. Checking the high byte for zero is sufficient to determine whether the vertical scroll bar exists.

Content view insets (insets)

This property is used internally to assist with adjusting the right and bottom offsets of the content view to account for the presence or absence of the scroll bars. This property should be considered private.

Relationships

Inherits from: TKView

Parent Section: Class Reference

Next Section: Subclassing

---

Next Chapter: Writing an Application

Table of Contents

This document is subject to revision updates.

Last modified: Jul 12, 2024