visualsmalltalk enterprisealereimondo.no-ip.org/papers/uploads/2/wbenchug.pdf · shortcuts. for...

VisualSmalltalk Enterprise ™ ™

Workbench User's Guide

P46-0203-00

Copyright © 1999–2000 Cincom Systems, Inc. All rights reserved.

Copyright © 1999–2000 Seagull Systems, Inc. All rights reserved.

This product contains copyrighted third-party software.

Part Number: P46-0203-00

Software Release 3.2

This document is subject to change without notice.

RESTRICTED RIGHTS LEGEND:

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013.

Trademark acknowledgments:

CINCOM, CINCOM SYSTEMS, and the Cincom logo are registered trademarks of Cincom Systems, Inc. Visual Smalltalk is a trademark of Cincom Systems, Inc., its subsidiaries, or successors and are registered in the United States and other countries. Microsoft Windows is a registered trademark of Microsoft, Inc. Win32 is a trademark of Microsoft, Inc. OS/2 is a registered trademark of IBM Corporation. Other product names mentioned herein are used for identification purposes only, and may be trademarks of their respective companies.

The following copyright notices apply to software that accompanies this documentation:

Visual Smalltalk is furnished under a license and may not be used, copied, disclosed, and/or distributed except in accordance with the terms of said license. No class names, hierarchies, or protocols may be copied for implementation in other systems.This manual set and online system documentation copyright © 1999–2000 by Cincom Systems, Inc. All rights reserved. No part of it may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form without prior written consent from Cincom.

Cincom Systems, Inc.

55 Merchant Street

Cincinnati, Ohio 45246

Phone: (513) 612-2300

Fax: (513) 612-2000

World Wide Web: http://www.cincom.com

Contents

Chapter 1 The WorkbenchWorkbench Features ..............................................................10On-line Help ..........................................................................11

Workbench Help Menu (Windows) ............................11Workbench Help Menu (OS/2) ....................................12F1 Key Help ..................................................................13Information Area Help .................................................13

Mouse Basics (Windows) ......................................................14Mouse Basics (OS/2) .............................................................14Cursors ...................................................................................14Opening a Workbench ..........................................................15Saving a Part (PAR) ................................................................16Closing a Workbench ............................................................16Canceling Operations ............................................................17Launching an Application .....................................................17Part File Dialogs .....................................................................18

File Name ......................................................................18File List Pane .................................................................18Format ...........................................................................19Search Path ...................................................................19OK .................................................................................19Cancel ...........................................................................20Any File... ......................................................................20

Saving an Executable Part .....................................................20Saving an Executable (EXE) Application ..............................21Delivering an Executable Application ..................................21Batch Processing Parts ..........................................................22Creating a Customized Sign-on Dialog .................................23Generating Source Code from a Part ....................................23Setting the Workbench Grid ..................................................24Setting User Preferences ........................................................25

User name .....................................................................25Search path ...................................................................25Add... .............................................................................26Delete ............................................................................27Sequence... ....................................................................27Workbench default settings ..........................................28Workbench grid ............................................................28

Visual Smalltalk Enterprise Workbench User’s Guide iii

Contents

Link colors... .................................................................28Background colors... ....................................................29Mouse Buttons... (Windows) ........................................31OK .................................................................................31Apply .............................................................................31Cancel ............................................................................32

Generating a Textual Description of an Application ...........32Generating a Visual Description of an Application .............34

Chapter 2 The CatalogCatalog Features .....................................................................36On-line Help ..........................................................................37

Help for Existing Catalogs ............................................37Adding a Context-Sensitive Hint to a Catalog Page ....38

Opening a Catalog .................................................................38Selecting Parts in a Catalog ...................................................39Saving a Catalog .....................................................................39Closing a Catalog ...................................................................40Creating a New Catalog .........................................................40Adding a Part to a Catalog Page ...........................................40Arranging Parts on a Catalog Page .......................................41Deleting a Part from a Catalog ..............................................42Adding a Page to a Catalog ...................................................42Deleting a Page from a Catalog ............................................43Setting a Major Tab ................................................................43Setting a Minor Tab ................................................................45Deleting a Tab from a Page ..................................................46Setting the Size of a Tab ........................................................46Setting the Size of the Page Buttons .....................................47

Chapter 3 Manipulating PartsOn-line Help ..........................................................................50

Help for Existing Parts ..................................................50Adding Context-Sensitive Help to an Application Part 50

Undo and Redo ......................................................................52Canceling an Operation .........................................................52Visual Parts .............................................................................52Nonvisual Parts ......................................................................53Smalltalk Objects as Parts ......................................................53Parent and Child Parts ...........................................................54Selecting Parts in an Application ..........................................55Adding Parts to an Application .............................................57Replacing Parts in an Application .........................................63Deleting Parts from an Application .......................................66Moving Parts ..........................................................................67

iv Visual Smalltalk Enterprise Workbench User’s Guide

Copying Parts .........................................................................68Resizing Parts .........................................................................69Aligning Parts .........................................................................70Distributing Parts in an Application ......................................72Shrinking and Expanding Parts .............................................72

Chapter 4 Part PropertiesProperty Basics ......................................................................76Properties Dialog Overview ..................................................77Setting Properties for an Individual Part ..............................78Undo and Redo .....................................................................79Setting Properties for a Group of Parts ................................79Direct-Editing a Part ..............................................................80

Chapter 5 Events, Messages, and LinksProgramming with Links .......................................................83Links, Labels, and Connections ............................................84Link Handles ..........................................................................86Events .....................................................................................87Messages ................................................................................88Event Links .............................................................................89Argument Links ......................................................................90Result Links ............................................................................94

Operation ......................................................................96Scenarios ................................................................................96

Chapter 6 Programming with LinksLink Pop-up Menu .................................................................97Creating Links ........................................................................98Deleting a Link .................................................................... 103Replacing a Result Link ....................................................... 104Moving an Event or Message Connection .......................... 104Changing the Event that Fires an Event Link ..................... 105Changing the Message Sent by a Link ................................ 105Changing an Event Link’s Origin ........................................ 105Changing a Link’s Destination ............................................ 106Sequencing Event Links ...................................................... 107

Chapter 7 Displaying LinksLink Layout .......................................................................... 109

Overriding the Default Layout Setting for Creating a Link ....................................................... 110

Adding a Control Point while Creating a Link .......... 110Adding a Control Point after a Link is Created ......... 110Moving a Control Point .............................................. 111Deleting a Control Point ............................................ 111

Visual Smalltalk Enterprise Workbench User’s Guide v

Contents

Link Visibility .......................................................................111Displaying Links Connected to Selected Parts ..........111Displaying Specific Links Attached to a

Selected Part ...........................................................113Displaying All Links ....................................................114Hiding Links ................................................................115

Labels ....................................................................................115Showing Link Labels ...................................................115Hiding Labels ..............................................................116Moving Link Labels .....................................................117

Scenarios ..............................................................................117Adding and Removing Scenarios ...............................117Adding Links to and Removing Links from a

Scenario ..................................................................118Displaying Scenarios ..................................................118Renaming Scenarios ...................................................119Commenting a Scenario .............................................119Pairing Scenarios ........................................................120

Display Preferences for Links and Labels ...........................121Show Labels with Links ..............................................121Show Links with Selection .........................................121Orthogonal Link Creation ..........................................122Link Color ...................................................................122

Chapter 8 Constructing New Parts

Anatomy of a Part ................................................................125Reasons for Constructing New Parts ...................................127Part File Reuse Options .......................................................127

Ensemble Reuse Option .............................................128Packaged Parts ............................................................129

YesNo Part—External Interface ...........................................130To build the external interface of the YesNo part: ...131(Optional) To customize the YesNo part’s

Properties: ..............................................................132(Optional) To add the YesNo part to a Catalog: .......133To build an application that uses the YesNo part: ....133

YesNo Part—Internal Implementation ................................138To build the YesNo part’s user interface: ..................140To implement the YesNo part’s behavior: .................142

Defining an External Interface ............................................145External Interface Event and Message Syntax ...........147Exporting Events and Messages from a Part .............147

Browsing Nested Parts .........................................................148

vi Visual Smalltalk Enterprise Workbench User’s Guide

Browsing References to a Nested Part ............................... 148Browsing Implementors of a Nested Part .......................... 149

Chapter 9 User-Defined Messages and EventsWhat is PARTStalk? .............................................................. 151When to Extend the Interface of a Part with Scripts ......... 152

Adding New Functionality ......................................... 152Replacing Links .......................................................... 153

Adding a Message to a Part’s Interface ............................... 153Editing a User-Defined Method Definition ......................... 154Deleting a User-Defined Message ....................................... 155Adding an Event to a Part’s Interface ................................. 155Deleting an Event from a Part’s Interface .......................... 156Managing User-Defined Methods ....................................... 156Displaying User-Defined Methods for all Parts .................. 158Triggering a User-Defined Event ........................................ 159Using Part Names in User-Defined Methods ...................... 160

Restrictions on Use of Part Names ............................ 160Referencing Value Holders ........................................ 160Nested Parts ................................................................ 161

Printing Interface Reports ................................................... 161Printing an Interface Report for an Individual Part .. 162Printing an Interface Report for all Parts in a

Workbench ............................................................. 162

Chapter 10 Debugging an ApplicationDebugger Features .............................................................. 163

Single-Step Execution Area ........................................ 164Link Information Area ................................................ 165Trace Log Area ............................................................ 166Notation ...................................................................... 166

Launching the Debugger ..................................................... 167Setting Link Breakpoints ..................................................... 167Clearing Link Breakpoints ................................................... 170Debugging an Application .................................................. 171Changing Message Argument Values .................................. 173Trace Log ............................................................................. 175

Chapter 11 Revision SupportRepositories .......................................................................... 177Nested Parts and Part Accessors ......................................... 177Revision Support Features ................................................... 178

Visual Smalltalk Enterprise Workbench User’s Guide vii

Contents

Appendix A Menu and Toolbar Quick Reference ....................................... 181Catalog File Menu ................................................................182Workbench File Menu .........................................................183Workbench Selected Menu ..................................................184Workbench Edit Menu .........................................................185Workbench View Menu .......................................................187Workbench Test Menu .........................................................188Workbench Developer Menu ..............................................188Workbench Scenarios Menu ................................................189Workbench Help Menu (OS/2) ...........................................190Workbench Help Menu (Windows) ....................................191Link Pop-up Menu ...............................................................191Debugger Log Menu ............................................................193Part Interface Window Interface Menu ...............................193.Part Interface Window Script Menu ...................................194Part Interface Window Edit Menu .......................................194Part Interface Window Xref Menu .....................................195The Workbench Tool Bar ....................................................196

Appendix B Mouse Actions Quick Reference (Windows) ............................. 197Mouse Basics ........................................................................197Mouse Button Actions for Parts ..........................................197Mouse Button Actions for Links ..........................................198

Appendix C Mouse Actions Quick Reference (OS/2) .................................. 199Mouse Basics ........................................................................199Mouse Button Actions for Parts ..........................................199Mouse Button Actions for Links ..........................................200

Appendix D User Interface Parts ......................................................... 201

Appendix E Parts for Programming ...................................................... 211

Glossary 217

Index 221

viii Visual Smalltalk Enterprise Workbench User’s Guide

CHAPTER

1
The Workbench
Your PARTS Workbench environment contains three types of objects:

• workbenches—windows where you build applications

• parts—pre-built software components which you assemble into applications

• catalogs—notebooks containing collections of parts

You begin building a typical application by dragging parts from a catalog and dropping them onto the workbench background. This chapter explains topics that primarily affect the workbench itself:

• Workbench Features

• On-line Help

• Mouse Basics (Windows)

• Mouse Basics (OS/2)

• Opening a Workbench

• Saving a Part (PAR)

• Closing a Workbench

• Canceling Operations

• Launching an Application

The following topics are also covered, but you don’t necessarily need to know them to begin working with PARTS Workbench:

• Part File Dialogs

• Saving an Executable Part

• Saving an Executable (EXE) Application

• Delivering an Executable Application

• Batch Processing Parts

• Creating a Customized Sign-on Dialog

• Generating Source Code from a Part

See appendix A, Menu and Toolbar Quick Reference, for a summary of menu and toolbar operations for the Workbench.

See appendix B, Mouse Actions Quick Reference (Windows), or appendix C, Mouse Actions Quick Reference (OS/2), for a summary of mouse operations for the Workbench.

Visual Smalltalk Enterprise Workbench User’s Guide 9

The WorkbenchCHAPTER 1

• Setting the Workbench Grid

• Setting User Preferences

• Generating a Textual Description of an Application

• Generating a Visual Description of an Application

See chapter 2, The Catalog, for information on catalogs in general and an overview of the PARTS catalog. See chapter 3, Manipulating Parts, and chapter 4, Part Properties, for information on using parts.

Workbench FeaturesA workbench opens looking something like this:

The workbench has the following features:

1. Title Bar

Provides the control menu box (in Windows) or the system menu (in OS/2), the name of your application, and the minimize and maximize icons.

2. Menu Bar

The source of pull-down menus. For further information about the available menu commands, see appendix A, Menu and Toolbar Quick Reference.

❽ Information Area ➐ Hint (for object under cursor)

➎ Workbench Background

➍ Tool Bar

➊ Title Bar ➋ Menu Bar ➌ Scenarios

➏ Scroll Bars

10 Visual Smalltalk Enterprise Workbench User’s Guide

On-line Help

3. Scenarios

A drop-down list of the scenarios defined for your application; the default scenario of “All Links” is automatically created for you. For further information about scenarios, see chapter 7, Displaying Links.

4. Tool Bar

A palette of buttons that provides menu-command shortcuts. For further information about these tools, see appendix A, Menu and Toolbar Quick Reference.

5. Workbench Background

This is where you edit an existing application or create a new one.

6. Scroll bars

If any parts in the workbench are not visible, horizontal and/or vertical scroll bars are automatically created.

7. Hint

Brief description of the object or menu item under the cursor.

8. Information Area

The area at the bottom of the workbench window that displays hints about the object under the cursor.

On-line HelpThere is menu help and two kinds of context sensitive help.

Workbench Help Menu (Windows)You can choose the on-line help system’s table of contents and index from the Help menu. This menu also gives you access to the on-line tutorial, instructions for using on-line help, and help for the sample applications.

Help table of contents:

> Choose Help/Contents from the workbench menu bar.

Help index:

> Choose Help/Search for Help on... from the workbench menu bar.



Instructions on using Windows Help:

> Choose Help/How to Use Help from the workbench menu bar.

On-line tutorial:

> Choose Help/Tutorial from the workbench menu bar.

Sample application help and catalog:

> Choose Help/Samples from the workbench menu bar.

This command opens both a help window and a Samples catalog which contains the sample parts.

Information about Visual Smalltalk including the version number:

> Choose Help/About Visual Smalltalk... from the workbench menu bar.

Workbench Help Menu (OS/2)You can choose the on-line help system’s table of contents and index from the Help menu. This menu also gives you access to the on-line tutorial, instructions for using on-line help, and help for the sample applications.

Help index:

> Choose Help/Help index from the workbench menu bar.

Help Table of Contents:

> Choose Help/General help.

Instructions on using OS/2 Help:

> Choose Help/Using help.

On-line tutorial:

> Choose Help/Tutorial from the workbench menu bar.

Sample application help and catalog:

> Choose Help/Samples from the workbench menu bar.

This command opens both a help window and a Samples catalog which contains the sample parts.

Information on Keyboard Shortcuts:

> Choose Help/Keys help from the workbench menu bar.


On-line Help

Information about Visual Smalltalk including the version number:

> Choose Help/Product information from the workbench menu bar.

F1 Key HelpTo view help for individual parts and menu commands:

1 Select the part or menu item for which you want help.

You must continue pressing the mouse button to keep menu items highlighted.

2 Press F1.

A help window explaining the selected item is displayed.

Information Area HelpWhen information area hints are enabled (the default), a brief message is displayed at the bottom of the workbench that explains objects under the cursor. For example, you can point to each of the buttons in the toolbar near the top of the workbench to get a brief description of their function.

To enable or disable the information area for the current session:

> Choose View/Show hints from the menu bar at the top of the workbench.

The Show hints menu item is a toggle – if it has a check mark in front of it, information area hints are enabled. Choosing it again disables information area hints and removes the check mark. See Setting User Preferences later in this chapter for information on changing the default setting for all workbenches.

To change the hint for the current application:

1 Double-click on the application part (the workbench background).

An application Properties dialog is displayed. Each workbench background represents a separate application. See chapter 3, Manipulating Parts, for more information on application parts and Properties dialogs.

2 In the entry field labeled Hint:, enter text describing the contents of the workbench and then click the OK button.

The new hint is displayed when you move the cursor over the application part.



Mouse Basics (Windows)A standard mouse has two buttons. Button 1, the left button, is used for all click, double-click and drag operations unless otherwise specified. If you are unfamiliar with the terms click, double-click, and drag, please refer to your operating system’s documentation. See appendix B, Mouse Actions Quick Reference (Windows), for more information about mouse operations.

Mouse Basics (OS/2)A standard mouse has two buttons. Button 1, the left button, is used for all click and double-click operations unless otherwise specified. Button 2 is used for all drag operations unless otherwise specified. If you are unfamiliar with the terms click, double-click, and drag, please refer to your operating system’s documentation. See appendix C, Mouse Actions Quick Reference (OS/2), for more information about mouse operations.

CursorsPARTS Workbench uses different cursor shapes to visually indicate system status. For example, the hour glass (Windows) or clock (OS/2) cursor indicates that a process is taking place such as when a file is being read. The cursor also takes on the appearance of the part’s icon when one is being copied from the catalog.

Here are some of the common cursors:

Shape Indicates

arrow pointing to upper left normal

clock system is busy (Windows)

hour glass system is busy (OS/2)

I-beam text entry position

double-headed arrow resizing


Opening a Workbench

Opening a WorkbenchThe first workbench is opened from the Visual Smalltalk Transcript window. You can then open additional workbenches from either the Transcript window or any workbench, to create additional applications or edit existing applications.

To open an empty workbench, perform one of the following steps:

> From the Visual Smalltalk Transcript window, choose Smalltalk/New Workbench.

or

> From any workbench’s menu bar, choose File/New or Developer/New Workbench.

To open a workbench for an existing application, perform one of the following steps:

> Choose File/Open... from any workbench’s menu bar.

An Open Part dialog is displayed. Use this dialog to select a PAR file and click the OK button. See Part File Dialogs for more information on using this dialog.

When you click the OK button in the dialog, a workbench window is opened on the application.

or

> Choose File/Replace from the workbench menu bar.

A Replace Part dialog is displayed. Use this dialog to select a PAR file and click the OK button. The contents of the current workbench are replaced with the application that you have selected. See Part File Dialogs for more information on using this dialog. This option is especially useful when you only have one workbench open. Closing all workbenches closes PARTS Workbench.

or

international “No” symbol not a valid place to place the current part (Windows)

Minus sign in a black circle not a valid place to place the current part (OS/2)

Shape Indicates



> Double-click on a file which has a PAR file extension.

You must add the directory containing your PARTS Workbench executable files to the PATH variable in your AUTOEXEC.BAT file.

or

> Double-click on a part icon in a catalog.

Do this if you want to view or modify the part that appears in the catalog. See chapter 2, The Catalog, for more information on modifying catalogs.

Saving a Part (PAR)The part (PAR) format can be reopened in the workbench and edited. You will use this default format throughout the development of your part.

To save a part using the current file name:

> Choose File/Save from the workbench menu.

To save a part to a new filename:

1 Choose File/Save as... from the workbench menu.

A Save Part As dialog is displayed. See Part File Dialogs for more information on using this dialog.

2 Select a destination directory.

Use the default PAR format.

3 Click the OK button.

Closing a Workbench> Double-click on the workbench’s control menu.

or

> Choose File/Close from the workbench’s menu bar.


Launching an Application

Canceling OperationsYou can cancel menus, dialogs, and many in-progress operations by pressing the Esc key. If the operation is already complete, the Esc key has no effect.

Launching an ApplicationWhen you are ready to test your application, you simply launch it; no time consuming compilation is required. When you launch it, the application part’s open event is triggered.

A typical application has its open event connected to the open message of a window containing your application’s user interface. You must link the application’s open event to some message if you intend to launch the application directly from the workbench or as a stand-alone EXE. See chapter 5, Events, Messages, and Links, for more information on these topics.

A launched application is independent of the parts in the workbench. Changes to your application in the workbench are not reflected in a launched application. Also, changes to the launched application, entering data in an entry field for example, do not affect the contents of the workbench. If you edit your application in the workbench, you must launch a new copy of the application in order to see the effect of your changes.

To Launch a workbench application, perform one of the following steps:

> Choose Test/Launch from the workbench menu bar.

or

> Click on the toolbar’s Launch button.

See chapter 10, Debugging an Application, for information on launching a workbench application in debug mode.



Part File DialogsThe Part File dialogs (for example, Save Part As, Open Part, Replace Part, etc.) replace the standard Windows or OS/2 File Dialog for most file operations in PARTS Workbench. The Part File dialogs provide you with a view of the directories that are included in the PARTS Workbench search path. You can access a standard file dialog by clicking on the Any File... button.

NOTE: Parts with their reuse option set to Linked that are referenced by nested parts must be in a directory that is included in your PARTS Workbench search path. If the part is not, PARTS Workbench will be unable to find the linked part; a warning dialog is displayed and the containing part is imported without the linked part. See the Nested Part chapter in the Part Reference for more information on the linked reuse option.

File NameEnter a file name or a pattern to filter the file names displayed in the list pane below this entry field.

File List PaneSelect a file name.


Part File Dialogs

Format(Windows) Combines the functions of the File Type and Format entry fields in the standard Windows File Dialog.

Select the extension identifying the desired file format.

• The PAR extension identifies an editable PARTS Workbench application. See Saving a Part (PAR) for more information.

• The EXE extension identifies a stand-alone executable application. This format is not editable, so you should also save a copy of the file in either the PAR or CLS format. See Saving an Executable (EXE) Application for more information.

• The PAX extension identifies an executable part. This format is not editable, so you should also save a copy of the file in the PAR or CLS format. See Saving an Executable Part for more information.

• The CLS format is the portable Smalltalk source code representation of a PARTS Workbench application. See Generating Source Code from a Part for more information.

Search PathSelect the pathname of the directory you want to examine. This list pane only includes directories that are part of your PARTS Workbench search path. If the directory you want to search is not listed here, you have two choices:

1. Close the dialog and add the desired directory to your PARTS Workbench search path (See Setting User Preferences).

2. Open a standard File Dialog by clicking on the Any File... button in the dialog.

If your application contains linked nested parts, the nested parts must be in a directory on your PARTS Workbench search path. See the Nested Part chapter in the Part Reference for more information.

OKOpens or saves to the selected file depending on the purpose of the dialog.



CancelCloses the dialog without completing the operation.

Any File...Opens a standard File dialog giving you access to directories that aren’t part of your PARTS Workbench search path.

If your application contains linked nested parts, the nested parts must be in a directory on your PARTS Workbench search path.

Saving an Executable PartAn executable part (PAX) is similar to an executable application (EXE) in that the workbench-only editing information is stripped away, execution optimizations are installed, and all nested parts are resolved. Unlike a stand-alone EXE, however, a PAX cannot be executed directly from the host operating system environment. (Technically, it lacks the stub program needed to execute as a program in the host environment.)

The PAX format allows you to deliver optimized executable parts for use with the Part Accessor. A PAX cannot be edited in a PARTS Workbench but it can be added to a catalog. See the Part Accessor chapter in the Part Reference for more information.

To save an executable part:

1 Choose File/Save as... from the workbench menu.

A Save Part As dialog is displayed. See Part File Dialogs for more information on using this dialog.

2 Select a destination directory.

Use the default PAR format.

3 Select the Executable Part (PAX) format from the Format drop-down list.



Delivering an Executable Application

Saving an Executable (EXE) ApplicationWhen you are ready to deliver a PARTS application, you save the application as an executable (EXE) file. The EXE format produces a file that you can run independently of the workbench. The EXE format is not editable—if you choose this format, you should also save a separate copy of the file in either the PAR or CLS format. The EXE will have the same icon as your application part’s icon.

To save an executable application:

1 Choose File/Save as... from the workbench menu bar.

A Save Part As dialog is displayed.

2 Choose a directory and name the application.

3 Choose Executable (EXE) from the Format drop-down list.

4 Click on the OK button.

Delivering an Executable ApplicationWhen you are ready to deliver your executable application, you must provide:

1. your EXE file

2. the PARTS Workbench runtime files

The current list of required files is in the file DELIVERY.TXT located in the DOC subdirectory of your PARTS Workbench installation directory. DELIVERY.TXT also includes specific instructions on installing a stand-alone application and its associated runtime files.

3. any other files needed to run your application

These include any files you require to support new parts used in your application or which are called from your application (for example, by means of a DLL accessor part to wrap a DLL).

4. (OPTIONAL) a customized sign-on dialog. See Creating a Customized Sign-on Dialog for more information.



Batch Processing PartsPARTS Workbench includes a tool called the Part File Converter that allows you convert groups of parts from one format to another without having to open each one separately. You can also use this tool to upgrade parts by opening them and then saving them back to the same file. The tool is packaged as a PAR file and it is stored in the SYSTEM\PARTS subdirectory of your installation directory in a file called PCNVRTW.PAR (Windows) or PCNVRTO.PAR (OS/2).

To batch process parts:

1 From a workbench menu bar, choose the File/Open... command.

2 Use the dialog to select PCNVRTW.PAR (Windows) or PCNVRTO.PAR (OS/2) and then click OK.

3 Launch the application.

4 In the File spec entry field, enter a file pattern.

A pattern could be a specific file name or a more general pattern such as *.*.

5 From the Part File Converter’s menu bar, choose the Files/Change source directory... command.

6 Select a directory that contains the files that you want to convert and click OK.

Files in the selected directory that match the file spec are displayed in the list pane.

7 Select the files that you want to convert from the list pane.

You can select all of the files by choosing Files/Select all files.

8 From the Part File Converter’s menu bar, choose the Files/Change destination directory... command.

9 Select where you want to save the converted parts and click OK.

10 Check the Confirm to overwrite checkbox if you want the Part File Converter to overwrite files with matching names.

11 Select a file type from the Destination file type drop-down list.

12 You can use the additional check boxes and entry fields to set the Version and Manufacturer attributes of the parts.

13 From the menu bar, choose Files/Convert selected files.

Status messages are displayed in the text pane.


Generating Source Code from a Part

Creating a Customized Sign-on DialogYou can create a customized sign-on dialog for your executable (EXE) application to display when it is executed. The following Cincom copyright notice must be included in the sign-on dialog of any application developed using PARTS Workbench:

Portions copyright (c) Cincom Systems, Inc. 2000,All rights reserved.

To create a customi zed sign-on dialog for your stand-alone EXE:

1 Create a BMP file with the same filename as your EXE.

Bitmap files in OS/2 and Microsoft Windows bitmap formats are supported.

2 Install the bitmap file in the same directory as the EXE file.

For example, if you create a stand-alone EXE file named PARTSAPP.EXE, you would create a bitmap file named PARTSAPP.BMP for its sign-on dialog and install both files in the same directory.

Generating Source Code from a PartA CLS file contains the portable Smalltalk source code representation of a PARTS Workbench application. The source code representation is printable and readable using any text editor. This code can be managed by version control systems, such as TeamV®, and it addresses a number of portability issues.

