ADEPT SERIES

ACL Designer
Version 1.0

ArborText, Inc.
1000 Victors Way
Ann Arbor, Michigan USA 48108-2700
Telephone: +1 313.997.0200
FAX: +1 313.997.0201
Website: www.arbortext.com
Email: [email protected]
ii Contents

Copyright © 1997, 1998 by ArborText, Inc.. All rights reserved. No part of this work covered by the copyright herein
may be reproduced or used in any form or by any meansgraphic, electronic, or mechanical, including photocopying,
recording, taping, or information storage and retrieval systemswithout the written consent of ArborText, Inc.
Portions of this manual copyright 1994 Visix Software Inc. 11440 Commerce Park Drive, Reston, VA 22091. Used
with permission.
Unpublished rights reserved under the copyright laws of the United States.
Software Licensing
ArborText, Inc. holds right, title, and interest in the software described herein. The software, or any copies thereof,
may not be made available to, or distributed to, any person or installation without the written consent of ArborText, Inc.
Software Status
The software described by this publication is subject to change without notice.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in the Rights in Technical Data
and Computer Software clause at DFARS 252.2277013, the Commercial Computer Software-Restricted Rights clause
at FAR 52.22719 or subparagraphs (c)(1) and (2) of the Commercial Computer Software-Restricted Rights at 48 CFR
52.22719 as applicable.
Trademarks
The ArborText ADEPT Series, ADEPT•Editor, ADEPT•Publisher, Document•Architect, ACL Designer, TurboParser,
are trademarks of ArborText, Inc..
Third-Party Trademarks
API Toolkit is a trademark of InterCAP Graphics Systems, Inc.
Carberry software is a registered trademark of Carberry Technologies, Inc.
DEC is a registered trademark of Digital Equipment Corporation.
Documentum and Documentum WorkSpace are trademarks of Documentum, Inc.
Elan License Manager and Softlock are trademarks of Elan Computer Group, Inc.
Galaxy Application Environment is a licensed trademark of Visix Software, Inc.
HP and Hewlett-Packard are trademarks of Hewlett-Packard Company.
IBM is a registered trademark of International Business Machines Corporation.
IslandDraw and IslandPaint are trademarks of Island Graphics Corporation.
OSF/Motif and Motif are trademarks of the Open Software Foundation, Inc.
Oracle is a registered trademark of Oracle Corporation
PostScript is a registered trademark of Adobe Systems Incorporated.
Proximity and Linguibase are registered trademarks of Proximity Technology, Inc.
SGI is a trademark of Silicon Graphics Incorporated.
SPARC is a registered trademark of SPARC International, Inc. Products bearing the SPARC trademarks are based on
an architecture developed by Sun Microsystems, Inc.
SPARCstation is a trademark of SPARC International Inc., licensed exclusively to Sun Microsystems, Inc.
Sun, SunOS, Solaris, NFS, and OpenWindows are trademarks of Sun Microsystems, Inc.
TeX is a trademark of the Mathematical Society.
UNIX is a registered trademark.
Windows, Windows for WorkGroups, and Windows NT and Windows95 are registered trademarks of Microsoft, Inc.
X Window System is a trademark of X Consortium, Inc.
All trademarks and registered trademarks are the property of their respective owners.

Updated: August 14, 2000

CONTENTS

Chapter 1: Introduction .......................................................................................................... 1

Who Should Read this Manual .................................................................................... 1
ACL Designer Configuration ...................................................................................... 2
Look-and-Feel Considerations .................................................................................... 2

Chapter 2: Installing ACL Designer ...................................................................................... 3

Before you begin ......................................................................................................... 3
Platforms ..............................................................................................................3
What you will need...................................................................................................... 4
Installing ACL Designer on UNIX.............................................................................. 4
Preparing to Install ACL Designer on Windows ......................................................... 7
Moving the installation files to a server ...............................................................7
Installing ACL Designer on a server for client access .........................................8
Sharing the distribution CD-ROM .......................................................................8
Creating installation diskettes ..............................................................................9
Installing ACL Designer on Windows....................................................................... 11
Editing the acldes.ini file on Windows...................................................................... 11
Saving Preference Settings for Single-User Installations ...................................11
Changing the Default Resource/Configuration File Location ............................12
Saving Preference Settings for Multi-User Installations ....................................12
Installing ACL Designer on OS/2 ............................................................................. 12
Directory and Pathnames ....................................................................................12
CD-ROM Installation Instructions .....................................................................13
ACL Designer Program Icon ..............................................................................13
Setting environment variables ............................................................................14

Chapter 3: Overview of ACL Designer................................................................................ 15

What Is ACL Designer? ............................................................................................ 15
Why Use ACL Designer? .......................................................................................... 16
Resources................................................................................................................... 17
Resource Files............................................................................................................ 17
Starting and Quitting ACL Designer ......................................................................... 18
Opening Resource Files............................................................................................. 20
Resource File Icons (UNIX only).............................................................................. 21
Setting Preferences .................................................................................................... 21
Application Preferences Dialog ..........................................................................21
Color and Font Preferences ................................................................................22
Automatic File Saving Preference ......................................................................23
Save Window Positions Preference ....................................................................23

iii
iv Contents

Windows Overview ................................................................................................... 24

Main Window .....................................................................................................24
Dictionary Editor ................................................................................................24
Resource Editors .................................................................................................25

Chapter 4: Resource Editor Overview................................................................................. 33

Editors and Panels ..................................................................................................... 33
Default Attributes ...................................................................................................... 33
Resource Editor Menus ............................................................................................. 34
Using the File Menu .................................................................................................. 34
Using the Edit Menu.................................................................................................. 36
Using the Panels Menu .............................................................................................. 38

Chapter 5: Dictionaries ......................................................................................................... 39

Overview of the Dictionary Editor ............................................................................ 39
Creating Resources .................................................................................................... 40
Dictionary Arrays ...................................................................................................... 42
Viewing Dictionaries ................................................................................................. 43
Editing Resources ...................................................................................................... 44
Finding Resources ..................................................................................................... 46
Copying and Moving Resources................................................................................ 47
Adding Resources to the New Menu ......................................................................... 47
Creating Subclassed Resources ................................................................................. 48
Generating Files......................................................................................................... 48
Customizing the View of the Dictionary Editor ........................................................ 48
The vobjectInheritance Dictionary ............................................................................ 49

Chapter 6: Dialogs ................................................................................................................. 51

Opening a Dialog Editor............................................................................................ 52
Dialog Editor Panels .................................................................................................. 52
Setting Window Attributes for a Dialog .................................................................... 53
The Item Palette......................................................................................................... 55
Creating a Dialog....................................................................................................... 55
Using the Dialog Panel’s Edit Menu ......................................................................... 58
Sizing Dialog Items in the Dialog Panel ................................................................... 60
Arranging Items in a Dialog ...................................................................................... 60
The Order Items Panel ............................................................................................... 62
Customizing the Item Palette..................................................................................... 63
Testing Your Dialog................................................................................................... 64
Working with Connections ........................................................................................ 65

Chapter 7: Dialog Items ........................................................................................................ 75

Dialog Item Overview ............................................................................................... 75
Supported dialog items .......................................................................................76
Unsupported dialog items ...................................................................................76
The Dialog Item Panel ............................................................................................... 76
Dialog Item Attributes ........................................................................................78
Dialog Items on the Item Palette ............................................................................... 80
Dialog Items from the New Item Menu..................................................................... 94

Chapter 8: Windows and Other Resources ....................................................................... 103

Overview of Windows ............................................................................................. 103
The Window Resource............................................................................................. 103
The Confirm Dialog................................................................................................. 105
The Notice Dialog ................................................................................................... 107
 Contents v

Chapter 9: Menus................................................................................................................. 109

Overview of Menus ................................................................................................. 109
The Window Panel................................................................................................... 109
The Menu Panel....................................................................................................... 110
Menus ...............................................................................................................111
Menu Items .......................................................................................................111
Mnemonic Keys ................................................................................................112
The Menu Item List .........................................................................................113
Testing a Menu .................................................................................................113

Chapter 10: Images.............................................................................................................. 115

The Image Editor ..................................................................................................... 115
Importing and Exporting Images ............................................................................. 116
Setting the Size of an Image .................................................................................... 116
Using the View Menu .............................................................................................. 117
The Show Position Command ..........................................................................118
Saving the View of an Image ............................................................................118
Creating an Image.................................................................................................... 119
Setting Colors for Drawing...................................................................................... 120
Setting Line Width for Drawing .............................................................................. 121
Using the Selection Tools ........................................................................................ 122
Adding Text to an Image ......................................................................................... 122
Viewing an Image .................................................................................................... 123
Using Undo and Erasing.......................................................................................... 124
The Color Palette ..................................................................................................... 124
Viewing a Color Palette ....................................................................................125
Modifying a Color Palette ................................................................................125
Saving a Color Palette ......................................................................................126
Creating an Image Transparency ............................................................................. 127
The Cursor Editor .................................................................................................... 127

Chapter 11: The Font Chooser ........................................................................................... 129

About the Font Chooser........................................................................................... 129
Dragging and Dropping Fonts (UNIX only) ........................................................... 130

Chapter 12: The Color Chooser ......................................................................................... 131

About the Color Chooser ......................................................................................... 131
Color Box .........................................................................................................132
Color View Area ...............................................................................................132
Slider Bars ........................................................................................................133
Defining Color Tolerances....................................................................................... 134
Using the HLS Color Model.................................................................................... 135
The HLS Color Wheel ......................................................................................136
Using the RGB or CMY Color Model..................................................................... 137
The RGB/CMY Color Plane ............................................................................138
Using the Grayscale Model ..................................................................................... 139
Named Colors .......................................................................................................... 140
Saved Colors............................................................................................................ 141
Applying Colors ...................................................................................................... 141
Dragging and Dropping Colors ............................................................................... 142

Chapter 13: The File Chooser............................................................................................. 143

Using the File Chooser Menus ................................................................................ 144
Additional Features of the File Chooser.................................................................. 145
vi Contents

Chapter 14: Modifying the ADEPT Interface ................................................................... 149

Creating dialogs ....................................................................................................... 149
Creating form regions .............................................................................................. 150
Creating toolbars...................................................................................................... 150
Modifying ADEPT’s default toolbars ...............................................................152
Editing the ADEPT interface ................................................................................... 152

Chapter 15: ACL Designer ACL Functions ...................................................................... 155

Overview ................................................................................................................. 155
ADEPT Command Language concepts ................................................................... 155
Attributes ................................................................................................................. 156
Dialog attributes ...............................................................................................156
Dialog item attributes .......................................................................................156
Dialog item-specific attributes .........................................................................157
Callbacks ................................................................................................................. 157
Callback event codes ........................................................................................158
Outline List Item Handling...................................................................................... 158
Image Handling ....................................................................................................... 160
ACL Designer ACL functions ................................................................................. 160
dlgitem_set_active_at .......................................................................................160
dlgitem_set_appdata_at ....................................................................................160
dlgitem_set_branch_image_at ..........................................................................161
dlgitem_set_extra_image_at .............................................................................161
dlgitem_set_leaf_image_at ...............................................................................161
dlgitem_set_refresh ..........................................................................................162

Chapter 16: Index ................................................................................................................ 163

CHAPTER
1
Introduction

NOTE: Some information in this manual is obsolete due to updates in recent versions of
Adept and Epic. Keep the following points in mind while using this manual:

• The term “ADEPT” is used throughout this manual. However, this manual’s
information applies to both the Adept and Epic series of products.
• The information in this manual can still be used to create toolbars, to create form
regions, and to modify existing forms by removing controls.
• Arbortext recommends that you do not use ACL Designer to create dialogs.
Instead, use a programming language such as Java or Visual Basic.
• In releases of Epic 4.0 and later, replace references to "adept.vr" with
"epic.vr".

This manual includes the following information regarding the ADEPT Series ACL Designer.
• Installation instructions
• Reference information
• Information on modifying the ADEPT interface

Who Should Read this Manual

ACL Designer separates the task of creating user interfaces from application programming.
Consequently, this manual is intended for application programmers, user interface designers,
and others involved in designing and testing user interfaces.

1
2 Chapter 1 Introduction

ACL Designer Configuration

This manual assumes that the ACL Designer is configured to the defaults as originally shipped.
Default settings that have been changed by you or your system administrator may cause certain
behavior or defaults to be different than described in this manual.

Look-and-Feel Considerations
The screen shots used in this manual are from a UNIX workstation running X Windows under
the Motif look-and-feel. Several of the screen shots in this manual refer to the Visual Resource
Builder. The Visual Resource Builder is a third party application on which ACL Designer is
based.
CHAPTER
2
Installing ACL Designer

Before you begin

This guide assumes you are familiar with the operating system at your site and with standard
system administration tasks necessary to install new software applications.

Platforms
This guide includes instructions for installing ACL Designer on the following systems:
• Sun™ workstation running Solaris 2.5.1 or SunOS 4.1.3
• HP™ 9000 Series 700 and 800 workstations running HP-UX 9.0.3 or 10.2
• IBM® RS/6000 running AIX 4.1
• DEC® 3000 Alpha AXP running Digital UNIX 3.2
• Silicon Graphics workstations (SGI™) running IRIX 6.2
• An IBM-compatible PC running either Windows NT 4.0, Windows 95, Windows for
Workgroups 3.11, Windows 3.1, or OS/2 Warp 3.x or 4.x
This guide also includes information for installing ACL Designer/Global (for use with
ADEPT•Editor/Global and ADEPT•Publisher/Global) on the following systems:
• Sun™ workstation running Solaris 2.5.1
• HP™ 9000 Series 700 and 800 workstations running 10.2
• IBM® RS/6000 running AIX 4.1
• An IBM-compatible PC running either Windows NT 4.0, or Windows 95

3
4 Chapter 2 Installing ACL Designer

What you will need

Be sure you have the following:
• The ACL Designer distribution CD-ROM.
• A supported system on which to install ACL Designer. ACL Designer requires 15MB (or
less) for UNIX installations, and 6MB for Windows installations.
• The host name of the device from which to install the CD-ROM (UNIX installations).
• The CD-ROM device name (UNIX installations).

Installing ACL Designer on UNIX

Follow the procedures below to install ACL Designer on UNIX platforms.

To determine login for installation:

1. The installation should be done from the site administrator's login or from a special
login for installation purposes.
NOTE: Log into the account that will be used for installation and maintenance. DO
NOT login as root when reading the ACL Designer CD-ROM contents into
the installation directory and DO NOT install as a super-user. The software
is designed to be installed on a normal user login; otherwise you create file
permission problems that can result in user execution problems. It is also
strongly recommended that you create a separate directory used only for
ACL Designer.

To create an ACL Designer directory:

1. In your installation directory, create a directory where you will install the ACL
Designer software (this directory is referred to as ACLDES-PATH throughout these
installation instructions).
Enter the following command:
mkdir ACLDES-PATH
where ACLDES-PATH represents the location where ACL Designer is being installed.
This should not be in a read-only file partition, and should be accessible by all ACL
Designer users. This directory should be empty at this point.
If you wish to install the ACL Designer files for multiple platforms in a single location,
create platform directories in the ACLDES-PATH directory.
For example:
mkdir /acldes/alpha
mkdir /acldes/hppa10
mkdir /acldes/hppa9
mkdir /acldes/rs6000
mkdir /acldes/sgi
mkdir /acldes/sun4
mkdir /acldes/sun4r5

2. Enter the following command:

chmod 755 ACLDES-PATH
This command sets the necessary permissions for the ACLDES-PATH directory. If you
created platform-specific directories for multiple installations, execute this command
for each of the new directories.
 Installing ACL Designer on UNIX 5

To extract files from the CD-ROM:

1. Insert the CD-ROM and change directories to the parent directory of your CD-ROM
mount point. If you haven’t already done so, create a directory for your CD-ROM
mount point (for example, cdrom).
mkdir /cdrom
2. Mount the CD-ROM. You may have to temporarily log in as root to mount the CD-
ROM. After the mount is successful, log out of root and log in as before. You can
extract ACL Designer software using a CD-ROM device on any platform. Note that
the numbers in the commands below may be different for your specific installation.
To mount an HP-UX device, use:
mount -r -t cdfs /dev/dsk/2s0 /cdrom
To mount a SunOS device, use:
mount -r -t hsfs /dev/sr0 /cdrom
Solaris mounts CD-ROMs automatically a short time after you insert the CD-ROM.
To mount a AIX device, use:
mount -v’cdrfs’ -r /dev/cd0 /cdrom
To mount a DEC device, use:
mount -r -t cdfs /dev/rz3c /cdrom
IRIX devices mount CD-ROMs automatically a short time after you insert the CD-
ROM.
3. List the mount directory:
On Solaris, type: ls /cdrom/cdrom0
On IRIX, type: ls /CDROM
On all other platforms, type: ls /cdrom
You should see a listing of the os2, unix, and windows directories, and the
autorun.inf file.
4. Go to the ACLDES-PATH directory and set the umask to 022.
cd ACLDES-PATH
umask 022
5. Extract the tar file.
If the mount directory is local:
From the ACLDES-PATH directory, use the appropriate tar command to extract the
ACL Designer files from the CD-ROM. If you are installing multiple platforms to
multiple directories, execute the commands below from the respective platform
directory. If you wish to install both ACL Designer and ACL Designer/Global, you
must create another directory to hold the ACL Designer/Global files and extract the
global tar file into that directory.
To install ACL Designer on Solaris, type:
tar xvf /cdrom/cdrom0/unix/standard/solaris/acldes10.tar
To install ACL Designer/Global on Solaris, type:
tar xvf /cdrom/cdrom0/unix/global/solaris/acldes10.tar
On SunOS, type:
tar xvf /cdrom/unix/standard/sunos/acldes10.tar
6 Chapter 2 Installing ACL Designer

On IRIX, type:
tar xvf /CDROM/unix/standard/irix/acldes10.tar
To install ACL Designer on AIX, type:
tar xvf /cdrom/unix/standard/aix/acldes10.tar
To install ACL Designer/Global on AIX, type:
tar xvf /cdrom/unix/global/aix/acldes10.tar
On HP-UX v.9, type:
tar xvf ’/cdrom/UNIX/STANDARD/HPPA9/ACLDES10.TAR;1’
To install ACL Designer on HP-UX v.10, type:
tar xvf ’/cdrom/UNIX/STANDARD/HPPA10/ACLDES10.TAR;1’
To install ACL Designer/Global on HP-UX v.10, type:
tar xvf ’/cdrom/UNIX/GLOBAL/HPPA10/ACLDES10.TAR;1’
On Digital UNIX, type:
tar xvf ’/cdrom/UNIX/STANDARD/ALPHA/ACLDES10.TAR;1’
If the mount directory is remote:
Type the following to extract ACL Designer from a remote mount directory for
SunOS:
rsh remote-host -n dd if=/cdrom/unix/standard/sunos/
acldes10.tar | tar xvf -
Type the following to extract ACL Designer from a remote mount directory for Solaris:
rsh remote-host -n dd if=/cdrom/cdrom0/unix/standard/
solaris/acldes10.tar | tar xvf -
Type the following to extract ACL Designer/Global from a remote mount directory for
Solaris:
rsh remote-host -n dd if=/cdrom/cdrom0/unix/global/
solaris/acldes10.tar | tar xvf -
Type the following to extract ACL Designer from a remote mount directory for HP-
UX v.9:
rsh remote-host -n dd if=’/cdrom/UNIX/STANDARD/HPPA9/
ACLDES10.TAR;1’ | tar xvf -
Type the following to extract ACL Designer from a remote mount directory for HP-
UX v.10:
rsh remote-host -n dd if=’/cdrom/UNIX/STANDARD/HPPA10/
ACLDES10.TAR;1’ | tar xvf -
Type the following to extract ACL Designer/Global from a remote mount directory for
HP-UX v.10:
rsh remote-host -n dd if=’/cdrom/UNIX/GLOBAL/HPPA10/
ACLDES10.TAR;1’ | tar xvf -
Type the following to extract ACL Designer from a remote mount directory for AIX:
rsh remote-host -n dd if=/cdrom/unix/standard/aix/
acldes10.tar | tar xvf -
Type the following to extract ACL Designer/Global from a remote mount directory for
AIX:
rsh remote-host -n dd if=/cdrom/unix/global/aix/
acldes10.tar | tar xvf -
 Preparing to Install ACL Designer on Windows 7

Type the following to extract ACL Designer from a remote mount directory for Digital
UNIX:
rsh remote-host -n dd if=’/cdrom/UNIX/STANDARD/ALPHA/
ACLDES10.TAR;1’ | tar xvf -
Type the following to extract ACL Designer from a remote mount directory for IRIX:
rsh remote-host -n dd if=/CDROM/unix/standard/irix/
acldes10.tar | tar xvf -
6. Unmount the CD-ROM.
With Solaris, use the eject command:
eject cdrom
Otherwise, type:
umount /cdrom

To add the binary directories to your search path:

1. Make sure that the ACL Designer binary files are included on the search paths of all
users who will be using ACL Designer.
2. Add the appropriate set path command to each user’s .login file so that the
additional path is automatically established each time a user logs in. For example, if
you are using the C-Shell:
set path = (ACLDES-PATH/bin $path)

Preparing to Install ACL Designer on Windows

Depending on your site’s specific needs, you may wish to perform one or more of the procedures
in this chapter. These procedures are provided to smooth the installation process for certain
special situations. The enclosed procedures describe:
• How to move the ACL Designer 1.0 installation files to a file server. Users can then install
the software without having to use the distribution CD-ROM.
• How to install ACL Designer 1.0 to a server and prepare the installed software for client
access.
• How to share the distribution CD-ROM from a Windows 95 or Windows NT workstation.
User's can then install the software from their remote PCs.
• How to create a set of installation diskettes. User's can use the diskettes to install the
software on systems with no CD-ROM drive or network connection (e.g., laptops).

Moving the installation files to a server

If you move the installation files from the distribution CD-ROM to a network file server, your
users will be able to install ACL Designer to their PCs without the distribution CD-ROM. You
will need approximately 10MB of free space on the server to hold the installation files.
8 Chapter 2 Installing ACL Designer

To copy the installation files to a file server:

1. Insert the distribution CD-ROM into a CD-ROM drive.
2. The ACL Designer installation program is AutoPlay-enabled, which means Windows
95 and Windows NT systems will automatically launch the installation process after
you insert the CD-ROM into the drive.
In a few seconds, the ArborText ACL Designer 1.0 Setup dialog appears. Click on the
Cancel button in the dialog box to cancel the installation process.
NOTE: If AutoPlay is disabled, or you are using Windows 3.1 or Windows for
Workgroups 3.11, you will not need to perform this step.

3. Open an Explorer window (File Manager for Windows 3.1/3.11 users) on the CD-
ROM and open the windows folder. This folder should contain several folders (e.g.,
Disk1, Disk2, Disk3, etc.).
4. Map the network drive (where you want to copy the installation files) to a local drive
letter (e.g., F:\).
5. Create a folder on the network drive to hold the installation files (e.g., F:\acldes).
6. Copy all the files in the CD-ROM’s windows directory to the desired folder on the
network server.
7. When the copy is complete, your users will be able to install ACL Designer by running
X:\netpath\Disk1\setup.exe, where X:\netpath is the drive and
directory where you copied the installation files.

Installing ACL Designer on a server for client access

In many network environments, it is advantageous to install the ACL Designer software on a
network server and set up each user as a client who accesses the software on the server. The
ACL Designer Setup program simplifies this installation method as it automates most of the
client/server installation process.

To install ACL Designer on server:

1. Perform any other preparatory procedures listed in this chapter which are necessary for
your specific installation.
2. Install ACL Designer to the desired location on a network server. These directions
appear later in this chapter.
3. Read the section on the acldes.ini file (later in this chapter). If desired, make
changes to the acldes.ini file on the server.
4. Notify your users of the location of the ACL Designer installation on the server. If you
made changes to the acldes.ini file on the server instruct the users to create any
necessary directories on their local machines.

Sharing the distribution CD-ROM

If you share the distribution CD-ROM across your PC network, your users will be able to install
ACL Designer to PCs that don’t have CD-ROM drives.
 Creating installation diskettes 9

To share the distribution CD-ROM on Windows 95/NT:

1. Insert the distribution CD-ROM into the CD-ROM drive.
2. The ACL Designer installation program is AutoPlay-enabled, which means Windows
95 and Windows NT systems will automatically launch the installation process after
you insert the CD-ROM into the drive.
In a few seconds, the ArborText ACL Designer 1.0 Setup dialog appears. Click on the
Cancel button in the dialog box to cancel the installation process.
NOTE: If AutoPlay is disabled, or you are using Windows 3.1 or Windows for
Workgroups 3.11, you will not need to perform this step.

3. Open a Windows Explorer window on the CD-ROM drive. Open the CD-ROM and
highlight the windows folder.
4. Choose the File->Sharing menu option; the Sharing tab of the Properties dialog
appears. Make the following adjustments in this dialog.
Click the Shared As: radio button.
Enter the desired Share Name (e.g., ACL Designer).
Enter the desired Comment (e.g., ACL Designer Installation Files).
Click the OK button.
5. Notify your users of the hostname for the computer with the distribution CD-ROM and
the Share Name you gave the windows directory on the CD-ROM. After your users
map a network drive to the shared location with the installation files, they can install
ACL Designer by running /Disk1/Setup.exe in the shared location.

To share the distribution CD-ROM on Windows 3.1/3.11:

1. Insert the distribution CD-ROM into the CD-ROM drive.
2. Open the File Manager. Open the CD-ROM and highlight the windows folder.
3. Choose the Disk->Share As menu option; the Share As dialog appears. Make the
following adjustments in this dialog.
Enter the desired Share Name (e.g., ACL Designer).
Check the Restore at startup checkbox if you want the CD-ROM shared after this
machine is rebooted.
Click the Read only radio button.
Click the OK button.
4. Notify your users of the hostname for the computer with the distribution CD-ROM and
the Share Name you gave the windows directory on the CD-ROM. After your users
map a network drive to the shared location with the installation files, they can install
ACL Designer by running /Disk1/Setup.exe in the shared location.

Creating installation diskettes

If you need to install ACL Designer on a system that has no CD-ROM drive and no network
connection, you can create installation diskettes for the ACL Designer installation files.
Before you start the following procedure, you should prepare five (5) 1.4 MB diskettes
(formatted).
If possible, scan your formatted diskettes for bad sectors before you copy the ACL Designer
installation files to them. Windows 95 and Windows NT users can open the Properties panel
for the diskette drive, click the Tools tab, and scan the diskette for errors. Make sure your
selected scan options will scan and repair bad sectors.
10 Chapter 2 Installing ACL Designer

To create ACL Designer installation diskettes:

1. Insert the distribution CD-ROM into a CD-ROM drive.
The ACL Designer installation program is AutoPlay-enabled, which means Windows
95 and Windows NT systems will automatically launch the installation process after
you insert the CD-ROM into the drive.
In a few seconds, the ArborText ACL Designer 1.0 Setup dialog appears. Click on the
Cancel button in the dialog box to cancel the installation process.
NOTE: If AutoPlay is disabled, or you are using Windows 3.1 or Windows for
Workgroups 3.11, you will not need to perform this step.

2. Open an Explorer window (File Manager for Windows 3.1/3.11 users) on the CD-
ROM and open the windows folder. This folder should contain several folders (e.g.,
Disk1, Disk2, Disk3, etc.).
3. Open the Disk1 folder inside the CD-ROM’s windows folder.
3. Label a diskette ACL Designer Disk 1 and place the diskette in the floppy drive.
4. Select the entire contents of the Disk1 folder inside the CD-ROM’s windows folder,
and copy the files to the ACL Designer Disk 1 diskette.
5. Repeat the steps above for the remaining Disk# folders in the CD-ROM’s windows
folder.
6. If you will be installing ACL Designer on Windows 3.1/3.11 computers which are not
already running Win32s, repeat the steps above for the Win32s130\Disk1 and
Win32s130\Disk2 folders in the CD-ROM’s windows folder. Label these two
diskettes Win32s Disk 1 and Win32s Disk 2.
7. Notify your users that they can install ACL Designer by starting the Setup.exe
program located on the ACL Designer Disk 1 diskette. If the installation program tells
them to do so, they should install Win32s by starting the Setup.exe program located
on the Win32s Disk 1 diskette.
 Installing ACL Designer on Windows 11

Installing ACL Designer on Windows

Start the ACL Designer setup program. Use the startup instructions that match your specific
situation.

Installing from the distribution CD-ROM:

1. The ACL Designer setup program is AutoPlay-enabled, which means Windows 95 and
Windows NT systems will automatically launch the installation process after you
insert the CD-ROM into the drive.
If AutoPlay is disabled, or you are using Windows 3.1 or Windows for Workgroups
3.11, you can invoke the Run... option and run the
X:\windows\Disk1\Setup.exe program where X is the drive letter for your
CD-ROM drive.
Installing from a network server:
From the PC, map a drive letter to the network server where the ACL Designer
installation files are located. Invoke the Run... option and run the
X:\PATH\Disk1\setup.exe program where X:\PATH is the drive letter and
path to the ACL Designer installation files.
Installing from a remote CD-ROM drive (Windows 95 and NT only):
From the PC, map a drive letter to the location on the remote workstation where your
system administrator has shared the ACL Designer distribution CD-ROM. Invoke the
Run... option and run the X:\Disk1\Setup.exe program where X is the mapped
drive letter for the shared distribution CD-ROM.
Installing from diskettes:
Insert the diskette labeled ACL Designer Disk 1 into the floppy drive. Invoke the
Run... option and run the X:\Setup.exe program where X is the drive letter for the
Disk 1 floppy drive.
2. Follow the instructions in the dialog boxes as they appear. You will be asked to select
which version of ACL Designer to install (standard or global), and to specify an install
directory.
NOTE: Do not use spaces in the names for the ACL Designer installation directory.

3. As the ACL Designer Setup program completes the install, follow the instructions in
the dialog boxes as they appear.

Editing the acldes.ini file on Windows

The acldes.ini file can be used to alter the default behavior of ACL Designer. The
acldes.ini file is located in the ACL Designer installation directory. See each setting below
for a description of what it controls.

Saving Preference Settings for Single-User Installations

Each time you start ACL Designer, it uses a new copy of the default resource/configuration file.
This practice ensures that the resources you use are consistent from session to session. This file
also holds the preference settings for ACL Designer. Since a new copy of the resource/
configuration file is used each time you start ACL Designer, any changes you make to the
preferences are lost.
12 Chapter 2 Installing ACL Designer

If you wish to retain your ACL Designer preference changes from session to session, remove
the leading semicolon from the Disable VR Copy=1 line in the acldes.ini file. This
will prevent ACL Designer from using a new copy of the default resource/configuration file
each time you start the program. To restore the default behavior, replace the semicolon.

Changing the Default Resource/Configuration File Location

When ACL Designer is configured to copy the default resource/configuration file (you still have
a semicolon in front of "Disable VR Copy" above), the file is copied to ACL Designer’s
installation directory (C:\acldes\ by default). If you would like the default resource/
configuration file copied to another location, perform the following steps:
1. Edit your ACL Designer icon/shortcut so the Working Directory (Windows 3.x) or
Start in (Windows 95/NT) field contains the explicit path to where you want the
default resource/configuration file copied.
2. Remove the leading semicolon from the Use Start Dir=1 line in the
acldes.ini file. To restore the default behavior, replace the semicolon.

Saving Preference Settings for Multi-User Installations

If you are serving ACL Designer from a network, and you want your users to be able to save
their own preference settings, perform the steps below:
1. If you haven’t already, remove the leading semicolon from the Disable VR Copy
line in the acldes.ini file.
2. Verify that there is a leading semicolon at the start of the Use Start Dir=1 line in
the acldes.ini file. These settings are mutually exclusive; you cannot use both
simultaneously.
3. Remove the leading semicolon from the Home Dir line in the acldes.ini file.
4. Edit the Home Dir line in the acldes.ini file to reflect the explicit path to the
desired local directory for the default resource/configuration file. For example, a
setting of Home Dir=c:\temp\ would place the default resource/configuration file
on your local C drive in the temp directory.
5. Have all your ACL Designer users create the directory you entered in the Home Dir
line. All users will must use the same directory name.

Installing ACL Designer on OS/2

This section contains the installation instruction for the OS/2 version ACL Designer, which runs
under OS/2 Warp versions 3.0 and 4.0. Its interface and operation are the same as that of the
Windows release with some minor exceptions. These exceptions are discussed in this document.

Directory and Pathnames

When a directory, pathname or filename appears italicized in these instructions, it indicates the
name is not to be taken literally. The actual name or directory on your system may vary
depending on your hardware or software configuration.
 CD-ROM Installation Instructions 13

