Pad++ Programmer's Guide

APPLICATION-DEFINED ITEM TYPES AND OPTIONS

Pad++ may be extended entirely with Tcl scripts (i.e., no C/C++ code). This provides a mechanism to define new Pad++ types and a way to define options for those types (or built-in types). These user-defined types and options are treated like first-class Pad++ objects. That is, they can be created, configured, saved, etc. with the same commands you use to interact with built-in objects, such as lines or text. These extensions are particularly well-suited for widgets, but can be used for anything.

For example, the PadDraw application defines a few sample widgets such as a checkbutton with the type mechanism. It also defines -roughness and -undulate options for the built-in line type.

Types and options are defined with the addtype and addoption commands, respectively. The addtype command defines a new type with a script that gets evaluated whenever a new item of that type is created with the create command. The pathname of the pad widget is added on to the script as an extra parameter when the script is evaluated. The script must return the id of an item that it creates that is to be treated as the new type. Any item type can be created for this purpose, and it will be treated as the new type. If a -renderscript is attached to this item, then this item type can have any desired visual look. Alternatively, the script might create a group with members that define the item's look.

The addoption command defines a new option for a built-in or user-defined type. This option is accessed the regular way with the itemconfigure command, and will get written out with the write command. Similar to the addtype command, addoption defines a script that gets evaluated whenever the user-defined option is accessed for an item of the specified type. The script must return the new value of the option. When the script is evaluated, two or sometimes three extra parameters are added on to the end of the string. They are:

pathName: The name of the pad widget the item is on.
item: The id of the item being configured.
[value]: Optional value. If value is specified, then the option must be set to this value.

The following example shows how to define a new "property" type that has two slots, -option and -value. When an item of type property is created, It appears as text with the option on the left and the value on the right separated by a colon and some space.

#
# Add new "property" type
#
.pad addtype property propCreate

#
# Define script to handle creation of property item
#
proc propCreate {PAD} {
	set option [.pad create text -anchor e -text "option: "]
	set value [.pad create text -anchor w -text "value"]
	set group [.pad create group -members "$option $value"]

	return $group
}

#
# Add "-option" and "-value" options to the property type
#
.pad addoption property -option "propConfig -option" "option"
.pad addoption property -value  "propConfig -value"  "value"

#
# Handle property item configuration
#
proc propConfig {args} {
	set option [lindex $args 0]
	set PAD [lindex $args 1]
	set id [lindex $args 2]
	set got_value 0
					
# Access arguments
	if {[llength $args] >= 4} {
		set value [lindex $args 3]
		set got_value 1
	} else {
		set value ""
	}
	switch -exact -- $option {		
		-option {     ;# Handle "-option" option
			set option_id [lindex [$PAD ic $id -members] 0]
			if {$got_value} {
				$PAD ic $option_id -text "$value: "
			} else {
				set value [$PAD ic $option_id -text]
				set len [expr [string length $value] - 3]
				set value [string range $value 0 $len]
			}
		}
		-value {      ;# Handle "-value" option
			set option_id [lindex [$PAD ic $id -members] 1]
			if {$got_value} {
				$PAD ic $option_id -text "$value"
			} else {
				set value [$PAD ic $option_id -text]
			}
		}

		default {return -code error "Unknown option: $option"}
	}

	return $value
}

The property item can be created and accessed just like any built-in item. The following code shows how one might use a property item.

set prop [.pad create property]
.pad itemconfig $prop -option "color"
.pad itemconfig $prop -value "blue"
set color [.pad itemconfig $prop -value]
puts "color of property is $color"

Pad++ Programmer's Guide - 20 JUN 1997

Web Accessibility