EmbeddedButtonsDoc.tioga
Bier, September 8, 1989 7:10:08 pm PDT
Kenneth A. Pier, September 30, 1992 11:39 am PDT
Eric A. Bier
1. Introduction
As described in the abstract, EmbeddedButtons is mainly a collection of registries for editors, button classes, and applications. While it is possible that some clients may wish to add new editors and button classes to the system, we anticipate that most of the clients of this package will add new applications that increase the usefulness of active documents. The next section describes ways to add new applications.
Clients interested in adding new editors to the system should see the EBEditors interface. Clients interested in adding new button classes should see the EBButtonClasses interface.
2. Adding New Applications
Introduction
Before you add a new application to the Embedded Buttons world, you should have an understanding of how embedded buttons are used. A button is a document element, such as a Tioga character or a Gargoyle slice, that has a property called ButtonData. For instance, the next sentence begins with a button.
Button -- this is a pop-up button
To see the ButtonData property of this button, select the entire node and click CTRL-U. To restore the original text, select all of the expanded text, from BEGIN NODE to END NODE, and click CTRL-SHIFT-U. The ButtonData you see should look like this:
Poppy1
Class: PopUpButton
MessageHandler: Colorizer
Menu: (
((SetColor Red) "Red" "Makes selected objects red")
((SetColor Green) "Green" "Makes selected objects green")
((SetColor Blue) "Blue" "Makes selected objects blue")
)
Poppy1 is the name of the language that is used to represent buttons. This ButtonData says that this is a pop-up button that sends command to an application called "Colorizer". The Menu field describes of pop-up menu with three entries, labeled "Red," "Green," and "Blue." The text string following the entry name is string that will be displayed when the mouse is over that entry. The parenthesized expression before each entry name represents a list of tokens that will be sent to Colorizer.
When this pop-up menu is used, Colorizer will receive a list of ATOMs, being either LIST[$SetColor, $Red], LIST[$SetColor, $Green], or LIST[$SetColor, $Blue] depending on which menu entry is clicked.
You can register an application, like Colorizer, using EmbeddedButtons.RegisterApplication.
Applications for All Documents
To register an application, like Colorizer, that is available from any button, just by button its name in the button's MessageHandler field, simply register your application's notify procedure using EmbeddedButtons.RegisterApplication. Thereafter, buttons that mention your application's name in the MessageHandler field will send a LIST OF REF to your notify procedure when they are clicked.
Each element of this list will be either an ATOM, a REF INT, a REF BOOL, a REF REAL, or a ROPE, depending on how the Cedar language parser interprets each token of the command string. For instance, if the Menu field of a PopUpButton were
Menu: (
((Foo 12 TRUE) "Foo" "Do a foo")
((Bar 12.0 "Hello") "Bar" "Do a bar")
)
then the MessageHander would receive a list of (ATOM, REF INT, REF BOOL) or a list of (ATOM, REF REAL, ROPE) depending on which menu entry was chosen.
Applications Linked to a Single Document
<to be written>
Null Documents
An application may use a set of EmbeddedButtons as a control panel. That control panel will normally appear as a top level viewer in the application container. Some applications will allow themselves to be lower level children of other applications, and their control panel may not be visible. Gargoyle is one such application. In that case, the child application may need to have a dummy control panel. EBNullDoc provides the capability to create an Active Doc that has no viewer or visible representation, but is simply a place for the application to link to for the purpose of defining stateful buttons used by that application. For an example, see the code in Gargoyle, GGWindowImpl.CreateChildViewer.