C64 OS PROGRAMMER'S GUIDE

Class Reference: TKCtrl:TKView:TKObj

Overview

TKCtrl is an abstract superclass of a set of control classes that share a set of properties and methods that are common to most user interface controls.

A TKCtrl inherits from TKView but typically does not have child views appended to it. By default an exception is raised if a child is appended to a TKCtrl.

As an abstract superclass you will not instantiate a new TKCtrl object directly, nor add one to a view hierarchy. You will only instantiate concrete subclasses which inherit from TKCtrl.

Subclassing notes

TKCtrl exists to be subclassed. There are two built-in classes which inherit from it, TKButton and TKSBar.

Class Definition

//os/tk/h/:tkctrl.h

Init (init_)

During initialization, TKCtrl assigns this as the default sender of targeted actions. The sender can be changed to be some alternative object after initialization.

By default a TKCtrl is configured with all of its control flags turned off. This means:

• Not Reverse Mode
• Not Continuous Action Send
• Not Default Control
• Not Disabled, and
• Radio/Checkbox State Unchecked

The repeat timer, used when continuous mode is enabled, defaults to 1/20th of a second. And all controls are initialized as having a single byte value of #0.

Left Mouse Down (musdown_)

This method implementation first checks the disabled flag (cf_disab) on the control flags property (cflags.) If the control is disabled, the event is handled by calling the superclass method. This will typically result in the event being propagated up the view hierarchy, but no other behavior of a control is performed.

If the continuous flag (cf_cont) is set, a timer is configured and queued to continously fire the action of this control each time the timer expires. Partial state of the Toolkit environment is preserved globally for this class. When the timer expires this state is used to reestablish the current Toolkit environment. Therefore, it is only possible for one control at a time (even across multiple Toolkit environments) to be firing continuously.

Left Mouse Up (musup_)

This method implementation dequeues any queued continuous timer before calling the superclass implementation.

Add Child (addchild_)

The only thing this method does is raise an exception. Controls cannot take child views, as that would allow them to embed nested controls, which leads to problems.

Some types of complex controls which are built of multiple coordinated controls should inherit from some class other than TKCtrl, such as TKView>.

Targetting Methods

Method	Description	Offset
settgt_	Set a target	61
sendact_	Send action	64

Set a target (settgt_)

Input	Description
A → Action type flag	0 = Not an object-oriented method
RegPtr → Action Routine Pointer	Pointer to a routine when A = 0
A → Action method offset	Offset to an object's method
RegPtr → NULL	Method is called on firstkey view
RegPtr → Target Object	Fixed object on which method is called
Output	Description
-	None

The fundamental behavior of a control is that it holds a value and when triggered performs an action on a target. The target usually gets a reference to the triggered control and reads the value, or other properties, off the control to help it determine what to do.

The target can either by another Toolkit object or it can be configured to call any non-object-oriented routine. The settgt_ method is used to set up the control's target.

The accumulator has a double role as a flag and a method offset. Zero is not the offset to any method. Therefore, if the accumulator is passed as zero, this means the target is a non-object-oriented routine. A RegPtr must also be passed in to the target routine.

If the accumulator is passed in as anything greater than zero, then it is a method offset. When the control is triggered, it looks up that method on the target object and calls it. However, the target object may be fixed or dynamic. If the RegPtr is null then the target object is the first key view. Otherwise the RegPtr is to a specific target object.

Send Action (sendact_)

Input	Description
C → Set = Keyboard Triggered	Control was triggered by the keyboard
C → Clr = Mouse Triggered	Control was triggered by the mouse
Output	Description
C ← Set = No Action Taken	No target object or target took no action
C ← Clr = Action Taken	Target took some action or underwent some change

As an abstract superclass, TKCtrl provides a way to send its action but none of its own methods call sendact_. This method is intended to be called by the event handling methods of TKCtrl subclasses.

It can also be called programmatically by non-object-oriented code. For example, to have a menu item perform the same task as clicking a button, the routine that is called when the menu item is selected can lookup an instance of TKButton (which is a concrete subclass of TKCtrl) and call its sendact_ method.

When a TKCtrl is keyboard triggered, its cf_hilit flag is set on the cflags property. This allows the control to draw itself in an alternative activated or highlighted state. sendact_ configures a timer to clear the highlight flag and redraw after 1/6th of a second.

When calling the target, either method or routine, a RegPtr is passed that points to the sender. The sender is the object that is nominally sending the action. During init_ the sender property is initialized to this. Therefore, by default, when a button is clicked the target method or routine is called and the RegPtr points to the button that was clicked. However, the sender property can be changed after a control is initialized. This allows for custom classes that coordinate multiple controls to have those controls specify their coordinating object as the sender.

When this method is called, if the target routine or target object is null, the carry is immediately returned set. This includes if the target object is dynamic and first key view is currently null.