CD-ROM Installation Instructions

To install ACL Designer, insert the ACL Designer CD-ROM into the appropriate drive on your
computer and copy the OS/2 files to your hard drive.

Copying files from CD-ROM:

1. Open your OS/2 System folder.
2. Open the DRIVES icon or folder.
3. Double-click on the CD-ROM drive.
3. Double-click on the OS2 folder.
4. Place the cursor on the ACLDES folder.
5. Drag and drop the ACLDES folder to your hard drive. (Do this by pressing and holding
the Ctrl key and the second mouse button.) The ACL Designer folder is copied to your
hard drive.

ACL Designer Program Icon

Perform the following procedure to create an ACL Designer icon on your desktop.

Creating ArborText program icons:

1. Open the OS/2 SYSTEM folder.
2. Open the DRIVES folder.
3. In the Drives folder, open the disk drive that contains your ACL Designer installation.
4. Open the ACLDES folder.
5. Select the ACLDES.CMD program file.
6. Click the right mouse button on the ACLDES.CMD program file.
7. Choose Create Another >Default from the menu that appears.
8. Click the Desktop tab and the Create button from the dialog box.
Depending on your system options, the icon will be created at this point or you will be
prompted to create it. If a prompt appears, choose Create the icon.
9. After the ACL Designer icon appears, select it (with the left mouse button). Then click
the right mouse button and choose Settings (Properties in Warp 4 systems). In the
Working Directory text field of the Program panel, type in the disk and directory
location of your ACL Designer working directory.
10. Open the General panel (Icon tab on Warp 4 systems). If the ACL Designer icon is
not visible in the Current icon box, follow these steps to add it:
11. Open the acldes folder and select the VRE.ICO file with the left mouse button.
12. Using the right mouse button, drag the VRE.ICO file and drop it in the Current icon
field of the General dialog box.
13. Close any open dialog boxes.
14 Chapter 2 Installing ACL Designer

Setting environment variables

Before running ACL Designer, you must set the ACLDESHOME and LIBPATH environment
variables to the ACL Designer installation directory.

To set the environment variables:

1. Open the CONFIG.SYS file.
2. Add the line: set ACLDESHOME=C:\ACLDES (where C:\ACLDES is the name
of your ACL Designer installation directory).
3. Add the line: set LIBPATH=C:\ACLDES (where C:\ACLDES is the name of your
ACL Designer installation directory).
4. Reboot your machine to implement the changes to your CONFIG.SYS file.
CHAPTER
3
Overview of ACL Designer

What Is ACL Designer?

ACL Designer is an interactive editing tool primarily used to construct the user interface portion
of ADEPT. With editors and choosers available in ACL Designer, you can create dialogs,
notices, choosers, menus, and other resources for your ADEPT application. You then use
ADEPT Command Language (ACL) code to integrate the custom dialogs into your ADEPT
application.

NOTE: ACL functions and commands are described in the online help that ships with
ADEPT. There are a few new functions which do not appear in the online help; these
are described in Chapter 15, “ACL Designer ACL Functions” on page 155.

For example, you can use the dialog editor to create a dialog for an application. ACL Designer
provides a set of standard dialog items to place into your dialog, or you can create your own
dialog items as needed. Editors and choosers are available to create menus, import or create
images, import fonts, create custom cursors, and more.
ACL Designer itself, with its different editors and choosers, illustrates the variety and
sophistication of resources that can be created. For example, the File Chooser, shown in Figure
1, is used by ACL Designer to select resource files for editing. It is an example of a dialog, with
component resources, that you can create with ACL Designer.

15
16 Chapter 3 Overview of ACL Designer

History Special View Filters Menu Bar

Path Pop-up Menu

hal/

Acme
Ad Copy File/Directory List
<
Appointments
Archive
Arrow Buttons
Bin
bin
> Budget
Client List

Open:
Budget/ Path Entry Text Item

Confirm Button OK Apply Cancel Cancel Button

Figure 1. The File Chooser

Why Use ACL Designer?

There are several advantages to constructing user interfaces with ACL Designer:
• Since resource files are kept separate from your ADEPT Command Language (ACL) code,
modifications to the user interface can be made without having to change the supporting
ACL code.
• The user interface is developed interactively and tested separately from the ACL code,
allowing parallel development. Changes to the interface are seen immediately.
• Different resource files can be kept for different versions of an application. For example,
separate resource files can be created for each language in an internationalized application.
• The tedious task of coding user interfaces is greatly simplified.
• Non-programmers can be involved in designing, developing, and testing user interfaces.
 Resources 17

Resources
A resource is the basic unit of storage provided by ACL Designer. Basic resources can be any
of the following fundamental types, which correspond to standard data types as shown in the
following table:

Table 1. Resource Types

Resource Type Corresponding Data Type

Array [ ] (one-dimensional array of the following types)

Boolean vbool

Character vchar

Character String vchar[ ]

Dictionary vdict or C struct

Fixed Point vfixed

Floating Point float

Integer int

Opaque vbyte[ ]

Symbolic Tag const vname *

Untyped void *

An array of resources is an ordered collection of resources of the same kind. An array of an

application’s error messages, stored as character strings, illustrates one possible use of this
resource.
A dictionary is a named collection of resources, not necessarily of the same kind. Dictionaries
are used to organize an application’s resources, and can contain other dictionaries, creating a
hierarchical organization.
Composite resources, such as dialogs, choosers, and other user interface resources are
constructed from basic resources. Most composite resources are created and modified with
special editors in ACL Designer. Since a composite resource is composed of other resources, it
is a special case of a dictionary organized according to the structure of the composite resource.

NOTE: User interface resources, such as dialogs and buttons, are usually class-based
resources; they are derived by subclassing other resources. However some user
interface resources, such as images, are type-based. These resources are not derived
from other classes, but instead have their own type.

Resource Files
A resource file is a top-level dictionary stored on a disk. The name of a resource file usually
ends with the extension .vr. When you open a resource file for editing, a resource editor
appears depicting the contents of the dictionary. Resources added to the file appear in the editor.
(This editor is called a Dictionary Editor, and is discussed in Chapter 5, “Dictionaries” on page
39.)
18 Chapter 3 Overview of ACL Designer

An application typically stores its entire user interface (dialogs, associated controls, strings, and
error messages) in one or more resource files. The user interface is kept separate from the
ADEPT Command Language (ACL) code, making it straightforward to modify the interface,
translate text strings into another language, or move the application to another platform.
Resources of the same type can be grouped together in resource files, making it easier to locate
specific resources. For example, a resource file could have a “Dialogs” dictionary (or array) to
hold all of its dialogs, another for menus, and another for images.

Starting and Quitting ACL Designer

To start ACL Designer:
1. At the command line prompt, type:
acldes
2. Press Return.
or
1. Double-click ACL Designer icon.
ACL Designer Main Window and a Dictionary Editor for a new resource file are
displayed.

The command line for starting ACL Designer is:

acldes [[filename...] [[-option [specification]]...]]
• filename represents optional resource files to open for editing. One or more file names
can be specified on the command line. (The .vr extension of a resource file’s file name
does not need to be included.) If no file names are specified, an “empty” Dictionary Panel
with the name New0.vr is opened.
• option represents any of the display configurations listed in Table 2. If no options are
specified, ACL Designer opens in the native look-and-feel of the host environment.
• specification represents any of the option specifications listed in Table 2.
 Starting and Quitting ACL Designer 19

Table 2. Startup Arguments

Option Specification Summary

-display machine Specifies the hardware display name for the machine used by ACL Designer. This
option is only valid under the X Window System. The machine name supplied is
used to set the DISPLAY environment variable.
-face face Specifies a typeface for text.
-font font Specifies a font for plain (non-bold) text. You can use any font available on your
system.
-laf style Specifies a look-and-feel style. Look-and-feel styles currently supported are:

cua
motif
windows
windows2d (2d specifies look-and-feel for monochrome monitors)
windows3d (3d specifies look-and-feel for color monitors)

(If 2d or 3d is not specified for openlook or windows, then the appropriate

look-and-feel for your monitor is displayed.)
-monochrome Forces a monochrome display on a color monitor.
-altFileMenus Specifies that ACL Designer use alternate File Menus for opening and saving
resource files and quitting ACL Designer.†

† Normally you can open resource files and quit ACL Designer using the File Menu from any resource
editor. You can also close and save a resource file using the File Menu from any resource editor for a
resource in the file.
When altFileMenus is specified, there is only one place to open and save resource files and to
quit ACL Designer. Using altFileMenus, you can only open resource files and quit ACL
Designer from the File Menu in the Main Window. Also, you can only save resource files from the
File Menu in the Dictionary Editor for a resource file.

For example, type the following to start ACL Designer:

acldes puzzle -laf windows -face helvetica
This tells ACL Designer to:
• Open the resource file puzzle.vr
• Open with the Windows look-and-feel for a monochrome monitor
• Use the Helvetica typeface for text

To quit ACL Designer:

1. Select Quit from the File Menu in the Main Window or Quit from any resource editor.
If you have not made any changes or have already saved your changes, ACL Designer
exits.
If you have made changes but have not saved them, a confirmation dialog appears,
asking if you want to save changes before quitting ACL Designer.
To close this confirmation dialog, click:
• Yes to quit ACL Designer and save your changes
• No to quit ACL Designer without saving your changes
• Cancel to return to ACL Designer
This confirmation dialog may vary, depending on your current look-and-feel.
20 Chapter 3 Overview of ACL Designer

Opening Resource Files

ACL Designer Main Window (UNIX only) opens automatically upon startup. Any number of
new and existing resource files can be opened from the File Menu of the Main Window. The
names of open resource files are displayed beneath a file icon in the Main Window. Figure 2
shows the Main Window with several resource files open for editing.

File View

dialogs.vr images.vr puzzle.vr

Figure 2. ACL Designer Main Window

Opening a resource file opens a Dictionary Editor that displays the contents of the file. If a
Dictionary Editor for a resource file is hidden, you can bring it to the front by double-clicking
on the file name or its icon in the Main Window.

To create a new resource file:

1. Select New from the File Menu in the Main Window.
A Dictionary Panel appears with the name of the new resource file. New resource files
are named sequentially, starting with New0.vr.

To open an existing resource file:

1. Select Open from the File Menu in the Main Window.
The File Chooser opens, displaying a list of resource files and directories from your
working directory. If this directory does not contain the file you want to open, specify
a new directory path.
To specify a new directory path do one of the following:
• Click on the Path Pop-up Menu above the File List.
• Double-click on a directory name in the File List.
• Select a path from the History Menu.
• Click one of the directional buttons to the left of the File List to move up or down
a directory level.
2. Navigate through your file system to locate and select the resource file you want to
open.
Your selection is highlighted in the list of files and directories, and the file name
appears in the text field below the list. A resource file can also be selected by typing
its file name in the Name text field below the scrolling list. The path needs to be
specified if the file is not in the current directory.
3. To open the selected resource file select one of the following confirmation buttons:
• Click OK. The Dictionary Panel for the selected file opens and the File Chooser
 Resource File Icons (UNIX only) 21

closes.
• Double-click on the selected file. The Dictionary Panel for the selected file opens
and the File Chooser closes.
• Click Apply. The Dictionary Panel for the selected file opens and the File Chooser
remains open.
• Click Cancel to close the File Chooser without opening a resource file.
These confirmation buttons may vary, depending on your current look-and-feel.
NOTE: The File Chooser has a Filter Menu automatically enabled to display .vr resource
files and directories only. For detailed information on using the File Chooser, see
Chapter 13, “The File Chooser” on page 143.

Resource File Icons (UNIX only)

Resource files displayed in the Main Window can be viewed by icon or by name. When viewed
by icon, an icon appears above the name of the resource file. When viewed by name, a small
icon appears to the left of the file name. The full pathnames of resource files can also be
displayed in the Main Window.

To change the icon display of resource files:

1. Select by Icon or by Name from the View Menu in the Main Window.
The files are displayed accordingly.

To display the full pathnames of resource files:

1. Select Full Path Name from the View Menu.
The full pathnames are displayed.

To change the position of resource file icons:

1. Drag the icons to new positions or select Clean Up from the View Menu in the Main
Window.
The icons are neatly repositioned in the Main Window, with the most recently opened
resource file at the upper left.

Setting Preferences
The following sections discuss setting preferences for working with ACL Designer, such as
display preferences (including color, font, and window placement) and automatic file saving.
NOTE: By default, ACL Designer resets its preferences during startup. UNIX and OS/2
users can alter their startup script/command file. Windows users should refer to the
section “Editing the acldes.ini file on Windows” on page 11.

Application Preferences Dialog

You can set the display preferences for ACL Designer with the Preferences... option of the File
Menu. This option opens the Application Preferences Dialog, shown in Figure 3.
22 Chapter 3 Overview of ACL Designer

Custom Attributes

Foreground Set Foreground...

Preview Box
Background Set Background... ABCDEF

Font Set Font...

Auto-Save Save Window Positions

Minutes:

OK Apply Reset Cancel

Figure 3. Application Preferences dialog

In the Application Preferences dialog you can open choosers to specify the foreground color,
background color, and the font for ACL Designer. The Preview Box lets you view any new color
or font settings before applying them. Additionally, you can enable an auto-save feature and
specify the interval between automatic saves. There is also an option to save the window
position of various dialogs used in ACL Designer.
NOTE: Preferences specified in the Application Preferences dialog apply only to ACL
Designer. They do not apply to an application using a resource file you created with
ACL Designer. Colors and fonts for an application’s resource file are specified in
resource editors. The next chapter, Chapter 4, “Resource Editor Overview” on page
33, discusses how to specify colors and fonts for an application’s resources.

Color and Font Preferences

To set the foreground color, background color, or font:
1. In the Application Preferences dialog, select the appropriate check box.
When a check box is selected, a corresponding button is enabled to open an appropriate
chooser.
2. Select the button for the preference you want to set.
For the foreground and background color preferences, the Color Chooser opens; for the
font preference, the Font Chooser opens.
3. Make your selection in the appropriate chooser.
The selection is applied to the Preview Box. For details on using the Font Chooser and
the Color Chooser refer to Chapter 11, “The Font Chooser” on page 129, and Chapter
12, “The Color Chooser” on page 131.
4. Apply your selection by clicking either the OK or Apply confirmation buttons.
Any open window in ACL Designer closes and reopens with the new selection. The
settings are the new default settings for ACL Designer. If you clicked OK, the
Application Preferences dialog closes; if you clicked Apply, the dialog remains open.
The OK, Apply, and Cancel confirmation buttons of the Application Preferences
dialog may vary, depending on your current look-and-feel.
 Automatic File Saving Preference 23

To revert to previously saved default settings:

1. In the Application Preferences dialog, click Reset.
ACL Designer returns to the previously saved default settings.

To revert to the system default settings:

1. In the Application Preferences dialog, unselect any check box specifying a font or
color.
2. Click Reset.
ACL Designer returns to the system default settings.

Automatic File Saving Preference

When the automatic file saving feature is enabled, a copy of the current file is automatically
written to disk after a specified interval. (The default interval is five minutes.) The name of the
backup file is the current file name appended with the tilde (~) character. For example, the
backup file for MyResFile.vr is MyResFile.vr~. If the file has not previously been
saved, the backup file is placed in your home directory. Otherwise, it is placed in the directory
containing the original resource file.
In future editing sessions, if you try to open a file that has an auto-save backup with a more
recent save date, a notice appears asking if you want to revert to the auto-save version. If you
revert to the auto-save version, the original file is not replaced until you select Save from the
Edit Menu. This allows you to revert to the original version if necessary. When you save a file
after reverting to the auto-save version, the original version of the file is replaced with the auto-
save version.

To enable the automatic file saving feature:

1. In the Application Preferences dialog, select the Auto-Save check box.
The Minutes field is enabled.
2. Enter the number of minutes between saves.
Specify the number of minutes in whole numbers greater than or equal to 1. The
default value is 5.
3. Close the Application Preferences dialog.
You do not have to click OK or Apply to activate automatic file saving.
The automatic file saving preference is saved from one editing session to the next. If automatic
file saving had previously been selected and you wish to disable it, unselect Auto-Save from
the Application Preferences dialog.

Save Window Positions Preference

ACL Designer contains several different editors, dialogs, and choosers for creating resources
and resource files. The display position of many of these editors and dialogs is saved in ACL
Designer’s own application resource file. If you change the position of these dialogs and then
close and later reopen ACL Designer, the dialogs return to the saved position.
However, the position of some dialogs are bound to certain relative screen locations; their
position is not saved when ACL Designer is closed. For example the Dialog Editor for a dialog
resource is always placed to the right of the dictionary containing the dialog.
24 Chapter 3 Overview of ACL Designer

To override this type of default window placement, select Save Window Positions from the
Application Preferences dialog. When this check box is enabled, ACL Designer saves the
position of all windows, including those formerly bound to other dialogs. The placement of
windows during future editing sessions will be at the saved positions.
The Save Window Positions preference is saved from one editing session to the next. If Save
Window Positions had previously been selected and you wish to disable it, unselect Save
Window Positions from the Application Preferences dialog.

Windows Overview
Resources are created and edited in various editing windows. These windows are resource
editors, panels, choosers, or other dialogs. The following section introduces the primary editing
windows with a brief description of their functions. These windows are covered in detail in later
chapters.

Main Window
The Main Window, shown in Figure 4, is the first window to appear when ACL Designer starts.
It is primarily used to open new or existing resource files, or to access information about ACL
Designer.

File View

New0.vr

Figure 4. Main Window

Dictionary Editor
The Dictionary Editor lists the resources contained in a dictionary. Additional resources for
editing can be created in the Dictionary Panel, and added to the list. Basic resources, such as
boolean, character, and integer, are edited directly in the list; composite resources are edited by
double clicking on the resource’s type field to call up a resource editor for the composite
resource. (Resource editors are discussed in the next section.) Figure 5 shows a Dictionary
Editor displaying the contents of a typical resource file.
 Resource Editors 25

File Edit Resource View Options

Tag Type Contents

PuzzleDialog Dialog

PuzzleImage Image

SolveDialog Dialog

vobjectInheritancDictionary 4 Components

Figure 5. Dictionary Editor

Resource Editors
Resource editors are used to edit resources for your application and can have one or more views,
or panels. These panels are used to create or edit specific properties of a resource, and often
reflect the modifiable attributes inherited from a parent class.
When an editor contains more than one panel, you can toggle between the panels by using menu
commands from the editor, or by using predefined accelerator keys. The accelerator keys are
listed in any Panels menu of an editor.
Figure 6 shows the two panels for a Slider Bar Editor—the first panel is the Dialog Item Panel
and the second is the Slider Panel. In the Dialog Item Panel, you name the slider bar and define
its appearance in your application. In the Slider Panel, you define the behavior of the slider bar.

File Edit Panels File Edit Panels

Tag: Slider Mnemonic: X: 53 Y: 124 Min: 0 Page: 1

Title: Slider W: 196 H: 16 Max: 1 Increment: 1

Enabled Visible Border Value: 0

Click Focusable Focusable Image Mask

Vertical Exclusive Alternate Style
Foreground Set Color... Background Set Color...

Menu Set Menu... Image Set Image...

Font Set Font... Cursor Set Cursor...

ABCDEF

Figure 6. Slider Bar Editor: Dialog Item Panel and Slider Panel

The following sections introduce several commonly used resource editors and panels. These are
discussed in detail in later chapters.
26 Chapter 3 Overview of ACL Designer

Dialog Panel
A dialog consists of several resources of varying types. These component resources are referred
to as dialog items, and are created in the Dialog Editor. The Dialog Editor has three panels: the
Dialog Panel, the Order Items Panel, and the Window Panel. The Dialog Panel is usually
accompanied by the Item Palette.
A dialog is built by dragging icons representing dialog items from the Item Palette to the Dialog
Panel or by selecting dialog items from the Dialog Menu. Items placed in the dialog can be
positioned, sized, and grouped in the Dialog Panel as needed. The dialog can be tested from
within the Dialog Panel at any time.
Figure 7 shows a dialog editor with a Dialog Panel containing two dialog items: a button item
and a radio group item. The Item Palette, discussed in the next section, is also shown. The dialog
being edited is represented by the inner rectangular area containing the dialog items. The Button
and Exclusive Group were placed in the Dialog Editor by dragging their icons from the Item
Palette.

Item Palette
Not really a resource editor, the Item Palette is a customizable tool used to add dialog items to
dialogs. The Item Palette, shown in Figure 7, contains icons representing the most common
dialog items, such as buttons, scrolling lists, and images. Icons representing additional dialog
items can be added or removed from the Item Palette.
When a Dialog Editor is opened for editing, an Item Palette automatically opens with it. Drag
the icons from the Item Palette to the Dialog Panel to add dialog items to a dialog.
 Resource Editors 27

File Edit Panels Dialog Arrange Connection Windows

Button

Exclusive Group
Choice 1
Choice 2
Choice 3

File Edit View

Figure 7. Dialog Panel with Item Palette

28 Chapter 3 Overview of ACL Designer

Dialog Item Panel

A dialog item’s properties can be edited with the Dialog Item Panel of the dialog item’s
resource editor. The Dialog Item Panel contains text fields to edit an item’s Tag and Title as well
as text fields for the item’s size and placement. One set of check boxes defines various dialog
item attributes while another set enables buttons to create or modify additional attributes. A text
viewing area displays sample text formatted with the currently selected text attributes. Figure 8
shows a typical Dialog Item Panel for a scroll bar. Several attribute check boxes are selected to
define properties of the scroll bar.

File Edit Panels

Tag: Scroll Bar Mnemonic: X: 70 Y: 120

Title: Scroll Bar W: 196 H: 16

Enabled Visible Border

Click Focusable Focusable Image Mask

Foreground Set Color... Background Set Color...

Menu Set Menu... Image Set Image...

Font Set Font... Cursor Set Cursor...

ABCDEF

Figure 8. Dialog Item Panel

 Resource Editors 29

Menu Panel
Menus and any corresponding submenus are created in the Menu Panel of the Menu Editor.
Menus can be created for use with any dialog item, but are most commonly created for the Menu
Bar and Option Menu items. The Menu Panel has a command that lets you test menus as you
create them. Figure 9 shows a Menu Panel for editing a “File” menu. Three menu items, Open,
Close, and Save, have been added to the menu, and mnemonic and accelerator keys have been
defined.

File Edit Panels Menu

File
Menu
Open
Title: File
Close
Save Tag: FileMenu
Mnemonic: F

Pinnable Disabled

Item
Title: Open
Tag:

Key:

Mnemonic: O

Disabled Default On

Figure 9. Menu Panel

30 Chapter 3 Overview of ACL Designer

Image Editor
In ACL Designer, images can be associated with dialogs and dialog items. The Image Editor is
the tool used to create, import, export, and edit images. The Cursor Editor, a variation of the
Image Editor, is used to create custom cursors. Figure 10 shows an image placed in the Image
Editor for editing.

File Edit Image View Options

Figure 10. Image Panel

Connection Window
The Connection Window is usually used with the Dialog Panel; it controls the size and relative
placement of dialog items in a dialog. A dialog item’s springs and struts define its size and
placement in a dialog. By manipulating the springs and struts in a Connection Window, shown
in Figure 11, a dialog item’s position and resizing behavior is precisely defined. (Springs and
struts are discussed in detail in Chapter 6, “Dialogs” on page 51.)

Tag: Button
To: (Border)
To Edge: Left Length: 124

Natural Base
Fixed Base

Value: 124

Drag Lock
Stretch

Close

Figure 11. Connection Window

 Resource Editors 31

Choosers
Choosers in ACL Designer are used to make specific selections, such as selecting resource files,
fonts, or colors. They are used in conjunction with other editors in ACL Designer.
The Font Chooser, shown in Figure 12, is used to specify fonts for an application’s resources.
The File Chooser, shown in Figure 13, is used to open and save selected files. The Color
Chooser, shown in Figure 14, is used to specify background and foreground colors for dialogs,
dialog items, and other resources. It is also used to add colors to the Color Palette of an Image
Editor.
Choosers contain a series of confirmation buttons which may vary depending on your current
look-and-feel. The choosers in the following figures contain the OK, Apply, and Cancel buttons
consistent with the Motif look-and-feel.

ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
1234567890

Family: Face: Size:

helvetica iso8859 1 bold 12
lucida iso8859 1 bold oblique
8
lucidabright iso8859 1 medium
10
lucidatypewriter iso8 oblique
11
mincho ksc5601.1987
12

OK Apply Cancel

Figure 12. The Font Chooser

History Special View Filters

hal/

Acme
Ad Copy
<
Appointments
Archive
Bin
bin
> Budget
Client List

Open:
Budget/

OK Apply Cancel

Figure 13. The File Chooser

32 Chapter 3 Overview of ACL Designer

Views Options

Color Method: HLS

Light: 79.61 %

Hue: 180.78 %

Saturation: 79.35 %

Saved Colors:

OK Apply Cancel

Figure 14. The Color Chooser

CHAPTER
4
Resource Editor Overview

Editors and Panels

Resources are created and edited in resource editors composed of one or more editing panels.
Editing panels often reflect the modifiable attributes or behavior a resource inherits from a
parent class.
For example, a menu is created in the Menu Editor which is composed of two panels: a Window
Panel and a Menu Panel. The Window Panel enables you to define the attributes the menu
inherits from the window class, such as the foreground and background colors of the window.
Editors for dialogs and other resources subclassed from windows also have a Window Panel.
The Menu Panel enables you to create and define the properties specific to a menu, such as its
behavior, or menu items and accelerator keys.
Sometimes a resource editor contains a panel that does not reflect class hierarchy, but is added
as a convenience. For example, the Dialog Editor contains an Order Items Panel that displays a
scrolling list of the dialog items contained in a dialog. Rearranging items in this list changes
their relative behavior in the dialog. (This relative behavior of dialog items is not inherited from
a parent class; the Order Items Panel is added as a convenience to edit the dialog.)

Default Attributes
A resource editor opens with default attributes set for the resource. As a convenience, ACL
Designer defines its default attributes so resources can easily be incorporated into your
application. It also sets the default values of the spring and strut positioning devices to define
the spring solution for dialog items. (A dialog’s spring solution is the combination of springs
and struts that specify the relative positions of dialog items in a dialog.)
For example, a menu bar created from the Item Palette automatically snaps to the top of a dialog
and has the File and Edit menus predefined. Creating dialog items with the Item Palette is
discussed in Chapter 6, “Dialogs” on page 51.

33
34 Chapter 4 Resource Editor Overview

Resource Editor Menus

Each resource editor has a menu bar containing several menus used to edit a resource. All
resource editors contain a File Menu and an Edit Menu. When more than one panel is present,
resource editors also contain a Panels Menu. The following sections outline the general
behavior of these three menus. Detailed information on these and other resource editor menus
are provided in chapters on specific resources.

Using the File Menu

Use the File Menu, shown in Figure 15, to open and close resource files, save resource files,
save the layout of an editor, revert to a previous version of an editor, and to quit ACL Designer.
There is an alternate version of the File Menu that simplifies the available options in the menu.
See the note on page 36 for details on alternate File Menus.

Open File... Ctrl+O

Close Editor Ctrl+W
Save File Ctrl+S
Save File As... Ctrl+Shift+S

Save Template
Revert Editor Ctrl+R

Quit vre Ctrl+Q

Figure 15. File Menu

Open File...
The Open File... command lets you open a resource file from any editor. Selecting this command
opens the File Chooser. Select the resource file you want to open with the File Chooser. For
more information about using the File Chooser, see Chapter 13, “The File Chooser” on page
143.

Close Editor
The Close Editor command closes a resource editor and any windows associated with it. With
the exception of the Dictionary Editor, closing a resource editor does not discard changes made
in the editor. Changes made in an editor are still active during the editing session, and can be
saved to disk later with the Save command. The Dictionary Editor exception pertains to closing
a Dictionary Editor for a resource file. If the file is not saved, all changes are lost. (ACL
Designer always prompts you to save changes before closing a Dictionary Editor for a resource
file.)

Save File
The Save File command saves a newly created resource file, or saves any changes to a
previously saved resource file.
 Using the File Menu 35

To save a newly created resource file:

1. Select Save File from the File Menu.
The File Chooser appears.
2. Navigate through your file system in the File Chooser to locate the directory in which
to save the resource file.
3. Enter a name for the resource file in the text field below the scrolling file list. Resource
files must end with the .vr extension. If you do not specify this extension, ACL
Designer appends it to the file name.
4. Click OK.
The File Chooser disappears and the name of the resource file appears in the title bar
of the Dictionary Panel. The file name also appears in the Main Window.
After a resource file has been initially saved, selecting Save automatically saves changes to a
file under its existing path and name without invoking the File Chooser. After a file has been
saved, the save command is disabled until changes are made to the file during an editing session.
For more information about using the File Chooser, see Chapter 13, “The File Chooser” on page
143.

Save File As...

The Save File As... command saves a resource file under a different name. The new file name
and/or path is specified in the File Chooser.

Save Template
The Save Template command saves the position and preferences of a resource editor. When
ACL Designer is opened in future editing sessions, the resource editor is positioned and
displayed according to the settings saved with this command.

NOTE: This command is currently enabled for the Dictionary Editor and Image Editor.
Future releases will enable this command for additional resource editors.

Revert Editor
The Revert Editor command discards any unsaved changes made to a resource editor, and
returns you to a previous version. If you saved any changes to the editor while it was open, you
are returned to the last saved version. If you haven’t saved any changes, you are returned to the
contents of the editor when it was last opened.

Quit
The Quit command is used to exit ACL Designer and close all windows. If changes have been
made, but not saved, a confirmation dialog is displayed.
36 Chapter 4 Resource Editor Overview

The resource file

</visix/user/hal/puzzle.vr> has been
modified and changes have not been
saved. Do you wish to save your
changes?

Yes No Cancel

Figure 16. Confirmation Dialog

To close this confirmation dialog, click:

• Yes to save your changes and quit
• No to abandon changes and quit
• Cancel to return to the resource editor
The confirmation buttons in this dialog may vary, depending on your current look-and-feel.

NOTE: Normally you can use the File Menu from any resource editor to open resource files
and quit ACL Designer. You can also close and save a resource file using the File
Menu from any resource editor for a resource in the file.

If you want to have only one place to open and save resource files and to quit ACL
Designer, specify altFileMenus when starting ACL Designer. When
altFileMenus is specified, you can only open resource files and quit ACL
Designer from the File Menu in the Main Window. Also, you can only save resource
files from the File Menu in the Dictionary Editor for a resource file. For details on
specifying altFileMenus (and other options) see “Starting and Quitting ACL
Designer” on page 18.

Using the Edit Menu

Use the Edit Menu to perform common editing operations on selected resources in a resource
editor. Each resource editor contains the editing commands shown in Figure 17. The
implementation of these options may vary according to the resource editor or panel. Some
editors, such as the Dialog Editor and Image Editor, have additional options not listed here.
Details are discussed in later sections on specific resources.
The Cut, Copy, and Paste commands all use an Editing Clipboard within ACL Designer. The
Editing Clipboard only saves the last item written to it.
 Using the Edit Menu 37

Undo Ctrl+Z
Redo Ctrl+Y

Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Clear Ctrl+B
Duplicate Ctrl+D

Figure 17. Edit Menu

Undo
The Undo command reverses the most recent editing action. Use it repeatedly to undo a series
of actions. The Undo command identifies the most recent action that can be undone. For
example, after dragging an item in a Dialog Editor, the command reads “Undo Drag.”

Redo
The Redo command restores the most recent editing action reversed by the Undo command. Use
it repeatedly to redo a series of actions.

Cut
The Cut command removes one or more selected items from the resource editor and places it on
the Editing Clipboard.

Copy
The copy command makes a copy of one or more selected items in the resource editor and places
it on the Editing Clipboard. Items copied are not removed from the resource editor.

Paste
The Paste command places the contents of the Editing Clipboard into the active resource editor.
A copy of the contents remain on the Editing Clipboard.

Clear
The Clear command removes one or more selected items from the resource editor. The items are
not placed on the Editing Clipboard.

Duplicate
The Duplicate command makes a copy of one or more selected items in the resource editor, and
places it in the editor. The items are not placed on the Editing Clipboard.
38 Chapter 4 Resource Editor Overview

Using the Panels Menu

Use the Panels Menu to navigate between editing panels in a resource editor. The number of
panels in an editor varies. Editors that have only one panel, such as the Button Editor, do not
have a Panels Menu. Figure 18 shows a Panels Menu for a Dialog Editor.

Window
Order Items
Dialog

First Panel Ctrl+Shift+F

Next Panel Ctrl+Shift+N
Previous Panel Ctrl+Shift+P
Last Panel Ctrl+Shift+L

