C64 OS PROGRAMMER'S GUIDE

Class Reference: TKTabs:TKView:TKObj

Overview

TKTabs is a container class. It inherits from TKView and takes from two up to a maximum of ten child views. It organizes the position and size of the child views to occupy its full visible area except for one row along the top that shows a set of tabs. All child views but one are marked invisible. Clicking the tabs in the top row changes which child view is visible.

Class Definition

//os/tk/h/:tktabs.h

Init (init_)

During initiation, TKTabs is initialized as a standard TKView. Its current tab is initialized to zero, and it is assigned a default delegate structure, which gives tabs the default title of "Tab X" where X is the tab's index+1.

Node Methods

Method	Description	Offset
addchild_	Add child node	40

Add child node (addchild_)

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

TKTabs reimplements the addchild_ method. TKTabs may only take 10 child views. If an eleventh child view is attempted to be added, addchild_ raises an exception.

When a child view is added to TKTabs its rsmask and offsets are automatically managed. Each child view is configured to resize its own children and to be anchored top, bottom, left and right, with offsets on all sides of 0, except for offtop which is set to 1 to leave room for the top tab bar.

All child views after the first are automatically marked as invisible by unsetting the df_visib flag on the dflags property.

A new tab is automatically displayed for every child view added to the TKTabs. All tabs are displayed with the same width (remaining space from an uneven division is distributed across the tabs from left to right). Tab titles are retrieved from the tab delegate structure.

Tabs Methods

Method	Description	Offset
gettab_	Get tab content view by index	61
setdel_	Assign a delegate structure	64
seltab_	Attempt a tab selection change	67

Get tab content view by index (gettab_)

Input	Description
X	Tab index
Output	Description
RegPtr	Tab's content view

This is a convenience method to fetch a pointer to the content view of a tab by index. Each child view that is added to the TKTabs is the content view for that tab. The tabs displayed left to right are in the order that the content views were added with addchild_

Pass the tab index in the X register. A RegPtr is returned to that tab's content view. There is no check that the index passed in X is in range. If X is greater than the highest index, the resultant value of RegPtr is undefined.

Assign a delegate structure (setdel_)

Input	Description
RegPtr	Pointer to a TKTabs delegate structure
Output	Description
-	None

This method changes the delegate property of the TKTabs. If the change is performed at runtime with the expected result that it will change the titles of the tabs, then it is also necessary to set the df_dirty flag of the dflags property.

Attempt a tab selection change (seltab_)

Input	Description
A	New tab index
Output	Description
C	Set on tab not changed
C	Clear on tab changed

Call seltab_ and pass the new tab index in the accumulator. If the index passed in the accumulator is out of range, an exception is raised. If the index is in range, this undergoes the same process as if the user had clicked the corresponding tab.

If the tab index passed in is already the current tab index, no change occurs. No delegate callback is called and the carry is returned set to indicate that no tab change occurred.

Otherwise, the delegate callback willblur is called while the curtab property is still the index of the currently selected tab. If that is denied, then no tab change occurs and the carry is returned set. If the blur is permitted then the delegate callback willfoc is called with the new tab index in the accumulator. If that is denied, then no tab change occurs and the carry is returned set. In order for a tab change to occur, both willblur and willfoc must permit it.

If the tab change is permitted then the following steps happen in order: the didblur delegate callback is called while the curtab property still holds the index of the tab being blurred. The content view associated with that tab has its df_visib flag unset on the dflags property. Then the curtab property is updated to the new tab index. Then the df_visib flag is set on dflags property of the content view associated with the new tab index. And finally, the didfoc delegate callback is called. The carry is returned clear to indicate that the tabs changed.

---

Object Definition

//os/tk/s/:tktabs.s

Object Size: 54 (+3) bytes

Tab Properties

Property	Description	Size	Offset
curtab	Current Tab	1	39
tabsz	Tab Sizes	10	40
tabcnt	Tab Count	1	50
hltab	Highlight Tab	1	51