You can use the CLS format to migrate parts across platforms. The source code describes the application in terms which are platform neutral. Thus, objects whose physical representations and internal implementations may vary greatly from platform to platform are specified in a high level, abstract, and portable way.

Objects that are managed by the operating system, like colors and fonts, are specified so that the closest matching object will be generated if an exact match is not available. Bitmaps and icons are also described in platform neutral terms.

When you save an application as source code, PARTS Workbench actually generates two files:

• A CLS file which contains Smalltalk source code

• A CRS file which contains binary data such as bitmaps and icons



These two files should be stored and managed as a unit, because both files are required to reconstruct the part.

Setting the Workbench GridThe grid makes it easier to align parts by hand. See chapter 3, Manipulating Parts, for other alignment tools.

The grid is specified in number of pixels for both the X and Y axis. In both dimensions the number represents the smallest increment in pixels that you can move a part.

At the default setting of X=1, Y=1, the grid is effectively turned off. At a setting of X=100, Y=100, you can only move parts in 100 pixel increments.

To change the grid setting for the current workbench:

1 Choose the View/Set grid... command.

A Set Grid dialog is displayed.

2 Enter X and Y values.


See Setting User Preferences for instructions on changing the grid’s default setting for all workbenches.


Setting User Preferences

Setting User PreferencesThe Settings window allows you to customize certain settings for all workbenches.

To open the Settings window:

> Choose File/Settings... from a workbench menu bar.

User nameEnter the default name of the user that appears in the Properties dialog for each application. To view the Properties dialog for an application, double-click on the workbench background.

Search pathA list pane containing an ordered list of directories that are included in the PARTS Workbench search path. You can modify the search path with the Add..., Delete, and Sequence... buttons.

The PARTS Workbench search path is used by the Part File dialogs for opening, importing and saving parts. See Part File Dialogs for more information on the Part File dialogs.

The search path is also used to locate files referenced by linked nested parts, launch pads and part accessors during development and to locate files referenced by part accessors at runtime. Files referenced by these parts must be stored in a directory located on the PARTS Workbench search path.



At runtime, the default PARTS Workbench search path is the current working directory (usually the directory from which your deployed application is launched). You can replace the default search path by including a PARTS.INI file in the deployed application’s current working directory. This PARTS.INI file only needs to include search path information; the PARTS.INI file in your installation directory contains other workbench settings that do not affect executable files.

You can create a PARTS.INI file with any text editor. It must contain the statement “searchPath =” followed by the directories in the search path separated by semicolons. The example below shows a search path consisting of two directories: 1) partsapp1 which is located on the same drive as your deployed application 2) partsapp2 which is located on the D drive.

searchPath = partsapp1;d:\partsapp2;

Since the part accessor only references file names rather than complete path names, you can create the PARTS.INI file for your deployed application at installation giving your clients the ability to customize file installation to their local environment.

See chapter 8, Constructing New Parts, later in this document and see the Nested Part chapter in the Part Reference for more information on nested parts. See the Part Accessor and Launch Pad chapters in the Part Reference for more information on these related parts.

Add...Opens a Select Directory dialog which prompts you for a new pathname to place at the beginning of the PARTS Workbench search path list.

To add a directory to the PARTS Workbench search path:

1 Choose File/Settings from a workbench menu bar.

A Settings window is displayed.



2 Click on the Add... button.

A Select Directory dialog is displayed.

3 Select a directory and click the OK button.

The new directory is added to the beginning of the search path. When the workbench looks for a nested part, it uses the first one it finds. You can reorder the search path with the Sequence... button.

4 In the Settings window, click OK.

DeleteDeletes the selected directory from the Search path list.

Sequence...Opens a Sequence Directories dialog which allows you change the order of the directories in the PARTS Workbench search path. You reorder the list by dragging any of the path names to a different position in the list.

To change the sequence of the PARTS Workbench search path:





2 Click on the Sequence... button.

A Sequence Directories dialog is displayed.

3 Drag the directory names to the desired positions.



Workbench default settingsThis group of check boxes specifies the default toggle settings for the following View menu commands: Show hints, Show labels with links, Show links with selection, and Orthogonal link creation. See On-line Help for more information on hints. See chapter 7, Displaying Links, for more information on displaying links.

Workbench gridEntry fields containing the default horizontal and vertical grid settings. The grid settings specify the smallest increment by which you can move a part in the workbench. The default setting of 1,1 is equivalent to turning the grid off. Higher settings are useful for aligning parts.

Link colors...Opens a PARTS Link Color Settings window which allows you to specify the colors for different types of links. See chapter 7, Displaying Links, for more information on link colors.

To change the default colors for different types of links:





2 Click on the Link colors... button.

A Link Color Settings window is displayed.

3 Select the desired color from each list pane.

You can preview the result of your selections without closing the window by clicking on the Apply button. Clicking the Reset button restores the current settings. Clicking the Defaults button restores the default settings.


5 In the Settings window, Click OK.

Background colors...Opens a Background Color Settings window which allows you to change the background colors for link labels, the workbench, and the catalog. On OS/2, you can also change the background colors of the workbench and the catalog by dragging a color from a palette.

To change the default background colors of workbenches, catalogs and link labels:





2 Click on the Background colors... button.

A Background Color Settings window is displayed.

3 Select the desired color from each list pane.

You can preview the result of your selections without closing the window by clicking on the Apply button. Clicking on the Reset button restores the current settings. Clicking on the Defaults button restores the default settings.


5 In the Settings window, Click OK.

(OS/2) To set the background color of a workbench or a catalog using a Color Palette:

1 Double-click on the OS/2 System icon.

2 Double-click on System Setup.

3 Double-click on Color Palette.

4 Drag a color from the palette to the workbench or the catalog.

The color of the workbench or catalog will change to reflect the new color. You can use any color palette as the source for a new color.



Mouse Buttons... (Windows) Opens a Mouse Button Settings window which allows you to specify the button to be used for drag operations and the button to be used for creating links. See chapter 6, Programming with Links for more information on creating links.

To change the mouse button settings:



2 Click on the Mouse Buttons... button.

A Mouse Button Settings window is displayed.

The Move/Resize group pane allows you to set the mouse button that you wish to use for operations that involve dragging a part. The Create Link group pane allows you to set the mouse button that you wish to use for creating links. You can’t choose the same mouse button for both Move/Resize and Create Link; selecting an option in one group pane automatically resets the option in the other group pane.

3 Choose a setting for either the Move/Resize operation or the Create Link operation.


5 In the Settings window, click the OK button.

OKApplies any changes and closes the Settings window.

ApplyMakes the specified changes, but does not close the Settings window.



CancelCloses the Settings window without applying any further changes.

Generating a Textual Descriptionof an Application

You can print a textual description of your application or preview the description on-screen. The print-out includes information from the application’s Properties dialog and a textual description of the links and parts that make up your application. See chapter 10, Debugging an Application, for information on the notation used to describe links between parts.

Figure 1-1: Application as Text Description

- Part name: 'AlarmButton' Title: 'Untitled' Author: 'Anonymous' Version: '1.0' Hint: 'Sounds an alarm when you press the Alert

button.' Help file: 'YourFile.hlp' Help topic: 'YourTopic' Part file reuse option: Packaged part (linked) Description: <none> Link external "open" message to Window1 "open" message

Application in Workbench


Generating a Textual Description of an Application

- Part name: 'Speaker1' Frequency: 800 Duration: 200

- Part name: 'Window1' Window label: 'Alarm' Border: Size border Title bar: yes Menu bar: yes Control menu: yes Minimize button: yes Maximize button: yes Font: System 10 bold Framing properties:

left: right of parent's left by 2100 twips right: right of window left by 4320 twips top: down from parent's top by 1755 twips bottom: down from window top by 3600 twips Initial Position: Relative to the display Initial Visibility: Visible Initial Size: Normal Tab Order: * indicates a tab stop * PushButton1

- Part name: 'PushButton1'

Label: 'Alert' Default button: no Font: MS Sans Serif 8 bold Framing properties: left: right of parent's left by 1500 twips right: right of window left by 1080 twips top: down from parent's top by 1050 twips bottom: down from window top by 420 twips Link PushButton1 "clicked" event to Speaker1 "alarm" message

NOTE: A “twip” as referenced above is equal to 1/1440th of an inch.



To preview your application’s description on-screen:

> Choose File/Print/Preview from the workbench menu bar.

PARTS Workbench opens a text editing window containing the description of your application.

To print a description of your application:

> Choose File/Print/Send to printer from the workbench menu bar.

PARTS Workbench prints the description on your default printer.

Generating a Visual Descriptionof an Application

You may find it useful to create visual descriptions of your application with images captured from your screen. The simple utility CAPTURE.PAR allows you to capture a specified portion of the screen and store it in the clipboard. You can then paste the captured bitmap into a word processing or graphics program.

To create a visual description of an application:

1 Launch the CAPTURE.PAR application.

This application is located in the SAMPLE subdirectory of your Visual Smalltalk or Visual Smalltalk Enterprise directory.

2 Click on the Capture button.

3 Drag the cursor to select an area to capture.

When you release the mouse button, the selected area is copied into the clipboard. You can now switch to a word processing or graphics application and paste the bitmap into that application.


CHAPTER

2
The Catalog
Catalogs are notebooks used to organize pre-built parts and are one of your primary sources for parts as you develop an application. They float on top of the active workbench to make them more easily accessible.

You begin building a typical application by dragging parts from a Catalog and dropping them onto the workbench.

This chapter explains how to use Catalogs and introduces the PARTS Catalog. The following topics are covered:

• Catalog Features

• On-line Help

• Opening a Catalog

• Selecting Parts in a Catalog

• Saving a Catalog

• Closing a Catalog

The following topics are also covered, but you don’t necessarily need to know them to begin working with PARTS Workbench:

• Creating a New Catalog

• Adding a Part to a Catalog Page

• Arranging Parts on a Catalog Page

• Deleting a Part from a Catalog

• Adding a Page to a Catalog

• Deleting a Page from a Catalog

• Setting a Major Tab

• Setting a Minor Tab

• Deleting a Tab from a Page

• Setting the Size of a Tab

• Setting the Size of the Page Buttons

See appendix A, Menu and Toolbar Quick Reference, for a summary of menu operations for the Catalog.


The CatalogCHAPTER 2

Catalog FeaturesThe standard PARTS Catalog is displayed when you launch PARTS Workbench. It is located in SYSTEM\PARTS.CAT in your PARTS Workbench installation directory. Modifying your catalog is easy and you are encouraged to customize one or more catalogs to meet your needs.

Notice the following:

1. Title Bar

Provides the control menu box (in Windows) or the system menu (in OS/2), the name of the catalog (without file extensions), and the minimize icon.

2. Catalog Page

A catalog consists of one or more pages. Each page holds one or more parts.

3. Section/Page Number

Number of the currently displayed page. The format of the number is major section/page number within section.

4. Minor Tab

Marks a page within a category. Clicking on a minor tab opens the catalog to that page.

➊ Title Bar

➋Catalog Page

➌ Section/Page Number

➍ Minor Tab

➐ Major Tab

➏ Page Forward/Backward Buttons

➎ Catalog File Menu Button


On-line Help

5. Catalog File Menu Button

Pops up the catalog’s File menu. (For information about the commands on this menu, see appendix A, Menu and Toolbar Quick Reference.)

TIP: You can also pop-up the catalog File menu by clicking on the catalog with mouse button 2.

6. Page Forward/Backward

Clicking on one of these buttons flips the catalog page either forward or backward.

7. Major Tab

Marks the first page of a category. Clicking on a major tab opens the catalog to that page.

On-line HelpThere is menu help and two kinds of context sensitive help.

Help for Existing CatalogsFor information on catalog-related topics, you can choose the on-line help system’s table of contents and index from the workbench Help menu. See chapter 1, The Workbench, for more information on the Help system.

The workbench’s information area will display a brief hint about the area of the catalog or the part in the catalog which is under the cursor. See chapter 1, The Workbench, for more on the information area.

If you select an object or menu item and then press the F1 key, a help window explaining the selected object or menu item is displayed.



Adding a Context-Sensitive Hint to a Catalog PageYou can add a brief hint to any catalog page. The hint appears in the topmost workbench’s information area when you place the cursor over the catalog page.

1 Open the catalog to the desired page.

2 Click on the catalog’s File... button.

The catalog File menu is displayed.

3 Choose the Describe Page... command.

A prompter dialog is displayed. If the page already has a description, it is displayed in the prompter dialog’s entry field.

4 Enter a description of the page and click OK.

5 Move the cursor over the page to display the new hint.

Opening a CatalogYou may open as many different catalogs as you like. All open catalogs float on top of the active workbench. By convention, catalog files have a CAT extension but this is not required.

To open a catalog, perform one of the following procedures:

1 Choose View/Open catalog... from a workbench menu bar.

An Open catalog dialog (a type of Part File dialog) is displayed. See chapter 1, The Workbench, for more information on Part File dialogs.

2 Use the Open Part dialog to locate a catalog and click on OK.

or

1 Click on the File... button of an already-open catalog.


2 Choose the Open... command.

An Open Catalog dialog is displayed.

3 Use the Open Catalog dialog to locate a catalog and click on OK, or double-click on a catalog file.

To enable this feature, you must define a program association for catalog (CAT) files and ensure that the PATH variable in your AUTOEXEC.BAT file contains the directory


Saving a Catalog

in which you have installed your PARTS Workbench executable files.

Selecting Parts in a Catalog> Click on a part.

You can only select one part at a time in a catalog. The selected part is shown in reverse video.

Saving a CatalogYou can save changes to an existing catalog or create a new catalog based on the existing one.

To save changes to an existing catalog or to save a new catalog:



2 Choose Save.

If the current catalog has not been saved to a file yet, a Save Catalog dialog (a type of Part File dialog) is displayed. Use this dialog to choose a directory and click the OK button. See chapter 1, The Workbench, for more information on Part File dialogs.

To save an existing catalog to a different file:



2 Choose the Save as... command.

A Save Catalog As dialog (a type of Part File dialog) is displayed. See chapter 1, The Workbench, for more information on Part File dialogs.

3 Name the new file, choose a directory, and click on the OK button.

Notice that the name of the file (minus the file extension) is displayed in the catalog’s title bar.

Unselected part in Catalog

Selected part in Catalog



Closing a Catalog> Double-click on the control-menu box.

All catalogs are closed automatically when you close the last open workbench.

Creating a New CatalogYou can create custom catalogs to suit your needs. You might create a catalog that contains a subset of the standard parts or you might create one that contains your own custom parts.

1 Click on the File... button of an already open catalog.


2 Choose New.

An empty untitled catalog is displayed. By default the new catalog has one page numbered 0.1. Subsequent pages will be numbered 0.2, 0.3, etc. until you add a major tab to one of the pages.

If you want the catalog to begin with page 1.1, you must add a major tab to the first page of the catalog. See Setting a Major Tab for more information.

You name the new catalog by saving it. The name displayed in the title bar of the catalog is the file name minus any file extension.

Adding a Part to a Catalog PageYou can add a part to a catalog from another catalog or from a file.

To add a part to a catalog page from another catalog:

1 Select a part in the source catalog.

Only parts that have been copied or cut from a catalog can be pasted into a catalog. You cannot cut or copy a part from a workbench and paste it into a catalog.

2 Click on the source catalog’s File... button.


3 Choose either Cut part or Copy part.


Arranging Parts on a Catalog Page

4 Select the catalog to which you want to add the part and turn to the destination page.

5 Click on the target catalog’s File... button.

6 Choose Paste part.

The part’s icon is displayed on the page. You can position the part either with the mouse or with a menu command. See Arranging Parts on a Catalog Page for more information.

To add a part to a catalog from a part file:

1 Select the catalog page to which you want to add the part.



3 Choose the Insert part file... command.

An Insert Part dialog (a type of Part File dialog) is displayed. See chapter 1, The Workbench, for more information on Part File dialogs.

4 Use the Insert Part dialog to locate a part and click the OK button.

The new part’s icon is displayed on the current catalog page. You can position the part either with the mouse or with a menu command. See Arranging Parts on a Catalog Page for more information.

Arranging Parts on a Catalog PageAs you add parts, delete parts, and resize catalogs, you will want to rearrange the part icons to maintain a neat appearance. You can do this manually by simply dragging the icons or you can do it automatically with the catalog File menu’s Arrange Icons command.

This command arranges all part icons in the minimum amount of space. If enough room is available, icons are placed left to right and then top to bottom. If, however, the catalog is only tall enough for a single row, or only wide enough for a single column, the command will place the icons in a single row or column.



To arrange parts on a catalog page:



2 Choose Arrange icons/For current page or Arrange icons/For all pages.

If the icons overlap, you can resize the catalog with the catalog File menu’s Size command and then repeat the Arrange icons command.

Deleting a Part from a Catalog1 Select the part that you want to delete.



3 Choose Cut part.

The part is deleted from the catalog and a copy is placed in the clipboard.

Adding a Page to a CatalogNew pages are inserted after the current page.



2 Choose Insert new page.

The new page is inserted and displayed. The new page is automatically numbered as the next page in the current section. For example, if page 1.1 was the current page when you chose the Insert new page command, the new page will be 1.2.

You can change the default numbering by designating the page as the start of a new section. See Setting a Major Tab for more information on creating a new section.


Setting a Major Tab

Deleting a Page from a Catalog1 Open the catalog to the page you want to delete.



3 Choose Delete page.

A confirmation dialog is displayed.

4 Click the Yes button.

The current page is deleted and the remaining pages are automatically renumbered. If you delete a page with a major tab, the pages following the deleted page will be numbered as part of the previous section.

If the first page of the catalog has a major tab and you delete that page, the first section of the catalog becomes section 0 with page numbers 0.1, 0.2, etc.

Setting a Major TabTabs are used to help organize catalogs. Major tabs appear on the right side of their assigned page and are vertically staggered according to the position of the page in the catalog. Major tabs for lower numbered sections appear above tabs for higher numbered sections.

Tabs can be labeled with either text or a bitmap graphic. Catalog tabs are not resizeable, however, so the number of characters you can use as a tab label is limited.

If there is not enough room to display all of the major tabs, a pair of double-headed arrows is added to the Catalog: one above the first tab and one below the last tab. These allow you to scroll through the major tabs.

Major tabs affect page numbering. Adding a major tab to a page causes the first part of the page number (for example, the 2 in 2.1) to increment by one indicating a new section. The second part of the page number is reset to one indicating that this is the first page of the section.

Pages in a catalog that don’t have any major tabs and pages that come before the first major tab in a catalog have a section number of 0.



There can only be one tab, major or minor, per page. If you add a major tab to a page that already has one, the existing major tab is replaced. If you attempt to add a major tab to a page that has a minor tab, a confirmation dialog is displayed asking you if you want to proceed.

To add a major tab with a text label to a catalog page:




3 Choose the Set major tab/Text... command.

A prompter dialog is displayed requesting the text for the new tab.

4 Enter the major tab text in the prompter and click the OK button.

The new major tab is added to the right side of the page and subsequent pages are automatically renumbered to reflect the new section.

To add a major tab with a bitmap label to a catalog page:




3 Choose the Set major tab/Bitmap file... command.

A Select Bitmap File dialog (a type of Part File dialog) is displayed. See chapter 1, The Workbench, for more information on Part File dialogs.

4 Select a bitmap file and click the OK button.

The new major tab is added to the right side of the page and subsequent pages are automatically renumbered to reflect the new section.


Setting a Minor Tab

Setting a Minor TabTabs are used to help organize catalogs. Minor tabs appear on the bottom of their assigned page and are horizontally staggered according to the position of the page in the catalog. Minor tabs for lower numbered pages appear to the left of minor tabs for higher numbered pages.

Tabs can be labeled with either text or a bitmap graphic. Catalog tabs are not resizeable, however, so the number of characters you can use as a tab label is limited.

If there is not enough room to display all of the minor tabs, a pair of double-headed arrows is added to the catalog: one to the left of the first tab and one to the right of the last tab. These allow you to scroll through the minor tabs.

There can only be one tab, major or minor, per page. If you add a minor tab to a page that already has one, the existing minor tab is replaced. If you attempt to add a minor tab to a page that has a major tab, a confirmation dialog is displayed asking you if you wish to proceed.

Minor tabs do not affect page numbering.

To add a minor tab with a text label to a catalog page:




3 Choose the Set minor tab/Text... command.

A prompter dialog is displayed requesting the text for the new tab.

4 Enter the minor tab text in the prompter and click the OK button.

The new minor tab is added to the bottom of the page.

To add a minor tab with a bitmap label to a catalog page:


2 Click on a catalog’s File... button.


3 Choose the Set minor tab/Bitmap file... command.

A Select Bitmap File dialog (a type of Part File dialog) is displayed. See chapter 1, The Workbench, for more information on Part File dialogs.



4 Select a bitmap file and click the OK button.

The new minor tab is added to the bottom of the page.

Deleting a Tab from a PageDeleting a major tab causes the page numbers of subsequent pages to change in order to reflect the loss of a section. Deleting a minor tab from a page has no effect on page numbering.

1 Click on the tab that you want to delete.

This insures that the catalog is opened to the appropriate page.



3 Choose Discard tab.

Setting the Size of a Tab1 Click on the catalog’s File... button.


2 Choose the Set size/Major tabs... or the Set size/Minor tabs... command.

A prompter requesting the new extent of the tab is displayed. The required value is an instance of the Point class which you create with an expression of the following form:

x @ y

where x is the new width of the tab in pixels and y is the new height of the tab in pixels.

3 Enter a new value and click on the OK button.

The tabs are resized to reflect the new setting.


Setting the Size of the Page Buttons

Setting the Size of the Page Buttons1 Click on the catalog’s File... button.


2 Choose the Set size/Page buttons... command.

A prompter requesting the new extent of the buttons is displayed. The required value is an instance of the Point class which you create with an expression of the following form:

x @ y

where x is the new width of each button in pixels and y is the new height of each button in pixels. You cannot set the size of the buttons individually.

3 Enter a new value and click on the OK button.

The buttons are resized to reflect the new setting.


CHAPTER

3
Manipulating Parts
You build your applications with reusable, customizable parts. Each part is the equivalent of thousands of lines of programming code. Many are provided for you in the PARTS catalog, and you can add to that total by combining existing parts into new parts, customizing parts and building entirely new parts.

This chapter explains different categories of parts and techniques for manipulating them. If you’re already familiar with the standard mouse and menu operations of your operating system, you may be able to figure out most part operations through a little experimentation.

The following topics are discussed:

• On-line Help

• Undo and Redo

• Canceling an Operation

• Visual Parts

• Nonvisual Parts

• Smalltalk Objects as Parts

• Parent and Child Parts

• Selecting Parts in an Application

• Adding Parts to an Application

• Replacing Parts in an Application

• Deleting Parts from an Application

• Moving Parts

• Copying Parts

• Resizing Parts

• Aligning Parts

• Distributing Parts in an Application

• Shrinking and Expanding Parts

See appendix A, Menu and Toolbar Quick Reference, for a summary of menu and toolbar operations for parts.

See appendix B, Mouse Actions Quick Reference (Windows), or appendix C, Mouse Actions Quick Reference (OS/2), for a summary of mouse operations for parts.


Manipulating PartsCHAPTER 3

On-line HelpThere is menu help and two kinds of context-sensitive help. You can also add context-sensitive help that is accessible in the workbench to your own parts.

Help for Existing PartsFor information on part related topics, you can choose the on-line help system’s table of contents and index from the workbench Help menu. See chapter 1, The Workbench, for more information on the Help system.

The workbench’s information area displays the name of the part under the cursor and a hint. See chapter 1, The Workbench, for more on the information area.

If you select a part and then press the F1 key, a help window introducing the part is displayed.

Adding Context-Sensitive Help to an Application PartWhen you construct a new part, you can add two types of help that are available during development: information area help and F1 key help. (See chapter 8, Constructing New Parts, for more information on building your own parts) To add F1 key help, you must first create a help file compatible with your operating system’s help system. You use the application part’s Properties dialog to enable both kinds of help.


On-line Help

To add information area help to an application part:

1 Open a workbench on the part.

2 Double-click on the workbench background.

The application part’s Properties dialog is displayed. The contents of the Part name and Hint fields are displayed in the workbench’s information area when you place the cursor over the workbench background.

3 Change the Part name and/or the Hint.


Move the cursor over the workbench background to see the new information area help for the part. If the cursor is already over the part when you close the dialog, move it over another part and back to update the information area.

To add F1 key help to a part:

1 Create a help file and install it according to the requirements of your operating system.

2 Open a workbench on the application.

3 Double-click on the workbench background.

The application part’s Properties dialog is displayed.

4 Enter the name of the help file that you have created in the Help file field.

5 Enter the name of the help topic within the help file in the Help topic field.


7 Choose File/Save from the workbench menu bar.

8 Add the part to an application or a catalog.

9 Select the part’s icon and press the F1 key.

The appropriate help window is displayed.



Undo and RedoThe workbench Edit menu contains Undo and Redo commands which allow you to undo or redo the last operation that you have performed.

The menu items are dimmed when there is no operation that you can undo or redo. The menu items will include the name of the operation which will be undone or redone. You can undo and redo the same operation as many times as you want. The next editing operation that you do resets the commands accordingly.

Undo and Redo are supported by all the standard editing operations on parts, such as add, delete, move, resize, and distribute.

Canceling an OperationYou can cancel most in-progress operations by pressing the Esc key. If the operation is already complete, pressing the Esc Key has no effect.

Visual PartsVisual parts have visible counterparts in the runtime application: windows, dialogs, buttons, and menus for instance. Most visual parts have two different views: shrunken and expanded (the pre-built dialogs do not have an expanded view in the workbench).

Visual parts are displayed in a catalog in their shrunken form as icons which represent their function. When you place a visual part in a workbench, it automatically expands to its normal appearance.

Window Part in Catalog

Window Part Expanded in Workbench


Smalltalk Objects as Parts

Windows and dialogs are special visual parts called top level parts that hold other visual parts. In general, you can place visual parts inside of top level parts or directly in the workbench. You cannot, however, place any of the pre-built dialogs (confirmer, confirmer with cancel, information dialog, and prompter) inside of top-level parts. If you needed to do this, you could recreate the pre-built dialogs using the dialog part. The various Windows operating systems add a further restriction that you cannot put a top level part inside of another top level part. With the exception of top level parts and the pre-built dialogs, you must put visual parts inside a top level part if you want them to be visible at runtime.

Nonvisual PartsNonvisual parts implement the logic, data storage, and resource access features of your application. They do not have any visual counterpart at runtime and therefore do not have an expanded view like visual parts do; they appear as icons representing the parts function in both the catalog and the workbench. In the workbench, the part also has a label displaying the part name that uniquely identifies the part.

Examples of nonvisual parts include the value holder which is similar to a variable in procedural languages, and the printer part which provides access to a printer.

In general, you place nonvisual parts directly in the workbench.

Smalltalk Objects as PartsUnderneath the hood, all parts are instances of Smalltalk classes. The parts in the standard catalogs have been specifically designed for use in the workbench but you can add an instance of virtually any class to the workbench. This is an especially effective way to combine the power and flexibility of Smalltalk with the ease of use inherent in the workbench. When you place a Smalltalk object in the workbench (one that has not been designed for use in the workbench), it is represented with a generic icon.

Printer Part in Catalog

Printer Part in Workbench

Generic Smalltalk Object Icon