Figure 18. Panels Menu

To navigate between panels in a resource editor:

1. Select Panels from the resource editor menu.
A submenu divided into two sections appears.
2. From the top section, select the panel you want to view.
or
From the bottom section, select the panel based on the default order in ACL Designer
(First, Next, Previous, or Last). The default order is displayed in the top section of the
Panels Menu.
NOTE: Use accelerator keys defined in the Panels Menu to quickly change panels.
CHAPTER
5
Dictionaries

Overview of the Dictionary Editor

A dictionary is a basic resource containing other resources; it is typically used to hold the
contents of a resource file. A hierarchical structure, a dictionary can contain other dictionaries.
Composite resources are composed of other resources and are a type of dictionary.
The Dictionary Editor is used to view and edit the contents of dictionaries. Since resource files
are dictionaries, the Dictionary Editor is where to begin when creating or editing resources for
your application. Figure 19 shows a Dictionary Editor with the contents of a typical resource
file. Two dialog resources, an image resource, and an inheritance dictionary are displayed as list
items in a scrolling resource list. Each resource is displayed in collapsed view. The first dialog
is selected for editing.

File Edit Resource View Options

Tag Type Contents

PuzzleDialog Dialog

PuzzleImage Image

SolveDialog Dialog

vobjectInheritancDictionary 13 Components

Figure 19. Dictionary Editor

If a resource is displayed in expanded view, its component resources are visible.

39
40 Chapter 5 Dictionaries

Figure 20 shows the same resource file with the inheritance dictionary displayed in expanded
view. (Inheritance dictionaries are explained later in this chapter.)

File Edit Resource View Options

Tag Type Contents

PuzzleDialog Dialog

PuzzleImage Image

SolveDialog Dialog

vobjectInheritancDictionary 13 Components

vbutton Tag vdialogItem

vcontainer Tag vdialogItem

vcontainerExcl Tag vcontainerGroup

vcontainerGrouTag vcontainer

vcontrol Tag vdialogItem

Figure 20. Dictionary Editor with inheritance dictionary in expanded view

From the Dictionary Editor, you can do the following:

• Create resources
• View the entire contents of a resource file
• Edit resources directly from the resource list
• Open resource editors for resources in the resource list
• Copy or move resources
• Create subclassed resources
• Save preferences for ACL Designer

Creating Resources
Basic resources, such as strings or integers, can be created directly in dictionaries, but often are
created and stored in arrays. Composite resources, such as dialogs or images, must be created
and stored in dictionaries or dictionary arrays. (A dictionary array is a special case of array and
is covered in the next section.)

To create a resource:
1. Select Resource from the menu bar in the Dictionary Editor.
The Resource Menu appears.
2. Select New from the Resource Menu.
The New Menu appears. Figure 21 shows the New Menu.
3. Select a resource from the New Menu.
The resource you select is added to the resource list in the Dictionary Editor.
 Creating Resources 41

Boolean

Character
Command Space

Confirm
Container

Cursor
Dialog

Dictionary

Fixed

Float

Image

Integer

Keystroke Item
Menu

Notice

Opaque

Palette
String

Tag

Window

Figure 21. New Menu

To create an array of basic resources:

1. Select Resource from the menu bar in the Dictionary Editor.
The Resource Menu appears.
2. Select New Array from the Resource Menu.
The New Array Menu appears. Figure 22 shows the New Array Menu.
3. Select a basic resource from the New Array Menu.
An array of the resource you selected is added to the resource list. The array initially
contains zero elements.

Boolean
Character
Dictionary
Fixed
Float
Integer
Opaque
String
Tag

Figure 22. New Array Menu

42 Chapter 5 Dictionaries

To add elements to an array resource:

1. Select an array resource from the resource list of a Dictionary Editor.
Arrays must be in expanded view before elements can be added. If the directional
arrow (to the left of the array icon) is pointing down, the array is in expanded view.
2. If the array is not in expanded view, select the directional arrow to place it in expanded
view.
3. Select Resource from the menu bar in the Dictionary Editor.
The Resource Menu appears.
4. Select New Array Element from the Resource Menu.
A new element is added to the array with its offset indicated in the tag field. The
contents field is highlighted for editing. The contents field varies depending on the
type of array being created. Select and edit this field to define the value for the array
element.

Dictionary Arrays
A dictionary array is a structure whose elements can only be dictionaries. Since class-based
composite resources are a type of dictionary, a dictionary array can contain various composite
resources as elements. For example, a dictionary array can contain a dialog as one element, a
button as another, and a dictionary as a third. As with any array, an element of a dictionary array
is referenced by its offset.

To create a dictionary array:

1. Select Resource from the menu bar in the Dictionary Editor.
The Resource Menu appears.
2. Select New Array from the Resource Menu.
The New Array Menu appears. Figure 22 shows the New Array Menu.
3. Select Dictionary from the New Array Menu.
A dictionary array is added to the resource list.

To add elements to a dictionary array:

1. Select a dictionary array in the resource list of a Dictionary Editor.
Dictionary arrays are represented with the array icon. Arrays must be in expanded view
before elements can be added. If the directional arrow (to the left of the array icon) is
pointing down, the array is in expanded view.
2. If the dictionary array is not in expanded view, select the directional arrow to place it
in expanded view.
3. Select Resource from the menu bar in the Dictionary Editor.
The Resource Menu appears.
4. Select New from the Resource Menu.
The New Menu appears. Figure 21 shows the New Menu.
5. Select a resource from the New Menu.
The resource is added to the array with its offset indicated in the tag field. Only
dictionaries and class-based composite resources can be added to the array.
 Viewing Dictionaries 43

Viewing Dictionaries
User interface resources in ADEPT are composite resources. The component resources of a
composite resource can be viewed by selecting Expand from the View Menu. An expanded
view can be collapsed by selecting Collapse from the View Menu. Figure 23 shows the View
Menu.

Expand Ctrl+Shift+E
Collapse Ctrl+Shift+C

Select Parent
Select Next Entry
Select Previous Entry

Resource Type
Resource Contents

Figure 23. View Menu

The components of a composite resource can be edited directly from the expanded view in the
Dictionary Editor. However, it is best to use the expanded view for viewing resources only. To
edit a component resource, you should open the resource editor for the parent at the highest level
in a dictionary or array. For more information on editing resources, see Editing Resources on
page 44.
Figure 24 shows an expanded view of a dialog resource. Composite resources in this expanded
view can also be expanded to view their contents.

File Edit Resource View Options

Tag Type Contents

PuzzleDialog Dialog

Class Tag vdialog

Flags Integer 8
Directional Arrow ItemList Dictionary 2 Components

Metrics Array of Integer 8 Elements

Style Integer 63

vdialogFlags Integer 0

PuzzleImage Image

SolveDialog Dialog

Figure 24. Expanded view of a dialog resource in the Dictionary Editor

44 Chapter 5 Dictionaries

To expand or collapse a view of a composite resource:

1. Select the composite resource to expand or collapse.
2. Select View from the menu bar in the Dictionary Editor.
If the resource is in collapsed view, the Expand command is enabled. If the resource is
in expanded view, the Collapse command is enabled.
3. Select Expand or Collapse.
The view of the resource changes, depending on your selection.
NOTE: The resource editor for a composite resource must be closed before you can view it
in expanded view.

The following commands are available from the View Menu to select component resources of
a composite resource in expanded view.

Select Parent
The Select Parent command automatically selects the parent resource of the currently selected
resource in expanded view.

Select Next Entry

The Select Next Entry command is only available in expanded view. It selects the next resource
at the same level as the currently selected resource.

Select Previous Entry

The Select Previous Entry command is only available in expanded view. It selects the previous
resource at the same level as the currently selected resource.

NOTE: You can use the up and down arrow keys from the keyboard to change the selection
in any view of a Dictionary Editor.

Editing Resources
Resources are edited directly in the Dictionary Editor or in resource editors provided by ACL
Designer for that resource. Basic resources, such as integers and strings, can only be edited in
the Dictionary Editor. Composite resources, such as dialogs and images, are usually edited from
resource editors.
The tag name of a resource is the name an application uses to load the resource from a resource
file. Edit the tag name of a resource in the Dictionary Editor. The contents field of basic
resources is also edited in the resource file list. Arrays and dictionaries must be in expanded
view to edit their contents. The contents of composite resources are usually edited by opening a
resource editor from the Dictionary Editor. (Using resource editors is covered in later chapters.)
CAUTION: Composite resources can be expanded in a Dictionary Editor and any
component resource that is a basic resource can be edited. However, without a
technical understanding of ADEPT, it would be difficult to edit composite
resources from the Dictionary Editor. Instead, use the resource editors provided
for composite resources. Resource editors provide visual interactive editing of
resources—the effect of editing changes are viewed as you make them.
 Editing Resources 45

To edit a resource’s tag name:

1. Click on the Tag field of a resource in the resource file list of the Dictionary Editor.
A text field becomes enabled.
2. Edit the text field for the resource’s tag name.
(To directly replace text in a text editing field, highlight it with the mouse before
typing.)
3. Press Return or click another resource in the resource file list.
The resource now has the edited tag name.

To edit the contents of a basic resource:

1. Click on the Contents field of a basic resource in the resource file list of the Dictionary
Editor.
An editable field becomes enabled. This field varies, depending on the type of resource
selected.
2. Edit the field for the resource.
(To directly replace text in a text editing field, highlight it with the mouse before
typing.)
3. Press Return or click on another resource in the resource file list.
The edited resource reflects your changes.

To open a resource editor for a composite resource using the Resource

Menu:
1. Select Resource from the menu bar in the Dictionary Editor.
The Resource Menu appears.
2. Select Edit... from the Resource Menu.
A resource editor for the composite resource opens.

To open a resource editor for a composite resource using the resource list:
1. Double-click on the type or contents field of a composite resource (or on its icon) in
the resource list.
A resource editor for the composite resource opens.
46 Chapter 5 Dictionaries

Finding Resources
Use the Find Dialog, shown in Figure 25, to locate the position of resources in a dictionary.

Find By Resource Type

Cursor
Dialog
Dialog Item

Find by Tag Name

Save

Matches:
/ PuzzleDialog
/SolveDialog

Cancel Find

Figure 25. Find Dialog

The Find Dialog can locate a resource when you specify its type or tag name. Specify the type
and tag names individually or together.

To find a resource:
1. Select Resource/Find Resource... from the menu bar in the Dictionary Editor.
The Find Dialog opens.
2. Select:
Find By Resource Type
The scrolling list of resources is enabled.
Find By Tag Name
The Tag Name text field is enabled.
Find By Resource Type and Find By Tag Name
Both fields are enabled.
3. Select a resource type from the Resource Type list and/or enter a tag name in the Tag
Name text field.
4. Click Find.
Any resources that match your specifications are displayed in the list of matched
resources.
 Copying and Moving Resources 47

Copying and Moving Resources

Resources in the Dictionary Editor can be copied or moved within a dictionary, to other resource
files, or to the Dialog Panel of a Dialog Editor. These operations are available for all resources
within a dictionary with the following exceptions:
• Only copy operations are allowed from one resource file to another, or from a Dictionary
Editor to a Dialog Editor.
• Only dialog items can be copied to a Dialog Panel.
Copy or move operations can be performed as a drag and drop operation, or by using editing
commands from the Edit Menu. Dragging to the same resource file is a move operation; press
the Control key while dragging to force a copy operation. During a drag operation a “safe” icon
appears over legal drop locations. An “unsafe” icon appears over illegal drop locations.
For an introduction to the Edit Menu, see Chapter 4, “Resource Editor Overview” on page 33.
For details on the Dialog Editor, see Chapter 6, “Dialogs” on page 51.

Adding Resources to the New Menu

The Resource/New Menu in the Dictionary Editor provides a list of resources commonly used
when creating resource files (see “Creating Resources” on page 40). You may want to modify
the resources available from the New Menu according to your specific needs. Use the Add
Resource Types... dialog, shown in Figure 26, to add or subtract resources from the New Menu.
(The New Menu is shown in Figure 21 on page 41.)

File Edit Resource

Boolean
Box Item
Button
Character
Check Box
Color Palette
Color Specification
Combo

Class Name: vreBooleanClass

Display Name: Boolean

Subclass

Figure 26. Add Resource Types... dialog

The Add Resource Types... dialog lists all the resources available to add to your application
from ACL Designer. A check next to a resource indicates that the resource is listed in the New
Menu. If a resource in the Add Resource Types... dialog is selected (with a mouse click), its class
name and display name appear in the text fields below the resource list. The class name is the
class of the selected resource.The display name is the name used by ACL Designer when
referencing the resource.
48 Chapter 5 Dictionaries

The display name is not used by your application. Edit this field to create your own display
name for a resource. The display name you select is saved by ACL Designer and appears in
future editing sessions.
You can also use the Class Name text field to search for a resource by its class name. For
example, if you want to find the resource for the class vtextitem, type vtextitem in the
Class Name text field and press Enter. The scrolling list then displays the text item resource.
To add a resource to the New Menu, select the field to the left of the resource in the Add
Resource Types... dialog. A check appears, indicating the resource has been added to the New
Menu. To verify that it has been added, select New from the Resource Menu. Selecting the
check removes the resource from the New Menu. You can also add (or remove) resources to the
New Menu with the Add to New Menu option in the Resource Menu.

NOTE: A resource can be added to a dictionary or a Dialog Panel directly from the Add
Resource Types... dialog without adding it to the New Menu. Select a resource from
the resource list and drag it from the chooser to the dictionary or the Dialog Panel.
See Chapter 6, “Dialogs” on page 51 for details on the Dialog Panel.

Creating Subclassed Resources

The Add Resources Types... dialog can also be used to view the class hierarchy of a resource,
and to create subclassed resources for subclasses defined in your application code.

Note: The Add Resources Types... option is not useful for ADEPT Command Language
(ACL) developers.

Generating Files
ACL Designer can generate .c and .h files to help incorporate your resource file into your
application source code. Once created, these files should never be edited, since any new source
code generated by ACL Designer will overwrite any editing changes.

Note: The files created by the Generate Files... option are not used by ADEPT.

Customizing the View of the Dictionary Editor

You can change the display of a Dictionary Editor by moving or resizing the Tag, Type, and
Contents ruler items. These ruler items are headers placed on a ruler above the scrolling
resource list in the Dictionary Editor. The position of the corresponding fields for the headers is
determined by the placement of the headers. The Type and Contents ruler items can also be
removed to limit the amount of information presented in the editor.
Additionally, you can set the font to use for the scrolling resource list in a Dictionary Editor.
This selection only affects the Dictionary Editor. Use the Preferences... option from the Main
Window to select a font for all editors in ACL Designer. For more on the Preferences... option,
see “Setting Preferences” on page 21.
Use the Save Template command in the File Menu to save changes made to the view of a
Dictionary Editor. Changes saved with the Save Template command affect future editing
sessions. If you do not use the Save Template command, the changes only affect the current
editor.
 The vobjectInheritance Dictionary 49

To move a ruler item:

1. Drag the ruler item to any position on the ruler.
The corresponding fields of the resources in the resource list move with the ruler item.

To resize a ruler item:

1. Drag either the left or right edge of a ruler item.
The size of the ruler item and its corresponding fields change.

To remove the Type or Contents ruler item:

1. Drag the ruler item off the ruler.
The ruler item is removed from the ruler. You may have to reposition the remaining
ruler items on the ruler.
NOTE: You can also remove ruler items from the Dictionary Editor by unselecting
the Resource Type or Resource Contents options in the View Menu.

To set the font for a Dictionary Editor:

1. Select Set List Font... from the Options Menu.
A Font Chooser opens.
2. From the Font Chooser, select a font.
The font you select is applied to the editor.
NOTE: You can revert to the default font by selecting Default List Font from the
Options Menu.

The vobjectInheritance Dictionary

When a resource file is saved, ACL Designer creates a dictionary with the tag name
vobjectInheritance. Information about the class hierarchy of resources in your file is
stored in this dictionary. ADEPT uses this information when it loads resources into memory
from your resource file.

CAUTION: There is normally no need to edit the inheritance dictionary. If the contents of
this dictionary changes, your application may not be able to find the resources
it needs from your resource file.
50 Chapter 5 Dictionaries
CHAPTER
6
Dialogs

The Dialog Editor, together with the Item Palette and other tools, is used to create dialogs for
your application. Figure 27 shows the Dialog Panel of a Dialog Editor. Figure 28 shows the Item
Palette.

File Edit Panels Dialog Arrange Connection Windows

Container

Label Item

Check Box Dialog Items

Bounds of Dialog
Being Edited
Button

Figure 27. Dialog Panel

51
52 Chapter 6 Dialogs

File Edit View

Figure 28. Item Palette

The Dialog Panel contains a rectangular area representing the dialog currently being edited. In
Figure 27, a container item and a button item have been placed in the dialog. The container
contains a label item and a check box. (A container is a dialog item used to hold other dialog
items. Dialog items placed inside a container function as a unit.)
The Item Palette contains icons representing dialog items. A dialog item is placed in a dialog by
dragging the item’s icon from the Item Palette to the Dialog Editor. (Dialog items can also be
placed in a dialog with menu commands.)
A dialog item’s position in a dialog is specified by a series of positioning devices called springs
and struts. A dialog’s spring solution is the combination of springs and struts that specify the
relative positions of dialog items in a dialog. The spring solution for a dialog can be defined
directly in the Dialog Panel, from the Dialog Panel’s Arrange and Connection menus, or with
the Connection Window. (The Connection Window is an editing tool opened from the Dialog
Panel.)
Using the Try Dialog command from the Dialog Menu, you can interactively test dialogs as you
create them. The Try Dialogs command opens a copy of the dialog being edited. Use this copy
to “try out” the current version of the dialog.

Opening a Dialog Editor

Dialogs must first be created in a Dictionary Editor before you can open a Dialog Editor. (For
information on creating resources in a dictionary, see Chapter 5, “Dictionaries” on page 39.)

To open a Dialog Editor:

1. Select the dialog resource you want to edit from the resource item list of the Dictionary
Editor.
2. Select Edit... from the Resource Menu of the Dictionary Editor or double-click on the
dialog in the resource item list.
A Dialog Editor for the selected dialog opens, accompanied by an Item Palette.

Dialog Editor Panels

The three panels of a Dialog Editor are:
• Window
 Setting Window Attributes for a Dialog 53

• Order Items
• Dialog
Use the Window Panel to define the appearance of a dialog and set attributes defining its
behavior. The Order Items Panel lists the dialog items contained in a dialog, and provides
options to define their behavior within the dialog. Use the Dialog Panel to place dialog items
into a dialog and open resource editors for them. The Try Dialog menu option in the Dialog
Panel allows you to test (“try out”) a dialog.
When a Dialog Editor opens, the Dialog Panel is displayed. Use the Panels Menu to change
panels in the Dialog Editor. (For information on changing panels in a resource editor, see
Chapter 4, “Resource Editor Overview” on page 33.)

Setting Window Attributes for a Dialog

Dialogs are subclassed from windows and inherit attributes and properties from the window
class. Use the Window Panel, shown in Figure 29, to set the window properties of a dialog. From
the Window Panel you also define tag and title names for the dialog, and specify its size and
placement.

File Edit Panels

Tag: X: 100 Y: 100

Title: W: 300 H: 200

Custom

Foreground Set Color... Cursor Set Cursor...

Background Set Color... Icon Set Icon...

Font Set Font... Menu Set Menu...

Attributes
Border Maximizable Iconifiable Movable

Modal Pinnable Resizable

ABCDEF

Figure 29. Window Panel

The tag name of a dialog is the name your application uses to access the dialog after the resource
file is loaded into memory. Tag names must be unique throughout your application, and are used
by ADEPT Command Language (ACL) functions to reference specific dialogs/dialog items.
The title is the name displayed in the title bar of a dialog. (The title bar includes the text field in
the top border of a window.)
54 Chapter 6 Dialogs

To specify the tag and title names for a dialog:

1. In the Window Panel, select the text box for the tag or title you want to edit.
The text box becomes active for editing.
2. Edit the tag or title for your dialog.
3. Press Enter or change the focus by clicking on another item in the editor.
The tag or title name of the dialog has been changed.
The position of a dialog is determined by its X and Y coordinates. These coordinates specify the
offset (in pixels) from the lower left corner of your dialog to the lower left corner of the display.
The size of a dialog is specified by W and H coordinates which set the width and height (in
pixels) of the dialog’s window. See Figure 30 for a diagram of these coordinates.

Screen Bounds

H = 150
Offset (in pixels) - X
50 Dialog

W = 200
(50,100)
100

(0,0)
Origin
Offset (in pixels) - Y

Figure 30. Window coordinates for a dialog

To specify the position and size of a dialog:

1. In the Windows Panel, edit the X and Y values for position, and the W and H values
for size.
The values entered are the new position and size specifications.
Windows have a series of attributes that define their appearance and behavior in an application.
In the Window Panel of a Dialog Editor, you can specify these attributes for a dialog with a
series of check boxes. These attributes are listed in Table 3; their behavior depends on the
current look-and-feel.

Table 3. Window Attributes

Attribute If enabled
Border The dialog is outlined with a border.
Movable The dialog can be moved on the display by dragging the dialog with a mouse.
Resizable The dialog can be resized by the user.
Modal The dialog is the only active window in the application. A user must respond or perform some
action in the dialog to change the focus.
Pinnable The dialog can be pinned to the display, depending on the look-and-feel.
Iconifiable The dialog can be minimized to an icon on a display.
 The Item Palette 55

Table 3. Window Attributes

Attribute If enabled
Maximizable The dialog can be enlarged to the size of the display.

A series of choosers and editors are available by enabling the check boxes in the Custom group
of the Window Panel. Selecting a check box for Foreground or Background activates a button
to open the Color Chooser. Use the Color Chooser to define the colors of your dialog. The check
box for Font activates a button to open the Font Chooser. Use the Font Chooser to specify the
font used in your dialog. Selecting the check boxes for Cursor and Icon activates buttons to open
the Image Editor. Use the Image Editor to specify a cursor or icon for your dialog.

The Item Palette

When a Dialog Editor opens, an Item Palette also opens. The Item Palette initially contains icons
for 14 commonly used dialog items. You can reconfigure the Item Palette according to your
needs. (See “Customizing the Item Palette” on page 63.)
The dialog items represented in the Item Palette have predefined attributes, sizing, and
placement information. These default attributes have been set by ACL Designer so the items can
be readily incorporated into your dialog.
To select a dialog item, click on its icon in the Item Palette. The selected item is highlighted,
and its name appears below the palette. Additionally, the selected item’s position in the class
hierarchy is displayed next to its name. (If the full class derivation is not shown, enlarge the Item
Palette Window.) Place the dialog item into a dialog by dragging its icon from the Item Palette
to the Dialog Panel.
To place a dialog item in a dialog, drag the selected icon to the Dialog Panel and drop it in the
dialog. Items are drawn in their actual form as you drag and place them in the dialog. After
placing the item in the dialog, default springs and struts, and other default sizing and placement
properties are applied to the item. Each dialog item on the Item Palette can be edited to change
its default properties. (See “Customizing the Item Palette” on page 63.)

Changing the View of the Item Palette

Use the View Menu of the Item Palette to select display options for the Item Palette. Large and
small icons are available for display. When the Auto Arrange option is enabled, the icons are
automatically rearranged when the Item Palette is resized.

Reopening the Item Palette

The Item Palette opens when you open a Dialog Editor. If, during an editing session, you have
closed the Item Palette, you can reopen it by selecting Item Palette from the Windows Menu in
the Dialog Panel. If the Item Palette is open but hidden, this command brings the Item Palette
to the front.

Creating a Dialog
Dialogs are created in the Dialog Panel of the Dialog Editor. You can place a dialog item in a
dialog by selecting an item from the Dialog/New Item Menu, dragging an icon from the Item
Palette to the dialog, or by dragging an item from the Add Resources Type... dialog opened from
a Dictionary Editor. Dialog items placed in a dialog can be selected for positioning and further
editing. Resource editors can be opened to edit dialog items placed in a dialog.
56 Chapter 6 Dialogs

To place a dialog item in a dialog using the New Item Menu:

1. Select Dialog from the menu bar in the Dialog Panel.
The Dialog Menu appears.
2. Select New Item from the Dialog Menu.
The New Item Menu, shown in Figure 31, appears.
3. Select a dialog item from the New Item Menu.
The dialog item is added to the dialog and is selected for further editing.

Box Item

Button
Check Box

Combo

Container

Control
Dialog Item
Domain Item

Domain View
Exclusive Group

Grouped Container
Icon View
Keystroke Item
Label Item
Line Item

List Item
List View
Menu Bar

Option Menu
Palette
Popdown Combo

Ruler
Scroll Bar
Slider
Spinner

Text Item
Text Ruler
Text Spinner
Text View

Figure 31. New Item Menu (actual ACL Designer menu contains additional selections)

To place a dialog item in a dialog using the Item Palette:

1. Drag an icon (representing the dialog item you want to create) from the Item Palette to
the Dialog Panel.
The dialog item is added to the dialog and is selected for further editing.

To place a dialog item in a dialog using the Add Resource Types... dialog:
1. Drag a dialog item from the resource list in the Add Resource Types... dialog (opened
from a Dictionary Editor).
The dialog item is added to the dialog and is selected for further editing. For more
information on the Add Resource Types... dialog, see “Adding Resources to the New
Menu” on page 47.
 Creating a Dialog 57

To replace a dialog item in a dialog with another dialog item:

1. Select a dialog item in the Dialog Panel.
2. Select Replace Item from the Dialog Menu.
The Replace Item Menu appears.
3. Select a dialog item from the Replace Item Menu.
The selected dialog item in the Dialog Panel is replaced by the dialog item selected
from the Replace Item Menu. The title of the new dialog item does not change.
NOTE: A newly created dialog item is placed in the dialog with predefined sizing
and placement definitions. An item created from the New Item Menu, the
Replace Item Menu, or from the Add Resource Types... dialog does not
necessarily have the same initial definitions as the same item created from
the Item Palette. The initial definitions from the New Item Menu, the
Replace Item Menu, and the Add Resource Types... dialog are usually more
generic.

To select items in a dialog for editing:

1. Perform one of the following actions:
To select an item, click on it once.
To select several items, hold down the Control key while clicking on each item.
or
Click in the dialog and drag the mouse. Dialog items completely enclosed in the
area described by the mouse are selected. (Hold down the Control key while
dragging to select dialog items partially enclosed by the described area.)
To select all items, use the Select All command from the Edit Menu in the Dialog
Panel.
To select items according to the tabbing order, press the Tab key. The tabbing order is
defined by the order of items in the Order Items Panel.

To unselect items in a dialog for editing:

1. Perform one of the following actions:
To unselect a selected item, click on it once.
To unselect all selected items, click on an empty area in the dialog.
To unselect several, but not all items, hold down the Control key while clicking on
each selected item.
NOTE: Selected items are indicated in ACL Designer by the appearance of square
“handles” around the item.
58 Chapter 6 Dialogs

To open a resource editor for a dialog item:

1. Perform one of the following actions:
Double-click on a dialog item placed in a dialog.
Select a dialog item in a dialog. Then select Edit Item... from the Dialog Menu.
Select a dialog item in a dialog. Press Enter.
A resource editor for the dialog item opens. For details on editing dialog items, see
Chapter 6, “Dialogs” on page 51.
NOTE: The resource editor for a dialog item is opened in a “reusable window.”
When another dialog item is selected for editing, the contents of the
reusable window changes to the resource editor of the newly selected item.

Using the Dialog Panel’s Edit Menu

From the Edit Menu, shown in Figure 32, you can undo or redo actions performed on selected
items, as well as perform the familiar editing commands Cut, Copy, Paste, Clear, and Duplicate.

Undo Ctrl+Z
Redo Ctrl+Y

Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Clear Ctrl+B
Duplicate Ctrl+D

Select All Ctrl+A

Place In Container
Place in Grouped Container
Place in Exclusive Container
Remove From Container

Set Foreground...
Set Background...
Set Font...
Reset to Defaults

Figure 32. Dialog Panel Edit Menu

These commands are covered in detail in Chapter 4, “Resource Editor Overview” on page 33.
Additional features of the Dialog Panel’s Edit Menu are described in the following sections.

Select All
At times you may want to select all of the items in a dialog. For example, you may want to copy
all of the items in one dialog to another dialog, or clear all of the items from the Dialog Panel.
 Using the Dialog Panel’s Edit Menu 59

To select all of the items in a Dialog Panel:

1. Select Select All from the Edit Menu in the Dialog Panel.
All items in the panel are selected. (Square “handles” appear around the edges of
selected items.)

Placing Items in Containers

A container is a dialog item that holds other dialog items. Dialog items placed in a container
behave as a unit, and cannot be selected individually for editing from the Dialog Editor. Placing
items in a container is useful when the items function as a logical unit. (The exclusive group
dialog item is an example of dialog items grouped in a container.)
To edit dialog items placed in a container, the resource editor for the container must be opened.
The container dialog item is discussed in detail in Chapter 6, “Dialogs” on page 51.

To place dialog items in a container:

1. Select the dialog items to place in a container.
2. From the Edit Menu, select one of the following:
Place In Container
A container is created and the selected items are placed in the container. The
position and size of the items are not affected.
Place In Grouped Container
A container is created and the selected items are placed in the container. The items
are sized and aligned automatically.
Place In Exclusive Container
A container is created and the selected items are placed in the container. The items
are automatically sized and aligned. When items are placed in an exclusive
container, users can only select one of the items at a time.
NOTE: Only items that are subclasses of vcontrolToggle, such as a check
box, can be grouped together to form a grouped container or an exclusive
container. A notice is displayed if the items you selected do not fulfill this
requirement.

To remove items from a container:

1. Select the container with dialog items to be removed.
2. Select Remove From Container from the Edit Menu.
The container is removed from the dialog. The items from the container remain in the
dialog, and are selected for editing.

Setting Attributes for Dialog Items

From the Edit Menu you can open choosers to set the display attributes of selected dialog items.
Select Set Foreground... or Set Background... from the Edit Menu to open the Color Chooser.
Select Set Font... to open the Font Chooser. To revert to the default attributes of a dialog item,
select Reset to Defaults.

NOTE: Dragging and dropping of fonts and colors is supported from the Font and Color
Choosers. For more information on using these choosers, see Chapter 11, “The Font
Chooser” on page 129, and Chapter 12, “The Color Chooser” on page 131.
60 Chapter 6 Dialogs

Sizing Dialog Items in the Dialog Panel

Most dialog items placed in the Dialog Panel for editing can be resized directly in the Dialog
Panel. However, if the dialog item has been predefined with “natural sizing,” the springs and
struts of the item may need to be edited before it can be resized. (An example of a natural sized
item is the button item when it is created from the Item Palette. The button’s size is defined by
its title or other contents.) If more than one item is in the Dialog Panel, resizing one item may
affect the size of another item. This is because of the sizing behavior of dialog items that have
been linked with springs and struts. For more information on editing springs and struts, see
“Working with Connections” on page 65.
To precisely size dialog items, use the Dialog Item Panel of an item’s resource editor. For details
on editing dialog items, see Chapter 6, “Dialogs” on page 51.

To size a dialog item in the Dialog Panel:

1. Select the dialog item you want to size.
Square “handles” appear around the edges of selected items.
2. Drag a handle of the selected item.
If the dialog item is not naturally sized, the size of the item changes.
NOTE: The dialog itself can be resized in the Dialog Panel. To resize a dialog in
the Dialog Panel, drag a corner or edge representing the bounds of the
dialog. The size of the dialog changes. The new size of the dialog will be
reflected in the W and H coordinates displayed in the Window Panel of the
Dialog Editor.

Arranging Items in a Dialog

Dialog items placed in a dialog can be repositioned by selecting and dragging the dialog items
in the Dialog Panel. Commands are also available in the Arrange Menu of the Dialog Panel to
specify relative placement of selected dialog items. Figure 33 shows the Arrange Menu.

Bring to Front
Bring Forward
Send Backward
Send to Back

Align Left
Align Horizontal Centers
Align Right
Align Top
Align Vertical Centers
Align Bottom

Distribute Horizontally
Distribute Vertically

Figure 33. Dialog Panel Arrange Menu

 Arranging Items in a Dialog 61

To reposition a dialog item in a dialog:

1. Select the dialog item or items you want to reposition.
Square “handles” appear around selected items.
2. Drag the selected items to a new position in the dialog.
When more than one item is selected, all the selected items move as a group.
3. For precise positioning, use the arrow keys to move the selected item.
The item is moved one pixel at a time in the direction specified by the arrow key.
NOTE: Some dialog items may have predefined springs and struts that prevent the
items from being moved to new positions, or cause other dialog items to be
moved simultaneously. For details on specifying placement of dialog items
with springs and struts, see “Working with Connections” on page 65.

