C64 OS PROGRAMMER'S GUIDE

Class Reference: TKSplit:TKView:TKObj

Overview

TKSplit is a container class. It inherits from TKView and takes two child views. It organizes the position and size of the two child views to split its own visible area into two regions. These regions may be either side-by-side (a vertical split) or one above the other (a horizontal split.)

The splitter bar may be shown in full and the user can click and drag from anywhere on that bar. Or the splitter bar may be collapsed. A collapsed splitter bar is used when there is already a natural visual divider provided by the left or top child view. The collapsed split shows only a 1x1 character nub, and the split may only be dragged by that nub.

The ability to collapse the split bar works in concert with the ability to inset a scroll bar by one character, leaving room to display the splitter's nub.

Subclassing notes

TKSplit does not typically need to be subclassed. But it could be subclassed to add some new features. For example, to constrain the position of the split, to add keyboard commands for moving the position of the split, and so on.

Class Definition

//os/tk/h/:tksplit.h

Init (init_)

During initiation, TKSplit is initialized as a standard TKView. Its orientation defaults to a vertical split, the position of the splitter bar defaults to 10 (the left side is allotted 10 characters,) and its collapsed bits are unset so that the full split bar is shown by default.

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

TKSplit reimplements the addchild_ method. A TKSplit may only take 2 child views. If a third child view is attempted to be added, addchild_ raises an exception.

When a child view is added to TKSplit 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.

TKSplit manipulates the offset properties of its two children to position them tiled within its own area. Therefore, it is not possible to offset the immediate child of a TKSplit from the edge of a TKSplit, for example, to produce a border around the child. If you want a border around one of the child views of a TKSplit, an intermediate TKView should be instantiated. Append the TKView as the immediate child of TKSplit, and then append the next view to the intermediate TKView container. The TKView's offsets will be managed by TKSplit. The TKView's child can be offset from it.

Split Methods

Method	Description	Offset
reorient_	Change the split orientation	61

Change the split orientation (reorient_)

Input	Description
A	Split Orientation
Output	Description
-	None

The orientation of a TKSplit view can be changed at runtime. This should not be done by manually changing the TKSplit's orient property. Instead, call its reorient_ method and pass the new orientation in the accumulator. See constants below.

---

Object Definition

//os/tk/s/:tksplit.s

Object Size: 45 (+3) bytes

Drawing Properties

Property	Description	Size	Offset
bcolor	Background Color	1	34

Background Color (bcolor)

The background color property is used to set the color of the splitter bar. Color restrictions of the VIC-II's hi-res character mode have implications for how the background color property affects the appearance of the splitter bar.

If the bcolor property is the same as the c_bckgnd property of the color theme (which is used to set the VIC-II background color register) then the foreground color of the nub is automatically displayed using the c_button color of the color theme.

If the bcolor property is something other than the c_bckgnd property of the color theme then that is used as the color of the bar, but by necessity the color of the nub becomes the VIC-II's background color, which is the c_bckgnd property of the color theme.

After manually changing the bcolor property of TKSplit, it is necessary to set the df_dirty flag of the dflags property to force the TKSplit to redraw using the new colors.

Split Properties

Property	Description	Size	Offset
orient	Split Orientation	1	39
spos	Split Position	2	40
schild	Second Child	2	42
collapse	Splitter Collapse Flags	1	44

Split Orientation (orient)

This property holds the current orientation of the TKSplit. See constants below.

This property is typically read-only. To change the orientation of a TKSplit at runtime use the reorient_ method.

There is one exception to this. Immediately after calling init_ on a new TKSplit, the orient property can be set manually to change its default orientation, prior to adding the first child view.

Split Position (spos)

The split position property indicates where the splitter bar is.

When the TKSplit is oriented vertically, if spos is zero, the splitter will run up and down the leftmost column of the TKSplit's visible area. If the vertical bar is collapsed, only the nub will be visible at the bottom of the leftmost column, and one column of the left child view will still be visible.

Examples of Vertical Split. In this example, spos = 15

When the TKSplit is oriented horizontally, if spos is zero, the splitter will run left to right in the topmost row of the TKSplit's visible area. If the horizontal bar is collapsed, only the nub will be visible at the right end of the topmost row, and one row of the top child view will still be visible.

The spos property can be set programmatically. However, after changing the spos property it is necessary to set the mf_resiz flag on the mflags property. The spos property may always be read to get the current position of the split.

Second Child (schild)

This property is used internally only. It should be considered private.

Collapse (collapse)

The collapse property holds the flags for whether the horizontal or vertical splitter bars should be collapsed.

Collapsing the splitter bar is most useful when the left or top child view is showing a scroll bar. In a vertical split, if the left child is showing a scroll bar then that scroll bar makes a visually distinctive divider between the two sides. It is usually unnecessary to use the full split bar as another divider. In this case, the vertical collapse flag (clps_ver) can be set.

When the splitter bar is horizontal, collapsing the horizontal split bar makes sense if the top child view is showing a horizontal scroll bar.

The vertical and horizontal collapse are two different flags so they can be set independently. When the split is reoriented using the reorient_ method the collapsed state of its new orientation is taken into consideration immediately.

After changing the collapse flags it is necessary to set the mf_resiz flag on the mflags property.

Examples of Horizontal Split

In example 1, because the top view has no horizontal scroll bar, the split bar should be uncollapsed so the two views have a visual divider. In example 2, the top child has a horizontal scroll bar turned on. If the horizontal split is not collapesed you get a double divider which may not be appropriate.

In example 3, because the split bar is collapsed and there is no horizontal scroll bar, this is probably bad as there is no clear division between the top and bottom views. It may still work, however, if the bottom view had some natural divider running along the top, such as a set of tabs. Example 4 shows the usefulness of collapsing the horizontal split in an appropriate situation. The horizontal scroll bar of the top view forms a natural divider, and the split bar's nub fits into the space left where the scroll bars meet.

Constants

TKSplit constants are defined by //os/tk/s/:tksplit.s

Split Orientations

Constant	Value	Description
so_hor	0	Make the splitter bar horizontal
so_ver	1	Make the splitter bar vertical

Collapse Flags

Constant	Value	Description
clps_hor	%100000000	Indicates if the horizontal splitter should be collapsed
clps_ver	%000000001	Indicates if the vertical splitter should be collapsed

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