The default interface of a Smalltalk object in the workbench is all of the messages that it understands and all of the events (except for its changed: event) that it can trigger. See the Visual Smalltalk Enterprise User’s Guide for information on customizing objects for use in the workbench. See the Visual Smalltalk Enterprise Language Reference for information on adding events to Smalltalk objects.

Parent and Child PartsYou can place some parts inside of other parts. When you do this, the containing or outer part is referred to as the parent and the inner part is referred to as the child. Multiple parts in the same parent are called siblings.

These familial relationships affect part selection and part movement:

• Copying, moving, or deleting a parent performs the same operation on the children.If you delete a window, its children are deleted as well.

• Moving a part to a different parent is a separate operation from moving a part within the same parent.You can’t just drag a child from its parent to another parent; you have to use a modifier key (the Shift key).

When considering parent/child relationships, remember that each workbench contains an application part which is the parent of all parts placed directly in the workbench.

Dialog (Top Level Part)

Push Button

Parent

Siblings

Children


Selecting Parts in an Application

Selecting Parts in an ApplicationWhen you add a part to an application, it is automatically selected. A selected part has resize handles: eight black squares superimposed around its perimeter.

Nonvisual parts have handles to indicate that they are selected, but they cannot be resized.

TIP: For more information about a part, select the part and press the F1 help key.

At least one part is always selected. The application part is selected by default when no other part is selected.

To select an individual part:

> Click on a part.

or

> Press the F7 key.

Each time you press the F7 key, the current part is deselected and a new part is selected. If you continue to press the F7 key, you will cycle through every part in the workbench including the application part.

or

1 Choose Selected/Select... from the workbench menu bar.

A Select Parts dialog is displayed. Selected parts are highlighted. If no other part is selected, the application part is highlighted.

2 Deselect the application part.

3 Highlight the name of the part that you wish to select by clicking on it.

Visual Part (List Pane) with Resize Handles

Nonvisual Part with Selection Handles



4 If there are any parts highlighted that you do not want selected, unhighlight them by clicking on their names.


The highlighted part is selected in the workbench.

To select a group of parts:

> Alt<drag> a selection rectangle around a group of sibling parts with mouse button.

As you drag the cursor, a rectangle grows from the starting point of the drag. Parts within the rectangle are selected when you release the mouse button. This technique only works with parts that are siblings. See Parent and Child Parts for information about siblings.

or

1 Select a part using one of the methods listed for selecting individual parts (these methods work regardless of the parts’ relationships to one another).

2 Shift<click> or Ctrl<click> on additional sibling parts to add them to the selection.

Shift<click> adds a part to the selection. Ctrl<click> toggles the selection state of a part. If a part is not included in the current selection, Ctrl<click> adds it to the current selection. If a part is part of the current selection, Ctrl<click> removes it from the current selection.

or

1 Choose Selected/Select... from the workbench menu bar.

A Select Parts dialog is displayed. If one or more parts in the workbench are already selected, they will be highlighted in the list.

2 Highlight the names of the parts that you wish to select by clicking on them.

TIP: Make sure that you deselect the application part if it is selected. It cannot be included in a multiple selection.

3 If there are any parts highlighted that you do not want selected, unhighlight them by clicking on their names.


The highlighted parts are selected in the workbench.


Adding Parts to an Application

Adding Parts to an ApplicationYou can add parts to the workbench from a catalog, from the clipboard from a file, or (OS/2 only) from the desktop.

When you add a part to a workbench, PARTS Workbench automatically assigns it a unique name consisting of the default part name followed by an integer.

The first radio button added to the workbench is RadioButton1, the next one is RadioButton2, and so on. You can change this name using the properties dialog, described later in this chapter.

There are some restrictions on where you put parts. If you drag a part to a location where it cannot be dropped, a symbol indicating that the operation is not allowed is superimposed on the part’s icon.

See Visual Parts, Nonvisual Parts, and the Part Reference for specific restrictions.

To add a single part to your application from a catalog:

> Using the primary mouse button, drag the part from the catalog to the destination part.

The cursor becomes the part’s icon with an angle bracket in the upper left corner. When you release the mouse button, the new part is placed with its upper left corner at the position indicated by the angle bracket.

If you release the part over the workbench background, the destination part is the application part.

Windows OS/2



To add multiple copies of the same part to your application from a catalog:

1 Using the secondary mouse button, drag the part from the catalog to the destination part.

The cursor becomes the part’s icon with an angle bracket in the upper left corner. When you release the mouse button, a pop-up menu with the choices Copy and Repeat Copy is displayed. The Copy operation produces the same result as adding a part with the primary mouse button.

2 Choose Repeat Copy.

A new part is placed with its upper left corner at the position indicated by the angle bracket. The cursor remains as the part’s icon reminding you that you can place additional copies.

3 Place additional copies by positioning the cursor and clicking with the primary mouse button.

4 When you are finished placing parts, click with the secondary mouse button or press the Esc key to cancel the repeat copy mode.

The cursor returns to its normal appearance.

(OS/2) To add a single part to your application from the desktop, perform the following step:

> Drag the part from the desktop to the destination part.

The cursor becomes the part’s icon with an angle bracket in the upper left corner. When you release the mouse button, the upper left corner of the part appears at the position indicated by the angle bracket.

If you release the part over the workbench background, the destination part is the application part.

To add a single part to your application from another application:

1 Select a part from the other application.

2 Choose Edit/Copy or Edit/Cut from the workbench menu bar.

3 Select the target application by selecting the workbench background.



4 Choose Edit/Paste from the workbench menu bar.

The cursor becomes an application icon with an angle bracket in the upper left corner.

5 Position the corner bracket where you want the upper-left corner of the part to appear and click with the primary mouse button.

To add multiple copies of the same part to your application from another application:

1 Select a part from the other application.





5 Position the corner bracket where you want the upper-left corner of the part to appear and click with the secondary mouse button.

A pop-up menu with the choices Copy and Repeat Copy is displayed.


A new part is placed with its upper left corner at the position indicated by the angle bracket. The cursor remains as the part’s icon reminding you that you can place additional copies.






To add a part to your application from a file:

1 Choose Edit/Import part... from the workbench menu bar.

An Import Part dialog (a type of Part File dialog) is displayed. See chapter 1, The Workbench, for more information on Part File Dialogs.

By convention, part files have a PAR extension but this is not mandatory.

If you wish to import a part with the linked reuse option set, the linked part must be in a directory that is included in your PARTS Workbench search path. If it is not, PARTS Workbench will be unable to find the linked part; a warning dialog is displayed and the containing part (if any) is imported without the linked nested part.

See chapter 1, The Workbench, for more information on the PARTS Workbench search path. See chapter 8, Constructing New Parts, and the Nested Part chapter in the Part Reference for more information on part file reuse options.

2 Select a part file and click OK.

The cursor becomes the application part icon with an angle bracket in the upper left corner.

3 Position the corner bracket where you want the upper-left corner of the part to appear and click with the mouse button.

The imported part’s appearance in the workbench depends on its reuse mode.

To add multiple copies of the same part to your application from a file:













The imported part’s appearance in the workbench depends on its reuse mode. The cursor remains as the part’s icon reminding you that you can place additional copies.




To add a single Smalltalk object to your application using the default message new to instantiate it:

1 Choose Developer/Add object from the workbench menu bar.

2 Start entering the name of the class of the object that you want to add.

The list of classes scrolls to match your typing. You can either continue typing until an exact match is found or you can use the scroll bar and the mouse to select a class.

3 When the correct class is highlighted, click the OK button.

The cursor changes to a generic object icon.




To add multiple copies of the same Smalltalk object to your application using the default new method to instantiate them:


2 Start entering the name of the class of the object that you want to add.

The list of classes scrolls to match your typing. You can either continue typing until an exact match is found or you can use the scroll bar and the mouse to select a class.

3 When the correct class is highlighted, click the OK button.





The cursor remains as the icon reminding you that you can place additional copies.




To add a single Smalltalk object to your application using a specific expression:


2 Click on the Evaluate Smalltalk expression radio button.

3 Enter a Smalltalk expression that returns an instance of a class.

You can only put instances of classes in the workbench, not the classes themseleves.





Replacing Parts in an Application

To add multiple copies of the same Smalltalk object to your application using a specific expression:


2 Click on the Evaluate Smalltalk expression radio button.

3 Enter a Smalltalk expression that returns an instance of a class.

You can only put instances of classes in the workbench, not the classes themseleves.






The cursor remains as the icon reminding you that you can place additional copies.




Replacing Parts in an ApplicationThe ability to replace a part is especially important once you have started connecting it to other parts via links. If you simply delete the part, its scripts and links are deleted as well. The Replace operation allows you to substitute a new part while preserving the existing part’s scripts and links.

If the replacement part does not support an event or message required by one of the original part’s links, you are given an opportunity to delete all obsolete links. You can also choose to keep the links. If you keep the links you will need to manually update each of the obsolete links to use a message or event that is supported by the replacement part.

You cannot replace a visual part with a nonvisual part or visa versa.



To replace a part with one from a catalog:

1 Using the secondary mouse button, drag the part from the catalog until the cursor’s angle bracket is over the part that you want to replace.

When you release the mouse button, a pop-up menu with a single choice, Replace, is displayed.

2 Choose Replace.

The old part is replaced with the new part and all links and scripts are transferred. If the new part does not support one or more of the events or messages required by the existing links, a dialog is displayed giving you the opportunity to delete the obsolete links. If you choose to keep them, you need to update each of the obsolete links to use events or messages that are supported by the new part.

(OS/2) To add a single part to your application from the desktop, perform the following step:

1 Using the secondary mouse button, drag the part from the Desktop until the cursor’s angle bracket is over the part that you want to replace.

The cursor becomes the part’s icon with an angle bracket in the upper left corner. When you release the mouse button, a pop-up menu with a single choice, Replace, is displayed.

2 Choose Replace.


To replace a part with another part from the same application or a different application:

1 Select a part.




Replacing Parts in an Application



5 Position the corner bracket over the part that you want to replace and click with the secondary mouse button.


6 Choose Replace.


To add a part to your application from a file:










3 Position the corner bracket where you want the upper-left corner of the part to appear and click with the mouse button.

The imported part’s appearance in the workbench depends on its reuse mode.

4 Position the corner bracket over the part that you want to replace and click with the secondary mouse button.


5 Choose Replace.


Deleting Parts from an ApplicationDeleting a part from an application removes the following:

• the part• all of the part’s children (See Parent and Child Parts for more

information on parent/child relationships)• scripts attached to the parent or its children

• all links attached to the part

To delete one or more selected parts from the workbench perform one of the following steps:

> Press the Delete button on the toolbar.

or

> Press the Delete key.

or

> Choose Edit/Delete from the workbench’s menu bar.

To copy the parts to the clipboard and then delete them:

> Choose Edit/Cut from the workbench menu bar.


Moving Parts

To delete all parts from a workbench:

1 Click on the workbench background to select it.

2 Press the Delete key, the delete button on the toolbar, or choose Edit/Delete from the workbench menu bar.

A dialog is displayed asking you to confirm the operation.


A workbench always includes an application part.

Moving PartsWhen you move a parent part, all of its children are moved with it. See Parent and Child Parts for information on parent parts.

(OS/2) To move a part without selecting it:

> Drag the part to a new location within the same parent part.

or

> Shift<drag> the part to a different parent part.

To move one or more selected parts:

> Press one of the arrow keys.

The current selection will move in the direction indicated by the arrow key. Each time you press the arrow key, the current selection moves the number of pixels specified in the workbench’s grid setting. See chapter 1, The Workbench, for details on viewing or changing the current grid setting.

or

> Drag a part from the current selection to a new location within the same parent part.

or

> Shift<drag> a part from the current selection to a different parent part.



Copying PartsPARTS Workbench requires all parts to have unique names. When you place a copy of a part in the same workbench as the original, PARTS Workbench automatically changes the copy’s name to make it unique.

When you copy a parent part, you copy the following:

• the part

• the part’s children

• scripts attached to the parent or its children

• any links that both begin and end within the parent part

See Parent and Child Parts for information on parent parts.

To copy one or more selected parts without changing the contents of the clipboard:

> Ctrl <drag> a part from the current selection to a new location within the same parent part or to a different parent part.

or

> Choose Edit/Duplicate from the workbench’s menu bar.

The copied parts appear slightly offset from the original ones and are automatically selected.

To copy and paste one or more selected parts using the clipboard:

1 Choose Edit/Copy from the workbench’s menu bar.

2 Choose Edit/Paste from the workbench’s menu bar.

The cursor becomes the application icon with an angle bracket in the upper left corner. The angle bracket indicates where the upper left corner of the part will appear when you place it.

3 Position the angle bracket and click to place the part(s).


Resizing Parts

Resizing PartsYou can only resize parts that have an expanded view; you cannot resize an icon (See Shrinking and Expanding Parts for an explanation of the difference). You can resize parts directly by manipulating them with the mouse or the keyboard, or resize them to match a reference part.

Some visual parts such as buttons with labels automatically resize themselves to accommodate a new label that would exceed the current width of the part. See chapter 4, Part Properties, for more details.

Resizable visual parts also have a Window layout property. This property determines how a part behaves when its parent part is resized: whether it is resized or remains fixed in size. You can also control the way in which the part is automatically resized. See chapter 4, Part Properties, for a detailed description of the Window layout property.

To resize an expanded part by direct manipulation:

1 Select a part to display its resize handles.

2 Drag one of the resize handles to the desired position, and release the mouse button.

or

1 Select a part to display its resize handles.

2 Press and hold the Shift key while pressing one of the arrow keys.

Pressing the up or down arrow keys moves the bottom of the part towards or away from the top of the part by the number of pixels specified for the Y value of the workbench’s grid setting.

Pressing the left or right arrow keys moves the right side of the part towards or away from the left side of the part by the number of pixels specified for the X value of the workbench’s grid setting. See chapter 1, The Workbench, for information on viewing or changing the workbench’s grid setting.



To resize an expanded part to the same size as another part:

1 Select the reference part first.

2 Add one or more parts to the selection.

Notice that these parts have gray resize handles while the reference part has the standard black resize handles.

3 Choose Edit/Same size from the workbench menu bar and then select one of the submenu options: Width, Height, or Both.

The selected dimension(s) of the parts with gray resize handles are resized to match the reference part.

Aligning PartsYou use either a part or the workbench grid as a reference when aligning parts. See chapter 1, The Workbench, for information on using the workbench grid.

You have the following alignment options when aligning to a reference part:

• Left

• Center vertically

• Right

• Top

• Center Horizontally

• Bottom

Before Resizing

After Choosing Edit/Same size/Both

Reference Part


Aligning Parts

To align a set of parts to a reference part:

1 Select the reference part first, and then add the other parts you want to align to the selection.

2 Click the Align Left or Align Top button in the tool bar.

or

1 Select the reference part first, and then add the other parts you want to align to the selection.

2 Choose Edit/Align and the appropriate submenu option from the workbench menu bar.

Reference Part

Before Alignment

After Choosing Edit/Align/Left



Distributing Parts in an ApplicationThis operation distributes the selected parts so that they are evenly spaced between the two outermost parts (the reference parts).

To distribute three or more parts so that they are equidistant from each other in the vertical and/or horizontal dimension, perform the followings:

1 Select the parts you want to distribute.

2 Choose Edit/Distribute/Horizontally or Edit/Distribute/Vertically.

Shrinking and Expanding PartsMost visual parts in the standard PARTS catalog have expanded and shrunken views. The shrunken view is the visual parts icon which is displayed in the catalog. Visual parts are automatically displayed in their expanded view when you place them in the workbench. The expanded view is virtually identical to what you see in your runtime application.

You can shrink and expand the view of some top-level visual parts manually after you have placed them in the workbench:

• windows• dialog windows• menus• nested parts referencing parts that contain top-level visual

parts (See the Nested Part chapter in the Part Reference, for more information on nested parts)

Reference Parts

Before Distribution

After Choosing Edit/Distribute/Horizontally


Shrinking and Expanding Parts

When you shrink a window or dialog window, the catalog icon is displayed with the part’s name under it.

When you shrink a nested part, the icon of the enclosed application is displayed with the nested part’s name below it. The same icon is displayed in a catalog.

It is possible to change the icon displayed by parts in their shrunken view. See chapter 4, Part Properties, for information on editing a part’s icon.

To expand or shrink a selected part:

> Choose Selected/Expand or Selected/Shrink from the workbench menu bar.

These options are grayed out when not appropriate.

Window Part Shrunken in Workbench


CHAPTER

4
Part Properties
Each type of part in the PARTS catalog—windows, push buttons, Btrieve accessors, etc.—has a set of properties which describe attributes (such as a part’s name) and states (such as whether a window is initially shown or hidden when it is first opened). You can change the settings of an individual part’s properties to customize its appearance and function in your runtime application.

This chapter explains how to access a part’s Properties dialog and how to direct-edit a part. The following topics are discussed in this chapter:

• Property Basics

• Properties Dialog Overview

• Setting Properties for an Individual Part

• Undo and Redo

• Setting Properties for a Group of Parts

• Direct-Editing a Part

The following standard properties are found in many types of parts and are discussed in appendix C of the Part Reference:

• Backcolor property

• Edit bitmap property

• Edit icon property

• Font property

• Forecolor property

• Order children property

• Part name property

• Size window property

See the individual section for each part in the Part Reference for information on the unique properties of particular parts.


Part PropertiesCHAPTER 4

Property BasicsEach instance or copy of a particular type of part has the same properties as every other instance. For example, all windows have an Initial visibility property that determines whether they are initially visible or hidden.

Each particular instance of a part, however, can have different values for each of its properties. For example, one window may have its Initial visibility property set to Visible while another has the same property set to Hidden.

The number of properties that different types of parts have varies widely depending on the complexity of the part. A push button has very few properties compared to a Btrieve accessor for example.

You edit properties in one of three ways:

• You perform most property editing in Properties dialogs.

• You can change some properties by direct-editing a part.

• You can also change most properties dynamically at runtime via links and scripts that send messages to the part.

See the individual chapter for each part in the Part Reference for information on dynamically changing properties at runtime with links. See chapter 9, User-Defined Messages and Events, for more information on scripts.


Properties Dialog Overview

Properties Dialog OverviewEach part’s properties are displayed in its Properties dialog. You use this dialog to view and change a part’s properties when you are building an application. Some properties are visible as soon as you open the Properties dialog. Others are accessed by pushing a button in the Properties dialog which opens a sub-dialog.

• Each part has a name property.

• Most visual parts have properties for size, forecolor, backcolor, and font.

• Nonvisual parts and some visual parts have an icon property that allows you to change their visual representation with an icon editor.

• Graphical items like drawn buttons and graph panes have a graphic property that lets you change their appearance with a Bit or Icon editor.

Clicking on the Edit contents... button opens a subdialog which allows you to enter the list of items that appears in the list pane.



NOTE: Each part Properties dialog also has an Interface... button which opens the part’s Interface window. This is provided as an alternate for the Selected/Edit interface... command available from the workbench menu bar. A part’s interface is not one of its properties, however. Closing a Properties dialog, clicking on its OK or Cancel buttons, and undoing property changes have no effect on a part’s Interface window or changes made to the part’s interface. See chapter 9, User-Defined Messages and Events, for more information on the Interface window.

Setting Properties for an Individual PartSee the topics describing common properties in Appendix C of the Part Reference and the individual chapters of the Part Reference for information on setting specific properties for a part.

1 Open the Properties dialog by double-clicking on a part.

2 Edit the part’s properties.

3 Click OK.

All changes made in the Properties dialog and any sub-dialogs are applied to the part.

Clicking on the Cancel button cancels all changes, including changes made in sub-dialogs even if you closed the sub-dialog by clicking on the OK button.

or

1 Select a part.

2 Choose Selected/Edit properties... from the workbench menu bar.

3 Edit the part’s properties.

4 Click OK.

All changes made in the Properties dialog and any sub-dialogs are applied to the part.

Clicking on the Cancel button cancels all changes, including changes made in sub-dialogs even if you closed the sub-dialog by clicking on the OK button.

You can also direct-edit a part to change certain properties. See Direct-Editing a Part for information on direct-editing and the properties affected by it.


Setting Properties for a Group of Parts

Undo and RedoChanges made to a part’s properties can be undone. When you undo changes to properties, all property changes, including those set via sub-dialogs of the main properties dialog, are undone. Undo and Redo are not supported for property changes made using the properties dialogs of the following parts:

• Btrieve accessor• C structure• DLL accessor

Undo of direct-edit changes to any of these parts is supported.

Setting Properties for a Group of PartsWhen building a user interface, you may wish to assign the same color and font properties to a group of visual parts. There is a special Color and Font Properties dialog that allows this. Changes made in this dialog will only affect selected parts that have the appropriate properties. Dialogs, for example, don’t have color or font properties.

1 Select a group of parts.

See chapter 3, Manipulating Parts, for various group selection techniques.

2 Choose Selected/Edit properties... from the workbench menu.

A Color and Font Properties dialog is displayed. You must use the Selected/Edit Properties command to open this dialog; double-clicking on one of the selected parts will not work.



3 Set the Forecolor, Backcolor, or Font property by clicking on the appropriate button.

See appendix C of the Part Reference for information on setting these properties.

The Forecolor, Backcolor, and Font check boxes above the buttons are automatically checked when you modify the corresponding property. Unchecking a check box allows you to cancel the changes for that property only. If you want to cancel all changes, use the Cancel button.


Direct-Editing a PartThe direct-edit mechanism lets you edit a single property without opening the part’s Properties dialog. In general, direct-editing affects the following properties for the listed types of parts:

• part name (icon label) for most nonvisual parts

• value for number and string holder parts

• label for visual parts with labels, such as windows and buttons

• the value (text) of visual parts with text contents, such as entry fields

• the value (a list) for list, multiple choice list, and combo box parts

• icon or bitmap property as appropriate for drawn buttons, graph panes, menu bitmap items, and static graphics

When you direct edit a label or other text, the text area is surrounded by a selection rectangle and any current contents are highlighted.

String holders and number holders follow this pattern except when the contents of the holder exceeds the holder’s maximum width. In this case, the first portion of the contents is displayed followed by an ellipsis (...). When you direct edit this holder, a dialog prompting for the new contents of the holder is displayed.

Direct editing a graphic part invokes either the Bitmap Editor or the Icon Editor as appropriate.


Direct-Editing a Part

To direct-edit a part, perform one of the following procedures:

1 Alt<click> on the part.

2 Make the desired changes.

3 Exit the direct-edit mode.

If you are direct-editing text, press the Enter key or click outside the text area.

If you are direct-editing a graphic, close the Bit or Icon Editor.

or

1 Select a single part.

2 Choose Selected/Edit direct from the workbench menu bar.

3 Make the desired changes.

4 Exit the direct-edit mode.

If you are direct-editing text, press the Enter key or click outside the text area.

If you are direct-editing a graphic, close the Bit or Icon Editor.


CHAPTER

5
Events, Messages, and Links
Building a PARTS Workbench application requires an understanding of events, messages, and links. This chapter explains the following topics and how they relate to building a PARTS Workbench application:

• Programming with Links

• Links, Labels, and Connections

• Link Handles

• Events

• Messages

• Event Links

• Argument Links

• Result Links

• Scenarios

Programming with LinksYou begin the mechanical task of building a PARTS Workbench application by choosing the parts you need from catalogs or files and then adding them to the workbench. It is important to realize, however, that simply placing parts in the workbench does not define the logic of your application, any more than placing computer chips in an otherwise empty case defines the design of a computer.

Just as the computer chips cannot do any useful work until they are properly connected, neither can parts. You define the logic of your application by connecting parts with wiring called links. The attachment points for links are events and messages.

Most types of parts can generate one or more events in response to various stimuli. An event is a signal that something has happened. For example, when you click on a push button, it generates a clicked event.


Events, Messages, and LinksCHAPTER 5

Most types of parts also understand one or more messages. A message is a command. A speaker understands the ring message, for example, which causes it to make a ringing sound.

A simple application using a push button and a speaker demonstrates the operation of events, messages, and links. The push button’s clicked event is connected to the speaker’s ring message with a link. When you click on the push button at runtime, the following occurs:

1. You trigger the push button’s clicked event.

2. The clicked event fires the link.

3. The link sends the ring message to the speaker part.

4. The speaker rings.

Links, Labels, and ConnectionsBefore delving too deeply into the topics of events, messages, and links, you need to understand some basic terminology. This topic identifies and describes the features of links, labels, and connections.

Link

➊

➋

➌

➎

➏

➐➑

➒➍ ➓


Links, Labels, and Connections

1. Event Link

Connects a part event to a part message.

2. Argument Link

Connects a message argument to an argument source. Some messages require one or more arguments to complete their function. For example, the speaker’s setFrequency: message needs the frequency to which it is to set the speaker.

3. Result Link

Connects the result of a part message to another part message. For example, linking the result of a number holder’s setValue: message to a speaker’s setFrequency: message.

4. Event Connection

A visual indicator for the origin of the link—the filled square where an event link is attached to the perimeter of the originating (source) part.

5. Message Connection

The arrowhead at the end of a link line where a link is connected to a message. It points to the destination part.

6. Result Connection

A colored dot representing the result of the message and serving as the origin of a result link. A result connection can also be the destination of an argument link.

7. Argument Connection

A black mark (unexpanded label), a pink dot (expanded label, unsatisfied argument), or a blue dot (expanded label, satisfied argument). An argument connection serves as the origin for an argument link.

8. Event Value Connection

A black mark (unexpanded label) or green dot (expanded label) indicating a value supplied by the event when it is triggered. Event value connections serve as destinations for argument links. There is no requirement that you use an event value, hence there is no difference in appearance between a linked and an unlinked event value connection.



9. Event Label

A box containing the name of the event that fires the link. It also indicates any event values the event provides by displaying event value connections as either asterisks or green dots.

10. Message Label

A flattened hexagon containing the name of the message sent by a link. It also indicates any arguments the message needs by displaying argument connections as either asterisks or colored dots.

Link HandlesLink handles allow you to format your links, access the Link pop-up menu, and display link information in the information area at the bottom of the workbench.

1. Link Handle

Any link connection, label, or control point. You can format links by dragging link handles, invoke the Link pop-up menu from any link handle (See chapter 6, Programming with Links), and display information about a link in the workbench’s information area by placing the cursor over a link handle.

➊

➋


Events

2. Control Point

A link handle displayed as small dot on a link line at the junction of two straight line segments. Control points are joints that allow you to bend links around obstacles. They have no effect on program execution.

EventsWhen you click on a push button in an application, the push button generates a clicked event announcing that the user has pushed it. In the terminology of PARTS Workbench:

The user triggered the push button’s clicked event by clicking on the push button with the mouse.

You instruct your application to perform work by linking events like clicked to messages which perform commands and may in turn trigger other events. A single event can trigger many links.

Most types of parts have one or more built-in events which are triggered by various stimuli. Many events provide values when they are triggered that you can display, store, or use to satisfy a message argument. Here are some examples of events that provide values:

• When the cursor is in an entry field and you press the Enter key, you trigger the entry field’s entered: event which provides the contents of the entry field as an event value.

• When you click on a check box, you trigger its clicked: event which provides an event value of either true, if the check box is now checked, or false, if the check box is now unchecked.

• When a timer’s time interval expires, it generates a tickedTime: event which provides the current time as an event value.

You can identify an event that provides a value in one of three ways:

• the event name includes one or more colons (one colon for each value)

• a link’s event label has one or more colored dots (link labels expanded) or black marks (link labels displayed but not expanded)

See the Part Reference for a complete description of each part’s events.