Dialog items have a relative “front to back” position in a dialog. When a new item is placed in
a dialog it is placed in front of, relatively speaking, other dialog items previously placed in the
dialog. This is apparent if you try to drag a newly created dialog item behind another item
already in the dialog. The front to back relationship reflects the order of the items in the Order
Items Panel. To change the relative position of dialog items in a dialog, use the following
commands from the Arrange Menu.

Bring To Front/Bring Forward Commands

The Bring To Front and Bring Forward commands move a dialog item forward in a stack of
items. Select Bring Forward to move a selected dialog item one layer closer to the front of the
stack. Select Bring To Front to move a selected dialog item to the front of the stack.

Send To Back/Send Backward Commands

The Send To Back and Send Backward commands move an item backward in a stack of items.
Select Send Backward to move a selected dialog item one layer closer to the bottom of the
stack. Select Send To Back to move a selected dialog item to the back of the stack.
You can specify the relative placement of two or more dialog items with the Align commands
in the Arrange Menu.

To align dialog items:

1. Select the dialog items you want to align or distribute.
2. Select an align command from the Arrange Menu in the Dialog Panel.
The items are aligned or distributed.
NOTE: It is sometimes easier to align items as you place them into the dialog. After
the items are aligned, set up the connections (as described later in this
chapter) to “cement” the relative positions of the items and define their
behavior in resized windows.

Table 4 lists the commands in the Arrange Menu for aligning items:

Table 4. Alignment Commands

Command Result
Align Left Left sides of all items line up with the left side of the leftmost item.
Align Horizontal Centers Horizontal centers of all items line up on the same vertical line; item positions change
horizontally.
62 Chapter 6 Dialogs

Table 4. Alignment Commands

Command Result
Align Right Right sides of items line up with the right side of the rightmost item.
Align Top Top sides of all items line up with the top side of the topmost item.
Align Vertical Centers Vertical centers of all items line up on the same horizontal line; item positions change
vertically.
Align Bottom Bottom sides of items line up with the bottom side of the bottom-most item.
Distribute Horizontally Items are distributed evenly between the right and left items; item positions do not
change vertically.
Distribute Vertically Items are distributed evenly between the top and bottom items; item positions do not
change horizontally.

For example, to line up the left sides of four dialog items, select the four items and then select
Align Left from the Arrange Menu. To make the vertical spacing for the items even between
the top item and the bottom item, select Distribute Vertically.

The Order Items Panel

The order of the items in the Order Items Panel, shown in Figure 34, defines the tabbing order
of dialog items in a dialog and their relative “top to bottom” placement. To change the tabbing
order you need to rearrange the order of items in the list. Rearrange items in the list by dragging
and dropping them to new locations. If you have a three-button mouse, drag dialog items with
the middle button. If you have a two-button mouse, drag dialog items by pressing both buttons
at the same time.

File Edit Panels Item

Class Tag Title

vbutton Button Button

vcontrolToggle Check Box Check Box
vdialogLabelItem Label Item Label Item
vcontainer Container

Figure 34. Order Items Panel

The Order Items Panel has an Item Menu with options to specify the behavior of items in the
dialog. The Item Menu contains a series of check boxes to define these properties:
Default Focus Item
Makes the selected item in the list enabled when the dialog item opens. Only one
 Customizing the Item Palette 63

item in a list can be set to Default Focus.

Confirm Item
Makes the selected item in the list a Confirm Item. A user activates a Confirm Item
from the keyboard by pressing Return.
Abandon Item
Makes the selected item in the list an Abandon Item. A user activates an Abandon
Item from the keyboard by pressing Escape.
NOTE: Default Focus, Confirm, and Abandon can also be selected from the Dialog Menu in
the Dialog Panel.

Customizing the Item Palette

You can add or remove items in the Item Palette, edit or create an icon image, change the view
of the Item Palette, and rearrange the icons. You can also edit the default attributes and
connections of an item associated with an icon.
The following procedures show how to customize the Item Palette. The first five procedures use
the Item Palette Menu. The last procedure shows how to customize the Item Palette directly
from the Dialog Panel.

To add an icon to the Item Palette:

1. Select File in the Item Palette Menu.
A menu appears with New Item as an option.
2. Select New Item.
The New Item Menu appears with a list of items that can be added to the Item Palette.
This menu is identical to the New Item Menu shown in Figure 31 on page 56, except
it can only be used to add items to the Item Palette.
3. Select the item you want to add to the Item Palette.
An icon for the selected item appears in the Item Palette.

To remove an icon from the Item Palette:

1. Select an icon in the Item Palette.
2. Select Edit in the Item Palette Menu.
3. Select Clear.
The selected icon has been removed from the Item Palette.

To edit an icon’s image:

1. Select an icon in the Item Palette.
2. Select Edit in the Item Palette Menu.
3. Select Edit Icon.
An Image Editor opens with the image for the selected icon displayed for editing. For
details on using the Image Editor, see Chapter 10, “Images” on page 115.
64 Chapter 6 Dialogs

To edit the default attributes of the item associated with an icon:

1. Select an icon in the Item Palette.
2. Select Edit in the Item Palette Menu.
3. Select Edit Item.
A resource editor opens, displaying the default attributes for the item. Use this editor
to change the default attributes. For more information on editing dialog items, see
Chapter 6, “Dialogs” on page 51.

To edit the default springs and struts of the item associated with an icon:
1. Select an icon in the Item Palette.
2. Select Edit in the Item Palette Menu.
3. Select Edit Connections.
A chooser opens specifying the default springs and struts for the item. Use this chooser,
shown in Figure 35, to change the default settings. For more on connections see
“Working with Connections” on page 65.

Stretches Natural Base

Left Left
Width Width
Right Right
Top Top
Height Height
Bottom Bottom

OK Cancel

Figure 35. Edit Connections dialog

To customize the Item Palette from the Dialog Panel:

1. Place a dialog item in the Dialog Panel.
2. Edit the item to give it the attributes and behavior you want.
3. Select the Add To Palette command from the Dialog Menu. (Make sure the item you
want to add is the selected item in the Dialog Panel.) You can also drag and drop the
item to the Item Palette.
The item, with the newly defined attributes, is added to the Item Palette.

Testing Your Dialog

As you design your dialog, you can test it with the Try Dialog command to see if it works as
expected.
 Working with Connections 65

To test your dialog:

1. Select Try Dialog from the Dialog Menu.
A test copy of the dialog you have been designing opens. The dialog items in this test
copy are activated for testing.
2. Try out the dialog.
When trying out a dialog you can see how various features of your dialog work. The
resize behavior of the dialog and the items it contains can be tested. Additionally, text
can be typed inside of editable text fields, scroll bars can be tested to see if they work
as defined, buttons can be pressed, or default attributes activated, depending on the
dialog’s contents.
3. When you are finished trying out your dialog, close the test copy by unselecting Try
Dialog from the Dialog Menu. You can also close the Try Dialog Window by using the
window manager’s close box.
The Try Dialog Window disappears.

Working with Connections

Springs and struts are devices that position dialog items within a dialog and define their sizing
behavior. These devices, referred to as connections, are displayed and edited in both the Dialog
Panel and the Connection Window. A spring solution is the series of connections that position
or size a dialog item. Figure 36 shows a spring solution for a dialog item placed in the Dialog
Panel.

File Edit Panels Dialog Arrange Connection Windows

Outside Strut

Inside Strut

Spring

Selected Spring

Figure 36. Dialog Panel showing connections

Dialog items have inside and outside connections. Inside connections are contained within a
dialog item, connecting opposite sides of the item. The inside connections of a dialog item
determine the size of an item. Outside connections link a dialog item to the border of the dialog
window or to another dialog item. The outside connections determine the relative positions of
dialog items in a dialog, including the positions of the items if the dialog is resized.
66 Chapter 6 Dialogs

Springs and struts function much as their names imply. A spring stretches to fill the available
space; a strut has a specific length. For example, consider the spring solution in Figure 36. The
outside connection on the left of the dialog item is a strut; the outside connection on the right is
a spring. With the spring solution shown, the dialog item is always positioned a specific distance
from the left border of the dialog, even if the dialog is resized. However, if both the left and right
outside connections were springs, as in Figure 37, the dialog item would always be centered
between the left and right borders of the dialog. Now if the dialog is resized, the dialog item
would remain centered, left and right, in the dialog.

File Edit Panels Dialog Arrange Connection Windows

Figure 37. Dialog Panel showing edited connections

A combination spring/strut connection sets the minimum length of a spring. This is useful
when you want an item to be a minimum distance from another item or from the border of the
dialog.
The inside connections of a dialog item can be used to make an item natural-sized. A natural-
sized item adjusts it size according to its contents. For example, the inside connections of a
button dialog item can be defined as natural-sized struts. The size of the button is then
determined by the size of its contents (the title displayed on the button).
A chain is a series of connections between dialog items. A chain is in one direction, horizontal
or vertical, and must always have at least one spring connection. If a chain does not have at least
one spring connection, the spring solution cannot stretch to fit a resized dialog.
Connections have a direction determined by the connection’s source and destination. The
source for outside connections is always a dialog item; the destination is another dialog item or
the border of a dialog. The source for inside connections is one edge of a dialog item; the
destination is the opposite edge of the item. The direction of a connection helps determine the
behavior of the connection.
 Working with Connections 67

When an item is initially placed in a dialog, with few exceptions, the outside connections on the
top and left sides of the item are struts. The outside connections on the bottom and right sides
of the item are springs. The inside connections are often natural-sized struts, but may vary,
depending on the dialog item.

To display connections for a dialog item (or items):

1. Select one or more dialog items in the Dialog Panel.
2. Select Connection from the Windows Menu in the Dialog Panel.
Connections are displayed for the selected item(s) in the Dialog Panel, and the
Connection Window appears.
or
2. Select Show from the Connection Menu in the Dialog Panel.
Connections are displayed for the selected item(s) in the Dialog Panel, but the
Connection Window does not appear.

To select connections for editing:

1. Select a dialog item in the Dialog Panel.
2. If the connections are not displayed, display the connections.
3. Click a connection in the Dialog Panel (or the Connection Window if it is open).
The connection is selected for editing. Selected connections appear highlighted.
4. Press the Control key while clicking to select multiple connections.
or
3. Select Select from the Connection Menu in the Dialog Panel.
The Select Submenu opens.
4. Select a connection from the options available in the Select Submenu.
The connection is selected for editing. Selected connections appear highlighted.
Multiple selections of connections cannot be made from the Select Submenu.

Changing the Destination of a Connection

Springs and struts connect one dialog item to another item or to the dialog border. The
destination of a connection is changed by selecting a connection and dragging it to a new
destination.
For example, Figure 38 shows a Dialog Panel containing a box item and a button item. The
default connections for the button item is displayed in the figure. The left outside strut of the
button can be connected to the right edge of the box item.
68 Chapter 6 Dialogs

File Edit Panels Dialog Arrange Connection Windows

Box Item

Button

Figure 38. Default connections for a dialog item

Figure 39 shows the same Dialog Panel after connecting an outside strut of the button to the box
item.

File Edit Panels Dialog Arrange Connection Windows

Box Item

Button

Figure 39. Reconnected outside strut

 Working with Connections 69

To change the destination of a connection:

1. Select Show from the Connection Menu in the Dialog Panel.
Connections are displayed for selected items.
2. Select the item that has the connection you want to change.
The item’s connections are displayed.
3. Select the connection you want to change.
The connection is highlighted.
4. Drag the connection to its new destination.
During the drag operation the end of the connection is displayed as an arc. The arc
indicates the nearest destination point during the drag. Releasing the mouse changes
the destination to the connection point indicated by the arc.

Using the Connection Window

The Connection Window, shown in Figure 40, displays the connections for a selected item or
items in the Dialog Panel.

Tag: Button
To: (Border)
To Edge: Left Length: 124

Natural Base
Fixed Base

Value: 124

Drag Lock
Stretch

Close

Figure 40. Connection Window

In the Connection Window, you can do the following:

• Change the type of connection (for example, change a spring to a strut)
• Set the length of a strut
• Set the minimum length of a combination spring/strut connection
• Define the size of a dialog item with its inside connections
70 Chapter 6 Dialogs

Table 5 lists the features of connections.

Table 5. Connection Window features

Field Description
Tag Displays the tag name of the selected item.
To Displays the name of the destination for the selected connection. If the destination is another
dialog item, the tag name of the item is displayed. If the destination is the border of the dialog,
“(Border)” is displayed.
To Edge Indicates the location of the connection on the destination item. The location is expressed as the
top, bottom, left, or right edge of the destination item.
Connection Display Graphically displays the inside and outside connections of a selected dialog item. If more than
Area one dialog item is selected, the connections displayed represent all the connections in the same
relative position on the selected items.
Length Displays the length of a connection.
Natural Base Changes a strut to its natural size.
Changes a combination spring/strut connection to a spring connection.
This field is always enabled for spring connections, which are natural-sized.
The size of a natural-sized connection is indicated in the Length field.
Fixed Base Resizes a strut to the size indicated in the Value field.
Converts a spring to a combination spring/strut connection. The size of the strut portion of the
combination is indicated in the Value field.
Value Sets the length of a strut or the length of the strut section of a combination spring/strut
connection.
Drag Lock Locks the length of a strut to the length specified in the Value field. When the length of a dialog
item’s strut is locked, it cannot be dragged while editing.
Stretch Converts a strut to combination spring/strut connection.
A spring, by definition, is a stretch connection. Unselecting Stretch for a spring converts the
spring to a strut.
Close Closes the Connection Window.

To change the type of a connection:

1. Open the Connection Window by selecting Connection from the Windows Menu in
the Dialog Panel.
The Connection Window is displayed.
2. Select the item that has the connection you want to change.
The connections for the item are displayed in both the Dialog Panel and the Connection
Window. In the Connection Window, the tag for the selected item is displayed.
3. In either the Connection Window or Dialog Panel, click on the connection you want to
change. (It may be easier to select a connection in the Connection Window than in the
Dialog Panel.)
The connection is highlighted in both windows, and information about the connection
is shown in the Connection Window.
4. Change the connection in one of the following ways.
To change a spring to a strut:
Unselect the Stretch check box and enter the strut length you want in the Value
field. The spring changes to a strut of the length you entered.
To change a strut to a spring:
Select the Stretch check box and change the Value to 0. The strut changes to a
 Working with Connections 71

spring.
If the Value is not set to 0, the strut changes to a combination spring/strut
connection and the strut part of the connection has a length equal to Value (see
“To set a combination spring/strut connection:” on page 72).
To change a spring to a strut or a strut to a spring:
Double-click on the connection you want to change in the Connection Window or
in the Dialog Panel.
NOTE: If you define a chain that does not contain a spring connection, you will get
an “error strut.” A chain must always contain at least one spring connection
so it can stretch to fit a resized dialog. Error struts are outlined; on color
monitors they are also displayed in red.
You can set the length of a strut by dragging an item to the desired position in the Dialog Panel
or by setting the size of the strut in the Connection Window. When you set the size of a strut in
a chain, the spring in the chain stretches to fill the remaining space.

To set the length of a strut in the Connection Window:

1. Open the Connection Window by selecting Connection from the Windows Menu in
the Dialog Panel.
The Connection Window is displayed.
2. Select a dialog item in the Dialog Panel.
The connections for the item are displayed in both the Dialog Panel and the Connection
Window. In the Connection Window, the tag for the selected item is displayed.
3. In either the Dialog Panel or the Connection Window, select the strut you want to set.
The strut is highlighted in both the Connection Window and Dialog Panel. The current
length of the selected strut, in pixels, is displayed in the Length and Value fields. The
Stretch check box is not selected.
4. In the Value field, enter a new strut length and press Enter.
In the Dialog Panel, the selected item moves to reflect the new strut length.
5. If you want to ensure that the length of this strut cannot be changed while editing,
select Drag Lock in the Connection Window.
The length of the selected strut is locked. You cannot change the length of the strut by
dragging the item in the Dialog Panel. For example, suppose the left strut of an item is
connected to the left side of the dialog border. You set the length to 15 and lock it. Now
when you try to drag the item, it remains 15 pixels from the left side of the dialog.
When you make a combination spring/strut connection, you are essentially setting the minimum
length of the connection while still allowing it to stretch. This length is the size of the strut
portion of a combination connection.
72 Chapter 6 Dialogs

To set a combination spring/strut connection:

1. Open the Connection Window by selecting Connection from the Windows Menu in
the Dialog Panel.
The Connection Window is displayed.
2. Select a dialog item that has the connection you want to set.
The connections for the item are displayed in both the Dialog Panel and the Connection
Window. In the Connection Window, the tag for the selected item is displayed.
3. In either the Dialog Panel or the Connection Window, select the connection you want
to set.
The connection is highlighted in both the Dialog Panel and the Connection Window.
4. If the connection is a spring, enter the minimum length (in pixels) you want for the
combination connection in the Value field. Press Enter.
A part of the spring equal to the length you set changes to a strut.
5. If the connection is a strut, select the Stretch check box. Then enter the initial length
(in pixels) you want for the combination connection in the Value field. Press Enter.
Part of the connection becomes a spring while part remains a strut. The length of the
strut portion of the connection is equal to the length entered in the Value field.
The size of a dialog item can be set to a fixed value or be natural-sized by setting a dialog item’s
inside connections. The size of a natural-sized item is determined by the size of its contents.

To define the size of a dialog item using its inside connections:

1. Open the Connection Window by selecting Connection from the Windows Menu in
the Dialog Panel.
The Connection Window is displayed.
2. Select a dialog item in the Dialog Panel.
The connections for the item are displayed in both the Dialog Panel and the Connection
Window.
3. Select an inside connection.
Horizontal connections set the width; vertical connections set the height.
4. Select the Fixed Base option to give the connection a fixed value. Enter the size for
the connection in the Value Field.
The item is sized according to your specifications.
or
4. Select the Natural Base option to make an item natural-sized.
The size of the item will be determined by its contents.

Using the Connection Menu

The Connection Menu in the Dialog Panel is used to edit an item’s connections. From the
Connection Menu you can display connections in the Dialog Panel, and specify the display size
of connections. Basic editing operations can be performed on connections using the Connection
Menu. Additional editing options are available to define a chain for several dialog items, and to
follow connections to adjacent items in a chain.
 Working with Connections 73

Displaying and Changing Connections

Use the Connections Menu to display connections in the Dialog Panel without opening the
Connection Window. An option is available to change the size of the displayed connections
from large to small.

To display connections in the Dialog Panel:

1. Select Show from the Connections Menu in the Dialog Panel.
Connections are displayed in the Dialog Panel.

To change the size of displayed connections in the Dialog Panel:

1. Select or unselect Use Large Connections from the Connections Menu.
Connections are displayed in the Dialog Panel as specified.
NOTE: The default size for connections in the Dialog Panel is large. Connections
are always displayed large in the Connection Window.
The Connection Menu has the following options to change the type of a selected connection:
• Natural Length
• Natural Base + Spring
• Fixed Length
• Fixed Base + Spring
• Locked Fixed Length
• Zero Length
• Spring

To change the type of a connection using the Connection Menu:

1. Select the connection you want to change in the Dialog Panel or the Connection
Window.
The selected connection is highlighted in the Dialog Panel.
2. Select Connection in the Dialog Panel Menu.
The Connection Menu opens. The option for the selected connection is highlighted in
the Connection Menu.
3. Select another option to change the type of the selected connection.
The connection in the Dialog Panel (and the Connection Window if it is open) changes
to the selected type.
A dialog item has a set of default connections associated with it when the item is placed in the
Dialog Panel. You can undo any changes to a dialog item’s connections by resetting the
connections to the defaults.

To reset the connection of a dialog item:

1. Select a dialog item in the Dialog Panel.
2. Select Reset from the Connection Menu.
The connections for the selected dialog item reset to the default connections for that
item.
74 Chapter 6 Dialogs

Chaining Items
Chaining refers to forming connections between two or more dialog items. The Chain option of
the Connection Menu provides a convenient way to chain items in a Dialog Panel.
You can chain items in the following ways:
• Bottoms to tops
• Left sides
• Right sides
• Left sides and right sides
• Left sides to right sides
• Top sides
• Bottom sides
• Bottom sides and top sides.

To chain items:
1. Select the items you want to chain in the Dialog Panel.
You must select two or more items for the Chain command to be enabled.
2. Select Chain from the Connection Menu.
The Chain submenu appears. Icons are displayed next to each option in the submenu
to illustrate the type of chains you can form.
3. Select an option from the Chain Submenu.
The selected items are chained according to your selection.

To unchain items:
1. Select the items you want to unchain in the Dialog Panel.
2. Select Reset from the Connection Menu.
The selected items are unchained and their connections are reset to the default
connections.

Following a Connection
You can change the selection from the currently selected dialog item to an item connected to it
with the Follow option in the Connection Menu.

To select a dialog item by following a connection:

1. Select a dialog item in the Dialog Panel.
The dialog item must be connected to another dialog item to follow a connection.
2. Select Follow from the Connection Menu.
The Follow Submenu appears. Icons are displayed next to each option in the submenu
to illustrate the connections you can follow.
3. Select a connection to follow from the Follow Submenu.
The selected dialog item changes according to the connection you followed.
CHAPTER
7
Dialog Items

Dialog Item Overview

A dialog item is a composite resource contained within a dialog that enables a user to interact
with an application. A dialog item is usually created by dragging its icon from the Item Palette
to the Dialog Panel. Dialog items can also be created using menu selections in the Dialog Panel
of a Dialog Editor or by dragging an item from a Dictionary Editor. Custom dialog items can be
created using the subclassing facilities of ACL Designer.
Figure 41 illustrates the dialog items represented on the Item Palette.

Button Check Box Slider

Exclusive Group Scroll Bar

File Edit View

Label Item Editable Text

Box Item List Item

Option Menu Palette

Menu Bar Image Dialog Item (Generic)

Figure 41. Dialog items represented on the Item Palette

75
76 Chapter 7 Dialog Items

For additional information on the Item Palette and dialogs, see page 51. For information on
subclassing resources, see “Creating Subclassed Resources,”on page 48.

Supported dialog items

WARNING - Extra resources and dialog items have been provided to ADEPT-specific
development. Refer to the following lists to determine which resource/dialog items are
supported in ADEPT.
The following dialog items are supported for use in ADEPT.
Adept Button Item Adept Spinner
Adept Check Box Adept Text Item
Adept Image Adept Toolbar
Adept List Item Adept Toolbar Button
Adept Menu Bar Box Item
Adept Notebook Container
Adept Option Menu Exclusive Group Items
Adept Outline Grouped Container
Adept Password gpBean
Adept Popdown Combobox Label Item
Adept Radio Group Line Item
Adept Scroll Bar Page
Adept Slider Section

Unsupported dialog items

The following resources/items should not be used for ADEPT-specific development. Many of
the items below have been sub-classed specifically for use with ADEPT. These items appear in
the list of supported resources/items and begin with the word “Adept.”
Adept Canvas List View
aptOutlist Main View
aptToolbarbutton Menu Bar
aptPasswordItem Notebook
Button Option Menu
Checkbox Palette
Combo Ruler
Combo Box Scroll Bar
Control Slider
Dialog item Spinner
Domain Item Text Item
Domain View Text Ruler
Icon View Text Spinner
Keystroke Item Text View
List Item

The Dialog Item Panel

A resource editor for a dialog item is usually opened by double-clicking on the dialog item in
the Dialog Panel of a Dialog Editor. The resource editor is opened in a “reusable window.”
When another dialog item is selected for editing, the contents of the reusable window changes
to the resource editor of the newly selected item.
 The Dialog Item Panel 77

The resource editor for each dialog item contains a Dialog Item Panel, shown in Figure 42. The
resource editors for many dialog items contain additional panels.

File Edit Panels

Tag: Slider Mnemonic: X: 53 Y: 124

Title: Slider W: 196 H: 16

Enabled Visible Border

Click Focusable Focusable Image Mask

Foreground Set Color... Background Set Color...

Menu Set Menu... Image Set Image...

Font Set Font... Cursor Set Cursor...

ABCDEF

Figure 42. Dialog Item Panel for the slider dialog item

Use the Dialog Item Panel to define the tag and title names of an item, and to specify its size
and placement within a dialog. The tag name is the name an application uses to access the
dialog item after the resource file is loaded into memory. The title name is displayed with the
dialog item in an application. (Not all dialog items display the title name, even if the name is
specified in the Dialog Item Panel.)

To specify the tag and title names for a dialog item:

1. In the Dialog Item Panel, select the text field for the tag or title you want to edit.
The text field is enabled.
2. Edit the tag or title for the dialog item.
3. Press Enter, or change the focus by selecting another item in the editor.
The tag or title name of the dialog has been changed. For dialog items that display their
titles, the title is visible in the Dialog Panel.

The position of a dialog item is determined by its X and Y coordinates; its size by its W and H
coordinates. The X and Y coordinates specify the offset (in pixels) from the lower left corner of
a dialog to the lower left corner of a dialog item. The W and H coordinates set the width and
height (in pixels) of the dialog item. Refer to Figure 43 for a diagram of these coordinates.
78 Chapter 7 Dialog Items

Dialog Bounds

H = 75
Offset (in pixels) - X
25 Dialog Item

W = 125
(25, 50)

50
(0,0)
Origin
Offset (in pixels) - Y

Figure 43. Coordinates of a dialog item

To specify the position and size of a dialog item:

1. In the Dialog Item Panel, enter the X and Y values for position, and the W and H values
for size.
The values entered are the new position and size specifications. The Dialog Panel
reflects these changes.

Dialog Item Attributes

A dialog item has a series of attributes that define its behavior and appearance in a dialog. The
attributes listed in Table 6 are enabled with a series of check boxes in the Dialog Item Panel.

Table 6. Dialog item attributes

Attribute If selected
Enabled Makes the dialog item available for use in the dialog. Items that are not enabled appear dimmed.
Visible Displays the dialog item in the dialog. Items that are not visible are still associated with the dialog,
but are not displayed.
Border Outlines the dialog item with a border.
Click Focusable Activates the dialog item when a user clicks it with a mouse.
Focusable Enables the item for “tabbing.” A user can “tab through” the focusable items in a dialog.
Image Mask Uses the dialog item’s image attribute as a 1-bit mask to draw the item. The “on” bits of the mask are
drawn and the remainder of the bits are not drawn.

Use the Mnemonic field to specify a mnemonic key for a dialog item. A mnemonic key allows
the user to enable a dialog item by pressing a specified key in combination with the mnemonic
key modifier from the keyboard. (The mnemonic key modifier is platform dependent but is
 Dialog Item Attributes 79

usually the Alt key. ) Only one alphanumeric character can be specified as the mnemonic key.
If the specified key is in the title of the Dialog Item, the corresponding letter is underlined on
the display.

CAUTION: Although the same mnemonic key can be defined for more than one dialog item
in a dialog, only one of the items will ever be enabled with the mnemonic key
selection. It is up to the application developer to provide unique mnemonic key
definitions to items in a dialog.

The user does not specify the case of a mnemonic key when making a selection
from the keyboard. This means the upper case and lower case version of a
character are not unique mnemonic key specifications.
You can further define attributes for a dialog item in the Dialog Item Panel by opening the
choosers and editors associated with a series of check boxes. Table 7 lists the choosers and
editors available in the Dialog Item Panel. Selecting one of these check boxes enables the button
associated with it. Click the button to open the chooser or editor associated with the button.

Table 7. Dialog item attributes

Attribute Chooser or Editor

Foreground Color Color Chooser
Background Color Color Chooser
Menu Menu Editor
Image Image Editor
Font Font Chooser
Cursor Cursor Editor

To set the foreground or background color for a dialog item:

1. Select the Foreground or Background check box.
The Set Color button is enabled.
2. Click Set Color.
The Color Chooser is displayed. In the Color Chooser, you can select one of four color
models (HLS, RGB, CMY, and Gray). Use the color wheel and slider bars to set the
foreground or background color.
The Color Chooser supports dragging and dropping of colors. For more information,
see Chapter 12, “The Color Chooser” on page 131.

To create a menu for a dialog item:

1. Select the Menu check box.
The Set Menu button is enabled.
2. Click Set Menu.
The Menu Panel is displayed. In the Menu Panel, you can create a pop-up menu for a
dialog item and test the menu.
For information on creating menus, see Chapter 9, “Menus” on page 109.
80 Chapter 7 Dialog Items

To select a font for a dialog item:

1. Select the Font check box.
The Set Font button is enabled.
2. Click Set Font.
The Font Chooser appears.
3. Select the type family, typeface, and size you want.
Your selection appears in the Font Display Field.
Dragging and dropping of fonts is available from the Font Chooser. For more
information, see Chapter 11, “The Font Chooser” on page 129.

To create an image for a dialog item:

1. Select the Image check box.
The Set Image button is enabled.
2. Click Set Image.
The Image Editor is displayed. Use the Image Editor to create, import, edit, or export
images. Image formats supported are GIF, XBM, PGM, PPM, PBM, ICO, DIB, and
BMP. (Run-length encoded DIB formats are not supported.) For information on the
Image Editor, see Chapter 10, “Images” on page 115.

To create a cursor for a dialog item:

1. Select the Cursor check box.
The Set Cursor button is enabled.
2. Click Set Cursor.
The Cursor Editor, a variation of the Image Editor is displayed. With the Cursor Editor,
you can create a custom cursor for a dialog item. For information on creating cursors,
see “The Cursor Editor” in Chapter 10, “Images” on page 115.

Dialog Item Default Attributes

When a dialog item is created, its default attributes are displayed in its Dialog Item Panel. If a
dialog item is created from the Item Palette, the default attributes may differ from the same item
created from a menu selection. The attributes defined from the Item Palette are designed to
readily incorporate the item into an application.

NOTE: Menu selection here means creating a dialog item using the New Menu of the
Dictionary Editor, the New Item Menu of the Dialog Panel, or dragging an item from
the Add Resource Types dialog or the Dictionary Editor. For details on creating
Dialog Items, see Chapter 5, “Dictionaries” on page 39, and Chapter 6, “Dialogs” on
page 51.

Dialog Items on the Item Palette

This section covers the dialog items represented on the Item Palette as originally configured.
The items initially represented on the Item Palette and their default properties can be changed.
For more information on the Item Palette, see “Customizing the Item Palette” in Chapter 6,
“Dialogs” on page 51.
 Dialog Items on the Item Palette 81

The Label Item

The label item is a one line, static, text field; it is usually used as an identifier in a dialog. For
example, if you had an unnamed dialog item in a dialog, you could place a label item next to it
to refer to the dialog item.
The resource editor for the label item contains only the Dialog Item Panel, shown in Figure 44.
The Title text field is used to specify the text for the label. The label item is a naturally sized
item, and automatically adjusts its size to fit the text in the Title field.

File Edit

Tag: Label Item Mnemonic: X: 72 Y: 179

Title: Label Item W: 62 H: 14

Enabled Visible Border

Click Focusable Focusable Image Mask

Foreground Set Color... Background Set Color...

Menu Set Menu... Image Set Image...

Font Set Font... Cursor Set Cursor...

ABCDEF

Figure 44. Dialog Item Panel for label item

The Adept Button and Adept Toolbar Button Items

The Adept button item is used in a dialog to initiate an action. The resource editor for the button
item contains only the Dialog Item Panel, shown in Figure 45. The Title text field contains the
name that appears on the button. The button item is a naturally sized item, and automatically
adjusts its size to fit the text in the Title field. The Adept Toolbar Button is a special button
specifically designed to be used in ADEPT toolbars. Both items share the same configuration
options.

File Edit

Tag: Button Mnemonic: X: 197 Y: 101

Title: Button W: 80 H: 25

Enabled Visible Border

Click Focusable Focusable Image Mask

Foreground Set Color... Background Set Color...

Menu Set Menu... Image Set Image...

Font Set Font... Cursor Set Cursor...

ABCDEF

Figure 45. Dialog Item Panel for button item

82 Chapter 7 Dialog Items

The Adept Radio Group Item

The Adept radio group item is a series of check boxes (toggle items) grouped in an exclusive
container. One, and only one, of the check boxes can be enabled at any time. The resource editor
for the exclusive group contains a Dialog Item Panel and an Exclusive Group Panel, as shown
in Figure 46.

File Edit Panels Container

Items:
<NewBtn1> - "Choice 1"
<NewBtn2> - "Choice 2"
<NewBtn3> - "Choice 3"

Layout: Auto-Arrange Flat Keyboard Traversal

Edit As Container Item Selected

Figure 46. Exclusive Group Panel for the exclusive group item

