C64 OS PROGRAMMER'S GUIDE

Class Reference: TKLabel:TKView:TKObj

Overview

TKLabel is used to put a single-line label into the user interface. It can be used beside a text field or other control to label it, or it can be used at the top of a section to label the whole section.

It inherits from TKView but is not a container view and cannot have child nodes appended to it. TKLabel objects are always one row high, but may have a fixed or flexible width, and may be anchored top, left, right or bottom of their parent view.

The label is assigned a pointer to a string to draw. The string may be aligned left, right, or centered within the bounds of the label. If the label string is longer than the visible width of label's bounds, the string is left aligned and clipped off the right end.

When the label is used in a non-reversed context, that is, when the background of the label matches the background color of the global screen, the text color can be changed. The color can either be set explicitly, or it can be set to take its value dynamically from the color theme.

Subclassing notes

TKLabelBox is a subclass of TKLabel. Other subclassing opportunities exist around changes to how the label is drawn.

Class Definition

//os/tk/h/:tklabel.h

Init (init_)

During initiation, TKLabel is initialized as a standard TKView. By default it is assigned the generic string "Label" and is left aligned. The color of the label text is defaulted to display text, c_dsptxt from the color theme.

By default a TKLabel is anchored top, left and right, with a height of 1.

Content Methods

Method	Description	Offset
setstrp_	Set string pointer	61

Set string pointer (setstrp_)

Input	Description
A/X → string pointer	NULL-terminated string
Output	Description
-	None

Most pointers in C64 OS use a RegPtr to pass data to a routine or a method. The setstrp_ method of TKLabel is a notable exception. The string pointer must be passed in the A (low-byte) and X (high-byte) registers. The string must be a C-style string, i.e., terminated by a NULL ($00) byte.

The label renders the string that has been assigned to it. By default TKLabel does not clear its own background before rendering its string. This is because most labels are static and therefore this default is more efficient. If the TKLabel's string content is changed dynamically, or if it is assigned a new string that has a different length, it is necessary to enable the df_opaqu bit of the dflags property, in order to prevent rendering glitches.

;After calling the init method
#setflag this,dflags,df_opaqu

---

Object Definition

//os/tk/s/:tklabel.s

Object Size: 44 (+3) bytes

Content Properties

Property	Description	Size	Offset
strptr	String pointer	2	39
strflgs	String flags	1	41
strlgth	String length	2	42

String pointer (strptr)

This property is private and not defined by the header file. When a string is assigned to the label with the setstrp_ method, the string pointer is assigned to this property. To change the string pointer property you should call the setstrp_ method again.

String flags (strflgs)

A set of bit flags controls how the label is drawn. See constants below for the bit flag options.

Text alignment of the content of the label is controlled with two bit flags, a_lft and a_rgt.

Alignment	Bits	Notes
Left	a_lft	The text of the label aligns left and is clipped at the right edge.
Right	a_rgt	The text of the label aligns right and is clipped at the left edge.
Center	a_lft | a_rgt	The text of the label aligns center and is clipped at both left and right edges.

Label Color (bcolor)

By default, when a label is drawn, the characters are not reversed. This means that the background of the label is the global background color of the screen. In this mode, the foreground color of the label text comes from the bcolor property, defined by TKView.

When the bcolor high bit is clear, the lower bits specify an absolute color for the label text. This is sometimes appropriate, but it could lead to conflicts if the user changes the color theme. See constants below for the color options. For example, to have a label dynamically use the color purple, set the bcolor property like this:

#setobj8 this,bcolor,cpurple

When the bcolor high bit is set, the lower bits specify an index into the color themes table. This allows a label to take on the appearence of any defined element from the color theme. See constants below for the color theme options. For example, to have a label dynamically use the strong text from the color theme, set the bcolor property like this:

#setobj8 this,bcolor,c_stgtxt.$80

The bcolor property retains its value, and the actual color is looked up from the theme every time the label is redrawn. If the theme changes while an Application is open, the label will automatically take on the new color.

Reverse Color (f_rev)

It sometimes happens that a label is being drawn on a background that is already reversed. The common example of this is when a label is drawn directly above a Utility panel. The typical Utility panel is light grey, and the typical global screen background is white. If a label is drawn in the standard non-reversed mode, it would display as an awkward white box with colored text. This is not usually desirable.

Instead, the f_rev bit can be set on the strflgs property. The label is then drawn in reverse characters. However, due to the limitations of the VIC-II's character mode, there can be only one global background color for the whole screen. In reverse mode, the text is shown in the background color, typically white, and therefore the bcolor property defines the background of the label.

Since the point of reversing the label is usually to make it blend in with the existing reversed characters context, the bcolor should be set to match the surrounding context. The bcolor value is interpreted the same way whether or not the f_rev flag has been set. For example, if the label is drawn on a Utility panel, to make the label blend in and look natural, you would set the f_rev flag and set the bcolor property to take the themed c_fpanel color. Like this:

#setflag this,strflgs,f_rev
#setobj8 this,bcolor,c_fpanel

String length (strlgth)

This property is used internally only, to help the TKLabel class compute how to draw and clip the label in the different alignment options available. There should be no reason to access this property. It should not be changed manually.

Constants

TKLabel constants are defined by //os/tk/s/:tklabel.s

String Flags

Constant	Bit	Description
a_lft	%0000 0001	Text left align
a_rgt	%0000 0010	Text right align
f_rev	%1000 0000	Draw label in reverse

Color constants are defined by //os/s/:colors.s

Constant	Value
cblack	$00
cwhite	$01
cred	$02
ccyan	$03
cpurple	$04
cgreen	$05
cblue	$06
cyellow	$07
corange	$08
cbrown	$09
clred	$0a
cdgrey	$0b
cmgrey	$0c
clgreen	$0d
clblue	$0e
clgrey	$0f

Color theme constants are defined by //os/s/:ctxcolors.s

Constant	Value	Description
c_border	$00	Global screen border
c_bckgnd	$01	Global screen background
c_fpanel	$02	Floating panel background
c_ftitle	$03	Floating panel title bar
c_mnubar	$04	Menu bar background
c_mnusel	$05	Highlighted menu background
c_dsptxt	$06	Normal display/body text
c_stgtxt	$07	Strong text
c_emftxt	$08	Emphatic text
c_seltxt	$09	Text input cursor, selected text and other selections
c_button	$0a	Standard button
c_defbut	$0b	Default button
c_scrlfg	$0c	Scroll bar nub and buttons
c_scrlbg	$0d	Scroll bar track
c_disabl	$0e	Disabled menu, button, or other element
c_txtfld	$0f	Unfocused text field
c_txffoc	$10	Focused text field
c_tabfoc	$11	Focused/selected tab
c_tabblr	$12	Unfocused/unselected tab
c_colfoc	$13	Focused/sorted column header
c_colblr	$14	Unfocused/unsorted column header

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