MessagesA message is the name of a function that a part knows how to perform. Most types of parts have one or more messages that they understand. Window parts, for example, understand the open message.

Some messages require arguments. An argument is a value that the message needs in order carry out its function. Arguments can be supplied by event values, by creating a link from the argument connection that sends a message to a part, or by using the result of a previous message. Some examples of messages that require arguments include the following:

• A list pane’s deleteItem: message deletes the item that matches the argument.

• A text pane’s insert: message inserts the text specified by the argument into the text pane.

• A speaker’s frequency:duration: message requires two arguments: one specifying the frequency of the sound it should make and the other specifying the length of time that it should play the sound.

You can identify a message requiring an argument in one of the following ways:

• the message name includes one or more colons (one colon for each argument)

• a link’s message label has one or more colored dots (link labels expanded) or black marks (link labels displayed but not expanded)

The color of the link sending the message indicates that the message requires an argument which has not yet been satisfied (the default colors for unsatisfied arguments are red for event and result links and pink for argument links)

Every message produces a result (also known as the value returned by a message), although not all messages return results that you, as a programmer, will find useful. Results that are useful are documented in the Part Reference. When you send a message to satisfy an argument, it is the message result that becomes the argument value.

See the Part Reference for a complete description of each part’s messages.


Event Links

Event LinksAn event link connects an event to a message. You can create a simple example of an event link by connecting a push button’s clicked event to a speaker’s ring message.

You can create as many event links as you like originating from the same event of a single part. If the order in which these links is fired is important, you can sequence them. See chapter 6, Programming with Links, for more information.

Some event links are created automatically. An example of this is when you add a window to an application. The window is automatically linked to the application’s open event so that the window opens when the application is launched. There are other parts that are automatically linked. See the Part Reference for details.

A simple event link, with no argument or result links attached, is executed in the following way:

1. The source part’s event is triggered.

2. The event fires the link.

3. The event link sends the message to the destination part.

4. The destination part executes the message.

The full sequence of operation including argument links and result links is as follows:

1. The source part’s event is triggered.

2. The event fires the link.

Event Link

Multiple Links Fired by a Single Event



3. Message arguments are collected by firing the argument links.

4. The event link sends the message with arguments to the destination part.


6. The message returns a result.

7. Result links are fired.

Argument LinksWhen a message requires arguments, it must first obtain a value for each of its arguments before it can execute. These values are supplied by argument links. An argument link connects the message to an argument source.

You can create a simple example of an argument link by first creating an event link from the entered: event of an entry field to the setValue: message of a dial pane. A default argument link is automatically created connecting the argument connection of the dial pane’s setValue: message to the event value connection of the entry field’s entered: event.

The entry field’s entered: event is triggered when the cursor is in the entry field and you press the Enter key. The event value of the entered: event is the contents of the entry field.


Argument Links

1. Argument Connection

The argument link originates at an argument connection.

2. Argument Source—Message Connection

The result of a message sent by the argument link satisfies the argument.

3. Argument Source—Event Value

The event value of the original link satisfies the argument. See Events for information on event values.

➊

➌

Argument Link

➋

➍



4. Argument Source—Result Connection

The result of the last message in the argument chain satisfies the argument.

PARTS Workbench tries to create argument links automatically when they are required. When a message sent by a link requires an argument, PARTS Workbench determines whether or not the source of the link that sent the message provides an event value or relevant message result. If the source of the link does provide a value or relevant result, it is automatically linked to the message argument.

Event values are matched to message arguments proceeding from left to right; the left-most event value is matched to the left-most message argument etc.

If the number of values does not match the number of arguments, PARTS Workbench attempts to satisfy as many arguments as possible. You can replace these default argument links at any time.

If any unsatisfied arguments remain after you create the link, the message label is automatically expanded when the link is first displayed. If you launch an application with incomplete argument links, the affected arguments are supplied with nil values.

In addition to supplying values for message arguments, you must sometimes be concerned with the types—such as String, Integer, or Boolean—required by the arguments as well.

Individual parts make many conversions automatically. This is demonstrated by using the contents of an entry field to set the value of a dial pane. The entry field’s entered: event supplies a String value but the dial pane’s setValue: expects an Integer. This arrangement works, however, because, PARTS Workbench automatically converts appropriate String values into Integers. If the entry field contains letters rather than numbers, the String is converted to zero.

Sometimes this automatic conversion is inadequate and you need to perform explicit conversions. Each part listed in the Part Reference lists the types of arguments expected.


Argument Links

A simple argument link that sends a message with no arguments is executed in the following manner:

1. A link that sends a message (setValue: for example) requiring an argument is fired.

2. The message’s argument link is fired.

3. The argument link sends the message (value for example) to the destination part.

4. The message is executed.

5. The message result is returned as the argument value.

6. The message (with argument) is sent to its destination and executed.

When you use an event value or a result connection as the source for an argument, the argument link works differently than if the link fires a message to retrieve an argument value.

In both cases you are using the link to specify the value that you want to use rather than to fire a message.

An argument link that connects to an event value or result connection executes in the following manner:

1. A link that sends a message requiring arguments is fired.

2. The message’s argument link is fired.

3. The specified value is returned as the argument value.

The full sequence of execution for an argument link is as follows:

1. A link that sends a message requiring arguments is fired.

2. The message’s first argument link is fired.

3. Message arguments for the message sent by the argument link are collected if necessary (which may cause other links to fire and their messages to execute).

4. The argument link sends the message with argument(s) to the destination part.

5. The message is executed.

➊

➍

➋

➌

➎ ➏



6. If a result link is connected, it is fired (and so on, until all the last message in the chain is executed).

7. The message result value of the last message in the argument link chain is returned as the argument value.

8. The process is repeated for each of the original message’s argument links.

Result LinksWhen a message executes, it produces a result value. The useful message results are documented as return values for the messages in the Part Reference.

A result link connects a message result to another part message. A result link connects to a message connection with a small round ball at the tip of the message connection.

You can create an example of a result link by first creating an event link from a push button’s clicked event to a speaker’s ring message. Then create a result link from the ring message’s message connection to the speaker’s alarm message.

You can use result links in a number of ways:

• to perform a sequence of messages in which the result of the first message is used as an argument to the next message in the sequence

➊

➋


Result Links

l

1. Clicking on the Debt-to-Income Ratio button fires a link that sends the divide: message to the Annual Income field. Annuaincome is divided by 12.

2. The result of the divide message (annual income divided by12) fires a link which sends the setValue: message to the Monthly Income field. setValue: uses the result of the divide message as its argument, setting the monthly income to thevalue of (annual income/12).

• To fire a series of messages in a specific sequence.

The next application performs the following actions in order:

1. rings a bell

2. opens the window

3. starts the timer (the end of the first result link chain)

4. timer ticks (begins second result link chain)

5. rings an alarm

6. stops timer

7. closes the window

You can achieve a similar result by creating a series of event links originating from the application part’s open event and then sequencing them. See chapter 6, Programming with Links, for more information on sequencing event links.



OperationA simple result link, with no argument or result links attached, is executed in the following way:

1. A link with result link appended fires its message.



4. The result link is fired with the message result.

5. The result link sends its message to the destination part.


The full sequence of operation including argument links and result links is as follows:

1. A link with result link appended fires its message.



4. The result link is fired with the message result.

5. Message arguments are collected by firing the argument links.

6. The result link sends its message to the destination part.


8. The message makes its result available.

9. Result links, if any, are fired.

10. When the final message in the result link chain is fired, its result is returned. If the chain was initiated by an argument link, the final message result becomes the argument value.

ScenariosIn a complex workbench, the number of links can become overwhelming. To manage this complexity, you can assign links to scenarios. A scenario is a named collection of links. Once you have defined a scenario and added links to it, you can control the display of the included links as a group. This allows you to easily focus on different parts of the application logic. The placement of links in scenarios has no effect on program execution.

Scenarios are more fully explained in chapter 7, Displaying Links.


CHAPTER

6
Programming with Links
This chapter describes techniques for specifying the logic of your application using links. See chapter 5, Events, Messages, and Links, for more information on what links, events, and messages are and what they do in your application.

The following topics are covered:

• Link Pop-up Menu

• Creating Links

• Deleting a Link

• Replacing a Result Link

• Moving an Event or Message Connection

• Changing the Event that Fires an Event Link

• Changing the Message Sent by a Link

• Changing an Event Link’s Origin

• Changing a Link’s Destination

• Sequencing Event Links

Link Pop-up MenuWhen you click on a link handle with mouse button 2, you see a Link pop-up menu. If you do not want to make a choice, you can cancel the menu by clicking anywhere outside the menu, or by pressing the Esc key.

Items in this menu vary depending on context from which it is invoked. See appendix A, Menu and Toolbar Quick Reference, for a quick reference to the Link pop-up menu and for the tool-bar button equivalents for commands that affect the display of links and labels.

See appendix A, Menu and Toolbar Quick Reference, for a summary of menu and toolbar operations for the Workbench.

See appendix B, Mouse Actions Quick Reference (Windows), or appendix C, Mouse Actions Quick Reference (OS/2), for a summary of mouse operations for the Workbench.


Programming with LinksCHAPTER 6

Creating LinksThere are a number of different kinds of links that you can create. The basic technique is similar for each type, although the origin of the link will differ.

To create an event link:

1 Place the cursor over a part.

2 Drag the cursor with the link mouse button to the same or a different part.

A rubber-band line follows the cursor as you drag to confirm that you are drawing a link. You can cancel the link while you are dragging by pressing the Esc key or by dragging the cursor outside of the workbench background and releasing the mouse button.

When you release the mouse button over a part, a Create Link dialog is displayed.

The left side of the Create Link dialog is a list of events that can be triggered by the link’s originating part. The right side of the dialog is a list pane displaying messages that you can send to the link’s destination part.

3 Choose an event from the left hand list pane.

4 Choose a message from the right hand list pane.


Creating Links


The new link is displayed.

To create an argument link to a part message:

1 Place the cursor over an argument connection.

2 Drag the cursor with the link mouse button to a part.

A rubber-band line follows the cursor as you drag to confirm that you are drawing a link. You can cancel the link while you are dragging by pressing the Esc key or by dragging the cursor outside of the workbench background and releasing the mouse button.

When you release the mouse button over a part, a Create Argument Link dialog is displayed.

The left side of Create Argument Link dialog displays the keyword preceding the argument connection on the argument label. If a message has multiple arguments, you only see the keyword that is satisfied by the current argument link.

The right side of the dialog is a list pane displaying messages which you can send to the link’s destination part.

Argument Link to a Part






To create an argument link to an event value connection or a result connection:

1 Place the cursor over an argument connection.

2 Drag the cursor with the link mouse button to an event value connection or result connection.

A rubber-band line follows the cursor as you drag to confirm that you are drawing a link. You can cancel the link while your dragging by pressing the Esc key or by dragging the cursor outside of the workbench and releasing the mouse button.

When you release the mouse button, the argument link is automatically created since there is only one value available at an event value connection or result connection.

Argument Link to a Result Connection


Creating Links

To create a result link:

TIP: You can change the destination of an existing result link without deleting it first by drawing a new link from the existing result connection to a new destination.

1 Place the cursor over message connection.

2 Drag the cursor with the link mouse button to the same part that the message connection is attached to or a different part.

3 A rubber-band line follows the cursor as you drag to confirm that you are drawing a link. You can cancel the link while you are dragging by dragging the cursor outside of the workbench background and releasing the mouse button or by pressing the Esc key.

When you release the mouse button, a Create Result Link dialog is displayed.

The left side of the Create Result Link dialog displays the message whose result is the source of the link. The right side of the dialog is a list pane displaying messages that you can send to the link’s destination part.






or

1 Click on a link handle of a link that sends a message with mouse button 2 to select the Link pop-up menu.

2 Choose Create result link.

A rubber-band line follows the cursor until you click on a part. You can cancel the link before selecting a destination by pressing the Esc key or by clicking the mouse button outside the workbench background.

When you click the mouse button, a Create Result Link dialog is displayed.

The left side of the Create Result Link dialog displays the message whose result is the source of the link. The right side of the dialog is a list pane displaying messages that you can send to the link’s destination part.



Deleting a Link



To insert a result link in the middle of a result link chain:

1 Invoke the Link pop-up menu of a link in the link chain that you want to delete by clicking with mouse button 2 on a link handle.

2 Choose Insert result link from the menu.

This command only appears if the link is part of a result link chain. A rubber-band line is attached to the cursor.

3 Click on a destination for the new link.

A Create Result Link dialog is displayed.

4 Select a message and click the OK button.

The new link is displayed. If you change your mind, immediately choose Edit/Undo from the workbench menu bar.

Deleting a LinkYou can delete links from the middle of a result link chain as well as well as terminal links from which no result link extends.

To delete a single link from your application:

1 Invoke the Link pop-up menu of the link you want to delete by clicking with mouse button 2 on one of its link handles.

2 Choose Delete link from the menu.

If you change your mind, immediately choose Edit/Undo from the workbench menu bar. If the link occurs in the middle of a link chain, the link following the deleted link is connected to the link preceding the deleted link.



To delete a link chain from your application:


2 Choose Delete link chain from the menu.

This command only appears if the link is part of a result link chain. If you change your mind, immediately choose Edit/Undo from the workbench menu bar.

Replacing a Result LinkIf you replace a result link that occurs in the middle of a result link chain, any links that follow the replaced link in the chain are deleted.

To replace a result link:


2 Choose Insert result link from the menu.

This command only appears if the link is part of a result link chain. A rubber-band line is attached to the cursor.

3 Click on a destination for the new link.

A Create Result Link dialog is displayed.

4 Select a message and click the OK button.

The new link is displayed. If you change your mind, immediately choose Edit/Undo from the workbench menu bar.

Moving an Event or Message ConnectionYou can move event and message connections around the perimeter of a part.

To move an event or message connection:

> Drag the connection to a different location.

If you want to move the connection to a different part, use the techniques described under either Changing an Event Link’s Origin or Changing a Link’s Destination.


Changing an Event Link’s Origin

Changing the Event that Fires an Event LinkTo change the event that fires an event link:

1 Click on a link handle with mouse button 2 to select the Link pop-up menu.

2 Choose Change event.

A pop-up list of available events is displayed.

3 Choose an event.

Changing the Message Sent by a LinkTo change the message that a link sends:


2 Choose Change message.

A pop-up list of available messages is displayed.

3 Choose a message.

Changing an Event Link’s OriginTo change the originating part of an event link:

1 Shift <drag> the event connection to a new part.

If the new part does not support the event that originally fired the link, a pop-up list of available events is displayed. If the part does support the same event, then the link is simply moved.

2 Select an event from the list if necessary.

The link origin is moved.

or


2 Choose Change origin.

A rubber-band line follows the cursor until you click on the new origin.



3 Click on a new part.

If the new part does not support the event that originally fired the link, a pop-up list of available events is displayed. If the part does support the same event, then the link is simply moved.


The link origin is moved.

Changing a Link’s DestinationTo change the destination part of a link:

1 Shift <drag> the message connection to a new destination.

If a new part does not support the message that the link originally sent, a pop-up list of available messages is displayed. If the part does support the same message, or if you move an argument link to an event value or result connection, then the link destination is simply moved.

2 Select a message from the list if necessary.

The link destination is moved.

or

> Drag a new link from the argument or result connection of an existing argument or result link.

or


2 Choose Change destination.

A rubber-band line follows the cursor until you click on the new destination.

3 Click on a new destination.

Event and result links use parts as destinations. Argument links use event value connections, result connections or parts.

If a new part does not support the message that the link originally sent, a pop-up list of available messages is displayed. If the part does support the same message, or if you move an argument link to an event value or result connection, then the link destination is simply moved.


Sequencing Event Links


The link destination is moved.

Sequencing Event LinksThe link sequence is the order in which multiple links triggered by a single event on the same part are fired.

The firing sequence for links determines the execution order of the messages attached to the links.

By default, a part with multiple links triggered by the same event will fire the links in the order that you created the links.

To change the event link firing sequence for a part:

1 Select the part.

2 Choose Selected/Sequence links... from the workbench menu bar.

A Sequence Links dialog is displayed.

3 Drag the link you want to resequence up or down the Link firing sequence list.

4 Click the OK button when you are through re-ordering the list, or click Cancel to restore the original order.

The links do not change their appearance in your application as a result of this re-ordering. You can open this Sequence Links dialog at any time to verify the firing sequence.

The push button’s clicked event fires two different links.



If one of the links in the list initiates a chain of argument or result links, all the links in the chain are fired before the next link in this list.


CHAPTER

7
Displaying Links
This chapter describes how to control the display of links and their various features. As you build more complex applications, you will find the ability to display links and labels in different levels of detail particularly useful for focusing on specific pieces of logic.

See chapter 5, Events, Messages, and Links, for more information on what links, events, and messages are and what they do in your application.


• Link Layout

• Link Visibility

• Labels

• Scenarios

• Display Preferences for Links and Labels

Link LayoutThere are a number of options for controlling the layout of links in your application.

When you create or modify a link, the default setting is to lay the link out orthogonally. This means that if the link’s path from its origin to its destination is not a straight horizontal or vertical line, then the link is drawn from straight lines meeting at right angles.

The topic Display Preferences for Links and Labels discusses how to change this default setting.

See appendix A, Menu and Toolbar Quick Reference, for a summary of menu and toolbar operations for the workbench.

See appendix B, Mouse Actions Quick Reference (Windows), or appendix C, Mouse Actions Quick Reference (OS/2), for a summary of mouse operations for the workbench.


Displaying LinksCHAPTER 7

Overriding the Default Layout Setting for Creating a LinkTo override the default link creation setting:

1 Hold down the Ctrl key.

2 Draw the link.

If Orthogonal link creation is the chosen default, the link will be drawn as a straight line between its origin and its destination regardless of the angle.

If Orthogonal link creation is not the chosen default, then the link will be drawn orthogonally.

Adding a Control Point while Creating a LinkYou can add control points as you draw a link.

To add a control point while drawing a link:

1 Start drawing the link.

2 Press the Space bar or click the other mouse button while drawing the link to create a control point.

Adding a Control Point after a Link is CreatedBy default, when you add a control point, the link is adusted in accordance with the default layout setting. You can, however, override the default setting when adding a control point.

To add a control point to a link using the default layout setting:

> Drag any point on the link line to a new control point location.

If you release the button without moving the mouse, a control point is not added. While still dragging, you can press the Esc key to cancel the operation.

To add a control point to a link using the alternate layout setting:


2 Drag any point on the link line to a new control point location.

If you release the button without moving the mouse, a control point is not added. While still dragging, you can press the Esc key to cancel the operation.


Link Visibility

Moving a Control PointBy default, when you move a control point, the link is adusted in accordance with the default layout setting. You can, however, override the default setting when adding a control point.

To move a control point using the default layout setting:

> Drag the control point to a new location.

While still dragging, you can press the Esc key to cancel the operation.

To move a control point using the default layout setting:


2 Drag the control point to a new location.

Deleting a Control PointDeleting a control point has no effect on program execution.

To delete an individual control point:

> Drag the control point onto another control point or onto a link connection.

To delete all control points from a link:

1 Click on one of the link’s handles with mouse button 2 to select the Link pop-up menu.

2 Choose Delete all control points.

Link VisibilityIn a very simple application, it may be sufficient to view all of the links at once. In moderately complex applications, however, you need to be able to view links selectively so that you don’t become overwhelmed by the complexity of the links.

Displaying Links Connected to Selected PartsSelectively displaying links by the part that they are connected to can help you understand the role that the part plays in your application.



To display all links connected to the selected part(s):

> Choose Selected/Show links from the workbench menu bar.

or

> Click on the Show links button on the workbench tool bar.

or

> <Shift> click with mouse button 2 on a part.

To display all incoming event and result links that send messages to the selected part(s):

> Choose Selected/Show incoming links from the workbench menu bar.

or

> Click on the Show incoming links button on the workbench tool bar.

These commands will not display incoming argument links.

To display all outgoing event links from selected part(s):

> Choose Selected/Show outgoing links from the workbench menu bar.

or

> Click on the Show outgoing links button on the workbench tool bar.

If any of the outgoing event links have result links chained off of them, the result links are also displayed.


Link Visibility

To automatically display only the links attached to the current selection:

> Choose View/Show links with selection from the workbench menu bar.

This toggle is turned off by default. When you toggle it on, a check mark appears before the menu item and you only see links attached to the current selection. When you deselect the current selection links are turned off.

Displaying Specific Links Attached to a Selected PartTo display specific links attached to a selected part:

1 Choose Selected/Show some links.

The Show Some Links dialog is displayed.

2 Select specific links from the left hand list panes and/or specific parts from the right hand list panes.

The top-left list pane lists all the messages which are sent to the part by links. The bottom-left list pane lists all the events which fire links from the selected part. Selecting an item from either of the left hand list panes selects the associated link for display.

The top-right list pane lists all the parts which originate a link to the selected part. The bottom-right list pane lists all the parts that serve as destinations for links originating from the selected part. Selecting an item from either of the right hand list panes selects all the links connecting the selected origin and destination parts for display.

3 Click the OK button when you are finished making selections.

The selected links are displayed.

If a selected message is sent by an argument link, the link that sends the message from which the argument link



originates will be displayed but not the argument link itself. You can display the argument link by expanding link labels.

Displaying All LinksThis is usually only useful for simple applications; for complex applications, the resulting display is often too visually complex to be useful. For complex applications, you should use one of the techniques for displaying links attached to selected parts.

To display all the event and result links:

> Choose View/Show all links from the workbench menu bar.

By default, all links are displayed without labels.

To display all argument links:

1 With all event and result links visible, choose View/Show labels from the workbench menu bar.

Unexpanded labels are displayed for all visible links.

Select the entry field.

Choose View/Show some links, select the value message, and click the OK button.

Only the event link from the push button to the speaker is displayed.

Expand labels to view the argument link which sends the value message to the entry field.


Labels

2 Choose View/Expand labels from the workbench menu bar.

Labels are expanded and argument links are displayed. Argument links are only visible when labels are expanded.

or

> With all event and result links visible, click on the Show expanded labels button on the workbench tool bar.

Hiding LinksUse these commands to limit the complexity of the logic that you are trying to understand.

To hide all links:

> Choose View/Hide all links from the workbench menu bar.

or

> Click on the tool bar’s Hide all links button.

To hide an individual link:

1 Invoke the link Pop-up menu for the link you want to hide by clicking on one of its link handles with mouse button 2.

2 Choose Hide link.

To hide all links connected to the current selection:

> Choose Selected/Hide links from the workbench menu bar.

Labels

Showing Link LabelsLink labels provide a lot of information about their links including the event that fires the link as well as any values that the event offers, and the message sent by the link as well as any arguments that the message requires.

To display unexpanded labels on all currently displayed links:

> Choose View/Show labels from the workbench menu bar.

or

> Click the Show labels button on the workbench tool bar.

This button works when labels are off or when labels are expanded.



To display unexpanded labels on an individual link:

> Double-click on the link handle of a link with no labels showing.

Double clicking on a link handle cycles through the three label display states: hidden, unexpanded, and expanded.

or


2 Choose Show labels.

To automatically view labels whenever links are visible:

> Choose View/Show labels with links from the workbench menu bar.

This is a toggle: when it’s on, a check mark appears in front of the menu item and labels are always displayed whenever a link is displayed. The default is off.

To display expanded labels for all currently displayed links:

> Choose View/Expand labels from the workbench menu bar.

or

> Click the Show expanded labels button on the workbench tool bar.

Hiding LabelsTo hide labels for all links currently displayed:

> Click on the Hide labels button on the workbench tool bar.

or

> Choose View/Hide Labels.

To hide labels for an individual link:

> Double-click on a link handle of a link with expanded labels.

Double clicking on a link handle cycles through the three label display states: hidden, unexpanded and expanded.

or


2 Choose Hide labels.


Scenarios

Moving Link LabelsTo move a link label:

> Drag the label to a new location.

ScenariosScenarios provide higher level abstractions for controlling the display of multiple links. You can display the links associated with a scenario by themselves or in addtition to the links currently displayed. The currently defined scenarios are displayed in a drop-down list on the right side of the workbench’s tool bar.

Adding and Removing ScenariosScenarios have no impact on links other than their display. For instance, deleting a scenario doesn’t delete the links that it grouped.

Scenarios are designed to be flexible so that you can use them in the way that makes the most sense for your development process. You should, however, set standards for what a scenario represents in your applications and how they should be named.

To create a new scenario:

1 From the workbench’s menu bar, choose the Scenarios/New... command.

A prompter requesting a new scenario name is displayed.

2 Enter a name for the scenario and click the OK button.

The new scenario is added to the drop-down list located on the right side of the tool bar.

To remove a scenario:

1 From the drop-down list on the right side of the workbench’s tool bar, select the scenario that you want to delete.

2 From the menubar, choose Scenario/Remove scenario.

The selected scenario is removed from the list. Removing the scenario does not remove its links.



Adding Links to and Removing Links from a ScenarioScenarios are empty when first created. Deleting a scenario or removing links from a scenario has no effect on the links themselves.

To automatically add new links to the selected scenario:

> From the menubar, choose Scenario/Add new links.

This is a toggle setting. As long as this menu item is checked, new links are automatically added to the currently selected scenario.

To add visible links to the secleted scenario:

> From the menubar, choose Scenario/Add visible links.

To replace all of the links assigned to the selected scenario with visible links:

> From the menubar, choose Scenario/Substitute visible links.

To remove a single link from the selected scenario:

1 Select the link pop-up menu for the link that you want to remove.

2 Choose Remove from scenario.

To remove visible links from the selected scenario:

> From the menubar, choose Scenario/Remove visible links.

To clear the selected scenario of all assigned links:

> From the menubar, choose Scenarios/Clear links.

Displaying ScenariosYou can set your environment so that all visible links are hidden before displaying a new scenario or so that the scenario’s links are displayed in addition to the visible links.

The inclusion of a link in a scenario does not interfere with your ability to show or hide it independent of its scenario. If you have hidden some of the links in a scenario there is a command that allows you to refresh the display showing all of the links belonging to the selected scenario.


Scenarios

To automatically hide visible links before displaying the links belonging to a scenario:

1 From the menubar, choose Scenarios.

The Scenarios menu is displayed. If the Exclusive displays item is checked, visible links are automatically hidden before the links assigned to a scenario are displayed.

2 If the Exclusive displays item is not checked, choose it.

To insure that all links assigned to the selected scenario are displayed:

> Choose Scenarios/Display scenario.

This is useful if you have been using other link visiblity options to hide individual links.

Renaming ScenariosRenaming a scenario has no impact on the links that it groups.

To rename a scenario:

1 From the drop-down list on the right side of the workbench tool bar, select a scenario.

2 From the workbench’s menu bar, choose the Scenarios/Rename scenario... command.

A prompter requesting a new name is displayed.

3 Enter a name for the scenario and click the OK button.

The drop-down list is updated.

Commenting a ScenarioScenario comments serve the same purpose as comments in written code. Comments are entered, edited, and displayed in a comment window. Each workbench has its own comment window for commenting scenarios.

To add or edit a scenario comment:

1 From the drop-down list on the right side of the workbench’s tool bar, select the scenario that you want to comment.

2 From the menu bar, choose the Scenario/Comment... command.

A Comment window is displayed.



3 Enter a comment in the text field and click the Save button.

4 Click on the Close button.

To view scenario comments:

1 From the menu bar, choose the Scenario/Comment... command.

A Comment window showing the comment for the currently selected scenario is displayed.

2 Set the Always above workbench checkbox for the desired behavior.