The Exclusive Group Panel contains a list of the items in the exclusive group. Use the Container
Menu in this panel to add to and edit items in the group. Use the Edit Menu to remove or
rearrange items in the group.

To add a toggle item to an exclusive group:

1. Select New Item from the Container Menu.
A new item is added to the Item List.

To edit a toggle item from the Item List:

1. Double-click the item you wish to edit, or select an item in the Item List and select Edit
Item... from the Container Menu.
The Check Box Editor opens. Use the Control Panel and the Dialog Item Panel of the
Check Box Editor to edit the toggle item. For more on the Check Box Editor see
“Control Dialog Items” on page 83.
NOTE: You can also select an item by moving up and down the Item List with the
arrow keys from the keyboard. Pressing Enter opens the Check Box Editor
for the selected item.

To remove a toggle item from an exclusive group:

1. In the Exclusive Group Panel, select a toggle item from the Item List.
2. Select Clear or Cut from the Edit Menu.
The toggle item you selected is removed from the Item List and no longer appears in
the Exclusive Group. If you selected Cut, the toggle item is copied to a clipboard and
can later be pasted into another container.
 Dialog Items on the Item Palette 83

To rearrange the order of toggle items in an exclusive group:

1. In the Exclusive Group Panel, drag and drop the toggle items in the Item List to new
positions or use the Cut, Copy, and Paste commands from the Edit Menu.
Toggle items can be copied and pasted to different positions in the Item List. For more
on using the Edit Menu, see Chapter 4, “Resource Editor Overview” on page 33.

When an exclusive group is created from the Item Palette, the group contains three toggle items
with a predefined spring solution. You can override the default spring solution and perform
additional editing on items in the group by adding a Container Panel to the Exclusive Group
Editor. For more on the Container Panel, see “The Container and Adept Toolbar Items” on page
95.

To override the default spring solution for an exclusive group:

1. Select Edit As Container from the Layout options.
A Container Panel has been added to the Exclusive Group Editor. Auto-arrange is now
unselected.
2. Select Container from the Panels Menu.
The Container Panel opens. Use the Container Panel to define a new spring solution or
otherwise edit the contents of the Exclusive Group.
By default, the Exclusive Group has flat keyboard traversal enabled. This means that a user can
“tab through” the items in an exclusive group to other dialog items in the dialog. If this option
is not selected, the user could tab into the exclusive group, but not out.

To disable flat keyboard traversal for an exclusive group:

1. Unselect Flat Keyboard Traversal from the Layout options.
Flat keyboard traversal is disabled.
When an Exclusive Group is created from the Item Palette, the first item in the group is selected,
making it the default selection for the group. You can change the default selection with the Item
Selected option.

To change the default selected item for an exclusive group:

1. In the Item List of the Exclusive Group Panel, select the item you want to be the default
selection.
2. In the Layout options, if the Item Selected option is not enabled, click Item Selected.
Any item previously designated as the default item is no longer the default selected
item in the group.

Control Dialog Items

A control dialog item is an item with a set of discrete states defined by a range of control values.
Each control value within this range indicates a specific action in an application. The Item
Palette by default contains the following control dialog items:
• Adept Check Box (Toggle)
• Adept Scroll Bar
• Adept Slider
• Adept Option Menu
84 Chapter 7 Dialog Items

The Adept check box is a toggle with values for on and off. The Adept scroll bar and Adept
slider items specify a range in a text field or a view from a list of items. The Adept option menu
is a pop-up menu that allows a user to specify one action from a series of options.
The resource editor for each control item contains the Control Panel shown in Figure 47.

File Edit Panels

Min: 0 Page: 1

Max: 1 Increment: 1

Value: 0

Vertical Exclusive Alternate Style

Figure 47. Control Panel

Table 8 lists the features of the Control Panel.

Table 8. Control Panel features

Feature Description
Min Defines the minimum value for the control item.
Max Defines the maximum value for the control item.
Value Defines the default placement within the control values.
Vertical Defines the orientation of a control item. The default is horizontal. (This option is not enabled for the
Option Menu and Check Box items.)
Exclusive Specifies that an item is drawn to represent an exclusive item, as represented in an exclusive group.
This option only applies to check box (toggle) control items.
Increment Sets the amount that a control value can be incremented.
Page Sets the amount that a scroll bar or slider pages.
Alternate Style Specifies an alternate style. Some look-and-feels have alternate ways to represent items. Currently,
this option only applies to the slider and check box under OPEN LOOK.

NOTE: The control values for Min, Max, and Value correspond to a position in a range of
values. For the nth position in a range, set the control value to n-1.
Not every feature from the Control Panel applies to every control dialog item. For example, the
page value has a specific meaning for the scroll bar and slider items, but has no meaning for the
check box and option menu items. Table 9 defines the valid features for each control item.
Table 9. Control dialog items

Control Dialog Item Feature Implementation

Check Box (Toggle) Min Set to zero. If set to -1, converts the check box to a tri-state check box.
Max Set to 1.
Value On or off. Some look-and-feels also specify a tri-state check box.
 Dialog Items on the Item Palette 85

Table 9. Control dialog items

Control Dialog Item Feature Implementation

Exclusive Draws the check box to represent an exclusive toggle item, as implemented in
an exclusive group.
Alternate Style Draws the check box in an alternate style (only available under OPEN
LOOK.)
Scroll Bar Min Usually set to zero.
Max Set to the maximum value in the range.
Value Position of the thumb of the scroll bar in the range of control values.
Vertical If selected, defines a vertical scroll bar.
Increment The base unit for increasing the control value.
Page The amount to increase the control value when the scroll bar is paged.
Slider Min Usually set to zero.
Max Set to the maximum value in the range.
Value Position of the slider in the range of control values.
Vertical If selected, defines a vertical slider.
Increment The base unit for increasing the control value.
Page The amount to increase the control value when the slider is paged.
Alternate Style Draws the slider in an alternate style (only available under OPEN LOOK.)
Option Menu Min Set to zero.
Max Set to one less than the number of menu items.
Value Index of the default menu item in the option menu. The default menu item is
displayed in an application.

The Adept Text and Adept Password Items

The Adept text item defines an editable text field in a dialog. A user can enter or edit text in
editable text fields. However, this field can be defined as static. A user can view static text fields,
but cannot edit them. The Adept Password item is a special version of the Adept Text item in
which characters do not appear as they are typed. Both items share the same configuration
options.
The Adept text item contains three panels:
• Dialog Item
• Text Item
• Text View
Use the Dialog Item Panel to define the font and colors for the text in the text field. Use the Text
Item Panel to define the properties of the text field. Use the Text View Panel to define the
appearance of the field.
The Text Item Panel, shown in Figure 48, contains a simple text editor with a text field and
various features to specify text treatment such as tab settings and line spacing. You can leave
the text field blank or place text in it. The user can edit or replace any text you place in the text
field unless the modifiable attribute is disabled.
To enter text for a text item, click in the text field and begin typing. The Set Style button opens
the Style Chooser; use this chooser to define styles for selected text in the text field. (The Style
Chooser is described on page 87.) Use the text ruler to set margins, tabs, line spacing, and
justification for text in the text field.
86 Chapter 7 Dialog Items

File Edit Panels

Selectable Wrap Set Style...

Modifiable One Line
Text Ruler

Text Field

Figure 48. Text Item Panel

Table 10 describes the various features of the Text Item Panel.

Table 10. Text Item Panel options

Feature Description
Selectable Enables the user to select the text field.
Modifiable Enables the user to modify text in the text field. Disabling this option converts the text field into a
static text field.
Wrap Automatically wraps text according to the specifications in the text ruler.
One Line Limits the text to one line.
Set Style... Opens the Style Chooser. Use the style chooser to select a font and attributes for the text.
Text Ruler Use the text ruler to set margins, tabs, justification, and line spacing for the text field.
Text Field Text entered here is displayed in your application.

Use the Text View Panel, shown in Figure 49, to add vertical and horizontal scroll bars to text
items. You can also define the scrolling attributes of text and specify the styles for highlighted
and unhighlighted text. (Highlighted text is text selected for editing; unhighlighted text is
selected text in a window that no longer has the focus.)
 Dialog Items on the Item Palette 87

File Edit Panels

Hilite Style: Default Auto-Scroll

Unhilite Style: Default

Scroll Locked Scroll Bars

Horizontally Horizontal
Vertically Vertical

Figure 49. Text View Panel

Table 11 describes the various options of the Text View Panel.

Table 11. Text View Panel options

Feature Description
Hilite Style Defines the appearance of highlighted text. The options are Default, Invert, Line, Box, None, and
Dotted Line.
Unhilite Style Defines the appearance of highlighted text when the dialog containing the text does not have focus.
The options are Default, Invert, Line, Box, None, and Dotted Line.
Auto-Scroll Automatically scrolls text in the editable text item.
Scroll Locked Disables the horizontal and/or vertical scrolling of text.
Scroll Bars Places horizontal and/or vertical scroll bars into the text field.

Style Chooser
Use the Style Chooser, shown in Figure 50, to apply styles and fonts to selected text in a text
item. Styles specified with the Style Chooser are only applied to text highlighted in the text field
of the Text Item Panel.

An example of this style.

Attributes
Set Font Set Color
Bold
Italic
Ascent: Auto
Underline
Hidden
Descent: Auto
Strikethru
Font
Size: Auto
Color

OK Apply Cancel

Figure 50. Style Chooser

88 Chapter 7 Dialog Items

The following text attributes are selected using tri-state check boxes:
• Bold
• Italic
• Underline
• Hidden
• Strikethru
Tri-state check boxes have three states–select, unselect, or no selection. The select state applies
the specified text attribute to highlighted text. The unselect state removes the specified attribute.
The no selection, or “fuzzy” state, leaves the current attribute unchanged. (The shading in the
check box appears gray when it is in the fuzzy state.)

To apply an attribute to text:

1. If the Style Chooser is not open, click Set Style... in the Text Item Panel.
The Style Chooser opens.
2. In the text field, highlight the text you want to change.
The Style Chooser only applies styles to highlighted text.
3. Select the check box for any attribute you want to apply.
4. Unselect the check box for any previously applied attribute you want to remove.
5. Specify “no selection” in the check box for any previously applied attribute you want
to remain unaffected by the new style.
6. Click Apply or OK in the Style Chooser.
The new style is applied to the highlighted text. (The Apply and OK confirmations
buttons may vary, depending on your current look-and-feel.)
For example, consider the situation where a sentence in the text field contains a key word that
you had previously set to bold. To make the entire sentence italic, but keep the bold attribute for
the key word, do the following:
1. Highlight the sentence.
2. Select the italic check box to apply the italic attribute to the sentence.
3. Specify “no selection” for the bold check box. This preserves the bold attribute
previously applied to the key word.
4. Apply the style.

The Style Chooser also contains two check boxes for Font and Color. Selecting Font or Color
enables the Set Font or Set Color buttons. Select these buttons to open the Font Chooser and
Color Chooser. Use these choosers to further define the appearance of selected text in the text
field. For more information on the Font Chooser and the Color Chooser, see “The Font
Chooser” on page 129., and “The Color Chooser” on page 131.
The Style Chooser has three fields to define the ascent, descent, and size of selected text in a
text item. Ascent is the amount type rises above the base line; descent is the amount type
descends below the base line. Size represents the font size. These fields are initially set to Auto;
the default values of the font define the attribute. To override the default values for selected text,
enter a value, in points, in the appropriate fields. To return to the default values, reenter Auto.
 Dialog Items on the Item Palette 89

The Box Item

The box item is a generic dialog item. Use the box item as a placeholder or a decoration, or to
logically group items. If you are creating subclassed dialog items in your application code, you
can use the box item as a place to begin subclassing. For more on creating subclasses, see
“Creating Subclassed Resources” in Chapter 5, “Dictionaries” on page 39.
The resource editor for the box item contains only the Dialog Item Panel, shown in Figure 51.

File Edit

Tag: Box Item Mnemonic: X: 117 Y: 59

Title: Box Item W: 100 H: 100

Enabled Visible Border

Click Focusable Focusable Image Mask

Foreground Set Color... Background Set Color...

Menu Set Menu... Image Set Image...

Font Set Font... Cursor Set Cursor...

ABCDEF

Figure 51. Dialog Item Panel for Box Item

The Adept Menu Bar Item

The Adept menu bar is a dialog item containing an ordered list of menus. Menus are created for
a menu bar in the Menu Bar Editor, shown in Figure 52.

File Edit Panels Menubar

Menus:
<FileMenu> - "File"
Menu List <EditMenu> - "Edit"

Figure 52. Menu Bar Panel

If a menu bar is created from the Item Palette, “File” and “Edit” menus are predefined for the
menu bar. Additionally, a spring solution is predefined to place the menu bar at the top of a
dialog.
90 Chapter 7 Dialog Items

NOTES: The Menu Bar Editor itself has File and Edit menus. These menus are used in the
editor, and should not be confused with menus you are creating.

When creating a menu for a menu bar, use the Menu Bar Editor, and not the Set
Menu button in the Dialog Item Panel. Set Menu is used to create pop-up menus for
dialog items.

To add a menu to a menu bar:

1. Select New Menu from the Menubar Menu.
A new menu is added to the Menu List.

To edit a menu from the Menu List:

1. Double-click the menu you wish to edit, or select a menu in the Menu List and select
Edit Menu... from the Menubar Menu.
The Menu Editor opens. In the Menu Editor you can name your menu and add menu
items to it. For more on the Menu Editor, see Chapter 9, “Menus” on page 109.
NOTE: You can also select a menu by moving up and down the Menu List with the
arrow keys from the keyboard. Pressing Enter opens the Menu Editor for
the selected menu.

To remove menus from a menu bar:

1. In the Menu Bar Panel, select the menu you wish to remove from the Menu List.
2. From the Edit Menu, select Clear or Cut.
The menu you selected is removed from the Menu List and no longer appears on the
menu bar. If you selected Cut, the menu is copied to a clipboard and can later be pasted
onto the same or another menubar.

To rearrange the order of menus on a menu bar:

1. In the Menu Bar Panel, drag and drop the menus in the Menu List to new positions, or
use the Cut, Copy, and Paste commands from the Edit Menu.
For more on using the Edit Menu, see Chapter 5, “Dictionaries” on page 39.

To create a Help Menu for a menu bar:

1. In the Menu Bar Panel, select the Has Help check box from the Menubar Menu.
The last menu in the Menu List becomes a help menu. Some look-and-feels right-
justify the help menu.

The Image Dialog Item

The image dialog item is a box dialog item with an image defined as one of its attributes. Figure
53 shows the Dialog Item Panel for an image dialog item. The Set Image Button is enabled;
click this button to open the Image Editor. If the image dialog item was created from the Item
Palette, the Image Editor contains an image of a question mark.
 Dialog Items on the Item Palette 91

File Edit

Tag: Image Mnemonic: X: 71 Y: 68

Title: Image W: 64 H: 58

Enabled Visible Border

Click Focusable Focusable Image Mask

Foreground Set Color... Background Set Color...

Menu Set Menu... Image Set Image...

Font Set Font... Cursor Set Cursor...

ABCDEF

Figure 53. Dialog Item Panel for image item

From the Image Editor you can edit, create, or import images. Image formats supported are GIF,
XBM, PGM, PPM, PBM, ICO, DIB, and BMP. (Run-length encoded DIB formats are not
supported.) For more information on the Image Editor, see Chapter 10, “Images” on page 115.
When the image dialog item is created from the Item Palette, it is a naturally-sized item; its size
is determined by the size of its image.

NOTE: The image dialog item should not be confused with an image item. An image item
is a typed resource that is an actual image. An image dialog item is a subclassed
resource that has an image item defined as one of its attributes.

The Adept List Item and Adept Outline

An Adept List Item is a dialog item that visually represents a one-dimensional data structure.
List items are usually used as single-column lists of character strings.
An Adept Outline Item is a special kind of Adept List Item. While list items display “flat-file”
information, outlines display hierarchical information. Users can click on the outline to expand
or contract the entries displayed in the list. Outlines also support the use of graphical icons at
the beginning of each line. You must use ACL calls to specify the values of these icons. An
example of a populated Adept Outline Item appears in Figure 54.

Figure 54. Sample Outline List

92 Chapter 7 Dialog Items

Use the List Editor to define the appearance and behavior of a list item. You must use ACL calls
to specify the value of cells in a list.
The List Editor contains four panels:
• Dialog Item
• List View
• String List
• List Item

List View Panel

Each list item contains a list view that defines the appearance of the list. Use the List View
Panel, shown in Figure 55, to specify various features of the list view. Table 12 describes the
features of the List View Panel.

File Edit Panels

Scroll Bars Show Grid

Horizontal Horizontal

Vertical Vertical

Options
Auto-Scroll Keyboard Selection

Traverse Wrap Keyboard Traversal

Rearrangeable: None Rows Columns

Figure 55. List View Panel

Table 12. List View Panel features

Feature/Item Description
Scroll Bars
Horizontal Places a horizontal scroll bar into the list view.
Vertical Places a vertical scroll bar into the list view.
Show Grid
Horizontal Draws a line between each row in the list.
Vertical Draws a line between each column in the list.
ADEPT does not support List Items with multiple columns.
Options
Auto-Scroll Enables scrolling for a list item. A user scrolls through a list by dragging the pointer to
the edge of a list view. If Auto-Scroll is disabled, the user cannot use the pointer to
scroll to items beyond the border of a list view.
Traverse Wrap Enables the user to travel backward and forward from one end of the list to the other. If
Traverse Wrap is disabled, the user cannot move beyond an end of the list.
Keyboard Selection Enables the user to select highlighted items in the list by pressing Return.
Keyboard Traversal Enables a user to travel through a list by using the arrow keys of the keyboard.
Rearrangeable
None Disables rearranging of rows and columns of a list.
 Dialog Items on the Item Palette 93

Table 12. List View Panel features

Feature/Item Description
Rows Enables the user to select and drag rows to new positions in the list.
Columns Enables the user to select and drag columns to new positions in the list.
ADEPT does not support List Items with multiple columns.

List Item Panel

Use the List Item Panel, shown in Figure 56, to further define the appearance of a list and to
specify a selection method for the list.

File Edit Panels

Natural Number of Rows: 0

Auto-Calculate Column Widths

At Least One Selection

Selection Method: None Only One
Free Rectangular

Figure 56. List Item Panel

Use the Natural Number of Rows and Auto-Calculate Widths options to determine the size of
natural-sized list items. (By default, list items are not natural-sized. To make a list item natural-
sized, edit its inside connections. See Chapter 6, “Dialogs” on page 51 for details on editing the
inside connections of a dialog item.)
The Natural Number of Rows is the number of rows used to calculate the natural height of a
list item. A natural-sized list item displays the number of rows entered here. A value of zero
means all the rows are used to calculate the natural height.
The default width of a column in a list is equal to the width of the list item. Selecting Auto-
Calculate Widths overrides this default size. When this option is selected, the width of a
column is determined by the greater of these two values:
• Width of the largest item in a list
• Width of the list item
The default height of a row in a string list is determined by the size of the font used in the list.
You cannot override the default height in the List Editor.
Use the Selection Method radio buttons to specify a selection method for a list. Four selection
methods are available:
• None No cell from a list can be chosen.
• Only One No more than one cell can be selected at any time.
• Free Any cell, or combination of cells, can be selected at any time.
• Rectangular The selection always forms a rectangle of contiguous cells.
94 Chapter 7 Dialog Items

Select the At Least One Selection check box if you want at least one item in the list to be
selected at all times.

String List Panel

The settings on the String List Panel are not supported in ACL Designer dialogs for use with
ADEPT.

Dialog Items from the New Item Menu

The Adept Popdown Combobox Item

The Adept Popdown Combobox contains a list of text strings representing possible selections
to a user. It also contains a text field representing the current selection from the list. There are
two types of combination boxes, the combo box and the popdown combo.
The combo box displays the list of text strings on the screen. The user makes a selection by
clicking an item in the list, or by typing a selection in the entry field under the list. As the user
is typing in the entry field, the list automatically scrolls to the closest matching item in the list.
Selections are enabled when the user presses Enter or changes the focus.
The popdown combo is similar to the combo box, except the list is not always visible. The user
displays the list for the popdown combo in a look-and-feel defined manner.
The Combo Box Editor and the Popdown Combo Editor are essentially the same. They each
contain two panels:
• Dialog Item Panel
• Combo Panel
Use the Combo Panel, shown in Figure 57, to define the behavior of the Combo Box and place
items into the list.

File Edit Panels Combo

Modifiable

New String0
New String1
New String2

Text: New String2

Figure 57. Combo Panel

Use the New command from the Combo Menu to insert new text items into a Combo Box’s list.
The first item, by default, is named New String0. Additional items are consecutively
numbered. For example, the next two items would be named New String1 and New
String2. Use the Text field to edit selected items from the list.
 Dialog Items from the New Item Menu 95

If the list of items is too large to be completely displayed in the Combo Box, scroll bars appear.
You can change the size of the list by resizing the Combo Box; edit the W and H coordinates in
the Dialog Item Panel or drag a corner of the Combo Box in the Dialog Panel to resize the
Combo Box.
Normally, the text field of a combo box is modifiable; the user can make a selection from the
list by typing an entry in the text field. Unselect the Modifiable check box in the Combo Panel
to make the text field a static text field. Now the text field displays the current selection, but
cannot be used to make selections from the list. The user must make a selection by clicking an
item in the scrolling list of the combo box.

The Container and Adept Toolbar Items

A container is a dialog item that holds other dialog items. The Adept Toolbar item is a special
container designed to be used as a toolbar. They both share the same configuration options. Both
items are used to group dialog items that behave as a unit. The spring solution for dialog items
in a container is calculated relative to the edges of the container. Dialog items placed in a
container cannot be edited directly from the Dialog Editor; they must be edited from the
Container Editor.
The Container Editor is based on the Dialog Editor. For details on using the Container Editor,
see similar features described for the Dialog Editor in Chapter 6, “Dialogs” on page 51.
The Container Panel, shown in Figure 58, is similar to the Dialog Panel of a Dialog Editor.
Dialog items are placed in a container from the Item Palette, or from the Container/New Items
menu. Edit items in a Container Panel just as you would in a Dialog Panel.

File Edit Panels Container Arrange Connection Windows

Figure 58. Container Panel

96 Chapter 7 Dialog Items

The Container Editor has an Order Items Panel, shown in Figure 59. This panel is similar to the
Order Items Panel of a Dialog Editor.

File Edit Panels Item

Class Tag Title

Figure 59. Order Items Panel of the Container Editor

The Dialog Item Panel of the Container Editor, shown in Figure 60, defines the appearance of
a container in a dialog. (Since dialogs are subclassed from windows, a Dialog Editor defines its
appearance with a Window Panel.)

File Edit Panels

Tag: Container Mnemonic: X: 91 Y: 58

Title: W: 100 H: 100

Enabled Visible Border

Click Focusable Focusable Image Mask

Foreground Set Color... Background Set Color...

Menu Set Menu... Image Set Image...

Font Set Font... Cursor Set Cursor...

ABCDEF

Figure 60. Dialog Item Panel of the Container Editor

 Dialog Items from the New Item Menu 97

Use the Container Attributes Panel, shown in Figure 61, to define scroll bars for a container
and define keyboard traversal behavior.

File Edit Panels

Horizontal Scroll Bar Flat Keyboard Traversal

Vertical Scroll Bar

Figure 61. Container Attributes Panel

To define the keyboard traversal or “tabbing” behavior of a container use the Flat Check Box.
If this option is enabled, a user can “tab through” any items in the container to other dialog items
in the dialog. If this option is not selected, a user can tab into the container, but not out.

NOTE: Containers are usually created in a Dialog Editor. Dialog items placed in the Dialog
Panel are selected and placed in a container with the Place in Container menu
commands from the Edit Menu. For more information on the Place in Container
commands, “Placing Items in Containers” on page 59.

The Grouped Container and Exclusive Group Items

The grouped container and the exclusive group container are both special cases of the
container item. Grouped and exclusive group containers can only contain toggle items. In a
grouped container, any number of the toggle items can be enabled at the same time. In an
exclusive group container, only one toggle item can be enabled at any time.
The Grouped Container Panel, shown in Figure 62, is based on the Exclusive Group Container
Panel. An exclusive group created from the New Item Menu is the same exclusive group item
created from the Item Palette. The difference is that when created from the New Item Menu, the
group does not initially contain any toggle items. Also, when new items are added to the group,
there is no spring solution defined to automatically arrange the items. Use the Edit As
Container option to create a Container Panel for the editor. You can define a spring solution for
the items using the Container Panel.
For details on exclusive group items and using the Grouped Container Panel, refer to “The
Adept Radio Group Item” on page 82.
98 Chapter 7 Dialog Items

File Edit Panels Container

Items:

Layout: Auto-Arrange Flat Keyboard Traversal

Edit As Container Item Selected

Figure 62. Grouped Container Panel

The Line Item

Use the line item to place a horizontal or vertical line into a dialog. The line item is often used
to visually group together items in a dialog that are otherwise unrelated. The line item has one
panel, the Dialog Item Panel. However, editing of a line item is usually done in the Dialog Panel
of the Dialog Editor. Figure 63 shows a Dialog Panel containing a line item.

File Edit Panels Dialog Arrange Connection Windows

Figure 63. The line item inside a Dialog Panel

The line item is a generic dialog item with a line drawn on one side. Resize the line item by
dragging a corner of the item to a new position in the Dialog Panel. The size of the line changes
as you drag it. When the width of the line exceeds its height the line is drawn horizontally;
otherwise the line is drawn vertically.
You can also change the orientation of the line by editing its inside connections. Change the
horizontal inside connection to a natural-sized strut to make the line vertical; change the vertical
inside connection to make the line horizontal. For details on editing an item’s connections, see
“Working with Connections” on page 65.
 Dialog Items from the New Item Menu 99

The Adept Spinner Item

An Adept spinner is a control item that allows a user to select a value from a defined range. The
user can scroll through all possible values one at a time, but can never view the entire range at
once. The user makes a selection by first scrolling to the desired value or typing the value in an
entry field. Pressing Enter or changing the focus then selects the current value of the spin box.
There are two types of spin boxes: numeric spinners and text spinners.

NOTE: Spin boxes are commonly used to prompt the user for frequently used information,
such as the day of the week. If you need to display the options available to a user,
consider using the combination box described on page 94.

Spinners, (sometimes called numeric spinners), accept only integer values from the user. Any
value in the defined range is allowed. If the user enters a value outside the range, the value of
the spinner resets to the closest legal value. The increment for a spinner can be changed to allow
the user to quickly scroll through a large range.
In the Control Panel for a spinner, displayed in Figure 64, Min and Max define the range for the
spinner. Increment defines the amount to change the value of the spinner during a scroll
operation. Value is the default value of the spinner, and is displayed when the spinner opens. For
more on the Control Panel and control items see “Control Dialog Items” on page 83.

File Edit Panels

Min: 0 Page: 1

Max: 1 Increment: 1

Value: 0

Vertical Exclusive Alternate Style

Figure 64. Control Panel for a spinner

The Spinner Panel, displayed in Figure 65, defines the modifiable and wrap properties of a
spinner. Normally, the entry field of a spinner is modifiable; the user can make a selection by
typing a numeric value in the entry field. Unselect the Modifiable check box in the Spinner
Panel to make the entry field static. Now the entry field displays the current selection, but cannot
be used to make further selections. The user must make a selection by scrolling through the
values of the spinner.
100 Chapter 7 Dialog Items

File Edit Panels

Modifiable

Wrap

Figure 65. Spinner Panel

Text spinners correlate the numeric value of the spinner with a sorted list of strings. The user
can scroll through the strings, one at a time, or enter the desired string in the text entry field.
Automatic name completion is available for text spinners. After typing a partial entry, change
the focus or press Enter. The text spinner scrolls to the first entry that begins with that partial
string. Any additional entries that begin with the partial string can be found by scrolling past the
first entry.
The Spinner Editor contains two panels:
• Dialog Item
• Text Spinner
In the Text Spinner Panel, shown in Figure 66, use the New Entry command from the Spinner
Menu to insert new strings into a text spinner. The strings are entered in alphabetic order. The
first item, by default, is named New String0. Additional items are consecutively numbered.
For example, the next two items would be named New String1 and New String2. Use
the Text field to edit selected strings from the list of strings.

File Edit Panels Spinner

Modifiable Wrap

Text:

Figure 66. Text Spinner Panel

 Dialog Items from the New Item Menu 101

Normally, the text field of a text spinner is modifiable; the user can make a selection from the
list by typing an entry in the text field. Unselect the Modifiable check box in the Text Spinner
Panel to make the text field a static text field. Now the text field displays the current selection,
but cannot be used to make selections from the list. The user must make a selection by scrolling
through the values of the text spinner.
If the Wrap option is enabled, the user can scroll backward and forward from one end of the
list to the other. Otherwise, the user can only scroll to the ends of the list.

The Adept Notebook, Page, and Section items

The Adept Notebook item resembles a physical notebook in appearance and performance. It
contains one or more Pages (the Page item) each of which contains dialog items that the user
can view or edit. Only one page (the active page) is visible at a time. The remaining pages are
“stacked” behind the active page.
Pages in a notebook can be grouped into sections (the Section item). A section in a notebook is
similar ot a page, except its contents are pages or other sections. The contents of a section ar
only visible when the user steps to that section.
Each page and section has an associated tab which can be graphically displayed with the
notebook. The tab, which corresponds to an index tab in a physical notebook, allows the user to
“step” to pages athat are not currently visible.
By using pages and sections to group related items, large amounts of data can be presented to
the user in a simple framework that does not sacrifice screen real estate. A sample notebook
appears in the samples/form/form.vr resource file that ships with ACL Designer. the
samples directory resides within your ACL Designer installation directory.
The Adept Notebook editor contains two panels:
• Dialog panel
• Notebook panel
The Dialog panel is described at the beginning of this chapter. Refer to the table below for the
features of the Notebook panel.

Table 13. Notebook Panel features

Feature/Item Description
Custom Styles
Major Tab Side Controls location of top level tabs (Pages and Sections).
Minor Tab Side Controls location of second level tabs (Pages).
Tabs Controls the visual appearance of the tabs.
Folio Places “Page 1 of X” label at the bottom edge of the notebook.
Folio Placement Controls where the Folio label appears.
Page Buttons Places scroll buttons for changing pages at the lower right corner of the notebook.
Pages Wrap If on, user can scroll directly from the last page to the first page.
Page Borders If on, a border appears around the page inside the notebook.
Tab Style Controls the outer profile of the tabs (Rectangular, Rounded, Beveled).
Vertical Tabs For tabs at the sides of the notebook; controls whether the tabs are level or rotated 90
degrees.
Page Count Controls the number of virtual notebook pages displayed.
Page Step Number of pixels between virtual notebook pages.
Page Inset Controls how close pages are to the edge of the notebook.
102 Chapter 7 Dialog Items

Table 13. Notebook Panel features

Feature/Item Description
Page Inset Border Controls the inset of the Page Borders (if enabled).
Tab Buttons Centered Controls whether tab buttons are centered with respect to the notebook.
Tab Buttons Placement Controls visual placement of tab buttons.
Allow Partial Tabs If on, allows background tabs to overlap.

The Notebook Pages section of the Notebook Panel lists the Sections and Pages you’ve added
to the table (in order). Use the Notebook menu items to add Pages and Sections to your
notebook. To change the order of the menu items, use the center mouse button (three-button
mouse) or both mouse buttons (two button mouse) to drag the Pages/Sections into different
locations.
Sections appear in the list as single items. To edit the pages within a section, double-click on the
desired section entry.
The following items are available from the Notebook menu:
• Edit - Displays the Page/Section panel for the currently selected Page/Section. You can
also display the Page/Section panel by double-clicking on the desired Page/Section entry
in the Notebook Pages list.
• Edit Tab... - By default, the Title field in a Page’s/Sections’s Dialog Panel determines the
name on the tab. If you want a different name, you can display a separate Dialog Item panel
for the tab corresponding to the currently selected page/section. On the tab’s Dialog Item
panel, you can change the font and name that displays on the tab.
• New Page - Adds a new page to the list on the Notebook Panel.
• New Section - Adds a new section to the list on the Notebook Panel.
• Current Page - Sets the currently selected page as the default page in the notebook.
CHAPTER
8
Windows and Other Resources

Overview of Windows
A window is a rectangular display area with various attributes that define its appearance and
behavior. A window by itself is not often used in an application, but it forms the basis for
subclassing other commonly used resources. For details on subclassing resource see “Creating
Subclassed Resources” on page 48.
Editors for the following resources, all subclassed from windows, are opened from a Dictionary
Editor:
• Dialog
• Menu
• Confirm
• Notice
The Dialog Editor is discussed in detail in Chapter 6, “Dialogs” on page 51. The Menu Editor
is covered in Chapter 9, “Menus” on page 109. This chapter discusses the Window, Confirm,
and Notice Editors.