Current Tab (curtab)

The curtab property is the index into the set of tabs of which one is currently in focus. Because a TKTabs object supports a maximum of 10 tabs, the theoretical valid range for this property is 0 to 9. In practice, the valid range for this property is 0 to tabcnt-1.

This property is read only. Do not attempt to change it manually. To change what tab is currently in focus, call the seltab method.

Tab Sizes (tabsz)

One reason why a TKTabs object only supports a maximum of 10 tabs is because the tabsz property is an array exactly 10 bytes long. Each byte holds a value for the computed width of the corresponding tab.

This property is read only. It is used internally to assist with drawing the tabs. Do not attempt to manually set the values in this array. The values are automatically recomputed and replaced whenever the TKTabs object is resized.

Tab Count (tabcnt)

This property is used to track how many child content views have been appended to the TKTabs object. It is used by the addchild_ method to quickly determine if there is room for the new child. It is used during hit testing and resizing.

This property is read only and should not be manually changed.

Highlight Tab (hltab)

This property is used internally during mouse interactions and redrawing to support drawing a highlighted tab on a mouse down event. This is a temporary property and there should be no reason to access it externally.

Control Properties

Property	Description	Size	Offset
delegate	Delegate Structure Pointer	2	52

Delegate Structure Pointer (delegate)

This property is used to point to the delegate structure. See TKTabs Delegate Structure in the Contants section below.

This property should not be set manually. To assign a delegate structure to a TKTabs object call its setdel_ method.

Constants

TKTabs constants are defined by //os/tk/s/:tktabs.s

TKTabs Delegate Structure

Constant	Offset	Description
tabstr	0	Callback to fetch tab title string
willblur	2	Callback to permit the current tab to lose focus
willfoc	4	Callback to permit a new tab to take focus
didblur	6	Callback to notify that a tab lost focus
didfoc	8	Callback to notify that a new tab took focus

When any delegate callback is called, this is set to the current object to which this delegate structure has been assigned. The same delegate structure may be assigned to more than one object, so the delegate callbacks may use this to determine which object is the one making the calls.

Fetch tab title string (tabstr)

Input	Description
A	Tab index
Output	Description
RegPtr	Pointer to string for the tab's title

When TKTabs is drawing the tab bar it calls the tabstr delegate callback once for each tab. The tab index is passed in the accumulator. The callback must return a RegPtr to a null-terminated string. That string is drawn on the current tab. If the tab is too narrow to show the whole string, the remaineder of the string clipped.

Permit the current tab to lose focus (willblur)

Input	Description
-	None
Output	Description
C	Set to deny the tab losing focus
C	Clear to permit the tab to lose focus

When this delegate callback is called no parameters are sent in the CPU's registers. The this pointer points to the current TKTabs object. To get the tab index currently in focus, read the curtab property from this.

Return with the carry set to prevent the current tab from losing focus. No further steps will be taken in the tab change process. If this delegate callback is not needed, use the global constant clc_rts in the delegate structure to always return with the carry clear and thus always permit the current tab to lose focus.

Permit a new tab to take focus (willfoc)

Input	Description
A	New tab index
Output	Description
C	Set to deny the tab taking focus
C	Clear to permit the tab to take focus

When this delegate callback is called the tab index that wants to take focus is passed in the accumulator. The this pointer points to the current TKTabs object.

Return with the carry set to prevent the new tab from take focus. No further steps will be taken in the tab change process. If this delegate callback is not needed, use the global constant clc_rts in the delegate structure to always return with the carry clear and thus always permit the new tab to take focus.

Notify that a tab lost focus (didblur)

Input	Description
-	None
Output	Description
-	None

This delegate callback is called to notify that a tab is losing focus. The tab index is not passed in the CPU's registers. To know which tab is losing focus read the curtab property from this.

There are no return parameters. This is a notification only, it cannot be used to prevent the change from happening.

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 02, 2024