If the checkbox is checked, the comment window is displayed above the workbench when they overlap. If the checkbox is unchecked, the comment window behaves like a normal window.

The comment window is automatically updated whenever you choose a different scenario.

3 Click on the Close window when you are finished viewing comments.

Pairing ScenariosYou can pair an application’s scenario with a scenario in one or more of the application’s nested parts. For example, if the application and one of its nested parts both have an Adding customer scenario, you can pair them. If you then edit the nested part while the application’s Adding customer scenario is selected, the same scenario is selected when the nested part is displayed. The scenarios don’t have to have the same name to be paired.

To pair a scenario with a nested part’s scenario:

1 From the drop-down list on the right side of the tool bar, select the first scenario of the pair.

2 From the menu bar, choose the Scenario/Scenario pairings... command.

A dialog is displayed.

3 Seclect a nested part.

4 Select one of the nested part’s scenarios.



Display Preferences for Links and Labels

Display Preferences for Links and LabelsYou can choose the default setting for three link properties: Show labels with links, Show links with selection, and Link colors.

Show Labels with LinksWhen Show labels with links is turned on, unexpanded labels are displayed when a link is first displayed.

To change the default settings for displaying labels for all applications:

1 Choose File/Settings from the workbench menu bar.

The Settings window is displayed.

2 Click on the check box for Show labels with links.


The selected setting is used whenever you open a new workbench.

To change the default settings for displaying labels for the current application only:

> Choose View/Show labels with links from the workbench menu bar.

This command is a toggle. A check appears next to the command when the option is turned on. This setting remains in effect until you change it or until you close the workbench.

Show Links with SelectionWhen Show links with selection is turned on, all links attached to the current selection are displayed.

To change the default settings for displaying links for all applications:



2 Click on the check box for Show links with selection.





To change the default settings for displaying links for the current application only:

> Choose View/Show links with selection from the workbench menu bar.

This command is a toggle. A check appears next to the command when the option is turned on. This setting remains in effect until you change it or until you close the workbench.

Orthogonal Link CreationWhen Orthogonal link creation is checked, all links are drawn orthogonally when they are created or modified. Overriding the default setting can be done on a link-by-link basis and is discussed in the topics that cover creating and modifying links.

To change the default settings for laying out links for all applications:



2 Click on the check box for Orthogonal link creation.



Link ColorThe color of a link indicates its type and whether or not it is complete. A complete link has values supplied for all of its message arguments. The color and appearance of an argument connection also indicates whether or not an argument is satisfied. An application can be executed if it has incomplete links, but unsatisfied arguments have the value nil.

Default Link Colors

Object Complete Incomplete

Event/Result Link Green Red

Argument Link Blue Pink


Display Preferences for Links and Labels

NOTE: You can reset the colors to the last applied settings by clicking on the Reset button. You can reset the colors to the system defaults by clicking on the Defaults button.

To change the default link color settings:



2 Click on the Link colors... button.

The Link Color Settings window is displayed.

3 Select the desired colors.

4 Click on the Apply button to test changes without closing the window.

5 Click on OK when you are done.


NOTE: The Color Settings window is independent of the Settings window. You can close the Settings window at anytime while leaving the Color Settings window open.


CHAPTER

C8
onstructing New Parts
This chapter focuses on building parts for use as components in other parts.

The following topics are discussed in this chapter:

• Anatomy of a Part

• Reasons for Constructing New Parts

• Part File Reuse Options

• YesNo Part—External Interface (tutorial)

• YesNo Part—Internal Implementation (tutorial)

• Defining an External Interface

• Browsing Nested Parts

• Browsing References to a Nested Part

• Browsing Implementors of a Nested Part

Anatomy of a PartA part consists of the following:

• An external interface.

This is comprised of the events and messages to which you can connect links after you place the part in a workbench. The Part Reference documents the external interface for each of the parts in the PARTS catalog.

• An internal implementation.

This is comprised of the parts, links, and scripts that do the actual work of your new part. The internal implementation of a part can, in turn, include other parts. The internal implementation of all parts is packaged inside of an application part.


Constructing New PartsCHAPTER 8

Figure 8-1: Schematic Diagram of a Part

• The part’s properties.

Properties allow you to specify various part states and store descriptive information about the part.

Everything that you build in a workbench, whether it is a complex application or a simple component, is a part. You can confirm this with any workbench by completing the steps below:

1 Select the background of a new workbench and press <Ctrl> I.

An External Interface window is displayed showing that the part has an external interface consisting of the open message. Everything you build has this default external interface. You can add additional events and messages to this default interface.

2 Add parts to the workbench and connect them with links.

You are building your part’s internal implementation using existing parts.

3 Double-click on a workbench background.

The Properties dialog for any part that you build or edit in the workbench is displayed.

As a part user, you are mainly concerned with a part’s external interface—the events and messages to which you can connect links. As a part builder, you are responsible for providing and maintaining the part’s external interface and its internal implementation.

Nested parts provide the actual mechanism for using a part in another part. A nested part references a part and surfaces the referenced part’s external interface. See the Nested Part chapter in the Part Reference for complete details on using a part that you build in a workbench.

external interface

internal Implementation

application part


Part File Reuse Options

NOTE: You can also build new parts with Smalltalk, as explained in the Visual Smalltalk Enterprise User’s Guide.

Reasons for Constructing New Parts• Modularity

Packaging functionality as a new part hides implementation details and provides an external interface that is independent of the internal implementation. This makes your system easier to use, easier to test, and more reliable since you can use pre-tested parts.

• Readability and UnderstandabilityAs you start building and browsing applications, you’ll see that the workbench quickly becomes crowded with parts and links. Breaking up the application into subsystems, each contained in a part, makes your application easier to understand.

• Workbench PerformanceCertain types of parts are only loaded when needed, allowing the application to load and execute more quickly. See the Nested Part and Part Accessor chapters in the Part Reference for more information.

• Reuse of Customized PartsIf you often use a part from the catalog and customize it in the same way—centering the text in an entry field, for example—it is handy to make a new part with your customizations.

Part File Reuse OptionsEach part has a choice of three reuse options that affect what happens to the part when you add it to another part. These options are introduced in this topic. See the Nested Part chapter in the Part Reference for a complete description of these options and their implications.

You can view and change a part’s reuse modes in the application part’s Properties dialog (double-click on the workbench background to open the application part’s Properties dialog):

• Packaged part (linked)—the default setting

• Packaged part (embedded)



• Ensemble of parts

Here is the default Properties dialog for an application part showing these reuse options:

Ensemble Reuse OptionThe ensemble reuse option is fundamentally different from the other two because it specifies that you don’t intend to reuse the contents of the part as a single new part. When you add an ensembled part to a workbench, the packaging and the part’s external interface are thrown away. The ensembled part’s contents (including its child parts, links that interconnect the child parts, and scripts attached to the child parts) are merged with the other parts in the workbench

Reuse options


Part File Reuse Options

.

Ensembles are useful when you want to access the individual parts in the ensemble without the extra level of abstraction provided by the packaging and its external interface; for example, if you often use a particular combination of parts and links.

Packaged PartsIf you assemble a number of parts and links that you want to use as a single new part, you should use one of the two packaged part options: linked or embedded. Using either option, you include the new part in an application via a nested part. See the Nested Part chapter in the Part Reference for more information. You can also reuse packaged parts with a part accessor. The part accessor always loads a part from its source file; see the Part Accessor chapter in the Part Reference for more information.

Linked Reuse ModeIf the part’s reuse mode is linked, the nested part that references the part maintains a link to the original file, ensuring that the application uses the most current version of the part.

Embedded Reuse ModeIf the part’s reuse mode is embedded, the nested part that references the part takes a snap shot of the original file and adds it to the contents of the nested part’s parent. From then on, the nested part references the snapshot stored in its parent rather than the original part file. If you want to take advantage of updates to the source file, you must explicitly reload the referenced part.

Reusing PART B inside of PART A as an ensemble of parts—PART B loses its packaging and no longer exists as a distinct part inside of PART A.

PART A

PART B



YesNo Part—External InterfaceThis topic is a tutorial demonstrating how to build the external interface for a custom confirmer part that includes a company logo. The external interface consists of the events and messages to which you connect links when you are using the part in an application.

A part’s external interface is separate from its internal implementation. In fact, you can build the external interface before you implement the part. At that point, the part is simply a shell; it doesn’t actually do anything. But you can add it to another part and link to it as though it was a finished part—perhaps while another developer completes or fine tunes the implementation of the new part.

This highlights one of the benefits of the external interface. The application doesn’t know anything about the internal implementation of a part, which may change to take advantage of performance enhancements or changing requirements; the application that uses a part only links to the external interface which shouldn’t change.

The YesNo part icon and its finished external interface are illustrated below. In the procedures that follow, you build the YesNo part’s external interface for yourself.

YesNo messages

YesNo part icon

YesNo events


YesNo Part—External Interface

To build the external interface of the YesNo part:1 Open a new workbench.

New parts have their reuse mode set to Linked packaged part by default. Leave it set this way for this part.

2 Choose Selected/Edit interface... from the workbench menu bar.

An External Interface window is displayed.

3 With the Messages radio button selected, click on the New... button.

A dialog requesting the name of the new message is displayed.

4 Enter the text “openMessage:” without the quotes.


openMessage: now appears below the standard open message.

NOTE: A message with a colon in its name requires an argument. An event with a colon provides a value. See chapter 5, Events, Messages, and Links, for more information.

6 Click on the Events radio button.

7 Click on the New... button.

A dialog requesting the name of the new event is displayed.

8 Enter the text “confirmed” without the quotes.


confirmed is displayed in the event list.

10 Repeat steps 7 through 9, this time adding a canceled event.





12 Save the file as YESNO.PAR.

Save the part in one of the directories located on your PARTS Workbench search path. Linked parts must be stored in a location listed in the PARTS Workbench search path.

(Optional) To customize the YesNo part’s Properties:1 Double-click on the workbench background.

The application’s Properties dialog is displayed.

2 Click on the Edit Icon button.

An Icon Editor is opened.

3 Choose File/Open... from the Icon Editor’s menu bar.

An Open dialog is displayed.

4 Use the dialog to open the file YESNO.ICO in the TUTORIAL subdirectory of your PARTS Workbench installation directory.

The YesNo icon is displayed.

5 Click on the Apply button.

This is the icon that is displayed in a catalog and also on the workbench if the nested part referencing the YesNo part is shrunk.

6 Double-click on the Icon Editor’s control-menu box to close the editor.

7 In the Properties dialog, change the Part name property to “YesNo”.

8 Change the Hint property to the following: “A confirmer with a company logo.”

This text is displayed in the information area at the bottom of the workbench when you place the cursor over the part.


10 Save the YesNo part.



(Optional) To add the YesNo part to a Catalog:1 Click on the PARTS catalog’s File... button.

A pop-up menu is displayed.

2 Choose New.

An empty untitled catalog is displayed.

3 Click on the untitled catalog’s File... button.

4 Choose Insert part file.

An Insert Part File dialog is displayed.

5 Select YESNO.PAR and click on the OK button.

The YesNo part is inserted into the catalog.

6 Click on the untitled catalog’s File... button.

7 Choose Save.

A Save catalog As dialog is displayed.

8 Enter CUSTOM.CAT as the file name and click on the OK button.

To emphasize the independence of the external interface from the internal implementation, you will now build a simple application that uses a YesNo part even though the YesNo part doesn’t do anything yet.

To build an application that uses the YesNo part:1 Open a new workbench.

2 Drag a window from the PARTS catalog and drop it on the workbench.

3 Drag a push button from the PARTS catalog and drop it in the window.

4 Alt<click> on the button to direct-edit its label.

A text cursor is displayed in the button’s label area.

5 Enter the following text without quotes: “Close”.

6 Click on the workbench background to exit the direct edit mode.

7 Choose the Edit/Import part... command. (If you inserted the YesNo part in a catalog, simply drag the part from the CUSTOM catalog, drop it on the workbench, and proceed to step 11).

An Import Part dialog is displayed.



8 Use the dialog to locate YESNO.PAR, select it.


The cursor becomes the YesNo part icon (if you did not customize the icon, you will see the standard parts application icon).

10 Click on the workbench background to place the part.

The part is displayed as an icon.

11 With the link mouse button , drag a link from the workbench background to the YesNo part.

A Create Link dialog is displayed.

12 Select openMessage: from the list of messages on the right.

Notice that from your viewpoint as a user of the YesNo part, it appears to be fully functional.




A red event link is created between the workbench and the YesNo part.

Now you need to supply a message as an argument to openMessage:.

14 From the PARTS catalog, drag a string holder and drop it onto the workbench.

15 Alt<click> on the string holder to direct-edit its contents.

A text cursor is displayed in the string holder.

16 Enter the following text without quotes: “Ring bell before closing?”.

17 Click on the workbench background to exit the direct-edit mode.

18 With the link mouse button, drag a link from the argument connection on the openMessage: label to the string holder.

A Create Argument Link dialog is displayed.

19 Select the value message from the message list on the right.

An argument link is created from the openMessage: argument connection to the string holder.



Now you need to link the YesNo part’s events to the application. If the user clicks the No button, you simply want to close your application.

20 With the link mouse button, drag a link from the YesNo part to the window.


21 Select the YesNo part’s canceled event from the event list on the left and the window’s close message from the message list on the right.


A link is created from the YesNo part to the window.

If the user clicks the Yes button, you want to ring a bell and then close the application.

23 From the PARTS catalog, drag a speaker part and drop it on the workbench.

24 With the link mouse button, drag a link from the YesNo part to the speaker.


25 Select the YesNo part’s confirmed event from the event list on the left and the speaker part’s ring message from the message list on the right.




A link is created form the YesNo part to the speaker.

27 With the link mouse button, drag an event link from the YesNo part to the window.


28 Select the YesNo part’s confirmed event from the event list on the left and the window’s close message from the message list on the right.


An event link is created from the YesNo part to the window.



31 Use the dialog to save the application as TEST.PAR.

Before you can test your application, you need to implement the YesNo part. See YesNo Part—Internal Implementation for information on implementing the YesNo part.



YesNo Part—Internal ImplementationThe internal implementation of a part is independent of the external interface. You are free to implement the part in any manner that you deem appropriate. You are also free to change the parts’s implementation at any time. Application builders who use your part in their applications don’t need to know how your part accomplishes its task; they only need to know its external interface.

By the same token, you don’t need to know what is happening outside of your part, you are only responsible for supporting the external interface. In the topic YesNo Part—External Interface, we said that the YesNo part’s external interface should include the following:

• A message that allows the user to open the YesNo dialog with a specific message

• An event signalling that the Yes button has been clicked

• An event signalling that the No button has been clicked

As you implement the YesNo part, you must consider what these elements of the external interface mean to you as the part builder.

• When should your part open the dialog?

There should be an event that signals your part to open its dialog with a specific message.

• How do you tell the application that the Yes button has been clicked?

The Yes button should send a message indicating that it has been clicked.

• How do you tell the application that the No button has been clicked?

The No button should send a message indicating that it has been clicked.

Fortunately, you don’t need to create these events and messages. They were automatically created when you built the external interface.

• For every external message that you add to the external interface, an identically named event is added to the part’s internal implementation (you create a link from this event by dragging the link from the workbench background). Sending the external message (which is part of the part’s external


YesNo Part—Internal Implementation

interface) to the part triggers the corresponding event in the part’s internal implementation.

• For every external event that you add to the external interface, an identically named message is added to the part’s internal implementation (you create a link to this message by dragging the link to the workbench background). When a part within the part that you are building sends an internal message to the application part, the corresponding external event (which is part of the external interface) is triggered.

Figure 8-2: Schematic Diagram of an Application Reusing a Part

In the following procedures, you will implement the YesNo part. If you have closed the YesNo part, you need to re-open it.

Nested Part

The nested part makes the YesNo part’s external events and messages (its external interface) visible to the containing application.

When you explicitly add this external event to the YesNo part’s external interface...

...this message is automatically added to the YesNo part’s internal implementation (the completed YesNo part is used here for illustration)



To build the YesNo part’s user interface:1 Drag a dialog window from the PARTS catalog and drop it on the

YesNo part’s workbench background.

2 <Alt>click on the dialog window to direct-edit it.

A text cursor is displayed in the dialog window’s title bar.

3 Enter the following text without quotes “Please Confirm”.


5 Drag a static text from the PARTS catalog and drop it in the dialog window near the top.

6 Resize the static text so that it is almost as wide as the dialog window.

7 Drag two push buttons from the PARTS catalog and drop them side-by-side in the dialog window below the static text.

8 <Alt> click on the left-most push button to direct-edit its label.

A text cursor is displayed in the label area of the push button.

9 Enter the following text without quotes: “Yes”.


Static text with resize handles showing.



11 Repeat steps 8 through 10 for the second button, changing its label to “No”.

12 Drag a static graphic from the PARTS catalog and drop it in the dialog window between the two push buttons.

13 Double-click on the static graphic to open its Properties dialog.

14 (OS/2) Click on the Icon radio button.

15 Click on the Edit graphic... button.

An Icon Editor is displayed.

16 Choose File/Open... from the Icon Editor’s menu bar.

An Open File dialog is displayed.

17 Select the file LOGO.ICO in the TUTORIAL subdirectory of your Visual Smalltalk or Visual Smalltalk Enterprise directory and click the OK button.

The logo is displayed in the Icon Editor.

18 Click on the Apply button.

19 Double-click on the Icon Editor’s control-menu box to close the Icon Editor.



20 In the static graphic’s Properties dialog, click the OK button.

The sample company logo is displayed between the two push buttons.

To implement the YesNo part’s behavior:1 Drag a link from the Yes button to the dialog window.


2 Select the Yes button’s clicked event from the event list on the left and the dialog window’s close message from the message list on the right.


A link is created from the Yes button to the dialog window.

4 Drag a link from the Yes button to the workbench background.


5 Select the Yes button’s clicked event from the event list on the left and the application’s confirmed message from the message list on the right.

The confirmed message was automatically created when you added the confirmed event to the external interface.


A link is created from the Yes button to the workbench background.



7 Repeat steps 1 through 6 for the No button, creating the second link to the canceled event instead of the confirmed event.

The dialog window doesn’t have a message corresponding directly to the external interface’s openMessage: message, so you have to use two links to implement this message: one to set the message displayed by the dialog window and one to open the dialog window.

8 Drag a link from the workbench background to the static text.


9 Select the application part’s openMessage: event from the event list on the left and the static text’s setValue: message from the message list on the right.

The openMessage: event was automatically created when you added the openMessage: message to the external interface.


A link is created from the workbench background to the dialog window.



11 Create a second link from the application part’s openMessage: event to the dialog window’s open message.

You don’t need the event value of the openMessage: event for this link.

12 Save your work.

You have already built the application that uses the YesNo part: TEST.PAR. If you closed TEST.PAR, go ahead and re-open it now. Launch TEST.PAR and click on the close button. The YesNo part’s dialog is displayed. If you click the Yes button, the speaker rings and the dialog closes. If you click the No button, the dialog closes without the ringing sound.

When you use a part in an application, you can only create links using those events and messages that have been explicitly defined in the part’s external interface by its builder.

For example, the dialog window inside the YesNo part understands the setLabel: message which you can use to change the text appearing in the title bar. But the YesNo part’s external interface doesn’t support this capability. If you create a link from the Close button in TEST.PAR to the YesNo part you will see that the setLabel: message does not appear in the YesNo part’s external interface: only the standard open message common to all application parts and openMessage: which you explicitly added to the external interface are visible.


Defining an External Interface

If you decide (as the builder of the part) that users should be able to set the label, you can add a message to the interface that allows them to do this.

Defining an External InterfaceAs the builder of a part, you must define its external interface. The external interface is made up of external events and messages that you specify in an application part’s External Interface window.

To open an External Interface window, perform one of the following procedures:

> Click on the workbench background to select the application part and press Ctrl+I.

or

> Click on the workbench background to select the application part and choose the Selected/Edit interface... command.

or

> Double-click on the workbench background to bring up the application part’s Properties dialog and press the Interface... button.

NOTE: If you decide to add messages or events to the external interface of a part referenced by a nested part, you must open a workbench on the referenced part and open the referenced part’s External Interface window using one of the techniques described above.

If you apply one of these techniques directly to the nested part that references the part, an Interface window for the nested part is opened. Messages and events entered in this window are added to the nested part’s interface—not the external interface of the referenced part.



To add a new event to the external interface:

1 Select the Events radio button in the External Interface window.

2 Press the New... button.

3 Enter the name of the new external event in the prompter and click on the OK button.

The event is added to the part’s external interface. A new internal message of the same name is automatically added to the part.

To add a new message to the external interface:

1 Select the Messages radio button in the External Interface window.

2 Press the New... button.

3 Enter the name of the new external message in the prompter and click the OK button.

A new internal event of the same name is automatically added to the part.


Defining an External Interface

External Interface Event and Message SyntaxExternal events and messages follow the same syntax established by regular events and messages. By convention, embedded words are capitalized.

Indicate argument positions with colons. For example, the external message at:put: takes two arguments.

Exporting Events and Messages from a PartYou can also define events and messages for a part’s external interface by exporting the events and messages of a child part using the Export button in the child part’s Interface window.

This button does three things automatically:

1. Adds the selected event or message to the parent part’s external interface.

2. If an event is selected, a corresponding internal message is added to the parent part; if a message is selected, a corresponding internal event is added to the parent part.

3. Creates a link from the child part’s exported event or message to the parent part’s corresponding internal message or event.

For example, when you export a push button’s clicked event, an internal clicked message and an external clicked event is added to the containing part, and a link is created from the push button’s clicked event to the part’s internal clicked message.

➊➋The push button’s

clicked event is exported to the external interface of the containing application. ➌



Clicking on the push button at runtime does the following:

1. Triggers the push button’s clicked event.

2. The clicked event fires the link.

3. The link sends the internal clicked message to the application part.

4. The message triggers the external clicked event.

Browsing Nested PartsYou can view a hierarchical list of the nested parts contained in a selected part.

To view a list of the nested parts in the selected part:

> Choose Selected/Browse/Nested part explosion from the workbench menu bar.

A Browse Nested Part Explosion window is displayed. You can display information about an individual part by selecting it. You can also open the selected nested part, or open a Set Search Scope dialog on the selected part.

Browsing References to a Nested PartYou can search the PARTS Workbench search path (or a portion of it) for files that reference the selected nested part. Searching can be a time consuming operation so, when possible, you should limit the search to specific directories.

To search the PARTS Workbench search path (or a portion of it) for files that reference the selected nested part:

1 Choose Selected/Browse/References from the workbench menu bar.

A Set Search Scope dialog is dsplayed.

2 Select the desired search parameters and click on the Search button.

The results of the search are displayed in a window which is the same in function as a Browse Nested Parts Explosion window.


Browsing Implementors of a Nested Part

Browsing Implementors of a Nested PartYou can search the PARTS Workbench search path for files that have the same name as the selected nested part. The search algorithm does not attempt to compare the contents of the files to see if they really implement the same part.

To search the PARTS Workbench search path for parts with the same name as the selected nested part:

> Choose Selected/Browse/Implementors from the workbench menu bar.

A window listing all of the parts with the same name as the selected nested part is displayed. From this window you can open the parts or browse references to them.


CHAPTER

9
User-Defined Messages and Events
This chapter discusses the capability of extending the standard interface of a part by adding new messages and events. You add new messages and trigger new events by writing methods in a Smalltalk-like scripting language called PARTStalk. The following topics are covered:

• What is PARTStalk?

• When to Extend the Interface of a Part with Scripts

• Adding a Message to a Part’s Interface

• Editing a User-Defined Method Definition

• Deleting a User-Defined Message

• Adding an Event to a Part’s Interface

• Deleting an Event from a Part’s Interface

• Managing User-Defined Methods

• Displaying User-Defined Methods for all Parts

• Triggering a User-Defined Event

• Using Part Names in User-Defined Methods

• Printing Interface Reports

What is PARTStalk?PARTStalk has virtually all of the same language and syntax features as Smalltalk. A PARTStalk method looks just like a Smalltalk method with the exception that a PARTStalk method selector must begin with a capital letter.

The main difference between PARTStalk and Smalltalk is that PARTStalk is instance based. This has two implications:

1. PARTStalk methods are defined for a specific instance of a class only. So if you add a new method, for example foo, to a list pane part using a script, foo is only implemented for that specific list pane. If you try to send foo to a different list pane, you won’t find foo listed in any of the link dialogs.

See appendix A, Menu and Toolbar Quick Reference, for a summary of menu operations for the Part Interface window.


User-Defined Messages and EventsCHAPTER 9

2. You cannot define new classes in PARTStalk but you can create instances of any existing classes.

When to Extend the Interface of a Part with ScriptsThe two situations in which you will consider extending the interface of a part with scripts are:

• adding new functionality (methods and events) to a part

• replacing links (a special case of adding new functionality)

The alternative to extending a part’s standard interface with scripts is using Smalltalk to either create a new object or modify the existing object.

In general, extending a part’s interface with scripts is most appropriate in situations where one or more of the following statements apply (the more statements that apply, the more appropriate):

• ad-hoc development of simple applications

• interface or application specific functionality

• needed fuctionallity requires only a small number of scripts in a part

• needed functionality requires adding scripts to only a limited number of parts in the application

Looking at it from the opposite perspective, if you are developing a complex application, if the functionality would be a generally useful addition to all instances of the class, if you are adding a lot of scripts to a single part, or if you are adding a few scripts to many parts, you should consider writing Smalltalk code instead of PARTStalk scripts.

Adding New FunctionalityWhen developing in a workbench, scripting is a fast and easy way to add a new method or event to a part. Used with discretion, they can be a powerful tool. Remember that functionality added in this way is limited to a single instance of a class. Also, script code is not visible in the class hierarchy browser or package browser which may make it seem less visible.


Adding a Message to a Part’s Interface

Replacing LinksLink based programming has a number of advantages over writing code:

• compared to learning the vocabulary and syntax of a new language, linking is simple

• links can make the logic of the application quickly apparent because of their visual nature

• links are more reliable because there are fewer opportunities for errors such as mispelling a message name

Link based programming does have some limitations. It is best suited to specifying fairly high level logic. Although it is possible to program a loop, for example, using a combination of links and parts, it is much more efficient and the resulting logic is much more understandable when programmed in PARTStalk or Smalltalk code. Which should you use, PARTStalk or Smalltalk?

If you find yourself wanting to replace parts and links with code, or if the number of parts and links seems excessive, be alert to the possibility of a new object. By generalizing the problem, or by combining it with other related problems you may find justification for creating a new class of object in Smalltalk which can more naturally provide the behavior and attributes that you need. Once defined, you can add an instance of the new object to the workbench and link it up just like any other part.

If it doesn’t seem that a new class of object is appropriate, you can choose between adding a script to a part, or extending a class in Smalltalk.

Adding a Message to a Part’s InterfaceYou add a message to a part’s interface by defining a new method with PARTStalk.

To add a message to a part’s interface:

1 Select the part.

2 Press Ctrl + I.

A Part Interface window is displayed.


A method template is displayed in the window’s text pane.



4 Enter a method using the template as a guide.

The only significant difference between a PARTStalk mehtod and a Smalltalk method is the method selector: a PARTStalk method selector must begin with a capital letter.

5 Click on the Save button.

If there are any errors, a warning message is inserted next to the problem. When the method compiles successfully, its name is added to the message list in the pane above.

The method selector for the new method will now appear in link dialogs when you create links to the part.