The Window Resource

The Window Editor contains only one panel, the Window Panel. Use the Window Panel, shown
in Figure 67, to set the attributes of a window, define its tag and title names, and specify its size
and placement.

103
104 Chapter 8 Windows and Other Resources

File Edit

Tag: X: 100 Y: 100

Title: W: 100 H: 100

Custom

Foreground Set Color... Cursor Set Cursor...

Background Set Color... Icon Set Icon...

Font Set Font... Menu Set Menu...

Attributes
Border Maximizable Iconifiable Movable

Modal Pinnable Resizable

ABCDEF

Figure 67. Window Panel

The tag name of a window is the name an application uses to access the window after the
resource file is loaded into memory. The title of a window is displayed in its title bar.

You can define the appearance of a window by activating the choosers and editors associated
with a series of check boxes in the Custom group of the Window Panel. Table 14 lists the
choosers and editors available. Selecting one of these check boxes enables the button associated
with it. Select the button to activate the chooser or editor associated with that button.

Table 14. Dialog item attributes

Attribute Chooser or Editor

Foreground Color Color Chooser
Background Color Color Chooser
Font Font Chooser
Cursor Cursor Editor
Icon Image Editor

To set the foreground or background color for a window:

1. Select the Foreground or Background check box.
The Set Color button is enabled.
2. Click Set Color.
The Color Chooser is displayed. In the Color Chooser, you can select colors from one
of four color models (HLS, RGB, CMY, and Grayscale). Dragging and dropping of
colors is available from the Color Chooser. For more information on the Color
Chooser, see Chapter 12, “The Color Chooser” on page 131.
 The Confirm Dialog 105

To select a font for a window:

1. Select the Font check box.
The Set Font button is enabled.
2. Click Set Font.
The Font Chooser appears.
3. Select the type family, typeface, and size you want.
Your selection appears in the Font Display Field. Dragging and dropping of fonts is
available from the Font Chooser. For more information on the Font Chooser, see
Chapter 11, “The Font Chooser” on page 129.

To create a cursor for a window:

1. Select the Cursor check box.
The Set Cursor button is enabled.
2. Click Set Cursor.
The Cursor Editor, a variation of the Image Editor, is displayed. With the Image Editor,
you can create a custom cursor for a window. For information on creating cursors, see
“The Cursor Editor” on page 127.

To create an icon for a window:

1. Select the Icon check box.
The Set Icon button is enabled.
2. Click Set Icon.
The Image Editor is displayed. Use the Image Editor to create, import, edit, or export
images. Image formats supported are GIF, XBM, PGM, PPM, PBM, ICO, DIB, and
BMP. (Run-length encoded DIB formats are not supported.) For information on the
Image Editor, see Chapter 10, “Images” on page 115.
A window has a series of attributes that define its behavior and appearance in an application.
These attributes, listed in Table 15, are enabled with a series of check boxes in the Attribute
group of the Window Panel. The behavior of these attributes is look-and-feel dependent.

Table 15. Window Panel attributes

Attribute If selected
Border The window is outlined with a border.
Movable The window can be moved on the display by dragging it with a mouse.
Resizable The window can be resized by the user.
Modal The window is the only active window in the application. A user must respond to or perform
some action in this window to change the focus.
Pinnable Depending on the look-and-feel, enables pinning a window on the display.
Iconifiable The window can be minimized to an icon on a display.
Maximizable The window can be expanded to fill a display screen.

The Confirm Dialog

The confirm dialog enables a user to confirm a specific action before an application continues
to execute. Various confirmation buttons are used to define the available actions for the user in
a confirm dialog. The action, behavior, and existence of these buttons vary, depending on look-
and-feel.
106 Chapter 8 Windows and Other Resources

The confirm dialog is subclassed from a dialog. The Confirm Editor contains the following
panels:
• Window
• Confirm Attributes
• Order Items
• Confirm
The Window Panel, Order Items Panel, and Confirm panels are similar to corresponding panels
in the Dialog Editor. Use the Confirm Panel to place additional dialog items into a confirm
dialog. By adding additional dialog items, you can create a confirmation dialog with added
functionality. For more information on using the Window, Order Item, and Confirm Panels, see
Chapter 6, “Dialogs” on page 51.

Use the Confirm Attributes Panel, shown in Figure 68, to define, name, and edit the various
buttons in a confirm dialog.

File Edit Panels Confirm

Buttons:
Ok
Cancel
Reset
Defaults
Apply
Help

Override Standard Titles Buttons Vertical

Figure 68. Confirm Attributes Panel

The confirm dialog, by default, includes the required buttons for the current look-and-feel. The
OK and Cancel buttons are required under all look-and-feels except OPEN LOOK. The Apply
button is required under OPEN LOOK and is optional for other look-and-feels. The OK and
Cancel buttons close the confirm dialog after notifying the application of the action taken. The
behavior of the Apply button is look-and-feel dependent.
The Reset and Defaults buttons are optional under all look-and-feels; their behavior is look-and-
feel dependent. The Help button is an optional button that activates the help system defined for
your application. To add an optional button to a confirm dialog, select the check box for the
optional button.
Some look-and-feels require standard titles for confirmation buttons. However, you can
override the standard titles and create new titles for the buttons using the Override Standard
Titles option in the Confirm Attributes Panel. If you change the title of a button and select the
Override Standard Titles option, the title is changed even if the title violates a look-and-feel
standard. If you change the title, but don’t select the Override Standard option, the title is
changed only when allowed by the look-and-feel.
 The Notice Dialog 107

To override a standard title for a button:

1. In the Confirm Attributes Panel, select the Override Standard Titles check box.
(Only select this option if you want to change the title even if the new title violates a
look-and-feel standard.)
2. Select the button with the title you want to change. If the button is enabled with a check
box, be sure to select the check box.
3. From the Confirm Menu, select Edit Button. You can also double-click the button you
want to edit.
The Dialog Item Editor for a button item opens.
4. Enter the new title in the Title text field.
The title of the button is changed. Use the Confirm/Try Dialog option in the Confirm
Panel to see the changes.

In the Confirm Attributes Panel, you can add new confirmation buttons to a confirm dialog,
open a dialog item panel to further edit a confirmation button, and specify vertical arrangement
for the buttons.

To add a new confirmation button to a confirm dialog:

1. In the Confirm Attributes Panel, select New Button from the Confirm Menu.
A confirmation button named “New Button” is added to the list of buttons in the
Confirm Attributes Panel.

To edit a confirmation button:

1. In the Confirm Attributes Panel, select the button you want to edit. If the button is
enabled with a check box, be sure to select the check box.
2. From the Confirm Menu, select Edit Button. You can also double-click the button you
want to edit.
The Dialog Item Editor for a button item opens.
3. Edit any attribute for the button that is not look-and-feel defined.
Use the Confirm/Try Dialog option in the Confirm Panel to see any newly defined
attribute.
NOTE: When editing confirmation buttons in the Dialog Item Panel, certain
properties are defined by the look-and-feel and cannot be changed. For
example, any changes to the size or placement of a confirmation button is
ignored. However, you can specify fonts, colors, and other attributes for the
buttons in the Dialog Item Panel.

To specify vertical arrangement of buttons:

1. In the Confirm Attributes Panel, select the Buttons Vertical check box.
Use the Confirm/Try Dialog option in the Confirm Panel to see the vertical placement
of buttons.

The Notice Dialog

The notice dialog communicates information to a user, usually to inform the user of an error or
some irrevocable action that has been initiated. By default, notice dialogs are modal; the user
must respond to the notice before proceeding in an application. Notices are displayed according
to the standards of the current look-and-feel.
108 Chapter 8 Windows and Other Resources

There are two types of notices available to applications. The warning notice is typically used to
display information. The warning notice contains the following:
• Text for the notice
• OK button
• Cancel button (optional)

The caution notice is used when the user has a choice of actions or can cancel the current
operation. The caution notice contains the following:
• Text for the notice
• Yes button
• No button
• Cancel button (optional)
The notice dialog contains two panels, the Window Panel and the Notice Panel. Use the Window
Panel to set the attributes for the notice dialog. See “The Window Resource” on page 103 for
details on using the Window Panel. The Notice Panel, shown in Figure 69, is used to define the
type of notice and to enter text for it.

File Edit Panels Notice

Notice type:

Caution Cancel Button

Warning

Text:

Static Text Field

Figure 69. Notice Panel

Table 16 lists the features of the Notice Panel.

Table 16. Notice Panel features

Feature Description
Notice type
Caution Creates a caution notice. A caution notice contains a Yes button and a
No button.
Warning Creates a warning notice. A warning notice contains an OK button.
Cancel Button Adds a Cancel button to the notice.
Text Contains a static text field. Text in this field is displayed in the notice.

After creating a notice, use the Try Out option in the Notice Menu to test the Notice.
CHAPTER
9
Menus

Overview of Menus
Menus provide a way for users to issue commands in an application. Each command in a menu
is represented on the menu as a menu item.
Menus are usually built upon a menu bar, a dialog item with an ordered list of menus. However,
a pop-up menu can be associated with any dialog item. (A pop-up menu is opened with the
menu button of the mouse.) The option menu is a specially defined pop-up menu that provides
a convenient way to place a menu within a dialog. See Chapter 6, “Dialogs” on page 51 for
details on the menu bar, pop-up menu, and option menu.

NOTE: The Menu Editor creates menus for the custom dialogs you wish to use with ADEPT.
The Menu Editor does not affect the pull-down menus in the ADEPT edit window.
There are ADEPT Command Language (ACL) commands to manipulate the pull-
down menus in the ADEPT edit window.

The Menu Editor contains the following two panels:

• Window Panel
• Menu Panel

The Window Panel

Menus are subclassed from a window, and contain a Window Panel to define the window
attributes of a menu. Figure 70 shows the Window Panel of the Menu Editor.

109
110 Chapter 9 Menus

File Edit Panels

Tag: X: 100 Y: 100

Title: W: 100 H: 100

Custom

Foreground Set Color... Cursor Set Cursor...

Background Set Color... Icon Set Icon...

Font Set Font... Menu Set Menu...

Attributes
Border Maximizable Iconifiable Movable

Modal Pinnable Resizable

ABCDEF

Figure 70. Window Panel of the Menu Editor

In the Window Panel, you can open the available editors and choosers to define the appearance
of the menu. You can also define the tag and title name for the menu in the Window Panel,
although this is usually done in the Menu Panel. Certain features of the Window Panel are
disabled. (Attributes such as modal and resizable do not normally apply to menus.) For more
information on using the Window Panel, see Chapter 8, “Windows and Other Resources” on
page 103.

The Menu Panel

Use the Menu Panel, shown in Figure 71, to name a menu, create and define menu items for a
menu, define the behavior of a menu, and test a menu.

File Edit Panels Menu

Title Display Field File

Menu
Open
Menu Item List Title: File
Close
Save Tag: FileMenu
Mnemonic: F
Pinnable Disabled

Item
Title: Open
Tag:

Key:

Mnemonic: O

Disabled Default On

Figure 71. Menu Panel

 Menus 111

Menus
Use the Menu group of the Menu Panel to assign attributes for a menu. Table 17 lists the
attributes you can define in the Menu group.

Table 17. Menu group features

Attribute Description
Title Defines a name for the menu. The title specified here is displayed in the Title Display Field of the
Menu Item List. The name also appears when testing the menu.
Tag Defines a tag name for the menu. The tag name of a menu is the name an application uses to access
the menu after a resource file is loaded into memory.
Mnemonic Defines a mnemonic key a user can use to open the menu. This is a one-character field. The character
entered must match a character in the title name. All mnemonic keys for menus in a menu list must
be unique. See page 112 for more on mnemonic keys.
Pinnable Defines the menu as pinnable. A user can place a pinnable menu on the display to keep it open.
Disabled Defines a menu as disabled. Disabled menus appear dimmed.

Menu Items
Use the Menu Menu of the Menu Panel to add menu items to a menu, remove accelerator keys
defined for a menu item, and try out a menu. Figure 72 shows the Menu Menu.

Try Out Menu Ctrl+T

Remove Accelerator

New Menu Item Ctrl+N

New Separator Item
New Check Item
New Group Item
New Submenu Item

Figure 72. Menu Menu

To add a menu item to a menu:

1. From the Menu Menu, select one of the following options:
• New Menu Item to create a menu item in the Menu Item List.
• New Separator Item to create a separator item in the Menu Item List. This is
useful for setting off or separating logical groups of items in a menu. When a
separator item is created, the disabled check box is selected in the Item group.
• New Check Item to create a check menu item in the Menu Item List. The menu
item is preceded by a check box. A user enables or disables a menu option with
this check box.
• New Group Item to create a group menu item in the Menu Item List. The menu
item is preceded by a radio button. Select the Group Item option multiple times to
create an exclusive group of menu items. Exclusive groups function as a set of
mutually exclusive items; a user can select only one item from an exclusive group
112 Chapter 9 Menus

at a time.
• New Submenu Item to create a submenu item in the Menu Item List. The menu
item is displayed with an arrow, indicating to a user that further menu options are
available. Double-click on the submenu item to open another Menu Editor. Define
the options for the submenu with the newly opened Menu Editor.

When a menu item is created, the Item group of the Menu Panel is enabled. Use the Item group
to assign attributes to menu items. Table 18 lists the features of the Menu Item group.

Table 18. Menu Item group features

Feature Description
Title Defines a name for the menu item. By default, new menu items are named “New.” Use this text field
to edit the name of a menu item.
Tag Defines a tag name for the menu item. The tag name of a menu item is the name an application uses
to access the menu item after a resource file is loaded into memory.
Key Defines an accelerator key for the menu item. In the Key field, type the key sequence you want to use
as an accelerator in the menu (for example, Ctrl+K, or ^K). In the Menu Panel, the Menu Menu has a
Remove Accelerator command that removes an accelerator key assigned to a menu item. Accelerator
keys must be unique among all menu options available.
Mnemonic Defines a mnemonic key a user can use to select the menu item from the keyboard. This is a one
character field. The character entered must match a character in the title name. All mnemonic keys
defined for menu items in a set of menus must be unique. See below for more on mnemonic keys.
Disabled Defines a menu item as disabled. Disabled menu items appear dimmed.
Default Defines the default selection for a menu. Only one menu item in a menu can be marked as the
default.
On Defines a check menu item or a group menu item as selected. The menu item appears selected when
a user opens the menu. (This feature is only available for the check and group menu items.)

Mnemonic Keys
Use the Mnemonic fields in the Menu and Item Groups to specify a mnemonic key for a menu
or a menu item. A mnemonic key allows the user to open a menu or invoke a menu command
by pressing the specified key in combination with the mnemonic key modifier from the
keyboard. (The mnemonic key modifier is platform dependent but is usually the Alt key. ) Only
one alphanumeric character can be specified as the mnemonic key. If the specified key is in the
title of the menu or menu item, the corresponding letter is underlined on the display.
It is up to the application developer to provide unique mnemonic key definitions to menus in a
menu list and menu items on a menu. Additionally, the mnemonic keys for menus on a menu
bar must be unique with respect to all mnemonic keys defined for dialog items in the dialog
containing the menu bar.

NOTE: The user does not specify the case of a mnemonic key when making a selection from
the keyboard. This means the upper case and lower case version of a character are
not unique mnemonic key specifications.

To specify a mnemonic character for a menu or menu item:

1. Select the Mnemonic field and type a single character for the mnemonic key.
If the specified character is in the title of the menu or menu item, it is underlined.
 The Menu Item List 113

The Menu Item List

To rearrange items in the Menu Items List, drag and drop the items to new positions in the list.
Use the Edit Menu of the Menu Panel to copy or remove items from the list. Menu items can be
copied or moved to the same or other menus. Also from the Edit Menu you can specify the font
and foreground color for items in the Menu Item List.

To rearrange menu items in the Menu Item List:

1. Select the menu item you want to reposition.
2. Drag and drop the item to the desired position in the Menu Item List.
The Menu Item List reflects the new position of the menu items.

To delete a menu item from the Menu Item List:

1. Select the menu item you want to delete from the Menu Item List.
2. Select Clear or Cut from the Edit Menu of the Menu Panel.
The menu item is removed from the Menu Item List. If you selected Cut, the menu item
can be placed in another Menu with the Paste command.
NOTE: When a menu item is “pasted” into another menu, it is placed as the last
item in the Menu Item List. The position of the menu item can then be
changed with a drag and drop operation. For more information on using the
editing commands from the Edit Menu, see section “Using the Edit Menu”
on page 36.

Testing a Menu
In the Menu Panel you can view and test a menu as you create it.

To test a menu:
1. Select Try Out Menu from the Menu Menu.
A version of your menu appears on the menu bar of the Menu Panel.
2. Select your menu from the menu bar of the Menu Panel.
The features you have defined for your menu are visible. Your menu remains on the
menu bar until you select Try Out Menu again. You can make changes to your menu
while the Try Out Menu option is enabled; changes you make appear in your menu.
NOTE: You can also test your menu with the Try Dialog feature available from the
Windows Menu in the Dialog Panel. For more information, see section
“Testing Your Dialog” on page 64.
114 Chapter 9 Menus
CHAPTER
10
Images

The Image Editor

Use the Image Editor to create, import, modify, and export images. Images can be associated
with any dialog item and are an integral part of items such as the image item, the icon view item,
and the cursor item. Figure 73 shows the Image Editor.

File Edit Image View Options

Color Palette

Tool Palette

Line Width
Palette

Background Image Editing Area

Color Box Foreground
Color Box

Figure 73. Image Editor

115
116 Chapter 10 Images

Importing and Exporting Images

Use the commands in the View Menu to import and export images. Image formats supported are
GIF, XBM, PGM, PPM, PBM, ICO, DIB, and BMP. (Run-length encoded DIB formats are not
supported.)

To import an image:
1. Select Import... from the Image Menu in the Image Panel.
The File Chooser appears.
2. In the Filters Menu of the File Chooser, select a filter for the image format you are
importing.
The File Chooser lists only directories and files specified by the filter selected.
3. Use the File Chooser to navigate through the file system and select the file name of the
image you want to import.
or
Type the full or relative pathname of the image in the Name field.

4. Click OK in the File Chooser.

The image appears in the Image Editing Area. The size of the Image Editing Area
adjusts to the size of the imported image. Imported images can be edited in the Image
Editor.
NOTE: If the entire image is not visible, select Preview from the View Menu.

To export an image:
1. Select Export... from the Image Menu in the Image Panel.
A File Chooser appears.
2. To specify an image format, select Export in the Export Menu.
The default format is GIF. Select a format from the options available.
3. Type the file name you want for the exported image. Include the path, if necessary.
4. Click OK in the File Chooser.
The image is written to the specified file.

Setting the Size of an Image

Specify the size of an image with the Size Window. If the image is too large to fit in the Image
Editing Area, a cropped area of the oversized image is displayed. Use the scroll bar of the Image
Editing Area to scroll through the image. Figure 74 shows the Size Window.
 Using the View Menu 117

Image Size

Width: 40

Height: 40

OK Cancel

Figure 74. Size Window

To set the size of an image:

1. Select Set Size from the Image Menu of the Image Editor.
A Size Window appears.
2. Type the height and width in the fields provided.
Specify the height and width in pixels.
3. Click OK.
The Size Window closes and the image adjusts to the specified size.

Using the View Menu

Use the View Menu of the Image Editor to change the view of an image in the Image Editing
Area. Figure 75 shows the View Menu.

Fat Bits Ctrl+F

Draw From Center

Show Grid Ctrl+G
Show Position
Preview Ctrl+P

Zoom In Ctrl+Shift+I
Zoom Out Ctrl+Shift+O

Figure 75. View Menu

118 Chapter 10 Images

Table 19 lists the commands of the View Menu.

Table 19. View Menu commands

Command Description
Fat Bits Magnifies the image in the Image Editing Area so each pixel can be viewed. When Fat Bits is
disabled, the image returns to its actual size. (The default magnification is 5 times the size of the
image.)
Draw From Defines the starting point for certain drawing tools. Normally, the line, ellipse, and rectangle tools
Center begin drawing an item from the end (or perimeter) of the item. Draw From Center specifies that
drawing begins at the center of the item.
Show Grid Displays the image in a grid. Individual pixels are outlined with the grid pattern. When the bit size
displayed is smaller than 3 pixels, the grid is not shown.
Show Position Displays the coordinates of an image above the Image Editing Area. The coordinates provide
information on the position, direction, and size of editing operations (refer to Table 8-2 for more
information).
Preview Displays the entire image in a separate Preview Window (see “Viewing an Image” on page 123 for
more information). If you use the Hand Tool to pan through an oversize image in the Image Editing
Area, the area currently in the Image Editing Area is outlined in the Preview Window.
Zoom In Magnifies the image in the Image Editing Area. Select repeatedly to continually increase the
magnification.
Zoom Out Decreases the magnification of the image in the Image Editing Area. Select repeatedly to continually
decrease the magnification.

The Show Position Command

Select the Show Position command from the View Menu to display information about the
position of an image in the Image Editing Area. Table 20 lists the information displayed by the
Show Position command.

Table 20. Specifications for the Show Position command

Specification Description
X: The position of the item on the X axis.*
Y: The position of the item on the Y axis.*
DX: The change in X as you draw or move an item.
DY: The change in Y as you draw or move an item.
Len: The distance between the starting point of the operation and the current position.
Ang: The arc, in degrees, described from the starting point as you draw or move an item.

*The origin of the image is the lower left corner of the image.

Saving the View of an Image

When the Image Editor opens, the Fat Bits option of the View Menu is enabled by default. The
other options in the View Menu are disabled. If you change the view of the editor by selecting
or unselecting options from the View Menu, and then close the editor, changes to the view are
not saved. Reopening the editor returns you to the default settings.
 Creating an Image 119

However, you can use the Save Template command from the File Menu to save the changes to
a view before closing the Image Editor. When the Image Editor subsequently reopens, the
options you previously set are active. The options you can save with the Save Template
command are:
• Bit Size
• Draw From Center
• Show Grid
• Show Position
• Preview

Creating an Image
Images are created and edited in the Image Editing Area with a set of 14 tools from the Tool
Palette. Table 21 lists the tools from the Tool Palette.

Table 21. Tool Palette

Tool Description
Hand Tool Repositions the visible part of the image when an oversize image is in the Image Editing Area. Select
and drag the oversize image with the Hand Tool to reposition the image.
Dropper Tool Picks up the color from a pixel in the image. Click anywhere in the Image Editing Area to pick up a
color. The color you pick up is displayed in the Color Palette and the Foreground Color Box. To pick
up a background color, press the Control key when you click the Dropper Tool.
Selection Tool Selects a rectangular area of an image for editing. Drag the mouse with the Selection Tool to describe
the selected area of the image. To select the entire Image Editing Area, double-click the Selection
Tool in the Tool Palette.
Lasso Tool Selects any area of an image for editing. Drag the mouse with the Lasso Tool to surround the area
you want to select.
Fill Tool Fills any enclosed area of an image with the foreground color. Click an enclosed area of the image
with the Fill Tool to fill the area with the foreground color.
Spray Can Tool Draws the foreground color with a “spray” pattern. Drag the Spray Can Tool across the image to
draw the pattern.
Eraser Tool Replaces the color of an image with the background color. Drag the Eraser Tool over the area you
want to erase. Press the Shift key before erasing to constrain the Eraser Tool horizontally or
vertically. To clear the entire editing area, click in the Image Editing Area, and then double-click the
Eraser Tool in the Tool Palette.
Text Tool Places text into the image. Click in the Image Editing Area with the Text Tool to open an Image Text
Window. Text entered in the Image Text Window appears as a selection in the image.
Pencil Tool Draws or erases one pixel at a time. Click in the Image Editing Area with the Pencil Tool to draw or
erase a pixel. If the area clicked is the foreground color, it becomes the background color. Otherwise,
an area clicked becomes the foreground color. Drag the Pencil Tool to draw a continuous line.
Line Tool Draws straight lines. Drag the Line Tool in the Image Editing Area to draw a straight line. Press the
Shift key during the drag operation to constrain the line horizontally, vertically, or to a 45-degree
angle.
Ellipse Tool Draws an ellipse. Drag the Ellipse Tool in the Image Editing Area to draw an ellipse. Press the Shift
key during the drag operation to constrain the ellipse to a circle.
Filled Ellipse Tool Draws a solid ellipse. Drag the Filled Ellipse Tool in the Image Editing Area to draw a solid ellipse.
Press the Shift key during the drag operation to constrain the ellipse to a circle.
Rectangle Tool Draws a rectangle. Drag the Rectangle Tool in the Image Editing Area to draw a rectangle. Press the
Shift key during the drag operation to constrain the rectangle to a square.
120 Chapter 10 Images

Table 21. Tool Palette

Tool Description
Filled Rectangle Draws a solid rectangle. Drag the Filled Rectangle Tool in the Image Editing Area to draw a solid
Tool rectangle. Press the Shift key during the drag operation to constrain the rectangle to a square.

To use the tools in the Tool Palette:

1. Click the tool you want to use.
The pointer changes to the appropriate cursor for the tool you selected.
2. Move the pointer to the Image Editing Area.
3. Click and/or drag the mouse to make the changes you want.
NOTE: Use the Undo command from the Edit Menu to undo the most recent editing
action. The Redo command restores the most recent Undo action.

Setting Colors for Drawing

The foreground and background colors for drawing are set in various ways. You can set the
drawing colors by using the Foreground and Background Color Boxes, the Color Palette, or the
Dropper Tool.
The Color Palette in the Image Editing Area contains 16 colors readily available to use for
setting colors. These 16 colors represent the most recently used colors from the 256 colors
available from the extended Color Palette. Additional color palettes are available with the Color
Palette Editor. The Color Palette Editor and the extended Color Palette are discussed in “The
Color Palette” on page 124.
The following tools from the Tool Palette are used for drawing:
• Spray Can Tool
• Pencil Tool
• Line Tool
• Ellipse Tools
• Rectangle Tools
 Setting Line Width for Drawing 121

To set the foreground color for drawing:

1. Click on a color in the Color Palette.
The color is displayed in the Foreground Color Box. The foreground color can be set
before or after clicking on a drawing tool.
or
1. Click and hold the Foreground Color Box.
The extended Color Palette is displayed. The current foreground color is indicated in
the palette.
2. Drag the mouse to a color in the extended Color Palette and release the mouse.
The foreground color is set to the color you selected. The color is displayed in the
Foreground Color Box and is added to the Color Palette.
or
1. Select the Dropper Tool from the Tool Palette.
2. Select a color in the image.
The Dropper Tool sets the foreground color to the color of the pixel you selected. The
color is displayed in the Foreground Color Box.

To set the background color for drawing:

1. Press the Control key and click on a color in the Color Palette.
The color is displayed in the Background Color Box. The foreground color can be set
before or after clicking on a drawing tool.
or
1. Click and hold the Background Color Box.
The extended Color Palette is displayed. The current background color is indicated in
the palette.
2. Drag the mouse to a color in the Full Color Palette and release the mouse.
The background color is set to the color you selected. The color is displayed in the
Background Color Box and is added to the Color Palette.
or
1. Select the Dropper Tool from the Tool Palette.
2. Press the Control key and select a color in the image.
The Dropper Tool sets the background color to the color of the pixel you selected. The
color is displayed in the Background Color Box.

Setting Line Width for Drawing

The line width for drawing can be set with the Line Width Palette. Setting the line width applies
to the following drawing tools:
• Line Tool
• Ellipse Tools
• Rectangle Tools
122 Chapter 10 Images

To set the line width for drawing:

1. Select a line width from the line width palette.
The new line width appears selected in the palette.

Using the Selection Tools

Use the Selection Tool and the Lasso Tool to manipulate whole images or parts of images. The
orientation of selected areas can be changed with special editing commands from the Edit Menu
of the Image Editor.

To move (or copy) a selected area:

1. Select an area of an image with the Selection Tool or the Lasso Tool.
The selected area appears in the Image Editing Area.
2. Click and drag the selected area to a new position in the Image Editing Area.
The cursor changes to the Hand Tool. The selected area is moved to a new position.
(Press the Control key before clicking the selected area to perform a copy operation.)
or
2. Use the Cut, Copy, and Paste commands from the Edit Menu of the Image Editor.
Images can be copied across different Image Editors. For more information, see
section “Using the Edit Menu” on page 36.

To change the orientation of a selected area:

1. Use the Selection Tool or Lasso Tool to select an area of the image.
2. From the Edit Menu, select:
Rotate to rotate the selection 90 degrees
Flip Horizontal to mirror the selected area horizontally
Flip Vertical to mirror the selected area vertically
You can crop the entire image to a selected area. The remaining unselected area of the
image is discarded.

To crop the image to a selected area:

1. Use the Selection Tool or Lasso Tool to select an area of the image.
2. Select Crop To Selection from the Edit Menu.
The image now consists of only the cropped area.

Adding Text to an Image

Use the Text Tool to add text to an image. Select the foreground and background colors for text
as you would for a drawing tool. The font and other attributes of the text should be specified
before adding text to an image.
 Viewing an Image 123

To specify the font and attributes of text for an image:

1. Select Choose Font from the Options Menu of the Image Editor.
A Font Chooser appears.
2. Select the font, size, and attributes for the text in your image.
For more information on selecting fonts, see Chapter 11, “The Font Chooser” on page
129.

To add text to an image:

1. Select the Text Tool from the Tool Palette, and click in the Image Editing Area.
An Image Text Window appears. Enter the text for the image. The current foreground
and background colors determine the appearance of the text.
NOTE: While the Text Window is open you can select different foreground and
background colors and change the font.

2. Click OK.
The text appears where you clicked in the Image Editing Area. The text is selected for
a move operation.
3. Move the selected text to position it in the Image Editing Area.

Viewing an Image
Use the Preview Window to observe changes to an image as you make them. You can also use
the Preview Window to select an area of an oversize image for viewing in the Image Edit Area.

To preview an image in the Image Editor:

1. Select Preview from the View Menu in the Image Editor.
The Preview Window opens displaying your image. Changes made in the Image
Editing Area are reflected in the Preview Window.

To select an area of an image for viewing using the Preview Window:

1. If the Preview Window is not open, select Preview from the View Menu in the Image
Editor.
2. Click and hold a mouse button in the Preview Window.
A rectangle appears. The rectangle describes the new area to be viewed in the Image
Editing Area.
3. Drag the rectangle to the position in the image you want to edit. Release the mouse
button.
The rectangle disappears. The Image Editing Area now contains the image area you
want to edit.
124 Chapter 10 Images

To select an area of an image for viewing using the Hand Tool:

1. Select the Hand Tool from the Tool Palette, and move the cursor into the Image
Editing Area.
The cursor changes to a hand.
2. Click and drag the image to a new position.
If the Preview Window is open, a rectangle appears outlining the current portion of the
image in the Image Editing Area.
NOTE: You can also use the scroll bars of the Image Editing Area to scroll an
oversize image.

Using Undo and Erasing

There are various ways to undo changes to an image you are editing. The Eraser Tool is used to
erase large areas of the image, and the Pencil Tool can be used to erase areas pixel by pixel.
Additionally, any number of actions made in the Image Editing Area can be reversed by
repeatedly selecting Undo from the Edit Menu. Select Revert Editor from the File Menu to
restore the Image Editor to the last saved version. To completely clear the Image Editing Area
to the background color, click in the Image Editing Area. Then double-click the Eraser Tool.

The Color Palette

An image created in the Image Editor contains up to 256 colors. These colors are selected from
the Color Palette in the Image Editor. When you open the Image Editor, 16 colors are readily
available in the Color Palette. The Foreground Color Box and the Background Color Box
display the current foreground and background colors.
An extended Color Palette containing up to 256 colors can be opened from the Foreground or
Background Color Box. Use the extended Color Palette to select a new foreground or
background color and add the newly selected color to the Color Palette. See “Setting Colors for
Drawing” on page 120 for more information on setting the foreground and background colors.
With the Color Palette Editor, shown in Figure 76, you can create, modify, or load color palettes.

File Edit Palettes

Number of colors: 256

New Delete

Pick... Ramp

Blend Contrast

Lighter Darker

Warmer Cooler

Remap To Closest Color

Edit Color Palette Cancel Install

Figure 76. Color Palette Editor

 Viewing a Color Palette 125

To open the Color Palette Editor:

1. Select Edit Colors... from the Options Menu in the Image Panel.
The Color Palette Editor opens, displaying the current Color Palette.

Viewing a Color Palette

