The C64 OS Programmer's Guide is being written

This guide is being written and released and few chapters at a time. If a chapter seems to be empty, or if you click a chapter in the table of contents but it loads up Chapter 1, that's mostly likely because the chapter you've clicked doesn't exist yet.

Discussion of development topics are on-going about what to put in this guide. The discusssions are happening in the C64 OS Community Support Discord server, available to licensed C64 OS users.

C64 OS PROGRAMMER'S GUIDE

Chapter 6: Using Toolkit: Class Reference

Toolkit consists of a number of built-in classes, plus a growing number of runtime loadable classes. With the built-in classes it is possible to build a typical user interface consisting of push buttons, cycle buttons, checkboxes and radio buttons, with labels and organized into a number of containers, such as a horizontal or vertical split view, a set of tabs, or a scrollable region with vertical or horizontal scroll bars.

To build more sophisticated user interfaces, such as the ability to take typed input, it is necessary to load and link the additional classes needed to build the interface.

Each class provided by C64 OS is given its own page to describe its super class, its properties and its methods, along with discussion and sample code showing how these are used.

Built-in classes

Pointers to the built-in classes can be fetched using ptrthis, passing in the X register the ClassID.

class TKObj

ClassID: tkobj

TKObj is the root class. It inherits from nothing, and all other classes inherit, ultimately, from it.

class TKView:TKObj

ClassID: tkview

TKView adds to TKObj node properites, allowing all classes that inherit from TKView to be appended to the view hierarchy. TKView also adds the ability for objects to draw themselves and to handle input events.

class TKSplit:TKView:TKObj

ClassID: tksplit

TKSplit manages two child TKViews. It positions and sizes them automatically either above and below or left and right, with a draggable bar at the separation point. When the bar is dragged TKSplit automatically manages to size of its two child views to reapportion screen real estate between them.

class TKTabs:TKView:TKObj

ClassID: tktabs

TKTabs manages from 1 to 10 TKViews. It positions and sizes them automatically stacked one on top of the other. It draws a bar of tabs along the top. When a tab is selected, all child views are hidden, except the one child associated with that tab which is shown.

class TKScroll:TKView:TKObj

ClassID: tkscroll

TKScroll manages from a single content TKView. It optionally instantiates and appends to itself a vertical and/or horizontal TKSBar class. TKScroll coordinates the size and scrolled offsets of its content view with the size and position of the scroll nub in the two scroll bar objects.

class TKLabel:TKView:TKObj

ClassID: tklabel

TKLabel is a single row of text. The text can be left, right or center aligned within the label's bounds. TKLabel draws a provided string of text. TKLabel cannot contain child views.

class TKCtrl:TKView:TKObj

ClassID: tkctrl

TKCtrl is the abstract superclass of all a set of control classes which can profitably benefit from the properties that it provides. This common inheritance allows different controls to be substituted generically one for the other.

class TKButton:TKCtrl:TKView:TKObj

ClassID: tkbutton

TKButton is a subclass of TKCtrl and therefore inherits an action that can be triggered by clicking it. It also has a value. The button can be configured to serve as either a push button, a cycle button, a radio button or a checkbox.

class TKSBar:TKCtrl:TKView:TKObj

ClassID: tksbar

TKSBar is also a subclass of TKCtrl but, unlike TKButton, its use is much more restricted. Typically TKScroll creates and automatically manages instances of TKSBar. Interacting with TKSBar sends messages to its TKScroll parent view to assist in scrolling content.

Runtime loadable classes

Runtime loadable classes must first be loaded, relocated, and linked to their parent class, instructions for which are found below. When a class is linked a pointer to it is returned which must be preserved either in a variable or in a pointer store.

Instantiating a runtime loadable class is performed with tknew the same as when instantiating a built-in class. The difference is that the pointer to the built-in class is fetched by passing a ClassID to classptr. Where as with runtime loadable classes you retrieve the class pointer from the pointer store where it was saved at the time that it was loaded and linked, and then pass that pointer to tknew.

The following list groups similar classes together, and the are listed in alphabetical order within that group.

Information Views

class TKCpuU:TKView:TKObj

class TKDirInfo:TKView:TKObj

class TKFileMeta:TKView:TKObj

class TKRamU:TKView:TKObj

class TKReuU:TKView:TKObj

Controls

class TKDatePick:TKView:TKObj

class TKIcon:TKCtrl:TKView:TKObj

class TKInput:TKCtrl:TKView:TKObj

class TKPBar:TKView:TKObj

class TKRating:TKCtrl:TKView:TKObj

class TKTimePick:TKView:TKObj

class TKTArea:TKCtrl:TKView:TKObj

Container Views

class TKLabelBox:TKLabel:TKView:TKObj

Content Views

class TKList:TKView:TKObj

class TKPlaces:TKView:TKObj

class TKTable:TKList:TKView:TKObj

class TKTCols:TKScroll:TKView:TKObj

class TKText:TKView:TKObj

How to load and link a class

Subclassing Toolkit Classes

In addition to the Toolkit classes provided in C64 OS, it is also possible to create your own custom subclasses any of previously exist class. How to subclass is the topic of the next section.

Next Section: Subclassing

Next Chapter: Writing an Application

This document is subject to revision updates.

Last modified: Oct 11, 2024