TIP: You can leave the Part Interface window open and make changes to the method after the application has been launched, but those changes are not reflected in the launched application. Each time you make a change to the method, be sure to close any applications that you are testing, save the script, and re-launch the application.

Editing a User-Defined Method DefinitionYou can modify the behavior of a PARTStalk method by editing it.

To edit a PARTStalk method:

1 Select the part to which the method is attached.

2 Press Ctrl + I.


3 Select the method’s method selector in the message list pane.

The method’s source code is displayed in the text pane.

4 Edit the method.

5 Click on the Save button to save the changes.

TIP: You can leave the Part Interface window open and make changes to the method after the application has been launched, but those changes are not reflected in the launched application. Each time you make a change to the script, be sure to close any applications that you are testing, save the script, and re-launch the application.


Adding an Event to a Part’s Interface

Deleting a User-Defined MessageYou can delete user-defined messages from a part’s interface using the Part Interface window.

To delete a mesage:

1 Select the part that implements the user-defined message.

2 Press Ctrl + I.


3 Select the message name in the message list pane.

The method that implements the message is displayed in the text pane.

4 Click on the Delete button.

Adding an Event to a Part’s InterfaceYou can define new events for a part to trigger. You do this in the Part Interface window. Defining an event simply requires that you name it. Triggering an event requires some scripting and is discussed in another topic.

To add an event to a part:

1 Select the part.

2 Press Ctrl + I.


3 Click on the Event radio button.


You are prompted for the name of the new event.

5 Enter a new event name.


You can now create event links from the part that are fired by the new event.



Deleting an Event from a Part’s InterfaceYou can delete user defined events from a part’s interface using the Part Interface window.

To delete an event:

1 Select the part that trigger’s the event.

2 Press Ctrl + I.


3 Click on the Event radio button.

4 Select the name from the list pane.

5 Click on the Delete button.

Managing User-Defined MethodsBoth the Part Interface window and the Script window include an XRef menu that provides important code manangement commands. These commands help you to quickly locate user-defined methods that reference a particular part, methods that send a particular user-defined message, and parts that implement a particular user-defined method.

To find all of the user-defined methods that reference a selected part:

1 Choose XRef /References.

A References window is displayed. The Components list includes all parts with user-defined methods that reference the selected part.

2 Select a part from the Component list.

Only the method selectors for methods that reference the originally selected part are displayed in the Scripts list.

3 Select a method selector from the Scripts list.

Source code for the selected method is displayed in the lower text pane.


Managing User-Defined Methods

To find all of the user-defined methods that reference a selected user-defined method:

1 Choose XRef /Senders.

A References window is displayed. The Components list includes all parts with scripts that reference the selected part. If no senders are found, an information dialog is displayed.


Only the method selectors for scripts that reference the originally selected part are displayed in the Scripts list.


Source code for the selected method selector is displayed in the lower text pane.

To find all of the user-defined methods that reference a user-defined method that you specify:

1 Choose the XRef /Senders... command.

You are prompted for the method selector of user-defined method in which you are interested.

2 Enter a method selector and click the OK button.

A References window is displayed. The Components list includes all parts with scripts that reference the selected part. If no senders are found, an information dialog is displayed.


Only the method selectors for scripts that reference the originally selected part are displayed in the Scripts list.





To find all of the parts in the workbench that implement a selected user-defined method:

1 Choose XRef /Implementors.

An Implementors window is displayed. The Components list includes all parts that implement the selected method. If no implementors are found, an information dialog is displayed.


Only the relevant method is displayed in the Scripts list.

3 Select the method selector from the Scripts list.


Displaying User-Defined Methods for all PartsThe workbench includes a Script window that provides access to all the methods that you have implemented within a single workbench. This window has the same script-related commands as a Part Interface window.

To select a method in a Script window:

1 From the workbench menu bar, choose the View/Edit scripts... command.

A Script window is displayed.


The Component list includes all of the parts that are direct children of the workbench. It does not include parts contained within nested parts. User-defined method selectors for the selected component are displayed in the Script list.

3 Select a method selector from the Script list.

The source code for the selected method is displayed in the lower text pane.


Triggering a User-Defined Event

Triggering a User-Defined EventOnce you have added an event to a part’s interface, you can use it to create links. But the event is never triggered, and therefore the link is never fired, unless you explicitly trigger the event from a method that is defined for the part.

To trigger an event that does not offer a value:

> Send the triggerEvent: message to self with the event name, a Symbol, as the argument.

self triggerEvent: #anEventName

For example, if you add the closed event to a part, you can trigger it from a method using the following expression:

self triggerEvent: #closed.

To trigger an event that offers a value:

> Send the triggerEvent:with: message to self with the event name, a Symbol, as the first argument, and the value that the event is to offer as the second argument.

triggerEvent: #anEventName with: anObject

The second argument, aValue, is typically an object resulting from some action taken within the method.

self triggerEvent: #changed: with: anObject

To trigger an event that offers multiple values:

> Send the triggerEvent:withArguments: message to self with the event name, a Symbol, as the first argument, and an Array of the values that the event is to offer as the second argument.

triggerEvent: anEventName withArguments: anArrayOfObjects

TIP: You can leave the Part Interface window open and make changes to a method after the application has been launched, but those changes are not reflected in the launched application. Each time you make a change to the method, be sure to close any applications that you are testing, save the script, and re-launch the application.



Using Part Names in User-Defined MethodsPart names are Global variables in Visual Smalltalk. This means that you can access other parts in the application by name from within a method defined for a particular part. The part name of each part in your application is displayed in the information area when the cursor is over that part. You can change the name of a part in its Properties dialog.

Restrictions on Use of Part NamesYou can send messages to a part as in the following example where List1 is a part name:

List1 setList: names.

But you cannot assign another object to the part name using the assignment operator, :=.

You should generally be cautious about using part names in your code. When you use a part name, you are writing a hard-wired constant into your code. If you later delete the part or change its name, the code that references it will break. You can use the XRef menu commands to help locate problem methods before and after you delete or rename a part.

Referencing Value HoldersWhen sending a message to a value holder part or one of its specializations, it is important to keep in mind the distinction between the value holder part and the value that it holds.

If you send a message to a value holder part, and the part implements behavior for that message, the value holder executes the message. In the following expression, the value message is executed by the value holder.

ValueHolder1 value.

If you send a message to the value holder that is implemented by the value in the value holder, and the value holder does not have its own implementation of the message, the message is executed by the value. In the following message, the foo message is executed by the value holder’s value because value holder’s don’t implement a foo method.

ValueHolder1 foo.


Printing Interface Reports

This distinction is fairly obvious in the workbench. But when you are writing code, you can create expressions like the following that don’t correspond to any workbench construct:

ValueHolder1 = ValueHolder2

Parts inherit the equality messsage (along with many others), so this expression actually compares the two parts, not the values that they hold. This is probably not a useful comparison.

For this reason, when you send a message to the value in a value holder, you should send the value message to the value holder to explicitly retrieve its value and then send the message intended for the value.

ValueHolder1 value foo.

This insures that the message is always sent to the value because the value holder never has an opportunity to intercept the message.

Nested PartsWhen sending a message to a nested part holder, it is important to keep in mind the distinction between the nested part holder and the part to which it refers. You will probably seldom have a need to send a message to the nested part holder.

To access the part refered to by the nested part, send the application: message to the nested part. This message returns a reference to the part in the nested part holder. The following expression sends the open message to the part in the nested part holder:

NestedPart1 application open.

Printing Interface ReportsYou can print reports on the interface of individual parts or for the entire application. The type of information contained in the report depends on the scope of the report.



Printing an Interface Report for an Individual PartReports for individual parts include all of the messages that the part understands, all of the events it can trigger, and the source code for any user-defined methods.

To preview an interface report for an individual part:

1 Select the part.

2 Press Ctrl + I.


3 Choose Interface/Print/Preview.

The report is displayed in a new workspace window. From here, you can save the report to disk, copy it to another application, or print it.

To print an interface report for an individual part:

1 Select the part.

2 Press Ctrl + I.


3 Choose Interface/Print/Send to printer.

Printing an Interface Report for all Parts in a WorkbenchAn interface report for all parts in a workbench includes the source code for any user-defined methods implemented by parts in the workbench.

To preview an interface report for a workbench:


A Scripts window is displayed.

2 Choose Interface/Print/Preview.

The report is displayed in a new workspace window. From here, you can save the report to disk, copy it to another application, or print it.

To print an interface report for a workbench:


A Scripts window is displayed.

2 Choose Interface/Print/Send to printer.


CHAPTER

10
Debugging an Application
The PARTS Workbench debugger allows you to control the execution of your PARTS application. It can help you find out why something doesn’t work or how something does work. You can:

• Set breakpoints on every link in your application or on individual links selected from a list for each part

• Step through link firing sequences

• Observe and change message argument values

• Create and save a log of your debugging session


• Debugger Features

• Launching the Debugger

• Setting Link Breakpoints

• Clearing Link Breakpoints

• Debugging an Application

• Changing Message Argument Values

• Trace Log

Debugger FeaturesThis section is a feature-by-feature overview of the debugger including:

• The Single-Step Execution area of the debugger window, where you set breakpoints, clear breakpoints, trigger events, and cancel link execution.

• The Link Information area of the debugger window, where you learn about the state of the application when it was halted and change message argument values before the messages are executed.

See appendix A, Menu and Toolbar Quick Reference, for a summary of menu operations for the Debugger.


Debugging an ApplicationCHAPTER 10

• The Trace Log area of the debugger window, where the debugger can display a detailed log of every link that fires during your debugging session.

Detailed instructions for using these features are included in the sections that follow this overview.

Single-Step Execution AreaThese controls, located at the top of the debugger window, are used to set breakpoints, clear breakpoints, trigger events, and cancel link execution.

1. Break on All Links

Checking this box puts the application in single-step link firing mode. It causes an application to behave as if breakpoints are set on all links in the application.

➊

➋

➌ ➍

➎

➏


Debugger Features

2. Go

When the debugger is first opened, before the application has been launched or any events triggered, pressing this button triggers the application’s open event. The button is also enabled whenever your application stops at a link breakpoint, allowing you to resume execution.

3. Cancel

Pushing this button cancels firing of the link selected in the Link Firing list. Any links triggered by the canceled link are also canceled. The canceled link returns the value nil if it is a result or argument link triggered by another link.

4. Parts List

Contains the names of all the parts in the application being tested. This list is used in conjunction with the Trigger event... and Breakpoints... buttons.

5. Breakpoints...

This button is used in conjunction with the Parts List located immediately to its left. It is used to inspect, set or clear breakpoints at links attached to the part selected in the Parts List.

6. Trigger event...

This button is used in conjunction with the Parts List located immediately to its left. It is used to start your application using an event other than open or to test specific links in the application under controlled circumstances.

Link Information AreaThe center section of the PARTS Workbench debugger window tells you about the state of the application when it was halted and allows you to change message argument values before the messages are executed.

➊

➋



1. Link Firing List

This list pane, located directly above the Link Values group pane, displays the Link Firing list, a list of all the links that were firing when the application was halted. There is always at least one link in the Link Firing list when your application halts. If you have stopped on an argument or result link, there will be two or more links on the firing stack, starting from the event link which triggered this link chain. This list is used in conjunction with the Link Values group pane located directly below it.

2. Link Values

This group pane allows you to view and change message argument values (if any) for the link selected in the Link Firing list located directly above this group pane.

Trace Log AreaThe Trace Log Area is the large text pane at the bottom of the debugger window. When enabled, it maintains a log of every link fired. You can save, enable, disable, and reset the log using the appropriate commands in the debugger’s Log menu. You can also edit the log, adding comments, using standard text editing commands.

NotationThe debugger represents visual links using text.

Event Linkprototype:

part <event> executes part [message]

example:

Button1 <clicked> executes Conversion [asInteger:•]


Setting Link Breakpoints

Argument Linkprototype:

part <message:• argument> gets part [message]

example:

Conversion <asInteger:• argument> gets EntryField1 [value]

Result Linkprototype:

part [message] result executes part [message]

example:

Conversion [asInteger:•] result executes NumberHolder1 [setValue:•]

Launching the DebuggerTo launch the PARTS Workbench debugger:

> Choose Test / Debug.

When you launch the debugger, PARTS Workbench creates a copy of your application. Changes made in the workbench after the debugger is launched won’t be reflected in the copy of your application that the debugger uses. If you want to test changes made in the workbench, you must launch the application (with Test/Debug) after you make the changes.

Setting Link BreakpointsSince links represent both control and data flow, they are an excellent place to start when you want to understand how your application executes. A breakpoint can be set on a link to temporarily stop the execution of your application when that link is fired so that you can inspect and perhaps alter some of its data. Breakpoints halt execution of the application after message arguments (if any) have been collected but before the message is actually executed.



When the application halts at a breakpoint, PARTS Workbench switches to the debugger window allowing you to view information about the current link—such as the origin and destination parts, the event and message names, arguments, and argument values—and to change argument values. You can set breakpoints from the debugger window and in the workbench. Breakpoints have no effect on your application when it is launched independently of the debugger.

To simulate setting breakpoints at all the links in your application while in the debugger:

> Click on the break-on-all-links check box.

Checking this box puts your application into single-step mode—it does not set any breakpoints. Unchecking this box turns off the Break-on-all-links property but does not clear breakpoints that you set individually using techniques described elsewhere. This single step mode only effects the current copy of the application.

To set a breakpoint at a specific link while in the debugger window:

1 Select a part from the Parts list at the top of the debugger window.

2 Press the Breakpoints... button.

The debugger displays a dialog box with a list of links attached to the selected part. Click on a link to select it.

3 Click on a link to select it.

When you click on a link, it is highlighted. You can choose multiple links by clicking on each one.


Setting Link Breakpoints

4 Press the OK button.

Breakpoints will be set at all of the highlighted links. Breakpoints set using this procedure are discarded when you close the debugger window.

You can also set breakpoints in the workbench before you open the debugger. Breakpoints set using this procedure persist until you explicitly clear them. If you save your application as an editable PAR file, the breakpoints are saved as well.

It is possible to set a breakpoint in the workbench after you have launched the debugger. However, the debugger works with a copy of your application made at the time the debugger is launched. Therefore any breakpoint you set in the workbench after the debugger is launched is not recognized until after you re-launch the debugger, and it makes a new copy of your application.

To set breakpoints at all the links in your application while in the workbench:

> Choose Test / Set all breakpoints from the workbench menu bar.

Breakpoints set using this command persist until you explicitly clear them.

You can set breakpoints at specific links by using the Parts List and the Breakpoints... button. Breakpoints set using this procedure apply only to the copy of your application used by the debugger; they are lost when the debugger window is closed.

To set a breakpoint at a specific link while in the workbench:

1 Select the link pop-up menu.

2 Choose the Set breakpoint command.

The next time you choose the link pop-up menu for this link, it will display the Clear breakpoint command instead of the Set breakpoint command.



Clearing Link BreakpointsTo clear individual breakpoints while in the debugger window:

1 Select a part from the Parts list at the top of the debugger window.

2 Press the Breakpoints... button.

The debugger will display the Breakpoints dialog box with a list of links. Links with breakpoints are highlighted.

3 Click on a highlighted link to unselect it.

If you change your mind about a link, click on it again to re-select it.


If you use the Breakpoints dialog to clear a link that was originally set in the workbench, the breakpoint is only cleared in the debugger’s copy of your application. If you wish to permanently clear a breakpoint set in the workbench, you must clear it in the workbench using one of the procedures below.

To clear all breakpoints while in the workbench:

> Choose Test / Clear all breakpoints from the workbench menu bar.

If you choose this command after you launch the debugger, it will clear all the breakpoints in the workbench but it will not affect the copy of your application in use by the debugger. You must re-launch the debugger for your changes to take effect.


Debugging an Application

To clear individual breakpoints while in the workbench:

1 Select the link pop-up menu.

2 Choose the Clear breakpoint command.

The next time you choose the link pop-up menu for this link, it will display the Set breakpoint command instead of the Clear breakpoint command.

Debugging an ApplicationWhen you are testing an application, it is often useful to set breakpoints at key points during execution so that you can stop and examine the values passed as message arguments. Once breakpoints are set (See Setting Link Breakpoints), the debugger gives you several options for executing your application or specific events within your application. Breakpoints will only halt application execution in the debugger. If you use the Launch button or the Test/Launch menu item, breakpoints are ignored.

To debug your application:

1 Choose Test/Debug.

A Debugger window is opened.

2 Press the Go button.

This triggers the open event for the debugger’s copy of your application. You then interact with the application until a link with a breakpoint is fired. At that point, PARTS Workbench switches back to the debugger window allowing you to view link information and argument values, change argument values and cancel link execution as described in the relevant sections below.

The Go button is only enabled to launch your application at the beginning of the debugging session. Once you’ve launched your application, or triggered any event within your application, the Go button is only enabled to resume execution after your application is halted at a breakpoint. You must use the Trigger event... button if you want to re-launch your application.

If you are building a part which will be invoked by a message other than open, or you are re-launching your application during a debugging session, you use the Trigger event... button. If the event you plan to trigger supplies event values which are used as message arguments in your application, you may want to set a breakpoint so you can set these values manually.



To trigger a specific event in your application:

1 Select the part whose event you want to trigger from the parts list pane in the Debugger window.

The application is itself a part and you can select it from the list.

2 Press the Trigger event... button.

The debugger displays a dialog box listing events that the selected part can trigger. If you have selected an application, the dialog lists the application’s internal events such as the standard open event.

3 Select an event.


The debugger now triggers the event. When a break point is encountered, PARTS Workbench switches back to the debugger window allowing you to view link information and argument values, change argument values, and cancel link execution.

To resume execution after halting at a breakpoint:

> Press the Go button.

In some cases you may want to cancel link firing rather than continuing.


Changing Message Argument Values

To cancel link firing:

1 Select the link that you want to cancel in the Link Firing list.

The Link Firing list is located directly below the Go button.

2 Press the Cancel button.

Any links triggered by the canceled link are also canceled. The canceled link returns the value nil if it is a result or argument link triggered by another link. The link which triggered the canceled link resumes its firing with the nil value returned by the canceled link when you press the Go button.

Changing Message Argument ValuesWhen your application fires a link on which you have set a breakpoint, PARTS Workbench stops executing the application and switches to the debugger window. Here, you can view link information and argument values, change argument values, and cancel link execution.

The Link Firing list, located directly below the Go button, shows all the links being fired at the time execution was halted. There is always at least one link in this list and sometimes more. In the example below, the first item in the list is the link from Button2’s clicked event to Auto’s label message. The second item is the result link from Auto’s label message to AutoValue’s setValue: message.



To change message arguments:

1 Select a link from the Link Firing List.

The debugger will display the names of the message arguments (if any) in the Link Values list pane located below the Link Firing List.

2 Select a message argument from the Link Values list.

The debugger will display the current value of the argument in the Value: field. If you only want to view message argument values without changing them, skip the next step and press the Go or Cancel button.

3 Enter a value in the New value: entry field and press Return.

You can enter any valid PARTStalk expression, which could be as simple as a letter or a number—whatever is appropriate for the situation. If you are familiar with the PARTStalk scripting language, you can enter more complex expressions here. Pressing Return changes the value but


Trace Log

does not resume execution. When you are ready to resume, press the Go button.

Trace LogThe bottom section of the PARTS Workbench debugger window is a text pane containing the link firing trace log. Whenever a link is fired in your application, a description of the link, the argument values of its message, and its result value are appended to the trace log.

You can edit the log using standard text editing commands. Commands to save the log, to toggle trace logging on and off, and to reset the trace log are available under the Log menu in the debugger window’s menu bar.


CHAPTER

R11
evision Support
This chapter explains the revision support features available in the workbench when you are using Visual Smalltalk Enterprise.

You access revisioning features via modified Part File dialogs. (See chapter 1, The Workbench, earlier in this document for information on standard Part File dialogs.)

RepositoriesYou can use existing repositories to store parts or you can create new repositories using Team/V. A repository is a collection of entities. When you save a part to a repository, an entity for that part is automatically created. Each subsequent save creates a new revision within the entity. Please refer to the Visual Smalltalk Enterprise Tools Reference for more information regarding repositories, repository entities, and revisions. You can store any parts of any format in a repository except for parts saved in executable (EXE) format.

Nested Parts and Part AccessorsYou can use a nested part or a part accessor to reference a part stored in a repository. A part accessor always references the latest revision in the main revision branch, or if the last revision has a branch, the last revision in that branch. Nested parts exhibit the following behaviors when used to reference parts stored in repositories:

• The workbench’s Edit/Import part... command always imports the latest revision.

• The catalog’s File/Insert part file... command always inserts the latest revision into the catalog.

• If the nested part’s reuse option is set to linked, you cannot change the referenced file to a specific entity revision; the part will always use the latest revision in the main revision branch, or if the last revision has a branch, the last revision in that branch.


Revision SupportCHAPTER 11

• If the nested part’s reuse option is set to embedded, you can use the nested part’s Change file... button to select a revision other than the latest one.

Revision Support FeaturesThe Part Dialog features that support revisions are shown in the following illustration.

1. Search path

Repositories are displayed in parentheses.

2. Proposed revision (Save Part As... dialog)

The initial value is the number of the current revision incremented by point one (0.1). You can enter a number directly. New files have an initial revision number of 0.1.

3. Derived from revision (Save Part As... dialog)

The revision number of the current file.

4. Existing revisions

A list of revisions currently contained in the repository entity.

➊

➋

➌

➍ ➎

➏

➐

➑

➒


Revision Support Features

5. Revision comment

Displays comments for existing revisions when you select a revision in the list pane: Existing revisions. You can also enter new comments here for the proposed revision.

6. Manufacturer/time stamp information

Displays the author and the time of creation for the selected revision.

7. New release (Save Part As... dialog)

Increments the selected revision number by 1.0.

8. Branch (Save Part As... dialog)

Creates a branch revision number for the selected revision number.

9. Increment (Save Part As... dialog)

Increases the last digit of the revision number by one. If the new number would be less then the latest revision number, a branch revision number is created.


APPENDIX

A
Menu and Toolbar Quick Reference
This section gives you a listing of all PARTS Workbench menus with a brief explanation of each item. All menu items are listed here, although some items are disabled if they are not appropriate for the current context. For example, many of the items in the Selected menu are not applicable if multiple parts are selected.

Press F1 while a menu item is highlighted to open a help window with more information about that menu choice.

In the following menu listings, keyboard shortcuts (if any) are shown the Shortcut column of the table. When the menu is displayed, you can also type the underscored letter to select items.


Menu and Toolbar Quick ReferenceAPPENDIX A

Catalog File MenuThis menu is accessed through the File... push button in the lower right-hand corner of the window or by clicking mouse button 2 on the Catalog’s background.

Menu Command Shortcut Command Description

New Opens a separate Catalog window with an empty Catalog.

Open... Pops up a dialog to select a Catalog file to open in a separate Catalog window.

Save Saves the Catalog to the current filename.

Save as... Saves the Catalog to a different filename.

Cut part Deletes the selected part from the Workbench and places a copy in the clipboard.

Copy part Copies the currently selected part to the clipboard.

Paste part Pastes the part stored in the clipboard to the current page.

Insert part file...

Displays an Insert Part dialog from which to select a part file and pastes the application stored in the file into the current notebook page.

Insert new page

Adds a new blank page in the Catalog after the current one.

Append new page

Appends a page to the Catalog.

Delete page Deletes the current page after asking for confirmation.

Describe page...

Opens a prompter on the text for the current page to display in the information area of the Workbench.

Set major tab Prompts for a text string or the name of a bitmap file for a new or replacement major tab for the current page.

Set minor tab Prompts for a text string or the name of a bitmap file for a new or replacement minor tab for the current page.


Workbench File Menu

Workbench File MenuThe File menu allows you to specify global PARTS Workbench preference settings, create a new PARTS Workbench application or view one saved previously in a separate Workbench, obtain a textual description of the current application, save an application in various formats to a file, and close the Workbench.

Discard tab Deletes the tab on the current page.

Set size Allows you to set the size of the major tabs, minor tabs, or page buttons in the Catalog window.

Arrange icons Sub-menu choices align the icons evenly on the current page or on all pages.


New Opens a separate Workbench window on a newly created application.

Open... Ctrl + O Displays the Open Part dialog from which to select a part file to open in a separate Workbench window.

Replace... Displays the Replace Part dialog from which to select a part file that replaces the application currently contained in the Workbench window. Asks for confirmation if the current application has been modified since it was last saved.

Save Alt + S Saves the current application in editable or executable form. If no filename has been specified, the Save Part As dialog is displayed.

Save as... Saves the current application to a path and filename specified in the Save Part As dialog. You can select the format of the saved file.

Print Previews or sends a textual representation of the current application to the printer.

Settings... Specifies global preference settings for the Workbench.




Workbench Selected MenuThe Selected menu provides operations that affect the selected part or parts only, such as changing its properties or displaying links attached to it.

Close Alt + F4 Closes the Workbench (asks for confirmation if the current application has been modified since it was last saved).

Menu Command

Shortcut Command Description

Edit direct Alt<click> Allows you to directly change the label or contents or some other visible feature of the selected part.

Edit properties...

double-click Opens up the properties dialog for the selected part. If multiple parts are selected, opens a Color and Font properties dialog.

Edit interface...

Ctrl + I Opens up the Interface window for the selected part. Also accessible from the Interface... button in the properties dialog.

Show links Displays all links connected to the selected part(s). Also accessible from the tool bar.

Show incoming links

Displays all links with destinations in the selected parts group. Also accessible from the tool bar.

Show outgoing links

Displays all links originating at any selected part. Also accessible from the tool bar.

Show some links...

Opens a dialog that lets you choose which links attached to the selected part you want to display. You choose links by choosing origin or destination part(s) or by event or message.

Hide links Hides all links connected to the selected part(s). Also accessible from the tool bar.

Create link... Creates a link from the selected part.

Sequence links...

Specifies a firing order for links fired by the same event from the selected part.



Workbench Edit Menu

Workbench Edit MenuThe Edit menu allows you to manipulate parts, using such operations as cutting, copying, pasting, aligning, and re-sizing. It also provides undo and redo commands as well as facilities for importing other applications.

Expand Ctrl + E Expands the selected item from its collapsed form (applicable for windows, dialog windows, nested parts, and menus only).

Shrink Ctrl + R Collapses the selected item into its icon view (applicable for windows, dialog windows, nested parts, and menus only).

Browse/Nested part explosion

Displays a heirachical list of nested parts.

Browse/References

Displays a list of the parts on a selected search path that reference the selected part.

Browse/Implementors

Displays the files on the selected search path that have the same file name as the selected application

Select... Selects one or more parts from a list of all parts in the application.


Undo Ctrl + Z orAlt + Backspace

Reverses the last operation.

Redo Ctrl + Y orShift + Alt + BackSpace

Reverses the last undo.

Cut Ctrl + X orShift + Del

Deletes the selected parts from the Workbench and places copies in the clipboard.

Copy Ctrl + C orCtrl + Ins

Copies the currently selected parts to the clipboard.

Paste Ctrl + V or Shift + Ins

Inserts the clipboard contents at the location of the next mouse click.

Menu Command

Shortcut Command Description



Delete Del Deletes the selected parts. Does not affect the current contents of the clipboard. Also accessible from the toolbar.

Duplicate Ctrl + D A combined copy and paste operation. Does not change clipboard contents.

Import part... Opens an Import Part dialog from which to select a part file for addition to the current application.

Nest... Allows you to create a nested part from the currently selected parts.