Color palettes are loaded into the Color Palette Editor from the Palettes Menu. ACL Designer
comes with five palettes available from the Palettes Menu. These palettes can be modified in the
Color Palette Editor and saved as a new Palette. When a new palette is saved it is added to the
Palettes Menu and can be deleted later.
When an image is imported to the Image Editor, the color palette for the image is imported with
it. The imported color palette can be viewed and edited in the Color Palette Editor.
The default palettes in the Color Palette Editor are:
• Rainbow
• Pastels
• Earthtones
• Hues16
• EGA Palette

To load a color palette into the Color Palette Editor:

1. Select Palettes from the Color Palette Editor Menu.
A list of color palettes is displayed in the Palettes Menu.
2. Select the color palette you want to load.
The color palette is displayed in the Color Palette Editor. The number of colors in the
palette is also displayed.

Modifying a Color Palette

Colors or series of colors on a color palette are edited in various ways. A color must be selected
before it can be edited.

To select colors for editing:

1. Click on a color in the Color Palette or drag the mouse over a series of colors.
Selected colors are outlined in the Color Palette.

Selected colors can be edited with a series of options available in the Color Palette Editor. Table
22 lists these options.

Table 22. Color Palette Editor options

Option Description
New Adds a new color to the palette. You can keep adding colors until the grid contains 256 colors.
126 Chapter 10 Images

Table 22. Color Palette Editor options

Option Description
Delete Removes a color or range of colors.
Pick Opens the Color Chooser. Use the Pick option to redefine an individual color on the palette. For more
information on the Color Chooser, see Chapter 12, “The Color Chooser” on page 131.
Ramp Creates a range of colors, from white to black. The first color selected in a series is the middle color
of the ramp.
Blend Modifies a series of colors so that the colors range gradually from the first color in the original series
to the last color in the original series.
Contrast Changes the selected colors to its complement.
Lighter Adds white to the selected color.
Darker Adds black to the selected color.
Warmer Adds red to the selected color.
Cooler Adds blue to the selected color.
Install Adds the displayed color palette to the image.
Cancel Cancels any editing performed and closes the Color Palette Editor.
Remap to Closest Matches the colors of the current palette to the closest colors of a new palette. If you want to
Color minimize changes to an image when installing a new palette use Remap to Closest Color. If Remap
to Closest Color is not enabled, the colors on the newly installed palette are mapped according to
their position on the palette.

Selected colors can also be edited with the Cut, Copy, and Paste commands from the Edit Menu.
Colors can be copied or moved across different Color Palette Editors with these commands.

NOTE: The Undo command from the Edit Menu of the Color Palette Editor can be used to
undo any editing action in the Color Palette Editor. However, only the last editing
action can be undone.

Saving a Color Palette

Modified palettes can be saved under a different name. Palettes you have modified and saved
show up in the Palettes Menu and can later be deleted. You can revert to the last palette selected
for an image with the Revert command.

To save a modified palette or a palette imported with an image:

1. Select Save from the File Menu in the Color Palette Editor.
A text window opens for you to specify a name for the palette. If you do not specify a
name, the first palette is saved as Palette. Successive palettes are consecutively
numbered. For example, the next two palettes saved would be named Palette1 and
Palette2.

To delete a palette:
1. Select Palettes from the Color Palette Editor Menu.
A list of color palettes is displayed in the Palettes Menu. A Delete option is also listed.
2. Select Delete from the Palettes Menu.
A list of modified or imported palettes is displayed.
3. Select the palette you want to delete.
The palette is deleted.
 Creating an Image Transparency 127

To revert to the last selected palette for an image:

1. Select Revert from the File Menu.
A color palette must be installed before it can be used with an image in the Image
Editor.

To install a palette:
1. Select a palette from the Palettes Menu.
2. Modify its contents as needed.
3. Select Remap To Closest Color if you want the values from the two palettes to match
as closely as possible.
NOTE: If you do not remap, colors are reassigned only on the basis of their relative
position in the color palette grid.

Creating an Image Transparency

A transparency for an image can be created in the Image Editor. A transparency is a mask of an
image. The areas of a transparency that are not white are masked out in the image. The rest of
the transparency is clear.

To create a transparency for an image:

1. Select Create Transparency from the Options Menu.
A Transparency Editing Area appears.
2. Using the Selection Tools, select the area of the original image in the Image Editing
Area you want to mask.
Double-click the Selection Tool to select the entire image.
3. Select Mask Selection from the Edit Menu.
A mask is created for the selected area, and displayed in the Transparency Editing
Area. This mask is a starting point for creating a final mask. Any area of your image
containing the background color is masked out.
4. Use any of the drawing tools to edit the transparency, if necessary.
When editing a transparency, the foreground color is always set to black and the
background color to white.

To remove a transparency:
1. Select Delete Transparency from the Options Menu.

The Cursor Editor

The Cursor Editor, a version of the Image Editor, is used to create cursors for dialog items.
Figure 77 shows the Cursor Editor.
128 Chapter 10 Images

File Edit Cursor View Options

Figure 77. Cursor Editor

The cursor is drawn in the Image Editing Area on the left. Use the center editing area to define
the hot spot for your cursor. The hot spot for a cursor is represented as a specially colored bit in
the Hot Spot Editing Area. Use the editing area on the right to create a mask for the cursor. A
mask must be specified to make a cursor visible in an application.
The default image size for a cursor is 16 pixels by 16 pixels. Adjust the size of the cursor with
the Set Size... option of the Cursor Menu.

To create a cursor:
1. Draw a cursor in the Cursor Image Editing Area.
Draw or import an image just as you would in the Image Editor.
2. In the Hot Spot Area, drag the specially colored bit to your cursor’s hot spot.
The Hot Spot determines the active bit of the cursor in your application.
3. Double-click the Selection Tool in the Tool Palette.
This selects the entire cursor image for masking.
5. Select Mask Selection from the Edit Menu.
This creates a mask for the selected area. Edit the mask if necessary. When editing a
transparency, the foreground color is always set to black and the background color is
always set to white.
6. Select Try Cursor from the Cursor Menu.
A copy of your cursor appears in the Cursor Panel. Select Try Cursor again to return
to your normal cursor.
CHAPTER
11
The Font Chooser

About the Font Chooser

Use the Font Chooser to specify fonts in ACL Designer. Any font available on your system can
be selected in the Font Chooser. You can specify fonts used by ACL Designer or fonts displayed
in the resources you create with ACL Designer. Figure 78 illustrates the Font Chooser.

ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
1234567890

Family: Face: Size:

helvetica iso8859 1 bold 12
lucida iso8859 1 bold oblique
8
lucidabright iso8859 1 medium
10
lucidatypewriter iso8 oblique
11
mincho ksc5601.1987
12

OK Apply Cancel

Figure 78. The Font Chooser

129
130 Chapter 11 The Font Chooser

Table 23 lists the features of the Font Chooser.

Table 23. Font Chooser features

Feature Description
Font Display Displays the current font selection.
Family Displays the type families available on your display.
Face Displays the typefaces available for the family selected in the Family List.
Size Displays the selected point size in the Size List. Edit this field to specify a size not listed in the
Size List.
Size List Displays point sizes available for the selected font.

To select a font:
1. In the Font Chooser, select the type family you want from the Family List.
Your selection appears in the Font Display.
2. Select the typeface you want from the Face List.
Your selection appears in the Font Display.
3. Select the size you want from the Size scrolling list or enter the size in the Size text
field.
Your selection appears in the Font Display.
4. Click one of the following confirmation buttons:
OK to change the font and close the Font Chooser
Apply to change the font without closing the Font Chooser
Cancel to close the Font Chooser without making any changes to the font
These confirmation buttons may vary, depending on your current look-and feel.

Dragging and Dropping Fonts (UNIX only)

When a Font Chooser has been opened in ACL Designer, fonts for any resource editor can be
specified by dragging and dropping a font from the Font Chooser to the resource editor. For
example, if you opened the Font Chooser from the Dialog Item Panel of a button item, the Font
Chooser could then be used to drag and drop fonts to other resource editors.

To drag and drop a font to a resource:

1. Specify the font you want in the Font Chooser. (Do not click OK or Apply.)
2. Select and drag any part of the Font Display Box in the Font Chooser to a resource.
A small box displaying the currently selected font is visible during the drag operation.
3. Release the mouse button at the resource.
The font for the resource is set.
CHAPTER
12
The Color Chooser

About the Color Chooser

Use the Color Chooser, shown in Figure 79, to specify colors for an application. Note that the
color chooser that appears on Windows platforms is the the system color chooser. With the
Color Chooser you can specify colors using four different color models, define color tolerances
for dithering, and save color specifications for future use.

Views Options

Color View Area

Color Method Option Menu
Color Method: HLS

Color Box
HLS Color Wheel

Color Component
Slider Bar Light: 79.61 %

Hue: 180.78 %

Saturation: 79.35 %
Saved Colors Palette
Saved Colors:

OK Apply Cancel

Figure 79. The Color Chooser

131
132 Chapter 12 The Color Chooser

The four color models available for choosing colors are:

• HLS
• RGB
• CMY
• Grayscale

The HLS color model specifies a color using a combination of the color’s hue, lightness, and
saturation components. This is the default color model in ACL Designer.
The RGB and CMY color models define colors by specifying a mixture of primary colors. The
RGB model mixes the additive primary colors: red, green, and blue. The CMY model mixes the
subtractive primary colors: cyan, magenta, and yellow.
The Grayscale model is used to define shades of gray for black and white or monochrome
monitors.

To specify a color model in the Color Chooser:

1. In the Color Method Option Menu, select a color model.
The Color Editor changes to reflect your choice.

Color Box
The Color Box displays the colors selected for use in the Color Chooser. The bottom half of the
Color Box displays the current color selection. The top half of the Color Box displays the
previous color selection. You can revert the current selection to the previous selection by
clicking in the top half of the Color Box. Colors can be dragged and dropped from the Color
Box to resource editors.

Color View Area

The Color View Area displays tools for selecting and defining colors for your application. Three
different views are available:
• Color Wheel/Plane
• Named Colors
• Color Tolerances

The Color Wheel/Plane displays a graphic representation, or map, of the selected color model.
In the HLS color model, this map is represented as a Color Wheel; in the RGB and CMY color
models, it is a Color Plane. Specify colors for your application directly from the map. (The map
is not used with the Grayscale model; selections are made using the Grayscale slider bar.)
Named Colors displays a scrolling list of predefined colors. Select colors for your application
directly from the list of Named Colors.
Color Tolerances displays a set of tools used to define the appearance of colors on a display.
You define the appearance of colors by specifying a method for dithering. (Dithering is the
process of approximating a color not available on a display by combining available colors in a
particular pattern.)
 Slider Bars 133

To specify a view for the View Area:

1. Select Views from the Color Chooser Menu.
The Views Menu, shown in Figure 80, is displayed.
2. Select a view from the Views Menu.
The selected view is displayed in the View Area.

Color Wheel / Plane

Named Colors
Color Tolerances

Figure 80. View Menu

Slider Bars
The three slider bars are used in conjunction with percentage fields to specify individual
components of a color. The color components represented by the slider bars varies with each
color model. Each slider bar has an indicator that defines the value of a color component. There
are several ways to specify a value with a slider bar. You can drag the indicator to the desired
location on the slider, enter the value directly into the percentage field for the slider, or click an
area in the slider to select a new value.
The appearance and behavior of the slider bars can be defined in two ways. By default, the slider
bars dynamically reflect the appearance of the color being selected. As you drag the indicator
to a new position on any component, the appearance of the other components change to reflect
your selection. However, if you want the slider bars to represent an unchanging scale of values
for each component, unselect Reform Slider Images from the Options Menu. Now the
appearance of the slider bars do not change to reflect the color being selected.
134 Chapter 12 The Color Chooser

Defining Color Tolerances

Since many displays cannot accurately represent all colors, dithering is used to approximate
colors on a display. Dithering takes place within certain tolerances you define in the Color
Chooser.
You define the color tolerances for dithering by specifying the maximum area (in pixels) to use
to approximate a color. You also specify a delta value that represents how close a color must
match before dithering approximates the color. Tolerances for dithering colors can be specified
from the Default Color Tolerances Menu in the Options Menu or from the Color Tolerances
view from the Views menu.
The selections available from the Default Color Tolerances menu, displayed in Figure 81,
provide the precision needed in most applications.

Large Dither
Small Dither
Solid
Precise Large Dither
Precise Small Dither
Precise Solid

Figure 81. Color Tolerances Menu

The color tolerance values corresponding to these menu selections are listed in Table 24.

Table 24. Default Color Tolerances

Menu Selection Dither Area (pixels) Delta Value (percent)

Large Dither 8x8 0.39
Small Dither 2x2 6.25
Solid No Dithering 25.00
Precise Large Dither 16 x 16 0.19
Precise Small Dither 4x4 1.56
Precise Solid No Dithering 6.25

CAUTION: Care should be taken when selecting Solid or Precise Solid from the Color
Tolerance Menu. These selections specify that no dithering take place. On most
displays, selecting too many colors that are not dithered limits the number of
colors available for other uses.
For most applications, the color tolerances available in the Default Color Tolerances Menu are
sufficient to define your colors. However, if you require more precision in defining a color, use
the Color Tolerances view from the Views Menu. Figure 82 shows the Color Tolerances view
for the HLS color model.
 Using the HLS Color Model 135

Views Options

Dither Area
Dither Area: 8 X 8 Option Menu
Color Method: HLS
Delta Values

H: 0.78 %

L: 0.78 % Delta Values Sliders

S: 1.56 %

Distance

D: %

Light: 50.00 %

Hue: 228.71 %

Saturation: 100.00 %

Saved Colors:

OK Apply Cancel

Figure 82. Color Tolerances View for the HLS color model
Use the Dither Area option menu to select a dithering matrix. Use the Delta Values sliders to
specify a delta value for each component individually. Use the Distance slider to specify a delta
value, or distance, applied equally to all components.

CAUTION: When selecting a dithering matrix, be careful about specifying no dithering for
a color. On most displays, selecting too many colors that are not dithered limits
the number of colors available for other uses.

Using the HLS Color Model

The HLS color model defines a color by specifying values for the color’s hue, lightness, and
saturation components. These components are represented in the double cone displayed in
Figure 83.

Hue

Lightness 90˚
Axis

180˚ 0˚ (Red)

Saturation
Axis
270˚

Figure 83. HLS Color Model

136 Chapter 12 The Color Chooser

The hue component defines a color’s position in a continuous color spectrum, and is represented
as the angle around the circumference of the cone. Hue is measured in degrees and ranges from
zero to 360. Zero represents red. The lightness component defines the density of a color and is
represented by the vertical axis. Lightness ranges from zero for black, to 100 for white.
Saturation defines the intensity of a color and is represented by the distance from the vertical
axis to the perimeter of the cone. Saturation ranges from zero to 100.

The HLS Color Wheel

The HLS Color Wheel, displayed in Figure 79, is a mapping of the hue and saturation
components of a color for a given lightness value. It is the view looking directly down the
double cone (displayed in Figure 83) at a plane determined by the lightness component. Hue is
measured in increasing values as you move counterclockwise around the Color Wheel. Zero, or
red, is located on the right side of the Color Wheel. Saturation is measured from the center of
the Color Wheel to the perimeter. Zero saturation is located at the center. (Specify the lightness
component with the Lightness Slider Bar in the Color Chooser.)

To specify a color using the HLS Color Wheel:

1. Select HLS from the Color Method Option Menu.
The Color Chooser changes to the HLS model.
2. If the Color Wheel is not visible, select Color Wheel/Plane from the Views Menu.
The Color Wheel is displayed in the View Area.
3. Select the lightness value for your color by dragging the indicator on the Light slider
bar or by typing a value in the percentage field.
A lightness value of zero represents black; 100 represents white.
4. Click anywhere in the Color Wheel to choose the hue and saturation mix of the new
color.
The crosshair tracks your selection in the Color Wheel. The indicators for the sliders
representing the hue and saturation components move to reflect your selection. The
Color Box also changes to reflect your selection.
NOTES: Colors can also be specified directly from the slider bars as described in the
section, “Slider Bars” on page 133.
Dithering for a color can be defined using the Default Color Tolerances
submenu from the Options Menu or the Color Tolerances View from the
Views Menu. See “Defining Color Tolerances” on page 134 for more on
color tolerances.
 Using the RGB or CMY Color Model 137

To specify a color using the HLS color model:

1. Select HLS in the Color Method selection area.
The Color Chooser changes to the HLS model.
2. Select the lightness value for your color by dragging the cursor on the Light slider bar
or by typing a value in the percentage field.
A lightness value of zero represents black; 100 represents white.
3. Click anywhere in the Color Wheel to choose the hue and saturation mix of the new
color, or specify values in the Hue and Saturation percentage fields.
The color you specify is displayed in the lower part of the Color Box.
NOTE: To return to the original color, double-click in the upper half of the Color
Box.

Using the RGB or CMY Color Model

The RGB and CMY color models define colors by specifying a mixture of primary colors. The
RGB model mixes the additive primary colors: red, green, and blue. The CMY model mixes the
subtractive primary colors: cyan, magenta, and yellow. Both of these color can be represented
as a cube. The height, width, and length of the cube each represent a primary color. Figure 84
displays a representation of the RGB color model.

r b

g
g
b
(0,0,0)

Figure 84. The RGB Color Model

138 Chapter 12 The Color Chooser

The RGB/CMY Color Plane

The Color Plane is a mapping of two primary color components of a color for a given value of
the third primary color component. Figure 85 displays a Color Plane for the cube represented in
Figure 85. It is a view looking directly down the top of the cube at a plane determined by the
value of the red component. (The value of the red component is specified with the Red Slider
Bar.)

Views Options

Color Method: RGB Color Plane

Red: 63.43 %

Green: 95.37 %

Blue: 95.79 %

Saved Colors:

OK Apply Cancel

Figure 85. Color Plane

The plane selected for viewing can be changed to reflect the mapping of any two primary colors
against a value for the third primary color in the RGB or CMY color models.

To select a color plane using the RGB or CMY Color Plane:

1. Select RGB or CMY from the Color Model Option Menu.
The Color Chooser changes to the appropriate model.
2. If the Color Plane is not visible, select Color Wheel/Plane from the Views Menu.
The Color Plane is displayed in the View Area.
3. Select the desired Color Plane from the Options Menu.
The Color Plane you select is displayed in the View Area.
 Using the Grayscale Model 139

To specify a color using the RGB or CMY Color Plane:

1. Select a Color Plane to use for specifying a color.
The Color Plane you select is displayed in the View Area.
2. Click anywhere in the Color Plane to choose a value for the two colors mapped in the
Color Plane.
The crosshair tracks your selection in the Color Plane. The indicators for the sliders
representing the two mapped colors move to reflect your selection. The Color Box also
changes to reflect the selection.
3. Move the slider for the third component to change its value.
The Color View area changes to reflect your selection.
NOTES: Colors can be specified directly from the slider bars as described in the
section, “Slider Bars” on page 133.

Dithering for a color can be defined using the Default Color Tolerances
submenu from the Options Menu or the Color Tolerances View from the
Views Menu. See “Defining Color Tolerances” on page 134 for more on
color tolerances.

Using the Grayscale Model

The Grayscale model is used to define shades of gray for black and white or monochrome
monitors. A value of 100 in the Grayscale model represents white; zero represents black. The
Grayscale model can be represented as the diagonal line drawn in the RGB cube when the
values for red, green, and blue are equal, as represented in Figure 86.
The Grayscale slider in the color Chooser corresponds to the diagonal line in Figure 86. The
View Area is inactive in the Grayscale Model, since the Grayscale slider represents every
possible value in the Grayscale model.

(r, g, b | r=g=b) r

g
b
(0,0,0)

Figure 86. The Grayscale Model

140 Chapter 12 The Color Chooser

To specify a new shade of gray using the Grayscale model:

1. Select Gray in the Color Model selection area.
The Color Chooser changes to the Grayscale model.
2. Specify a shade of gray by dragging the cursor on the Grayscale slider bar or by typing
a value in the percentage field.
The shade of gray you specify is displayed in the lower part of the Color Box.
NOTE: Dithering for a shade of gray can be defined using the Default Color
Tolerances submenu from the Options Menu or the Color Tolerances View
from the Views Menu. See “Defining Color Tolerances” on page 134 for
more on color tolerances.

Named Colors
The Color Chooser comes with a set of predefined colors available for use in an application.
These predefined colors can be selected from the scrolling list in the Named Colors view, shown
in Figure 87.

Views Options

alice blue
Color Method: HLS antique white
aquamarine
azure
beige
bisque
black
blanched almond
blue
blue violet

Light: 50.00 %

Hue: 228.71 %

Saturation: 100.00 %

Saved Colors:

OK Apply Cancel

Figure 87. Named Colors View

To select a Named Color:

1. Select Named Colors from the Views Menu.
The scrolling list of named colors is displayed.
2. Double-click on any color in the scrolling list.
The color selected is displayed in the Color Box.
 Saved Colors 141

Saved Colors
Use the Saved Colors Palette to save frequently used colors. Up to 16 colors can be saved on
this palette. When a color is saved, the color tolerance values for dithering are saved with it.
Saved colors are automatically saved with the Color Chooser and are available for future editing
sessions.

To save a color on the Saved Color Palette (by clicking on a cell):

1. Select a color in the Color Chooser.
Use any of the previously outlined methods to select a color.
2. Press the Control key and click a cell on the Saved Color Palette.
The color has been added to the selected cell.

To save a color on the Saved Color Palette (using the Arrow Keys):
1. Select a color in the Color Chooser.
Use any of the previously outlined methods to select a color.
2. Click on the Saved Colors Palette.
The border of the Saved Colors Palette is highlighted indicating it has been focused.
3. Using the left and right Arrow keys, move the cell indicator to select a cell to hold the
saved color.
4. Select Add Saved Color from the Options Menu.
The color has been added to the selected cell.

To retrieve a color from the Saved Colors Palette:

1. Double-click on a cell in the Saved Colors Palette.
The color stored in the cell is now the selected color, and is displayed in the Color Box.

Applying Colors
Selected colors can be applied in the Color Chooser using the chooser’s confirmation buttons:
• Click OK to apply the color selection and close the Color Chooser
• Click Apply to apply the color selection and leave the Color Chooser open
• Click Cancel to close the Color Chooser without applying the color selection
These confirmation buttons may vary, depending on your current look-and-feel.
142 Chapter 12 The Color Chooser

Dragging and Dropping Colors

When a Color Chooser has been opened in ACL Designer, color specifications for many items
can be made by dragging and dropping colors from the Color Chooser to the item’s resource
editor. For example, if you opened the Color Chooser from the Dialog Item Panel of a button
item, the Color Chooser could then be used to drag and drop colors to other resource editors.

To set the foreground (and background) color for a resource:

1. Specify the color you want in the Color Chooser. (Do not click OK or Apply.)
2. Select and drag any part of the Color Box in the Color Chooser to a resource. (A small
box displaying the currently selected color is visible during the drag operation.)
3. Release the mouse button at the resource.
The foreground color for the resource is set. (Press the Control key while dragging to
specify the background color.)
CHAPTER
13
The File Chooser

Use the File Chooser to navigate through your file system when opening or saving files. Note
that the default file chooser on Windows platforms is the native Windows file chooser provided
with the system. To use the file choose shown here on Windows systems, use the
-nonativefilechooser command line option when starting ADEPT.

History Special View Filters

hal/

Acme
Ad Copy
<
Appointments
Archive
Bin
bin
> Budget
Client List

Open:
Budget/

OK Apply Cancel

Figure 88. The File Chooser

143
144 Chapter 13 The File Chooser

Use the View Menu of the File Chooser to change the way files are listed. You can change your
current directory using any of the following:
• History menu
• Path pop-up menu
• Scrolling list
• Arrow buttons
• Name text field
Open a file using any of the following:
• Scrolling list
• Name text field

Using the File Chooser Menus

The File Chooser has three menus: History, Special, and View. The History and Special Menus
provide shortcuts for moving through your system. The View Menu contains commands that
change how the information is displayed in the scrolling lists.

The History Menu

Use the History Menu to change the File Chooser’s current directory. The History Menu has two
parts. The upper part displays the most recently visited directories; up to five directories can be
displayed. The lower part of the menu lists marked directories. Directories are marked with the
Mark Directory command in the Special Menu. Marked directories provide quick access to
frequently used directories. (If the History Menu does not have a lower part, then no directories
have been marked.)
When you visit more than five directories, the oldest directory is removed from the bottom of
the “most recently visited” list and the newest directory is inserted at the top. Marked directories
remain in the History Menu until you unmark them.
The directories listed in the History Menu are saved from one editing session to the next.

To change directories using the History Menu:

1. Select a new directory from either the upper or lower part of the History Menu.
The current directory changes to the selected directory and is displayed in the File
Chooser.

The Special Menu

Use the Special Menu to change the current directory to your home directory or to mark the
current directory. A marked directory is displayed in the lower half of the History Menu for
quick access. You can mark as many directories as you like. Marked directories can be
unmarked later.

To change to your home directory:

1. Select Home from the Special Menu.
The File Chooser’s current directory changes to your home directory.
 Additional Features of the File Chooser 145

To mark a directory:
1. Change the current directory to the directory you want to mark.
You can only mark the current directory.
2. Select Mark from the Special Menu.
The current directory is placed in the marked directory list in the lower part of the
History Menu.

To unmark a directory:
1. Change the current directory to a marked directory.
You can only unmark a directory if it is the current directory.
2. Select Unmark from the Special Menu.
The current directory is removed from the marked directory list in the lower part of the
History Menu. It is still visible as a “most recently visited” directory in the upper part
of the History Menu.

The View Menu

Use the View Menu to sort and view the contents of the current directory by name, date
modified, or date created.

To change the view of the contents of the current directory:

1. Select by Name, by Date Modified, or by Date Created from the View Menu.
The contents of the current directory are displayed according to the selected format.

The Path Menu

The Path Menu is a pop-up menu that displays the current directory. When the Path Menu is
opened, the directories in the current path are displayed. You can change your current directory
to any of the directories in the current path.

To change the current directory using the Path Menu:

1. Select the Path Menu.
A pop-up menu appears listing the directories in the current path.
2. Select a directory from the pop-up menu.
The selected directory becomes the current directory; its contents are displayed in the
scrolling list below the Path Menu.

Additional Menus
Depending on the context of the File Chooser, additional options are available for handling files.
For example, if the File Chooser is being used to open resource files from the Main Window, a
Filter Menu is available. Use the Filter Menu to filter out entries that are not resource files or
directories.

Additional Features of the File Chooser

The Scrolling List

The scrolling list displays the files and directories in the current directory. An icon displayed
before each name in the list indicates whether the listing is a file or directory. Use the scrolling
list to change the current directory or to open a file.
146 Chapter 13 The File Chooser

To change the current directory using the scrolling list:

1. Double-click on a directory name in the scrolling list.
The current directory changes to the selected directory. The contents of the list changes
to reflect the new current directory.

To open a file using the scrolling list:

1. Double-click on the name of a file in the scrolling list.
The file you selected opens.
or
1. Select a file in the scrolling list.
2. Click one of the following three confirmation buttons:
OK to open the selected file and close the File Chooser
Apply to open the selected file without closing the File Chooser
Cancel to close the File Chooser without opening a file
These confirmation buttons may vary, depending on your current look-and-feel.

Displaying Several Directories

You can resize the File Chooser (make it wider) to display up to five directory levels at one time.
The current directory is always displayed in the leftmost list. Additional directories can be
displayed as follows:
• When you change current directories using the Path Menu, the new current directory is
displayed in the leftmost list and the other directories in the path are displayed in the
remaining lists. For example, if the current directory is bin in the path /usr/systems/
bin, and you use the Path Menu to change the current directory to usr, usr becomes the
leftmost list, systems is displayed in the list to the right of usr, and bin is displayed in
the list to the right of systems. The directory names are displayed in the text fields above
the appropriate lists.
• When you select a directory from a list, the contents of the selected directory are displayed
in the list immediately to the right and the selected directory’s name appears in the text field
above the list.

Using the Arrow Buttons

Use the arrow buttons to the left of the scrolling list to change the current directory to the
directory immediately above or below the current directory or a directory selected in the list.

To change the current directory using the arrow buttons:

1. Click the left arrow button or select a directory in the leftmost scrolling list.
The parent of the current directory becomes the new current directory.
2. Select the right arrow button.
The selected directory becomes the new current directory.

Using the Name Text Field

The Name text field displays the name of the file or directory selected in the scrolling list. Use
the Name field to change your current directory or to open a file.
 Additional Features of the File Chooser 147

To change your current directory using the Name field:

1. In the Name text field, type the pathname of the new current directory.
If the new directory is located in the current directory, type the directory’s name in the
text field. Pressing the space bar completes partially entered unique names. The
Chooser beeps if the entered name is not unique.
2. Click OK or Apply, or press Enter.
The current directory is changed to the directory specified in the Name field. (The
confirmation buttons available may vary, depending on your current look-and-feel.)

To open a file using the Name field:

1. In the Name text field, type the pathname of the file you want to open.
If the file you want to open is in the current directory, you only need to type the name
of the file you want to open. Pressing the space bar completes partially entered unique
names. The Chooser beeps if the entered name is not unique.
2. Click OK or Apply, or press Enter.
The current directory is changed to the directory specified in the Name field. (The
confirmation buttons available may vary, depending on your current look-and-feel.)
148 Chapter 13 The File Chooser
CHAPTER
14
Modifying the ADEPT Interface

Using ACL Designer, the three basic ways to modify the ADEPT interface are:
• To create a form region that becomes an integral part of the ADEPT window.
• To create a toolbar that becomes an integral part of the ADEPT window.
• To modify existing forms by removing controls.

Each of these basic methods is described in detail in this chapter.

Creating dialogs
NOTE: Arbortext recommends that you do not use ACL Designer to create dialogs. Instead,
use a programming language such as Java or Visual Basic for creating dialogs.

149
150 Chapter 14 Modifying the ADEPT Interface

Creating form regions

A Form Region is a specific kind of ADEPT interface item. Where dialogs appear in their own
windows and can be manipulated independently of the ADEPT window, form regions become
an integral part of the ADEPT window, appearing just under the toolbars, or just above the status
bar at the bottom of the window.
Form regions are good places to place site-specific configuration selections which your authors
will use often. ACL Designer ships with a sample form region. The sample form region is
located in the ACL Designer installation directory in the samples/form/ directory. The
form sample consists of two files.
form.cmd - contains the ADEPT Command Language (ACL) code which places the form.vr
interface in the form region and sets up its callbacks.
form.vr - is the ACL Designer resource file for the form region.
Upon opening the form.vr file, you’ll notice that a form region isn’t a dialog, but rather a
container. The dialog items within the container are placed just as they would be for a dialog.
When creating a form region, keep the following in mind:
• A form region does not size vertically. However, textitems and listitems within a form
region can certainly have vertical scroll bars.
• Form regions span the ADEPT edit window and, therefore, are subject to being stretched
or shrunk horizontally. When creating a form region, make sure it handles this behavior
gracefully.
• There are two form regions on the ADEPT window: topForm and bottomForm.
- topForm - This region is just below the toolbars. If the Options->Toolbars menu
item is off, the form regions in the topForm area will appear just below the menu
bar.
- bottomForm - This region is at the bottom of the ADEPT window, just above the
status bar at the lower border. If the command line is enabled, form regions in the
bottomForm area will appear just above the command line.
• It is wise to limit the vertical height of your form regions. The larger the form region, the
smaller the size of the ADEPT document area.
• By default, ADEPT does not provide the user with control over the form regions (show,
hide, etc.). If you wish, you can always add this functionality to ADEPT.

Creating toolbars
A Toolbar is a special kind of ADEPT interface item. Toolbars are attached to a specific area of
the ADEPT window. In the default ADEPT application, there are three toolbars both consisting
of sets of buttons.
A Toolbar is an excellent place to give the user access to often-used functions. ACL Designer
ships with a sample toolbar. The sample toolbar is located in the ACL Designer installation
directory in the samples/toolbar/ directory. The toolbar sample consists of two files.
toolbar.cmd - contains the ADEPT Command Language (ACL) code which places the
toolbar in toolbar.vr in the ADEPT edit window and sets up its callbacks.
toolbar.vr - is the ACL Designer resource file for the toolbar.
Upon opening the toolbar.vr file, you’ll notice that a toolbar region isn’t a dialog, but rather
a container. The dialog items within the container are placed just as they would be for a dialog.
When creating a toolbar, keep the following in mind:
 Creating toolbars 151

• There are five toolbars defined in adept.vr. They are.

