17.5 Operating upon objects and items

The Works > Object and Works > Slots submenus allow you to perform the standard action commands on either the object being inspected, or the slot values selected in the main list. The commands available are largely identical in both menus, and so are described together in this section.

17.5.1 Examination operations

The standard action commands are available in both the Works > Object and Works > Slots menus, allowing you to perform a variety of operations on the current object or any items selected in the list. For full details of the standard action commands, see 3.8 Performing operations on selected objects.

17.5.1.1 Example

Consider the following example, where a closure is defined:

(let ((test-button (make-instance 'capi:button)))
  (defun is-button-enabled ()
    (capi:button-enabled test-button)))

This has defined the function is-button-enabled, which is a closure over the variable test-button, where the value of test-button is an instance of the capi:button class.

Enter the definition of the closure shown above into a Listener.
Choose Works > Values > Inspect.
The Inspector examines the symbol is-button-enabled.
Click on the FUNCTION slot to select the closure.
Choose Works > Slots > Inspect to inspect the value in the selected slot.

The closure is inspected.

17.5.1.2 Recursive inspection

You can also double-click on an item in the attributes list to inspect its value. Most users find this the most convenient way to recursively inspect objects.

To return to the previous inspection, choose History > Previous or click in the toolbar.

17.5.2 Examining attributes

The Works > Slots > Attributes submenu allows you to apply the standard action commands (described in 3.8.1 Operations available) to the attributes rather than the values of those attributes.

For example, the Works > Slots > Attributes > Inspect command causes the Inspector to view the attributes, rather than the values, of the selected slots. This is useful when inspecting hash tables or lists, since the attributes (keys) might be composite objects themselves.

17.5.3 Tracing slot access

The Works > Slots > Trace submenu provides four commands. When inspecting a CLOS object, code which accesses the selected slot may be traced using these commands.

Break on Access causes a break to the debugger if the slot is accessed for read or write, either by a defined accessor or by slot-value.

Break on Read causes a break to the debugger if the slot is accessed for read, either by a defined accessor or by slot-value.

Break on Write causes a break to the debugger if the slot is accessed for write, either by a defined accessor or by slot-value.

Untrace turns off tracing on the selected slot.

The Works > Object > Trace submenu provides the same four options, but these commands control the tracing of all the slots in the object.

17.5.4 Manipulation operations

As well as examining objects in the Inspector, you can destructively modify the contents of any composite object.

This sort of activity is particularly useful when debugging; you might inspect an object and see that it contains incorrect values. Using the options available you can modify the values in the slots, before continuing execution of a program.

Choose Works > Slots > Set to change the value of any selected slots. A dialog appears into which you can type a new value for the items you have selected. Previously entered values are available via a dropdown in this dialog.

Choose Works > Slots > Paste to paste the contents of the clipboard into the currently selected items.

17.5.4.1 Example

This example takes you through the process of creating an object, examining its contents, and then modifying the object.

Create a button as follows:

(setq button1 (make-instance 'capi:button))

Choose Works > Values > Inspect in the Listener to inspect the button in the Inspector.
In the Listener, use the CAPI accessor button-enabled to find out whether button1 is enabled.
```
(capi:button-enabled button1)
```
This returns t. So we see buttons are enabled by default. The next step is to destructively modify button1 so that it is not enabled, but first we will make the Inspector display a little simpler.
Choose Tools > Preferences... and select Inspector in the list on the left side of the Preferences dialog. You can now change the current package of Inspector tools.
In the Package box, replace the default package name with CAPI and click OK.
This changes the process package of the Inspector to the CAPI package, and the package name disappears from all the slots listed. This makes the display a lot easier to read.
In the Inspector, type enabled into the Filter box.
Button objects have a large number of slots, and so it is easier to filter out the slots that you do not want to see than to search through the whole list. After applying the filter, only one slot is listed.
Select the slot enabled.
Choose the Works > Slots > Set... menu item.
A dialog appears into which you can type a new value for the slot enabled.
Entering a new slot value
Note that previously entered forms are available via a dropdown in this dialog. Enter nil (or select it from the history) and click on OK.
The attributes and values area shows the new value of the enabled slot.
Click on the button. This removes the filter and displays all the slots once again.
To confirm that the change happened, type the following in the Listener. You should be able to recall the last command using Alt+P or History > Previous.
```
(capi:button-enabled button1)
```
This now returns nil, as expected.

The next part of this example shows you how you can modify the slots of an object by pasting in the contents of the clipboard. This example shows you how to modify the text and font of button1.
Type the following into the Listener and then press Return:
```
"Hello World!"
```
Choose Works > Values > Copy to copy the string to the clipboard.
Select the TEXT slot of button1 in the Inspector.
Choose Works > Slots > Paste to paste the "Hello World!" string into the text slot of button1.
This sets the text slot of button1 to the string.

Enter the following into the Listener and press Return:

(let ((font (capi:simple-pane-font button1)))
  (if font 
      (gp:find-best-font 
       button1 
       (apply 'gp:make-font-description 
              (append (list :size 30) 
                      (gp:font-description-attributes 
                       (gp:font-description 
                        (capi:simple-pane-font button1))))))
    (gp:make-font-description :size 30)))

This form simply calculates a large font object suitable for the button object.

Choose Works > Values > Copy to copy the font to the clipboard.
Select the FONT slot of button1 in the Inspector.
Choose Works > Slots > Paste to paste the font into the font slot of button1.
Confirm the effect of these changes by displaying the button object. To do this, choose Works > Object > Listen.
This transfers the button object back into the Listener. As feedback, the string representation of the object is printed in the Listener above the current prompt. The object is automatically transferred to the * variable so that it can be operated on.
In the Listener, type the following:
```
(capi:contain *)
```

This displays a window containing the button object. Note that the text now reads "Hello World!", as you would expect, and that the font size is larger than the default size size for buttons. Note further that you cannot click on the button; it is not enabled. This is because you modified the setting of the enabled slot in the earlier part of this example.

17.5.5 Copying in the Inspector

You can easily copy objects in the inspector, ready for pasting into other tools.

To copy the inspected object itself use Works > Object > Copy.

To copy a slot value use Works > Slots > Copy.

To copy an attribute use Works > Slots > Attributes > Copy.

Similarly you can use Works > Object > Clip, Works > Slots > Clip or Works > Slots > Attributes > Clipto place the object itself, a slot value or an attribute on the Object Clipboard, so that you can conveniently retrieve them later. See 8 The Object Clipboard for details.