Content Methods

A TKCtrl object has one value and a property valtype that specifies the type of that value. The types include, a byte, a word, a float, or a string pointer. Each of the following methods sets the value of the control and also sets the type.

Method	Description	Offset
setbyt_	Set with a 1 byte integer value	67
setwrd_	Set with a 2 byte integer value	70
setflt_	Set with a 5 byte float value	73
setstr_	Set with a 2 byte string pointer value	76

Set Byte Value (setbyt_)

Input	Description
A → 1-byte value	1-byte integer value
Output	Description
-	None

The 1-byte integer value of the control is passed in the accumulator. The valtype property is set to vt_byt.

Set Word Value (setwrd_)

Input	Description
RegWrd → 2-byte value	2-byte integer value, little endian
Output	Description
-	None

The 2-byte integer value of the control is passed in a RegWrd. The valtype property is set to vt_wrd.

Set Float Value (setflt_)

Input	Description
FAC → 5-byte value	5-byte float value, BASIC format
Output	Description
-	None

The 5-byte float value of the control is passed via the FAC, floating point accumulator used by the BASIC ROM's floating point math routines. The valtype property is set to vt_flt.

The location of the FAC is defined by //os/s/:float.s and floating point math routines used to move float values into and out of the FAC are found in the BASIC ROM and defined by //os/h/:float.h.

Set String Value (setstr_)

Input	Description
RegPtr → 2-byte string pointer	Pointer to a NULL-terminated string
Output	Description
-	None

A control that has a string value holds a 2-byte pointer to the string, not the string itself. That pointer is passed in a RegPtr. The valtype property is set to vt_str.

The string must be a C-string, i.e., it must be properly NULL-terminated.

---

Object Definition

//os/tk/s/:tkctrl.s

Object Size: 54 (+3) bytes

Action Properties

Property	Description	Size	Offset
sender	Object pointer	2	39
act_meth	Action method offset	1	41
act_tgt	Action target	2	42

Sender object pointer (sender)

During initialization sender is set to this. The value of sender is sent in a RegPtr to the target when the sendact_ method is called.

This property can be changed after initialization to have the control specify a different object as the sender when its action is sent to the target.

#storeget views,othersender
#setobjxy this,sender

Action Method (act_meth)

This property should only be set with the settgt_ method. It holds the flag for whether the target is an object or a non-object routine, and if the target is an object this property is the method offset on that object.

Action Target (act_tgt)

This property should only be set with the settgt_ method. If the target is an object, this property holds a pointer to that object or null to specify a dynamic target. If the the target is not an object, this property holds a pointer to the routine to be called by the sendact_ method.

Interaction Properties

Property	Description	Size	Offset
cflags	Control Flags	1	44
rtval	Repeat Timer Value	3	45

Control Flags (cflags)

Some of the control flags are managed automatically by subclasses of TKCtrl to manage the control's state. Others can be set programmatically to adjust the behavior of the control.

Constant	Value	Notes
cf_rvrs	1	Draw the control in reverse mode.
cf_cont	2	Fire the action continuously while the mouse button is down.
cf_hilit	16	Draw the control in a highlighted state. This flag is managed automatically.
cf_deflt	32	The control has default status. Affects drawn appearence and RETURN key trigger.
cf_state	64	Holds active/inactive state. Affects how the control is drawn.
cf_disab	128	Holds the enabled/disabled state. Affects how the control is drawn and whether it can be triggered.

Repeat Timer Value (rtval)

If a control's continuous flag (cf_cont) is set, the control will fire continuously at a regular interval while the mouse is held down. This allows for cycle buttons to be rotated continuously by clicking and holding it, or for scroll bars to be scrolled continuously by clicking and holding one of the scroll buttons or in the scroll track.

The rate of continuous firing is controlled by the repeat timer value (rtval). The value is 3 bytes, which are copied into the repeat timer which is managed (queued and canceled) by TKCtrl. The value is a count in jiffies and is little endian.

This value is initialized to 1/20th of second. (3, 0, 0.) (Slighly slower on PAL, 1/16th of a second.)

Value Properties

Property	Description	Size	Offset
valtype	Control Value Type	1	48
value	Control Value	5	49

Control Value Type (valtype)

The control's value type is set by calling one of the content methods.

This property can be read and referenced by a control's target to determine what action or behavior should be taken.

Constant	Value	Notes
vt_byt	1	1-byte Integer (Byte)
vt_wrd	2	2-byte Integer (Word)
vt_flt	4	5-byte Float (BASIC format)
vt_str	8	2-byte Pointer (Pointer to C-String)

Control Value (value)

The control's value is set by calling one of the content methods.

This property can be read and referenced by a control's target to determine what action or behavior should be taken. The target's action may be to modify the value of the sending control. This should be done by calling one of its content methods.

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: Oct 11, 2024