- Toolbar1X - Epic Editor LE toolbar.
- Toolbar1 - ADEPT edit toolbar.
- Toolbar2 - ADEPT markup toolbar.
- Toolbar3 - Table editor toolbar. If you edit the ADEPT interface to eliminate
access to the table editor, you could then safely load a user-defined toolbar in this
area.
- Toolbar4 - DocBook Application toolbar.
• Two resource items, Adept Toolbar and Adept Toolbar Button are provided as starting
points for custom toolbar construction. If you use the default Adept Button and Adept
Container items to build a toolbar, it will not function correctly. You may wish to use the
sample toolbar resource file (toolbar.vr) and copy and paste the toolbar buttons for
your own uses. If you use the Adept Toolbar Button dialog item, make sure to resize your
button image down to 19 pixels wide by 15 pixels tall. This will match the other ADEPT
toolbar icons.
• The toolbar.cmd file has an added section which loads the sample toolbar whenever a
new window is opened. Pay close attention to this section of the toolbar.cmd file, as
you may find this functionality useful.
• The sample toolbar.vr file includes the necessary resources for tooltips. Tooltips are
the little messages which appear when you place your mouse pointer over a button. The
following are the important issues when adding tooltips (inspect the toolbar.vr file for
an example of this organization).
- There must be dictionary called Tooltips in the root of the .vr file.
- The Tooltips dictionary should contain additional dictionaries; one for each
toolbar in your .vr file. You may wish to name these dictionaries to match your
toolbar container names, but this is not required.
- Each Tooltips:toolbarname dictionary should contain a subsequent dictionary for
each button on that toolbar. Each dictionary name must match one of the toolbar
button names exactly.
- Each Tooltips:toolbarname:buttonname dictionary should contain two string
resources: StatusText and TipText (these names are case-sensitive). The
StatusText string appears in the status bar when the mouse pointer is over that
toolbar button. The TipText appears in a pop-up box when the mouse pointer is
over that toolbar button.
• Pay close attention to the connections between the buttons in the sample toolbar.vr
file. These connections are necessary to ensure that the buttons will properly appear and
disappear if you use the dlgitem_withdraw and dlgitem_display functions.
Since the size of the toolbar buttons forces you to work in close quarters, use the
Window->Connection dialog to assist in making the necessary connections.
• If you wish your toolbars to appear consistent with ADEPT’s default toolbars, you may
wish to copy the buttons and line items from the sample toolbar as a starting point.
• Like ADEPT’s toolbars, the sample toolbar has a 1-pixel wide line accross the top of the
toolbar. This provides a visually pleasing break between adjacent toolbars.
• By default, only the standard ADEPT toolbars appear and disappear per ADEPT’s
Options->Toolbars menu option (slots toolbar1, toolbar2, and toolbar3). You could
alter the function of this menu option so it would also control your custom toolbars.
152 Chapter 14 Modifying the ADEPT Interface

Modifying ADEPT’s default toolbars

If you edit the adept.vr resource file which ships with ADEPT, you can permanently change
the appearance and behavior of the default toolbars.
NOTE: Before editing the adept.vr file, make sure you have an unedited copy available
in case your changes are not satisfactory.

To edit ADEPT’s default toolbars

1. Start ACL Designer and open the adept.vr file. The adept.vr file is located in
the ADEPT installation directory in the lib subdirectory.
2. At the root level of the adept.vr file, open the dictionary called AdeptEditor.
3. Open the Toolbar1 and/or Toolbar2 items and edit the toolbars to your liking.
Remember that each toolbar button must have a unique tag name. Do not use an
existing tag name for a new toolbar button. If you are simply moving a button from one
toolbar to another, do not change its tag name. Make a note of the new toolbar button
tag names, as you will need them when adding tooltips and programming callbacks.
Note that default ADEPT toolbars use the internal ADEPT class of
aptToolbarButton. Any button you add must be of the Adept Toolbar Button class.
4. At the root level of the adept.vr file, open the Tooltips dictionary.
5. Open the adeptEditor dictionary.
6. Add a dictionary for each new toolbar button tag name you added. Refer to the
guidelines in the previous section for creating the tooltip string resources.
7. Save your changes to the adept.vr file.
8. Create an ACL script that assigns callbacks to the new buttons you added. This script
should be called such that it runs each time ADEPT is started.

Editing the ADEPT interface

If you edit the adept.vr resource file which ships with ADEPT, you can permanently change
the appearance and behavior of much of the ADEPT user interface. The adept.vr file is
located in the ADEPT installation directory in the lib subdirectory.

NOTE: Before editing the adept.vr file, make sure you have an unedited copy available
in case your changes are not satisfactory. If you wish, you can set the APTVR
environment variable to point at the .vr file you wish to use with ADEPT.

If you plan to edit adept.vr, we suggest taking a few moments and inspecting the
organization of the resources in this file. The following information serves a quick tour of the
adept.vr file.
• All ADEPT edit window structures, including toolbars, are found in the AdeptEditor
dictionary.
• The default structure for the tags and entity pull down menus (as accessed from the toolbar),
are located in the aptDropdown dictionary.
• Cursors used in ADEPT are located in the Cursors dictionary.
• The default color definitions for UNIX platforms are located in the DefaultPreferences
dictionary. There is a Windows dictionary inside the DefaultPreferences dictionary which
contains the default color definitions for the Windows platforms.
• The interface resources for the equation editor are inside the EquationEditor dictionary.
 Editing the ADEPT interface 153

• The object icons which appear in ADEPT (predominately in the Document Map) are
located in the IconImages dictionary. Other images, including those used by the Object
Browser, are located in the Images dictionary.
• All ancillary dialogs are found in the PopUpDialogs dictionary. This includes (among
many others) the Find, Print, Open, Save, Preferences, and Spelling dialogs.
• The interface resources for the table editor are inside the TableEditor dictionary.
• The status messages and tooltips, which appear when you place your mouse pointer over a
toolbar button, are found in the Tooltips dictionary. The Tooltips dictionary has a specific
structure which must be followed closely. Refer to the Creating Toolbars section (earlier
in this chapter) for details.
A sample procedure for changing an existing dialog appears below.

To remove the Options button from the Spelling dialog

1. Start ACL Designer and open the adept.vr file. The adept.vr file is located in
the ADEPT installation directory in the lib subdirectory.
2. At the root level of the adept.vr file, open the dictionary called PopUpDialogs.
3. Open the Spelling dialog.
4. The options button is grouped together in a container with the Ignore All, Change All
and Help buttons. Double-click on this container group to edit the individual buttons.
5. Select the Options button and delete it. Either select Edit->Cut, or press Ctrl-B.
6. Select the Help button and select Connection->Select->Bottom.
7. Select Connection->Fixed Base + Spring.
8. Select the top connection for the Help button. If you wish to do this explicitly, select
Connection->Select->Top.
9. Select Connection->Fixed Length.
10. Click the top of the Help button’s top connection and drag it down until it snaps to the
bottom of the Change All button.
11. Drag the Help button up until the space between it and the Change All button is
similar to the space between the Change All button and the Ignore All button.
12. Select the Help button’s bottom connection and select select Connection->Locked
Fixed. The connections will turn red, as this is an invalid connections scheme. The
next step repairs this condition.
13. Select the top connection for the Help button and select Connection->Fixed Base +
Spring.
14. Close the editor windows and save your changes.
15. Run ADEPT. The changes you made to the Spelling dialog are immediately apparent.
154 Chapter 14 Modifying the ADEPT Interface
CHAPTER
15
ACL Designer ACL Functions

Overview
Several design tools can be used together to create a custom ADEPT application:
• Use ACL Designer to create dialogs.
• Use a text editor to create ADEPT Command Language (ACL) code. The code will locate
dialogs and widgets on the dialogs, attach callbacks, and implement application-specific
functionality within the callbacks.
This chapter assumes that you have a working knowledge of ACL.

ADEPT Command Language concepts

ACL Designer is the ADEPT developer's primary visual design tool. The interface designer uses
ACL Designer to construct one or more dialogs and then the developer writes ACL code to
access the dialogs, attach callbacks, and implement application-specific functionality within the
callbacks. The resulting system is referred to as an ADEPT application. The callback
mechanism is the primary communication channel between the dialogs and the application
code. User-initiated actions on the dialogs ultimately result in the activation of one or more
callbacks. Note that the resource files are stored in a portable, machine-independent format.
Therefore, the resource files and the ACL code will run on any platform which supports
ADEPT. The ADEPT application will be able to load items from any number of resource files.
Dialogs are a subclass of the existing window data type within ACL. Callbacks can be attached
to dialogs and to individual dialog items ("widgets") in each dialog. Callbacks are attached to
instances of items, not to classes. Callbacks are passed context information to allow them to
operate on behalf of more than one item. Callbacks are used to inform the application of change
of focus and other similar events of potential interest. When an event occurs on a dialog item
the following stream of events occurs:
• The dialog item changes its state based on the event.

155
156 Chapter 15 ACL Designer ACL Functions

• The callbacks on the dialog item's callback list are called in order.
• The callbacks on the dialog's callback list are called in order.
Dialog items have attributes that can be accessed from ACL. The set of available attributes
varies depending on the type of the dialog item. The section on dialog items attributes (later in
this chapter) describes the set of attributes.
An ACL Designer resource file (.vr) can contain an arbitrary hierarchy of dialogs and dialog
items. Dialogs can be nested within dictionaries, and dialogs can directly contain dialog items,
or they can contain containers which in turn could contain other containers or actual dialog
items. In keeping with the goal of simplicity, this hierarchy will be made invisible to the
developer.
The hierarchy contained within the resource file is effectively flattened so that all dialogs appear
to be at the top level of the file, and all dialog items appear at the top level of the dialog. This
places some responsibility on the developer, since all names assigned within the file must be
unique within their scope. The effect of this flattening behavior is to simplify the programming
interface.
ACL calls which encounter an error situation will set the main::$ERROR global variable and
return a distinctive value. This "fail soft" behavior allows developers to incrementally build and
test new ADEPT applications.

Attributes

Dialog attributes
All dialogs have the following dialog attributes:
CALLBACKS - A string: a comma-delimited list of callbacks for the dialog, in the order that the
callbacks are used.
DIALOG_PTR - An integer: The internal ACL Designer identifier for the dialog. Cannot be
changed by the application.

Dialog item attributes

All dialog items have the following dialog item attributes:
ACTIVE - An integer: non-zero if the dialog item is active, zero if the dialog item is not active.
An active dialog item responds to user actions (mouse clicks and key strokes).
APPDATA - A string: application-specific data that is passed to dialog item and outline list
expansion callbacks.
BACKGROUND - An integer: the red-green-blue value denoting the item's background color.
CALLBACKS - A string: a comma-delimited list of callback for the item, in the order that the
callbacks are used.
DLGITEM_PTR - An integer: The internal ACL Designer identifier for the dialog item. Cannot
be changed by the application.
EDITABLE - An integer: non-zero if the dialog item accepts user modifications, zero if the
dialog item does not accept user modifications.
FOREGROUND - An integer: the red-green-blue value denoting the item's foreground color.
IMAGE - A string: the name of an image to display within the dialog item.
 Dialog item-specific attributes 157

TITLE - A string: the title of the dialog item. Not all dialog items display their title.
VALUE - A string: the value of the dialog item.
VISIBLE - An integer: non-zero if the dialog item is visible, zero if the dialog item is not
visible. A visible dialog item is shown when its dialog is open.

Dialog item-specific attributes

Certain dialog items may have type-specific attributes in addition to the default attributes for
dialog items:
LIST_COUNT - An integer for items which contain lists. Contains the number of items in the
list. Setting the value extends or truncates the list as appropriate.
EXPAND - A callback function that is called to generate additional structure in an outline list
item.
ENABLE - A callback function that is called to enable or disable menu items before a menu is
opened.
Note that the attribute types are expressed as strings in ACL (e.g., “EXPAND”), and are case
sensitive.

Callbacks
Any window or dialog item can have a list of callbacks attached to it. Callbacks are regular ACL
functions that take a fixed set of arguments. Callbacks should always be set using a fully
qualified name to avoid ambiguity. The callbacks are called to inform the application that
various interesting events have occurred. There are four types of callbacks:
• Window notify
• Dialog item
• Outline list expansion
• Menu enable
Dialog item callbacks are called first, then window callbacks are called. Within a callback list,
callbacks are called starting at the first element in the list. A callback has no opportunity to
interrupt the normal flow of processing or to prevent the event it is called for from taking effect.
In other words, window and dialog item callbacks are purely informational in nature.

NOTE: This differs from the existing "quit" callback used for windows.

Outline lists also have a special callback specified by the EXPAND attribute. This callback is
called to construct the hierarchy within the list on an as-needed basis. Menu bars also have a
special callback specified by the ENABLE attribute. This callback is used to enable and disable
menu items immediately prior to the time that the menu is opened.
Window notify callbacks are called with the following arguments:
WindowCallback(window, dlgitem, event, data)
Where window is the window where the event happened, dlgitem is either the tag name of
the dialog item where the event happened or NULL if the event is a window-level event, and
event is the event code (see section later in this chapter). The data argument contains event-
specific information. The callback need not return a value.
Dialog item callbacks are called with the following arguments:
158 Chapter 15 ACL Designer ACL Functions

DialogItemCallback(window, dlgitem, event, data, appdata)

Where window is the window where the event happened, dlgitem is the tag name of the
dialog item where the event happened, and event is the event code (see below). The data
argument contains event-specific information. The appdata argument contains the
application data of the dialog item. The callback should not return a value.
The outline list expansion callback is called with the following arguments:
ExpandCallback(window, dlgitem, listtag)
Where window is the window containing dlgitem, dlgitem is the tag name of the dialog
item containing listtag, and listtag is the list tag in need of expansion. The callback can
use the dlgitem_set_array function to add values to the list tag. The callback should not
return a value.
The menu enable callback is called with the following arguments, immediately prior to the time
a menu in the menu bar is to be displayed:
EnableCallback(window, dlgitem, menutag)
Where window is the window containing dlgitem (which is always a menu bar) and
menutag is the tag of a menu in the menu bar. The callback must return 1 if the menu item is
to be enabled, or 0 if the menu is to be disabled.

Callback event codes

The following event codes may be passed (as uppercase strings) to window callbacks:
WINDOW_CLOSED - The window has been closed by user or program request.
WINDOW_FOCUSED - The user has moved the focus to the window.
WINDOW_UNFOCUSED - The user has removed the focus from the window.
The following event codes may be passed to window callbacks and to dialog item callbacks:
ITEM_CHANGED - The VALUE of the item has been changed by the user.
ITEM_FOCUSED - The user has moved the focus to the item.
ITEM_UNFOCUSED - The user has removed the focus from the item.

Outline List Item Handling

Outline list items are more complicated than the other dialog items. The item contains a top-
level list that can contain other secondary lists which are descendants of various items in the
top-level list. The secondary lists can themselves have descendants, and so forth. The list items
can be added incrementally as the list is expanded. A special expansion function is notified
when a list item may require expansion.
Each outline list item contains a number of lists, each identified by a list tag. The tags are private
to a particular item, and are assigned automatically as needed. The lists are bound to the item
which owns them; they cannot be shared between items. List tags can be used interchangeably
with tags which identify dialog items. In particular, the dlgitem_set_list_at and
dlgitem_set_list_array functions can be used to expand the list.
 Outline List Item Handling 159

Consider the following outline list information:

The following lists will exist:

Each list is identified by a unique list tag. The pointer references are maintained internally; the
corresponding list tags can be obtained as follows:
top = dlgitem_get_sublisttag(window, dlgitem) will return the list tag
identified as (1).
B1 = dlgitem_get_sublist(window, dlgitem, top, 2) will return the list tag
identified as (2).
B2A = dlgitem_get_sublist(window, dlgitem, B1, 2) will return the list tag
identified as (3).
C1 = dlgitem_get_sublist(window, dlgitem, top, 3) will return the list tag
identified as (4).
160 Chapter 15 ACL Designer ACL Functions

Image Handling
Certain ACL Designer dialog items use their Image attribute as a background image for the
item. To support this, the IMAGE attribute is provided. It is important to note that not all items
will display their image, and that items which do display their image may appear different under
each supported look and feel. The image item will always display its image.
The IMAGE attribute can be set programmatically to affect a change in the displayed image.
Potential images are stored in an ACL Designer dictionary named "Images" at the root level of
the resource file where the dialog containing the dialog item was found. Setting the IMAGE
attribute of an item to the special string “_NONE” will display no image for the item. Setting the
IMAGE attribute of an item to the special string “_ORIGINAL” will display any image that is
specified in the resource file for the item.

ACL Designer ACL functions

The following ADEPT Command Language (ACL) functions are designed specifically to
interface with the resources and dialog items stored in ACL Designer .vr files. Most of the
supported ACL functions are documented in the online help which ships with ADEPT. Several
supported functions were not included in the ADEPT online help; they are documented in this
chapter.

dlgitem_set_active_at
ret = dlgitem_set_active_at(window, listtag, row, activestatus)
Activates or deactivates the specific outline list entry row in the outline list listtag in
window. If listtag does not refer to a outline list list tag, $ERROR is set and zero (0) is
returned. Otherwise, one (1) is returned.
The window parameter is a window identifier. The listtag parameter is an outline list list
tag (case sensitive). The row parameter is an offset into listtag (starting from one). The
activestatus parameter sets the enabled/disabled status of the list entry (1=enabled;
0=disabled).
Example
$ret = dlgitem_set_active_at(win, "Hierarchy", 3, 0)
deactivates the third item in the outline list item Hierarchy.

dlgitem_set_appdata_at
ret = dlgitem_set_appdata_at(window, listtag, row, appdata)
Associates application-specific appdata with the outline list entry row in the outline list
listtag in window. If listtag does not refer to an outline list list tag, $ERROR is set and
zero (0) is returned. Otherwise, one (1) is returned.
The window parameter is a window identifier. The listtag parameter is an outline list list
tag (case sensitive). The row parameter is an offset into listtag (starting from one). The
appdata parameter is the string of application data to associate with the list item.
Notes
The application data is passed to dialog item and outline list expansion callbacks.
Example
 dlgitem_set_branch_image_at 161

ret = dlgitem_set_appdata_at(win, "Hierarchy", 3, "TopOne")

sets the application data of the third item in the outline list item Hierarchy to TopOne.

dlgitem_set_branch_image_at
ret = dlgitem_set_branch_image_at(window, listtag, row, image)
Associates an ACL Designer image resource image with the outline list entry row in the
outline list listtag in window. The image appears at the front of the list item. Use this
specific function to set the image for list items that have children. If you were to create a file
browser using an outline list, you may use folder and disk drive icons as your branch images. If
listtag does not refer to an outline list list tag, $ERROR is set and zero (0) is returned.
Otherwise, one (1) is returned.
The window parameter is a window identifier. The listtag parameter is an outline list list
tag (case sensitive). The row parameter is an offset into listtag (starting from one). The
image parameter specifies the ACL Designer image resource to place at the front of the list
item.
Example
ret = dlgitem_set_branch_image_at(win, "Hierarchy", 3, "Folder")
sets the image for the third item in the outline list item Hierarchy to the Folder image.

dlgitem_set_extra_image_at
ret = dlgitem_set_extra_image_at(window, listtag, row, image)
Associates a second ACL Designer image resource image with the outline list entry row in the
outline list listtag in window. The image appears at the front of the list item, just to the
right of the leaf image set by the dlgitem_set_leaf_image_at function. If listtag
does not refer to an outline list list tag, $ERROR is set and zero (0) is returned. Otherwise, one
(1) is returned.
The window parameter is a window identifier. The listtag parameter is a outline list list tag
(case sensitive). The row parameter is an offset into listtag (starting from one). The image
parameter specifies the second ACL Designer image resource to place at the front of the list
item.
Example
ret = dlgitem_set_extra_image_at(win, "Hierarchy", 3, "Padlock")
sets the image for the third item in the outline list item Hierarchy to the Padlock image.

dlgitem_set_leaf_image_at
ret = dlgitem_set_leaf_image_at(window, listtag, row, image)
Associates an ACL Designer image resource image with the outline list entry row in the
outline list listtag in window. The image appears at the front of the list item. If listtag
does not refer to an outline list list tag, $ERROR is set and zero (0) is returned. Otherwise, one
(1) is returned.
The window parameter is a window identifier. The listtag parameter is an outline list list tag
(case sensitive). The row parameter is an offset into listtag (starting from one). The image
parameter specifies the ACL Designer image resource to place at the front of the list item.
162 Chapter 15 ACL Designer ACL Functions

Example
ret = dlgitem_set_leaf_image_at(win, "Hierarchy", 3, "File")
sets the image for the third item in the outline list item Hierarchy to the File image.

dlgitem_set_refresh
ret = dlgitem_set_refresh(window, dlgitem, refreshstatus)
Activates or deactivates the automatic refresh for outline list dlgitem in window. Turning
off the refresh is good if you are executing a routine which would redraw the list several times
(e.g., fill the list, resort the list, etc.). If dlgitem does not refer to an outline list list tag,
$ERROR is set and zero (0) is returned. Otherwise, one (1) is returned.
The window parameter is a window identifier. The dlgitem parameter is an outline list name
(case sensitive). The refreshstatus parameter sets the refresh/no refresh status of the list
entry (1=refresh; 0=no-refresh).
Example
ret = dlgitem_set_refresh(win, "Filelist", 0)
deactivates automatic refresh for the outline list Filelist.
Index B
Background color 142
dialog item attribute 79
dialog items 79
drawing with Image Editor 121
Background colors 142
Symbols Basic resources 17
.vr extension 17 arrays 41
editing contents 45
Before you begin
on UNIX platforms 3
A Binary directories, adding to search path 7
Blend color palette option 126
ACL Designer 1
BMP image format 91
Dialog Editor 26
Border dialog item attribute 78
Dictionary Editor 24
Box dialog item 89
Main Window 24
Bring To Front/Bring Forward Commands 61
preferences 21
Button item 81
quitting 19
resource editors 25
starting 18
ACLDESHOME environment variable 14 C
Add Resource Types Dialog 47
Add Resource Types dialog 56, 80 Cancel
Adding color palette option 126
dialog items to dialogs 26 CD-ROM
elements to a dictionary array 42 extracting files from (UNIX) 5
elements to an array resource 42 installing from (PC) 11
resources to a dictionary or a Dialog Panel 48 CD-ROMsharing (PC) 9
resources to the New Menu 47 Chains
Additive primary colors 137 series of connections 66
ADEPT program icon Changing
creating on OS/2 13 connections 70, 73
ADEPTdirectory, creating 4 current directory 144, 147
AIX tabbing order for a dialog 62
extracting files on 5 Choosers 31
Alignment commands Add Resource Types dialog 47, 80
dialog items 61 Color Chooser 131
Alternate File Menus preference 19, 36 File Chooser 143
Applications Font Chooser 80, 129
user interfaces 15 Style Chooser 87
Arranging Class names 47
items in a dialog 60 Class-based composite resources 17
Array resource Classes
adding elements 42 searching 48
Arrays 17 Clear command 37
basic resources 41 Click-Focusable dialog item attribute 78
dictionary 42 Client/server installation (PC) 8
Automatic file saving preference 23 Close Editor command 34
CMY color model 104, 132, 137
Color Chooser 31, 131

163
164 Index

Color models 104, 132 Connections 65

CMY 137 changing 70, 73
Grayscale 139 combination spring/strut 66, 72
RGB 137 displaying 73
Color Palette Editor 125 following 74
Color palettes 124 inside 65
modifying 125 natural size 72
options 125 outside 65
saving 126 resetting 73
viewing 125 Container Attributes Panel 97
Color tolerances 132 Container Editor 95
Colors Container Panel 95
additive primary 137 Containers 95
background color for drawing 121 exclusive group 97
color tolerances 132 grouped 97
dithered 132 placing items 59
dragging and dropping 142 removing items 59
foreground and background 142 Contrast color palette option 126
foreground color for drawing 121 Control dialog items 83
named colors 132, 140 Control Panel 84
specifying colors 131 Cooler color palette options 126
subtractive primary 137 Copy command 37
Commands Copying resources 47
aligning dialog items 61 Create Check Item items 111
Bring To Front/Bring Forward 61 Create Group Item items 111
Clear 37 Create Submenu Item items 112
Close Editor 34 Creating
Copy 37 cursors 128
Cut 37 cursors for dialog items 80
Duplicate 37 dialogs 55
Open File 34 images 115, 119
Paste 37 images for dialog items 80
Quit 35 menus for dialog items 79
Redo 37 resource files 20
Revert Editor 35 resources 40
Save File 34 subclassed resources 48
Save File As... 35 Current directory 146
Save Template 35, 48 changing 144
Select All 58 Current path 145
Select Next Entry 44 Cursor Editor 30, 127
Select Parent 44 Cursors 127
Select Previous Entry 44 dialog item attribute 79
Send to Back/Send Backward 61 Cut command 37
Undo 37
Composite resources 17
Confirm Attributes Panel 106
Confirm dialog 105
Confirm Editor 106
Confirm Panel 106
Connection menu 72
Connection Window 30, 69
 Index 165

D Directories
displaying several 146
Darker color palette option 126 filtering 145
Default attributes 33 history list 144
Delete color palette option 126 marking 145
Dialog Editor 26, 51 sorting 145
opening 52 Disabled menu attribute 111
panels 52 Diskettes, installation 11
Dialog item creating 9
attributes 104 Display names 47
Dialog Item Panel 28, 76 Displaying
Dialog Items connections 73
placing in dialog fromItem Palette 56 connections for an item 67
Dialog items 75 dlgitem_set_active_at function 160
aligning in dialog 61 dlgitem_set_appdata_at function 160
attributes 78 dlgitem_set_branch_image_at function 161
button 81 dlgitem_set_extra_image_at function 161
chaining in dialog 74 dlgitem_set_leaf_image_at function 161
connections 65 dlgitem_set_refresh function 162
control 83 Documentation
default attributes 80 conventions 12
editing 57 Dragging and dropping colors 142
exclusive group 82 Drawing
label 81 line width 122
menu bar 89 setting colors 120
option menu 109 Dropper tool
repositioning 61 Image Editor 119
setting attributes 59 Duplicate command 37
sizing in the Dialog Panel 60
Dialog Panel 26, 51
Edit Menu 58
sizing dialog items 60 E
Dialogs
Edit Menu 36
arranging items 60
Dialog Panel 58
confirm 105
Editing
creating 55
color palettes 125
notice 107
dialog items 57
setting window attributes 53
panels 33
testing 64
resources 44
DIB image format 91
Editors
Dictionaries 17
color palette 125
viewing 43
Cursor Editor 127
Dictionary arrays 42
Image Editor 115
Dictionary editor 24, 39
Ellipse tool
customizing the view 48
Image Editor 119
Digital UNIX
Enable dialog item attribute 78
extracting files on 5
Environment variables
ACLDESHOME 14
LIBPATH 14
Eraser tool
Image Editor 119
Erasing 124
166 Index

Exclusive group containers 97 H

Exclusive group item 82
Exclusive Group Panel 82 Hand tool
Expanded views 44 Image Editor 119
Exporting images 116 History list
Extracting tar files 5 directories 144
HLS color model 104, 132
HP-UX
extracting files on 5
F
File Chooser 16, 31, 143
File Menu 34 I
alternate File Menus 36
Files ICO image format 91
filtering 145 Icon Palette
generating source code files 48 icons 55
opening 143 Icons
Fill tool Icon Palette 55
Image Editor 119 resource file 21
Filled Ellipse tool Icons, creating (OS/2) 13
Image Editor 119 Image dialog item 90
Filled Rectangle tool Image dialog item attribute 79
Image Editor 120 Image Editor 30, 115
Filtering Cursor Editor 30
directories 145 Image formats 91
Finding Image Mask dialog item attribute 78
resources 46 Images
Focusable dialog item attribute 78 adding text 122
Font Chooser 31, 129 creating 115, 119
Font dialog item attibute 79 importing and exporting 116
Fonts saving views 118
dragging and dropping 130 setting the size 116
Foreground color 142 transparency 127
dialog item attribute 79 Importing images 116
dialog items 79 Inside connections 65
drawing with Image Editor 121 Install color palette option 126
Installation
creating diskettes (PC) 9
on OS/2 12
G Installation files, copying to server (PC) 7
Installing
Generating
UNIX login 4
source code files 48
IRIX
GIF image format 91
extracting files on 5
Grayscale color model 104, 132, 139 italics in pathnames 12
Grouped Container Panel 98
Item Palette 26, 52, 55, 75
Grouped containers 97
changing the view 55
customizing 63
default dialog items 80
dialog items 55
reopening 55
 Index 167

Items N
aligning in dialog 61
button 81 Named colors 132, 140
chaining in dialog 74 Natural size struts 72
exclusive group 82 Natural-sized items 66
label 81 New color palette option 125
menu bar 89 Notice dialog 107
minimum spacing in dialog 66 Notice Panel 108
placing in containers 59 Numeric spinners 99

L O
Label item 81 Open File command 34
Lasso tool Opening
Image Editor 119 Dialog Editors 52
Lighter color palette option 126 existing resource files 20
Line item 98 files 143
Line tool Item Palette 55
Image Editor 119 resource files 20
Line width 122 Option menu dialog item 109
List dialog item 91 Order Items Panel 62
List Editor 92 OS/2
List Item Panel 93 ACLDESHOME environment variable 14
List View Panel 92 creating program icons 13
Login, for UNIX install 4 installing on 12, 13
LIBPATH environment variable 14
Outside connections 65
Overview of resource editors 33
M
Main Window 24
Marking directories 145 P
Menu attributes 111
Menu bar dialog item 89 Palettes
Menu Bar Editor 89 color 124
Menu Bar Panel 89 installing 127
Menu bars 109 Item 75
Menu dialog item attibute 79 modifying 125
Menu group 112 Tool Palette for Image Editor 119
Menu Item List 113 Panels
Menu items 109, 111 Dialog Item 76
Menu Panel 29, 110 Exclusive Group 82
Menus 109 resource editors 33
pop-up 109 Text View 86
testing 113 Panels Menu 38
Mnemonic Paste command 37
dialog item attribute 78 PBM image format 91
menu attribute 111, 112 Pencil tool
menu item attribute 112 Image Editor 119
Mounting, CD-ROM 5 Permissions, for UNIX install 4
Moving resources 47 PGM image format 91
Pick color palette option 126
168 Index

Pinnable menu attribute 111 S

Popdown combo 94
Pop-up menus 109 Save File As... command 35
PPM image format 91 Save File command 34
Preferences 21 Save Template command 35, 48
alternate File Menus 19, 36 Save window position preference 23
automatic file saving 23 Select All command 58
Save window position 23 Select Next Entry command 44
Primary colors 137 Select Parent command 44
Select Previous Entry command 44
Selecting
connections for editing 67
Q fonts for dialog items 80
Selection tools
Quit command 35
Image Editor 119, 122
Quitting ACL Designer 19, 35 Send To Back/Send Backward commands 61
Separator items 111
Setting
R colors 120
image size 116
Ramp color palette option 126 strut length 71
Rectangle tool Show Position command 118
Image Editor 119 Solaris
Redo command 37 extracting files on 5
Remap to Closest Color color palette option 126 Sorting
Resetting directories 145
connections 73 Spin box 99
Resource editors 25, 33 Spinner Panel 99
menus 34 Spinners
opening 76 numeric 99
panels 33 text 100
Resource files 17 Spray Can tool 119
filtering 145 Spring solution 65
icons 21 Springs and Struts 65
opening 20 minimum length 66
Resources 17 Starting ACL Designer 18
adding to the New Menu 47 Struts 65
array of resources 17 setting length 71
basic 17 Style Chooser 85, 87
class-based 17 Subclassed resources 48
copying 47 Subtractive primary colors 137
creating 40 SunOS
editing 44 extracting files on 5
finding 46
searching by class 48
type-based 17
viewing 43 T
Revert Editor command 35
Tag menu attribute 111
RGB color model 104, 132, 137
Tag names 45, 77, 104
Root 4, 5
Testing
dialogs 64
menus 113
 Index 169

Text X
adding to images 122
Text Item Panel options 86 XBM image format 91
Text spinner 100
Text Spinner Panel 100
Text tool 119
Text View Panel 86
Text View Panel options 87
Title menu attribute 111
Title names 77
Titles 104
Tool Palette
Image Editor 119
Tools
drawing 120
Try Dialog command 65
Try Out Menu command 113
Trying out dialogs 65
Type-based composite resources 17

U
Undo command
resource editors 37
Undoing changes 124
User interfaces 15
Using Undo 124

V
View Menu commands 118
Viewing
dictionaries 43
images 123
Visible dialog item attribute 78
vobjectInheritance Dictionary 49

W
Warmer color palette option 126
Window attributes
setting for dialogs 53
Window Panel 53, 103, 109
attributes 105
Window resource 103
Windows
overview 103
170 Index