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.

Scroll bar insets (inset)

This property is used inset the position of either the vertical or horizontal scroll bar by one or more rows or columns.

This property is initialized to zero. When inset is zero, the actual inset is determined automatically based on which scroll bars are turned on.

TKScroll view with different inset values

In example A, only the vertical scroll bar is enabled. The inset is set to zero, and as a consequence the scroll bar stretches all the way from the top to the bottom of its containing TKScroll.

In example B, only the horizontal scroll bar is enabled. The inset is set to zero, and as a consequence the scroll bar stretches all the way from the left to the right of its containing TKScroll.

In example C, even though the inset is set to zero, the fact that both scroll bars are enabled forces each to be inset by 1 automatically. If you will be turning one or both of the scroll bars on and off at runtime, leaving the inset as zero is usually recommended. Imagine a situation where the vertical scroll bar is always on, but the horizontal scroll bar will be toggled on and off. With the inset set to zero, as soon as the horizontal bar is turned on, both scroll bars will be inset by 1 automatically to accommodate the existence of the other. When the horizontal scroll bar is turned off, the vertical one will automatically stretch to fill the newly available space.

In example D, only the vertical scroll bar is enabled, but you can see that it still sits inset from the bottom by one row. This is accomplished by setting inset to 1.

In example E, inset has been set to 2. The vertical scroll bar is sized automatically to leave two blank rows at the bottom.

In example F, you can see that inset, if it is set, also affects the horizontal scroll bar's inset from the right edge. Here, only the horizontal scroll bar is turned on, but because inset is set to 1, it leaves one column empty.

The reason for the insets is to leave room for controls provided by a containing class. The primary example is when the TKScroll is embedded in a TKSplit which is marked as collapsed. Only the 1x1 character resize handle is drawn. If both scroll bars are enabled, such as in example C, that resize handle fits perfectly into the bottom right corner. If the vertical or the horizontal scroll bar is disabled, as in examples A or B, the scroll bar will cover over the resize handle and prevent clicks from reaching one or the other object.

By setting inset to 1, example A can be changed to example D, and resize handle becomes available again. Example e, where more than one space is left, allows for some other custom container class to have room to draw other controls below or beside a scroll bar.

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: Nov 20, 2024