Align Aligns the selected parts to the part that was selected first. according to the selected alignment option. Aligns parts according to the submenu item chosen: left, center vertically, right, top, center horizontally, or bottom. Toolbar equivalents are available for Align/Left and Align/Top.

Distribute Distributes three or more parts evenly between the two outermost parts of the selection. Distributes parts according to the submenu item chosen: horizontally or vertically.

Same size Adjusts the size of the selected parts to equal the height, width, or both (as selected from the submenu) of the part that was selected first.



Workbench View Menu

Workbench View MenuThe View menu controls the display of hints, links, labels, and grids—settings which are done on a per-application basis. It contains toggle selections that determine whether hints in the information area are shown or whether link labels are displayed with links by default. You can also open a new Catalog through this menu.


Show labels Displays all labels on the currently visible links so that event and message names are visible. Also accessible from the tool bar.

Expand labels Expands labels of all visible links so that argument links are displayed.

Hide labels Hides all labels. Also accessible from the tool bar.

Show all links Displays all links.

Hide all links Hides all links and labels. Also accessible from the tool bar.

Set grid... Displays a dialog to set the grid for positioning parts.

Show hints Toggles whether hints are shown in the information area at the bottom of the Workbench. The default is on.

Show labels with links

Toggles whether labels are shown by default when a link is displayed. The default is off.

Show links with selection

When this toggle setting is on, only the links attached to the selected part are shown. The default is off.

Edit scripts... Opens a script editor which allows you to edit the scripts on all parts in the application.

Open catalog...

Opens a new Catalog window on the specified Catalog file, the same as the Catalog’s File.../Open... selection.



Workbench Test MenuThe Test menu allows you to test (launch) an application, open a debugger on it, and control the setting of breakpoints in the application.

Workbench Developer MenuThe Developer menu allows you to easily move between subsystems of the Visual Smalltalk environment while you are developing an application.


Launch Runs the application. The same as the toolbar’s Launch button.

Debug Opens a debug window to control the execution of the current application.

Set all breakpoints

Sets breakpoints on all links in this application. Does not change the breakpoint settings inside nested parts.

Clear all breakpoints

Clears breakpoints on all links in this application. Does not change the breakpoint settings inside nested parts.


Inspect Opens an Inspector window for the selected part, so you can view detailed information about the part (such as its instance variables).

Add object Opens a dialog window where you can enter a Smalltalk expression that evaluates to a part, for placement on the workbench. (This is used primarily when a part is still under development and is not yet available from a catalog.)

New Workspace

Ctrl + W Opens a new workspace window where you can enter and evaluate Smalltalk expressions.

Browse Packages

Ctrl + P Opens a package browser window where you can work with packages.

Browse Disk Ctrl + K Opens a disk browser window where you can manage files.


Workbench Scenarios Menu

Workbench Scenarios MenuThe Scenarios menu allows you to define, display, and document selected subsets of the links in an application, so you can more easily understand the logic of a complex application.

Browse Services

Opens a dialog window where you can select and install various services and samples.

New Workbench

Opens a new workbench window where you can develop another application.


New.. Opens a prompter for the name of a new scenario. (The links to be included in this scenario are defined using other commands on this menu.)

Exclusive displays

Toggles whether the currently visible links are hidden when a different scenario is selected, so only the links in that scenario will be displayed. The default is on.

Display scenario

Displays the links in the currently selected scenario, which is chosen from the drop-down list box on the right side of the workbench’s toolbar.

Add new links Toggles whether newly-created links are automatically added to the currently selected scenario. The default is off.

Add visible links

Adds all the currently visible links to the currently selected scenario.

Substitute visible links

Substitutes the currently visible links for the previously-defined set of links, in the currently selected scenario.

Remove visible links

Removes all the currently visible links from the currently selected scenario.

Clear links Clears all the links defined in the currently selected scenario, so you can start over.




Workbench Help Menu (OS/2)The Help menu provides access to the help facilities, including an on-line tutorial and information about each of the system parts and how to use them.

Pairings... Opens a dialog that enables you to create an association between the currently selected scenario in the workbench and another scenario defined for a nested part.

Remove scenario

Removes the currently selected scenario from the application.

Rename scenario

Opens a prompter where you can change the name of the currently selected scenario.

Comment... Opens a window where you enter or change the comment for the currently selected scenario.

Menu Command Command Description

Help index Displays an index of on-line help topics.

General help Displays a list of general help topics.

Using help Explains how to use the help system.

Keys help Describes the shortcut keys.

Tutorial Invokes the on-line tutorial. The tutorial provides an excellent hands-on introduction to the PARTS Workbench.

Samples Opens the SAMPLES Catalog containing the sample applications and a help window which explains them. The individual files are located in the SAMPLES subdirectory of your Visual Smalltalk or Visual Smalltalk Enterprise installation directory.

Product information... Provides the version number and other information about this product.



Link Pop-up Menu

Workbench Help Menu (Windows)The Help menu provides access to the help facilities, including an on-line tutorial and information about each of the system parts and how to use them.

Link Pop-up MenuThe context-sensitive Link pop-up menu manipulates aspects of a particular link, such as its visibility, labels, control points, and breakpoints. It allows you to change its origin, destination, event, and message. You select this menu by clicking on a link handle with button 2. See chapter 5, Events, Messages, and Links, for more information on link handles.

Some of the items in this menu are toggles: for example, if link labels are displayed, you see the Hide labels choice, but if labels are hidden, you see Show labels.


Contents Displays a list of general help topics.

Search for Help on... Displays an index of on-line help topics.

How to Use Help Explains how to use the help system.

Tutorial Invokes the on-line tutorial. The tutorial provides an excellent hands-on introduction to the PARTS Workbench.

Samples Opens the SAMPLES Catalog containing the sample applications and a help window which explains them. The individual files are located in the SAMPLES subdirectory of your Visual Smalltalk or Visual Smalltalk Enterprise installation directory.

About Visual Smalltalk... Provides the version number and other information about this product.



*Available in menu only when appropriate.


*Create result link Initiates a result link connected to the current link.

*Insert result link Inserts a result link in the link chain. The origin is the result of the selected link’s message. The destination is user specified. The new result link’s message result becomes the origin of the result link that was originally connected to the selected link’s message result.

*Replace result link Replaces existing result link plus any links attached to it with a new user-defined result link.

Hide link Makes the link invisible.

Hide/Show labels Toggles the display of event and message labels for the link.

Shrink/Expand labels Toggles the display of expanded labels for the link. When labels are expanded, argument links are also displayed.

*Delete link chain Deletes all of the links in the selected result link chain.

*Delete link Removes the current link from the application. If the selected link is part of a result link chain, only the link itself is deleted.

Delete all control points Removes all control points (small dots at the junction of link line segments) for the link.

*Change origin Allows you to change the link’s origin.

*Change event Changes the link’s event to the one chosen from the pop-up list.

*Change destination Allows you to change the link’s destination.

*Change message Changes the link’s message to the one chosen from the pop-up list.

Set/Clear breakpoint Controls whether a breakpoint is set on the link.


Part Interface Window Interface Menu

Debugger Log Menu

Part Interface Window Interface Menu


Save Saves the current contents of the log file. If you have not already specified a filename, the Save as... dialog is opened.

Save as... Opens a file dialog that allows you to specify the name of the file in which to save the current contents of the log pane.

Trace links Toggles the link trace setting. When the item is checked, all links fired during your application’s execution are logged in the Link Trace log. Deselecting this item disables link trace logging. The default is to log link firing.

Reset Log Clears the current contents of the Link Trace Log.


New The same as the New... button, it replaces the text pane contents with a new script template after notifying you of any unsaved changes in the text pane.

Delete The same as the Delete button, it deletes the script of the selected event or message.

Export The same as the Export button, it makes the selected event or message visible to the enclosing layer. See chapter 8, Constructing New Parts, for more information about this function.



.Part Interface Window Script Menu

Part Interface Window Edit Menu


Inspect... Ctrl + I Compiles and executes the PARTStalk code selected in the text pane and opens an Inspector window on the resulting PARTStalk object.

Evaluate Ctrl + E Compiles and executes the PARTStalk code selected in the text pane and returns the result as selected text in the text pane. Press the Backspace or Delete key or choose Edit / Cut to delete the returned value.

Save Ctrl + S Makes changes to the script permanent.

Restore Ctrl + R Undoes any editing performed since the last save. Restore can’t undo changes once the script has been saved.


Cut Ctrl + X or Shift + Del

Copies the selected text from the text pane to the clipboard and then deletes it.

Copy Ctrl + C or Ctrl + Ins

Copies the currently selected text from the text pane to the clipboard.

Paste Ctrl + V or Shift + Ins

Inserts the clipboard contents at the cursor location, or replaces the current selection.

Delete Del Deletes the selected text from the text pane. Does not affect the current contents of the clipboard.

Select all Ctrl + A Selects the entire contents of the text pane.

Find/Replace... Ctrl + F Presents a dialog box to enter a text string for which to search and, optionally, a replacement string for the search text. Dialog controls permit setting the search direction to forward or backward, to replace at a pattern or column, and whether to replace all automatically or with confirmation.

Find Again Ctrl + G Performs the most recent search again, looking for the same text string in the same direction as the last search operation.

Word wrap (checked if on)

When toggled on (the default), text is automatically wrapped when it gets close to the right margin of the text pane.


Part Interface Window Xref Menu

send

ipt or

e

Part Interface Window Xref Menu


References Opens a script browser on all scripts in the application whichreference the selected part.

Senders Opens a script browser on all scripts in the application whichthe selected script.

Senders... Opens a prompter in which you can type the selector of a scra message, then opens a script browser on all scripts in the application which send the specified message.

Implementors Opens a script browser on all scripts in the application with thsame name as the selected script.



The Workbench Tool BarIn addition to a drop-down list box for the scenarios defined for the application, the tool bar contains the following buttons for quick access to frequently used commands:

Button Name Corresponding Menu Item

Launch Test/Launch

Show incoming links Selected/Show incoming links

Show outgoing links Selected/Show outgoing links

Show links Selected/Show links

Hide all links View/Hide all links

Show labels View/Show labels

Expand labels View/Expand labels

Hide labels View/Hide labels

Align parts left Edit/Align/Left

Align parts top Edit/Align/Top

Delete selected parts Edit/Delete


APPENDIX

B
Mouse Actions Quick Reference (Windows)
Mouse BasicsThe PARTS Workbench documentation assumes that you are familiar with basic mouse terminology such as click, double-click, drag, etc. If you are not, refer to your operating system documentation.

Unless otherwise specified, all mouse operations in Windows are performed with button 1, which by default is the left button.

Mouse Button Actions for Parts

Selecting

Single part Click with button 1 (deselects previous selection)

Group of sibling parts Alt<drag> around parts with button 1

Toggle selection state of part Ctrl<click> with button 1

Add part to selection Shift<click> with button 1

Moving

Part within parent Drag with button 1 or use arrow keys to move selected part(s)

Part to different parent Shift<drag> with button 1

Editing

Direct-edit part Alt<click> with button 1

Property edit part Double-click with button 1

Resize part Drag resize handle with button 1 or use Shift <Arrow key>

Duplicate part Ctrl<drag> with button 1


Mouse Actions Quick Reference (Windows)APPENDIX B

Mouse Button Actions for LinksViewing

Expand labels and shows argument links (when labels are showing)

Hide labels and argument links (when labels are expanded)

Show labels (when labels are hidden)

Double-click with button 1

Show links connected to part Click with button 2

Moving

Link handle Drag with button 1

Link attachment to new part Shift<drag> with button 1

Editing

Initiate Link pop-up menu Click with button 2 on link handle

Create link Drag with button 2

Create/Delete control point Drag link line/control point with button 1


APPENDIX

C
Mouse Actions Quick Reference (OS/2)
Mouse BasicsThe PARTS Workbench documentation assumes that you are familiar with basic mouse terminology such as click, double-click, drag, etc. If you are not, refer to your operating system documentation.

Unless otherwise specified, drag operations in OS/2 are performed with button 2 and all other operations (such as click, double-click, select, and choose) are performed with button 1. The following table lists buttons for all operations.

Mouse Button Actions for Parts

Selecting

Single part Click with button 1 (deselects previous selection)

Group of sibling parts Alt<drag> around parts with button 2

Toggle selection state of part Ctrl<click> with button 1

Add part to selection Shift<click> with button 1

Moving

Part within parent Drag with button 2 or use arrow keys to move selected part(s)

Part to different parent Shift<drag> with button 2

Editing

Direct-edit part Alt<click> with button 1

Property edit part Double-click with button 1

Resize part Drag resize handle with button 2 or use Shift <Arrow key>

Duplicate part Ctrl<drag> with button 2


Mouse Actions Quick Reference (OS/2)APPENDIX C

Mouse Button Actions for LinksViewing

Expand labels and shows argument links (when labels are showing)

Hide labels and argument links (when labels are expanded)

Show labels (when labels are hidden)

Double-click with button 1

Show links connected to part Click with button 2

Moving

Link handle Drag with button 2

Link attachment to new part Shift<drag> with button 2

Editing

Initiate Link pop-up menu Click with button 2 on link handle

Create link Drag with button 1

Create/Delete control point Drag link line/control point with button 2


APPENDIX

D
User Interface Parts
PARTS Workbench includes many visual parts to simplify the task of building an effective graphical user interface (GUI). The following table lists parts by how they are used in a GUI. The table includes the following GUI functions:

• Confirming Operations

• Displaying Visual Parts at Runtime

• Formatted Text—Entry and Display

• Graphics—Creation and Display

• Initiating Operations

• Notification

• Numbers—Entry and Display

• Organizing Controls

• Prompting for User Input

• Reporting

• Selecting

• Text—Entry and Display

Note that some parts have multiple functions, so they appear in more than one category. The description of each part includes the part’s name, an illustration representing its appearance, its catalog icon, and a brief descriptive comment. See the Part Reference for more information on individual parts.

For more information about the Reporting function, see the Visual Smalltalk Enterprise Workbench Report Writer User’s Guide.


User Interface PartsAPPENDIX D

Function Part Icon Comments

Confirming Operations confirmer A pre-built dialog that gives the user a choice of Yes/No, OK/Cancel, or Retry/Cancel.

Appears as icon in Workbench.

confirmer with cancel A pre-built dialog that gives the user a choice of Yes/No/Cancel or Abort/Retry/Ignore.


Displaying Visual Parts at Runtime dialog window Used to display and request information. See also the pre-built dialogs: confirmer, confirmer with cancel, information dialog, prompter, and file dialog.

property sheet (Win32 only)

Used to display the properties of an application, on tabbed pages. See also the property constructor and property interface parts.

window The foundation for your user interface. You place visual parts inside of a window (or dialog window) so that they can be seen at runtime.

wizard (Win32 only) A dialog window simulating the Win95 wizard control, for guiding the user through the steps of an operation (where typically each step is on a separate page).

Formatted Text—Entry and Display alphabetic entry field A formatted entry field which restricts display and entry of characters to letters and spaces.

date entry field A formatted entry field which allows display and entry of a date with or without the year. Input is automatically formatted.


phone number entry field

A formatted entry field which allows display and entry of a phone number. Input is automatically formatted.

picture entry field A formatted entry field which allows display and entry of a alphanumeric data in an application builder defined format. (Useful for entering data such as ID numbers that must follow a specific format.)

Graphics—Creation and Display drawn button Allows you to make a bitmap graphic into a push button.

graph pane Allows you to display bitmaps and icons in a scrollable window. You can also draw graphics using scripts and then copy them to the clipboard.

menu bitmap item Allows you to use a bitmap as one of the choices in a menu.

static graphic Allows you to display an icon or (in OS/2 only) a bitmap.

video pane (Win32 only)

Allows you to display AVI (Audio / Video Interleaved) full-motion video files in Windows. See also the AVI video (Win32 only) part.

Initiating Operations drawn button Allows you to make a bitmap graphic into a push button.

edit menu A pre-built menu containing the common Edit menu commands.




file menu A pre-built menu containing the common File menu commands.

format menu (Win32 only)

A pre-built menu for operations on text using the rich edit (Win32 only) part.

header control (Win32 only

A row of buttons typically used with a list of data items formatted in columns, such as the Report view of a list view (Win32 only) part.

help menu A pre-built menu containing the common Help menu commands, which provide access to the table of contents, index, and other features of the help system for your operating system.


menu Custom menus are actually built from a collection of menu related parts: menu, menu text item, menu bitmap item, menu item separator, and menu label.

push button Allows you to initiate an operation by clicking on a visual button.



toolbar (Win32 only) A region (typically below the menu bar) of buttons or other tools providing quick access to frequently-used commands. A toolbar is constructed from the tool box, toolbar, toolbar button, toolbar toggle button, and toolbar separator parts.

Notification information dialog A pre-built dialog that displays an information-only message.

progress bar (Win32 only)

An output-only control (usually placed at the bottom of a window) that an application can use to display the progress of a lengthy operation.

status window(Win32 only)

A short horizontal control (usually placed at the bottom of a window) that an application can use to display various kinds of status information.

Numbers—Entry and Display currency entry field A formatted entry field which allows display and entry of currency. Input is automatically formatted.

dial pane Allows entry and display of numbers via a graphic dial. Also allows numeric input and numeric display when combined with the appropriate parts.

float entry field A formatted entry field which allows display and entry of floating point numbers. Input is automatically formatted.

integer entry field A formatted entry field which restricts display and entry of characters to integers.

progress bar (Win32 only)

An output-only control (usually placed at the bottom of a window) that an application can use to display the progress of a lengthy operation.




scroll bars (Win32 only)

These parts allow the entry, display, and selection of numbers by dragging the scroll box with the mouse. Also allows numeric input and numeric display when combined with the appropriate parts.

sliders (OS/2 only) These parts allow the entry, display, and selection of numbers by dragging a control with the mouse. Also allows numeric input and numeric display when combined with the appropriate parts.

spin button (Win32 only)

This part allows the entry, display, and selection of numbers by scrolling through a list of choices or by directly entering a number.

spin buttons (OS/2 only)

These parts allow the entry, display, and selection of numbers by scrolling through a list of choices or by directly entering a number. Also allows numeric input and numeric display when combined with the appropriate parts.

track bar (Win32 only)

A window containing a slider control, which allows you to select a single integer value within its range.

Organizing Controls group pane Allows you to visually designate and label a group of parts—typically radio buttons or check boxes.

notebook Allows you to group visual parts into a notebook with pages that you can turn. See also the notebook page part.



tab control (Win32 only)

Allows you to group visual parts into pages having a labeled tab that you select to bring it to the front for viewing. See also the tab control page part.

This part implements the Win95 tab control, which is commonly used to display the properties of an object.

Prompting for User Input file dialog A pre-built dialog that allows the user to access the file system.

prompter A pre-built dialog that prompts the user for text.

Reporting report writer catalog(RW.CAT)

This catalog of parts allows you to format, print, and display data from your application.

For more information, see the Visual Smalltalk Enterprise Workbench Report Writer User’s Guide.

Selecting button list box (Win32 only)

Allows multiple selection from a scrollable list, with each item in the list having a check box in addition to its text string.

check box Allows you to turn a selection on or off. Use check boxes when multiple selections are valid at the same time; for example, setting the style attributes of a font, which can be bold and italic at the same time.

combo box Allows display and entry of text as well as selection of a single text item from a drop down list.

container (OS/2 only) Holds a collection of objects which can be viewed as full-size icons, miniature icons, or text. The objects can be placed in arbitrary locations, lined up in columns, arranged in tree form, or shown in a tabular format.




drop-down list Allows the user to select a single text item. Displays a single item by default. User displays entire list by clicking on down-arrow.

list pane Allows the user to select a single text item from a scrollable list.

list view (Win32 only) Displays a collection of items in either Icon view, Small Icon view, List view, or Report view.

multiple choice list Allows the user to select multiple text items from a scrollable list.

radio button Allows the user to select one of multiple possible choices. By convention, radio buttons are mutually exclusive; like the buttons on an old-style car radio, only one choice is active at a time. Used in conjunction with a group pane.

scroll bars (Win32 only)

These parts allow the entry, display, and selection of numbers by dragging the scroll box with the mouse. Also allows numeric input and numeric display when combined with the appropriate parts.

sliders (OS/2 only) These parts allow the entry, display, and selection of numbers by dragging a control with the mouse. Also allows numeric input and numeric display when combined with the appropriate parts.

spin button (Win32 only)

This part allows the entry, display, and selection of numbers by scrolling through a list of choices or by directly entering a number.



spin buttons (OS/2 only)

These parts allow the entry, display, and selection of numbers by scrolling through a list of choices or by directly entering a number. Also allows numeric input and numeric display when combined with the appropriate parts.

table pane You can make various selections based on cells, rows, and columns.

tree view (Win32 only)

Displays a hierarchical list of items, with sublevels that can be expanded or collapsed.

value set (OS/2 only) This part allows you to make a selection from a grid of graphically represented choices. Useful for selecting things like colors or patterns.

Text—Entry and Display combo box Allows display and entry of text as well as selection of a single text item from a drop down list.

entry field Allows display and entry of text at runtime.

rich edit (Win32 only) Allows you to enter and edit text which can have rich text formatting (RTF) applied at both the paragraph and character level. This part implements the Win95 Rich Edit control.

See also the format menu (Win32 only) part, which provides a prebuilt menu of formatting commands.

static text Allows you to display text that the user won’t change directly (i.e. by typing). Useful for labeling controls or groups of controls that don’t have built-in labels.




table pane Displays and accepts data in tabular format.

text pane Allows display and entry of text in a scrollable pane.



APPENDIX

E
Parts for Programming
PARTS Workbench includes many parts that simplify the process of building an application by implementing common programming logic or access to features or programs outside of PARTS Workbench. The following table lists a number of important functions and services and the parts that implement them. The functions and services include the following:

• Arithmetic

• Conditional Execution

• Database

• DDE

• DLLs

• File System Access

• Multimedia

• OLE

• Part Reuse/Performance Tuning

• Properties Management

• System Features

• Type Conversion

• Variables

The description of each part includes the part’s name, its catalog icon, and a brief descriptive comment. See the Part Reference for more information on individual parts.


Parts for ProgrammingAPPENDIX E


Arithmetic computation Performs unary and binary arithmetic operations on Floats and Integers. Can also add and subtract Dates and Times.

Conditional Execution comparison Performs logical comparisons of two values. Use with the link junction.

link junction Tests true/false or nil/not nil and branches accordingly. The comparison part provides a Boolean result that you can use with the link junction.

Also allows you to conveniently perform multiple actions as the result of a single action or perform a single action as the result of multiple actions.

Database Btrieve accessor Allows you to create and access Btrieve databases.

DDE DDE client Allows your application to act as a DDE Client.

DDE server Allows your application to act as a DDE Server.

DLLs C structure Used in conjunction with the DLL accessor, allows you to use C DLLs that require arguments of the C struct data type.

DLL accessor Allows you to access individual procedures in a dynamic link library (DLL).


File System Access disk accessor Allows you to perform standard disk operations such as creating and deleting directories.

file accessor Allows you to perform standard file operations such as reading and copying files.

Multimedia AVI video (Win32 only)

Used to play an AVI (Audio / Video Interleaved) full-motion video file, which is displayed in a video pane (Win32 only) part.

CD audio (Win32 only)

Used to play CD audio discs, using the Media Control Interface.

Wave audio (Win32 only)

Used to play wave audio files, which are digital audio samples in .WAV format.

OLE OLE control (Win32 only)

Allows you to use an OLE control in a PARTS application. An OLE control is a custom control which is implemented as an OLE (Object Linking and Embedding) object.

Part Reuse/Performance Tuning nested part Allows you to reuse a part (PAR format) as a component of another part. It can improve performance during development by delaying the loading of referenced parts.

part accessor Allows you to reuse an executable part as a component in another part. It can improve application performance by dynamically loading and unloading portions of an application as needed.

Properties Management property constructor Used to interactively construct an application’s property manager, which provides a way to retrieve or modify the named properties of an object.



Parts for ProgrammingAPPENDIX E

property interface Provides the interface between an application’s property manager and its Properties dialog. The property interface part can automatically generate a Properties dialog for each named property in the application.

System Features clipboard accessor Allows you to paste and copy bitmaps or text to and from the clipboard.

launch pad Gives you access to the system command line.

printer Allows you to print text and bitmaps.

speaker Allows you to produce sound on the system speaker.

timer Allows you to access the system clock.

Type Conversion conversion Most conversions are performed automatically. This part allows you to control type conversion explicitly.

Variables array holder A specialized value holder for storing arrays. You store and retrieve values from arrays by their numerical index. An array holder has Array-specific messages.

dictionary holder A specialized value holder for storing dictionaries. You store and retrieve values from dictionaries by their key value. Key values are strings. A dictionary holder has Dictionary-specific messages.

number holder A specialized value holder for storing numbers. A number holder has numeric messages.



ordered collection holder

A specialized value holder for storing ordered collections. You can store and retrieve ordered collection values by index, relative to the current position, at the beginning and at the end. An ordered collection holder has OrderedCollection-specific messages.

string holder A specialized value holder for storing strings of characters. A string holder has String-specific messages.

string template A specialized value holder that allows you to create strings which include variables. A string template has specialized messages.

value holder Serves as an untyped variable that can hold any value. You can also assign a class (type) to it in which case the value holder will only accept values of the specified class. Also, when you assign a class to a value holder, it gains additional messages relevant to the specified class.



Glossary

Application Part Each Workbench contains an application part represented by the Workbench background. You build parts by adding parts to an application part.

Argument A value of a specific type required by a message. Argument values are obtained by argument links. The number of arguments required by a message is indicated by the number of colons in the message name.

Argument Connection A colored dot displayed in an expanded message label to indicate where an argument link connects to a message argument. It is the origin for an argument link.

Argument Link An argument link supplies a value for a message argument. It is represented visually as a line between an argument connection and either a value message or a result connection. If argument links are displayed, they are blue or pink by default. When a message is executed that requires arguments, the destination is asked to supply a value. Control flow thus originates with the message that needs the argument value, and data is returned via the argument link.

Catalog The notebook that contains the part icons.

Child Part A part inside of another (Parent) part. For example a push button in a window is a child part of the window. Multiple selections must be Siblings (children of the same part).

Control Point A point on a link line that connects two straight line segments. You create control points to visually format links by routing them around parts in the Workbench.

Destination Part The part that an Event Link points to.

Direct Edit <Alt> clicking on most parts allows you to change one of its properties, such as the name, contents, or label without using its Properties dialog.

Event An event is a signal generated by a part indicating that something has happened. For example, when you click on a push button at runtime, it generates a clicked event.


Glossary

Event Link Connects an event to a message: the event is triggered firing the link and then the link sends the message to the destination part.

Event Value Events with colons in their names provide a value when they are triggered.

External Events and Messages

The events and messages that make up a part’s external interface.

Information Area The pane at the bottom of the Workbench that displays a brief description of the item the cursor is over. The display of information in this area can be disabled with View/Show hints.

Input Focus The part to which user input is directed.

Label Indicates the event (rectangular label) or message (elongated hexagon) that a link is attached to.

Launch To test an application built in the Workbench.

Link Handle Any link connection, label, or control point.

Link Pop-up Menu The menu associated with a particular link, activated when you click the mouse button 2 on a link handle.

Message A command understood by a part.

Message Result The value which is the result of executing a message.

Nil A special value which indicates that no other value is available. Uninitialized values have the value nil. Nil is also used as a result value to indicate that no other value is available when the operation fails to produce a legitimate value. A link junction can be used to conditionally fire a link based on whether the argument it carries is nil or not.

Parent Part A part which contains other parts, such as a window. All parts in a multiple selection must have the same parent part.

Part Icon The appearance of a part in the catalog. Non-visual parts appear as an icon in either the Catalog or the Workbench. Visual parts appear differently in the Workbench than they do in the catalog.

Property An attribute of a part, such as its size or label. Properties may be changed with the property dialog, opened by double-clicking on a part.


Glossary

Resize Handles Black squares around the perimeter of a visual part that serve as handles which can be dragged to resize the part. The presence of resize handles indicates that the part is selected. Nonvisual parts display resize handles to indicate selection but cannot be resized.

Result Link A link which is fired as the result of a message being executed.


Index

Symbols: (colon)

event names 87message names 88, 131

AAbout Visual Smalltalk... (Help menu)

command 191accessing

See also openingCatalog File menu 182file dialogs 18global variables 160instructions for using on-line help 190,

191Link pop-up menu 86, 191, 198, 200on-line tutorial 12, 190, 191part properties 77

Add new links (Scenarios menu) command 189

Add object (Developer menu) command 188Add visible links (Scenarios menu) command

189Add... button (PARTS Settings window) 26adding

catalog pages to catalogs 182context-sensitive help to applications 50directories to Workbench search path 26events to external interfaces 131, 146hints to catalog pages 38link handle control points 110messages to external interfaces 131, 146new links to scenario automatically

Scenarios menu command 189pages to catalogs 42parts to

applications 57catalog pages 40catalogs 133

visible links to scenarioScenarios menu command 189

adding objects 188Align (Workbench Edit menu) command 186Align parts left (tool bar) button 196

Align parts top (tool bar) button 196aligning

catalog page icons 183parts

described 70Edit menu command for 186tool bar buttons 196Workbench grid 24

alphabetic entry fields 202Any File... button (Part File dialog) 20application logic. See linksapplication parts

adding context-sensitive help to 50defined 217as parent of all parts 54

applicationsadding

parts to 57breaking into subsystems 127creating executables 21debugger copies of 167debugging 171deleting parts from 66importing PAR files into 186isolation from part internal

implementation 130launching

described 17Test menu command 188, 189, 190tool bar button 196

printing textual descriptions of 183replacing, in Workbench windows 183sample

opening Catalog of 190, 191saving

File menu commands for 183script changes after launching 154, 159textual descriptions of, generating 32visual descriptions of, generating 34

Apply button (PARTS Settings window) 31argument connections

as argument link origins 91defined 85, 217


Index

argument linkscreating

to event value/result connections 100to part messages 99

debugger representation of 167defined 85, 217described 90displaying

all, in application 114for selected parts 114mouse operations 198, 200

expanding labels of 187Link Firing list and 166

argumentscolon (:) and 131defined 217link colors and 88result links as 94triggerEvent: message 159unsatisfied after link creation 92

arguments, message 88arithmetic functions 212Arrange icons (Catalog File menu) command

183array holder parts 214arrow cursor 14

BBackground Color Settings window 29bitmaps

See also BMP filesCLS files and 23labeling major tabs 43, 44minor tab labels 45screen captures 34

BMP filesSee also bitmapscustomized sign-on dialogs 23

Break on All Links (debugger) control 164breakpoints, link

clearing 188removing 170resuming execution after halting at 172setting 167

Link pop-up menu command 192Test menu command 188

Breakpoints... button (debugger) 165Browse (Workbench Selected menu) command

185Browse / Implementors (Workbench Selected

menu) command 185Browse / Nested part explosion (Workbench

Selected menu) command 185

Browse / References (Workbench Selected menu) command 185

Browse Disk (Developer menu) command 188Browse Packages (Developer menu) command

188Browse Services (Developer menu) command

189browsing

disksDeveloper menu command 188

servicesDeveloper menu command 189

Btrieve accessor parts 212Building 83

CC structure parts 212Cancel button (debugger) 165Cancel button (Part File dialog) 20Cancel button (PARTS Settings window) 32cancelling operations

Esc key 17link firing 165, 173manipulating parts 52

CAPTURE.PAR file 34Catalog File menu 182Catalog File Menu Button 37catalog pages

addingto catalogs 42context-sensitive hints to 38parts to 40to catalogs 182

arranging parts on 41deleting 43, 182numbering 40, 43overview 36removing tabs from 46

Catalog, PARTSfeatures 36overview 35

Catalogs 35catalogs

addingpages to 42parts to 133PAX files to 20

changingdefault background colors 29

changing size of 46, 47closing 40creating 40defined 9, 217deleting parts from 42, 43


Index

on-line help 37opening 38overview 35sample 12saving 39selecting parts in 39

Change destination (Link pop-up menu) command 192

Change events (Link pop-up menu) command 192

Change message (Link pop-up menu) command 192

Change origin (Link pop-up menu) command 192

changingbackground colors 29event link firing sequences 107event link origin 105events firing event links 105, 192information area hints 13link colors 28, 123link destinations 106, 192link messages 192link origins 192message argument values 166, 173messages sent by links 105part reuse modes 127result link destinations 101scripts 154search path directory order 27Workbench grid settings 24

check boxes 207child parts

defined 217described 54

Clear all breakpoints (Test menu) command 188

Clear links (Scenarios menu) command 189clearing

See also deleting; removingall links in scenario

Scenarios menu command 189link breakpoints 170, 188Link Trace Log contents 193

clipboardcopying parts to

Catalog File menu command 182Workbench Edit menu command 185

pasting parts toCatalog File menu command 182Workbench Edit menu command 185

clipboard accessor parts 214clock cursor 14Close (Workbench File menu) command 184

closingcatalogs 40Link pop-up menu 97Workbenches 16, 184

CLS files, format of 19, 23colon (:)

event names 87message names 88, 131

colorsassigning to groups of parts 79background 29link 28

combo boxes 207, 209Comment (Scenarios menu) command 190comparison parts 212compiling PARTStalk code 194computation parts 212conditional execution 212confirmer parts 202confirmer with cancel parts 202constructing parts

defining external interfaces 145external interface 130internal implementation 138overview 125reasons for 127

Contents (Help menu) command 190, 191context-sensitive help

adding to application parts 50catalog page hints 38

control pointsadding 110defined 217deleting 110, 192described 87moving 110

conversion parts 214converting message argument data types 92converting parts

utility for 22Copy (Edit menu) command 194Copy (Workbench Edit menu) command 185Copy part (Catalog File menu) command 182copying

text to clipboard 194copying parts

before deletion 66Catalog File menu command 182described 68Workbench Edit menu command 185

Create Argument Link dialog 99Create Link dialog 98Create link... (Workbench Selected menu)

command 184


Index

Create result link (Link pop-up menu) command 192

Create Result Link dialog 101creating

catalogs 40comment for scenario

Scenarios menu command 190links

described 98mouse operations 197, 199

part user interfaces 140PARTS.INI files 26result links 101, 192scenarios

Scenarios menu command 189textual descriptions of applications 32visual descriptions of applications 34

creating nested parts 186cross-referencing (Xref menu) 195CRS files, format of 23currency entry fields 205cursors 14customizing

Workbench settings 25Cut (Edit menu) command 194Cut (Workbench Edit menu) command 185Cut part (Catalog File menu) command 182

Ddata types, message argument 92database functions 212date entry fields 202DDE client parts 212DDE server parts 212Debug (Test menu) command 188Debugger Log menu 193debugger, PARTS Workbench

features 163launching 167opening 188

debugging applications 171defining part external interfaces 145Delete (Edit menu) command 194Delete (Interface menu) command 193Delete (Workbench Edit menu) command 186Delete all Control points (Link pop-up menu)

command 192Delete button (PARTS Settings window) 27Delete link (Link pop-up menu) command 192Delete page (Catalog File menu) command 182Delete selected parts (tool bar) button 196deleting

catalog page tabs 183catalog pages 43, 182

link handle control points 111, 192links 103, 192parts

from applications 66Catalog File menu command 182from catalogs 42tool bar button 196without affecting clipboard 186Workbench Edit menu command 185

tabs from catalog pages 46deleting scripts 156, 193delivering applications

files required for 21DELIVERY.TXT file 21Describe page... (Catalog File menu) command

182desktop, adding parts to applications from 58,

64destination parts 217Developer (Workbench) menu 188dial panes 205dialog windows 202dictionary holder parts 214Cincom copyright notice 23direct-editing parts

defined 217described 80mouse operations 197, 199Selected menu command for 184

directorieschanging search path order of 27modifying search path 25viewing PARTS Workbench search path 18viewing search path 19

disablinginformation area 13Workbench grid 28

Discard tab (Catalog File menu) command 183disk accessor part 213disks

browsingDeveloper menu command 188

Display scenario (Scenarios menu) command 189

displayingargument links 114help topics 190, 191information area hints 187link labels

described 115Link pop-up menu command 192mouse operations 198, 200tool bar button 196Worbench View menu command 187


Index

linksall, in application 114connected to selected parts 111firing at execution halt 166Selected menu command 184specific, connected to selected parts

113tool bar buttons 196View menu command 187

Open Part dialog 183part names 160scenario

Scenarios menu command 189Distribute (Workbench Edit menu) command

186distributing part spacing. See also aligning parts

72, 186double-headed arrow cursor 14drawn buttons 203drop-down lists 208Duplicate (Workbench Edit menu) command

186dynamic data exchange (DDE) functions 212

EEach 75Edit direct (Workbench Selected menu)

command 184Edit interface... (Workbench Selected menu)

command 184Edit menu 194

Workbench 185edit menu parts 203Edit properties... (Workbench Selected menu)

command 184Edit scripts... (View menu) command 187editing

See also changing; direct-editing; property editing

part interfaces 184scripts 187trace log, debugger 175

edits, undoing 194ellipsis (...) 80embedded reuse mode 129enabling

automatic catalog opening 38information area 13Workbench grid 28

ensemble reuse mode 128ensembles, part 128entry fields

overview 209

environment, PARTS Workbenchobjects in 9

error warning messages 154Evaluate (Script menu) command 194event connections

defined 85moving 104

event labelsdefined 86of events providing values 87

event linkschanging

events firing 105origin of 105, 192

creating 98debugger representation of 166defined 85, 218described 89displaying all in application 114sequencing 107, 184

event value connectionsarguments and 91creating argument links to 100defined 85

event valuesas argument sources 93defined 218

eventsSee also external interface, part; external

eventsadding to external interfaces 131, 146defined 217described 87execution of 89triggering specific 172user-defined 151

events from scripts, triggering 159Exclusive displays (Scenarios menu) command

189exclusive displays of scenario links

Scenarios menu command 189EXE files

format of 19launching applications as 17saving applications as 21

executable partssaving

described 20execution

See also breakpoints, linkargument link 93conditional 212debugger controlling 163event link 89


Index

result link 96resuming after link breakpoints 165, 171,

172single-step 164speeding application 127

Expand (Workbench Selected menu) command 185

Expand labels (tool bar) button 196Expand labels (View menu) command 187expanded parts

overview 52resizing 69

expandinglink labels

Link pop-up menu command 192mouse operations 198, 200tool bar button 196View menu command 187

partsdescribed 72Selected menu command for 185

Export (Interface menu) command 193Export button 147external events

messages added to internal implementation for 139

syntax 147External Interface windows, opening 131, 145external interfaces, part

addingevents to 146messages to 146

constructing 130defining 145editing 184event and message syntax 147independence from internal

implementation 127external messages

events added to internal implementation for 138

syntax 147

FF1 key help 13

adding to parts 51for existing parts 50

F7 key 55file accessor parts 213file dialog parts 207file extensions, file formats and 19file list pane (Part File dialog) 18File menu

Workbench 183

file menu parts 204File Name field (Part File dialog) 18file system access functions 213files

adding parts to applications from 60, 65Find Again (Edit menu) command 194Find/Replace... (Edit menu) command 194float entry fields 205fonts, assigning 79Format list box (Part File dialog) 19

GGeneral help (Help menu) command 190global variables

accessing 160Go button (debugger) 165, 171graph panes 203grid, Workbench, setting 187group panes 206GUIs (graphical user interfaces)

building 140parts

confirming operations 202creating/displaying graphics 203displayed at runtime 202enabling selections 207formatted text entry and display 202initiating operations 203notification 205numbers, entering/displaying 205organizing controls 206prompting user input 207text entry and display 209

Hhandles, resize


Help index (Help menu) command 190, 191Help menu 190, 191Help menu (OS/2) 12Help menu (Windows) 11help, on-line. See on-line helpHide all links (tool bar) button 196Hide all links (View menu) command 187Hide labels (tool bar) button 196Hide labels (View menu) command 187Hide link (Link pop-up menu) command 192Hide links (Workbench Selected menu)

command 184Hide/Show labels (Link pop-up menu)

command 192


Index

hidinglink labels

described 116Link pop-up menu command 192mouse operations 198, 200tool bar button 196View menu command 187

linksdescribed 115Link pop-up menu command 192Selected menu command 184tool bar buttons 196View menu 187

hintsadding to catalog pages 38, 182information area 13, 187

hour glass cursor 14How to Use Help (Help menu) command 190

II-beam cursor 14icons

CLS files and 23EXE file 21nonvisual part 53rearranging catalog page 183shrunken part 52, 73

Implementors (Xref menu) command 195Import part... (Workbench Edit menu)

command 186importing parts 60, 65, 186incoming links, displaying 196information area help/hints

for existing parts 50adding to application parts 51catalogs and 37defined 218displaying 187mouse operations 13

information dialogs 205input focus

See also tab orderdefined 218

Insert new page (Catalog File menu) command 182

Insert part file... (Catalog File menu) command 182

inserting. See pastingInspect (Developer menu) command 188Inspect... (Script menu) command 194Inspector windows 194integer entry fields 205Interface... button 78

internal implementation, partapplication isolation from 130constructing 138

Kkeyboard shortcuts 12, 190Keys help (Help menu) command 190

Llabels

direct-editing 80major tab 43, 44minor tabs 45nonvisual part icon 53

Launch (Test menu) command 188Launch (tool bar) button 196launch pad parts 214launching

applicationsdescribed 17Test menu command 188, 189, 190tool bar button 196

debugger 167defined 218

link colorsarguments and 88changing default 28described 122

Link colors... button 28link firing

cancelling 173single step 164

Link Firing List (debugger) 166link firing sequence. See sequencing event

linkslink handles

See also control pointsaccessing Link pop-up menu 191defined 218described 86

Link Information area (debugger) 165link junction parts 212link labels

defined 218displaying

described 115Link pop-up menu command 192mouse operations 198, 200tool bar button 196Workbench View menu command 187

expandingmouse operations 198, 200tool bar button 196View menu command 187


Index

hidingdescribed 116Link pop-up menu command 192tool bar button 196View menu command 187

moving 117setting display preferences for 121shrinking 192

Link pop-up menuaccessing 86, 198, 200defined 218described 97, 191

link properties 121Link Trace log 193Link Values (debugger) pane 166linked nested parts, importing 60, 65linked reuse mode 129links

See also event linkschanging

destination of 192destinations of 106messages sent by 105, 192

debugger representation of visual 166deleting 103, 192displaying

all, connected to selected parts 111all, in application 114firing at execution halt 166Selected menu command 184specific, connected to selected parts

113View menu command 187

formatting 86hiding

described 115Link pop-up menu command 192Selected menu command 184tool bar button 196View menu 187

logging firing of 193mouse operations 197, 198, 199, 200setting display preferences for 121specifying colors of 28textual descriptions of 32

list panes 208log files, debugger 193logic, application. See links

Mmajor tabs

overview 37reunumbering catalog pages 40setting 43, 182

menu bitmap items 203menu items

See also entries for specific menu itemsdisabled 181tool bar correspondences to 196viewing help for 13

menu parts 204Merge (Workbench Edit menu) command 186merging nested parts 186message arguments

changing values of 173examining values of 171viewing names of 174

message connectionsargument links and 91defined 85moving 104result link connections to 94

message labelsdefined 86of messages requiring arguments 88unsatisfied arguments 92

message resultsSee also result linksas argument values 88defined 218

messagesSee also external interface, part; external

eventsadding to external interfaces 131, 146breakpoints and execution of 167changing, sent by links 105, 192creating argument links to part 99defined 218described 88firing in specific sequences 95to typed value holders 160user-defined 151

minor tabsoverview 36setting 45, 182

minus sign cursor 15Mouse 198, 200Mouse Buttons... (PARTS Settings window) 31mouse operations

described 197overview for OS/2 14overview for Windows 14

mouse operations (OS/2)described 199

movingcontrol points 111event or message connections 104link handles 198, 200


Index

link labels 117parts 67, 197, 199

multiple choice lists 208

NNest... (Workbench Edit menu) command 186nested parts

defined 126defining external interfaces for 145overview 213referencing parts 18reuse modes and 129shrinking 73

nested scenario, pairingScenarios menu command 190

New (Catalog File menu) command 182New (Interface menu) command 193New (Workbench File menu) command 183New Workbench (Developer menu) command

189New Workspace (Developer menu) command

188nil value

defined 218"‘No" symbol cursor 15nonvisual parts

described 53notation, debugger 166notebooks 206number holder parts

defined 214direct-editing 80

OOK button (Part File dialog) 19OK button (PARTS Settings window) 31on-line help 11

accessing instructions for using 190, 191catalog 37menu commands 181for parts 50

Open catalog... (View menu) command 187open event

debugger Go button triggering 165launching applications 17

open messagelaunching applications 17

Open Part dialog, displaying 183Open... (Catalog File menu) command 182Open... (Workbench File menu) command 183opening

See also accessing; launchingcatalogs 38, 182debugger 188

External Interface window 131External Interface windows 145Inspector windows 194PAR files 15PARTS Settings window 25prompters 195workbench window

Developer menu command 189Workbench windows 183Workbenches 15workspace window

Developer menu command 188operating systems, migrating parts across 23ordered collection holder parts 215OS/2 Help 12

Ppackaged part reuse modes 129packaging, part

advantages of 127ensembles vs. 128

Page Forward/Backward buttons 37pages, catalog. See catalog pagespairing

nested scenarioScenarios menu command 190

Pairings... (Scenarios menu) command 190PAR files

adding parts to catalogs from 41format of 19importing into applications 186opening 15, 183pasting into notebook pages 182saving applications as 21

parent partsdefined 218described 54

part accessorsdefined 213PAX files and 20

part file converter utility 22Part File dialogs 18part files. See PAR filespart icons

cursors as 14defined 218

part namesassignment of 57of copied parts 68direct-editing 80

partsaccessing system features 214adding to

applications 57


Index

catalog pages 40aligning 70

Edit menu command 186tool bar buttons 196

arranging on catalog pages 41copying

described 68to clipboard 182, 185

defined 9deleting

from applications 66Catalog File menu command 182from catalogs 42tool bar button 196from Workbench 185

described 125direct-editing 80, 184distributing spacing of 72, 186duplicating 186, 197, 199expanding 72, 185implementing behavior of 142loading when needed 127migrating across platforms 23moving 67pasting to clipboard 68, 182, 185property editing 184referenced by nested parts 18referencing (Xref menu) 195resizing 69, 186saving

described 16selecting

in applications 55, 185in catalogs 39

setting propertiesfor groups of 79for individual 78

shrinkingdescribed 72Selected menu command 185

textual descriptions of 32user interface 201viewing help for 13

Parts List (debugger) control 165PARTS Settings window 25PARTS Workbench

debugger 163features 10menus and menu items 181on-line information about 190, 191overview 9version numbers 13, 190, 191

PARTS.CAT file location 36PARTS.INI files 26

Paste (Edit menu) command 194Paste (Workbench Edit menu) command 185Paste part (Catalog File menu) command 182pasting parts 68, 182, 185paths, PARTS Workbench search 18PAX files

format of 19phone number entry fields 203picture entry fields 203pixels

Workbench grid specifications 24Print (Workbench File menu) command 183printer parts 214printing

textual descriptions of applications 32, 183

Product information... (Help menu) command 190

prompters 195, 207properties

defined 218Properties dialogs

application partadding context-sensitive help 50part reuse modes 127

overview 77properties, part

affected by direct-editing 80overview 75

property editingmouse operations for 197, 199Selected menu command for 184

push buttons 204

Rradio buttons 208Redo (Workbench Edit menu) command 52,

185redoing

changes to part properties 79last part manipulation 185

References (Xref menu) command 195Remove scenario (Scenarios menu) command

190Remove visible links (Scenarios menu)

command 189removing

scenarioScenarios menu command 190

visible links from scenarioScenarios menu command 189

Rename scenario (Scenarios menu) command 190


Index

renamingscenario

Scenarios menu command 190Replace... (Workbench File menu) command

183replacing

applications in Workbench window 183text 194

Reset button (Link Color Settings window) 123Reset Log (Debugger Log menu) command

193resize handles


resizingCatalog windows 183parts 69, 186, 197, 199

Restore (Script menu) command 194result connections

as argument sources 93arguments and 92creating argument links to 100defined 85

result linkscreating 101, 192debugger representation of 167defined 85, 219described 94displaying all in application 114Link Firing list and 166

reusing partscustomized 127nested parts 213overview 126reuse modes 127

SSame size (Workbench Edit menu) command

186sample applications

opening catalog of 190, 191Samples (Help menu) command 190, 191Save (Catalog File menu) command 182Save (Debugger Log menu) command 193Save (Script menu) command 194Save (Workbench File menu) command 183Save as... (Debugger Log menu) command 193Save as... (Workbench File menu) command

183saving

applicationsdescribed 16File menu commands 183

breakpoints in applications 169

catalogs 39, 182debugger log files 193executable applications 21PAR files 132parts to catalogs 133

saving scripts 194scenario

adding new links automaticallyScenarios menu command 189

adding visible linksScenarios menu command 189

removing visible links fromScenarios menu command 189

substituting visible linksScenarios menu command 189

scenario, clearing all linksScenarios menu command 189

scenario, creatingScenarios menu command 189

scenario, creating comment forScenarios menu command 190

scenario, displayingScenarios menu command 189

scenario, removingScenarios menu command 190

scenario, renamingScenarios menu command 190

Scenarios (Workbench) menu 189screen, capturing images from 34scripts

changing 154deleting

Delete (Interface menu) command 193

Delete button 156saving 194triggering events from 159undoing edits to 194

scripts, editing 187scroll bars 206, 208Search for Help on... (Help menu) command

191Search Path list box (Part File dialog) 19Search Path list box (PARTS Settings window)

25search path, PARTS Workbench 18searching for text 194Select all (Edit menu) command 194Select Directory dialog 26Select... (Workbench Selected menu) command

185Selected menu, Workbench 184Selected/Edit interface... command 78


Index

selectingmenu commands 181parts

in applications 55, 185in catalogs 39mouse operations 197, 198, 199, 200

selecting text 194Senders (Xref menu) command 195Senders... (Xref menu) command 195Sequence Directories dialog 27Sequence Links dialog 107Sequence links... (Workbench Selected menu)

command 184Sequence... button (PARTS Settings window)

27sequencing event links

described 107Selected menu command for 184

servicesbrowsing

Developer menu command 189Set all breakpoints (Test menu) command 188Set grid... (View menu) command 187Set major tab (Catalog File menu) command

182Set minor tab (Catalog File menu) command

182Set/Clear breakpoint (Link pop-up menu)

command 192setting

link and link label preferences 121link breakpoints 167

Link pop-up menu command 192Test menu command 188

major tabs 43, 182minor tabs 45, 182properties for

groups of parts 79individual parts 78

Workbench grid 24, 187Workbench preferences 25, 183

Settings... (Workbench File menu) command 183

shortcuts, keyboard. See keyboard shortcutsShow all links (View menu) command 187Show hints (View menu) command 187Show incoming links (Selected menu)

command 184Show incoming links (tool bar) button 196Show labels (tool bar) button 196Show labels (View menu) command 187Show labels with links (View menu) command

187Show labels with links property 121

Show links (Selected menu) command 184Show links (tool bar) button 196Show links with selection (View menu)

command 187Show Links with selection property 121Show outgoing links (Selected menu)

command 184Show outgoing links (tool bar) button 196Show some links... (Selected menu) command

184Shrink (Workbench Selected menu) command

185Shrink/Expand labels (Link pop-up menu)

command 192shrinking

link labels 192parts 72, 185

shrunken parts 52sibling parts 54sign-on dialogs, creating customized 23Single-Step Execution area (Debugger

window) 164Size (Catalog File menu) command 183sliders 206, 208, 210source code, applications as Smalltalk 23speaker parts 214spin button (Win32 only) 206, 208spin buttons 209spin buttons (OS/2 only) 206static graphics. See also bitmaps; icons 203static text parts 209string holder parts

defined 215direct-editing 80

string template parts 215Substitute visible links (Scenarios menu)

command 189substituting

visible links in scenarioScenarios menu command 189

syntax, external interface 147system features, parts accessing 214

Ttable panes 209, 210tabs, catalog. See major tabs; minor tabsTest (Workbench) menu 188text, Edit menu commands for 194The 163This 97, 109, 125, 151, 177timer parts 214title bars, PARTS Catalog 36To 99


Index

top-level partsdescribed 53shrinking and expanding 72

Trace links (Debugger Log menu) command 193

trace log (debugger) 175Trace Log area (debugger window) 166Trigger event... button (debugger) 165, 171triggerEvent:withArguments message 159Tutorial (Help menu) command 190, 191tutorial, accessing on-line 12, 190, 191typed value holders

messages to 161

UUndo (Workbench Edit menu) command 52,

185undoing

changes to part properties 79last part manipulation 185

User name field (PARTS Settings window) 25user-defined messages and events 151Using help (Help menu) command 190

Vvalue holder parts 215value sets 209values

argument links supplying 90arguments supplied by event 88changing message argument 173direct-editing part 80event 87, 218

variables 214version numbers, PARTS Workbench 13, 190,

191version numbers, Visual Smalltalk 12View (Workbench) menu 187viewing

message argument values for links 166part properties 77part reuse modes 127

visual partsautomatic resizing of 69described 52direct-editing text values of 80displayed at runtime 202

Visual Smalltalkversion numbers 12

WWindow Layout property

resizing parts and 69Window page, parts on 36

windowsoverview 202

Windows Help 12Word wrap (Edit menu) command 194Workbench default settings (PARTS Settings

window) 28Workbench grid field (PARTS Settings window)

28Workbench grid, setting 24Workbench Selected menu 184workbench window

openingDeveloper menu command 189

Workbencheschanging default background colors 29closing 16, 184defined 9described 10opening 15replacing applications in 183setting

breakpoints in 169preferences for 25

workbencheslaunching applications from 17

workspace windowopening

Developer menu command 188wrapping text 194

XX axis, Workbench grid 24Xref menu 195

YY axis, Workbench grid 24You 49


ess

FAX IT!

WE STRIVE FOR QUALITY

Reader Comment Sheet Name:

Job title/function:

Company name:

Address:

Telephone number: ( ) - Date: / /

How often do you use this product? # Daily # Weekly # Monthly # L

How long have you been using this product? # Months # Years

Can you find the information you need? # Yes # No

Please comment.

Is the information easy to understand? # Yes # No

Please comment.

Is the information adequate to perform your task? # Yes # No

Please comment.

General comment:

To respond, please fax to Larry Fasse at (513) 612-2000.

P46-0203-00

visualsmalltalk enterprisealereimondo.no-ip.org/papers/uploads/2/wbenchug.pdf · shortcuts. for...

Documents