home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
VSCPPv4.zip
/
VACPP
/
IBMCPP
/
HELP
/
CPPVBUG.INF
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
1995-06-01
|
2MB
|
13,258 lines
ΓòÉΓòÉΓòÉ 1. About This Book ΓòÉΓòÉΓòÉ
Welcome to Visual Builder!
Notices
Trademarks
Highlighting conventions
How to use the Contents
How to obtain additional information
How to use action bar choices
- Placing bookmarks
- Searching for information
- Printing information
- Copying information to a file
How to cut and paste examples
Other information you might find helpful
- Related information
Communicating Your Comments to IBM
ΓòÉΓòÉΓòÉ 1.1. Welcome to Visual Builder! ΓòÉΓòÉΓòÉ
Welcome to Visual Builder-the quickest and easiest way to create applications
using the C++ programming language! This book, Visual Builder User's Guide,
introduces parts, tools, and features that you can use to build Visual Builder
applications.
Visual Builder is a tool provided by VisualAge C++. It is based on the
construction-from-parts paradigm, a software development paradigm in which
applications are assembled from reusable and existing software components,
called parts. You can extend Visual Builder by adding your own reusable, custom
parts and then using these parts in your applications as you need them.
Visual Builder gets you started by providing a set of parts as well as
interactive visual programming tools to work with those parts. You create your
applications by visually assembling and connecting these prefabricated parts.
In many cases, you do not even have to write any code.
Programmers who want to develop C++ applications using Visual Builder should
read this book. Knowledge of object-oriented (OO) concepts, although not
required unless you are interested in extending the Visual Builder parts to
include your own parts, is highly recommended. This product incorporates OO
concepts and knowledge of them will allow you to get the maximum use from the
product, as well as an understanding of the terminology used in this book.
If you are new to Visual Builder, read through the first section completely. If
you have used Visual Builder before, you can skim that section.
You will find shortcut techniques and other tips wherever you see
Before you begin to use this information, it would be helpful to understand how
to navigate through it. You can use the Table of Contents and Index facility to
locate topics and the Search facility to search the text of this document. You
can use hypertext links to acquire related information on the current topic.
Hypertext links appear in a different color (which you can customize using the
OS/2 Scheme Palette). For example, here is a link to another panel:
Communicating Your Comments to IBM. By double-clicking on the text of the link
or by pressing Enter on a highlighted link, you will open a panel of related
information. When you open a panel, the first link has the focus; to shift the
focus to other links, use the Tab key.
We encourage you to double-click on the graphics. Many of these graphics are
hyperlinks to additional information, much like a hypertext links.
Wherever you see , you can add your own personal notes and comments to this
book. Double-click on it to start the system editor (or any E.EXE program that
is found in your PATH). You can type your notes into the file and save them for
later retrieval. There is one note file for each section of the book.
Note: DO NOT change the default name given to the file in which notes are
stored. If you change the name of this file, you cannot reopen it.
Shortcut techniques and other tips are provided wherever you see .
You should also understand:
How to Use the Contents
How to Obtain Additional Information
How to Use Action Bar Choices
How to Cut and Paste Examples
ΓòÉΓòÉΓòÉ 1.2. Notices ΓòÉΓòÉΓòÉ
Copyright International Business Machines Corporation, 1992, 1995. All rights
reserved.
Note to U.S. Government Users - Documentation related to restricted rights -
Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP
Schedule Contract with IBM Corp.
First Edition, June 1995.
This edition applies to Version 3.0 of VisualAge C++ for OS/2 (30H1664,
30H1665, 30H1666) and to all subsequent releases and modifications until
otherwise indicated in new editions. Make sure you are using the correct
edition for the level of the product.
This publication could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; any such changes will
be reported in subsequent revisions.
Requests for publications and for technical information about IBM products
should be made to your IBM Authorized Dealer or your IBM Marketing
Representative.
When you send information to IBM, you grant IBM a nonexclusive right to use or
distribute the information in any ways it believes appropriate without
incurring any obligation to you.
Any reference to an IBM licensed program in this publication is not intended to
state or imply that only IBM's licensed program may be used. Any functionally
equivalent product, program, or service that does not infringe any of IBM's
intellectual property rights may be used instead of the IBM product, program,
or service. Evaluation and verification of operation in conjunction with other
products, except those expressly designated by IBM, is the user's
responsibility.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license
to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY, 10594
USA
This publication contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include
the names of individuals, companies, brands, and products. All of these names
are fictitious and any similarity to the names and addresses used by an actual
business enterprise is entirely coincidental.
ΓòÉΓòÉΓòÉ 1.3. Trademarks ΓòÉΓòÉΓòÉ
The following terms are trademarks of the IBM Corporation in the United States
or other countries:
BookManager
Common User Access
CUA
IBM
IBMLink
Library Reader
Open Class
OS/2
OS/2 Warp
Presentation Manager
PROFS
VisualAge
WorkFrame
Workplace Shell
The following term is a trademark of another company:
C++ American Telephone & Telegraph Company
ΓòÉΓòÉΓòÉ 1.4. Highlighting Conventions ΓòÉΓòÉΓòÉ
This book uses the following highlighting conventions:
Highlighting Element Example
Bold Key interface items in code Select Tools from the menu bar.
listings. Areas in code examples
that are described in
accompanying text
Monospace C++ coding examples, text that The following code from the
the user enters, and messages IAddress illustrates ...
(within text)
The street member function
returns the current street.
Italics Emphasis of words, first time a stored in persistent objects
glossary term is used
Refer to Object-Oriented User
Titles of books Interface Design - IBM Common
User Access Guidelines.
ΓòÉΓòÉΓòÉ 1.5. How to Use the Contents ΓòÉΓòÉΓòÉ
When the Contents window first appears, some topics have a plus (+) sign beside
them. The plus sign indicates that additional topics are available.
To expand the Contents if you are using a mouse, click on the plus sign. If
you are using the keyboard, use the Up or Down arrow key to highlight the
topic, and press the plus (+) key. For example, How to Use the Contents has a
plus sign beside it. To see additional topics for that heading, click on the
plus sign or highlight that topic and press the plus (+) key.
To view a topic, double-click on the topic (or press the Up or Down arrow key
to highlight the topic, and then press the Enter key).
ΓòÉΓòÉΓòÉ 1.6. How to Obtain Additional Information ΓòÉΓòÉΓòÉ
After you select a topic, the information for that topic appears in a window.
Highlighted words or phrases indicate that additional information is available.
Certain words and phrases are highlighted in a different color from the
surrounding text. These are called hypertext terms.
If you are using a mouse, double-click on the highlighted word. If you are
using a keyboard, press the Tab key to move to the highlighted word, and then
press the Enter key. Additional information then appears in a window.
ΓòÉΓòÉΓòÉ 1.7. How to Use Action Bar Choices ΓòÉΓòÉΓòÉ
Several choices are available for managing the information presented in this
document. There are three menus on the action bar: the Services menu, the
Options menu, and the Help menu.
The actions that are selectable from the Services menu operate on the active
window currently displayed on the screen. These actions include the following:
Placing bookmarks
You can set a placeholder so you can retrieve information of interest to
you.
Searching for information
You can find occurrences of a word or phrase in the current topic, selected
topics, or all topics.
Printing information
You can print one or more topics. You can also print a set of topics by
first marking the topics in the Contents list.
Copying information to a file
You can copy a topic that you are viewing to the System Clipboard or to a
file that you can edit. This method is particularly useful for copying
syntax definitions and program samples into the application that you are
developing.
Using the actions that are selectable from the Options menu, you can change
the way your Contents list is displayed. To expand the Contents and show all
levels for all topics, choose Expand all from the Options pull-down. You can
also press the Ctrl and * keys together.
The actions that are selectable from the Help menu allow you to select
different types of help information.
For information about any of the menu choices, highlight the choice in the
menu and press F1.
ΓòÉΓòÉΓòÉ 1.7.1. Placing Bookmarks ΓòÉΓòÉΓòÉ
When you place a bookmark on a topic, it is added to a list of bookmarks you
have previously set. You can view the list, and you can remove one or all
bookmarks from the list. If you have not set any bookmarks, the list is empty.
To set a bookmark, do the following:
1. Select a topic from the Contents.
2. When that topic appears, select the Bookmark option from the Services
menu.
3. If you want to change the name used for the bookmark, type the new name
in the field.
4. Click on the Place radio button (or press the Up or Down arrow key to
select it).
5. Click on OK (or select it and press Enter). The bookmark is then added to
the bookmark list.
ΓòÉΓòÉΓòÉ 1.7.2. Searching for Information ΓòÉΓòÉΓòÉ
You can specify a word or phrase to be searched. You can also limit the search
to a set of topics by first marking the topics in the Contents list.
To search for a word or phrase in all topics, do the following:
1. Select the Search option from the Services menu.
2. Type the word or words to be searched for.
3. Click on All sections (or press the Up or Down arrow keys to select it).
4. Click on Search (or select it and press Enter) to begin the search.
5. The list of topics where the word or phrase appears is displayed.
ΓòÉΓòÉΓòÉ 1.7.3. Printing Information ΓòÉΓòÉΓòÉ
You can print one or more topics, the index, or the table of contents. Make
sure that your printer is connected to the serial port, configured correctly,
and ready for input. To print:
1. Select Print from the Services pull-down.
2. Select what you want to print. Note that the This section and Marked
sections choices are only available if you are viewing a topic or if you
have marked topics, respectively. To mark topics in the table of
contents, press the Ctrl key and click on the topics, or use the arrow
keys.
3. Select Print to print what you've chosen on your printer.
ΓòÉΓòÉΓòÉ 1.7.4. Copying Information to a File ΓòÉΓòÉΓòÉ
You can copy a topic that you are viewing in two ways:
Copy copies the topic that you are viewing into the System Clipboard. If
you are using a Presentation Manager (PM) editor (for example, the
Enhanced Editor) that copies or cuts (or both) to the System Clipboard,
and pastes to the System Clipboard, you can easily add the copied
information to your program source module.
Copy to file copies the topic that you are viewing into a temporary file
named TEXT.TMP. You can later edit that file by using any editor.
TEXT.TMP is placed in the directory where your viewable document resides.
To copy a topic, do the following:
1. Expand the Contents list and select a topic.
2. When the topic appears, select Copy to file from the Services menu.
3. The system puts the text pertaining to that topic into the temporary file
TEXT.TMP.
ΓòÉΓòÉΓòÉ 1.8. How to Cut and Paste Examples ΓòÉΓòÉΓòÉ
You can copy examples (or information) from this reference/guide/book to
compile, link, and run them, or to paste them into your own code.
To copy an example or information:
1. Make the topic you want to copy the active window.
2. From the Services menu, select Copy to file. The text in that topic is
placed in the temporary file TEXT.TMP, in the same directory as this
reference.
3. You can then modify or use TEXT.TMP as you want.
Note: Because the system copies the entire contents of the topic to the file,
you may need to edit it to remove additional text. Most examples in this
reference are ready to compile, link, and run as they appear, and do not
require any editing.
ΓòÉΓòÉΓòÉ 1.9. Other Information You Might Find Helpful ΓòÉΓòÉΓòÉ
This product provides a number of online guides and references that we hope you
find helpful as you develop applications. This information includes user's
guides, references, and How Do I? help that gives you specific instructions for
performing common tasks. You can get to this online information from the
Information folder inside the main product folder. You can also get to it from
the Help menu in any of the components of the product.
ΓòÉΓòÉΓòÉ 1.9.1. Related Information ΓòÉΓòÉΓòÉ
The following publications can help you find more information on OO software
design and Common User Access (CUA) user interface design. Double click on a
category to see a list of book titles that pertain to that category.
OO programming and design
User interface
ΓòÉΓòÉΓòÉ 1.9.2. OO Programming and Design ΓòÉΓòÉΓòÉ
Booch, Grady. Object Oriented Design with Applications.
Cox, Brad J. Object-Oriented Programming: An Evolutionary Approach.
ΓòÉΓòÉΓòÉ 1.9.3. User Interface ΓòÉΓòÉΓòÉ
Object-Oriented Interface Design - IBM Common User Access Guidelines.
Rubenstein, R. and Hersch, H. The Human Factor: Designing Computer
Systems For People.
ΓòÉΓòÉΓòÉ 1.10. Communicating Your Comments to IBM ΓòÉΓòÉΓòÉ
If there is something you like or dislike about this book, please let us know.
You can use one of the methods listed below to send your comments to IBM.
Please be sure to include the complete title of the publication that you are
commenting on.
The comments you send should only pertain to the information in this document
and its presentation. To request additional publications or to ask questions
or make comments about the functions of IBM products or systems, you should
talk to your IBM representative or your authorized IBM remarketer.
When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate without incurring
any obligation to you.
You can send your comments to IBM in the following ways:
By mail to the following address:
IBM Canada Ltd. Laboratory
Information Development
2G/345/1150/TOR
1150 EGLINTON AVENUE EAST
NORTH YORK, ONTARIO
CANADA M3C 1H7
By FAX to the following number:
- United States and Canada: (416) 448-6161
- Other countries (+1) 416-448-6161
By electronic mail to one of the following IDs. Be sure to include your
entire network address if you want a reply.
- Internet: torrcf@vnet.ibm.com
- IBMLink: toribm(torrcf)
- IBM/PROFS: torolab4(torrcf)
- IBMMAIL: ibmmail(caibmwt9
ΓòÉΓòÉΓòÉ 2. Getting Started ΓòÉΓòÉΓòÉ
What Is Visual Builder?
What are the benefits of using Visual Builder?
What are the key concepts?
Personal notes:
ΓòÉΓòÉΓòÉ 2.1. What is Visual Builder? ΓòÉΓòÉΓòÉ
Visual Builder is a visual programming tool that can help you create
object-oriented (OO) programs using the C++ programming language. With Visual
Builder, you can create applications faster and easier than you ever could
using a text editor. Visual Builder provides a powerful visual editor, the
Composition Editor, which enables you to create complete applications, often
without writing code.
ΓòÉΓòÉΓòÉ 2.2. What Are the Benefits of Using Visual Builder? ΓòÉΓòÉΓòÉ
With Visual Builder, you can quickly create applications with advanced
graphical user interfaces (GUIs). You can use Visual Builder to build OO
applications by assembling and connecting parts.
Visual Builder is part of VisualAge C++, a state-of-the-art C++ application
development product that includes the IBM Open Class Library, WorkFrame, code
browsing and editing tools, and a sophisticated debugger.
With Visual Builder, you can adopt OO technology immediately and learn to use
it at the pace that is best for you. Its benefits include the following:
When you work with Visual Builder's visual programming tools, you are
creating OO applications.
You can use Visual Builder to enhance and extend your applications
because Visual Builder supports C++, an OO programming language.
You can also access other logic written in C and C++ using Visual
Builder's support for external C and C++ program logic.
You can shorten your application development cycle time considerably by
creating reusable parts.
You can change the way a part does its work without affecting its
external interface by encapsulating your application into parts.
Encapsulating your application into parts also helps you deploy your
business logic where it needs to be. Critical calculations can be moved
into a dynamic link library.
By its nature, Visual Builder caters to all skill levels, so that
programmers using Visual Builder can build not only simple applications
but also complex ones.
ΓòÉΓòÉΓòÉ 2.3. What Are the Key Concepts? ΓòÉΓòÉΓòÉ
Before we continue any further, let's look at some key Visual Builder concepts.
Parts
In Visual Builder, a part is a C++ class that, in addition to the usual
elements of a C++ class, includes a well-defined part interface. The part
interface defines how the part can interact with other parts.
Three kinds of features make up a part interface. The following list provides a
brief description of each kind:
attributes The logical data, often stored in data members, that other parts
can access. This data can represent any logical property of a
part, such as the balance of an account, the size of a shipment,
or the text of a push button.
actions Services or operations that a part can perform. Actions, such as
placing an order or displaying a window, can be triggered by
connections from other parts.
events Signals that a part can send to notify itself or other parts that
a change has occurred. When events are connected to attributes,
actions, or member functions of other parts, the connections
monitor these events and trigger the target features when the
events occur. For example, when a push button's buttonClickEvent
feature is connected to an action of another part, the other
part's action is called when the push button is clicked.
To get you started, Visual Builder provides a set of base parts for you. These
parts are included in the vbbase.vbb file, which Visual Builder loads each
time it is started. The parts in this file are based on the classes in the IBM
Open Class Library. Visual Builder does not allow you to modify these parts,
but you can create parts of your own by subclassing or using these parts in
parts that you create.
Connections
To define how the parts interact with each other, you can make the following
kinds of connections. The definitions that follow apply to most cases in which
these connections are used. Exceptions and special cases are noted in Learning
to Use Connections
Attribute-to-attribute Connections that link two data values
together so that when one changes, the
other changes, too.
Event-to-attribute Connections that change the value of an
attribute when a certain event occurs.
Event-to-action Connections that start an action when a
certain event occurs.
Attribute-to-action Connections that start an action whenever
an attribute's event identifier is
signalled.
Event-to-member function Connections that call a member function
whenever a certain event occurs.
Attribute-to-member function Connections that call a member function
whenever an attribute's event identifier is
signalled.
Custom logic Connections that call your customized C or
C++ logic whenever an event or an
attribute's event identifier is signalled.
Parameter Connections that provide a parameter value
for an action or member function. The
parameter value can be provided by
connecting a parameter to an attribute, an
action, a member function, or custom logic.
Source code generation
Visual Builder can generate C++ code for the GUI that you design in the
Composition Editor, as well as for all of the connections that you make
between parts. It can also generate C++ code for any new parts that you
create. You can then use the code that Visual Builder generates when building
your application. This capability allows you to concentrate on what your
application does instead of spending time writing code for the GUI and its
connections.
Besides saving you time and effort, additional advantages of letting Visual
Builder generate your code instead of writing it yourself include the
following:
Easier code modifications.
Do you want to replace a multiline entry field with a list box? Delete
the entry field, drop the list box in its place, make any necessary
connections, and regenerate the code. That's all.
Fewer errors.
Because Visual Builder can generate the majority of the code for your
application, there is less opportunity for human errors, such as
typographical and syntax errors, to creep into your code. That means you
spend less time debugging your code for minor errors.
Support for pre-existing C and C++ code.
Using Visual Builder's Class Editor, you can specify files that contain
existing C or C++ code that you want to use in your application. Then,
when you generate the code for your application, those files are
included.
In addition, you can create .vbe files that contain information about
your C++ classes. You can then import that information into Visual
Builder so that you can use those classes as parts. Refer to Building
VisualAge C++ Parts for Fun and Profit for information about using .vbe
files.
Standard format.
Another advantage is that a standard format is applied to all generated
code. The code that Visual Builder generates is uniformly structured,
indented, and commented.
ΓòÉΓòÉΓòÉ 3. Creating a Simple Visual Builder Application ΓòÉΓòÉΓòÉ
What you will achieve
Creating the To-Do List application
Personal notes:
ΓòÉΓòÉΓòÉ 3.1. What You Will Achieve ΓòÉΓòÉΓòÉ
The best way to learn about Visual Builder is to see how you can use it. The
following sections take you through an example of how you might use Visual
Builder to develop an application for creating and maintaining a simple to-do
list. Here is what the application looks like when it is finished:
Now it is time to create the To-Do List application.
ΓòÉΓòÉΓòÉ 3.2. Creating the To-Do List Application ΓòÉΓòÉΓòÉ
Creating the To-Do List application consists of the following steps:
Starting Visual Builder for the To-Do List application
Creating a new visual part for the To-Do List application
Placing parts in the application window
Resizing and aligning the parts
Connecting the parts
Generating the C++ code for your application
Building the application
Running the application
Exiting the Composition Editor and Visual Builder
Personal notes:
ΓòÉΓòÉΓòÉ 3.2.1. Starting Visual Builder for the To-Do List Application ΓòÉΓòÉΓòÉ
Before you create the To-Do List application, start Visual Builder. For this
sample application, start Visual Builder from the Tools folder, as follows:
1. Double-click on the VisualAge C++ folder icon on your desktop.
The VisualAge C++ folder opens.
2. Double-click on the Tools folder icon.
The Tools folder opens.
3. Double-click on the Visual Builder icon.
Visual Builder displays the Visual Builder window, as shown in the
following figure.
Now it is time to create a new visual part for the To-Do List application.
ΓòÉΓòÉΓòÉ 3.2.2. Creating a New Visual Part for the To-Do List Application ΓòÉΓòÉΓòÉ
Before you create your new visual part for the To-Do List application, set the
option for generating make files by selecting OptionsGenerate make files.
Otherwise, when you finish the application and generate the code, Visual
Builder will not generate the make file. By selecting this option now, you will
not have to come back to the Visual Builder window to select it later.
The next thing to do when creating the To-Do List application is to create the
main part, a new visual part, as follows:
1. Select PartNew.
Visual Builder displays the Part - New window, as shown in the following
figure:
The Part - New window provides the following fields in which you can
enter information about your part:
The Class name field, where you enter the name of your part. Each
composite part must have a name.
For the To-Do List application, enter the following:
ToDoList
The Description field, where you enter a description of your part.
For this example, enter the following:
The To-Do List application
The File name field, where you enter the name of the .vbb file in
which you want Visual Builder to store your part.
For this example, you can either leave this field blank or enter the
following:
ToDoList.vbb
This causes Visual Builder to store the ToDoList part in a file
named todolist.vbb. If you leave this field blank, Visual Builder
uses the part name as the name of the .vbb file by default, so the
result is the same.
The Part type field, where you indicate the type of part. This field
initially contains Visual part. However, you can specify a different
type of part to create by selecting one from the field's drop-down
list box.
For this example, do not select a different part type because you
want to create a visual part for the To-Do List application.
The Base class field, where you specify the class that you want to
be the base class of the part that you are creating. The base class
is the part that part you are creating inherits attributes, events,
and actions from. The Base class field contains the default base
class name of IFrameWindow, which Visual Builder uses when you
specify that you want to create a new visual part.
For this example, leave IFrameWindow as the base class.
2. Select the Open push button to create a visual part named ToDoList whose
parent is IFrameWindow. This causes Visual Builder to display the
Composition Editor. For more information about the Composition Editor,
see Touring the Composition Editor.
If you look back at the Visual Builder window, you see that the file
todolist.vbb is now included in the list of loaded files. This file was
created for you when you selected the Open push button in the Part - New
window.
Before you place any parts in the application window, first edit its title.
Changing the title of the To-Do List application window
The new visual part that you just created contains an IFrameWindow* part. This
will be the To-Do List application window. Change the title of this window by
doing the following:
1. Hold down the Alt key.
2. Click on the title bar with mouse button 1.
3. Type the new title text, such as To-Do List.
4. Press Shift+Enter after you have changed the window title.
ΓòÉΓòÉΓòÉ 3.2.3. Placing Parts in the Application Window ΓòÉΓòÉΓòÉ
Now that you have created your new visual part and edited the title of the
application window, it is time to place the other parts of the To-Do List
application in the application window.
Placing a static text part in the window
The To-Do List application needs two static text parts. Follow these steps to
place the first static text part in the To-Do List application window:
1. Select , the Data entry category, from the row of icons on the left-hand
side of the parts palette.
2. Select , the IStaticText* icon, from the row of icons on the right-hand
side of the parts palette.
When you move the mouse pointer over the free-form surface, you see that
it has changed to crosshairs. This means the mouse pointer is loaded with
the IStaticText* part.
3. Place the crosshairs in the upper-left corner of the To-Do List
application window's client area and click mouse button 1.
A static text part is placed in the window.
4. Change the text of the static text part to To-do item. Use the same
method for changing text that you learned previously when you changed the
title of the To-Do List application window.
Placing an entry field in the window
The To-Do List application needs an entry field part. Follow these steps to
place an entry field part in the To-Do List application window:
1. Select , the Data entry category, from the row of icons on the left-hand
side of the parts palette.
2. Select , the IEntryField* icon, from the row of icons on the right-hand
side of the parts palette.
3. Place the crosshairs beneath the first static text part and click mouse
button 1.
The entry field part is placed beneath the static text part.
Placing another static text part in the window
The To-Do List application needs another static text part. Follow these steps
to place and modify this part:
1. Place the second static text part in the To-Do List application window.
Use the same method for placing a static text part that you learned
previously when you placed the first static text part in the To-Do List
application window.
2. Change the text of the static text part to To-do list. Use the same
method for changing text that you learned when you changed the title of
the To-Do List application window.
Placing a list box in the window
Because the to-do list is to consist of a list of text strings, you want to
store that list in an IListBox* part. Follow these steps to place a list box
part in the To-Do List application window:
1. Select , the Lists category, from the row of icons on the left-hand side
of the parts palette.
2. Select , the IListBox* icon, from the row of icons that Visual Builder
displays on the right-hand side of the parts palette.
3. Place the crosshairs below the second static text part and click mouse
button 1.
The list box part is placed beneath the second static text part.
Placing the push buttons in the window
The To-Do List application needs two push buttons, one for adding items to the
list and one for removing items from the list. Follow these steps to place two
push button parts in the To-Do List application window:
1. Select , the Buttons category, from the row of icons on the left-hand
side of the parts palette.
2. Select , the IPushButton* icon, from the row of icons on the right-hand
side of the parts palette.
3. Place the crosshairs below the lower-left corner of the list box and
click mouse button 1.
The first push button part is placed in the window.
4. Select the IPushButton* icon again.
5. Place the crosshairs to the right of the first push button and click
mouse button 1.
The second push button is placed in the window.
6. Change the text of the first push button to Add. Use the same method you
used to change the text in the title bar.
7. Change the text of the second push button to Remove.
ΓòÉΓòÉΓòÉ 3.2.4. Resizing and Aligning the Parts ΓòÉΓòÉΓòÉ
Now that you have placed all of the parts you need in the application window,
it is time to resize and align them. When you have finished, your application
window should look like the following figure:
Matching the width of the list box to the width of the entry field
Follow these steps to match the width of the list box to the width of the entry
field:
1. Move the mouse pointer over the list box.
2. Press and hold mouse button 1.
The selection handles appear at the four corners of the list box.
3. While holding down mouse button 1, move the mouse pointer to the entry
field.
The selection handles on the list box become hollow and black selection
handles appear on the four corners of the entry field. This means that
both parts are selected, but the entry field is the anchor part.
Therefore, any sizing actions performed using the tool bar cause the list
box to match the size of its anchor part, the entry field.
4. Select , the Match Width tool, from the row of icons on the tool bar,
located beneath the menu bar.
The width of the list box changes to match that of the entry field.
Matching the width of the Add push button to that of the Remove push button
Using the techniques you learned in the preceding steps, match the width of
the Add push button to that of the Remove push button.
Dragging and dropping parts in the application window
Before you align the parts, you might want to drag and drop some of them to
put them in closer proximity to each other. For example, you might want the
static text parts to be closer to the parts that they label. Follow these
steps to drag and drop the parts in the application window:
Note: The following instructions are written for dragging and dropping
multiple parts simultaneously. If you just want to drag and drop one
part at a time, you can skip the first step.
1. Select all of the parts you want to drag using the technique you learned
previously when matching the width of the list box to the width of the
entry field.
2. Move the mouse pointer over one of the parts that you selected to drag.
3. Press and hold mouse button 2 and move the mouse cursor.
Visual Builder displays an outline of the parts that you are dragging.
4. Move the outline to the place where you want to drop the parts and
release mouse button 2.
The parts are moved to their new location.
Resizing the application window
At this point, the parts in the application window are closer to the left
window border than to the right window border. Follow these steps to resize
the application window:
1. Select the application window by clicking mouse button 1 on the title
bar.
2. Move the mouse pointer over the selection handle on the lower-right
corner of the application window.
3. Press and hold mouse button 1.
4. Resize the application window by dragging the mouse pointer towards the
left until the right border of the application window is approximately
the same distance from the entry field and list box as the left border
is.
To size the window in only one direction, either horizontally or
vertically, hold down the Shift key while dragging the mouse
pointer.
Centering the entry field and list box within the application window
The entry field and list box need to be centered within the application
window. Follow these steps to center them:
1. Select the entry field.
2. Select , the Distribute Horizontally tool, from the row of icons on the
tool bar.
Visual Builder centers the entry field between the left and right borders
of the application window.
3. Select the list box and then the entry field, making the entry field the
anchor part. Use the multiple part selection technique you learned
previously.
4. Select , the Align Center tool, from the row of icons on the tool bar.
The list box is centered beneath the entry field.
Aligning the static text, entry field, and list box parts so their left edges
are even
The static parts need to be aligned evenly with the left edges of the entry
field and list box. Follow these steps to align them:
1. Select the first static text part and then select the entry field, making
the entry field the anchor part. Use the multiple part selection
technique you learned previously.
2. Select , the Align Left tool, from the row of icons on the tool bar.
The first static text part is aligned even with the left edge of the
entry field.
3. Repeat steps 1 and 2 for the second static text part and the list box.
The second static text part is aligned even with the left edge of the
list box.
Aligning the top edges of the push buttons
The push buttons need to be aligned so that their top edges are even. Follow
these steps to align them:
1. Select the Add push button and then select the Remove push button. Use
the multiple part selection technique you learned previously.
2. Select , the Align Top tool.
Visual Builder aligns the Add push button even with the top of the Remove
push button.
Spacing the push buttons evenly across the application window
The push buttons need to be evenly spaced across the width of the application
window. Follow these steps to space them:
1. Select both push buttons. You can make either push button the anchor
part. Use the multiple part selection technique you learned previously.
2. Select , the Distribute Horizontally tool.
Visual Builder spaces both push buttons evenly across the application
window.
Centering the push buttons between the bottom edge of the list box and the
bottom border of the application window
The push buttons need to be centered between the bottom edge of the list box
and the bottom border of the application window. Follow these steps to center
them:
1. Select both push buttons. You can make either push button the anchor
part. Use the multiple part selection technique you learned previously.
2. Move the mouse pointer over either push button.
3. Press and hold mouse button 2, and position the push buttons midway
between the bottom edge of the list box and the bottom window border.
4. When the push buttons are in place, release mouse button 2.
Your application should now look like the one shown in the following figure:
ΓòÉΓòÉΓòÉ 3.2.5. Connecting the Parts ΓòÉΓòÉΓòÉ
Now it is time for you to connect the parts so that your application can add
items to and remove items from the to-do list. You need to connect the push
buttons to the list box and entry field. The following steps show you how to do
this.
Before you start connecting parts, it is a good idea to make sure
none of your parts is selected. Otherwise, the correct pop-up menus
may not appear. To do this, hold down the Ctrl key, point to each
item that is selected, and press mouse button 1. When the selection
handles disappear, you know that the part is no longer selected.
Connecting the Add push button to the list box
The connection between the Add push button and the list box provides the
information your application needs to add items to the list box.
1. With the mouse pointer over the Add push button, click mouse button 2.
A pop-up menu is displayed.
2. Select Connect.
A cascaded menu, called the connection menu, of the Add push button is
displayed.
3. Select the buttonClickEvent feature.
Selecting the buttonClickEvent feature means that you want something to
happen whenever a user clicks this push button. The mouse pointer changes
to look like a spider, indicating that it is ready for you to select
another feature.
4. Move the mouse pointer to the list box and click mouse button 1.
A pop-up menu is displayed showing the connection menu of the list box.
5. Select the addAsLast action.
Selecting the addAsLast action means that you want new items to be added
to the end of the to-do list whenever a user clicks the Add push button.
The connection is shown in the following figure:
The line connecting the Add push button to the list box is dark green. It
points from the push button to the list box, showing that the event that
occurs when the push button is selected will cause the list box to
perform an action.
Notice that the connection line is dashed instead of solid. A dashed line
means that the connection is incomplete. The connection is supposed to
add something to the list box when the Add push button is clicked, but
you have not yet supplied what needs to be added. The next step does
that.
6. Move the mouse pointer to the dashed connection line between the Add push
button and the list box.
7. To take a shortcut to display connection menus, hold down the Alt key and
click mouse button 2.
The pop-up menu for the connection is displayed.
8. Select the text parameter.
The text parameter is the reason the connection line is dashed. You need
to give this parameter a value.
9. Move the mouse pointer over the entry field, and click mouse button 1.
Visual Builder displays the connection menu for the list box.
10. Select the text attribute.
Selecting the text attribute here means that you want to pass the text
that a user enters in the entry field to the text parameter of the
addAsLast action. This text string is added to the end of the to-do list
whenever the addAsLast action is called, which occurs whenever the Add
push button is clicked. The completed connection is shown in the
following figure:
The line connecting the entry field to the connection between the Add
push button and the list box is violet. The solid arrow head points to
the entry field, showing that the text attribute is the target of the
connection.
The hollow arrow head points to the connection line, indicating that the
text parameter of the addAsLast action is the source of the connection.
When the text parameter needs a value, which occurs when a user clicks on
the Add push button, the connection invokes the get member function of
the entry field's text attribute. The value of that attribute (the text
in the entry field) is returned to the text parameter and the addAsLast
action puts the text string in the list box.
Notice that both of the connection lines are solid. This means that the
connection between the Add push button and the list box now has the
information it needs to perform its function, so the connection is
complete.
Connecting the Remove push button to the list box
The connection between the Remove push button and the list box provides the
information your application needs to remove items from the list box.
1. With the mouse pointer over the Remove push button, hold down the Alt key
and click mouse button 2.
Visual Builder displays the connection menu for the Remove push button.
2. Select the buttonClickEvent feature.
3. Move the mouse pointer to the list box and click mouse button 1.
Visual Builder displays the connection menu for the list box.
4. Select the remove action.
Selecting the remove action means that you want your application to
remove the selected item in the to-do list whenever a user clicks the
Remove push button. Once again, the connection is incomplete.
5. Move the mouse pointer to the connection between the Remove push button
and the list box.
6. Hold down the Alt key and click mouse button 2.
Visual Builder displays the connection menu for the connection.
7. Select the index parameter.
The index parameter is the reason the connection line is dashed. You need
to give this parameter a value.
8. Move the mouse pointer over the list box and click mouse button 1.
Visual Builder displays the connection menu for the list box.
9. Select the selection attribute.
Selecting the selection attribute means that you want to pass the index
of the selected item in the list box to the index parameter of the remove
action. The remove action uses this index to determine which item to
remove whenever the Remove push button is clicked.
Making this connection completes your application. It should now look
like the one shown in the following figure:
Note: In the preceding figure, we changed the shape of the connection
between the Remove push button and the list box to make it easier
for you to see. You can do this by selecting the connection and
dragging the middle selection handle.
Now that you have made all of the connections, the next step is to generate
your C++ source code.
ΓòÉΓòÉΓòÉ 3.2.6. Generating the C++ Code for Your Application ΓòÉΓòÉΓòÉ
The first thing you must do to get your application ready to build is to
generate the C++ code. This is a two-part process that consists of generating
the source code for your new visual part and then generating the source code
for your main procedure.
Generating the source code for your visual part
To generate the C++ source code for your visual part, select FileSave and
GeneratePart source.
Another way to generate part code is to select , the Part Code
Generation tool, on the tool bar. The results are the same.
Visual Builder generates the following files in the working directory:
todolist.cpp The C++ code for your ToDoList part.
todolist.hpp The C++ header file for your ToDoList part.
todolist.h The resource header file for your todolist.cpp file.
todolist.rc The resource file for your todolist.cpp file.
Generating the source code for your main() function
To generate the source code for your main() procedure, select FileSave and
Generatemain() for part. Visual Builder generates the following files in the
working directory:
todolist.app The main function for your application.
Note: If you start Visual Builder from a WorkFrame project,
the name of this file is vbmain.cpp.
todolist.mak The make file that you specify when you build your application.
You have now generated the C++ code for your application. The next step is to
build the application.
ΓòÉΓòÉΓòÉ 3.2.7. Building the Application ΓòÉΓòÉΓòÉ
Building your application consists of compiling and linking it. To build your
application, do the following:
1. Open an OS/2 window.
2. Change to your Visual Builder working directory.
3. Enter the following command:
nmake todolist.mak
This command produces the following files:
todolist.exe The executable file for your application.
todolist.map The application configuration map.
todolist.o The object file for your application.
Note: If you start Visual Builder from a WorkFrame
project, the name of this file is vbmain.obj.
todolist.obj The object file for your part. Visual Builder
provides a separate object module for your part that
is used when compiling this part with other parts.
todolist.res The binary resource file that is bound to
todolist.exe.
You have now built your application; the next step is to run your application.
ΓòÉΓòÉΓòÉ 3.2.8. Running the Application ΓòÉΓòÉΓòÉ
To run your application from the same OS/2 command prompt from which you
entered the nmake command, enter the following:
todolist
Once your application is running, experiment with it to make sure it works as
you designed it. That is all there is to it!
You can add a finishing touch to your application by creating an OS/2 program
object. Create a program object from the OS/2 Templates folder, specifying the
name todolist.exe as the program name and the directory that contains
todolist.exe as the working directory. Once you have done this, you can run
your application by simply double-clicking on the program object you just
created.
ΓòÉΓòÉΓòÉ 3.2.9. Exiting the Composition Editor and Visual Builder ΓòÉΓòÉΓòÉ
To exit either the Composition Editor or Visual Builder, do either of the
following.
Note: You must exit Visual Builder before you can shut down OS/2. Otherwise,
OS/2 does not shut down completely.
When you exit Visual Builder, any changes you have made to the selections in
the Options menu are saved. Therefore, if you want certain options to be
selected or deselected the next time you start Visual Builder, be sure to
select or deselect them before exiting Visual Builder.
Select FileExit.
Double-click on the system menu icon in the window.
If you try to exit Visual Builder while one or more editor windows is open,
Visual Builder displays a message asking if you want to close the editors and
Visual Builder. You can select either of the following:
The OK push button to exit the windows.
The Cancel push button to cancel the exit request.
If you select the OK push button with this message displayed or try to exit an
editor and the open editor window contains unsaved changes, Visual Builder
displays a message asking if you want to save the changes for each open editor
before exiting. You can select either of the following:
The Yes push button to save the changes and exit.
The No push button to exit without saving the changes.
The Cancel push button to cancel the exit request.
ΓòÉΓòÉΓòÉ 4. Setting Up and Starting Visual Builder ΓòÉΓòÉΓòÉ
This chapter tells you how to do the following:
Set up your WorkFrame project to use Visual Builder
Start Visual Builder
Personal notes:
ΓòÉΓòÉΓòÉ 4.1. Setting Up Your WorkFrame Project to Use Visual Builder ΓòÉΓòÉΓòÉ
If you have created a WorkFrame project and will be running Visual Builder from
the project folder, you should set up the project as follows before starting
Visual Builder.
Note: We recommend that you use a Project Smarts Visual Builder template in
your WorkFrame project. Refer to the VisualAge C++ User's Guide for
information on how to do this.
1. Open the settings notebook for the project folder by doing the following:
a. Click on the project folder with mouse button 2.
b. Select OpenSettings.
The settings notebook appears.
2. Set the names of the executable file and the make file by doing the
following:
a. On the Target page, type the name that you want your executable file
to have in the Name field.
b. Type the name that you want your make file to have in the Makefile
field.
3. Set the directory in which your project files will be stored by doing the
following:
a. Select the tab for the Location OS/2 Files page.
b. Type the full path for the directory in which you want to store your
project files in the multiline edit field on this page. This is the
directory in which Visual Builder puts the files for your
application when you generate your source code.
4. Inherit the settings of a C++ project by doing the following:
a. Select the tab for the Inheritance page.
b. Select the Add push button.
A dialog is displayed in which you select the project whose settings
you want to inherit.
c. Double-click on the Desktop directory in the Directory list box.
d. Double-click on the VisualAge C++ 3.0 directory, also in the
Directory list box.
e. Select the C Set ++ Project file in the File list box.
f. Select the Inherit push button.
This puts all of the WorkFrame tools, including Visual Builder, that
you need for a C++ project in the project's pop-up menu, giving you
easier access to them.
5. Close the settings notebook.
You are now ready to start Visual Builder.
ΓòÉΓòÉΓòÉ 4.2. Starting Visual Builder ΓòÉΓòÉΓòÉ
You can start Visual Builder in the following ways:
From the C/C++ window
From the Tools folder icon
From a WorkFrame Project folder
Starting Visual Builder from the C/C++ window
To start Visual Builder from the C/C++ window, do the following:
1. Double-click on the icon for the VisualAge C++ folder.
The folder opens.
2. Double-click on the C/C++ Window icon.
The C/C++ window opens.
3. Type the following:
icsvb
4. Press the Enter key.
Visual Builder displays the Visual Builder window, as shown in the
following figure.
Starting Visual Builder from the Tools folder
To start Visual Builder from the Tools folder, do the following:
1. Double-click on the icon for the VisualAge C++ folder.
The folder opens.
2. Double-click on the Tools folder icon.
The folder opens.
3. Double-click on the Visual Builder icon.
Visual Builder displays the Visual Builder window, as shown in the
preceding figure.
Starting Visual Builder from a WorkFrame Project folder
You can start Visual Builder from a WorkFrame Project folder in the following
ways.
Note: The following steps assume that your project inherits the settings of a
C Set ++ project or that it was created using a Project Smarts
template.
If the WorkFrame Project folder is closed, you can click on the folder
with mouse button 2 and select Visual from the pop-up menu.
If the WorkFrame Project folder is open, you can do any one of the
following:
- Double-click on the name of the .vbb file
- Click on the name of the .vbb file with mouse button 2 and select
Visual from the pop-up menu.
- Click on the white space in the project folder with mouse button 2
and select Visual from the pop-up menu.
Visual Builder displays the Visual Builder window, as shown in the
preceding figure. If you double-clicked on a .vbb file to open Visual
Builder, that file and all other .vbb files that you selected are
preloaded.
When you start Visual Builder from a WorkFrame Project folder, the menu bar in
the Visual Builder window and in each of the Visual Builder editor windows
contains an additional Project choice. Selecting this choice displays a list
of the WorkFrame actions that are currently at the project scope for the
project with which you are working. Examples of actions you might see in this
list are Debug, MakeMake, Build, Run, Database, and Browse.
ΓòÉΓòÉΓòÉ 5. Getting Acquainted with the Visual Builder Window ΓòÉΓòÉΓòÉ
This chapter provides the following topics that show you how to set up a
WorkFrame project to use Visual Builder, start Visual Builder, work with .vbb
files, and use the functions available to you in the Visual Builder window.
Getting to know the Visual Builder window.
Working with the files for storing parts, .vbb files
Customizing the information area
Seeing the base files
Seeing where part files are located
Seeing the type list
Using File Allocation Table (FAT) file names
Generating make files
Setting the working directory
Refreshing the display
Personal notes:
ΓòÉΓòÉΓòÉ 5.1. Getting to Know the Visual Builder Window ΓòÉΓòÉΓòÉ
The Visual Builder window is shown in the following figure.
This window contains the following areas:
The Loaded Part Files list box
Parts that you create are stored in files with an extension of .vbb.
These files are called part files. You can share part files that you
create with other programmers so that they can reuse your parts.
This list box shows all of the part files that are currently loaded.
Visual Builder provides the following part files:
VBBase.vbb
Contains the base parts that Visual Builder provides. This file is
always loaded.
VBMM.vbb
Contains multimedia parts.
VBSOM.vbe
Contains Direct-to-SOM parts that you can use in Visual Builder.
You must import this file to use the parts.
VBCC.vbe
Contains sample parts based on the IBM Collection Class Library.
You must import this file to use the parts.
VBSample.vbb
Contains miscellaneous sample parts.
The .vbb files that Visual Builder provides are read-only
files. Store the parts that you create in your own .vbb
files.
Part files must be loaded into Visual Builder for you to use the parts
that they contain. Once part files are loaded, you can perform actions on
them and on the parts that they contain by using the choices in the
Visual Builder's menu bar.
You can access the same choices that are available in the
menu bar by moving the mouse pointer over a list box and
pressing mouse button 2 to display a pop-up menu. Each
pop-up menu contains only the menu choices that pertain to
the contents of the list box over which it is displayed.
The pop-up menu that Visual Builder displays for the
Loaded Part Files list box, for example, contains only the
menu choices that pertain to part files.
Also, the pop-up menu for the Visual Parts list box only
affects parts that are selected in that list box, even if
parts are also selected in the Nonvisual Parts list box,
and vice versa. For example, to simultaneously open both a
visual and a nonvisual part, you must select PartOpen
from the menu bar. If you select Open from the pop-up menu
for the Visual Parts list box, you can only open a visual
part. The same is true for the pop-up menu for the
Nonvisual Parts list box.
The choices on the Part menu apply to selected items in
all of the list boxes in the Visual Builder window. This
includes the Loaded Type Information list box, which you
display by selecting OptionsShow type list.
For more information about part files and the actions you can perform on
them, see Working with the Files for Storing Parts, .vbb Files.
The Visual Parts list box
This list box displays the names of the visual parts that the selected
part file contains. Visual parts are parts that the person using your
application can see, such as frame windows, push buttons, and sliders.
The Nonvisual Parts list box
This list box displays the names of the nonvisual parts and the class
interface parts that the selected part file contains. Nonvisual parts are
parts that your application uses to perform its functions, but the person
using your application never sees them. For example, an object factory,
which creates new instances of objects, is a nonvisual part. The user
sees only the objects that the object factory creates, not the object
factory itself.
Class interface parts are nonvisual parts that have no notification
ability. Thus, these parts cannot send events to other parts. You can use
C++ classes that you have written as class interface parts in Visual
Builder.
ΓòÉΓòÉΓòÉ 5.2. Working with the Files for Storing Parts, .vbb Files ΓòÉΓòÉΓòÉ
The topics in this section describe how to perform various actions on part
files from the Visual Builder window.
The following topics are covered:
Loading part files
Unloading part files
Selecting all part files
Deselecting all part files
Personal notes:
ΓòÉΓòÉΓòÉ 5.2.1. Loading Part Files ΓòÉΓòÉΓòÉ
To give Visual Builder access to parts, you must load the contents of the part
files that contain those parts by doing the following:
1. Select FileLoad file in the Visual Builder window.
Visual Builder displays the window shown below:
2. Select the file or files that you want to load.
3. Select the OK push button.
When you are just loading one file, it is quicker to
double-click on the file name instead of selecting the
file name and the OK push button.
The file name or names are displayed in the Loaded Part Files list box in
the Visual Builder window. The following figure shows the Visual Builder
window with multiple .vbb files loaded.
For information about unloading files, see Unloading Part Files.
ΓòÉΓòÉΓòÉ 5.2.2. Unloading Part Files ΓòÉΓòÉΓòÉ
If a part file appears in the Loaded Part Files list box in the Visual Builder
window, Visual Builder has access to the parts that the part file contains. If
you do not want Visual Builder to have access to those parts, you can unload
the part file, with the exception of vbbase.vbb. To unload one or more part
files, do the following:
1. Select one or more files in the Loaded Part Files list box.
To select multiple files, hold down the Ctrl key while clicking on a file
name with mouse button 1.
2. Select FileUnload file.
The following window is displayed showing the files you selected to
unload:
At this point, you can review the files that you selected and make any
changes by deselecting any file or files that you want to remain loaded.
3. Select the Unload push button.
The window disappears and the file names are removed from the Loaded Part
Files list box.
For information about loading files, see Loading Part Files.
ΓòÉΓòÉΓòÉ 5.2.3. Selecting All Part Files ΓòÉΓòÉΓòÉ
To select all of the part files, select EditSelect all files. Visual Builder
highlights all of the part files listed in the Loaded Part Files list box.
At this point, you can review the list to see if you want to deselect any of
the files.
ΓòÉΓòÉΓòÉ 5.2.4. Deselecting All Part Files ΓòÉΓòÉΓòÉ
To deselect all of the part files, select EditDeselect all files. Visual
Builder removes the highlighting from all of the selected part files listed in
the Loaded Part Files list box.
At this point, you can review the list to see if you want to select any of the
files.
ΓòÉΓòÉΓòÉ 5.3. Customizing the Information Area ΓòÉΓòÉΓòÉ
The following options allow you to specify the kind of information that Visual
Builder displays in the information area for a selected part in the Visual
Builder window. To use these options, select OptionsInformation area and then
select one of the following options:
Show base class
Displays the C++ notation for a class and its base class. For example, if
you select IVBContainerControl when this option is selected, Visual Builder
displays the following in the information area to show that IControl is
IVBContainerControl's base class:
IVBContainerControl::IControl
Show description
Displays a brief description of the selected part. For example, if you
select IVBContainerControl when this option is selected, Visual Builder
displays the following description in the information area:
Part: IVBContainerControl* - IBM VB container control
Show full file names
Displays the name of the part file in which the part is stored. For example,
if you select IVBContainerControl when this option is selected, Visual
Builder displays the following file name in the information area to show
that VBBase.vbb contains the IVBContainerControl part.
VBBase.vbb
ΓòÉΓòÉΓòÉ 5.4. Seeing the Base Files ΓòÉΓòÉΓòÉ
Select OptionsShow base files to see the names of the parts in the .vbb files
that Visual Builder provides, as follows:
VBBase.vbb
Contains the base parts that Visual Builder provides.
VBCC.vbb
Contains sample parts based on the IBM Collection Class Library.
VBMM.vbb
Contains sample multimedia parts.
ΓòÉΓòÉΓòÉ 5.5. Seeing Where Part Files Are Located ΓòÉΓòÉΓòÉ
Select OptionsShow full file names to see the drive and directory where each
of your part files is stored.
ΓòÉΓòÉΓòÉ 5.6. Seeing the Type List ΓòÉΓòÉΓòÉ
The type list shows the types of data, such as enumerations and typedefs, for
the parts contained in the .vbb file that is currently selected. If no .vbb
file is selected or if the selected .vbb file has no data types defined, this
list is empty.
Once a type list is displayed, you can perform the following functions on data
types that are selected:
Delete data types
Move data types to another part file
Export data type definitions into part information files
These functions are available in the Part pull-down menu.
To display a type list, do the following:
1. Select the part file or files for which you want to see defined types.
2. Select OptionsShow type list.
A list box titled Loaded Type Information is displayed at the bottom of
the Visual Builder window, as shown in the following figure.
ΓòÉΓòÉΓòÉ 5.7. Using File Allocation Table (FAT) File Names ΓòÉΓòÉΓòÉ
Select Default to FAT file names if your system uses the File Allocation Table
(FAT) file system instead of the High Performance File System (HPFS). This
option is selected by default when you first install VisualAge C++. The FAT
file system limits file names to a maximum of eight characters and file name
extensions to a maximum of three characters.
When you select this option, Visual Builder uses these limits when creating
file names and extensions, such as in the Class Editor when it provides a file
name and extension for you to use when generating default code. For example,
suppose you create a part and name it MyNewPart. This name has nine characters.
If you generate code for this part, the default file name that Visual Builder
uses for the files it generates will have only eight characters, as will the
.vbb file in which the part is saved if you allow Visual Builder to use a
default name for that, too.
Be aware that Visual Builder does not check for existing file names
when creating default file names. If you always use the default file
name on a FAT system, Visual Builder may use a file name that has
already been used, which may cause an existing file to be written
over. For example, if you created another part named MyNewPart2,
Visual Builder would use the same default file name as it used for
MyNewPart.
Visual Builder assigns the file name when you create the part.
Deselecting the Default to FAT file names option does not change the
name of a file that has already been created.
ΓòÉΓòÉΓòÉ 5.8. Generating Make Files ΓòÉΓòÉΓòÉ
Select Generate make files if you want Visual Builder to generate a make file
for you when you generate the default source code for the main() function of
your application.
ΓòÉΓòÉΓòÉ 5.9. Setting the Working Directory ΓòÉΓòÉΓòÉ
Select OptionsSet working directory if you want to store files created with
Visual Builder in a different working directory. The default working directory
is the directory in which you installed Visual Builder.
When you select this option, Visual Builder displays the following window:
To change the working directory, do the following:
1. Type the complete path to the directory in which you want to store Visual
Builder files that you create.
The path consists of all directories that must be opened to get to the
working directory.
2. Select the OK push button.
If the path you enter in the Working Directory window is invalid, Visual
Builder displays an error message and resets the path to the last valid path
that was entered.
ΓòÉΓòÉΓòÉ 5.10. Refreshing the Display ΓòÉΓòÉΓòÉ
You might want to ensure that the information displayed in the Visual Builder
window is current, for example, when you have loaded and unloaded several part
files or moved parts from one part file to another. If such a situation occurs,
you can cause the display to show the latest updates by selecting EditRefresh.
ΓòÉΓòÉΓòÉ 6. Getting to Know the Visual Builder Editors ΓòÉΓòÉΓòÉ
This chapter takes you on a tour of the Visual Builder editors. It begins with
an overview of the editor symbols and then examines each editor in detail. The
following topics are covered:
The editor symbols.
The Composition Editor
The Class Editor
The Part Interface Editor
Personal notes:
ΓòÉΓòÉΓòÉ 6.1. The Editor Symbols ΓòÉΓòÉΓòÉ
The Editor symbols, located at the bottom-right corner of the window, provide a
fast-path to each of the Visual Builder Editors. Double-click on one of the
following editor symbols to learn more about that editor.
Composition Editor Use the Composition Editor to create the views for
your application, choose the parts that perform
the logic you need, and make connections between
the parts.
Class Editor Use the Class Editor to specify the names of files
that Visual Builder writes to when you generate
default code. You can also use this editor to do
the following:
Enter a description of the part
Specify a different .vbb file in which to
store the part
See the name of the part's base class
Modify the part's default constructor
Enter additional constructor and destructor
code
Specify a .lib file for the part
Specify a resource DLL and ID to assign an
icon to the part
Specify other files that you want to include
when you build your application
Part Interface Editor You can use the Part Interface Editor to define
the features (attributes, actions, and events) for
your parts, along with a list of preferred
features for the pop-up connections menu. These
features make up the part's interface. You use
them when you make connections between
collaborating parts. You can also promote features
of subparts from this editor.
ΓòÉΓòÉΓòÉ 6.2. The Composition Editor ΓòÉΓòÉΓòÉ
Introducing the Composition Editor
The tool bar
The parts palette
The free-form surface
Personal notes:
ΓòÉΓòÉΓòÉ 6.2.1. Introducing the Composition Editor ΓòÉΓòÉΓòÉ
The heart of Visual Builder is the Composition Editor. Use the Composition
Editor to lay out the visual parts that make up your views, choose the parts
that perform the logic you need, and make connections between them.
The Composition Editor is the editor you use to visually compose the various
parts of your application. This section provides an overview of the Composition
Editor's components. See Learning Visual Construction Fundamentals for
information about visually composing an application.
The Composition Editor is shown in the following figure.
The next section describes the Composition Editor tool bar.
ΓòÉΓòÉΓòÉ 6.2.2. The Tool Bar ΓòÉΓòÉΓòÉ
The tool bar appears below the menu bar of the Composition Editor. It contains
icons that provide convenient access to actions that you commonly use when you
create composite parts. These tools help you perform such tasks as:
Aligning parts within your composite part
Managing the connections between parts
Unloading the mouse pointer.
Generating code for the part you are editing
All of the tools in the tool bar, except the Selection tool, act on the
selected objects.
All of the tools available from the tool bar are also available from
the Tools menu found on the Composition Editor's menu bar, except
for the tool used to generate source code for your part. This tool
is available in the File menu as the Save and generatePart source
choice.
The tool bar contains the following tools:
Part Code Generation Generates C++ source code for the part that you
are currently editing. This tool performs the same
function as the FileSave and generatePart source
menu choice. For information about the source code
files that Visual Builder generates, see Source
Files Created during Part Code Generation.
Selection tool Changes the mouse pointer from the crosshairs,
which are used when the mouse pointer is loaded
with a part, to the arrow that is used to select
parts and perform actions on them. If the mouse
pointer is not loaded, this tool is not available.
Connection tools
Show Connections Displays all hidden connections to or from the
selected parts. If no parts are selected, all
connections are shown.
Hide Connections Hides all displayed connections to or from the
selected parts. If no parts are selected, all
connections are hidden.
Grid tools
Toggle Grid Toggles the display of the part alignment grid on
and off for the selected parts. You can use
separate alignment grids for parts in the
Composers category and for the free-form surface.
Snap To Grid Causes the selected parts to be repositioned to
the nearest grid coordinate. The grid does not
need to be visible for Snap To Grid to work.
Select the Snap On Drop and Snap On
Size choices found in the
Composition Editor Options menu to
automatically align to the grid all
parts that you add or size. This
allows you to align parts to the
grid without having to select the
Snap To Grid tool for each part.
Use the Snap To Grid tool if you
only want to align selected parts
to the grid.
Alignment tools
Align Left Aligns the selected parts to the left edge of the
last part selected.
Align Center Aligns the selected parts along the vertical axis
of the last part selected.
Align Right Aligns the selected parts to the right edge of the
last part selected.
Align Top Aligns the selected parts to the top edge of the
last part selected.
Align Middle Aligns the selected parts along the horizontal
axis of the last part selected.
Align Bottom Aligns the selected parts to the bottom edge of
the last part selected.
Distribution tools
Distribute Horizontally Spaces the selected parts evenly between the left
and right window borders.
Distribute Vertically Spaces the selected parts evenly between the top
and bottom window borders.
For information about the horizontal and vertical
distribution of visual parts within a bounding
box, see Space parts within a bounding box.
Sizing tools
Match Width Sizes the width of the selected parts to match
that of the last part selected.
Match Height Sizes the height of the selected parts to match
that of the last part selected.
ΓòÉΓòÉΓòÉ 6.2.3. The Parts Palette ΓòÉΓòÉΓòÉ
The parts palette is found on the left side of the Composition Editor. It
contains icons for the parts that you use most frequently.
The parts palette organizes parts into categories. The icons in the left column
of the parts palette represent the part categories. The right column of the
parts palette contains the parts you use to build your application. When you
select a category in the left column, the right column shows the parts
contained within that category.
Notes:
The information area at the bottom of the Composition Editor indicates
which category and part are currently selected on the palette or which
part or connection is currently selected on the free-form surface.
You can add categories and parts to the parts palette, as well as delete
categories and parts from it. See Adding Categories and Parts to the
Parts Palette for information about adding parts that you create to the
parts palette.
See Placing Parts on the Free-form surface for information about putting
parts on the free-form surface.
The Visual Builder parts palette contains the following categories and parts.
Click on a part bitmap to see more information about the part it represents.
Buttons Contains the following button parts:
IPushButton*
IRadioButton*
ICheckBox*
INumericSpinButton*
ITextSpinButton*
IGraphicPushButton*
IAnimatedButton*
Data entry Contains the following data entry parts:
IStaticText*
IEntryField*
IMultiLineEdit*
IGroupBox*
IOutlineBox*
IBitmapControl*
IIconControl*
Lists Contains the following list parts:
IListBox*
ICollectionViewListBox*
IComboBox*
ICollectionViewComboBox*
IVBContainerControl*
IContainerColumn*
Frame Extensions Contains the following parts that you can add to a
window frame:
IToolBar*
IToolBarButton*
IMenu*
IMenuItem*
IMenuCascade*
IMenuSeparator*
IInfoArea*
ITitle*
Sliders Consists of the following slider parts:
IProgressIndicator*
ISlider*
IScrollBar*
Composers Consists of the following parts that are used to
contain other visual parts:
IMultiCellCanvas*
ISetCanvas*
ISplitCanvas*
IViewPort*
INotebook*
ICanvas*
IFrameWindow*
Models Contains the following nonvisual parts to help
implement the logic of your application:
IVBFactory*
IVBVariable*
IVSequence*
Other Contains the following miscellaneous parts:
IHelpWindow*
IMessageBox*
IVBFileDialog*
IVBFontDialog*
IVBFlyText*
ΓòÉΓòÉΓòÉ 6.2.4. The Free-form Surface ΓòÉΓòÉΓòÉ
The large open area in the Composition Editor is called the free-form surface.
This is the working area for visual programming, where you compose the various
visual parts of your application and where you make connections to the logic of
your application.
You add visual parts, such as static text and push buttons, to either a frame
window part, to another part from the Composers category, or to the free-form
surface itself. You add nonvisual parts, such as object factories, and class
interface parts to your application by placing them on the free-form surface,
not on a frame window part or on any other part from the Composers category.
For more information about using the free-form surface, see Working with Parts
On the Free-form Surface.
ΓòÉΓòÉΓòÉ 6.3. The Class Editor ΓòÉΓòÉΓòÉ
Introducing the Class Editor
Entering a description of a part
Moving a part to a different .vbb file
Seeing the base class of a part
Modifying a part's constructor
Specifying your own constructor code
Specifying your own destructor code
Specifying a library file
Specifying a starting resource ID
Specifying a unique icon for your part
Specifying the names of your code generation files
Specifying files to include when you build your application
Personal notes:
ΓòÉΓòÉΓòÉ 6.3.1. Introducing the Class Editor ΓòÉΓòÉΓòÉ
The Class Editor is the editor you use to specify the names of files that
Visual Builder writes to when you generate default code. You can also use this
editor to do the following:
Enter a description of the part
Specify a different .vbb file in which to store the part
See the name of the part's base class
Modify the part's default constructor
Enter additional constructor and destructor code
Specify a .lib file for the part
Specify a resource DLL and ID to assign an icon to the part
Specify other files that you want to include when you build your
application
Use your favorite text editor for creating new classes and member functions,
writing application logic, and modifying existing member functions.
The Class Editor is shown in the following figure:
If you cannot see all of the fields shown in the preceding figure, use the
scroll bar on the right side of the Class Editor to see the remaining fields.
The next section tells you how to enter a description of the part.
ΓòÉΓòÉΓòÉ 6.3.2. Entering a Description of a Part ΓòÉΓòÉΓòÉ
The Description field in the Class Editor is an entry field in which you can
enter a description of your part. This description is used in the following
places:
If you add your part to the parts palette, the description appears in the
information area at the bottom of the Composition Editor when you select
the part.
If you export your part information into a .vbe file, the description is
included in the first line.
In the following example, the text shown in quotation marks was taken
from the Description field for the ToDoList part.
//VBBeginPartInfo: ToDoList,"To-Do List sample application"
ΓòÉΓòÉΓòÉ 6.3.3. Moving a Part to a Different .vbb File ΓòÉΓòÉΓòÉ
The Part file specification field in the Class Editor shows the name of the
.vbb file that contains this part. If you want to move this part to another
.vbb file while using the Class Editor, do the following:
1. Replace the name of the current .vbb file with the name of another .vbb
file in which you want to store the part.
2. Select FileSave to apply the change.
Visual Builder moves the part from the former .vbb file to the one you
just specified. If the .vbb file you specified does not exist, Visual
Builder creates it for you.
ΓòÉΓòÉΓòÉ 6.3.4. Seeing the Base Class of a Part ΓòÉΓòÉΓòÉ
The Base class - access level field in the Class Editor shows the name of the
base class for your part. This is the class name that you specified as the base
class when you created the part.
This field also shows you the current access level to the base class: public,
protected, or private.
You cannot modify the base class name or the access level.
ΓòÉΓòÉΓòÉ 6.3.5. Modifying a Part's Constructor ΓòÉΓòÉΓòÉ
The Constructor field in the Class Editor initially contains a default
constructor that Visual Builder inserts for you. If the default constructor
does not do exactly what you want it to do, you can modify it by typing over
the text in this field.
If you want your class to have multiple constructors, we recommend putting them
in the .hpv and .cpv files that contain your default feature code and then
including them when you generate your code. Otherwise, if you modify your code
after generating it, your changes will be lost the next time you generate your
code.
For information about including files, see Specifying Files for Visual Builder
to Include When You Build Your Application.
ΓòÉΓòÉΓòÉ 6.3.6. Specifying Your Own Constructor Code ΓòÉΓòÉΓòÉ
Use the User constructor code field in the Class Editor to enter your own
constructor code for the part that you are editing. If you enter code in this
field, it is added at the end of the default constructor that Visual Builder
provides for you. If you have more than one line of code, put your code into a
function and put the function name in this field. Put the code for this
function in the files that Visual Builder creates when you generate your
default feature code. These file names are specified in the User .hpv file and
User .cpv file fields.
ΓòÉΓòÉΓòÉ 6.3.7. Specifying Your Own Destructor Code ΓòÉΓòÉΓòÉ
Use the User destructor code field in the Class Editor to enter your own
destructor code for the part that you are editing. If you enter code in this
field, it is added at the beginning of the default destructor that Visual
Builder provides for you. If you have more than one line of code, put your code
into a function and put the function name in this field. Put the code for this
function in the files that Visual Builder creates when you generate your
default feature code. These file names are specified in the User .hpv file and
User .cpv file fields.
ΓòÉΓòÉΓòÉ 6.3.8. Specifying a Library File ΓòÉΓòÉΓòÉ
Use the .LIB file name field in the Class Editor to specify the name of a
library file (partname.lib) that you want to to be included when you generate
the source code for your part. The library file points to a .dll file that
contains information about a subpart in your application that was compiled
separately. When you generate the source code for your part, Visual Builder
includes a #pragma statement to include the library file.
When Visual Builder generates make files for other parts that use this part,
the .lib file is specified in the make file as a dependency.
ΓòÉΓòÉΓòÉ 6.3.9. Specifying a Starting Resource ID ΓòÉΓòÉΓòÉ
Use the Starting resource id field in the Class Editor to specify the number
that Visual Builder is to use as a starting point for generating resource IDs
for your part. The resource IDs that Visual Builder generates are written into
a file named partname.h, which Visual Builder creates when you generate code
for your part.
The check box next to the field enables the starting resource ID. The first
time you select this check box, Visual Builder inserts a default starting
resource ID. You can change this number.
If you deselect the check box, the field is disabled. The number in the field
is included in the partname.h file when you generate your code, but it is not
referenced.
Generating resource IDs is useful if the text in your application is being
translated into another language. See Enabling National Language Support for an
Application for more information about using starting resource IDs.
ΓòÉΓòÉΓòÉ 6.3.10. Specifying a Unique Icon for Your Part ΓòÉΓòÉΓòÉ
Fill in the fields in the Icon group box in the Class Editor before you add
your part to the parts palette so that you can use an icon other than the
default icon provided by Visual Builder to represent your part. The default
icon is .
The Icon group box contains the following fields:
DLL name An entry field in which you enter the name of the resource DLL that
contains the icon you want to use. Enter just the file name, not the
extension.
Resource Id The resource ID number of the icon in the DLL whose name you
entered in the DLL name field.
When you enter both the DLL name and a valid resource ID number, Visual
Builder displays the icon that matches the resource ID number in the area
below the Resource Id field. This occurs when you click on another field. This
allows you to verify that you entered the correct resource ID number.
ΓòÉΓòÉΓòÉ 6.3.11. Specifying the Names of Your Code Generation Files ΓòÉΓòÉΓòÉ
The Code generation files group box in the Class Editor contains the following
fields:
A C++ header file (.hpp) field
A C++ code file (.cpp) field
The file names displayed in these fields are the files into which your C++
header file code and source code are written. This occurs when you generate
default code from the Visual Builder window or from any of the editors by
selecting FileSave and GeneratePart source.
For complete information about generating default source code, see Generating
Source Code for Parts and Applications.
The fields in the group box initially contain .hpp and .cpp file names that
are based on the name of the part you are editing. To change the file names in
these fields, select FileSave so that Visual Builder uses the new file names.
Warning: If the files already exist, Visual Builder replaces their contents
with the code currently being generated.
Visual Builder writes both files to the current directory.
ΓòÉΓòÉΓòÉ 6.3.12. Specifying Files to Include When You Build Your Application ΓòÉΓòÉΓòÉ
The User files included in generation group box in the Class Editor allows you
to specify files that you want to be included when you build your application.
These fields are typically used to contain the names of the files that hold
user code that Visual Builder is to use when you generate default feature code
for your part's features.
The .hpv and .cpv file extensions are used because the WorkFrame Build tool
tries to compile every .cpp file that it finds into an object module (.obj
file). Since these files are not meant to be compiled by themselves, we
selected a different file extension for you to use to prevent this from
happening.
The group box contains the following fields:
User .hpv file Use this field to enter the name of a header file that you want
to be included in the header file that Visual Builder generates. You must
enter a file name in this field before you can generate default feature
code.
User .cpv file Use this field to enter the name of a code file that you want
to be included in the source code file that Visual Builder generates. You
must enter a file name in this field before you can generate default feature
code.
User .h file Use this field to enter the name of a resource header file that
contains resource IDs for your application other than those that Visual
Builder generates for you in the partname.h file. This file is included in
partname.h.
User .rcv file Use this field to enter the name of a resource file that
contains text strings used in your application other than those that Visual
Builder generates for you in the partname.rc file. This file is included in
partname.rc.
The .rcv file extension is used because the WorkFrame Build tool tries to
compile every .rc file that it finds into a binary resource (.res) file.
Since partial resource files cannot always be compiled by themselves, we
selected a different file extension for you to use to prevent this from
happening.
Required include files This field is a multiline entry field in which you can
enter the names of other files that you want Visual Builder to include when
you generate default source code for your application. Some examples of
files that you might want to include are the following:
Standard C++ library files, such as streamio.h
IBM Open Class Library header files, such as IString.hpp
Visual Builder generates the #include statements in the default source code.
If you type a label next to the file name, Visual Builder uses that label to
generate #ifndef and #endif statements for you. For example, if you want to
include the header file for an address part that you created, you might
enter the following in the Additional Include Files field:
address.hpp _ADDRESS_
This would cause Visual Builder to generate the following in your default
.cpp source code file:
#ifndef _ADDRESS_
#include <address.hpp>
#endif
If you omit the label, Visual Builder generates only the #include statement.
ΓòÉΓòÉΓòÉ 6.4. The Part Interface Editor ΓòÉΓòÉΓòÉ
Introducing the Part Interface Editor
The Attribute page
The Event page
The Action page
The Promote page
The Preferred page
Personal notes:
ΓòÉΓòÉΓòÉ 6.4.1. Introducing the Part Interface Editor ΓòÉΓòÉΓòÉ
Each part that Visual Builder provides has a defined part interface that allows
the part to interact with other parts. The part interface consists of
features-attributes, events, and actions-that allow you to use the part in
constructing your application. An entry field, for example, has a text
attribute, a push button has a buttonClickEvent feature, and a frame window has
a setFocus action.
The parts that you create must also have a defined part interface so they can
be used. Use the Part Interface Editor to define that interface. See Creating
Parts for Reuse to learn more about building reusable parts.
Other uses for the Part Interface Editor include the following:
Viewing the interface of a part
Modifying or extending the interface of an existing part
Creating or altering the list of preferred features, the features that
are displayed in the pop-up connection menu for a part
The Part Interface Editor is a notebook made up of the following visual
components:
The Attribute page
The Event page
The Action page
The Promote page
The Preferred page
ΓòÉΓòÉΓòÉ 6.4.2. The Attribute Page ΓòÉΓòÉΓòÉ
Use the Attribute page of the Part Interface Editor, shown in the following
figure, to define the attributes for your part.
You can define many attributes for a part, each with unique characteristics,
such as name and data type. An attribute's value is always acquired by using
the attribute's get and set member functions. It is up to you whether data for
the attribute is stored in a data member, calculated, or acquired from some
other location.
In addition, you can define three different kinds of behavior for your
attributes, as follows:
full attribute A full attribute contains all of the characteristics and
behaviors that are available for an attribute, as follows:
A get member function, which is required
A set member function, which is optional (see no-set attribute below)
An event identifier, which is optional (see no-event attribute below)
no-set attribute A no-set attribute has no set member function. It can
initialize another attribute if it is the source of an
attribute-to-attribute connection, but it cannot set itself to the value of
another attribute.
no-event attribute A no-event attribute has no event identifier. Therefore, if
you use a no-event attribute as the source of a connection, it cannot signal
another part because of the lack of an event identifier. However, you can
still use it as the source of connections so that it can initialize other
attributes.
ΓòÉΓòÉΓòÉ 6.4.2.1. Adding an Attribute ΓòÉΓòÉΓòÉ
To add an attribute in the Part Interface Editor, do one of the following:
If you want to add the attribute using the default attribute type, get
member function, set member function, and event identification that
Visual Builder provides, enter a name in the Attribute name field and
select the Add with defaults push button.
Visual Builder adds the attribute to the part interface.
If you want to see the default attribute type, get member function, set
member function, and event identification that Visual Builder provides
before you add the attribute, select the Defaults push button.
Visual Builder displays the default information for the attribute in the
fields on the right side of the Attribute page. Here are descriptions of
those fields:
Attribute name The name of the attribute. This name appears in the
connection menu for the part when you make connections to or from
it in the Composition Editor.
Attribute type The data type of the attribute. The first time you create
an attribute for your part, the default data type that Visual
Builder uses is int. If you change int to another data type, such
as IString, the new data type becomes the default data type for
any new attributes that you create until you change it to
something else or close the Part Interface Editor window. When you
reopen the Part Interface Editor window, the default data type for
any new attributes that you create reverts to int. It stays that
way unless you change it again when creating another attribute or
when modifying an existing attribute.
You typically define attributes as private data members to protect
them from being changed by users of the part. The get and set
member functions that you define for an attribute give other
programmers access to the attribute's value. You probably do not
want to expose all of the data members of your part as attributes,
particularly if you intend to share the part with other
programmers. You only need to decide which of the data members you
want to make available for other programmers to reference. Some of
your data members might be used for implementation purposes, so
you would not want to identify these as attributes.
Get member function The public member function used by the part and other
parts to query or get the value of the attribute.
Set member function The public member function used by the part and other
parts to set the value of the attribute. An event identifier is
typically signalled from within the implementation of the set
member function to indicate that the value of the attribute
changed.
If you press either the Defaults or Add with defaults push button,
Visual Builder uses the data type in the Attribute type field to
determine whether the parameter on the set member function passes
the actual value of the attribute being set or simply references
the location of that value, as follows:
- If the data type in the Attribute type field represents the
class name of a part in a loaded .vbb file, Visual Builder
references the location of the value that is to be used to
set the attribute.
For example, suppose you create a part named MyPart. If you
create a text attribute for MyPart with a data type of
IString and select either Defaults or Add with defaults,
Visual Builder puts the following in the Set member function
field:
MyPart & setText(const IString &aText)
The & in front of the aText parameter means that, unless you
modify this member function, it passes a reference to the
value being used to set the text attribute. The & is used
because IString is defined as a part in vbbase.vbb.
- If the data type in the Attribute type field is not defined
in any loaded .vbb file, or if it is defined in a .vbb file
but it does not represent the class name of a part, Visual
Builder passes the actual value that is to be set for the
attribute.
Using the MyPart example again, if you put an undefined data
type in the Attribute type field before selecting either
Defaults or Add with defaults, Visual Builder puts the
following in the Set member function field:
MyPart & setText(const myType aText)
In this example, unless you modify this member function, it
passes the actual value being used to set the text attribute.
Event identification The name of the event identifier that is typically
signalled from within the implementation of the set member
function. You can create one of your own or you can use the
default event identifier that Visual Builder supplies when you
select either Defaults or Add with defaults.
Use this identifier to notify this part and other parts that the
attribute's value has changed. This is typically done when the
attribute is used as the source of a connection. The connection
types that use an attribute as the source of a connection are:
- Attribute-to-attribute
- Attribute-to-action
- Attribute-to-member function
- Custom logic, which can use either an attribute or an event
as the source of a connection
You are not required to specify an event identification for any
attribute because you are not required to notify other parts when
the value of the attribute changes. However, failing to do so
could prevent your application from passing necessary information
from one part to another when it is needed.
The event identifier is typically signalled from within the
implementation of the attribute's set member function, causing the
attribute to behave as an event. Therefore, you do not need to
specify another event with this event identifier on the Event page
of the Part Interface Editor.
Description A description of the attribute. This entry field is blank
unless you enter a description, or you select either the Defaults
or Add with defaults push button, in which case Visual Builder
supplies a default description consisting of the attribute's name.
If you want to add the attribute after seeing or modifying its default
information or after entering your own information, select the Add push
button.
Visual Builder adds the attribute to the part interface.
ΓòÉΓòÉΓòÉ 6.4.2.2. Changing an Attribute ΓòÉΓòÉΓòÉ
To change, or update, an attribute in the Part Interface Editor, do the
following.
Note: You can change anything about an attribute except its name. To change an
attribute's name, you must create a new attribute with the name you want
to use.
1. Select the attribute that you want to change or type its name in the
Attribute name field.
2. Make the changes that you want to make in the fields on the right side of
the Attribute page.
3. Select the Update push button.
Visual Builder saves the changes you made.
ΓòÉΓòÉΓòÉ 6.4.2.3. Deleting an Attribute ΓòÉΓòÉΓòÉ
To delete an attribute in the Part Interface Editor, do the following:
1. Select the attribute that you want to delete or type its name in the
Attribute name field.
2. Select the Delete push button.
Visual Builder deletes the attribute.
Note: If you added the attribute that you just deleted to the preferred
features list, you must go to the Preferred page and delete it
there, too.
ΓòÉΓòÉΓòÉ 6.4.2.4. Setting Defaults for an Attribute ΓòÉΓòÉΓòÉ
To set defaults for an attribute in the Part Interface Editor, do the
following:
1. Select the attribute that you want to set defaults for or type its name
in the Attribute name field.
2. Change the attribute type in the Attribute type field.
3. Select the Defaults push button.
Visual Builder changes all occurrences of the former attribute type to
the new attribute type in the fields on the right side of the Attribute
page.
ΓòÉΓòÉΓòÉ 6.4.2.5. Clearing the Attribute Page Fields ΓòÉΓòÉΓòÉ
To clear the fields on the Attribute page, select the Clear push button.
Visual Builder clears all of the fields on the Attribute page.
ΓòÉΓòÉΓòÉ 6.4.2.6. An Attribute Example ΓòÉΓòÉΓòÉ
Suppose you create a nonvisual Customer part that inherits from Visual
Builder's sample ICustomer part. You also create an age attribute for which you
specify the following:
An attribute type of IString
An age get member function
A setAge set member function
An ageId event notifier
You create this attribute so other parts can access its value or so it can be
passed as a parameter value.
Note: Visual Builder does not use the value that is passed on the attribute's
event. It uses the attribute's get member function instead.
The default feature code that Visual Builder would generate for the age
attribute would be similar to these code segments, which show the following:
The declarations of the get member function, set member function, event
identifier, and data member in the user header (.hpv) file.
public:
IString age() const; /* Get member function */
Customer & setAge(
const IString &aAge); /* Set member function */
static INotificationId ageId; /* Event notifier */
private:
IString iAge; /* Data member */
The event notifier initialized as a text string, followed by the get and
set member functions for the age attribute, as defined in the user source
code (.cpv) file.
INotificationId Customer::ageId = "Customer::ageId";
IString Customer::age() const /* The age attribute's get */
{ /* member function returns */
return iAge; /* the value of the data */
} /* member. */
Customer & Customer::setAge( /* The age attribute's set */
const IString & aAge) /* member function sends */
{ /* the event notification */
if (iAge != aAge) /* when the text changes. */
{
iAge = aAge;
IString eventData(iAge);
notifyObservers(INotificationEvent(Customer::ageId, *this,
true, (void *)&eventData));
} /* endif */
return *this;
}
ΓòÉΓòÉΓòÉ 6.4.3. The Event Page ΓòÉΓòÉΓòÉ
Use the Event page of the Part Interface Editor, shown in the following figure,
to define the events you use to notify this part or other parts about changes
you decide are significant. For example, you might notify other parts when an
attribute is set to a certain value or when important processing is finished.
In this way, someone using your reusable part can link to one of your part's
events and receive automatic notification of the event whenever it is
triggered.
If you cannot see all of the fields shown in the preceding figure, use the
scroll bar on the right side of the Part Interface Editor to see the remaining
fields.
The names of the part's events are displayed in the list box named Event name.
When you create a new part, the first time you open the Part Interface Editor
and turn to the Event page, you see that Visual Builder has provided an event
for you: the ready event.
ΓòÉΓòÉΓòÉ 6.4.3.1. The Ready Event ΓòÉΓòÉΓòÉ
Visual Builder adds the ready event to every new part that you create using the
PartNew menu choice in the Visual Builder window. However, this event is not
added if you import part information from a part information file (.vbe file).
By connecting the ready event to one of your part's subparts, you can cause an
action or member function to be invoked when your application is executed. The
ready event is sent to the part when both of the following occur:
All subparts of the part have been constructed.
All connections have been made and initialized.
For example, suppose you have a part named MyApp and this part is an
application that has a window that contains an animated push button. By
connecting the MyApp part's ready event to the animated push button's
startAnimation action, you cause the push button to become animated as soon as
the application starts running.
The ready event is not a preferred feature by default, but you can add it to
your part's preferred features list. For information on how to do this, see
The Preferred Page.
ΓòÉΓòÉΓòÉ 6.4.3.2. Adding an Event ΓòÉΓòÉΓòÉ
To add an event in the Part Interface Editor, do one of the following:
If you want to add the event using the default event identification that
Visual Builder provides, enter a name in the Event name field and select
the Add with defaults push button.
Visual Builder adds the event to the part interface.
If you want to see the default event identification that Visual Builder
provides before you add the event, select the Defaults push button.
Visual Builder displays the default event identification in the Event
identification field on the right side of the Event page. Here are
descriptions of that field and the other fields on the page:
Event name The name of the event. This name appears in the pop-up menu
for the part when you make connections to or from it in the
Composition Editor if you add it to the preferred features list.
Event identification The name of the event identifier that is actually
used in a member function signalling this event.
Description A description of the event. This entry field is blank unless
you enter a description or unless you select either the Defaults
or Add with defaults push button. In the latter case, Visual
Builder inserts a default description consisting of the event's
name.
Parameters and their types A table used to define a parameter and data
type sent as part of an event.
Name The name of the event parameter.
Type The class, or data type, of the event parameter, such
as IString, integer, or unsigned long.
The parameter that you specify in this table is used to specify
event data, or a reference to that data's location, that you want
to send along with the event identifier as part of the event.
Doing this prevents you from having to perform a separate query
for the data.
To add a parameter and its type to this table, do the following.
Note: You can add only one parameter and type for each event.
1. Move the mouse pointer over the table and click mouse button 2.
Visual Builder displays a pop-up menu.
2. Select either Add before or Add after.
Visual Builder adds a row to the table with a default parameter name and
type.
3. If you want to change the defaults, do the following:
a. Click on the parameter name with mouse button 1.
b. Type the parameter name you want to use.
c. Click on the parameter type with mouse button 1.
d. Type the parameter type you want to use.
e. Select the Update push button.
ΓòÉΓòÉΓòÉ 6.4.3.3. Changing an Event ΓòÉΓòÉΓòÉ
To change, or update, an event, do the following.
Note: You can change anything about an event except its name. To change an
event's name, you must create a new event with the name you want to use.
1. Select the event that you want to change or type its name in the Event
name field.
2. Make the changes that you want to make in the fields on the right side of
the Event page.
3. Select the Update push button.
Visual Builder saves the changes you made.
ΓòÉΓòÉΓòÉ 6.4.3.4. Deleting an Event ΓòÉΓòÉΓòÉ
To delete an event, do the following:
1. Select the event that you want to delete or type its name in the Event
name field.
2. Select the Delete push button.
Visual Builder deletes the event.
Note: If you added the event that you just deleted to the preferred
features list, you must go to the Preferred page and delete it
there, too.
ΓòÉΓòÉΓòÉ 6.4.3.5. Setting Defaults for an Event ΓòÉΓòÉΓòÉ
To set defaults for an event, do the following:
1. Select the event that you want to set defaults for or type its name in
the Event name field.
2. Select the Defaults push button.
Visual Builder changes the former event identification to the default
event identification in the Event identification field.
ΓòÉΓòÉΓòÉ 6.4.3.6. Clearing the Event Page Fields ΓòÉΓòÉΓòÉ
To clear the fields on the Event page, select the Clear push button.
Visual Builder clears all of the fields on the Event page.
ΓòÉΓòÉΓòÉ 6.4.3.7. An Event Example ΓòÉΓòÉΓòÉ
Using the same example shown for the Attribute page, suppose you also create an
invalidDataEntered event for which you specify the following:
An invalidDataEnteredId event notifier
An invalidData parameter with a data type of IString
You create this event because you want to show an error message for the
Customer part whenever invalid data is entered for any of the Customer part's
attributes, such as the customer's age being outside a valid range. Then, in
your source code for the age attribute's set member function, you can call the
notifyObservers member function to display a message asking for a valid age if
the check fails.
The default feature code that Visual Builder would generate for the
invalidDataEnteredId event notifier would be similar to these code segments,
which show the following:
The declarations of the get member function, set member function, event
identifiers, and data member in the user header (.hpv) file.
Note: Sample code highlighted in bold shows the code that was added to
modify the previous example.
public:
IString age() const; /* Get member function */
Customer & setAge(
const IString &aAge); /* Set member function */
static INotificationId ageId; /* Event notifiers */
static INotificationId invalidDataEnteredId;
private:
IString iAge; /* Data member */
The event notifier initialized as a text string, followed by the get and
set member functions for the age attribute, as defined in the user source
code (.cpv) file.
INotificationId Customer::ageId = "Customer::ageId";
INotificationId Customer::invalidDataEnteredId =
"Customer::invalidDataEnteredId";
IString Customer::age() const /* The age attribute's get */
{ /* member function returns */
return iAge; /* the value of the data */
} /* member. */
Customer & Customer::setAge( /* The age attribute's set */
const IString &aAge) /* member function sends */
{ /* the event notification */
if (aAge > 99)
{
notifyObservers(
INotificationEvent(
Customer::invalidDataEnteredId,
*this,
true,
(void *) IString("Enter a value between 1 and 99.")));
}
else
{
if (iAge != aAge)
{
iAge = aAge;
IString eventData(iAge);
notifyObservers(INotificationEvent(Customer::ageId, *this,
true, (void *)&eventData));
} /* endif */
}
return *this;
}
ΓòÉΓòÉΓòÉ 6.4.4. The Action Page ΓòÉΓòÉΓòÉ
Use the Action page of the Part Interface Editor, shown in the following
figure, to define the actions your reusable part uses to perform specific
tasks. Often, you will want to perform some task when a specific event occurs.
For example, you might want to update a balance attribute each time a push
button's buttonClickEvent feature is triggered. You might create an action
named updateBalance to perform this task and connect it to the push button's
buttonClickEvent feature.
The names of the part's actions are displayed in the list box below the Action
name field.
ΓòÉΓòÉΓòÉ 6.4.4.1. Adding an Action ΓòÉΓòÉΓòÉ
To add an action in the Part Interface Editor, do one of the following:
If you want to add the action using the part you are editing as the
default return type, enter a name in the Action name field and select the
Add with defaults push button.
Visual Builder adds the action to the part interface.
If you want to see the default return type before you add the action,
select the Defaults push button.
Visual Builder displays the default return type in the Return type field,
as well as in the Action member function field, on the right side of the
Action page. Here are descriptions of those fields and the other fields
on the page:
Action name The name of the action. This name appears in the pop-up menu
for the part when you make connections to or from it in the
Composition Editor if you add it to the preferred features list.
Action member function The name of the public member function, defined
within your reusable part, that performs the action.
Return type The return type of the action member function.
Description A description of the action.
Parameter Names Parameters of the selected action. Initially, the names
that are inserted in the Parameter Names table are the same as the
parameter names that are specified in the Action member function
field.
The parameter names in the table are linked to the action name and
can appear in a pop-up connection menu. The purpose of the table
is to allow you to change the parameter names that appear in the
part interface without affecting the member function definition
itself. That is, if you change the parameter names in the table,
the parameter names in the Action member function field do not
change.
Here are some reasons for using the Parameter Names table:
- To give parameters descriptive names.
You can give parameters that appear in pop-up connection
menus names that are more descriptive than those in the
member function definition.
- To associate specific parameter names with actions.
You might have more than one action name for the same public
member function. If so, to make your part interface easier to
use, you might not want to have the same parameter name
associated with each action. The Parameter Names table allows
you associate separate, descriptive parameter names with each
action, even though those names represent the same parameter
in the same member function.
- To change a member function without changing its action name
in the part interface.
You might decide to change a member function. For example,
you might rename a parameter or substitute another member
function entirely. The Parameter Names table allows you to do
this without having to change your part interface. You can
modify and then update the information in the Action member
function field without changing the parameter names in the
table. Therefore, if other programmers are using your part,
they continue to see the same part interface. They would only
need to regenerate their source code.
ΓòÉΓòÉΓòÉ 6.4.4.2. Changing an Action ΓòÉΓòÉΓòÉ
To change, or update, an action in the Part Interface Editor, do the following.
Note: You can change anything about an action except its name. To change an
action's name, you must create a new action with the name you want to
use.
1. Select the action that you want to change or type its name in the Action
name field.
2. Make the changes that you want to make in the fields on the right side of
the Action page.
3. Select the Update push button.
Visual Builder saves the changes you made.
ΓòÉΓòÉΓòÉ 6.4.4.3. Deleting an Action ΓòÉΓòÉΓòÉ
To delete an action in the Part Interface Editor, do the following:
1. Select the action that you want to delete or type its name in the Action
name field.
2. Select the Delete push button.
Visual Builder deletes the action.
Note: If you added the action that you just deleted to the preferred
features list, you must go to the Preferred page and delete it
there, too.
ΓòÉΓòÉΓòÉ 6.4.4.4. Setting Defaults for an Action ΓòÉΓòÉΓòÉ
To set defaults for an action in the Part Interface Editor, do the following:
1. Select the action that you want to set defaults for or type its name in
the Action name field.
2. Select the Defaults push button.
Visual Builder changes the former return type to the default return type
in both the Action member function and the Return type fields.
ΓòÉΓòÉΓòÉ 6.4.4.5. Clearing the Action Page Fields ΓòÉΓòÉΓòÉ
To clear the fields on the Action page, select the Clear push button.
Visual Builder clears all of the fields on the Action page.
ΓòÉΓòÉΓòÉ 6.4.5. The Promote Page ΓòÉΓòÉΓòÉ
Use the Promote page of the Part Interface Editor to specify features that you
want to connect to another part when this part is embedded as a subpart within
another part. The features (attributes, events, and actions) that you specify
appear in the window that is displayed when you select More from this part's
pop-up connection menu. For a complete description of promoting a part's
features, see Promoting a Part's Features.
The following figure shows the Promote page:
ΓòÉΓòÉΓòÉ 6.4.5.1. Promoting a Feature ΓòÉΓòÉΓòÉ
To promote a feature in the Part Interface Editor for a subpart, do the
following:
1. Select a subpart name from the list box beneath the Subpart name field or
type the name in the field.
Visual Builder displays the name of the subpart that you select in the
Subpart name field.
2. Select a feature type from the list box beneath the Feature type field or
type the name in the field.
Visual Builder displays the type that you select (attribute, event, or
action) in the the Feature type field.
3. Select the feature that you want to promote from the list box beneath the
Promotable feature field or type the name in the field.
Visual Builder displays the feature that you select in the Promotable
feature field.
4. Do one of the following:
If you want to promote the feature using the default name that
Visual Builder provides, select the Add with defaults push button.
Visual Builder promotes the feature and displays the feature name in
both the Promote feature name field and in the list box below this
field.
If you want to see the default feature name that Visual Builder
provides before you promote the feature, select the Defaults push
button.
Visual Builder displays the default name for the feature in the
Promote feature name field.
If you want to promote a feature after seeing its default name or
typing another name that you prefer, select the Add push button.
Visual Builder promotes the feature using the name in the Promote
feature name field and displays the name in the list box below this
field.
ΓòÉΓòÉΓòÉ 6.4.5.2. Changing a Promoted Feature ΓòÉΓòÉΓòÉ
To update a feature that you have already promoted, do the following:
1. Select the promoted feature that you want to update.
2. Select those aspects of the promoted feature that you want to update in
the fields on the right side of the Promote page. You can select any or
all of the following:
Subpart name
Feature type
Promotable feature
3. Select the Update push button.
Visual Builder updates those aspects of the feature that you selected.
The only noticeable change is the subpart name if you selected a different
one. The subpart name shown in parentheses behind the promoted feature name
changes if you selected a different subpart. For example, suppose you promoted
the buttonClickEvent feature of PushButton1 and then realized you should have
promoted the buttonClickEvent feature of PushButton2. Instead of deleting the
promoted feature, you can update it by changing only its subpart.
ΓòÉΓòÉΓòÉ 6.4.5.3. Deleting a Promoted Feature ΓòÉΓòÉΓòÉ
To delete a promoted feature, do the following:
1. Select the promoted feature that you want to delete.
2. Select the Delete push button.
Visual Builder deletes the promoted feature from the list box beneath the
Promote feature name field.
Note: If you added the promoted feature that you just deleted to the
preferred features list, you must go to the Preferred page and
delete it there, too.
ΓòÉΓòÉΓòÉ 6.4.5.4. Clearing the Promote Page Fields ΓòÉΓòÉΓòÉ
To clear the fields on the Promote page, select the Clear push button. Visual
Builder removes the information from all of the fields on the page.
ΓòÉΓòÉΓòÉ 6.4.6. The Preferred Page ΓòÉΓòÉΓòÉ
Use the Preferred page of the Part Interface Editor to specify the preferred
features for your part-the features that you use most often when connecting
this part to another part. The features (attributes, events, and actions) that
you specify appear in the pop-up menu that is displayed when you begin a
connection on this part. You can include any features that exist for your part,
as well as any features that your part inherits from other parts.
In addition to these features, the pop-up connection menu contains the More
selection. This selection allows you to display a window that contains all of
the features for this part, as well as the features it inherits. Visual Builder
provides this window in case you need a feature that is not in the preferred
features list.
The names of the part's features are displayed in the list boxes named Actions,
Attributes, and Events on the left side of the page. The preferred features are
displayed in the Preferred Features list box on the right side of the page.
ΓòÉΓòÉΓòÉ 6.4.6.1. Adding a Preferred Feature ΓòÉΓòÉΓòÉ
To add a preferred feature to the connection menu for a part, do the following:
1. Select a feature name from one of the list boxes on the left side of the
page.
2. Do either of the following:
Select the Add push button at the bottom of the page.
With the mouse pointer still over the list box in which you selected
the feature name, do the following:
a. Click mouse button 2.
A pop-up menu with the Add choice appears.
b. Select Add to add the feature.
The feature name that you selected is inserted into the Preferred
Features list box in alphabetical order.
ΓòÉΓòÉΓòÉ 6.4.6.2. Removing a Preferred Feature ΓòÉΓòÉΓòÉ
You can remove a preferred feature name from the connection menu for a part.
Doing this removes the feature from the menu only; it does not delete the
feature.
To remove a preferred feature from the connection menu for a part, do the
following:
1. Select the name that you want to remove from the Preferred Features list
box.
2. Do either of the following:
Select the Remove push button at the bottom of the page.
With the mouse pointer still over the feature name in the Preferred
Features list box, do the following:
a. Click mouse button 2.
A pop-up menu appears.
b. Select Remove to remove the selected feature.
A message box is displayed to make sure you want to remove the name of
this preferred feature.
3. Select Yes to remove the feature name from the list.
The feature name that you selected is removed from the list.
ΓòÉΓòÉΓòÉ 6.4.6.3. Removing All Preferred Features ΓòÉΓòÉΓòÉ
You can remove all of the feature names from the connection menu for a part.
Doing this removes the features from the menu only; it does not delete the
features. Once you remove all preferred features from the connection menu, you
must select More to use the features in a connection.
To remove all of the preferred features from the connection menu for a part, do
either of the following:
Select the Remove all push button at the bottom of the page.
With the mouse pointer over the Preferred Features list box, do the
following:
1. Click mouse button 2.
A pop-up menu appears.
2. Select Remove all to remove all of the selected features.
A message box is displayed to make sure you want to remove all of the
preferred features.
Select Yes to remove all of the feature names from the list. All of the
feature names are removed from the list.
ΓòÉΓòÉΓòÉ 6.4.6.4. Showing Inherited Preferred Features Only ΓòÉΓòÉΓòÉ
To show only the preferred features that your part inherits from other parts,
select the Default push button.
A message box is displayed. Select Yes to display only the inherited preferred
features.
ΓòÉΓòÉΓòÉ 7. Developing Applications ΓòÉΓòÉΓòÉ
Designing effective applications
Designing parts for a single purpose
Taking the object-oriented approach
Identifying reusable parts
Using inheritance
Using abstract classes
Keeping your components small
Designing parts for the OASearch application
Using a simulated database
Designing nonvisual parts
Designing visual parts
How the sample application was built
Personal notes:
ΓòÉΓòÉΓòÉ 7.1. Designing Effective Applications ΓòÉΓòÉΓòÉ
When designing your applications, remember that Visual Builder implements parts
as C++ classes. Therefore, keep in mind good design practices and techniques
that apply to both classes and parts.
At the heart of Visual Builder lies visual programming and construction from
parts. The predefined palette of reusable parts coupled with the Composition
Editor provide a new level of power in developing applications. Of course,
increased power does not guarantee good design and improved productivity, so
the following sections are provided to assist you in designing more effective
Visual Builder applications.
ΓòÉΓòÉΓòÉ 7.2. Designing Parts for a Single Purpose ΓòÉΓòÉΓòÉ
Much like designing the user interface of any application, you need to design
each part in your Visual Builder application for a single purpose. For example,
consider an application that queries a simulated database for information about
contractors, their skills, and the contracts to which they are assigned. These
queries clearly identify the three actions that can be performed using the
application. Therefore, this application needs a separate part that shows the
results of each query.
These parts could include a notebook that displays information about individual
contractors, a window with entry fields that contain information about a
specific contract, and a container that shows which contractors have a certain
skill. Each of these specific queries becomes the single purpose around which
you design your parts. Of course, supporting parts such as a main window for
starting the queries, nonvisual parts that supply the results of a search, and
dialogs for specifying the search targets are also required.
You can then combine your parts into a single business-wide application that
can be shared by multiple users. Each user has direct access to the parts
needed to complete a specific query without interference from any parts of the
application that are conducting other queries.
In Designing Parts for the OASearch Application, we introduce a sample
application that can perform the queries described in this section and explain
the design of each of the application's parts.
ΓòÉΓòÉΓòÉ 7.3. Taking the Object-Oriented Approach ΓòÉΓòÉΓòÉ
Object-oriented design seeks to find parallels between computer entities and
real-world entities. By not blurring the lines between the roles and tasks of
the business, and by providing a part for each, you effectively provide a
computer application that parallels the way your business operates in the real
world.
Thinking more closely in terms of Visual Builder and the Composition Editor,
parts that are too large can have a negative effect on usability, performance,
and maintenance. As a general rule, for each part, you want to use the minimum
number of visual parts, nonvisual parts, connections, and parameters necessary
to achieve a single purpose.
In addition, try to use attributes whenever possible instead of actions.
Attribute-to-attribute connections, for example, tend to minimize the number of
required connections because usually you do not need any additional connections
to provide a parameter as you do with actions.
Here is a sample list of steps you might follow to create an OO application
using Visual Builder:
1. Design the application.
Decide which tasks and functions you want the application to
perform.
Determine how you will represent those tasks and functions on the
interface.
Design the user interface, deciding which windows the application
displays.
If more than one window is involved, decide which one is to be the
main window. The main window normally consists of the following:
- The window that users first see when they start the application
- Any other visual parts that are included in the window, such as
list boxes, entry fields, and push buttons
- Any nonvisual parts that are needed, such as object factories
Decide which parts the application needs in order to provide those
windows and to support the task a user wants to accomplish.
Decide which member functions the parts need by determining what
messages need to be sent from one object to another.
Decide which data members the parts need by determining the various
types of data the part is to provide.
Decide which features (attributes, events, and actions) the parts
need.
Decide which features of each part need to be connected to features
of another part. For example, a Close push button can close a window
only if its buttonClickEvent feature is connected to the window's
close action.
2. Create any parts you need that Visual Builder does not already provide,
or that someone else has not already created.
3. Create the main window and any other required windows using the parts and
connections predetermined in the previous steps.
4. Generate the C++ code for the application.
5. Make any necessary modifications to the generated C++ feature code.
6. Build and run the application.
Developing an OO application is a process in which these (and perhaps other)
steps are usually repeated many times. For that reason, the preceding steps
are provided merely as an example. You might not follow them exactly in the
order given when creating your applications. For example, you might not
realize that you need to create a certain part until you have already started
creating a composite part.
The next section, Identifying Reusable Parts, suggests ways to get the most
from parts, once you have settled upon their high-level design.
ΓòÉΓòÉΓòÉ 7.4. Identifying Reusable Parts ΓòÉΓòÉΓòÉ
Once you have the high-level design of your application's parts, identify
common elements. These common elements are perfect opportunities for reuse.
Make them into reusable parts and add them to the parts palette.
For example, go back to the application that queries for contractor, skill, and
contract information. Consider the visual part that displays information about
an individual contractor. Along with the information supplied for each
contractor is the contractor's name and address. You can make this common
address element into a reusable, composite visual part that looks like this:
You can then reuse the same address part in visual parts for other applications
you create. By reusing parts, you increase productivity. For example, you only
have to lay out the form once. In addition, because the State and Postal code
field formats differ from the default formats used by the other fields, you
only have to set the formats for these fields once, as well.
You also get the potentially more important benefit of improved maintenance.
For example, if an error is discovered, you only have to fix it in one place.
Or later, if your business decides to start using an Auxiliary address field,
you would only have to make the change once to your visual address part.
Likewise, if the business grows into worldwide sales, then you could change
State to State/Region, and add a Country field (provided you are using a
database that can accommodate such changes). Having to make these changes only
once saves time.
The next section, Using Inheritance, suggests more ways to reuse parts.
ΓòÉΓòÉΓòÉ 7.5. Using Inheritance ΓòÉΓòÉΓòÉ
As you are scanning your application looking for common elements, do not
overlook the possibility of reusing an entire part. You can reuse both
nonvisual and class interface parts.
Many times, you need parts that are similar to ones you have already built.
Inheritance gives you an easy way to make new parts from the ones you already
have. Reusing existing parts through inheritance saves most of the work that
would usually be required to create a new part.
Example
Suppose you created a new nonvisual part named Person. You could use
inheritance to build a derived Contractor part that inherits the Person part's
features and has other features of its own. The following example assumes you
have already created a nonvisual Person part.
1. Begin in the Visual Builder window by selecting PartNew.
The following window is displayed:
2. Type Contractor in the Class name field.
3. Change the part type to Nonvisual part in the Part type field.
4. Enter Person in the Base class field.
Your new Contractor part now inherits from your Person part. Your window
looks like the following:
5. Select Open to create the part and open the Part Interface Editor.
When the Part Interface Editor opens, it displays the Attribute page.
6. Add new attributes that a contractor might have, such as startDate,
endDate, and activeStatus.
The next section, Using Abstract Classes, suggests ways to factor out common
classes and member functions so you can better reuse the code that you write.
ΓòÉΓòÉΓòÉ 7.6. Using Abstract Classes ΓòÉΓòÉΓòÉ
The technique of scanning your application for common elements applies as much
to code as it does to visual parts.
As you are writing member functions that enhance your visual parts, look for
common member functions. These common member functions indicate perfect
opportunities for reuse and can possibly be placed in an abstract class.
Abstract classes are used for factoring out common behavior. They are not
intended to define any particular real part. Therefore, never represent an
abstract class as a part on the free-form surface of the Composition Editor.
Instead, use the abstract class as the base class, or as an ancestor of the
base class, of nonvisual or class interface parts that you create and place on
the free-form surface.
Abstract classes are repositories for common member functions. The similarities
between your various parts determine which member functions are candidates to
be grouped together under a common abstract class.
If you move a member function from a part to an abstract class,
remove that member function from the interface of the part from
which it was removed. You are not required to do this, but
maintaining your application is easier if each part properly
reflects only the member functions it contains in its part
interface.
All of the benefits of reuse are achieved, namely increased productivity and
reduced maintenance, from only having to write and maintain the member
functions in one place.
The next section, Keeping Your Components Small, emphasizes a common theme in
designing effective Visual Builder applications.
ΓòÉΓòÉΓòÉ 7.7. Keeping Your Components Small ΓòÉΓòÉΓòÉ
As the topics in this chapter have probably made clear by now, a primary goal
of any object-oriented environment, including Visual Builder, is reuse, for
which keeping your components small is fundamental. The smaller you make the
components of your applications, the more opportunity you have to take
advantage of reuse.
The following table provides the numbers, based on C++ research, that you
should aim for in creating your classes, member functions, and data members.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéCriteria ΓöéOptimum number ΓöéReason Γöé
ΓöéAverage lines per member ΓöéFewer than 24 ΓöéA higher average generally Γöé
Γöéfunction Γöé Γöéindicates poor Γöé
Γöé Γöé Γöéobject-oriented design and aΓöé
Γöé Γöé Γöétendency toward Γöé
Γöé Γöé Γöéfunction-oriented Γöé
Γöé Γöé Γöéprogramming. Γöé
ΓöéAverage member functions perΓöéNo more than 20 ΓöéHigher averages indicate youΓöé
Γöéclass Γöé Γöécan distribute your member Γöé
Γöé Γöé Γöéfunctions among more Γöé
Γöé Γöé Γöéclasses. Γöé
ΓöéAverage data members per ΓöéNo more than six ΓöéHigher averages indicate youΓöé
Γöéclass Γöé Γöécan distribute your data Γöé
Γöé Γöé Γöémembers among more classes. Γöé
ΓöéAverage number of base ΓöéNo more than six ΓöéInheriting from too many Γöé
Γöéclasses per class Γöé Γöéclasses indicates too few Γöé
Γöé Γöé Γöémember functions in each Γöé
Γöé Γöé Γöéclass. This can cause Γöé
Γöé Γöé Γöéperformance and size Γöé
Γöé Γöé Γöéproblems because the more Γöé
Γöé Γöé Γöébase classes from which yourΓöé
Γöé Γöé Γöéclasses inherit, the slower Γöé
Γöé Γöé Γöéyour compiled code runs and Γöé
Γöé Γöé Γöéthe larger it becomes. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
These numbers generally depend on the complexity of the class. Less complex
classes that take full advantage of prewritten reusable parts typically have
fewer member functions per class. Also, the number of data members depends on
how data-intensive the classes are. However, many of the member functions and
data members you need can be inherited by default from classes provided by
Visual Builder.
Applying the design strategies covered in these sections and gaining experience
should help you achieve these averages.
ΓòÉΓòÉΓòÉ 7.8. Designing Parts for the OASearch Application ΓòÉΓòÉΓòÉ
A sample application is used in this part of the book to show you how to build
a simple GUI application. You can find the nonvisual parts in oanonvis.vbb. All
visual parts are in oawin.vbb. For in-depth information about designing your
own parts, refer to Building VisualAge C++ Parts for Fun and Profit.
This application, called OASearch, serves recruiters for a fictitious technical
contracting services firm, called Opportunities Abound (OA). Customers call OA
to request temporary help; recruiters use the application to match skill
requirements with available contractors. When matches are made, the recruiters
enter contract information into the application.
ΓòÉΓòÉΓòÉ 7.8.1. Using a Simulated Database ΓòÉΓòÉΓòÉ
This sample application does not require the installation of a database
program. Instead, the application uses the IProfile class to create and
maintain a simple database in three .ini files. To see the implementation,
browse the following code files:
contrctr.cpv
contract.cpv
skillb.cpv
For more information about the IProfile class, refer to the IBM Open Class
Library Reference.
ΓòÉΓòÉΓòÉ 7.8.2. Designing Nonvisual Parts ΓòÉΓòÉΓòÉ
When designing your own application, take extra time to think through the
nonvisual parts. One way to minimize rework during design is to use index
cards, putting the data and tasks of each part or class on a separate card.
This method enables you to throw away one design in favor of another,
rearranging the cards until you are confident of your design.
The OASearch application uses the following nonvisual parts to hold or manage
data:
OAContractor, which represents OA employees
OAContract, which represents OA contracts
OASkill, which represents marketable skills held by OA's employees
OASkillBase, which controls traffic between the OASkillView window and
the skill database. This is necessary because of the one-to-many
relationship that exists between OAContractor and OASkill instances. That
is, many contractors could hold the same skill and a single contractor
could hold many skills.
SkillList, a part instance of type IVSequence. For more information about
sequences, refer to the Visual Builder Parts Reference.
ΓòÉΓòÉΓòÉ 7.8.2.1. The OAContractor Part ΓòÉΓòÉΓòÉ
When you design a Visual Builder part, you are designing a C++ class. The part
interface corresponds to the part interface of the underlying class. The class
can also have member functions (public, protected, or private) that do not
exist in the part interface.
OAContractor Attributes
The OAContractor part has the following attributes:
lastName, the contractor's last name
firstName, the contractor's first name
middleInitial, the contractor's middle initial
homeStreet, the contractor's home street address
homeCity, the contractor's home city
homeState, the contractor's home state or province
homeZip, the contractor's home postal code
phoneNumber, the contractor's daytime phone number
startDate, the date on which the contractor started working at
Opportunities Abound
endDate, the date on which the contractor stopped working at
Opportunities Abound
activeStatus, whether the contractor is interested in a new position
currentContract, the contractor's current assignment (if any)
contractorID, the contractor's database identifier
All attributes are of type IString, except for the activeStatus attribute,
which is of type Boolean. The contractorID attribute is derived from the
contractor's name attributes.
To enable you to use these attributes, the contractor part must also contain
public get and set member functions. By convention, the names of these member
functions follow a pattern determined by the name of the attribute. For the
IString attribute lastName, the get member function is called lastName, and
the set member function is called setLastName. For the Boolean attribute
activeStatus, the get member function is called isActiveStatus, and the set
member function is called enableActiveStatus.
To retrieve or update contractor information from the database, the
OAContractor part contains the following actions:
getContractor
OAContractor & getContractor();
parseName
OAContractor & parseName(const IString & aName);
putContractor
OAContractor & putContractor();
The parseName action parses an input string to set the firstName,
middleInitial, and lastName attributes. The getContractor and putContractor
actions use the derived attribute contractorID to retrieve and store
contractor information in the database. The feature code for this part appears
in contrctr.cpv.
For a look at the visual part that OAContractor supports, see The
Opportunities Abound Contractor Information Window.
ΓòÉΓòÉΓòÉ 7.8.2.2. The OAContract Part ΓòÉΓòÉΓòÉ
The OAContract part contains the following attributes:
accountNum, the contract's account number
companyName, the name of the client company
projectMgr, the client company's representative
deptName, the department within the client company that needs a position
filled
positionTitle, a description of the position to be filled
startDate, the first day of work at the client company
endDate, the last day of work at the client company
currContractor, the identifier of the contractor filling the position
It also contains the following actions:
getContract
OAContract & getContract(const IString & anAccountNum);
putContract
OAContract & putContract(const IString & anAccountNum);
All attributes are of type IString. The feature code for this part appears in
contract.cpv.
For a look at the visual part that OAContract supports, see The Opportunities
Abound Contract Information Window.
ΓòÉΓòÉΓòÉ 7.8.2.3. The OASkill Part ΓòÉΓòÉΓòÉ
The OASkill part contains the following attributes:
skillName, a description of the skill required
yearsExp, the number of years of experience needed
contractorID, the identifier of the contractor holding this skill
key, an index used to construct the database key
All attributes are of type IString. The feature code for this part appears in
skill.cpv.
For a look at the visual part that OASkill supports, see The Opportunities
Abound Skill Information Window.
ΓòÉΓòÉΓòÉ 7.8.2.4. The OASkillBase Part ΓòÉΓòÉΓòÉ
The OASkillBase part contains no attributes but has the following actions:
getSkills
OASkill & getSkills(const IString & aSkillName, IVSequence <OASkill*> & aList);
This action retrieves skill information from the database, instantiates
OASkill objects from retrieved information, and adds pointers for the new
objects to the specified list of skills.
putSkill
OASkill & putSkill(const OASkill & aSkill);
This action stores skill information in the database.
The feature code for this part appears in skillb.cpv.
For a look at the visual part that OASkillBase supports, see The Opportunities
Abound Skill Information Window.
ΓòÉΓòÉΓòÉ 7.8.3. Designing Visual Parts ΓòÉΓòÉΓòÉ
Although the OASearch application was designed to illustrate variety more than
efficiency, consider the following design decisions:
The Opportunities Abound Databases window (part OAMain) is the
integration point for the application. All variables found in the other
composite parts are resolved in OAMain. All parts except the OASkill
search results are instantiated here.
The connections between visual parts are minimized with the use of
promoted variables to pass data. Inside each visual part,
attribute-to-attribute connections load data from the variables into the
windows.
All views use multicell canvases to hold the primitive visual parts. They
are as follows:
- The Opportunities Abound Databases window
- The Opportunities Abound General Information window
- The query windows
- The Opportunities Abound Contractor Information window
- The Opportunities Abound Contract Information window
- The Opportunities Abound Skill Information window
ΓòÉΓòÉΓòÉ 7.8.3.1. The Opportunities Abound Databases Window ΓòÉΓòÉΓòÉ
The welcome window for OASearch appears in the following figure:
This first window to appear is the primary view; the part containing this
window, OAMain, is the main part. To view information, recruiters can use the
View submenu or press one of the three graphic push buttons. To enter
information about new contracts or contractors, they can use the Edit submenu.
This window shows use of the following:
Menu bar
Embedded multicell canvas
Icons as resources
Object Factory parts
Variables used with Object Factory parts
ΓòÉΓòÉΓòÉ 7.8.3.2. The Opportunities Abound General Information Window ΓòÉΓòÉΓòÉ
When a user selects General information from the View submenu, the
Opportunities Abound General Information window appears, as shown in the
following figure:
This window shows use of the following:
IViewPort* with multicell canvas
Handler class (IVBMinSizeViewPortHandler) for IViewPort*
This window uses an IViewPort* part as the client. An IMultiCellCanvas* part
within the IViewPort* holds the IStaticText* parts. In the compiled
application, the handler resizes the IMultiCellCanvas* whenever the window is
resized.
To see what happens when the handler is not running, open the OAGenInfo part
in the Composition Editor. If you resize the IFrameWindow* part, the
IViewPort* part is resized automatically, but the IMultiCellCanvas* part is
not. You must resize the IMultiCellCanvas* part manually to fit inside the
border of the resized IFrameWindow*.
ΓòÉΓòÉΓòÉ 7.8.3.3. The Query Windows ΓòÉΓòÉΓòÉ
When recruiters select a graphic push button or View menu item from the
Opportunities Abound Databases, a query window appears, as shown in the
following figure:
The OAQuerySkill part contains this window. Two other parts, OAQueryContract
and OAQueryContractor, hold other query windows.
When a user enters a value in the query window and selects the OK push button,
the query window closes and the corresponding information window appears. If
the requested value is not found, a message box appears. Users can also get
help or return to the Opportunities Abound Databases window.
This window shows use of the following:
Modal window display
Help enablement
Promoted variables features
ΓòÉΓòÉΓòÉ 7.8.3.4. The Opportunities Abound Contractor Information Window ΓòÉΓòÉΓòÉ
When the requested contractor is found in the contractor database, the
Opportunities Abound Contractor Information window appears, as shown in the
following figure:
The application retrieves the records matching the requested contractor
identifier, sets an OAContractor* part, and displays the values in this window.
The Contact page contains information about how to get in touch with the
contractor. The History page contains information about the contractor's work
history. The Skills page is provided for users of the sample application to
update skills a hypothetical contractor has.
This window shows use of the following:
INotebook* part
Different multicell canvas layouts
Event-to-member function connection
Event-to-custom logic connection
Variables used as placeholders
Promoted features
ΓòÉΓòÉΓòÉ 7.8.3.5. The Opportunities Abound Contract Information Window ΓòÉΓòÉΓòÉ
When the requested contract is found in the contract database, the
Opportunities Abound Contract Information window appears, as shown in the
following figure:
The application retrieves the records matching the requested contract account
number, sets an OAContract* object, and displays the values in the window. This
window shows basic multicell canvas layout.
A variant of the OAContractView part, ContractView, appears in contract.vbb.
This version of the Opportunities Abound Contract Information window uses an
ICanvas* part instead of a multicell canvas. It is formatted for an XGA/8514
display.
ΓòÉΓòÉΓòÉ 7.8.3.6. The Opportunities Abound Skill Information Window ΓòÉΓòÉΓòÉ
When the requested skill is found in the skill database, the Opportunities
Abound Skill Information window appears, as shown in the following figure:
The application retrieves all records matching the requested search
description, creating instantiating an OASkill object for each pair of records
(contractor and years of experience) found. Each new OASkill object is put into
a list and, from there, into the container shown in the window. Recruiters can
search on other skills without leaving this window by typing the new skill
description into the entry field and selecting the Refresh push button.
This window shows use of the following:
IVBContainerControl*
IContainerColumn*
IVSequence*
ΓòÉΓòÉΓòÉ 7.8.4. How the Sample Application Was Built ΓòÉΓòÉΓòÉ
The OASearch application was developed in the following order:
1. The major nonvisual parts were designed.
2. The major visual parts were designed.
3. The nonvisual parts were built.
4. The view parts were built.
5. The query parts were built.
6. The OAMain and OAGenInfo parts were built.
7. Code for all parts was generated at the same time from the Visual Builder
window.
ΓòÉΓòÉΓòÉ 8. Creating Nonvisual Parts ΓòÉΓòÉΓòÉ
What you will achieve
Defining the part interface
Adding code to your part
Personal notes:
ΓòÉΓòÉΓòÉ 8.1. What You Will Achieve ΓòÉΓòÉΓòÉ
This chapter describes how to define your own parts. For this example, we will
create a nonvisual part, OAContractor, because it illustrates the process
better than a visual part.
For information about using the Composition Editor to create visual parts, see
Learning Visual Construction Fundamentals. For more information about using the
Part Interface Editor to define part interfaces, see Touring the Part Interface
Editor.
You create a part by doing the following:
1. Design the part.
2. Define the part interface, either through the Part Interface Editor or by
importing a part information file.
3. Add code to your part. You can use C++ code written outside of Visual
Builder, or you can generate default feature code in Visual Builder and
modify it.
If you have previously existing C++ code that you would like to use in your
part, the following process is probably more efficient:
1. Design the part.
2. Define the part interface using part information files.
ΓòÉΓòÉΓòÉ 8.2. Defining the Part Interface ΓòÉΓòÉΓòÉ
When you are satisfied with your part's design, you are ready to define the
part interface to Visual Builder.
1. Define the attributes of your part.
A part's attributes typically correlate to the class' data members and
can additionally include derived attributes, or attributes that are
determined based on the value of other attributes.
2. Define the member functions that get or set the value of those
attributes.
3. Define any actions that you want the part to be able to do.
A part's actions correlate to the class' public member functions.
4. Specify the event notification identifier used to signal a change in the
value of each attribute.
You can define the part interface in either of the following ways:
Use the Part Interface Editor. With this method, you create the part from
the Visual Builder window and then enter each feature of the part
interface individually using the pages of the Part Interface Editor.
Use a part information file. With this method, you encode part
information in a file and then create the part and its interface by
importing the information into Visual Builder. This method might be more
efficient if C++ code already exists for your part. See Using Existing C
and C++ Code with Visual Builder and refer to Building VisualAge C++
Parts for Fun and Profit for information about creating part information
files.
ΓòÉΓòÉΓòÉ 8.2.1. Defining the Part Interface Using the Part Interface Editor ΓòÉΓòÉΓòÉ
Open a new nonvisual part called OAContractor. The Part Interface Editor
appears.
On the Attribute page, do the following:
1. Type lastName in the Attribute name text-entry field and select the Add
with defaults push button.
Your Part Interface Editor looks like the following figure:
Notice that several default values are displayed:
The default Attribute type is IStandardNotifier*. This means that
the lastName attribute is an instance of the IStandardNotifier*
class.
The default Get member function, lastName, matches the lastName
member function of your design. When your contractor part is queried
for the value of its lastName attribute, it executes the lastName
member function to retrieve the contractor's last name.
The default Set member function is setLastName. When your contractor
part is passed the name that has been assigned to the contractor, it
uses the setLastName member function to store the value in its
lastName attribute.
The default Event notification is lastNameId. When a value is stored
in the lastName attribute using the setLastName member function, the
contractor part signals this event to let other parts know that the
value has changed. For example, if there is an
attribute-to-attribute connection between lastName and a label's
string value, the label part is informed so that it displays the
latest value.
If needed, you can explain more about the attribute in the
Description field.
2. Change any of the default values, if needed. For this example, change the
default attribute type to IString. You can do this by typing the value
directly into the entry field or by selecting the drop-down list box
arrow to the right of the entry field and selecting IString from the
list.
Also, edit the Get member function and Set member function fields,
changing IStandardNotifier to IString. This causes these member functions
to accept IString as a parameter instead of IStandardNotifier.
3. Select the Update push button to save the changes you just made.
4. Select the Clear push button to clear the fields before adding the next
attribute.
5. Repeat the previous steps for the contractor's firstName, middleInitial,
homeStreet, homeCity, homeState, homeZip, startDate, endDate,
currentContract, and phoneNumber attributes. For these attributes,
specify the IString attribute type before selecting the Add with defaults
push button in the first step. This prevents you from having to change
IStandardNotifier* to IString as you did previously.
6. Define the contractorID attribute as IString, with the following get
member function:
OAContractor & getContractorID ();
This attribute is derived from other attributes; we will add the code for
this later. You do not want users to set this attribute directly, so do
not include a setContractorID member function.
7. Define the activeStatus attribute as Boolean. Note that the default get
member function and set member function follow a different format than
the ones for IString attributes.
8. To define the actions for OAContractor, select the Action page.
9. Type putContractor in the Action name field and the following into the
Action member function field:
OAContractor & putContractor();
10. Select the Add push button; then select Clear.
11. Repeat for the getContractor and parseName actions. At this point, the
Action page appears as shown in the following figure:
12. Select Save from the File pull-down menu to save your work.
The next step is adding code to your part.
ΓòÉΓòÉΓòÉ 8.3. Adding Code to Your Part ΓòÉΓòÉΓòÉ
Once you have specified the part interface for your part, you are ready to add
the code to make the part work. Adding code involves the following tasks:
1. Generating default feature code. If you already have C++ code for your
part and have imported the part information, this step is not necessary.
2. Modifying the feature code.
3. Adding code created outside Visual Builder if it already exists.
ΓòÉΓòÉΓòÉ 8.3.1. Generating Default Feature Code ΓòÉΓòÉΓòÉ
If code does not already exist for your part, you can use Visual Builder to
generate default feature code. Default feature code consists of code that is
based on the part interface you defined earlier. For most attributes, the
default feature code is sufficient to define get member functions, set member
functions, and event notifications. For actions, you have to modify the default
feature code to add the function or logic you want your part to perform.
If you also use Visual Builder to generate the default source code for your
parts, you will find it helpful to generate default feature code separately.
Each time you generate default source code, Visual Builder replaces the
existing files with new ones because there is no need for you to modify these
files.
The files that you usually need to modify are the default feature code files.
These are the files in which you write the code to tell your application how to
perform the actions that you create in the Part Interface Editor. Each time you
generate default feature code, Visual Builder appends the newly generated code
to the end of each existing feature code file. This is done so that you will
not lose any code that you have written.
In addition, you do not have to generate new code for all of your features each
time you need default code for a feature. You can create a new feature in the
Part Interface Editor and then generate default feature code just for the new
feature. Visual Builder appends the default code for the new feature to end of
the existing files so that you can modify it.
Note: If you regenerate default code for a feature, be sure to remove the
previous code for that feature from the file to prevent compilation
errors or unwanted results.
To generate default feature code for the OAContractor part, follow these
steps.
Note: This example is a continuation of the example in the preceding section
using the OAContractor part, which should be open in the Part Interface
Editor.
1. Switch to the Class Editor by selecting the icon in the lower-right
corner of the window.
2. Specify the .hpv and .cpv files for Visual Builder to use for the default
feature code for the OAContractor part's attributes and actions by
filling in the following fields:
User .hpv file contrctr.hpv
User .cpv file contrctr.cpv
The Class Editor with the appropriate fields filled in is shown in the
following figure:
3. Select FileSave and GenerateFeature source.
The Generate feature source code window appears, as shown in the
following figure:
4. Generate the default feature code using one of the following methods:
Select the Generate all push button to generate default feature code
for member functions and data members.
Select the appropriate member functions and data members from the
Member functions, Attribute data members, or Event data members list
boxes. Then, select the Generate selected push button.
The first time you will probably want to generate code for all of your
features. Then, you can generate code for other features as you add them.
For this example, select the Generate all push button.
The default feature code is stored in the files you specified in the
Class Editor, contrctr.hpv and contrctr.cpv. If these files already
exist, the code you just generated is appended to the ends of these
files.
For most parts, you must modify the default code to make your part fully
functional.
The next step is modifying the generated feature code.
ΓòÉΓòÉΓòÉ 8.4. Modifying the Generated Feature Code ΓòÉΓòÉΓòÉ
After you have Visual Builder generate the feature code, review it. Does it do
what you need it to do? If not, modify the code. The OAContractor part needs
the following changes:
Modified code for the getContractor action
Modified code for the putContractor action
Modified code for the parseName action
Added code to set the activeStatus attribute
Added code to set the contractorID attribute
ΓòÉΓòÉΓòÉ 8.4.1. Modifying Code for the getContractor Action ΓòÉΓòÉΓòÉ
This version of our contractor application uses an IProfile-based database to
store information about the contractors. For our OAContractor part to use this
database, we must complete the getContractor and putContractor actions and
modify the activeStatus attribute. The following example shows the default code
generated for the two actions:
OAContractor & OAContractor::getContractor()
{
return *this;
}
OAContractor & OAContractor::putContractor()
{
return *this;
}
To modify default feature code, edit the code files using the syntax text
editor provided by VisualAge C++ or your favorite editor. Code for our
getContractor action follows:
OAContractor & OAContractor::getContractor()
{
// Start data access code
IProfile *p = new IProfile("contrctr.ini");
// Test for missing name information
// Necessary for proper derivation of the contractorID attribute
if ((!iLastName) || (!iFirstName) || (!iMiddleInitial))
{
throw IException("The contractor's name is incomplete. Complete all name fields and try again.");
delete p;
return *this;
}
// Refresh the value of contractor ID
setContractorID();
// Check for this contractor ID in the profile collection
if (!p->containsKeyName("contractorID", iContractorID))
{
throw IException("A record was not found for this contractor.");
delete p;
return *this;
}
// If other data exists for this contractor,
// set the corresponding contractor attributes
if (p->containsKeyName("lastName", iContractorID))
setLastName(p->elementWithKey("lastName", iContractorID));
if (p->containsKeyName("firstName", iContractorID))
setFirstName(p->elementWithKey("firstName", iContractorID));
if (p->containsKeyName("middleInitial", iContractorID))
setMiddleInitial(p->elementWithKey("middleInitial", iContractorID));
if (p->containsKeyName("homeStreet", iContractorID))
setHomeStreet(p->elementWithKey("homeStreet", iContractorID));
if (p->containsKeyName("homeCity", iContractorID))
setHomeCity(p->elementWithKey("homeCity", iContractorID));
if (p->containsKeyName("homeState", iContractorID))
setHomeState(p->elementWithKey("homeState", iContractorID));
if (p->containsKeyName("homeZip", iContractorID))
setHomeZip(p->elementWithKey("homeZip", iContractorID));
if (p->containsKeyName("phoneNumber", iContractorID))
setPhoneNumber(p->elementWithKey("phoneNumber", iContractorID));
if (p->containsKeyName("startDate", iContractorID))
setStartDate(p->elementWithKey("startDate", iContractorID));
if (p->containsKeyName("endDate", iContractorID))
setEndDate(p->elementWithKey("endDate", iContractorID));
if (p->containsKeyName("currentContract", iContractorID))
setCurrentContract(p->elementWithKey("currentContract", iContractorID));
// Call overloaded set member function using string parameter
if (p->containsKeyName("activeStatus", iContractorID))
enableActiveStatus(p->elementWithKey("activeStatus", iContractorID));
delete p;
// End data access code
return *this;
}
The getContractor action checks for one possible error condition. If it occurs,
the action throws an exception. Otherwise, the action retrieves data by
contractor identifier from the contrctr.ini file.
In response to these exceptions, the OAContractorView part shows a message box.
More about the contractor view part appears in Constructing the User Interface.
For information about how to handle exceptions visually, see Passing Exceptions
to Message Boxes.
ΓòÉΓòÉΓòÉ 8.4.2. Modifying Code for the putContractor Action ΓòÉΓòÉΓòÉ
Code the putContractor action as follows:
OAContractor & OAContractor::putContractor()
{
// Start data entry code
IProfile *p = new IProfile("contrctr.ini");
// Test for missing name information
// Necessary for proper derivation of the contractorID attribute
if ((!iLastName) || (!iFirstName) || (!iMiddleInitial))
{
throw IException("The contractor's name is incomplete. Complete all name fields and try again.");
delete p;
return *this;
}
// Refresh the value of contractor ID
setContractorID();
p->addOrReplaceElementWithKey("contractorID", contractorID(), iContractorID));
// If other data about this contractor exists, update it in the database
if (lastName)
p->addOrReplaceElementWithKey("lastName", lastName(), iContractorID));
if (firstName)
p->addOrReplaceElementWithKey("firstName", firstName(), iContractorID));
if (middleInitial)
p->addOrReplaceElementWithKey("middleInitial", middleInitial(), iContractorID));
if (homeStreet)
p->addOrReplaceElementWithKey("homeStreet", homeStreet(), iContractorID));
if (homeCity)
p->addOrReplaceElementWithKey("homeCity", homeCity(), iContractorID));
if (homeState)
p->addOrReplaceElementWithKey("homeState", homeState(), iContractorID));
if (homeZip)
p->addOrReplaceElementWithKey("homeZip", homeZip(), iContractorID));
if (telephoneNumber)
p->addOrReplaceElementWithKey("telephoneNumber", telephoneNumber(), iContractorID));
if (startDate)
p->addOrReplaceElementWithKey("startDate", startDate(), iContractorID));
if (endDate)
p->addOrReplaceElementWithKey("endDate", endDate(), iContractorID));
if (currentContract)
p->addOrReplaceElementWithKey("currentContract", currentContract(), iContractorID));
if (iActiveStatus)
{
p->addOrReplaceElementWithKey("activeStatus", "yes", iContractorID));
}
else
{
p->addOrReplaceElementWithKey("activeStatus", "no", iContractorID));
}
delete p;
// End data entry code
return *this;
}
The putContractor action checks for one possible error condition. If it occurs,
the action throws an exception. Otherwise, the action stores data by contractor
identifier in the contrctr.ini file.
In response to these exceptions, the OAContractorView part shows a message box.
More about this part appears in Constructing Containers and Notebooks. For
information about how to handle exceptions visually, see Passing Exceptions to
Message Boxes.
ΓòÉΓòÉΓòÉ 8.4.3. Modifying Code for the parseName Action ΓòÉΓòÉΓòÉ
The parseName action parses input text from the Request for Contractor
Information window and sets the contractor's firstName, middleInitial, and
lastName attributes. Add code as follows:
OAContractor & OAContractor::parseName(const IString & aName)
{
// aName is supplied by user in OAQueryContractor
// Test for missing information in newly entered name
if (aName.numWords()!= 3)
{
throw IException("The name you entered is incomplete.
Enter first name, middle initial, and last name.");
return *this;
}
// Set name attributes and derive contractorID attribute
setFirstName(aName.word(1));
setMiddleInitial(aName.word(2));
setLastName(aName.word(3));
setContractorID;
// End added code
return *this;
}
ΓòÉΓòÉΓòÉ 8.4.4. Adding Code to Set the activeStatus Attribute ΓòÉΓòÉΓòÉ
You must add a member function to pass string data to the one Boolean
attribute, activeStatus. All data in our simple database is stored as strings,
but the set member function for the activeStatus attribute takes a Boolean as a
parameter. Because only OAContractor's two actions use this member function, it
is not necessary to add this to the part interface for OAContractor. However,
you must add the member function prototype to the contrctr.hpv file.
The following example shows both the default feature code and the added code in
contrctr.cpv:
Boolean OAContractor::isActiveStatus() const
{
return iActiveStatus;
}
OAContractor & OAContractor::enableActiveStatus(const Boolean enable)
{
if (iActiveStatus != enable)
{
iActiveStatus = enable;
notifyObservers(INotificationEvent(OAContractor::activeStatusId, *this));
} // endif
return *this;
}
// Start Boolean string enabler
OAContractor & OAContractor::enableActiveStatus(const IString & status)
{
Boolean tempBoolean = iActiveStatus;
if (status = "yes") iActiveStatus = true;
if (status = "no") iActiveStatus = false;
if (tempBoolean != iActiveStatus)
{
notifyObservers(INotificationEvent(OAContractor::activeStatusId, *this));
}
return *this;
}
// End Boolean string enabler
iActiveStatus is the private data member that corresponds to the activeStatus
attribute.
The notifyObservers function signals that the value of the activeStatus
attribute has changed. For more information about notification, see Building
VisualAge C++ Parts for Fun and Profit.
ΓòÉΓòÉΓòÉ 8.4.5. Adding Code to Set the contractorID Attribute ΓòÉΓòÉΓòÉ
Now, add code to derive the value of the contractorID attribute. The following
example shows the code as modified in contrctr.cpv:
OAContractor & OAContractor::setContractorID()
{
IString tempString = iFirstName+iMiddleInitial+iLastName;
if (iContractorID != tempString)
{
iContractorID = tempString;
notifyObservers(INotificationEvent(OAContractor::contractorIDId, *this));
} // endif
return *this;
}
The next step is adding code that was created outside of Visual Builder.
ΓòÉΓòÉΓòÉ 8.5. Adding Code Created Outside Visual Builder ΓòÉΓòÉΓòÉ
To include previously existing member function code with generated class
declarations, do the following:
1. Change the file extension of .cpp files to .cpv.
2. Change the file extension of .hpp files to .hpv.
3. Change the file extension of any .rc files to .rcv.
4. Add these files to the Class Editor for the appropriate part.
If you prefer not to use Visual Builder to develop the code for a nonvisual
part but you want to be able to use it in the Composition Editor, you can do
the following:
Write the code.
Compile it into a .lib file.
Define the part interface using a part information file.
Import the part information file.
For more information on part information files, see Defining the Part
Interface Using Part Information Files.
ΓòÉΓòÉΓòÉ 9. Learning to Use Parts ΓòÉΓòÉΓòÉ
Visual construction overview
Working with parts in the Visual Builder window
Working with parts on the free-form surface
Undoing and redoing changes in the Composition Editor
Constructing a GUI: the OASearch application
ΓòÉΓòÉΓòÉ 9.1. Visual Construction Overview ΓòÉΓòÉΓòÉ
This chapter provides general information on using parts, and then shows you
how some of this information can be applied to an actual application-the
OASearch sample application that was introduced in Designing Parts for the
OASearch Application.
With the Composition Editor you can visually construct an application by
placing parts on the free-form surface and making connections between them.
With connections, you can construct the interactions between the parts of the
application. For information about connecting parts to each other, see Learning
to Use Connections.
In Visual Builder you use the following kinds of parts:
Visual parts, such as IPushButton*, IListBox*, and IEntryField*, to
construct the graphical user interface (GUI) of the application.
Nonvisual parts, such as the sample ICustomer and ICompany parts, to
represent the data or objects manipulated by the application.
Class interface parts, such as IDate* and ITime*, to represent data or
objects, also. The difference between nonvisual parts and class interface
parts is that nonvisual parts can notify other parts when an event occurs
or an attribute value changes; class interface parts, however, do not
have this notification capability.
ΓòÉΓòÉΓòÉ 9.2. Working with Parts in the Visual Builder Window ΓòÉΓòÉΓòÉ
The topics in this section describe how to perform various actions on part
classes from the Visual Builder window.
The following topics are covered:
Displaying part names
Selecting all parts
Deselecting all parts
Importing part information
Exporting part information
Creating a new part
Opening parts
Copying parts from one .vbb file to another
Moving parts to a different .vbb file
Deleting parts from a .vbb file
Renaming parts in .vbb files
Personal notes:
ΓòÉΓòÉΓòÉ 9.2.1. Displaying Part Names ΓòÉΓòÉΓòÉ
To display the names of the parts in a .vbb file, in the Loaded Files list box
in the Visual Builder window select the .vbb file whose parts you want to see.
The names of the parts contained in the .vbb file that you selected are
displayed in the Visual Builder window. Visual parts are displayed in the
Visual Parts list box; nonvisual parts and class interface parts are displayed
in the Nonvisual Parts list box.
Once part names are displayed, you can perform actions on them, such as opening
or deleting them. If you need information about loading .vbb files, see Loading
.vbb Files.
The following figure shows the Visual Builder window with the names of the
parts in the vbbase.vbb file displayed:
ΓòÉΓòÉΓòÉ 9.2.2. Selecting All Parts ΓòÉΓòÉΓòÉ
To select all of the parts in the selected .vbb files, select EditSelect all
parts.
At this point, you can review the list to see if you want to deselect any of
the parts. You can do so by pressing the Ctrl key and clicking on the part name
with mouse button 1.
ΓòÉΓòÉΓòÉ 9.2.3. Deselecting All Parts ΓòÉΓòÉΓòÉ
To deselect all of the parts in the selected .vbb files, select EditDeselect
all parts.
ΓòÉΓòÉΓòÉ 9.2.4. Importing Part Information ΓòÉΓòÉΓòÉ
Using any text editor, you can create files called part information files,
which are used to import existing C++ classes into Visual Builder as parts.
Part information files are normally recognizable by their .vbe. extension.
The import part information function loads part information files so that you
can use the parts specified in those files in Visual Builder.
To import part information, do the following:
1. Select FileImport part information.
The following window is displayed:
2. Select the part information file that you want to import.
3. Select the OK push button.
The part information in the part information file is imported. Any visual
parts that the part information file contains are displayed in the Visual
Parts list box, and any nonvisual parts and class interface parts it
contains are displayed in the Nonvisual Parts list box. In addition, one
or more .vbb files may be created.
For more information about using and creating part information files, see the
following:
Defining the Part Interface Using Part Information Files (.vbb)
Building VisualAge C++ Parts for Fun and Profit
ΓòÉΓòÉΓòÉ 9.2.5. Exporting Part Information ΓòÉΓòÉΓòÉ
Just as you can import part information from an existing part information file,
you can also export part information for any Visual Builder part into a .vbe
file.
The Export interface function creates a part information file that you can, for
example, use to share nonvisual and class interface parts with other
programmers. Part information files contain usage information that programmers
who do not have access to the part (.vbb) file can use.
To export part information, do the following:
1. Select the part or parts whose information you want to export in either
the Visual Parts list box, the Nonvisual Parts list box, or both.
2. Select PartExport interface.
The following window is displayed:
3. Type the name of the .vbe file in which you want the part information to
be stored in the Open filename field.
If you do not enter a file name, Visual Builder uses exported.vbe as the
default file name.
4. Select the OK push button.
The part information maintained by Visual Builder is exported to the file
name you specified in the Open filename field.
For more information about using and creating part information files, see the
following:
Defining the Part Interface Using Part Information Files (.vbb)
Building VisualAge C++ Parts for Fun and Profit
ΓòÉΓòÉΓòÉ 9.2.6. Creating a New Part ΓòÉΓòÉΓòÉ
This section provides only the basic steps for creating a new part. For a
description of how to create a part that others can reuse, see Creating Parts
for Reuse.
To create a new part, do the following:
1. Select PartNew.
A Part - New window is displayed, as follows:
2. Enter the name that you want to give to your part in the Class name
field.
3. Enter a description of your part in the Description field.
Visual Builder uses the description that you enter here in the following
ways:
If you add the part that you create to the parts palette, Visual
Builder displays the part's description in the information area at
the bottom of the Composition Editor when the part is selected.
If you export the information about the part to a .vbe file, the
description is included with the other information about the part.
4. Enter the name of the .vbb file in which you want Visual Builder to store
the part in the File name field.
If the file does not already exist, Visual Builder creates it for you. If
you leave this field blank, Visual Builder creates a .vbb file as
follows:
If you are using the High Performance File System (HPFS) and do not
select OptionsDefault to FAT file names, the name of the .vbb file
is the same as the name of your part.
If you are using the File Allocation Table (FAT) file system and
have selected OptionsDefault to FAT file names, Visual Builder
creates a .vbb file whose name has no more than eight characters.
Without this selection, Visual Builder attempts to create a .vbb
file whose name is the same as the name of your part, which causes
an error if your part name has more than eight characters.
Note: If you are using the FAT file system, we recommend that you
always use part names and file names that have eight
characters or less, even if you have selected the Default to
FAT file names option. Otherwise, Visual Builder might use a
file name for a .vbb file that is the same as one that
already exists and write over the existing file.
5. Select the type of part that you want to create in the Part type field.
You can select one of the following:
Visual part
Nonvisual part
Class interface
6. Either keep the default class name provided by Visual Builder in the Base
class field, change it, or delete it.
Note the following:
A nonvisual part must have the IStandardNotifier class in its
inheritance so it can exhibit the behavior required for all parts-a
part interface (attributes, events, and actions). It must inherit
this behavior from IStandardNotifier. Therefore, you cannot leave
this field blank when creating a nonvisual part. The default base
class for a nonvisual part is IStandardNotifier.
A visual part must have the IWindow class in its inheritance so it
can inherit the visual behavior common to all windows, as well as
part interface behavior, which IWindow inherits from
IStandardNotifier. Therefore, you cannot leave this field blank when
creating a visual part. The default base class for a visual part is
IFrameWindow, which inherits from IWindow.
No inheritance is required for a class interface part. Therefore,
you can leave the Base class field blank when creating a class
interface part. The default base class for a class interface part is
IVBase*.
7. Select Open.
One of the following occurs:
If you are creating a visual part, the Composition Editor is
displayed.
If you are creating a nonvisual part or a class interface part, the
Part Interface Editor is displayed.
8. Use the displayed editor to create your part.
ΓòÉΓòÉΓòÉ 9.2.7. Opening Parts ΓòÉΓòÉΓòÉ
Use PartOpen to open parts that are already created. You must load the .vbb
file that contains a part before you can open the part.
Visual Builder uses the question mark icon, , to represent the unloaded parts
on the free-form surface. If you open a part that contains other parts and the
.vbb files that contain the other parts are not loaded, Visual Builder displays
this icon.
The question mark folder icon indicates that most of the information about the
unloaded part is not available to Visual Builder. You can select connections
between unloaded parts and other parts to see which features are connected, but
the features are not available in the unloaded part's connection menu.
You should not make any changes to an unloaded part or generate any code when a
part is not loaded.
If you open a part and see a question mark folder icon, do the following:
1. Close the part you just opened.
2. Load the .vbb file that contains the unloaded part.
3. Reopen the part you previously opened.
The question mark folder icon is replaced by the part's icon.
The following instructions tell you how to open one part at a time or multiple
parts simultaneously.
Opening one part
To open one part, do the following:
1. Find the name of the part that you want to open by scrolling through the
appropriate list box in the Visual Builder window.
Note: If the list boxes in the Visual Builder window are empty or if you
cannot find the part, the .vbb file that contains the part you
want to open is not selected or not loaded. See Loading .vbb Files
if you need help loading .vbb files.
The Visual Builder window with parts loaded from the vbbase.vbb file is
shown in the following figure:
2. Select the part you want to open.
3. Select Part on the menu bar.
4. Select Open in the pull-down menu.
One of the following occurs:
If you are opening a visual part, Visual Builder displays the
Composition Editor.
If you are opening a nonvisual part, Visual Builder displays the
Part Interface Editor.
A quicker way to open an existing part is to double-click on the
part name within the Visual Parts or Nonvisual Parts list box.
Opening multiple parts
To open multiple parts, do the following:
1. Find the name of the first part that you want to open by scrolling
through the Nonvisual Parts and Visual Parts list boxes shown in the
Visual Builder window.
Note: If the list boxes in the Visual Builder window are empty, see
Loading .vbb Files if you need help loading .vbb files.
The Visual Builder window with parts loaded from the vbbase.vbb file is
shown in the following figure:
2. Select the first part you want to open.
3. Find the next part you want to open and press the Ctrl key while
selecting that part.
4. Continue finding and selecting parts in this manner, pressing the Ctrl
key while selecting each part, until you have selected all the parts you
want to open.
5. Select Part on the menu bar.
6. Select Open in the pull-down menu.
Visual Builder displays a separate window for each part that you
selected. The window displayed is the Composition Editor for visual parts
or the Part Interface Editor for nonvisual parts.
ΓòÉΓòÉΓòÉ 9.2.8. Copying Parts from One .vbb File to Another ΓòÉΓòÉΓòÉ
To copy a part, do the following:
1. Select the part that you want to copy in the Visual Parts or Nonvisual
Parts list box.
If you select more than one part or if you do not select a part, the Copy
function is not available.
2. Select PartCopy.
The following window is displayed:
The Source part name field shows the name of the part that you selected
to copy.
3. In the Target part name field, enter the name you want the part to have
when you copy it.
4. In the Target file name field, enter the name of the .vbb file to which
you want to copy the part. If you leave this field blank, the part's
current file name is used.
5. Select the Copy push button.
The part is copied under the new name and stored in the designated .vbb
file.
ΓòÉΓòÉΓòÉ 9.2.9. Moving Parts to a Different .vbb File ΓòÉΓòÉΓòÉ
Here is what happens to the .vbb file into which the part or parts are being
moved:
If this .vbb file does not exist, Visual Builder creates and loads it for
you.
If this .vbb file already exists and is loaded, the part or parts are
moved into it.
If this .vbb file already exists but is not loaded, Visual Builder
displays a message to warn you that the unloaded .vbb file will be
overwritten by the part or parts that you are moving into it.
To move one or more parts from one .vbb file to another, do the following:
1. Select the part or parts that you want to move.
If you do not select at least one part, the Move function is not
available.
2. Select PartMove.
3. Use the following instructions for moving one part or multiple parts:
Moving one part
If you selected one part, the following window is displayed:
The Part name field of this window shows the name of the part that you
selected to move. The File name field displays the complete path of the
.vbb file that contains the part you want to move.
Do the following:
a. In the New file name field, enter the path and name of the .vbb file
to which you want to move the part.
b. Select the Move push button.
The part is moved to the .vbb file specified in the New file name
field.
Moving multiple parts
If you selected more than one part, the following window is displayed:
The text in the window specifies the names of the parts you selected.
Do the following:
a. In the entry field, enter the name of the .vbb file to which you
want to move the parts. If the .vbb file is not in your current
directory, specify the complete path for the .vbb file.
b. Select the OK push button.
The parts are moved to the .vbb file specified in the entry field.
An alternate method of moving a part is to change the name of the
.vbb file specified in the Class Editor. For more information, see
Using the .vbb File Specification Field
ΓòÉΓòÉΓòÉ 9.2.10. Deleting Parts from a .vbb File ΓòÉΓòÉΓòÉ
To delete a part, do the following:
1. Select the part or parts that you want to delete in the Visual Parts list
box, Nonvisual Parts list box, or both.
If you do not select at least one part, the Delete function is not
available.
2. Select PartDelete.
The following window is displayed:
Deselect any parts that you do not want to delete. Once you delete a part
from a .vbb file, you cannot recover it unless you have another copy
stored in another .vbb file.
3. Select the Delete push button.
The selected parts are deleted.
ΓòÉΓòÉΓòÉ 9.2.11. Renaming Parts in .vbb Files ΓòÉΓòÉΓòÉ
The PartRename menu choice allows you to change the name that a part is stored
under in a .vbb file.
Use care when renaming parts because the name changes only in the
.vbb file in which the part is stored. The name of the part does not
change in any other part in which this part is embedded, that is,
used as a subpart. Therefore, the next time you open the part in
which you embedded the renamed part, Visual Builder will not be able
to find the renamed part.
To rename a part in a .vbb file, do the following:
1. Select the part that you want to rename in the Visual Parts or Nonvisual
Parts list box.
If you select more than one part or if you do not select a part, the
Rename function is not available.
2. Select PartRename.
The following window is displayed:
The Part name field shows the name of the part that you selected to
rename.
3. In the New part name field, enter the new name that you want to give the
part.
4. Select the Rename push button.
The part is renamed under the new name.
ΓòÉΓòÉΓòÉ 9.3. Working with Parts on the Free-form Surface ΓòÉΓòÉΓòÉ
Placing parts on the free-form surface
Selecting and deselecting parts
Manipulating parts, which includes:
- Displaying pop-up menus
- Copying parts
- Deleting parts
- Editing text strings
- Renaming parts
Arranging parts, which includes:
- Moving parts
- Positioning parts on the grid
- Sizing parts
- Matching part sizes
- Aligning parts
- Spacing parts within Composer parts
- Spacing parts within a bounding box
Changing settings for a part
Tearing off an attribute
Personal notes:
ΓòÉΓòÉΓòÉ 9.3.1. Placing Parts on the Free-form Surface ΓòÉΓòÉΓòÉ
In the Composition Editor, you place visual, nonvisual, and class interface
parts on the free-form surface. This section explains how to place parts there
that appear on the parts palette, as well as parts that do not appear on the
parts palette.
Placing a part that appears on the parts palette
1. From the left column of the parts palette, select the appropriate
category. Then, from the right column, select the part you want to add.
When the mouse pointer is moved over a place where the part can be
placed, it changes to a crosshair, indicating that it is loaded with the
part.
2. Move the mouse pointer to where you want to add the part.
3. Click mouse button 1.
If you hold down mouse button 1 instead of clicking it, an outline of the
part is displayed under the pointer to help you position the part. After
the part is in position, release mouse button 1.
See Touring the Parts Palette and Touring the Free-form Surface for more
information.
To unload the mouse pointer at any time, do either of the following:
Select , the Selection tool, on the tool bar.
Select ToolsSelection Tool on the menu bar.
To add several copies of the same part, select Sticky on the parts
palette. When Sticky is selected, the mouse pointer remains loaded
with the part you last selected. When Sticky is not selected, the
mouse pointer becomes unloaded after you add a part.
Placing a part that is not on the parts palette
You can place on the free-form surface any part whose .vbb file is loaded by
doing the following:
1. Select Add part from the Options pull-down menu.
The Add Part window appears, as shown in the following figure:
2. Type the part's class name in the Part class field.
This is the class name that was specified when the part was created. When
you begin typing, you replace the highlighted prompt with the name of the
part you want to add.
The asterisk at the end of the name is a reminder that you are actually
entering a pointer to the part. When you enter a valid class name for the
part without deleting the asterisk, Visual Builder automatically selects
the Part radio button. You can change this by selecting the Variable
radio button if you want to place a pointer to a variable on the
free-form surface. The following figure shows how you could place a
notebook part on the free-form surface using the Add Part window:
If you delete the asterisk, the Part radio button is not available. This
means that you can only place a variable on the free-form surface; Visual
Builder automatically selects the Variable radio button indicating that
you will be adding a variable whose type is the class name you entered in
the Part class field, as shown in the following figure:
Note: You cannot add abstract parts or template parts using the Add Part
window. For example, IButton* is the abstract part that
IPushButton* inherits from. You can add IPushButton*, but not
IButton*.
Similarly, you cannot add an object factory part or a variable part using
the Add Part window because they are templates. You must add them by
selecting them on the parts palette.
3. Type a name for the part in the Name field.
This name will appear in the information area at the bottom of the
Composition Editor when you select the part after it is placed; it is
also used for the part when you generate your part code.
The Name field is optional. If you leave it blank, the part's class name
is used.
4. Select the Add push button to add the part.
The Add Part window disappears and the mouse pointer turns into the same
crosshairs used for placing a part on the free-form surface.
Note: If you did not enter the name of a part that is known to Visual
Builder in the Part class field, the Add push button is not
enabled.
5. Move the crosshairs to the place where you want to add the part and click
mouse button 1.
ΓòÉΓòÉΓòÉ 9.3.2. Guidelines for Placing Parts on the Free-form Surface ΓòÉΓòÉΓòÉ
Following are guidelines for placing parts on the free-form surface:
Avoid overlaying parts
You can overlay visual parts. Generally speaking, however, it is not good
interface design for one part to overlay another part, such as one push
button either completely or partially covering another push button. Be
aware that completely overlaying a part can cause focus problems, meaning
that runtime users may be able to see, but not select, the part.
Partially overlaying a part can cause problems, too, because the runtime
users might not be able to see where the overlaying occurs. When they try
to select the part that is partially overlaid, they may be lucky and
select the right spot, or they may select the part that is overlaying the
part they are trying to select. If you overlay parts, be sure to do it in
a way in which the user can understand why the parts are overlaid and how
to select them.
You cannot overlay, or cover up, nonvisual parts. You can overlay visual
parts, but you should avoid doing this if possible unless you are placing
parts on top of a part in the Composers category (see the next
guideline).
Place other parts on top of parts in the Composers category
Parts included in the Composers category have a special behavior; these
parts can contain any other visual parts that are placed on top of them.
The parts that the Composers part contains automatically become subparts
of the Composers part. For example, if you place an entry field, a list
box, and two push buttons in a frame window, the frame window contains
the other parts and they, in turn, become the frame window's subparts.
The following table lists each of the Visual Builder categories and
specifies how you can use the parts in each category.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéCategory ΓöéUse Parts to Contain ΓöéUse Parts as Subparts? Γöé
Γöé ΓöéOther Parts? Γöé Γöé
ΓöéButtons ΓöéNo ΓöéYes Γöé
ΓöéData entry ΓöéNo ΓöéYes Γöé
ΓöéLists ΓöéNo ΓöéYes Γöé
ΓöéFrame Extensions ΓöéNo ΓöéNo Γöé
ΓöéSliders ΓöéNo ΓöéYes Γöé
ΓöéComposers ΓöéYes ΓöéYes Γöé
ΓöéModels ΓöéNo ΓöéNo Γöé
ΓöéOther ΓöéNo ΓöéNo Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Use supplementary composite parts as subparts
Suppose you create a visual composite part that consists of a canvas on
which you have placed other visual parts, such as radio buttons and check
boxes, with each radio button and check box connected to a variable, as
shown in the following figure:
Assume this part is not your main composite part but is instead a
supplementary part that you want to use in your application's user
interface. When you place this part in your main composite part, such as
in a frame window, as shown in the following figure, you place it and
work with it as one part, not as a canvas and separate radio buttons and
check boxes. The frame window contains the entire supplementary part,
which becomes a subpart of the frame window.
One of the first things you have probably noticed is that the connections
for a supplementary composite part are not displayed when that part is
added to another part. The connections and variables are still there; you
just cannot see them because you cannot edit them directly from the
Composition Editor window that contains the main composite part. Also,
you cannot select the individual radio buttons, check boxes, or their
connections in the supplementary part that you placed in your main part.
To change the connections or the default text on the radio buttons and
check boxes, or to do anything else to alter this part, you must edit the
part indirectly, as described in Editing Parts Placed on the Free-form
Surface.
ΓòÉΓòÉΓòÉ 9.3.3. Selecting and Deselecting Parts ΓòÉΓòÉΓòÉ
Before you can perform an action on a part that you have placed on the
free-form surface, such as sizing it, you must first select the part. The name
of the part currently selected is displayed in the information area at the
bottom of the Composition Editor. If more than one part is selected, then
*Multiple selection* is displayed.
You cannot select parts and connections together. They are mutually exclusive.
However, if you delete a part that is connected to other parts, Visual Builder
deletes the connections in addition to the part.
When a part is selected, small boxes, called selection handles, are displayed
on its corners. If more than one part is selected, the one you selected last
has solid selection handles, indicating that it is the anchor part. The other
selected parts have hollow selection handles as shown in the following figure:
Some parts are not sizable and, therefore, do not have any selection handles.
These parts have their background reverse colored. Parts with this behavior
include variables, menus, and tear-off attributes, among others.
The following sections describe how to select and deselect a single part and
multiple parts.
Selecting a single part
To select a part that you have placed on the free-form surface, click on the
part with mouse button 1. If other parts are already selected, they are
deselected automatically.
Selecting multiple parts
Selecting multiple parts enables you to perform the same operation on several
parts at once. To select multiple parts, do one of the following:
Hold down the Ctrl key and click mouse button 1 on each additional part
you want to select.
Hold down mouse button 1 instead of clicking it; then move the mouse
pointer over each additional part you want to select. After you select
the parts, release mouse button 1.
Note: Depending on the operation you want to perform, remember to consider
which part you want to be the anchor part because that is the part you
want to select last. For example, if you select two parts because you
want to match the width of one part to the width of the other, the part
you select last is the anchor part, the part whose width is used for
the operation.
Deselecting parts
To deselect a part after you have selected it, do the following:
1. Hold down the Ctrl key.
2. Click on the selected part with mouse button 1.
To deselect multiple parts, do the following:
1. Hold down the Ctrl key.
2. Click on a selected part with mouse button 1.
3. Without releasing either the Ctrl key or mouse button 1, move the mouse
pointer to another selected part.
4. Repeat the previous step until all parts that you want to deselect have
been deselected.
ΓòÉΓòÉΓòÉ 9.3.4. Manipulating Parts ΓòÉΓòÉΓòÉ
Once a part is added to the free-form surface, you can manipulate it in a
number of different ways. The following sections explain each of those ways.
Displaying pop-up menus
Copying parts
Deleting parts
Editing text strings
Renaming parts on the free-form surface
Personal notes:
ΓòÉΓòÉΓòÉ 9.3.4.1. Displaying Pop-up Menus ΓòÉΓòÉΓòÉ
To display the pop-up menu of a part, click on the part with mouse button 2.
The pop-up menu displays the operations you can perform on that part.
A part does not have to be selected for you to display its pop-up menu. The
pop-up menu that is displayed is for the part the mouse pointer is over when
mouse button 2 is clicked, even if another part is selected.
ΓòÉΓòÉΓòÉ 9.3.4.2. Copying Parts ΓòÉΓòÉΓòÉ
To copy parts by dragging them, do the following:
1. Select all the parts you want to copy.
If you only want to copy one part, you do not have to select it.
2. Move the mouse pointer over the part you want to copy or one of the
selected parts.
3. Hold down the Ctrl key and mouse button 2.
4. Drag a copy of the part or parts by moving the mouse pointer to a new
position.
An outline of the part or parts is displayed to help you with
positioning. When you are copying multiple parts, the outlines of each
part move together as a group.
5. Release the Ctrl key and mouse button 2 when the part or parts are where
you want them to be.
A copy of the part or parts appears where you positioned the outline or
outlines.
Copying parts using the clipboard
To copy parts by using the clipboard, do the following:
1. Select all the parts you want to copy.
2. From the Edit pull-down menu, select Copy.
A copy of each selected part is placed on the clipboard.
3. Select Paste from the Edit pull-down menu when you are ready to use the
parts.
The mouse pointer turns to crosshairs to show that it is loaded with the
copied parts.
4. Position the mouse pointer where you want the parts to be copied.
5. Click mouse button 1.
Copies of the parts are pasted at the position of the mouse pointer.
Parts that you copy remain on the clipboard until you copy something
else. Therefore, you can continue to paste copies of those parts by
selecting Paste, positioning the mouse pointer, and clicking mouse
button 1.
If you select Paste and then decide against pasting the parts, you
can unload the mouse pointer by either selecting the Selection Tool
on the tool bar or by selecting ToolsSelection Tool on the menu
bar.
ΓòÉΓòÉΓòÉ 9.3.4.3. Deleting Parts ΓòÉΓòÉΓòÉ
To delete one or more parts, do the following:
1. Select all of the parts you want to delete.
If you are deleting just one part, you do not have to select it.
2. Position the mouse pointer over the part you want to delete or one of the
selected parts.
3. Click mouse button 2.
4. From the part pop-up menu, select Delete.
The part or parts are deleted.
Any connections between the part that you are deleting and other
parts are also deleted. Visual Builder displays a message to alert
you to this. However, the EditUndo function also restores any
connections that were removed when you deleted the part.
ΓòÉΓòÉΓòÉ 9.3.4.4. Editing Text Strings ΓòÉΓòÉΓòÉ
Some visual parts, such as push buttons and menus, have text strings. To
directly edit a part's text string, do the following:
1. Hold down the Alt key.
2. Click mouse button 1 on the text string.
3. Edit the text string.
4. When you have finished, do either of the following:
Click mouse button 1 anywhere outside of the text string.
Press Shift+Enter.
You can also use this direct editing technique to edit the names of
nonvisual parts. The name of a nonvisual part is displayed directly
below its icon.
ΓòÉΓòÉΓòÉ 9.3.4.5. Renaming Parts On the Free-form Surface ΓòÉΓòÉΓòÉ
When you use parts in the Composition Editor, Visual Builder gives those parts
a name based on the names given to the parts on the parts palette or the names
you specify when you place parts on the free-form surface. For example, the
first push button part that you use is named PushButton1. When you select this
part, the information area at the bottom of the Composition Editor shows the
message "PushButton1 selected." The second push button you use is named
PushButton2, the third is named PushButton3, and so forth. These default names
are assigned to help Visual Builder distinguish one part from another, as well
as the connections between parts, when you generate the code to build your
application.
If you want to give parts names that are more descriptive or meaningful to your
application, you can do so as follows:
1. Move the mouse pointer over the part whose name you want to change.
2. Click mouse button 2 to display the pop-up menu for the part.
3. Select Change Name.
A Name Change Request window is displayed. The following figure shows a
Name Change Request window for a push button part.
4. Type a new name in the entry field.
5. Select OK.
Visual Builder changes the name of the part to the name that you typed in
the entry field.
You can also change a part's name by opening the part's settings notebook and
changing the name in the Subpart name field.
ΓòÉΓòÉΓòÉ 9.3.5. Arranging Parts ΓòÉΓòÉΓòÉ
You can arrange parts on the free-form surface in a number of different ways.
The following sections explain each of those ways.
Moving parts
Positioning parts on the grid
Specifying grid spacing
Showing and hiding the grid
Sizing parts
Matching part sizes
Aligning parts
Spacing subparts within Composers parts
Personal notes:
ΓòÉΓòÉΓòÉ 9.3.5.1. Moving Parts ΓòÉΓòÉΓòÉ
To move a part, move the mouse pointer over the part, hold down mouse button 2,
and move the mouse pointer to drag the part to the new position.
You can move several parts at once by first selecting all the parts
you want to move and then dragging one of the parts as described.
All of the selected parts will move together, maintaining their
position relative to each other.
ΓòÉΓòÉΓòÉ 9.3.5.2. Positioning Parts on the Grid ΓòÉΓòÉΓòÉ
The free-form surface has a grid that you can use to position parts. In
addition, parts that can contain other parts (any Composers part, such as a
frame window) have a grid associated with them. You can use this grid to align
and evenly space subparts that Composers parts contain.
To position the top-left corner of parts to the nearest grid coordinate, do the
following:
1. Select all the parts you want to position to the grid.
Note: If the parts you select are subparts, they are positioned to the
grid set up inside the Composers part, not the grid for the
free-form surface.
2. Select , the Snap To Grid tool.
You can automatically position a part to the nearest grid coordinate
when it is added to the free-form surface or a Composers part by
selecting Snap On Drop from the Options pull-down menu.
ΓòÉΓòÉΓòÉ 9.3.5.3. Specifying Grid Spacing ΓòÉΓòÉΓòÉ
To specify the grid spacing, do the following:
1. From the pop-up menu of a Composers part or the free-form surface, select
Set Grid Spacing.
2. Specify the horizontal and vertical distance between the lines of the
grid in pixels.
ΓòÉΓòÉΓòÉ 9.3.5.4. Showing and Hiding the Grid ΓòÉΓòÉΓòÉ
To toggle between showing and hiding the grid for the free-form surface, do one
of the following:
If no parts are selected, you can select , the Toggle Grid tool to toggle
the grid for the free-form surface.
If a Composers part is selected, selecting the Toggle Grid tool toggles
the grid for the Composers part instead of the free-form surface.
Toggling between showing and hiding the grid for a Composers part
To toggle between showing and hiding the grid for a Composers part, do one of
the following:
Select the Composers part and the select , the Toggle Grid tool.
From the Composers part's pop-up menu, select Toggle Grid.
ΓòÉΓòÉΓòÉ 9.3.5.5. Sizing Parts ΓòÉΓòÉΓòÉ
To change the size of a part, select it and use mouse button 1 to drag one of
the selection handles to the new position. An outline of the part is displayed
under the mouse pointer to show you the new size of the part.
You can size several parts at once by first selecting all the parts
you want to size.
To size a part in only one direction, press and hold the Shift key
while using mouse button 1 to size the part. Holding down the Shift
key prevents one dimension of the part from changing while you
resize the other dimension. For example, to change the width of a
part but prevent its height from changing, hold down the Shift key
while changing the width.
You can also size a part to the grid coordinates by selecting Snap
On Size from the Options pull-down menu.
ΓòÉΓòÉΓòÉ 9.3.5.6. Matching Part Sizes ΓòÉΓòÉΓòÉ
To size parts to the same width or height of another part, do the following:
1. Select all the parts you want to size, making sure the last part you
select is the part whose size you want the others to match.
2. Select one of the following sizing tools from the tool bar:
Match Width Match Height
The size of all the parts you selected, with the exception of the last
part, changes to match the size of the last part selected.
ΓòÉΓòÉΓòÉ 9.3.5.7. Aligning Parts ΓòÉΓòÉΓòÉ
To align parts to the same position as another part, do the following:
1. Select all the parts you want to align, and then select the part you want
the others to be aligned with.
2. Select one of the following alignment tools from the tool bar:
Align Left Align Top
Align Center Align Middle
Align Right Align Bottom
ΓòÉΓòÉΓòÉ 9.3.5.8. Spacing Subparts Within Composers Parts ΓòÉΓòÉΓòÉ
To evenly space subparts within their Composers part, do the following:
1. Select all the parts you want to evenly space.
2. Select one the following spacing tools from the tool bar:
Distribute Horizontally
Distribute Vertically
ΓòÉΓòÉΓòÉ 9.3.5.9. Spacing Parts Within a Bounding Box ΓòÉΓòÉΓòÉ
To evenly space parts within the unseen bounding box that contains the selected
parts, do the following:
1. Select all the parts you want to evenly space. You must select a minimum
of three parts.
2. From the pop-up menu of one of the selected parts, select
LayoutDistribute, and then one of the following:
Horizontally In Bounding Box Evenly distributes the selected parts within
the region bounded by the leftmost edge and rightmost edge of the
selected parts.
Vertically In Bounding Box Evenly distributes the selected parts within
the region bounded by the topmost edge and bottommost edge of the
selected parts.
For more information on tool bar tools, see Tool Bar.
ΓòÉΓòÉΓòÉ 9.3.6. Changing Settings for a Part ΓòÉΓòÉΓòÉ
The settings notebook of a part provides a way to display and set attributes
and options for the part.
Opening the settings notebook for one part
To open the settings notebook for a part, move the mouse pointer over the part
and do one of the following:
Double-click mouse button 1.
Click mouse button 2 and select Open settings from the part's pop-up
menu.
Opening settings notebooks for multiple parts
You can open the settings notebooks for multiple parts by doing the following:
1. Select the parts whose settings you want to change.
2. Move the mouse pointer over one of the selected parts.
3. Click mouse button 2.
4. Select Open settings from the pop-up menu.
Visual Builder opens a settings notebook for each of the selected parts.
Navigating through a settings notebook
You can navigate through the notebook pages in the following ways:
To turn the pages of a notebook, use the small left- and right-arrow push
buttons at the bottom right corner of each page.
To move to a different settings category, select one of the tabs to the
right of the pages.
Note: When a category has more than one page, the page number and total
number of pages within the category are displayed at the bottom of
the page.
If all the category tabs cannot fit below the pages of the notebook,
small double left- and right-arrow push buttons are displayed to the left
and right of the category tabs. Use these buttons to move through the
available category tabs.
About the settings pages
The following list contains a description of each of the pages a settings
notebook may contain:
General
A page for setting the name of the part, any static text that may appear on
the part, and other part-specific settings. For example, the General page
for an IMenuItem* part contains a group box for setting the keyboard
accelerator for the menu item. Refer to the Visual Builder Parts Reference
for descriptions of specific settings for parts.
Control
A page that allows you to specify information for the part in its role as an
OS/2 control, such as fly over text, a window ID, and whether the part is
available for the user to select.
Styles
A page that provides style settings from the IBM Open Class Library. The
style settings generally correspond to those of the class on which the part
is based. Refer to the IBM Open Class Library Reference for descriptions of
the style settings.
Selecting the defaultStyle check box means you want Visual Builder to use
the default style provided for the class by the IBM Open Class Library. You
can select this check box and then modify the default settings by selecting
the On and Off radio buttons on the page beside each style setting. Doing
this means you want Visual Builder to use the default style except for any
exceptions that you have made by turning style settings on or off.
The Default column shows which style settings are the defaults as specified
for the class in the IBM Open Class Library. Visual Builder has not turned
these style bits on or off. They are set to whatever the default settings
are supposed to be.
If you deselect the defaultStyle check box and also turn off
one or more of the required settings, you will get errors
when you generate and compile your code. However, selecting
this check box ensures that no required settings will be
omitted. Therefore, we recommend that you keep the
defaultStyle check box selected so that you always have the
required settings.
Selecting one style setting does not cause another to be
automatically deselected. For example, selecting minor tabs
for a notebook page does not cause major tabs to be
deselected. In this case, the major tab style setting
overrides the minor tab setting. Be sure to deselect the
styles that you do not want to use.
Handlers
A page that allows you to list handlers that you want to attach to this
part. You can use handlers instead of event connections, such as
event-to-action connections. List the handlers in the order in which they
should be called.
Adding a handler
To add a handler, do the following:
1. Enter the name of the handler class in the Handler Name field, along
with the list of parameters that you want to send to the handler's
constructor. If you use any part names as parameters, be sure to use
the default name that Visual Builder has assigned unless you have
changed the name. Also, put a lower case "i" before those parameters
because Visual Builder prefixes the part name with an "i" when it
generates the code files. For example, if you are using the first entry
field that you placed in a frame window as a parameter and have not
changed the default name that Visual Builder assigns, the parameter
name would be iEntryField1.
2. If the Handler List list box contains other handlers, select the
handler that you want your new handler to either precede or follow.
3. Select either the Add after or Add before push button.
If you did not import the handler class from a .vbe file, Visual
Builder displays a message saying that the name you entered is not a
valid part and asks if you want to continue.
4. Select the Yes push button.
The message disappears and the handler is added either after or before
the handler that is selected in the Handler List list box, depending on
which push button you select.
5. Select the OK push button to save the new handler in the handler list
and close the settings notebook.
We recommend that you put your handler class declaration and
code in separate user .hpv and .cpv files rather than
modifying the files that Visual Builder generates. This way,
if you need to regenerate the files, you do not have to
recreate your handler code.
Be sure to include the names of the files that contain the
handler code in the User .hpv file and User .cpv file fields
in the Class Editor.
For information about implementing handlers, refer to the IBM
Open Class Library User's Guide and the IBM Open Class
Library Reference.
Moving a handler
To move a handler to a different position in the list, do the following:
1. Select the handler that you want to move.
2. Select the Move push button.
3. In the dialog that is displayed, select the handler that is to precede
or follow the handler being moved.
4. Select the Move after push button to move the handler after the
selected handler, or select the Move before push button to move the
handler before the selected handler.
The dialog disappears and the handler is moved.
Removing a handler
To remove a handler from the list, do the following:
1. Select the handler you want to remove from the list.
2. Select the Remove push button.
The selected handler is removed from the list.
Color
A page that allows you to change the color of the part.
Changing the color
To change the color, do the following:
1. In the Color Area group box, select the area, such as foreground or
background, whose color you want to change.
2. Do one of the following:
If you want to specify red-green-blue values, select the RGB check
box and specify values in the fields in the RGB Values group box.
If you want to select a color by its name, deselect the RGB check
box and select a color from the Colors drop-down list box.
3. Select either the Apply push button to see how this color looks for
your part without saving the change or the OK push button to close the
settings notebook and save the color change.
Size/Position
A page that allows you to specify the size and position of a part.
Specifying the size and position of a part
To specify the size and position of a part, do the following:
1. In the x and y fields, specify the initial x/y coordinates for the
part. These coordinates determine the position of the part's upper left
corner.
2. In the width and height fields, specify the number of pixels for the
width and height of the part.
3. Optionally, you can also specify the smallest size the part can have by
using the Minimum Size group box to do either of the following:
If you want the minimum size to be calculated for you, select the
Calculate at execution time radio button.
If you want to specify the minimum size for the part, select the
Set value here radio button and then enter the width and height in
pixels in the corresponding fields.
Font
A page that allows you to specify the font that is to be used for the part.
Changing the font for a part
To change the font for a part, do one of the following:
If you know the name and size of the font you want to use, you can
enter them in their respective fields.
If you do not know the name and size of the font you want to use or if
you want to change the style or emphasis, select the Edit push button.
Visual Builder displays a standard font dialog on which you can select
the name, size, style, and emphasis you want to use for the part's
font.
Using code strings to supply initial field values
Many settings pages provide fields in which you can specify initial values for
part settings. For example, the General page of the IEntryField* settings
notebook contains a Text field and a Limit field. In the Text field, you can
enter a text string that you want Visual Builder to initially display in the
entry field. The Limit field contains a default value of 32, which represents
the maximum number of characters a user can type in the entry field, and you
can change this number.
To facilitate National Language Support (NLS) translation and code changes in
providing settings values, such as the ones just described, you can enter a
code string to provide those values. You must precede the code string with a
number sign (#). If the first character of your code string is a #, be sure to
enter two #s-the first one to signify that a code string follows and the
second one to begin your code string.
For example, suppose you want the initial text in an entry field to be Enter a
name here. Further, suppose that you want the limit for this entry field to be
18 characters. In a user header file (.hpv or .h), you could insert the
following #define statements:
#define NAME_PROMPT "Enter a name here"
#define NAME_LENGTH 18
Be sure to enter the name of the file that contains these #define
statements in the Required include files field in the Class Editor.
Otherwise, this file is not included when you generate the code for
this part.
Then, on the General page of the IEntryField* settings notebook you could
enter the following in the Text and Limit fields, respectively:
#NAME_PROMPT
#NAME_LENGTH
By doing this, the values that you defined for NAME_PROMPT and NAME_LENGTH are
used when you generate the source code for the part being edited.
For an example that uses a code string to specify an icon to represent items
in a container, see the subsection titled "Specifying the container type and
layout" in Adding Container Parts.
Activating settings changes
After you make changes to the settings, you can activate them in the following
ways:
Select the OK push button to immediately activate and save the settings
changes you have made, and close the settings notebook.
Select the Apply push button to apply the settings changes you have made
and keep the settings notebook open.
This allows you to see whether you need to modify any of the changes you
have made. The changes remain applied until you change them again.
Select the Cancel push button to remove the settings notebook. If you made
changes and selected the Apply push button, the changes are saved.
Select the Help push button for more help with using the settings notebook.
For information about the settings of a particular part, refer to the settings
section of the part in the Visual Builder Parts Reference.
ΓòÉΓòÉΓòÉ 9.3.7. Using the Generic Settings Notebook ΓòÉΓòÉΓòÉ
When you create a part, Visual Builder provides a settings notebook for that
part. The settings notebook for your part has one page, which contains the
following types of settings:
An entry field for each attribute that has a set member function
The #define statements are supported for the generic settings notebook,
just as they are for a regular settings notebook. See Changing Settings
for a Part for information about using #define statements in a settings
notebook.
A check box for each Boolean attribute
If your part has no attributes, the page displays a message saying that there
are no values to set.
To view the settings notebook for your part, do one of the following:
To set values for an instance of your part that you are using in a
composite part, do the following:
1. Place the part in the Composition Editor.
2. Move the mouse pointer over the part and click mouse button 2.
3. Select Open settings from the pop-up menu.
Visual Builder displays the settings notebook for the part.
To set attribute values for your part that will be available each time
your part is used, do the following:
1. Open the part.
2. If the part is a nonvisual or class interface part, switch to the
Composition Editor. You will already be in the Composition Editor if
your part is a visual part.
3. Move the mouse pointer over the free-form surface and click mouse
button 2.
4. Select Open settings from the pop-up menu.
A quicker way to open the generic settings notebook
is to double-click on the part.
Visual Builder displays the settings notebook for the part.
The following figure shows the generic settings notebook for the OAContract
part:
The notebook page includes settings for attributes that your part inherits
from other parts in addition to attributes for the part you created. For
example, the enabledForNotification check box is present because the
OAContract part inherits this Boolean attribute from IStandardNotifier.
ΓòÉΓòÉΓòÉ 9.3.8. Setting the Tabbing Order ΓòÉΓòÉΓòÉ
The tabbing order specifies the order that the input focus moves from part to
part as the user presses the Tab key. The tabbing order can further specify the
order that the input focus moves to parts within a tab group as the user
presses the arrow keys.
The tabbing order can only be set or displayed for parts that are placed within
a Composers part. For example, if you place a row of push buttons in a frame
window, you can set the tabbing order for the push buttons.
The initial order of the parts in the tabbing order list is determined by the
order in which you place the parts on the Composers part. Also, the first part
in the list is the part that receives the initial input focus. For example, if
the first part in the list is a push button, that push button receives the
initial input focus when the application starts.
Displaying the tabbing order list
To display the tabbing order list, do the following:
1. Move the mouse pointer to the Composers part whose tab order you want to
change.
2. Click mouse button 2.
Visual Builder displays the pop-up menu for the Composers part.
3. Select Tabbing And Depth Order.
A list of the current tabbing order is displayed. The following figure
shows the tabbing order list for a canvas part that contains three push
buttons.
When the tabbing order is displayed, you can do the following:
Change the positions of parts in the tabbing order list.
Set groups and tab stops.
Perform operations on parts in the tabbing order list.
ΓòÉΓòÉΓòÉ 9.3.8.1. Changing the Positions of Parts in the Tabbing Order List ΓòÉΓòÉΓòÉ
Since the order in which parts are placed on a Composers part determines the
tabbing order, you will probably need to change the order of the list as you
add or rearrange parts. For example, suppose you decide to rearrange the three
push buttons from the example in the preceding section so that PushButton3 is
between PushButton1 and PushButton2, as shown in the following figure:
As shown in the following figure, the tabbing order of these push buttons is
PushButton1, PushButton2, PushButton3, even though PushButton3 is now between
PushButton1 and PushButton2.
By moving PushButton3 between PushButton1 and PushButton2 in the tabbing order
list, you can change the order so that you can cursor directly from PushButton1
to PushButton3 instead of jumping over to PushButton 2 first. The changed
tabbing order list is shown in the following figure:
To change the position of a part within the tabbing order list, do the
following:
1. Move the mouse pointer to the part whose position you want to change.
2. Press and hold mouse button 2.
3. Drag the part to a new position in the list.
4. Release mouse button 2.
You can change the position of several parts within the tabbing
order at the same time by first selecting all the parts you want to
move. You select multiple parts by holding down the Ctrl key and
clicking on the parts with mouse button 1.
You cannot move a subpart to a new Composers part by changing the
tabbing order. You must do this in the Composition Editor.
ΓòÉΓòÉΓòÉ 9.3.8.2. Setting Groups and Tab Stops ΓòÉΓòÉΓòÉ
If you want the user to be able to move the input focus to a part using the Tab
and Backtab keys, select the Tab stop check box to the left of the part in the
tabbing order list.
If you want the user to be able to move the input focus to a part with the
keyboard arrow keys, select the Group check box to the left of the first part
in the group. All other parts listed below the part that has Group selected are
included in the group.
To start another group, select the Group check box for the part that you want
to be the first part in that group. If a part has both Group and Tab stop
selected, a user can tab to the first part in the group and then use the arrow
keys to move to the other parts in the group.
Special considerations for radio buttons and entry fields
When you put radio buttons in groups, they become mutually exclusive within
their group. For example, suppose you have four consecutive radio buttons in
your list and you select the Group check box for RadioButton1 and RadioButton3.
In this case, RadioButton1 and RadioButton2 become mutually exclusive in their
group, with RadioButton3 and RadioButton4 mutually exclusive in their group, as
well. The following figure shows an example. Tab stops are also set so a user
can tab between the two groups.
Consider setting a tab stop on each entry field that a user can type in to
allow the user to move the input focus from one entry field to another.
Read-only entry fields do not need a tab stop and arrow keys only move the
cursor within an entry field; only the Tab key, the Backtab key, and the mouse
can change the input focus from one entry field to another.
Style guidelines for setting groups and tab stops
The following are some typical style guidelines for setting groups and tab
stops:
The position of the parts in the tabbing order should be the same as the
order in which they are displayed in the window, from left to right and
then top to bottom.
Parts that are not in groups, such as entry fields and list boxes, should
have Group and Tab stop selected.
Each group of related parts, such as check boxes and radio buttons,
should be put within an outline box or a group box.
If there is only one group of related parts, such as push buttons, you do
not need to put them within an outline box or group box. Select only Tab
stop for these parts.
Parts that should not receive input focus, such as static text parts,
should not have either Group or Tab stop selected.
ΓòÉΓòÉΓòÉ 9.3.8.3. Performing Operations on Parts in the Tabbing Order List ΓòÉΓòÉΓòÉ
You can perform many of the same operations on parts listed in the tabbing
order that you can perform on the parts on the free-form surface. Visual
Builder provides pop-up menus that contain the allowable operations for each
part in the list. Examples of typical operations are opening a part's settings,
editing a part, and browsing a part's features.
To perform an operation on a part in the tabbing order list, do the following:
1. Move the mouse pointer over the part.
2. Click mouse button 2.
Visual Builder displays the pop-up menu for the part.
3. Select the operation you want to perform.
ΓòÉΓòÉΓòÉ 9.3.9. Editing Parts Placed on the Free-form Surface ΓòÉΓòÉΓòÉ
Suppose you create a composite part, add it to another composite part that you
are creating, and then realize that you need to change the first composite
part. With Visual Builder you do not have to start over. It provides a way for
you to edit the part that needs to be changed right from the free-form surface.
The only exception is the base parts that Visual Builder provides. Visual
Builder does not allow you to modify these parts. This includes all of the
parts that the vbbase.vbb file contains. If you place one of these base parts
on either a Composers part or the free-form surface, you can modify the subpart
by doing any of the following:
If you want to add an action to the subpart, consider connecting to a
member function or custom logic that belongs to the composite part,
instead. Write a member function or provide custom logic if you need to
perform an action of limited usefulness, that is, one that you do not
anticipate using very often, and that you do not want derived parts to
inherit. For information about using member functions and custom logic in
connections, see the following:
- Adding an Event-to-Member Function Connection
- Connecting Features to Custom Logic
If you want to add a new feature that you plan to use often, create a new
part that is derived from the base part. For example, to add a new
feature to an IEntryField* part, create a new visual part whose base part
is the IEntryField* part and replace the IEntryField* part that you were
using with your new part. You can then add as many new features to your
new part as you need.
If you derive a new part from a base part, you also have the option of
adding handlers to the new part. One reason for adding handlers is that
you might want to monitor Presentation Manager messages to see when
certain events occur and then notify observers. Another reason is that
you might want to add special behavior to your part. You can add handlers
to parts that Visual Builder provides on the Handlers page of the part's
settings notebook. For more information about handlers, refer to the IBM
Open Class Library User's Guide.
If you need to edit a part that was added to the part you are currently
editing, do the following:
1. If you have not already done so, load the .vbb file that contains the
part you want to edit.
2. Move the mouse pointer over the part you want to edit.
3. Click mouse button 2.
The part's pop-up menu appears.
4. Select Edit Part.
Visual Builder displays the appropriate editor for the part, as follows:
If you are editing a visual part, Visual Builder displays the
Composition Editor
If you are editing a nonvisual or class interface part, Visual
Builder displays the Part Interface Editor.
5. Edit the part.
If you want to promote any of the features of the parts
used to create the composite part you are editing, doing
so now keeps you from having to edit this part again
later. See Promoting a Part's Features if you need more
information about doing this.
6. Select FileSave to save the part.
7. Close the editor by doing one of the following:
Double-click on the system menu icon.
Select FileExit.
The editor you are using disappears and you are returned to the
Composition Editor you were using previously. However, Visual Builder has
not applied the changes you made to the part you just edited, so those
changes are not visible yet.
8. Select FileSave to save the original part.
9. Close the Composition Editor for the original part that you were editing,
as described above.
10. Reopen the original part you were editing by double-clicking on the
part's name in the Visual Builder window.
You should now be able to see the changes you made to the part that you
edited.
ΓòÉΓòÉΓòÉ 9.3.10. Promoting a Part's Features ΓòÉΓòÉΓòÉ
In Guidelines for Placing Parts on the Free-form Surface, we explained the
relationship between parts in the Composers category and parts that are placed
on top of them, called subparts. When you create a visual part that consists of
a part from the Composers category that contains subparts, you can then place
that visual part on top of another part from the Composers category. However,
if you do this, the features of the subparts in the visual part that you
created are not automatically available. You must promote these features to use
them in connections.
For example, suppose you create a visual part called Buttons whose base class
is ICanvas*. This part consists of a canvas part that contains three push
button parts. Here is what the Buttons part looks like:
Suppose you create another visual part whose base class is IFrameWindow* and
then add the Buttons part to the frame window part. Here is what the frame
window part with the Buttons part looks like:
Now, suppose that you want to connect the buttonClickEvent feature of the
Cancel push button to the close feature of the Frame Window so that the window
closes whenever the Cancel push button is selected. However, features of the
push button parts are not automatically available for connections because the
push buttons are subparts of the canvas.
When you use a part such as Buttons as a subpart, only the features of the
Buttons part's ancestor parts (ICanvas, IWindow, and so forth) are available in
the connections menu for the Buttons part. To use the features of the push
button parts, you must promote them to the Buttons part. You can do this either
before or after you add the Buttons part to the frame window.
The following steps show you how to promote a part's features from the
Composition Editor.
To promote features of several subparts, we recommend using Promote
page of the Part Interface Editor. For information about promoting a
part's features from the Part Interface Editor, see The Promote
Page.
1. If you have not already done so, load the .vbb file that contains the
composite part whose features you want to promote.
2. If you have not already done so, open the composite part or edit the
subpart, whichever is necessary.
Visual Builder displays the Composition Editor with the part that you are
opening or the subpart that you are editing on the free-form surface.
3. Move the mouse pointer over a part whose features you want to promote.
4. Click mouse button 2 to display the part's pop-up menu.
5. Select Promote Part Feature.
Visual Builder displays a window with three columns of features: one for
attributes, one for events, and one for actions. The following figure
shows the window that is displayed for a push button part.
6. Select a feature.
The name of the feature you selected is displayed in the Promote feature
name entry field prefixed with the name of the part. This is done so that
when you make the connection, you can tell which push button part the
feature belongs to. For example, if you selected the buttonClickEvent
feature for the PushButton2 part, the feature name displayed in the entry
field would be pushButton2ButtonClickEvent, as shown in the following
figure. This is how the feature name will appear in the connections menu
unless you change it before performing the next step.
7. Select the Promote push button.
The feature name is added to the Previously promoted list box, as shown
inthe following figure:
8. Repeat the previous two steps until you have promoted all of the features
you need to make the necessary connections.
9. Close the window for promoting features.
10. Select FileSave to save the features you just promoted.
11. Close the Composition Editor.
You can now use the feature or features that you promoted to make
connections.
ΓòÉΓòÉΓòÉ 9.3.11. Tearing Off an Attribute ΓòÉΓòÉΓòÉ
Select Tear-Off Attribute from a part's pop-up menu to work with an attribute
as if it were a standalone part. The torn-off attribute is not actually a
separate part but a variable that either represents the attribute itself or
points to it.
When you select Tear-Off Attribute, Visual Builder displays the list of
attributes for the part that you are tearing from. After you select an
attribute from the list, you can drop the torn-off attribute on the free-form
surface. Visual Builder creates an attribute-to-attribute connection between
the original part and the torn-off attribute. You can then make other
connections to or from the torn-off attribute.
You might want to tear off an attribute to do the following:
Allow direct access from one that is nested inside of another
Enable direct access to an attribute's events and actions
For example, in an address book application you might tear off attributes as
follows:
You might have a Person part that contains both homeAddress and
workAddress attributes, both of which, in turn, could contain street,
city, and state attributes.
By tearing off either the homeAddress or workAddress attribute, you can
create a new part that contains street, city, and state attributes.
Tearing off a homeAddress or workAddress attribute makes the nested
street, city, and state attributes directly accessible. Now that the
nested attributes are directly accessible, you can make connections to
and from them, as well as to their associated events and actions.
ΓòÉΓòÉΓòÉ 9.3.12. Undoing and Redoing Changes in the Composition Editor ΓòÉΓòÉΓòÉ
If you change something in the Composition Editor and then decide that you
should have left things as they were, select Undo from the Edit pull-down menu
to restore the part to its previous state. You can undo as many operations as
you want, all the way back to when you opened the Composition Editor.
If you undo an operation and then decide that you did the right thing in the
first place, select Redo from the Edit pull-down menu. Redo restores the part
to the state it was in before the last Undo, including any connections that
were deleted.
If you are not sure which operations you want to undo or redo, select Undo/Redo
list from the Edit pull-down menu to display two lists of operations, one for
undoing and one for redoing. From these lists, you can select an operation and
then select the Undo or Redo push button. The operation that you select and all
of the operations listed below it are undone or redone.
Note: Undo, Redo, and Undo/Redo list only affect operations you perform on the
free-form surface and parts palette in the Composition Editor. They have
no affect on any of the functions in the File pull-down menu, such as
Save, Save As, and Save and Generate, which you cannot undo.
ΓòÉΓòÉΓòÉ 9.4. Constructing a GUI: the OASearch Application ΓòÉΓòÉΓòÉ
GUI construction overview
Adding basic visual parts
- Adding the parts
- Changing the settings
Adding a variable to a composite part
- Changing the variable's type
- Adding the variable to the part interface
Personal notes:
ΓòÉΓòÉΓòÉ 9.4.1. GUI Construction Overview ΓòÉΓòÉΓòÉ
The remainder of this chapter describes how to visually construct the graphical
user interface (GUI) of an application using the OASearch application as an
example. You construct a GUI by adding visual parts, such as push buttons,
lists, and menus, to a window part. For a list of the visual parts available on
the Composition Editor, see The Parts Palette.
ΓòÉΓòÉΓòÉ 9.4.2. Adding Basic Visual Parts ΓòÉΓòÉΓòÉ
The purpose of this section is to guide you through constructing a version of
the Opportunities Abound Contract Information window for the OASearch sample
application. You construct this part (ContractView) in the Composition Editor
using the basic visual parts. When finished, the Opportunities Abound Contract
Information window looks like the following figure:
To see the finished part, open contract.vbb. Begin with adding the parts.
ΓòÉΓòÉΓòÉ 9.4.2.1. Adding the Parts ΓòÉΓòÉΓòÉ
Before starting this new visual part, make sure that oanonvis.vbb is loaded
into Visual Builder.
Adding the parts
1. Because you are constructing a new user interface, begin by creating a
visual part. Call it ContractView.
When you create a visual part, the Composition Editor opens a part that
inherits from IFrameWindow*. By default, the client area of the
IFrameWindow* appears as a canvas.
2. Change the title of the window.
3. Add the following parts to the window part:
Static text and entry field parts for Account Number, Company Name,
Project Manager, and Department.
A group-box part for the Position Details group. Resize the group
box.
Static-text and entry-field parts for the items inside the group
box.
Push-button parts.
See the figure below to see how the window should look after the parts
are added.
Changing the Labels
Directly edit the static text so that the text matches the figure shown in
What You Will Achieve.
Arranging the Parts
Arrange the parts on the frame window part so they are aligned and positioned
as shown in What You Will Achieve.
For more information on how to perform these operations, see Using Parts.
Now that all the parts have been added, continue on with changing the
settings.
ΓòÉΓòÉΓòÉ 9.4.2.2. Changing the Settings ΓòÉΓòÉΓòÉ
Now that the parts have been added for the user interface, customize the parts
by modifying their settings.
Specifying a push button label with mnemonic
On the General settings page for the middle push button, type ~Save in the Text
field. Select the OK push button.
The middle push button of your window now reads Save, with a mnemonic of S.
This means the user can select the push button by pressing Alt+S.
Repeat this procedure for the push button to the right of the Save push button,
specifying Cl~ear as the push button label. This push button now reads Clear,
with a mnemonic of E.
For the rightmost push button, specify ~Cancel as the label. This push button
now reads Cancel, with a mnemonic of C.
Specifying the default push button
On the General settings page for the leftmost push button, type ~Refresh in the
Text field. Select the Apply push button. The leftmost push button of your
window now reads Refresh, with a mnemonic of R.
On the Styles settings page, select the On radio button for the defaultButton
style. Select the OK push button. The Refresh push button is now the default
button for the window. This means the user can select the push button by
pressing the Enter key.
For details on the settings of a particular part, refer to the Visual Builder
Parts Reference. For more information on how to perform these operations, see
Changing Settings.
Now that the settings have been specified, the next step is making connections
between the parts.
ΓòÉΓòÉΓòÉ 9.4.3. Adding a Variable to a Composite Part ΓòÉΓòÉΓòÉ
Variables serve an important role in complex applications. Use variables
instead of parts in the following situations:
To act as a placeholder inside a composite part for parts not found in
the composite part. Using variables for nonvisual parts enables you to
pass data or function between composite parts.
To represent part instances created with Object Factory parts. For more
information on using Object Factory parts, see Adding Parts as Dynamic
Instances.
Each variable must be set to the part type it represents. Once set, the
variable takes on the interface of that part type. Unlike using a part, using
a variable does not cause the part constructor to run.
Begin by opening the ContractView part (found in contract.vbb) in the
Composition Editor. If you prefer to use the OAContractView part, you can find
this part in oawin.vbb. At this point, the ContractView part appears as shown
in the following figure:
We are using a variable instead of an OAContract* part because the contract
data varies with the information entered from the OAQueryContract* part.
To add a variable to the free-form surface, select , the Models category, from
the parts palette; then add , an IVBVariable* part, to the free-form surface.
Change its name to Contract. The ContractView with a variable added appears as
shown in the following figure:
Notice the square bracket symbols around the variable part. You can
always identify a variable by these symbols. Also note that tear-off
attributes also have square brackets and are in fact variables with
a special connection.
The next step is changing the variable's type.
ΓòÉΓòÉΓòÉ 9.4.3.1. Changing the Variable's Type ΓòÉΓòÉΓòÉ
When you add a variable part, its type is initially IStandardNotifier*, meaning
that the variable can stand for any part. This variable is supposed to stand
for an OAContract* in this example, so you must change its type.
Note: You cannot use variables to represent template-based parts, such as
IVSequence*.
1. First, make sure the the .vbb file holding the OAContract part
(oanonvis.vbb) is loaded into Visual Builder.
2. Select Change Type on the variable's pop-up menu; then type OAContract*
The next step is adding the variable to the part interface.
ΓòÉΓòÉΓòÉ 9.4.3.2. Adding the Variable to the Part Interface ΓòÉΓòÉΓòÉ
So far, the Contract variable is empty. To make the variable available for
passing values from the main view (or any part outside ContractView), we must
add the variable to the part interface of ContractView), Do this by selecting
Promote Part Feature from the variable's pop-up menu. See Promoting a Part's
Features if you need information about doing this.
The next step is connecting the variable.
ΓòÉΓòÉΓòÉ 10. Learning to Use Connections ΓòÉΓòÉΓòÉ
Connection types overview
Connection type summary
Making the connections
Connecting features to member functions
Connecting features to custom logic
Connecting exception events to actions and member functions
Manipulating connections
Rearranging connections
Making connections for the OASearch application
Personal notes:
ΓòÉΓòÉΓòÉ 10.1. Connection Types Overview ΓòÉΓòÉΓòÉ
This chapter describes the types of connections that you can make and how to
make them. Each connection description provides a definition of the connection,
the color of the connection, whether the arrows are unidirectional or
bidirectional, and whether the connection requires you to satisfy parameters to
complete it.
Attribute-to-attribute connection
An attribute-to-attribute connection links two attribute values together. The
purpose of this type of connection is to cause the value of one attribute to
change when the value of another attribute changes.
An attribute-to-attribute connection uses a bidirectional cyan arrow with the
solid arrow head pointing to the target and the hollow arrow head pointing to
the source. The bidirectional arrow indicates that a change in the value of
either attribute can cause the value of the other attribute to change
accordingly, except as noted in the table below. When your part is created
within an application, the target attribute is set to the value of the source
attribute. Attribute-to-attribute connections never take any parameters.
Note: You can use a class interface part as the source of a connection only
when making an attribute-to-attribute connection. An attribute of a
class interface part can be used to initialize an attribute of another
part without using notification.
In the following example, the text attribute of the entry field is connected
to the accountNum attribute of the Contract. This connection causes the value
of the accountNum attribute to change whenever the value of the text attribute
changes, and vice versa.
The effect of attribute types on connections
It is important to know the types of attributes that you are connecting.
Otherwise, you might not achieve the results that you anticipate.
The following table shows the results of connecting attributes that have
different behavior types. See The Attribute Page for descriptions of the
attribute types.
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIf the source is a...ΓöéAnd the target is a ΓöéAnd the target is a ΓöéAnd the target is a Γöé
Γöé Γöéfull attribute... Γöéno-set attribute... Γöéno-event attribute...Γöé
Γöéfull attribute ΓöéAll attribute ΓöéThe target attribute ΓöéThe target attribute Γöé
Γöé Γöébehaviors are Γöécannot set itself to Γöécannot notify the Γöé
Γöé Γöéavailable to both theΓöéthe value of the Γöésource attribute whenΓöé
Γöé Γöésource and target Γöésource attribute. Γöéthe target Γöé
Γöé Γöéattributes. Γöé Γöéattribute's value Γöé
Γöé Γöé Γöé Γöéchanges. Γöé
Γöéno-set attribute ΓöéThe source attribute ΓöéThis is an invalid ΓöéThe source attribute Γöé
Γöé Γöécannot set itself to Γöéconnection. Γöécannot set itself to Γöé
Γöé Γöéthe value of the Γöé Γöéthe value of the Γöé
Γöé Γöétarget attribute. Γöé Γöétarget attribute; theΓöé
Γöé Γöé Γöé Γöétarget attribute Γöé
Γöé Γöé Γöé Γöécannot notify the Γöé
Γöé Γöé Γöé Γöésource attribute whenΓöé
Γöé Γöé Γöé Γöéthe target Γöé
Γöé Γöé Γöé Γöéattribute's value Γöé
Γöé Γöé Γöé Γöéchanges. Γöé
Γöéno-event attribute ΓöéThe source attribute ΓöéThe source attribute ΓöéThe source attribute Γöé
Γöé Γöéinitializes the Γöéinitializes the Γöéinitializes the Γöé
Γöé Γöétarget attribute; no Γöétarget attribute; no Γöétarget attribute; no Γöé
Γöé Γöéevent notification Γöéevent notification Γöéevent notification Γöé
Γöé Γöéoccurs. Γöéoccurs; the target Γöéoccurs; the target Γöé
Γöé Γöé Γöéattribute cannot set Γöéattribute cannot Γöé
Γöé Γöé Γöéitself to the value Γöénotify the source Γöé
Γöé Γöé Γöéof the source Γöéattribute when the Γöé
Γöé Γöé Γöéattribute. Γöétarget attribute's Γöé
Γöé Γöé Γöé Γöévalue changes. Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Event-to-attribute connection
An event-to-attribute connection allows the occurrence of the source event to
change the value of the target attribute. To accomplish this, the connection
calls the attribute's set member function whenever the event occurs. If the
attribute is a no-set attribute, you cannot make the connection.
An event-to-attribute connection uses a unidirectional dark green arrow with
the arrow head pointing to the target. If the attribute's set member function
requires data to satisfy its parameter, the connection line is initially
dashed to show that it is incomplete unless event data is provided, causing it
to turn solid.
You can satisfy the missing parameter value or override any event data that is
present by connecting the parameter to an attribute, action, member function
or custom logic, or by supplying a constant parameter value. See Satisfying
Parameters for Incomplete Connections for information about providing
parameter values.
In the following example, the buttonClickEvent feature of the Refresh push
button is connected to the text attribute of the entry field.
Event-to-action connection
An event-to-action connection allows an action to start whenever the event
that the action is connected to occurs.
An event-to-action connection uses a unidirectional, dark green arrow with the
arrow head pointing to the target. If the action requires data to satisfy its
parameter, the connection line is initially dashed to show that it is
incomplete unless event data is provided, causing it to turn solid.
You can satisfy the missing parameter value or override any event data that is
present by connecting the parameter to an attribute, action, member function
or custom logic, or by supplying a constant parameter value. See Satisfying
Parameters for Incomplete Connections for information about providing
parameter values.
Also, the action that is the target of this connection can have a return
value. If it does, you can treat the return value as a no-set attribute of the
connection and use it as the source of another connection. The return value
appears in the connection menu for the connection as actionResult.
In the following example, the buttonClickEvent feature of the Add push button
is connected to the addAsLast action of the multiline edit control.
Event-to-member function connection
An event-to-member function connection calls a member function of the part
currently being edited whenever the event that the member function is
connected to occurs.
An event-to-member function connection uses a unidirectional, light green
arrow with the arrow head pointing to the target. If the member function
requires data to satisfy its parameter, the connection line is initially
dashed to show that it is incomplete unless event data is provided, causing it
to turn solid.
You can satisfy the missing parameter value or override any event data that is
present by connecting the parameter to an attribute, action, member function
or custom logic, or by supplying a constant parameter value. See Satisfying
Parameters for Incomplete Connections for information about providing
parameter values.
Also, the member function that is the target of this connection may have a
return value. If it does, you can treat the return value as a no-set attribute
of the connection and use it as the source of another connection. The return
value appears in the connection menu for the connection as actionResult.
In the following example, the buttonClickEvent feature of the Clear push
button is connected to a resetFields member function.
Attribute-to-action connection
An attribute-to-action connection allows an action to start whenever the event
identification that is associated with the attribute is triggered. This
connection is similar to an event-to-action connection because the connection
calls the action whenever the attribute's event is triggered.
An attribute-to-action connection uses a unidirectional, dark green arrow with
the arrow head pointing to the target. If the action requires data to satisfy
its parameter, the connection line is initially dashed to show that it is
incomplete unless event data is provided, causing it to turn solid.
The attribute's value is passed as the first parameter of the action if no
parameter is explicitly specified. You can satisfy any other missing parameter
values or override the attribute value that is present by connecting the
parameter to an attribute, action, member function or custom logic, or by
supplying a constant parameter value. See Satisfying Parameters for Incomplete
Connections for information about providing parameter values.
Also, the action that is the target of this connection can have a return
value. If it does, you can treat the return value as a no-set attribute of the
connection and use it as the source of another connection. The return value
appears in the connection menu for the connection as actionResult.
In the following example, the text attribute of the entry field is connected
to the addAsLast action of the list box.
Attribute-to-member function connection
An attribute-to-member function connection allows a member function to start
whenever the event identification that is associated with the attribute is
triggered. This connection is similar to an event-to-member function
connection because the connection calls the action whenever the attribute's
event is triggered. However, if the attribute is a no-event attribute, the
member function is not signalled because a no-event attribute does not have an
event identifier.
An attribute-to-member function connection uses a unidirectional, light green
arrow with the arrow head pointing to the target. If the member function
requires data to satisfy its parameter, the connection line is initially
dashed to show that it is incomplete unless event data is provided, causing it
to turn solid.
You can satisfy the missing parameter value or override any event data that is
present by connecting the parameter to an attribute, action, member function
or custom logic, or by supplying a constant parameter value. See Satisfying
Parameters for Incomplete Connections for information about providing
parameter values.
Also, the member function that is the target of this connection can have a
return value. If it does, you can treat the return value as a no-set attribute
of the connection and use it as the source of another connection. The return
value appears in the connection menu for the connection as actionResult.
In the following example, a member function is called to calculate the
presentation space in the list box.
Custom logic connection
A custom logic connection allows your customized logic to run whenever either
of the following happens:
The value of the attribute that you connect it to changes.
The event that you connect it to occurs.
If you connect an attribute to your custom logic, use the attribute's event
identifier to execute the custom logic when the attribute's value changes.
A custom logic connection uses a unidirectional, blue arrow with the arrow
head pointing to the target.
Also, the custom logic that is the target of this connection may have a return
value. If it does, you can treat the return value as a no-set attribute
attribute of the connection and use it as the source of another connection.
The return value appears in the connection menu for the connection as
actionResult.
In the following example, custom logic is called to clear all of the entry
fields in a notebook. Otherwise, you would need to make a separate connection
from the push button's buttonClickEvent feature to the clear action of each
entry field.
Parameter connections
A parameter connection satisfies a parameter of an action or member function
by passing either an attribute's value or the return value from an action,
member function, or custom logic. This connection looks similar to an
attribute-to-attribute connection; it uses a bidirectional arrow, with the
solid arrow pointing to the target and the hollow arrow pointing to the
source. The difference you see on your screen is that parameter connections
are violet instead of cyan.
In addition, the parameter names are included in the connection menu.
Therefore, if you are in doubt about a connection that you want to make, you
can browse a part's features to see the parameter names. Be aware, however,
that any parameter names that you specified for an action in the Parameter
Names table on the Action page of the Part Interface Editor appear in the
connection menu instead of the actual parameter names.
The parameter is always the source of the connection because the parameter
cannot store any values. If you connect an attribute, action, member function,
or custom logic to a parameter, which makes the parameter the target of the
connection, Visual Builder reverses the direction to make the parameter the
source.
Whenever the parameter needs a value, the connection attempts to satisfy the
parameter in one of the following ways:
If the parameter is connected to an attribute, the connection invokes the
attribute's get member function to get the attribute's value and return
it to the parameter.
If the parameter is connected to an action, the connection invokes the
action and passes the action's return value to the parameter. The same is
true when a parameter is connected to a member function or to custom
logic.
You can supply a constant parameter value. See Satisfying Parameters for
Incomplete Connections for information about doing this.
If you connect a parameter to two different attributes, the first attribute
that you connect the parameter to has precedence over the second. You can
change this, if necessary, by reordering the connections or deleting one of
the connections.
Visual Builder uses a dashed line to give you a visual cue so that you know
when a parameter connection is needed. For example, if you connect an event to
a member function and the member function has a parameter that needs to be
satisfied, the connection line between the event and the member function is
dashed. See Satisfying Parameters for Incomplete Connections for more
information about parameter connections.
ΓòÉΓòÉΓòÉ 10.2. Connection Type Summary ΓòÉΓòÉΓòÉ
The following table summarizes the types of connections that Visual Builder
provides:
Note: In the table below, the return value is supplied by the connection's
actionResult attribute.
If you want to... Use this connection Color Arrows Return value
type allowed?
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Cause one data value attribute-to-attribute Cyan Bidirectional No
to change another
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Change a data value event-to-attribute Dark green Unidirectional Yes
whenever an event
occurs
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Invoke an action event-to-action Dark green Unidirectional Yes
whenever an event
occurs
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Invoke a member event-to-member Light green Unidirectional Yes
function whenever an function
event occurs
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Invoke an action attribute-to-action Dark green Unidirectional Yes
whenever a data value
changes
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Invoke a member attribute-to-member Light green Unidirectional Yes
function whenever a function
data value changes
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Call customized code custom logic Blue Unidirectional Yes
whenever a data value
changes or an event
occurs
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Satisfy a parameter parameter Violet Bidirectional Yes
with a data value
ΓòÉΓòÉΓòÉ 10.3. Making the Connections ΓòÉΓòÉΓòÉ
In this section, you learn how to make attribute-to-attribute,
event-to-attribute, event-to-action, and attribute-to-action connections. This
section provides the following information:
Determining the source and target
Browsing a part's features
Connecting features to features
Satisfying parameters for incomplete connections
Member function connections are discussed in Connecting Features to Member
Functions. Custom logic connections are discussed in Connecting Features to
Custom Logic.
ΓòÉΓòÉΓòÉ 10.3.1. Determining the Source and Target ΓòÉΓòÉΓòÉ
A connection is directional; it has a source and a target. The direction in
which you draw the connection determines the source and target. The part on
which the connection begins is the source and the part on which it ends is the
target.
When you make a connection, Visual Builder draws an arrow on the connection
line between the two parts. The arrow points from the source to the target. If
information can pass through the connection in both directions, as it can in an
attribute-to-attribute connection, a hollow arrow points to the source and a
solid arrow points to the target.
Often, it does not matter which part you choose as the source or target, but
there are connections where direction is important.
Here are the source and target rules:
With an attribute-to-action, event-to-action, or event-to-attribute
connection, the event is always the source and the action or attribute is
always the target. If you try to make an action-to-attribute,
action-to-event, or attribute-to-event connection, Visual Builder
automatically reverses it for you.
For attribute-to-attribute connections, if only one of the attributes has
a set member function Visual Builder makes that attribute the target.
This is done so that the attribute that has the set member function can
be initialized when the application starts.
When you make attribute-to-attribute connections, the order in which you
choose the source and target is important. The source and target
attribute values are probably different when your view is first
initialized. If they are, Visual Builder resolves the difference by
changing the target end of the connection to match the source.
Thereafter, if both attributes have set member functions, the connection
updates either attribute if the other changes.
Refer to the attributes, actions, and events sections of the particular part
in the Visual Builder Parts Reference for information that is specific to a
part's features.
ΓòÉΓòÉΓòÉ 10.3.2. Browsing a Part's Features ΓòÉΓòÉΓòÉ
Sometimes it is useful to browse a part's features before using them in a
connection. For example, you might want to look at an attribute to see if it
has a set member function so that it can update itself when it receives new
data from another attribute.
By using Browse Part Features, you can see all of a part's features in one
window and browse, but not change, the information about each feature. To
modify a feature, use the Part Interface Editor.
There is an important distinction between browsing a part's features and
displaying its features for making a connection. When you browse a part's
features, you see all of its features, including inherited and promoted
features, even if some of them are not available for connections. When you
display a part's connection menu, however, you see only those features that are
available for connections.
To browse the features of a part, do the following:
1. Move the mouse pointer over the part and click mouse button 2.
Visual Builder displays the part's pop-up menu.
2. Select Browse Part Features.
Visual Builder displays a browse window that contains three columns: one
for actions, one for attributes, and one for events. For example, the
following figure shows the browse window that Visual Builder displays for
browsing the features of a push button:
3. Select the feature you want to browse.
Visual Builder displays information about the feature that you select in
the entry fields below the feature columns. Different sets of entry
fields are displayed depending on whether you select an attribute, an
event, or an action.
The information that Visual Builder displays when you browse a part's
features is the same as the information that you would see in the Part
Interface Editor. See Touring the Part Interface Editor to learn about
the information that Visual Builder displays for features.
4. If the information about a part's features should change, you can select
the Refresh push button to see those changes reflected in the browse
window.
5. When you have finished browsing the features, select the Close push
button to close the browse window.
ΓòÉΓòÉΓòÉ 10.3.3. Connecting Features to Features ΓòÉΓòÉΓòÉ
When you connect features to features, you can use any of the following
source-target combinations:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéIf source is a... ΓöéThe target can be a... Γöé
Γöépart Γöépart or connection Γöé
Γöéconnection Γöépart Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
Follow these steps to connect features:
1. Position the mouse pointer over the source, the part or connection that
you want to connect from, click mouse button 2, and select Connect from
its pop-up menu.
To display the connection pop-up menu more quickly, hold
down the Alt key while clicking mouse button 2.
A menu appears showing the names of the most commonly used attributes,
actions, and events, called the preferred features. If the source is a
part, there is usually a More selection at the bottom of the list.
If the More selection is not there, this means the list contains all of
the available features, not just the preferred ones, and there are no
more from which to select.
2. Do one of the following:
If the feature you want appears in the list, select it.
If the feature you want does not appear in the list, but the More
selection is available, select More and then select the feature you
want from the complete list of features.
If the feature you want does not appear in either the preferred list
or the expanded list that is displayed when you select More, you can
edit the part to add the feature you need. For more information
about this, see Editing Parts Placed on the Free-form Surface.
If, at this point, you decide not to complete the
connection, do one of the following:
- If a pop-up menu is displayed, move the mouse
pointer away from the connection menu and click
mouse button 1.
- If a window showing all of the features is
displayed, select the Cancel push button at the
bottom of the window.
The menu or window disappears and the connection is
not completed.
3. Position the mouse pointer over the part or connection that you want to
connect to.
While moving the mouse, notice that a dashed line trails from the mouse
pointer to the source of the connection.
4. Click mouse button 1 and a pop-up menu appears, again showing a list of
features.
5. Select a name from the pop-up menu or from the More list.
The same instructions regarding the presence of More apply as described
previously.
A colored connection line appears when both ends of the connection have been
made. The color indicates the connection's type, based on the selections you
made in the connection pop-up menu. See Connection Type Summary for a table
that shows the colors that are used for each connection type.
If the line is dashed, it requires parameters. To specify parameters, you make
an attribute-to-parameter connection or specify constant parameter values. You
can learn more about specifying parameters in Satisfying Parameters for
Incomplete Connections.
ΓòÉΓòÉΓòÉ 10.3.4. Satisfying Parameters for Incomplete Connections ΓòÉΓòÉΓòÉ
Event-to-action, attribute-to-action, event-to-attribute, event-to-member
function, and attribute-to-member function connections sometimes require
parameters, or input arguments. If a connection requires parameters that have
not been specified, it appears as a dashed arrow indicating that it is
incomplete. When you have made all the necessary parameter connections, the
connection line becomes solid indicating that the connection is complete.
The following sections describe how to complete connections when input
parameters are required and how to change source and target features without
deleting a connection and starting over.
Satisfying a parameter using a connection
One way to satisfy parameters is to make connections from the dashed connection
lines to the parts that supply the values to the parameters. Most of the time,
the values you need are those of attributes of other parts that you are working
with in the Composition Editor. Sometimes, however, the value you need is the
return value from an action, a member function, or custom logic.
To supply a parameter value, do the following:
1. Start a new connection using the dashed connection line that requires the
parameter as the source.
2. For the target, select the attribute, action, member function, or custom
logic that is to provide the value that the parameter needs.
While making a connection, when the mouse pointer is directly over
the connection line, you see a small box as a visual cue that the
pointer is positioned correctly.
The following example illustrates how to complete a connection using an
attribute to supply the input value to the parameter. The figure shows an
incomplete event-to-action connection. When a user selects the Add push
button, its buttonClickEvent feature notifies the addAsLast action of the
IListBox* part to add something to the list box as the last item in the list.
The connection is incomplete because the addAsLast action has a parameter that
needs an input value, which is the text to add to the list box.
The next example shows how a parameter connection, in which an attribute of
the IEntryField* part is used to supply the input value for the parameter,
completes the event-to-action connection shown above. The text parameter of
the incomplete connection is connected to the text attribute of the
IEntryField* part. Therefore, when the Add push button is selected, its
buttonClickEvent feature notifies the addAsLast action of the IListBox* part
to add the text in the IEntryField* part as the last item in the list box.
The return type of an action displays as the actionResult attribute
of the connection. For example, you can connect the actionResult
attribute to an attribute of the same part or another part.
Satisfying a parameter using a constant value
When connections need parameters whose input values are constant, you provide
these values by using the settings window of the incomplete connection, as
follows:
1. Select Open settings from the incomplete (dashed) connection's pop-up
menu.
A quicker way to open the settings window is to
double-click on the connection line.
The settings window of the incomplete connection is displayed.
2. Select the Set parameters push button.
The Constant Parameter Value Settings notebook is displayed showing the
parameters for which you can set constant values.
3. Enter the constant parameter values you want to use.
Type the parameter values just as you would type them as parameters for
the member function if you were coding it by hand. For example, to
provide a constant value for a text parameter, enter the text string that
you want the parameter to receive. Visual Builder copies them as strings
to the output files when you generate your default code.
In event-to-attribute connections, the attribute's set
member function sometimes has more than one parameter. In
this case, Visual Builder only allows you to provide a
constant parameter value for the first parameter. The
other parameters are given default settings.
For example, a set member function called setRange might
have a range parameter and an override parameter. If you
followed the instructions provided in this section, when
you selected the Set parameters push button the settings
page would only provide a field for a constant value for
the range parameter; you would not be given an opportunity
to change the default setting of the override parameter.
To change the default values assigned to parameters, use a
custom logic connection. See Connecting Features to Custom
Logic for information about making custom logic
connections.
4. Do one of the following:
Select the OK push button to apply the values and save them.
Select the Apply push button if you want to see what effect these
values have before saving them.
Select the Cancel push button to remove the notebook without saving
any of the parameter values you entered.
You can select Help for additional information about entering parameter
values.
Specifying defaults for parameters
There are two places in Visual Builder in which you can specify defaults for
the parameters of actions in the declaration of the action's member function:
In the part's .vbe file
On the Action page of the Part Interface Editor
Either of these allows a default value to be passed in an event-to-action
connection, thus avoiding the need to satisfy a parameter.
For example, suppose you want to connect the buttonClickEvent feature of a
Remove push button to a removeSelected action that you created for an
IListBox* part. Normally, you would also need to connect the selection
attribute of the subclassed IListBox* part to the index attribute of the
connection between buttonClickEvent and removeSelected. This connection would
be required to get the index of the selected item in the list box.
However, in the .vbe file of the IListBox* part, you can specify the following
default parameter value for the removeSelected action: //VBAction:
removeSelected, "removeSelected",, //VB: removeSelected(unsigned long
index=selection())
This means that if no attribute of the IListBox* part is connected to the
index attribute, the selection member function (the get member function of the
selection attribute) is called by default to provide the index of the selected
item.
You could do the same thing by creating a removeSelected action on the Action
page of the Part Interface Editor for the IListBox* part. You would specify
the default parameter in the declaration of the removeSelected member function
in the Action member function field, as follows: virtual unsigned long
removeSelected(unsigned long index=selection())
Missing or invalid parameters
When an action connection requires arguments, be sure that you make the
correct number of parameter connections. Also be sure that you make the
parameter connections before you generate the default code for your part. See
Manipulating Connections to learn how to re-order connections.
ΓòÉΓòÉΓòÉ 10.4. Connecting Features to Member Function Connections ΓòÉΓòÉΓòÉ
About connections between features and member functions
Adding an event-to-member function connection
Using Browser information
Personal notes:
ΓòÉΓòÉΓòÉ 10.4.1. About Connections Between Features and Member Functions ΓòÉΓòÉΓòÉ
A common use for member functions is with event-to-member function connections
and attribute-to-member function connections. These connections link an event
to a member function so that the member function is called when the event
occurs. Event-to-member function connections make this link directly from an
event to a member function connection. Attribute-to-member function connections
make this link indirectly using the attribute's event identifier, passing the
value of the attribute as the first parameter of the member function. The
member function that you connect the event or attribute to must belong to the
part being edited.
For example, suppose you are creating a composite part that consists of several
individual parts, such as a frame window, an entry field, a list box, and two
push buttons. In this case, you can connect the attributes and events of all
individual parts to a member function that belongs to the composite part that
you are editing.
When to connect attributes or events to member functions
How do you know when to connect an attribute or event to an action and when to
connect it to a member function? After all, an action is simply a member
function with a part interface. Therefore, it seems there should be little
difference between connecting to one and connecting to the other.
The difference is accessibility. Anyone can use actions that you include in
your part's interface, but only you can use the member functions that belong to
your part. When you create actions and include them in your part's interface,
other programmers who use your part can create their own event-to-action or
attribute-to-action connections using the actions that you have defined for the
part. That is the reason for including functions in the part's interface as
actions-to make them available to other programmers.
However, you may have functions that you want to invoke for your part without
including them in the part's interface. For example, your part may need to
perform a calculation internally whenever the value of an attribute changes.
However, another programmer who is using your part may not need to be aware
that this is happening. This is when you use member functions instead of
actions. By using event-to-member function connections and attribute-to-member
function connections, you can call these member functions when specific events
occur or when attribute values change, but no one else can.
ΓòÉΓòÉΓòÉ 10.4.2. Adding an Event-to-Member Function Connection ΓòÉΓòÉΓòÉ
The requirements for connecting an event to a member function are a visual part
that has at least one event specified for it, as well as at least one member
function.
The following figure shows the OAContractorView part used in the OASearch
sample application in this book. The steps for adding an event-to-member
function connection, which follow the figure, are based on this part. For
information about how to construct this part, see Adding Notebook Parts.
1. With the mouse pointer over the Clear push button, hold down the Alt key
and click mouse button 2.
Visual Builder displays the connection menu for the Clear push button.
2. From this menu, select the buttonClickEvent choice, an event.
3. Move the mouse pointer to a point on the free-form surface outside the
OAContractorView notebook part and click mouse button 1. Doing this
indicates to Visual Builder that you want to connect the event to the
OAContractorView notebook part instead of one of its subparts.
Visual Builder displays the connection menu with the preferred features
that have been defined for OAContractorView. The member function that you
want to connect your event to is not on this menu. Member functions are
not considered to be preferred features unless you define them as actions
in the Part Interface Editor.
4. Select More.
Visual Builder displays a window that contains three list boxes. The left
and middle boxes show the actions and attributes of the OAContractorView
notebook that you can connect the buttonClickEvent feature to. The third
list box is for events; this list box is empty because you cannot connect
one event, in this case buttonClickEvent, to another event.
Below the three list boxes is another section of the window titled Member
Function Connection. This is where you specify the member function that
you want to connect the buttonClickEvent feature to.
The For class field contains the class name of the part that you are
editing. This field is actually a drop-down list box. The list box is
initially empty. See the definition of the Browser pull-down menu item in
Browsing Part Information to find out how to display the names of the
classes that your part inherits from, as well as how to display the
member functions that your part contains in the list box at the bottom of
the window.
For this example, the For class field should contain OAContractorView,
the part that you are editing.
The Access field is another drop-down list box. This field is where you
specify the access level (public, protected, or private) for the member
functions that you want to see in the list. You must open the Browser
data to see a list of member functions. See Using Browser Information to
learn how to do this.
For this example, the Access field should contain public.
5. Type the member function to which the buttonClickEvent feature is to be
connected in the entry field below the Access field. Be sure to type the
full declaration of the member function, including return type and
parameters.
For this example, enter the following member function to clear all of the
fields in OAContractorView: void resetFields();
You must also create an .hpv file that contains this member function
declaration and a .cpv file that contains the code for this member
function. The member function declaration that you enter in this field
must be identical to the declaration that you put in the .hpv file. For
information about .hpv and .cpv files, see Specifying Files for Visual
Builder to Include When You Build Your Application
In addition, before you generate the code for your part, you must switch
to the Class Editor and enter the names of these files so that Visual
Builder will include them in the code for your part. For more information
about including these files, see Specifying Files for Visual Builder to
Include When You Build Your Application.
6. Select the OK push button.
The connection window disappears and a light green connection arrow is
drawn from the Clear push button toward the edge of the free-form
surface. It looks like this:
If the resetFields member function had parameters, the connection arrow
would be dashed instead of solid to give you a visual cue that you would
need to provide values for the parameters. For information about the
various ways to do this, see Satisfying Parameters for Incomplete
Connections.
ΓòÉΓòÉΓòÉ 10.4.3. Using Browser Information ΓòÉΓòÉΓòÉ
When connecting attributes or events to member functions, you might find it
helpful to see the classes and member functions in your inheritance tree, as
well as member functions that your part contains. You can get this information
by selecting FileBrowser when using any of the Visual Builder editors. This
menu choice provides access to a list of the classes that your part inherits
from.
You can use this list when you make attribute-to-member function and
event-to-member function connections. The window that Visual Builder displays
when you are making these connections contains a drop-down list box titled For
class. In this list box, you can select one of the classes that your part
inherits from. This causes Visual Builder to display a list of the member
functions that the class contains in another list box at the bottom of the
connection window.
The connection window is modal. Therefore, to display browser data in this
window, you must select the Open browser data menu choice before you begin the
connection. Otherwise, the For class drop-down list box contains only the class
name of your part, and the member function list box can display only the member
functions that your part contains.
The VisualAge C++ compiler generates the browser information when you have
compiled your application. Therefore, except for the Quick browse menu choice,
browser information is not available until after you compile your application.
The VisualAge C++ compiler stores the browser information in a file whose name
is based on the part name and whose extension is .pdb. To generate this file,
you must include the -Fb+ compiler option in your make file.
The cascaded menu that Visual Builder displays when you select FileBrowser
contains the following selections:
Quick browse
Causes Visual Builder to retrieve a list of the classes that the part you
are editing inherits from, as well as a list of the member functions that
your part and the part it inherits from contains. If you select one of the
classes in the list, Visual Builder retrieves a list of the member functions
that the class contains.
This function is available only if you start Visual Builder from a WorkFrame
project. It gives you access to browser information before you compile your
application.
Open browser data
Works the same as Quick browse except you must compile your application with
the -Fb+ option before using this function. Also, you do not have to start
Visual Builder from a WorkFrame project to use this function.
Refresh browser data
Refreshes the list of the classes that the part you are editing inherits
from, as well as the list that is displayed in the member function list box
for the current class. If you reparse a part or recompile your application,
use this function afterwards to ensure the data in the list boxes is
current.
Close browser data
Removes the list of the classes that the part you are editing inherits from,
as well as the member functions those classes contain.
ΓòÉΓòÉΓòÉ 10.5. Connecting Features to Custom Logic ΓòÉΓòÉΓòÉ
About connections between features and custom logic
Adding a custom logic connection
Personal notes:
ΓòÉΓòÉΓòÉ 10.5.1. About Connections Between Features and Custom Logic ΓòÉΓòÉΓòÉ
Custom logic connections enable you to connect small, specialized code snippets
to events and attributes. These connections link an event to your code so that
it is called when the event occurs. Custom logic connections that use events
make this link directly from an event to the custom logic; custom logic
connections that use attributes make this link indirectly using the attribute's
event identifier.
Use custom logic for unique logic requirements because the logic is stored as
part of the connection and is not reusable.
ΓòÉΓòÉΓòÉ 10.5.2. Adding a Custom Logic Connection ΓòÉΓòÉΓòÉ
The requirements for connecting an event or attribute to custom logic are a
visual part that has at least one event or attribute specified for it.
Following are the steps to follow for adding a custom logic connection. The
following figure shows the History page of the OAContractorView part used in
the OASearch sample application in this book. The example used in the following
steps is based on this part.
1. Select the right arrow in the lower right corner of the notebook to
display the History page.
2. With the mouse pointer over the Clear push button, hold down the Alt key
and click mouse button 2.
Visual Builder displays the connection menu for the Clear push button.
3. From this menu, select the buttonClickEvent choice, an event.
4. Move the mouse pointer to a point on the free-form surface outside the
OAContractorView part and click mouse button 1. Doing this indicates to
Visual Builder that you want to connect the event to the OAContractorView
part instead of one of its subparts.
Visual Builder displays the connection menu with the preferred features
that have been defined for the OAContractorView part.
5. Select Custom logic.
Visual Builder displays the following window:
6. Enter the following in the Description field:
Custom logic code to clear all entry fields
The Description field serves two purposes. After you complete the
connection, if you select the connection line Visual Builder displays the
text that you entered in this field in the information area at the bottom
of the Composition Editor. Also, when you generate the code for this
part, Visual Builder inserts a comment line that contains this
description.
7. The buttonClickEvent feature is the event you want to connect to your
custom logic, so do not change the Event name field for this example.
This field contains the event that you selected previously from the
connection menu. You can change this by selecting an event name from the
drop-down list box.
8. The default return type of void is the return type you want to use, so do
not change the Return type field for this example.
This field contains the return type for your custom logic. If you leave
void as the return type, your custom logic will have no return value. If
you want to pass a return value from your custom logic to another part, a
member function, or other custom logic, be sure to change the return type
to the type of data that you want to pass.
9. Select the Target push button.
Visual Builder inserts target-> in the Custom logic field.
The Custom logic field is a multiline entry field. This is where you
enter your custom logic. You can specify whether the code you enter here
is to effect the source part or the target part by selecting the Source
or Target push button before entering a line of code. You only need to
select one of these push buttons before entering the first line of a
group of lines.
In the generated code, the entry fields that we want to clear are created
using the new operator. For the StartEF part, the resulting pointer is
called iStartEF.
10. Type the following to the right of target->:
iStartEF->removeAll();
This code calls the removeAll member function for the StartEF part, the
entry field labeled OA Start Date.
11. Press the Enter key to move the cursor to a new line.
12. Select the Target push button again.
13. Type the following to the right of target->:
iEndEF->removeAll();
This code calls the removeAll member function for the EndEF part, the
entry field labeled OA End Date.
14. Press the Enter key to move the cursor to a new line.
15. Select the Target push button again.
16. Type the following to the right of target->:
iContractEF->removeAll();
and put the following line beneath it:
return;
This code calls the removeAll member function for the ContractEF part,
the entry field labeled Current Contract.
The connection window should now look like the following figure:
17. Select the Add push button.
The connection window disappears and a blue connection arrow is drawn
from the Clear push button toward the edge of the free-form surface. It
should look like this:
ΓòÉΓòÉΓòÉ 10.6. Connecting Exception Events to Actions and Member Functions ΓòÉΓòÉΓòÉ
In C++, an exception is any user, logic, or system error detected by a function
that does not deal with the error itself but passes the error on to a handling
routine, called an exception handler. In Visual Builder, you can catch
exceptions by connecting an exception event to either an action or a member
function.
An exception event is a feature of a connection, not a part. It is typically
connected to an IMessageBox* part, which is used to display an error message
associated with the exception.
To connect an exception event, do the following:
1. Use your favorite text editor to create an action or member function that
throws an exception.
The easiest way to do this is to include the following in your action or
member function source code:
throw IException("Error message.");
where the text of the error message that you want to display in the
message box is the only parameter given for the IException constructor.
For example, the following isEntryFieldEmpty member function uses the
strcmp function to check the contents of an entry field in a To-Do List
application. The application adds the contents of the entry field to the
to-do list whenever the user clicks the Add push button. If the entry
field is empty and the user clicks on Add, the member function throws an
exception, which consists of an error message.
void ToDoList::isEntryFieldEmpty()
{
if (strcmp(this->iEntryField->text(), "") == 0)
throw IException("Type a to-do item in the entry field
before selecting Add.");
}
2. Connect an event to the action or member function you just created.
The event that you connect here is the event for which you want to throw
an exception if an error occurs. In this example, you want to throw an
exception if the user clicks on Add when the entry field is empty.
Therefore, you would connect the buttonClickEvent feature on the Add push
button to the isEntryFieldEmpty member function.
3. Drop an IMessageBox* part on the free-form surface.
This message box is used to display the error message.
4. Move the mouse pointer to the connection you just made.
5. While holding down the Alt key, press mouse button 2.
6. Select the exceptionOccurred event from the connection menu.
7. Move the mouse pointer to the IMessageBox* part.
8. Click mouse button 1.
9. Select the show action from the connection menu.
This connection causes the application to show a message box that
contains the exception error message whenever the exception is thrown.
For an example using the OAContractorView part from the OASearch application,
see Passing Exceptions to Message Boxes.
ΓòÉΓòÉΓòÉ 10.7. Manipulating Connections ΓòÉΓòÉΓòÉ
Once a connection is made, you can manipulate it by doing the following:
Changing settings for a connection
Reordering connections
Deleting connections
Showing and hiding connections
ΓòÉΓòÉΓòÉ 10.7.1. Changing Settings for a Connection ΓòÉΓòÉΓòÉ
The settings window of a connection provides a way for you to select different
features as the source and target of the connection. If a member function is
the target of the connection, this window allows you to specify or select a
different member function as the target.
Note: If you are changing the settings of a connection whose target is a
member function, you might want the connection settings window to show
the classes that your part inherits from, as well as the member
functions that those classes contain. To display the class and member
function names, you must open the browser data before opening this
settings window. See See Browsing Part Information for information
about opening browser data.
To open the settings window for a connection, move the mouse pointer over the
connection and do one of the following:
Double-click mouse button 1.
Click mouse button 2 and select Open settings from the connection's
pop-up menu.
Visual Builder displays different connection settings windows depending on
whether the target of the connection is an attribute, action, or member
function. The following sections describe these three windows.
Changing settings when an attribute is the target
Changing settings when an action is the target
Changing settings when a member function is the target
ΓòÉΓòÉΓòÉ 10.7.1.1. Changing Settings for Attribute-to-Attribute Connections ΓòÉΓòÉΓòÉ
The following figure shows the window that Visual Builder displays when you
open the settings window for an attribute-to-attribute connection:
The connection settings window for an attribute-to-attribute connection
contains two columns of attributes. The left column contains the attributes
that belong to the source part. The right column contains the attributes that
belong to the target part.
To change the attribute to be used as either the source or target of the
connection, select an attribute from the list.
This connection settings window has the following push buttons:
OK
Removes the connection settings window and puts any changes made into
effect.
Reverse
Reverses the order of the connection; the source part becomes the target and
the target part becomes the source.
Delete
Deletes the connection.
Cancel
Removes the connection settings window without putting any changes into
effect.
Help
Provides helpful information about the window.
ΓòÉΓòÉΓòÉ 10.7.1.2. Changing Settings When an Action Is the Target ΓòÉΓòÉΓòÉ
When you open a settings window for a connection whose target is an action,
Visual Builder displays the following window:
The connection settings window contains two columns of features. The features
in the left column belong to the source part; these features are the same type
of feature as the one currently selected for the source part. For example, if
the feature selected for the source part is an event, this column contains a
list of the events that belong to the source part.
Likewise, the features in the right column belong to the target part; these
features are all actions or attributes that have set member functions.
The entry fields above each list contain the names of the features that are
currently selected. To change the feature to be used as either the source or
target of a connection, select a feature from the list.
This connection settings window has the following push buttons:
OK
Removes the connection settings window and puts any changes made into
effect.
Cancel
Removes the connection settings window without putting any changes into
effect.
Delete
Deletes the connection.
Set parameters
Opens another window in which you can specify a constant parameter value for
each parameter the action has.
Help
Provides helpful information about the window.
ΓòÉΓòÉΓòÉ 10.7.1.3. Changing Settings When a Member Function Is the Target ΓòÉΓòÉΓòÉ
Two types of connections can use a member function as the target:
attribute-to-member function and event-to-member function connections. The
following figure shows a settings window for an event-to-member function
connection:
The Event name or Attribute name field
The Event name field shows the name of the event that is connected to the
member function. If this was an attribute-to-member function connection, this
field would be the Attribute name field and would contain an attribute name.
To change this name, select an attribute or event from the drop-down list box
below the entry field.
The For class field
The For class field shows the name of the class that the target member function
belongs to. This field can contain either the class name of the part that you
are editing or the class name of a part that the part you are editing inherits
from.
To change this class name, select a class name from the drop-down list box
below the entry field if you opened the browser data before opening this
window.
The Access field and member function list
The Access field shows the current access type, which is either public,
protected, or private. Member functions of this access type that belong to the
class shown in the For class field are displayed in the list box at the bottom
of the window. These member function names are displayed only if you opened the
browser data before opening this window. The list includes the currently
selected member function, which is shown in the entry field above the list.
To change the access type, do one of the following:
Move the mouse pointer over the Access field, click mouse button 1, and
type the letter p.
Each time you type the letter p, the next access type appears. For
example, if the entry field contains public, typing the letter p causes
protected to appear.
Select an access type from the drop-down list box.
To change the member function that is used for the connection, do one of the
following:
Type a different member function in the entry field.
Select a member function from the list displayed below the entry field if
you opened the browser data before opening this window.
The push buttons
The connection settings window for member functions has the following push
buttons:
OK
Removes the connection settings window and puts any changes made into
effect.
Cancel
Removes the connection settings window without putting any changes into
effect.
Delete
Deletes the connection.
Set parameters
Opens another window in which you can specify a constant parameter value for
each parameter the member function has.
Help
Provides helpful information about the window.
ΓòÉΓòÉΓòÉ 10.7.1.4. Changing Settings When Custom Logic Is the Target ΓòÉΓòÉΓòÉ
The following figure shows a settings window for a custom logic connection:
The fields in this window are the same as those used to create the connection.
See Adding a Custom Logic Connection for information about these fields and
push buttons.
The only push button that differs on this window is the Update push button. Use
this push button to save any changes you make and close the window.
ΓòÉΓòÉΓòÉ 10.7.2. Reordering Connections ΓòÉΓòÉΓòÉ
If you make several connections from the same part, they run in the order in
which you made the connections. To ensure the correct flow of control when you
generate the source code, you may need to reorder the connections. If so, do
the following:
1. Select the source part.
2. From the source part's pop-up menu, select Reorder Connections From.
Visual Builder displays the Reorder Connections window showing a list of
your connections.
3. With the mouse pointer over the connection you want to reorder, press and
hold mouse button 2.
4. Drag the connection to the place in the list where you want the
connection to occur.
5. Release mouse button 2.
6. Repeat these steps until the connections are listed in the order in which
you want them to occur.
7. Close the window.
ΓòÉΓòÉΓòÉ 10.7.3. Deleting Connections ΓòÉΓòÉΓòÉ
You can delete a connection in either of the following ways:
From the connection's pop-up menu.
Note: You do not have to select a connection to delete it using this
method.
To delete a connection from its pop-up menu, do the following:
1. Click on the connection with mouse button 2 to display its pop-up
menu.
2. Select Delete.
From the connection's settings window
To delete a connection from its settings window, do the following:
1. Open the settings window for the connection by doing one of the
following:
- Double-clicking on the connection
- Clicking on the connection with mouse button 2 to display its
pop-up menu and selecting Open Settings
2. Select the Delete push button.
ΓòÉΓòÉΓòÉ 10.7.4. Showing and Hiding Connections ΓòÉΓòÉΓòÉ
You can show and hide connections by using , the Hide Connections tool, and ,
the Show Connections tool on the Tool bar. These tools show or hide all
connections that have the selected part or parts as their source or target. If
no parts are selected, these tools show or hide all of the connections.
If you hide connections, the Composition Editor free-form surface is
drawn faster and is less cluttered, making it easier for you to
work.
If no parts are selected, these tools show and hide all of the connections in
the view. If a part or parts are selected, these tools show and hide the
connections between the selected part or parts.
Another way to show and hide connections is to move the mouse pointer over a
part, click mouse button 2, and select the Browse Connections choice from the
part's pop-up menu, which displays a cascaded menu. The choices in the menu
affect only connections going to and from the part the mouse pointer was over
when you displayed the pop-up menu.
The Browse Connections cascaded menu contains the following choices:
Show To
Shows all connections for which the part is the target.
Show From
Shows all connections for which the part is the source.
Show To/From
Shows all connections for which the part is either the source or the target.
Show All
Shows all connections that have been made, regardless of where the mouse
pointer is when you click mouse button 2.
Hide To
Hides all connections for which the part is the target.
Hide From
Hides all connections for which the part is the source.
Hide To/From
Hides all connections for which the part is either the source or the target.
Hide All
Hides all connections that have been made, regardless of where the mouse
pointer is when you click mouse button 2.
ΓòÉΓòÉΓòÉ 10.8. Rearranging Connections ΓòÉΓòÉΓòÉ
You can rearrange a connection by doing the following:
Selecting connections
Deselecting connections
Changing the source and target of connections
ΓòÉΓòÉΓòÉ 10.8.1. Selecting Connections ΓòÉΓòÉΓòÉ
You select connections in the same way that you select parts. When you select a
connection, three boxes called selection handles appear on it to show that it
is selected: one at each end and one in the middle. You can use these boxes to
change either of the following:
The end points of the connection, as described in Changing the Source and
Target of Connections.
The shape of the connection arrow by dragging the middle box to another
location. This helps you distinguish among several connection lines that
are close together.
Selecting a single connection
1. Move the mouse pointer over the connection you want to select.
2. Click mouse button 1 to select the connection.
The connection is selected.
Selecting multiple connections
If you want to select several connections, do one of the following:
To select multiple connections using just the mouse, do the following:
1. Move the mouse pointer over one of the connections you want to
select.
2. Hold down mouse button 1 instead of clicking it.
3. Move the mouse pointer over each connection that you want to select.
The selection boxes appear on each connection that the mouse pointer
passes over to show they are selected.
4. After the connections are selected, release mouse button 1.
To select multiple connections using both the mouse and the keyboard, do
the following:
1. Hold down the Ctrl key.
2. Move the mouse pointer over a connection.
3. Click mouse button 1 while the mouse pointer is over the connection
line.
4. Without releasing the Ctrl key, repeat the preceding steps until all
connections that you want to select are selected.
ΓòÉΓòÉΓòÉ 10.8.2. Deselecting Connections ΓòÉΓòÉΓòÉ
If you want to deselect a connection without selecting another part or
connection, do the following:
1. Move the mouse pointer over the connection line.
2. Hold down the Ctrl key.
3. Click mouse button 1.
ΓòÉΓòÉΓòÉ 10.8.3. Changing the Source and Target of Connections ΓòÉΓòÉΓòÉ
Visual Builder gives you the ability to change what a connection is pointing to
(the target) or pointing from (the source). Of course, you could always just
delete the connection and create a new one. However, the following steps show
you a quicker way to do this.
To move either end of a connection, do the following:
1. Select the connection.
2. Move the mouse pointer over either selection handle that appears on the
ends of the connection.
3. Press and hold mouse button 2.
4. Move the mouse pointer to the new part or connection.
5. Release the mouse button.
Depending on the connection type, you may get a pop-up menu asking you for new
information for the connection.
What you can change
You can change the source and target of either end of any connection. However,
depending on the feature that you connect to when you make the change, you
might get a different type of connection than the one you started with.
The following table gives you a closer look at the connection types and what
you can change without changing the connection type:
ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
ΓöéConnection type ΓöéMove either end ΓöéMove source end ΓöéMove target end Γöé
Γöéattribute-to-attribute Γöéx Γöé Γöé Γöé
Γöéattribute-to-member function Γöé Γöéx Γöé Γöé
Γöéattribute-to-action Γöéx Γöé Γöé Γöé
Γöéevent-to-action Γöéx Γöé Γöé Γöé
Γöéevent-to-attribute Γöéx Γöé Γöé Γöé
Γöéevent-to-member function Γöé Γöéx Γöé Γöé
Γöécustom logic Γöéx Γöé Γöé Γöé
Γöéparameter connection Γöéx Γöé Γöé Γöé
ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
ΓòÉΓòÉΓòÉ 10.9. Making Connections for the OASearch Application ΓòÉΓòÉΓòÉ
The following sections show you how to connect the parts that were used to
create a GUI for the OAContractView part in Constructing a GUI: the OASearch
Application
Enabling push buttons when an entry field contains a value
Enabling a window to be cleared of all entry values
Connecting the variable part
Passing exceptions to message boxes
Personal notes:
ΓòÉΓòÉΓòÉ 10.9.1. Enabling Push Buttons When an Entry Field Contains a Value ΓòÉΓòÉΓòÉ
This section shows you how to make the connections that enable the Refresh and
Save push buttons in the OAContractView window. When you have made these
connections, the window appears as shown in the following figure:
Follow these steps to enable the push buttons:
1. From the Account Number pop-up menu, select Connect.
2. Select text from the list.
3. Click on the Refresh push button.
4. Select enabled from the pop-up menu.
This connection means that the Refresh push button will only be enabled
whenever the contents of the Account Number text changes, whether by
typing text in it or by another connection. Here, you use an
attribute-to-action connection because you want the enabled action to
occur whenever the value of the text attribute changes.
5. Follow the same procedure to connect the text attribute of the Account
Number text part to the enabled attribute of the Save push button part.
ΓòÉΓòÉΓòÉ 10.9.2. Enabling a Window to be Cleared of All Entry Values ΓòÉΓòÉΓòÉ
You can enable the Clear push button to empty all entry fields of their
contents using more than one method. One way would be to connect the
buttonClickEvent feature of the Clear push button to the removeAll action of
each entry field in the window. Another way would be to connect the
buttonClickEvent feature of the Clear push button to a resetFields member
function of the OAContractView composite part.
For this example, assume that the member function has been written. Make the
connection as follows:
1. From the Composition Editor, use Alt-mouse button 2 to select the
buttonClickEvent of the Clear push button.
The connection spider appears.
2. Use Alt-mouse button 2 to select an empty section of the free-form
surface.
3. Select More from the pop-up menu.
4. Enter the member function declaration in the entry field as shown in the
following figure:
5. Select the OK push button.
6. Switch to the Class Editor.
Include the files containing the member function code. For this example,
the file names are oafwclr.cpv and oafwclr.hpv.
a. In the User .hpv file field, type the name of the header file,
oafwclr.hpv
b. In the User .cpv file field, type the name of the code file,
oafwclr.cpv
For details on the attributes, actions, or events of a particular part, refer
to the Visual Builder Parts Reference. For more information on how to perform
these operations, see Making the Connections.
ΓòÉΓòÉΓòÉ 10.9.3. Connecting the Variable Part ΓòÉΓòÉΓòÉ
Once you have added the variable to the free-form surface and set its name and
type, you need to connect it to the OAContractView composite part.
Making the attribute-to-attribute connections
So that recruiters can display and update contract information held by the
Contract variable, you must make attribute-to-attribute connections between the
composite visual part and the Contract variable as follows:
From part, feature To part, feature
Contract,#accountNum EntryField1,#text
Contract,#companyName EntryField2,#text
Contract,#projectMgr EntryField3,#text
Contract,#deptName EntryField4,#text
Contract,#positionTitle EntryField5,#text
Contract,#startDate EntryField6,#text
Contract,#endDate EntryField7,#text
Contract,#currContractor EntryField8,#text
So far, the connections appear as shown in the following figure:
Making the event-to-action connections
To enable push buttons on the composite visual part, you must make
event-to-action connections. This is a two-step process, because you specified
an input parameter for each of the data access actions. First, connect each
push button to the Contract variable. The connection line appears dashed,
indicating an incomplete connection. Next, connect the attribute that
represents the input parameter to the event-to-action connection itself.
For this example, make the following connections:
From part, feature To part, feature
PushButton1,#buttonClickEvent Contract,#getContract
EntryField1,#text (Account Number text) The anAccountNum parameter of the
PushButton1,#buttonClickEvent-->
Contract,#getContract connection.
Visual Builder draws the parameter
connection in the opposite
direction.
PushButton2,#buttonClickEvent Contract,#putContract
EntryField1,#text (Account Number text) The anAccountNum parameter of the
PushButton2,#buttonClickEvent-->
Contract,#putContract connection.
Visual Builder draws the parameter
connection in the opposite
direction.
The connections now appear as shown in the following figure:
The putContract and getContract actions throw exceptions when the account
number is not found in the database.
The next step is passing the exception to a message box.
ΓòÉΓòÉΓòÉ 10.9.4. Passing Exceptions to Message Boxes ΓòÉΓòÉΓòÉ
You can trigger the display of a message box when an exception is thrown.
Although a message box is a user-interface element, Visual Builder treats
message boxes as nonvisual parts.
Adding the message box
To add a message box to the free-form surface, select , the Other category,
from the parts palette; then add , an IMessageBox* part, to the free-form
surface.
Making the connections
Now, connect the exceptionOccurred event of each event-to-action connection to
the showException action of the message box.
The connections appear as shown in the following figure. Save and close your
visual part.
ΓòÉΓòÉΓòÉ 11. Displaying Objects in a List Box ΓòÉΓòÉΓòÉ
The following steps show you how to modify the original To-Do List application
to use objects instead of text strings. If you have not already done so, please
complete the original application, shown in Creating a Simple Visual Builder
Application, before continuing with this example.
Introduction
Copying the ToDoList part
Creating the ToDoItem nonvisual part
Replacing and modifying the list box
Placing and modifying an IVBFactory* part
Placing and modifying an IVSequence* part
Making the new connections
Generating the source code for your visual part and main() procedure
Building and running the modified application
Personal notes:
ΓòÉΓòÉΓòÉ 11.1. Introduction ΓòÉΓòÉΓòÉ
In Creating a Simple Visual Builder Application, you use an IListBox* part to
display the items in a to-do list. The items that you put in the IListBox* part
are text strings that you create by entering them in an entry field and
clicking on a push button. In this case, the text strings displayed in the list
box are just text strings.
Besides viewing a list of text strings, you can also use a list box to view a
collection of nonvisual objects. List boxes that can display objects include
the following:
ICollectionViewListBox*
ICollectionViewComboBox*
By connecting a collection of objects, such as an IVSequence* part, to one of
these list boxes, you can view a collection of objects instead of simple text
strings.
The procedure outlined in this section modifies the original To-Do List
application so that the list box contains objects rather than text strings. In
this case, text strings are again displayed in the list box, but this time
they are used to show the names of the objects in the sequence. When you
select an item in the list box after completing this procedure, you are really
selecting an object in the sequence, not the text string that represents the
object.
The modified To-Do List application differs from the original application in
that it uses the following parts:
An ICollectionViewListBox* part instead of an IListBox* part.
The ICollectionViewListBox* part can contain objects instead of just text
strings.
An IVBFactory* part.
The IVBFactory* part creates new objects to put in the list box.
An IVSequence* part.
The IVSequence* part contains the sequence of objects that is reflected
in the list box.
A ToDoItem part.
ToDoItem is a nonvisual part that is used as the type of objects that the
list box and sequence will contain, and that the object factory will
create.
The following prerequisites must be met to reflect a sequence of objects in a
list box:
The class name of the type of objects in the list box and sequence, as
well as the type of objects that the object factory creates, must be the
same. This class name must also be the name of a part that inherits from
IStandardNotifier. It does not have to inherit from IStandardNotifier
directly, but IStandardNotifier must be somewhere above it in its class
hierarchy.
The objects in the sequence must override the asString member function
inherited from the IVBase part. This is necessary so that at least one
attribute of each object, such as the object's name, can be displayed in
the list box.
In the procedure that you will follow for the To-Do List application, the
ToDoItem nonvisual part has its own asString member function. This member
function overrides the asString member function of IVBase by calling the
toDoItemName attribute's get member function, which returns the name of
the to-do item, as follows:
IString ToDoItem :: asString () const
{
return toDoItemName();
}
ΓòÉΓòÉΓòÉ 11.2. Copying the ToDoList Part ΓòÉΓòÉΓòÉ
First, you must copy the ToDoList part, as follows:
1. Select todolist.vbb.
Visual Builder displays the name of the ToDoList part in the Visual Parts
list box.
2. Select the ToDoList part.
3. Select PartCopy.
Visual Builder displays the Copy Part window.
4. Enter ToDoLst2 in the Target part name field.
5. Enter todolst2.vbb in the Target file name field.
6. Select the Copy push button.
Visual Builder creates a copy of the ToDoList part, gives it the name
ToDoLst2, and stores it in the todolst2.vbb file.
ΓòÉΓòÉΓòÉ 11.3. Creating the ToDoItem Nonvisual Part ΓòÉΓòÉΓòÉ
The next step is to create a nonvisual part called ToDoItem, as follows:
1. Open a new nonvisual part by doing the following:
a. In the Visual Builder window, select PartNew.
Visual Builder displays the Part - New window.
b. Fill in the fields in this window as follows.
Class name ToDoItem
Description Type of objects in To-Do List
File name ToDoLst2.vbb
Part type Nonvisual part
Base class IStandardNotifier
c. Select the Open push button.
Visual Builder displays the Part Interface Editor.
2. Create a new attribute called toDoItemName by doing the following:
a. On the Attribute page, fill in the following fields:
Attribute name toDoItemName
Attribute type IString
b. Select the Add with defaults push button.
Visual Builder adds the toDoItemName attribute to the ToDoItem part.
You can add the toDoItemName attribute to the preferred
features list so that it will be readily available for
making connections by doing the following:
a. Switch to the Part Interface Editor.
b. Select the Preferred page.
c. Scroll down the list of attributes until you find the
toDoItemName attribute and select it.
d. Select the Add>> push button.
Visual Builder adds the toDoItemName attribute to the
list of preferred features so that it will appear in
the pop-up connection menu.
3. Specify the .hpv and .cpv files for Visual Builder to use for the default
feature code for the toDoItemName attribute by doing the following:
a. Switch to the Class Editor if you followed the steps in the
preceding hint.
b. Fill in the following fields:
User .hpv file ToDoItem.hpv
User .cpv file ToDoItem.cpv
4. Generate the default source and feature code for the ToDoItem part by
doing the following:
a. Select FileSave and generatePart source.
Visual Builder generates the code for the ToDoItem part and stores
it in files named ToDoItem.hpp and ToDoItem.cpp. These files contain
the appropriate include statements for the ToDoItem.hpv and
ToDoItem.cpv files.
b. Select FileSave and generateFeature source
Visual Builder generates the default code for the toDoItemName
attribute and stores it in the ToDoItem.hpv and ToDoItem.cpv files.
5. Override the asString member function in the IVBase* part by doing the
following:
a. Using your favorite text editor, edit the ToDoItem.hpv file and
insert the following at the bottom of the public section:
IString ToDoItem :: asString () const;
b. Save the file.
c. Edit the ToDoItem.cpv file and insert the following at the bottom of
the file:
IString ToDoItem :: asString () const
{
return toDoItemName();
}
d. Save the file and close the text editor.
6. Close the Part Interface Editor.
The ToDoItem part is now completed.
ΓòÉΓòÉΓòÉ 11.4. Replacing and Modifying the List Box ΓòÉΓòÉΓòÉ
You need a list box that can display objects instead of just text strings, so
next you must replace the IListBox* part with an ICollectionViewListBox* part,
and then modify the ICollectionViewListBox* part to specify the type of objects
it can display.
Replacing IListBox* with ICollectionViewListBox*
1. Open the ToDoLst2 part.
2. Delete the IListBox* part.
The IListBox* part only accepts strings. You want a part that accepts
objects.
Visual Builder displays a message warning you that it will delete the
connections as well as the list box if you continue. You want to delete
the connections because you need different connections for this example.
3. Select the OK push button.
Visual Builder deletes the list box and the connections.
4. Select , the Lists category, from the row of icons on the left-hand side
of the parts palette.
5. Select , the ICollectionViewListBox* icon, from the row of icons that
Visual Builder displays on the right-hand side of the parts palette.
6. Place the crosshairs below the bottom left corner of the second static
text part and click mouse button 1.
A list box part that displays the items in a collection is placed beneath
the second static text part.
Specifying the type of items the list box can contain
1. Move the mouse pointer to the list box, click mouse button 2, and select
Open Settings.
Visual Builder displays the settings notebook for the list box.
2. Enter ToDoItem* in the Class name of items field.
3. Select the OK push button.
The list box can now accept only ToDoItem* objects.
ΓòÉΓòÉΓòÉ 11.5. Placing and Modifying an IVBFactory* Part ΓòÉΓòÉΓòÉ
You need an IVBFactory* part to create the objects to be displayed in the list
box. In addition, you must specify the type of objects the IVBFactory* part can
create.
Placing an IVBFactory* part on the free-form surface
1. Select , the Models category, from the row of icons on the left-hand side
of the parts palette.
2. Select , the IVBFactory* icon, from the row of icons that Visual Builder
displays on the right-hand side of the parts palette.
3. Place an object factory part on the free-form surface to the right of the
To-Do List window adjacent to the entry field.
4. Change the text beneath the object factory icon to ItemFactory.
Specifying the type of objects the object factory can create
1. Move the mouse pointer to the object factory, click mouse button 2, and
select Change Type.
Visual Builder displays a window in which you are to enter the type of
objects that the object factory is to create.
2. Enter ToDoItem* in the entry field in this window.
3. Select the OK push button.
The object factory can now create only ToDoItem objects.
ΓòÉΓòÉΓòÉ 11.6. Placing and Modifying an IVSequence* Part ΓòÉΓòÉΓòÉ
You also need to place an IVSequence* part to put the objects that the
IVBFactory* part creates into a sequence; you must also specify the type of
objects the sequence can contain.
Placing an IVSequence* part on the free-form surface
1. Select OptionsAdd part.
Visual Builder displays the Add part window.
2. Enter ItemSequence in the Name field.
3. Enter IVSequence* in the Part class field.
4. Select the Add push button.
5. Place an IVSequence* part on the free-form surface surface to the right
of the To-Do List window adjacent to the list box.
Specifying the type of objects in the sequence
1. Move the mouse pointer to the sequence, click mouse button 2, and select
Open Settings.
Visual Builder displays the settings notebook for the sequence.
2. Enter ToDoItem* in the Class name of items field.
3. Select the OK push button.
The sequence can now accept only ToDoItem objects.
ΓòÉΓòÉΓòÉ 11.7. Making the New Connections ΓòÉΓòÉΓòÉ
The following steps describe the connections that this example requires to add
objects to and remove objects from the list box. To review the instructions for
connecting features, see Making the Connections.
1. Connect the buttonClickEvent feature of the Add push button to the new
action of the object factory.
This connection causes the object factory to create a new ToDoItem object
whenever a user clicks the Add push button.
2. Connect the toDoItemName attribute of the object factory to the text
attribute of the entry field.
This connection causes text in the entry field to be used as the name of
ToDoItem objects that the object factory creates. Notice that the
connection line is violet, the color of a parameter connection, instead
of cyan, which is the color of an attribute-to-attribute connection. The
connection line is violet because the text attribute of the entry field
supplies a value for the toDoItemName attribute only when the object
factory creates a new object, just as if it were satisfying a parameter
of the new action.
3. Connect the newEvent attribute of the object factory to the addAsLast
action of the sequence.
This connection causes each new ToDoItem object to be added as the last
object in the sequence.
4. Connect the this attribute of the sequence to the items attribute of the
list box.
This connection causes the list box to display all of the ToDoItem
objects that the sequence contains.
5. Connect the buttonClickEvent feature of the Remove push button to the
removeAtPosition action of the sequence.
This connection causes the object at a specified position in the sequence
to be removed. This connection is incomplete because the removeAtPosition
action's position parameter must be satisfied.
6. Connect the position parameter of the previous connection to the
selectedCollectionPosition attribute of the list box.
This connection provides the position of the selected item in the
collection of objects, which is required by the previous connection in
order to remove an object.
ΓòÉΓòÉΓòÉ 11.8. Generating the Source Code for Your Visual Part and main() Procedure ΓòÉΓòÉΓòÉ
To generate the C++ source code for your visual part, select FileSave and
GeneratePart source. Visual Builder generates the following files in the
working directory:
todolst2.cpp The C++ code for your todolst2 part.
todolst2.hpp The C++ header file for your todolst2 part.
todolst2.h The resource header file for your todolst2.cpp file.
todolst2.rc The resource file for your todolst2.cpp file.
Generating the source code for your main() procedure
To generate the source code for your main() procedure, select FileSave and
Generatemain() for part. Visual Builder generates the following files in the
working directory:
todolst2.app The main function for your application.
Note: If you start Visual Builder from a WorkFrame project,
the name of this file is vbmain.cpp.
todolst2.mak The make file that you specify when you build your application.
Note: You must select OptionsGenerate make files in the
Visual Builder window to generate this file.
ΓòÉΓòÉΓòÉ 11.9. Building and Running the Modified Application ΓòÉΓòÉΓòÉ
You should now be ready to build and run your modified To-Do List application,
as follows:
Building the new To-Do List application
1. Open an OS/2 window.
2. Change to your Visual Builder working directory.
3. Enter the following command:
nmake todolst2.mak
This command produces the following files:
todolst2.exe The executable file for your application.
todolst2.map The application configuration map.
todolst2.o The object file for your application.
Note: If you start Visual Builder from a WorkFrame
project, the name of this file is vbmain.obj.
todolst2.obj The object file for your part. Visual Builder
provides a separate object module for your part that
is used when compiling this part with other parts.
todolst2.res The binary resource file that is bound to
todolst2.exe.
Running the new To-Do List application
To run your application from the same OS/2 command prompt from which you
entered the nmake command, enter the following:
todolst2
Once your application is running, experiment with it to make sure it works as
you designed it. That is all there is to it!
You can add a finishing touch to your application by creating an OS/2 program
object. Create a program object from the OS/2 Templates folder, specifying the
name todolst2.exe as the program name and the directory that contains
todolst2.exe as the working directory. Once you have done this, you can run
your application by simply double-clicking on the program object you just
created.
ΓòÉΓòÉΓòÉ 12. Creating Resizable Windows ΓòÉΓòÉΓòÉ
What you will achieve
What are the benefits of using multicell canvases?
Adding a multicell canvas
Adding parts to the multicell canvas
Changing the multicell canvas grid
Extending a part to span more than one cell
Adding a group box
Changing the settings for a multicell canvas
Personal notes:
ΓòÉΓòÉΓòÉ 12.1. What You Will Achieve ΓòÉΓòÉΓòÉ
The purpose of this chapter is to show you how to use multicell canvases to
build a window that can be resized dynamically.
All visual parts of the OASearch sample application except OAContractorView use
multicell canvases as client areas. (OAContractorView uses multicell canvases
as notebook page clients.) The example built in this chapter is based on the
following figure:
For the finished panel, see the OAContractView part in oawin.vbb.
ΓòÉΓòÉΓòÉ 12.2. What Are the Benefits of Using Multicell Canvases? ΓòÉΓòÉΓòÉ
Because multicell canvases are dynamically resizable, they are the best canvas
choice for applications that will be used in a variety of display resolutions.
Using multicell canvases also makes it easier to plan for translation of your
interface into other languages.
Multicell canvases contain rows and columns of cells into which you can drop
parts. Cells are referred to by row and column location: the cell at row 2,
column 3 is called cell (2,3). Each cell is initially very small, 10 pixels
wide and 10 pixels high. A grid of 5 rows and 5 columns appears when you first
drop a multicell canvas into a client area.
Any extra space between the grid and the bounds of the client area appears to
the right of the rightmost grid line and below the bottommost grid line. This
extra space is called the expansion area. The expansion area can also change
size at run time when the user resizes the window.
When you drop a visual part into the cell, the cell resizes to fit the minimum
size of the dropped part. This minimum size is calculated for you based on
limits that are set for the dropped part.
For example, suppose you want an entry field that holds 10 characters. You drop
the part and use the settings notebook to set its limit to 10 characters. The
minimum size of the entry field is then calculated based on holding 10
characters of the font defined for the entry field.
The minimum size of a cell also depends on the size of parts that span the cell
but are not contained within it. For specific examples of how layout influences
minimum size, refer to the sample visual parts contained in oawin.vbb.
Rows and columns are either fixed or expandable, depending on how their size is
calculated.
The size of a fixed row or column is based on the minimum size of the
largest cell in that row or column. If no part occupies a cell in that
row or column, the row or column takes the default minimum size.
Expandable rows or columns can grow from their minimum size (the same as
if their size were fixed) to include the expansion area. If two or more
expandable rows or columns exist, the expansion area is parceled out
among them. Examples of the use of expandable columns appear in
oawin.vbb.
When first created, all rows and columns have a fixed size. To make them
expandable, edit the settings for the multicell canvas. For more information,
see Changing the Settings.
Working with multicell canvases does not require the Visual Builder alignment
tools. You alternate between the free-form surface and the settings notebook
for the multicell canvas. Begin by adding a multicell canvas.
ΓòÉΓòÉΓòÉ 12.3. Adding a Multicell Canvas ΓòÉΓòÉΓòÉ
This example is based on OAContractView, found in oawin.vbb.
1. Because you are constructing a new user interface, begin by creating a
visual part. Call it contractView.
When you create a visual part, the Composition Editor opens and an
IFrameWindow* part is automatically added for you. By default, the client
area of the IFrameWindow* part appears as a canvas.
2. Delete the default canvas client.
3. Select , the Composers category, from the left side of the parts palette.
4. Select , the IMultiCellCanvas* part, from the right side of the parts
palette and drop it on the IFrameWindow* part.
Your visual part now looks like the following figure:
The next step is adding parts to the multicell canvas.
ΓòÉΓòÉΓòÉ 12.4. Adding Parts to the Multicell Canvas ΓòÉΓòÉΓòÉ
When you first drop a multicell canvas, the cell grid appears at its default
size in the upper-left corner of the client area. You can now drop parts into
the canvas. For the contractView example, do the following:
1. Select , the Data Entry category, from the left side of the parts
palette.
2. Select , the IStaticText* part, from the right side of the parts palette.
When you move the mouse pointer over the free-form surface, the pointer
changes to crosshairs.
3. Drop the part at cell (2,2) of the multicell canvas.
Row 1 was left as a spacer between the top of the multicell canvas and
the window border. When you drop the IStaticText* part, cell (2,2)
expands to contain the dropped part. The multicell canvas now looks like
the following figure:
4. Drop another IStaticText* part at cell (4,2), leaving row 3 as a spacer.
The multicell canvas now looks like the following figure:
5. Drop two more IStaticText* parts into the expansion area below the
StaticText2 part.
Each time you drop a part into the expansion area, a new row is created
for you.
6. Drop three more IStaticText* parts in column 3 as shown in the following
figure:
No spacer rows exist yet between these new rows. We will add these in
Adding Rows or Columns. Now add some IEntryField* parts.
7. Select , the Data Entry category, from the left side of the parts
palette.
8. Select , the IEntryField* part, from the right side of the parts palette.
9. Drop IEntryField* parts in the expansion area to the right of the
IStaticText* parts, starting at row 2. A new column 6 is created, as
shown in the following figure:
ΓòÉΓòÉΓòÉ 12.5. Changing the Multicell Canvas Grid ΓòÉΓòÉΓòÉ
You can add or delete rows or columns from a multicell canvas as follows:
To add rows or columns from the expansion area, you can just drop parts
into it, as discussed in Adding Parts to the Multicell Canvas.
To add several rows or columns at a time, you might find it easiest to
change the grid using the multicell canvas's settings notebook. This
method is discussed in Changing the Multicell Canvas Grid Using the
Settings Notebook.
With the multicell canvas selected, you can press mouse button 2 and use
the contextual menu. For more information on this method, see the
following:
- Adding Rows or Columns Using the Contextual Menu
- Deleting Rows or Columns Using the Contextual Menu
ΓòÉΓòÉΓòÉ 12.5.1. Adding Rows or Columns Using the Contextual Menu ΓòÉΓòÉΓòÉ
You can add rows or columns anywhere on the multicell canvas as follows:
1. Select a cell next to where you want to add the row or column.
Note: No selection handles are shown on the cell if it is empty. Also,
you can only open the contextual menu for an empty cell.
2. Press mouse button 2 to open the contextual menu.
3. To add a row, select Rows. To add a column, select Columns.
A cascade menu appears.
4. If you want to insert the row above the cell you selected, select Add row
before from the cascade menu.
If you want to insert the row below the cell you selected, select Add row
after from the cascade menu.
For columns, Add column before inserts a column to the right of the
selected cell. Add column after inserts a column to the left of the
selected cell.
For practice, add spacer rows to the contractView example as follows:
1. Select the empty cell to the left of StaticText3. Add a row after it.
2. Add one row each after StaticText4 through StaticText7.
At this point, the contractView window looks like the following figure:
ΓòÉΓòÉΓòÉ 12.5.2. Deleting Rows or Columns Using the Contextual Menu ΓòÉΓòÉΓòÉ
You can delete rows or columns from anywhere on the multicell canvas as
follows:
1. Select a cell in the row or column you want to delete.
2. Press mouse button 2 to open the contextual menu.
3. To delete the row, select Rows. Then select Delete row.
To delete the column, select Columns. Then select Delete column.
ΓòÉΓòÉΓòÉ 12.6. Extending a Part to Span More than One Cell ΓòÉΓòÉΓòÉ
Parts can span more than one column or row. This is necessary when placing a
part entirely within one cell would distort the multicell canvas. Consider what
happens when you add three push buttons individually to the sample multicell
canvas, as shown in the following figure:
Clearly, this was not intended. Instead, build a deck of push buttons using an
ISetCanvas* part as a base, as follows:
1. Drop an ISetCanvas* part in the bottom expansion area of column 2.
2. Extend the span of the ISetCanvas* as follows:
a. Select the ISetCanvas* part.
b. Holding the Alt key with one hand, drag either right-hand part
handle over to the column that contains the IEntryField* parts.
c. Release the mouse. The sample window now looks like the following
figure:
3. Add three IPushButton* parts to the ISetCanvas* part.
The ISetCanvas* and multicell canvas parts expand to contain the newly
dropped IPushButton* parts.
To change the way minimum size is calculated for the
IPushButton* parts, edit Pack Type settings for the
ISetCanvas* part.
4. Edit the IStaticText* parts so that they appear as shown in the following
figure: Extend each column 2 IStaticText* part into column 3.
ΓòÉΓòÉΓòÉ 12.7. Adding a Group Box ΓòÉΓòÉΓòÉ
To organize groups of related visual parts on the multicell canvas, add a group
box. You can drop the IGroupBox* part before or after you drop the visual parts
contained within it.
If you prefer to drop the IGroupBox* part first, consider carefully how
many rows and columns you need within the group box. Add any extra rows
and columns before you drop the IGroupBox* part. It can be difficult to
add others in the correct locations later.
If you prefer to drop the contained parts first, you must edit tabbing
and depth order after you have dropped the IGroupBox* part. This is
necessary because parts are added to the window's tabbing and depth order
in the order in which they are dropped. To work properly, the IGroupBox*
part must appear in the tabbing and depth order before the parts
contained within it.
In the contractView sample, the column 3 IStaticText* parts and their entry
fields belong to the Position Details group shown in the following figure:
The group box will extend from cell (10,2) to cell (18,8).
Adding the extra rows and columns to hold the group box
Extra cells are necessary to hold the group box and provide space between the
group box and the parts within it.
1. Add 2 rows above Title.
2. Add 2 rows after Contractor.
3. Add 2 columns after the corresponding IEntryField* parts.
The sample window now looks like the following figure:
Dropping and extending the group box
1. Select , the Data Entry category, from the left side of the parts
palette.
2. Select , the IGroupBox* part, from the right side of the parts palette.
3. Drop the IGroupBox* part into cell (10,2).
This temporarily distorts the multicell canvas. Resize the IFrameWindow*
part to see the extra columns on the right.
4. Select the IGroupBox* part. Holding the Alt key with 1 hand, drag the
lower right part handle to cell (18,8) as shown in the following figure:
If necessary, press Alt-Backspace to undo and retry. Edit the IGroupBox*
text to read Position Details. Remember to move the IGroupBox* part up in
the tabbing and depth order.
ΓòÉΓòÉΓòÉ 12.8. Changing the Settings for a Multicell Canvas ΓòÉΓòÉΓòÉ
You can use the General page of the multicell canvas settings notebook to do
the following:
Move a dropped part
Change the default minimum size for rows or columns
Add rows or columns
Delete rows or columns
Make fixed rows and columns expandable
This page consists of a series of directly editable tables.
ΓòÉΓòÉΓòÉ 12.8.1. Moving Dropped Parts ΓòÉΓòÉΓòÉ
From the free-form surface, you can move dropped parts by selecting and
dragging them to their new locations. You can also move dropped parts between
cells in a multicell canvas using the settings notebook as follows:
1. Open settings for the multicell canvas.
2. At the top of the General page is a scrollable list of all parts
contained in the multicell canvas as shown in the following figure:
3. Select the table entry you want to change and edit the highlighted value.
Row and column numbering starts from (1,1) in the upper-left corner of
the multicell canvas.
4. Select the OK push button to close settings.
Use this table for reference whenever you edit row and column settings.
ΓòÉΓòÉΓòÉ 12.8.2. Changing Default Minimum Size for Rows or Columns ΓòÉΓòÉΓòÉ
You can change the minimum size of a row or column when it is empty. As stated
previously, the default minimum size is 10 pixels wide (columns) and 10 pixels
high (rows), but you can change the default minimum size for individual rows
and columns as follows:
1. Open settings for the multicell canvas.
2. The second table on the General settings page is called Rows, as shown in
the following figure:
3. The default height appears as nil. To change the minimum height for row
1, select the Row 1 table entry under Height. Change this to the new
default value in pixels. For example, the minimum height of row 1 in most
views of the OASearch sample application is 20.
4. Scroll down the General page a little more to see the third table on the
page, called Columns. You can edit values in this table in the same way
you edited the Rows table.
5. Select the OK push button to close settings.
ΓòÉΓòÉΓòÉ 12.8.3. Adding Rows or Columns Using the Settings Notebook ΓòÉΓòÉΓòÉ
To save time when adding more than one row or column at a time, use the
settings notebook. The methods for adding rows and columns are similar, as
follows:
1. Open settings for the multicell canvas. The tables on the General page
are described in Moving Dropped Parts and Changing Default Minimum Size
for Rows or Columns
2. If necessary, scroll down to the Rows table. For a complex layout,
consider resizing the window so that the Controls table is also
displayed.
3. Select the number of a row next to the insertion point. Select the Add
push button.
4. Select either Add before or Add after.
Add before inserts the new row above the selected row.
Add after inserts the new row below the selected row.
5. Select the OK push button to close settings.
ΓòÉΓòÉΓòÉ 12.8.4. Deleting Rows or Columns Using the Settings Notebook ΓòÉΓòÉΓòÉ
To save time when deleting more than one row or column at a time, use the
settings notebook. The methods for deleting rows and columns are similar, as
follows:
1. Open settings for the multicell canvas. The tables on the General page
are described in Moving Dropped Parts and Changing Default Minimum Size
for Rows or Columns
2. If necessary, scroll down to the Rows table. For a complex layout,
consider resizing the window so that the Controls table is also
displayed.
3. Select the number of the row you want deleted. Select the Delete push
button.
4. Select the OK push button to close settings.
ΓòÉΓòÉΓòÉ 12.8.5. Making Rows or Columns Expandable ΓòÉΓòÉΓòÉ
To allocate extra client space, make at least one row and one column
expandable. In most of the OASearch windows, the row immediately above the deck
of push buttons is expandable. In the OAContractView part, the rightmost column
is expandable. For a more complicated example involving several expandable rows
and columns, see the OAMain part in oawin.vbb.
The methods for making rows and columns expandable are similar, as follows:
1. Open settings for the multicell canvas. The tables on the General page
are described in Moving Dropped Parts and Changing Default Minimum Size
for Rows or Columns
2. If necessary, scroll down to the Rows table. For a complex layout,
consider resizing the window so that the Controls table is also
displayed.
3. The default expansion value appears as nil. Select the appropriate entry
from the Rows table under Expand. For the contractView example, select
the row 19 entry.
4. The value d is highlighted. Change it to y and select the Apply push
button.
5. Move the settings notebook window over so you can see the result of your
work, as shown in the following figure:
The expansion area is now hidden. All extra vertical space becomes part
of row 19.
6. When you are finished adjusting row and column expansion settings, select
the OK push button.
To make this row fixed later, enter n in the Expand column.
ΓòÉΓòÉΓòÉ 13. Constructing Containers and Notebooks ΓòÉΓòÉΓòÉ
What you will achieve
Adding container parts
- Setting up the container
- Adding container columns
- Filling the container
Adding notebook parts
- Adding the notebook
- Adding notebook pages
Personal notes:
ΓòÉΓòÉΓòÉ 13.1. What You Will Achieve ΓòÉΓòÉΓòÉ
The purpose of this chapter is to show how easy Visual Builder makes it to use
IBM Open Class Library container and notebook controls.
Container controls hold objects; for example, an OS/2 program folder holds
program objects. You can display containers in different views including the
following:
Icon view, like an OS/2 program folder. Container objects appear inside
the container as icons.
Details view. Attributes of container objects appear in tabular columns.
To use this view, you must define the container columns as well as the
container itself.
Tree view, for container objects that are related hierarchically.
Notebook controls present related information on tabbed pages that the user
can display sequentially or randomly. For an example of a notebook control,
open any Visual Builder settings editor.
ΓòÉΓòÉΓòÉ 13.2. Adding Container Parts ΓòÉΓòÉΓòÉ
In this section, you set up a container in the OASkillView part to hold the
OASkill* objects returned as a result of a user's skill query. The completed
window looks like the following figure:
This example is based on the OASkillView* part, found in oawin.vbb. Before
constructing this new visual part, make sure that oanonvis.vbb is loaded into
Visual Builder.
1. Create a new visual part and name it OASkillView.
A frame window and default canvas appear.
2. Select , the Lists category, from the left side of the parts palette.
3. Select , the IVBContainerControl* part, from the right side of the parts
palette and drop the part onto the default canvas.
4. Change the container's name to SkillCnr.
5. Resize the container part as needed.
The next step is Setting Up the Container.
ΓòÉΓòÉΓòÉ 13.2.1. Setting Up the Container ΓòÉΓòÉΓòÉ
You set some container values in the container part and some in the container
column part. Set the following values in the container part:
Title and title format
View style
Type of contained objects
Set the following values in the container column parts:
Column title and width
Attribute to appear in the column
Vertical and horizontal separators
Whether contents can be changed by the user
For information about container columns, see Adding Container Columns.
Setting the container titles
1. Open the settings notebook for SkillCnr.
2. Specify the general settings. In the Title Attributes group, type
Contractors Holding This Skill into the Title field.
3. Select both Show title and Show title separator.
4. Select the Left radio button for left title alignment.
Specifying the container type and layout
1. Select showDetailsView from the View type list box.
2. Scroll down on the General page. In the Container Item Attributes group,
type OASkill* into the Part type field.
3. Select contractorID from the Text drop-down combination box. The Text
field specifies which OASkill attribute would appear as text in the
container's icon view.
4. The Icon field specifies the icon to be used for each item in the
container. Type the following into the Icon field:
#IDynamicLinkLibrary("cppov33r").loadIcon(803)
cppov33r.dll is the resource DLL containing the icons for this
application, and 803 is the resource ID for the skill icon that would
appear in the container's icon view.
5. Select the Refresh container after changes check box.
6. Select the OK push button to save and close the settings notebook.
ΓòÉΓòÉΓòÉ 13.2.2. Adding Container Columns ΓòÉΓòÉΓòÉ
Once you have added a container, add container columns. This is a good idea
even if you intend for the container to be used mainly as an icon view.
1. Select , the Lists category, from the parts palette.
2. Select the Sticky check box.
3. Select , the IContainerColumn* part, from the parts palette.
4. Drop two IContainerColumn* parts on the SkillCnr part.
Setting up the container columns
1. Open up the settings notebook for the first container column.
2. On the General settings page, type Contractor ID in the Heading text
field.
3. Specify the column's width (in pixels) in the Width field. For this
example, enter 200.
4. Specify the OASkill attribute to appear in this column. Select the Use
the Text attribute set in the container radio button because you want to
display the same information in this container column that the container
displays as text on the icon view.
5. Set the container so that its elements cannot be changed by the user.
Select the following from the Styles settings page:
For the readOnlyHeading style, select the On radio button.
For the readOnly style, select the On radio button.
6. Set a vertical separator for container column 1 only. For the
verticalSeparator style, select the On radio button.
7. Select the OK push button to close the settings notebook.
Repeat this procedure for the second container column, adjusting the width of
the column to fit. The second column is supposed to display the number of
years of experience each contractor has for a certain skill, so use the
following settings:
Select the Use an attribute from the part radio button
Choose yearsExp to populate the container column.
Do not add a vertical separator.
The next step is Filling the Container.
ΓòÉΓòÉΓòÉ 13.2.3. Filling the Container ΓòÉΓòÉΓòÉ
The easiest way to fill the container is to use a collection part. The
OASkillView part uses an IVSequence* part named SkillList. Basically, you
manage container objects through the collection and use a single connection
between it and the container to load the contents of the collection into the
container.
Adding the nonvisual parts
The OASearch application uses static parts that are actually found in OAMain
part. All nonvisual parts in this view except SkillList are variables that will
be connected later to the actual parts.
1. Add an OASkill* part as a variable. Name it Skill.
For help on how to do this, see Adding a Variable to a Composite Part.
2. Add an OASkillBase* part as a variable. Name it SkillBase.
3. Add an IVSequence* part. Name it SkillList.
4. Add an IMessageBox* part to handle exceptions.
Populating the collection
The SkillBase part contains the action (getSkills) needed to populate the
skill list. The getSkills action takes two parameters, a skill description and
a sequence. Make the following connections:
From To
Skill,#skillName EntryField1,#text
PushButton1,#buttonClickEvent SkillBase,#getSkills
Skill,#skillName The aSkillName parameter of the
PushButton1,#buttonClickEvent-->
SkillBase#getSkills connection
SkillList,#this The aList parameter of the
PushButton1,#buttonClickEvent-->
SkillBase#getSkills connection
To handle exceptions, connect the exceptionOccurred feature of the getSkills
connection to the showException feature of the message box part.
Connecting parts to fill the container
To fill the container, connect the this attribute of the SkillList part to the
items attribute of the container.
ΓòÉΓòÉΓòÉ 13.3. Adding Notebook Parts ΓòÉΓòÉΓòÉ
The purpose of this section is to guide you through using a notebook part to
create the OAContractorView part. The completed window looks like the following
figure:
The steps in creating a notebook are as follows:
Add the notebook and set it up.
Add notebook pages and set them up.
Begin by adding the notebook.
ΓòÉΓòÉΓòÉ 13.3.1. Adding the Notebook ΓòÉΓòÉΓòÉ
Before constructing this new visual part, make sure that oanonvis.vbb is loaded
into Visual Builder.
1. Create a new visual part. Call it OAContractorView.
A frame window and default canvas appear.
2. Delete the default canvas part from the frame window and resize the
window as necessary.
3. Select , the Composers category, from the left side of the parts palette.
4. Select , the INotebook* part, from the right side of the parts palette
and drop the part onto the frame window.
Specifying the notebook layout
You change the notebook's appearance using its settings notebook. As you make
selections, notice that the Preview area changes to reflect your choices.
1. Open the settings notebook for the notebook part.
2. On the General settings page, select the icon that represents the
orientation that you want for the notebook. For this example, select from
the Layout group.
3. From the Binding group, select the Spiral radio button.
4. From the Tab Shape group, select the Round radio button.
5. From the Justification group, select the two Center radio buttons.
6. Select the OK push button to close the settings notebook.
The next step is adding notebook pages.
ΓòÉΓòÉΓòÉ 13.3.2. Adding Notebook Pages ΓòÉΓòÉΓòÉ
You add notebook pages using the notebook part's Composition Editor contextual
menu.
1. To add the first page of the notebook, select Add initial page.
2. To add each additional page, select Add page before or Add page after.
For this example, add one page after the initial page.
Setting up the notebook page and tab
1. Open the settings notebook for the first notebook page.
To open the settings for the notebook page instead of the
canvas that is on the notebook page, move the mouse
pointer to the small area around the canvas before opening
the settings.
2. On the General page, type ContactPage into the Subpart name field.
3. Type Contact into the Tab text field. This text is what appears on the
notebook tab.
4. Type Vital statistics into the Status text field. This text is what
appears in the status area at the bottom of the notebook page.
5. On the Style page, select the On radio button for the following styles:
The autoPageSize style, to enable automatic sizing of the notebook
page
The statusText style, to enable display of the status text that you
entered in the previous step to be displayed
The majorTab style, to give the notebook page a major tab
Adding parts to a notebook page
Each notebook page initially contains an ICanvas* part. If you want to use a
different part, delete the ICanvas* part and select another part from the
Composers category, such as IMultiCellCanvas*.
Note: A notebook page allows only one subpart, which should be a part from
the Composers category. You can, of course, add other subparts to the
Composers part.
The ContactPage subpart contains the primitive parts shown in the following
figure:
To see the other notebook pages, open the OAContractView part in oawin.vbb.
ΓòÉΓòÉΓòÉ 14. Adding Menus to Your Application ΓòÉΓòÉΓòÉ
What you will achieve
Types of menus and menu items
Adding a menu bar
Connecting the menu bar to the window
Adding menu choices
Adding menu separators
Connecting menu choices to actions
Personal notes:
ΓòÉΓòÉΓòÉ 14.1. What You Will Achieve ΓòÉΓòÉΓòÉ
The purpose of this section is to guide you through adding menus to the welcome
window of the sample recruitment application. The completed menu parts and
connections are shown in the following figure:
First, read about types of menus. Then, begin with adding a menu bar to the
window.
ΓòÉΓòÉΓòÉ 14.2. Types of Menus and Menu Items ΓòÉΓòÉΓòÉ
In Visual Builder, you use the same menu part to build several different menu
types, as follows:
Menu bars This menu type is attached to a window. It appears horizontally
under the window's title bar.
Pop-up menus This menu type is attached to a control, such as an entry
field, within the window. It appears vertically when the user
selects the control and presses mouse button 2.
Cascaded menus This menu type is attached to a cascade menu item.
If the cascade menu item is part of a menu bar, the
cascaded menu appears below the menu item as a pull-down
menu.
If the cascade menu item is part of a pop-up menu, the
cascaded menu appears beside the menu item.
Begin with adding a menu bar to the window.
ΓòÉΓòÉΓòÉ 14.3. Adding a Menu Bar ΓòÉΓòÉΓòÉ
Begin by opening the visual part that contains the OASearch welcome window, the
OAMain part.
1. Select , the Frame Extensions category, from the left side of the parts
palette.
2. Select , the IMenu* part, from the right side of the parts palette and
drop it on the free-form surface next to the window, as shown in the
following figure:
3. To add two of the menu choices to the menu bar, add two menu parts on top
of the menu part for the menu bar.
As you add each menu part, a cascade button part is added to the menu bar
and a connection is made between the cascade button part and the menu
part you added. This connection causes the menu part to be displayed when
the user selects the cascade button part. See the following figure:
4. Edit the text of the menu choices as shown in the following figure: To do
this, select each one and press Alt-mouse button 1.
ΓòÉΓòÉΓòÉ 14.4. Connecting the Menu Bar to the Window ΓòÉΓòÉΓòÉ
To make the menu a menu bar, connect the this attribute of the IMenu* part to
the menu attribute of the window part. Although the menu continues to appear
vertically on the free-form surface, this connection defines the menu part as a
menu bar.
Since the menu bar is shown outside the frame window, be sure to
leave enough space for it below the window title.
Making this same connection to a part other than a window part, such as a list
part, makes the menu part a pop-up menu instead of a menu bar. See Types of
Menus and Menu Items
Now that the menu bar has been added, the next step is adding the menu
choices.
ΓòÉΓòÉΓòÉ 14.5. Adding Menu Choices ΓòÉΓòÉΓòÉ
Once the menu structure is complete, you need to add menu choices that do
something other than open other menus.
1. Select , the Frame Extensions category, from the left side of the parts
palette.
2. Select , the IMenuItem* part, from the right side of the parts palette.
3. The position at which you click the mouse is where the part is added
within the menu. Drop menu items as follows:
One part as the last item in the Menu1 part
Four items in the Menu2 part
Two items in the Menu3 part
You can change the position of a menu choice part within the menu part by
using mouse button 2 to drag each item to a new position. Position these parts
and change their text as shown in the following figure: The next step is
connecting menu choices to actions.
ΓòÉΓòÉΓòÉ 14.6. Adding Menu Separators ΓòÉΓòÉΓòÉ
Once you have added and edited the OAMain menu items, add a separator bar to
Menu2 between Skill and General Information as follows:
1. Select , the Frame Extensions category, from the left side of the parts
palette.
2. Select , the IMenuSeparator* part, from the right side of the parts
palette.
ΓòÉΓòÉΓòÉ 14.7. Connecting Menu Choices to Actions ΓòÉΓòÉΓòÉ
Once you have added menu choices, you can connect them to actions in this or
other parts. As an example, connect the Exit menu bar item so that when the
item is selected, the main window closes, as follows:
From part, feature To part, feature
ExitMI,#commandEvent FrameWindow,#close
Command events occur when a user selects a menu item, push button, or
accelerator key. In this case, the user' selection of Exit generates a command
event to perform the close action on the Frame Window.
Note: You cannot promote menu item events to the part interface.
The other menu choices, shown in the following figure, connect to other parts
that are not on this free-form surface. These connections are completed in
Completing the Menu Bar.
ΓòÉΓòÉΓòÉ 15. Adding Help To Visual Builder Applications ΓòÉΓòÉΓòÉ
Introduction
Creating the help file
Providing context-sensitive help
Providing general help
Providing the application help window
Providing help for factory-generated frame windows
Providing a Help push button
Displaying fly-over help when the mouse pointer is over a part
Displaying help in an information area
Personal notes:
ΓòÉΓòÉΓòÉ 15.1. Introduction ΓòÉΓòÉΓòÉ
In this section, you learn about adding different types of help to your
application. Generally, in application development, you develop your user
interface and then provide the necessary help panels. The basic help types are
as follows:
Help Type Description
Context-sensitive help Help information for the current choice, object, or
group of choices or objects. The user can display
context-sensitive help by tabbing or cursoring to a
subpart and doing either of the following:
Pressing the F1 key. You do not have to do
anything to make this happen. Presentation
Manager handles it for you.
Selecting the Help push button if you have
provided one. See Providing a Help Push Button
for information on how to do this.
General help Help for a specific window, explaining the purpose of
the window and how it operates.
To show you how to add help, we are going to write help for the main window of
the OASearch application, introduced in The Welcome Window section and shown
below.
The example we use in this chapter assumes that you have already built the
main view for the OASearch application. If you want to do the example along
with us, you must build this view first.
The first step in providing help is to create the help file.
ΓòÉΓòÉΓòÉ 15.2. Creating the Help File ΓòÉΓòÉΓòÉ
Before we can connect the help, we must first create the help file.
Writing the help
For convenience sake, we have provided the help source so you do not have to
retype it. Double-click here to see the help source and select Copy from the
Services pull-down menu to copy the panel text to the system clipboard. Using
your favorite editor, create a new file and paste this text into the file.
Note: Be sure to use an .ipf extension when naming the file.
When creating your own help files, try using a Project Smarts IPF
template, which provides the basic tags for creating online help
using the OS/2 Information Presentation Facility. For more
information on writing online help, refer to the OS/2 Information
Presentation Facility Guide and Reference.
The :h1 tags are heading tags. These tags cause IPF to create a new help panel
using the text on the tag as the panel's title.
The res parameter specifies the panel's resource number. See Providing
Context-sensitive Help to learn how these resource numbers are used.
The :i1 tags are index tags. These tags allow you to provide an index of help
topics for your application. If you provide a Help index choice in the Help
pull-down menu on the menu bar, the user can select this choice to display the
help index. When the user double-clicks on a topic in the help index, IPF
displays the help panel whose :h1 tag precedes the index tag in the help file.
Save this file with a name similar to cppov33.ipf.
Building the help file
Ensure that you have the IPF compiler installed on your system and that your
environment variables are set up to run the IPF compiler. The IPF compiler
comes with the OS/2 2.1 Toolkit and the OS/2 Warp Toolkit.
To build the help file, simply run the Information Presentation Facility (IPF)
compiler. For example, if you saved your help file with the name cppov33.ipf,
you would enter the following command in the directory where you saved your
file:
ipfc cppov33.ipf
This command generates a file called cppov33.hlp.
You have now built your help file. The next step is to provide
context-sensitive help in your application.
ΓòÉΓòÉΓòÉ <hidden> Sample Help Source Code ΓòÉΓòÉΓòÉ
:userdoc.
:title.Opportunities Abound Databases Help
:docprof toc=1 ctrlarea=page.
:ctrl ctrlid=buttons controls='ESC SEARCH PRINT' page.
:h1 res=9998.
General Help for the Opportunities Abound Databases
:i1.general help
:p.Text goes here.
:h1 res=9999.
Request for Skill Information Help
:i1.requesting skill information, help for
:p.Text goes here.
:h1 id=10000.
Skill Information Help
:i1.skill information, help for
:p.Text goes here.
:h1 res=10001.
Request for Contract Information Help
:i1.requesting contract information, help for
:p.Text goes here.
:h1 res=10002.
Contract Information Help
:i1.contract information, help for
:p.Text goes here.
:h1 res=10003.
Request for Contractor Information Help
:i1.requesting contractor information, help for
:p.Text goes here.
:h1 res=10004.
Contractor Information Help
:i1.contractor information, help for
:p.Text goes here.
:euserdoc.
ΓòÉΓòÉΓòÉ 15.3. Providing Context-sensitive Help ΓòÉΓòÉΓòÉ
This section tells you how to provide context-sensitive help for subparts in
your application.
For this example, we use the graphic push buttons on the window.
To provide context-sensitive help for a subpart, do the following:
1. Open the cppov33.ipf file in your text editor and find the "Request for
Skill Information Help" heading.
Above this heading is the heading tag, :h1, with a res attribute. This
attribute contains the resource number for the help panel for the Skills
push button.
2. Open the settings notebook for the subpart, in this case the Skill push
button.
3. Select the Control page. It looks like the following figure:
4. Enter the resource number for the Skills push button help panel in the
Help panel id field.
When you generate the code for your application, Visual Builder creates a
help table in the resource (.rc) file that it generates and inserts this
number into the help table.
5. If the Enable check box is not checked, select it.
6. Select the OK push button.
7. Repeat steps 2 through 6 for the Contract push button and the Contractor
push button. Use the resource numbers for the "Request for Contract
Information Help" and "Request for Contractor Information Help",
respectively.
You have now provided context-sensitive help for the push buttons. The next
step is to provide general help in your application.
ΓòÉΓòÉΓòÉ 15.4. Providing General Help ΓòÉΓòÉΓòÉ
This section tells you how to provide general help for your application. For
this example, we use the frame window.
To provide context-sensitive help for your application, do the following:
1. Open the cppov33.ipf file in your text editor and find the "General Help
for the Opportunities Abound Databases" heading.
Above this heading is the heading tag, :h1, with a res attribute. This
attribute contains the resource number for the general information help
panel.
2. Open the settings notebook for the subpart, in this case the frame
window.
3. Select the Control page. It looks like the following figure:
4. Enter the resource number for the general information help panel in the
Help panel id field.
When you generate the code for your application, Visual Builder creates a
help table in the resource (.rc) file that it generates and inserts this
number into the help table.
5. If the Enable check box is not checked, select it.
6. Select the OK push button.
You have now provided general help for the main window. The next step is to
provide a help window to display the help panels in.
ΓòÉΓòÉΓòÉ 15.5. Providing the Application Help Window ΓòÉΓòÉΓòÉ
Now that you have added the context-sensitive help and the general help for the
main window, you need a help window to display the help panels in. You must
place an IHelpWindow* part on the free-form surface to give Visual Builder a
window in which to display the help information. The default owner of the
IHelpWindow* part is the primary part for your application. Therefore, no
connections are required.
To add a help window to your application, do the following:
1. Select , the Other category, on the parts palette.
2. Select , the IHelpWindow* part, and place it on the free-form surface.
3. Open the settings notebook for the IHelpWindow* part. It looks like the
following figure:
4. In the Title field, enter the title of the help window.
This must be the same title that you entered on the :title tag in your
.ipf file.
5. In the Help libraries field, enter the name of the help file that you
compiled, such as oasearch.hlp.
If you had created multiple help files for your application, you would
enter all of their names in this field.
6. We recommend that you leave the Help table id field empty and let Visual
Builder generate it for you unless you need a specific help table ID.
Otherwise, you could have conflicts in your resource (.rc) file.
7. Select the OK push button.
ΓòÉΓòÉΓòÉ 15.6. Providing Help for Factory-generated Frame Windows ΓòÉΓòÉΓòÉ
You can associate a help window with a part that is generated by an object
factory if the base class of that part is IFrameWindow*. To do this, you can do
either of the following:
Edit the part that the object factory generates, place an IHelpWindow*
part on the free-form surface next to it, and do all the things described
in the preceding sections to use the help window properly. Repeat this
step for each IFrameWindow*-based part that is generated by an object
factory.
You should use this method if you have created multiple help library
(.hlp) files for your library instead of putting all of your help panels
in one library file.
Place an IHelpWindow* part on the free-form surface in the same view with
the object factory if you have created only one help library file for all
of your help panels. Then, do the following:
1. Open the settings notebook for the IHelpWindow* part.
2. Enter the help window title and the name of the library (.hlp) file.
3. Close the settings notebook by selecting the OK push button.
4. Connect the newEvent feature of the object factory to the
setAssociatedWindow action of the help window.
5. Repeat step 4 for each object factory in the view.
6. Edit each IFrameWindow*-based part that an object factory generates
and specify the appropriate help panel IDs for the subparts that you
want to provide help for. Each help panel ID must be a resource ID
in the library file that you specified in step 2.
ΓòÉΓòÉΓòÉ 15.7. Providing a Help Push Button ΓòÉΓòÉΓòÉ
The main window of the OASearch application, which we have been using for this
help example, does not contain a Help push button. However, many applications
provide such a push button to give users quick and easy access to the help
information that the application provides.
To provide a Help push button in your application, do the following:
1. Select , the Buttons category, in the left-hand column on the parts
palette.
2. Select , the IPushButton* part, and place it where you want it to be.
3. Change the text on the push button to Help.
4. Open the settings notebook for the push button.
5. Select the Styles tab.
6. Find help on the Styles page and select the On radio button.
This style turns a regular push button into a help push button.
7. On the same page, find noPointerFocus and select the On radio button.
This style keeps the Help push button from getting the input focus when a
user clicks on it. By setting this style, you enable your application to
display help for the part that has the input focus when a user clicks the
Help push button. Otherwise, the user sees the help panel that you assign
to the Help push button.
When this style is set, the user must use the cursor keys to set the
input focus on the Help push button. After doing this, the user can click
on the Help push button to display the help panel that you assign to it.
8. Select the OK push button to close the settings notebook.
You now have a Help push button. If you have followed the steps in the
preceding sections, clicking this button causes the contextual help panel for
the part that currently has the input focus to be displayed. If no part has
the focus, the main help panel for the window is displayed. The behavior of
the Help push button is identical to that of the F1 key.
To provide a help panel for the Help push button itself, follow the
instructions in Providing Context-sensitive Help.
ΓòÉΓòÉΓòÉ 15.8. Displaying Fly-over Help When the Mouse Pointer Is Over a Part ΓòÉΓòÉΓòÉ
Another type of help that you can provide in your application is called
fly-over help, which is intended to provide instant help for novice users. This
type of help consists of a text string that your application displays when the
user positions the mouse pointer over a subpart, such as a push button or list
box. The text string should be short and precise, giving the user information
such as the purpose of the subpart.
Your application can provide the following types of fly-over help:
A short text string that your application displays next to the subpart
that the mouse pointer is over
A longer text string that your application displays in a text control
Providing fly-over help for a subpart
To provide fly-over help for a subpart, do the following:
1. Place an IVBFlyText* part on the free-form surface by doing the
following:
a. Select , the Other category, on the parts palette.
b. Select , the IVBFlyText* part, and place it on the free-form
surface.
2. Add fly-over help text to one or more subparts by doing the following:
a. Open the settings notebook for a subpart, such as an entry field or
push button.
b. Select the Control notebook tab.
c. Enter fly-over text strings in the Fly over short text field, the
Fly over long text field, or both.
Text that you enter in the Fly over short text field is displayed in
a pop-up window next to a subpart when the user positions the mouse
pointer over that subpart.
Text that you enter in the Fly over long text field is displayed in
a text control that you specify. For example, you might add an
information area to a window and display the long fly-over help text
there. See Displaying Long Fly-over Text In an Information Area to
see how this is done.
If one of your application views contains two or more
frame windows, do not use the same IVBFlyText* part
to assign long fly-over text strings to text controls
in each window. If you do, your fly-over text
probably will not appear in the window that you
expect it to appear in.
For example, suppose your view contains two frame
windows: one that is displayed when your application
starts and another one that is displayed when a menu
item in the first window is selected. In this case,
place two IVBFlyText* parts on the free-form surface.
The first IVBFlyText* part is associated by default
with the window that is displayed when your
application starts. However, you must specify the
owner of the second IVBFlyText* part by opening the
IVBFlyText* part's settings notebook and entering the
name of the owner part in the Owner field, such as
iFrameWindow1.
d. Select the OK push button to save the text strings that you just
entered.
That is all you need to do. There are no connections to make.
ΓòÉΓòÉΓòÉ 15.9. Displaying Help in an Information Area ΓòÉΓòÉΓòÉ
There are times when it is helpful to provide an information area in an
application window that your application can use to give the user feedback. For
example, the information area might let the user know whether the application
performed an operation successfully or it might provide a description of a menu
choice.
Visual Builder provides the IInfoArea* part that you can use for this purpose.
An information area is considered to be an extension of a frame window. You can
only add it to an IFrameWindow* part. Visual Builder positions the information
area at the bottom of the frame window's client area.
The following sections provide specific information about displaying help in an
information area:
Adding an information area to a frame window
Displaying help for menu choices in an information area
Displaying information about successful actions
ΓòÉΓòÉΓòÉ 15.9.1. Adding an Information Area to a Frame Window ΓòÉΓòÉΓòÉ
To add an information area to a frame window, do the following:
1. Select , the Frame Extensions category, on the parts palette.
2. Select , the IInfoArea* part.
3. Move the mouse pointer over the title bar or window border of the frame
window and click mouse button 1.
Visual Builder places an information area at the bottom of the frame
window.
4. Open the settings notebook for the information area.
5. Enter text that you want your application to display in the following
fields:
Disabled text
Text to display when the selected menu choice is disabled.
Inactive text
Text to display when no menu choice is selected.
Missing text
Text to display when the information area cannot find and display
specific help for a menu choice.
ΓòÉΓòÉΓòÉ 15.9.2. Displaying Help for Menu Choices in an Information Area ΓòÉΓòÉΓòÉ
To display help text for menu choices in an information area, do the following:
1. Create the menu bar and pull-down menus for your application.
2. Open the settings notebook for each menu choice.
3. Enter a description of the menu choice in the Info area text field.
4. Select the OK push button to save the description you just entered.
ΓòÉΓòÉΓòÉ 15.9.3. Displaying Long Fly-over Text In an Information Area ΓòÉΓòÉΓòÉ
Earlier in this chapter, we showed you how to add an IVBFlyText* part and
display a short text string in a pop-up window. This section shows you how to
display a longer text string in an IInfoArea* part, although you can use any
text control, such as an IEntryField*.
To display a long fly-over text string in an information area, do the
following.
Note: The following steps assume that you have already added an IVBFlyText*
part and an IInfoArea* part to a frame window. If you have not, you
should complete the steps in the following sections and then return
here.
Displaying Fly-over Help When the Mouse Pointer Is Over a Part
When following these steps, make sure you enter a text string in the Fly
over long text field in the settings notebook for a subpart, such as an
entry field or push button.
Adding an Information Area to a Frame Window
1. Display the connection menu for the information area.
2. Select the this attribute.
3. Display the connection menu for the fly-over text part.
4. Select the longTextControl attribute.
That is all you have to do.
ΓòÉΓòÉΓòÉ 15.9.4. Displaying Information about Successful Actions ΓòÉΓòÉΓòÉ
One way to make your applications more user-friendly is to provide feedback to
the user when an action or member function performs successfully, such as the
successful completion of an action that is triggered by a buttonClickEvent
feature. We recommend that you display this information in an IInfoArea* part.
To display information in an information area when an action or member function
completes successfully, do the following:
1. Create an event-to-attribute connection using the text attribute of the
IInfoArea* part as the target. The source event can be one of the
following:
The same event that triggered the action or member function
If the action or member function was triggered by an event, you can
use the same event, such as the buttonClickEvent or commandEvent
feature. In this case, be sure to check the connection order to make
sure the event-to-action or event-to-member function connection
occurs before the event-to-attribute connection.
The actionResult event of the connection that triggered the action
or member function
All connections have both an actionResult event and an actionResult
attribute. Therefore, be sure you use the actionResult event as the
source of the connection.
2. Double-click on the connection you just made to open the settings window
for the connection.
3. Select the Set parameters push button to open the Constant Parameter
Value Settings window.
4. In the text field, enter the text string that you want to assign to the
text attribute.
Your application will display this text string in the information area
each time the action or member function completes successfully.
5. Select the OK push button to close the Constant Parameter Value Settings
window.
6. Select the Cancel push button to close the connection settings window.
ΓòÉΓòÉΓòÉ 16. Integrating Visual Parts into a Single Application ΓòÉΓòÉΓòÉ
What you will achieve
Adding nonvisual support parts to the primary part
Adding static visual parts
Adding visual parts as dynamic instances
- Adding and setting Object Factory parts
- Adding variable parts
- Connecting to the Object Factory parts
- Connecting the Object Factory parts to their corresponding variable
parts
Making the final connections
- Connecting the nonvisual parts to the variables that represent them
- Completing the menu bar
Personal notes:
ΓòÉΓòÉΓòÉ 16.1. What You Will Achieve ΓòÉΓòÉΓòÉ
In this chapter, you combine all visual parts of the OASearch sample
application in preparation for generating code and compiling. This chapter
includes the following tasks:
Adding nonvisual support parts to the primary part
Adding static visual parts
Adding visual parts as dynamic instances
Making the final connections
To follow this example, load oanonvis.vbb and oawin.vbb into Visual Builder.
ΓòÉΓòÉΓòÉ 16.2. Adding Nonvisual Support Parts to the Primary Part ΓòÉΓòÉΓòÉ
For this example, refer to the primary view, OAMain, in oawin.vbb, shown in the
following figure:
1. Begin by building the primary part as you would any IFrameWindow*-based
part. For information about building the menu bar, see Adding Menus to
Your Application.
2. The OASearch application starts up with a small number of static
nonvisual instances to support the visual parts. Add the following parts:
OAContractor*. Name it Contractor.
OAContract*. Name it Contract.
OASkill*. Name it Skill.
OASkillBase*. Name it SkillBase.
You must connect these part instances to the variables that represent
them in the other visual parts. First, you must add the visual parts.
ΓòÉΓòÉΓòÉ 16.3. Adding Static Parts ΓòÉΓòÉΓòÉ
One visual part, OAGenInfo, exists statically in the OASearch application as a
modal window. The disadvantage of using static visual parts is that once the
user closes the window, the part is destroyed and cannot be instantiated again
in the same session.
Add the OAGenInfo* part. Name it VBDevelopment. You must also connect
OAGEnInfo* to the menu item that causes it to display. For details, see
Completing the Menu Bar.
ΓòÉΓòÉΓòÉ 16.4. Adding Visual Parts as Dynamic Instances ΓòÉΓòÉΓòÉ
All OASearch visual parts except for OAMain and OAGenInfo are created at run
time as the user requests them from a menu or button selection. The dynamic
windows are represented in the OAMain part by Object Factory parts. Like static
visual parts, dynamic visual parts are destroyed when the user closes them.
However, the existence of the Object Factory enables the creation of a new
instance of that same part the next time the user requests it.
Like variable parts, Object Factory parts are placeholders for other parts.
Each Object Factory part is set to the part it represents. The Object Factory
part works in tandem with a variable part that represents the dynamic part
instance. You can use Object Factory parts to create both visual and nonvisual
parts.
Unlike variable parts, Object Factory parts run the corresponding part class
constructor, creating a new instance. Variable parts merely stand in for
instances created elsewhere.
Implementing dynamic parts involves the following tasks:
Adding and setting Object Factory parts
Adding variable parts
Connecting to the Object Factory parts
Connecting the Object Factory parts to the corresponding variable parts
The first step is adding and setting Object Factory parts.
ΓòÉΓòÉΓòÉ 16.4.1. Adding and Setting Object Factory Parts ΓòÉΓòÉΓòÉ
Before you can use Object Factory parts, you must have created the part classes
to be represented. Before you start, be sure to load the .vbb files that
contain those parts into Visual Builder.
Adding the Object Factory parts
1. Select , the Models category, from the left side of the parts palette.
2. Select the Sticky check box.
3. Select , the Object Factory part, from the right side of the parts
palette.
4. Drop six Object Factory parts on the free-form surface.
5. Unload the mouse pointer by selecting , the Selection tool, from the
Visual Builder tool bar.
Setting an Object Factory part
1. Change the part name using the Composition Editor contextual menu.
In the OASearch example, the Object Factory parts are named as follows:
ConQFac Request for Contract Information window
ConVFac Contract Information window
CtrQFac Request for Contractor Information window
CtrVFac Contractor Information window
SklQFac Request for Skill Information window
SklVFac Skill Information window
2. Change the part type from the default (IStandardNotifier*) using the
Composition Editor contextual menu.
In the OASearch example, the Object Factory parts have the following
types:
ConQFac OAQueryContract*
ConVFac OAContractView*
CtrQFac OAQueryContractor*
CtrVFac OAContractorView*
SklQFac OAQuerySkill*
SklVFac OASkillView*
3. Set the Object Factory part to automatically delete each instance, as
follows:
a. Open the settings notebook for the part.
b. Switch to the General page.
c. Select the AutoDelete check box.
ΓòÉΓòÉΓòÉ 16.4.2. Adding Variable Parts ΓòÉΓòÉΓòÉ
When used with Object Factory parts, variable parts represent the newly created
part instance. Add and set variable parts as follows:
ContractQ Set the type to OAQueryContract*.
ContractorQ Set the type to OAQueryContractor*.
SkillQ Set the type to OAQuerySkill*.
ContractV Set the type to OAContractView*.
ContractorV Set the type to OAContractorView*.
SkillV Set the type to OASkillView*.
For more information on variables, see Adding a Variable to a Composite Part.
ΓòÉΓòÉΓòÉ 16.4.3. Connecting to the Object Factory Parts ΓòÉΓòÉΓòÉ
Once you have added and set both the Object Factory and variable parts, connect
the IGraphicPushButton* parts on the welcome window to the Object Factory parts
representing the query windows, as follows:
From part, feature To part, feature
ContractGB, #buttonClickEvent ConQFac, #new
ContractorGB, # CtrQFac, #new
buttonClickEvent
SkillGB, #buttonClickEvent SklQFac, #new
Next, connect promoted button actions in the query windows to the Object
Factory parts representing the information windows, as follows:
From part, feature To part, feature
ContractQ, #okPB ConVFac, #new
ButtonClickEvent
ContractorQ, #okPB CtrVFac, #new
ButtonClickEvent
SkillQ, #okPBButtonClickEvent SklVFac, #new
ΓòÉΓòÉΓòÉ 16.4.4. Connecting the Object Factory Parts to Their Corresponding Variable Parts ΓòÉΓòÉΓòÉ
Once you have set both Object Factory and variable parts, you must connect
them. In OAMain, the connections vary depending on whether the window is modal.
Modal windows retain focus until they are closed; the user cannot switch focus
to another window without closing the modal window. In OAMain, OAGenInfo and
the query windows are modal; the other windows are modeless.
Connections for modal windows
Make the following connections for the query window parts. The connections for
OAGenInfo* are listed in Completing the Menu Bar.
From part, feature To part, feature
ConQFac, #newEvent ContractQ, #this
ConQFac, #newEvent ContractQ, #setFocus
ConQFac, #newEvent ContractQ, #showModally
CtrQFac, #newEvent ContractorQ, #this
CtrQFac, #newEvent ContractorQ, #setFocus
CtrQFac, #newEvent ContractorQ, #showModally
SklQFac, #newEvent SkillQ, #this
SklQFac, #newEvent SkillQ, #setFocus
SklQFac, #newEvent SkillQ, #showModally
Connections for modeless windows
Now make the following connections for the modeless information windows:
From part, feature To part, feature
ConVFac, #newEvent ContractV, #this
ConVFac, #newEvent ContractV, #setFocus
ConVFac, #newEvent ContractV, #visible
CtrVFac, #newEvent ContractorV, #this
CtrVFac, #newEvent ContractorV, #setFocus
CtrVFac, #newEvent ContractorV, #visible
SklVFac, #newEvent SkillV, #this
SklVFac, #newEvent SkillV, #setFocus
SklVFac, #newEvent SkillV, #visible
ΓòÉΓòÉΓòÉ 16.5. Making the Final Connections ΓòÉΓòÉΓòÉ
With all parts represented in the primary part, you have only to make the final
connections. This includes the following:
Connecting the nonvisual parts to their corresponding variable parts
Completing the menu bar
ΓòÉΓòÉΓòÉ 16.5.1. Connecting the Nonvisual Parts to the Variables that Represent Them ΓòÉΓòÉΓòÉ
Each visual part contains promoted variables as placeholders for the static
nonvisual parts dropped in OAMain. Now, connect the static parts to the
variables that represent them as follows:
From part, feature To part, feature
Contract, #this ConQFac, #contract
Contract, #this ConVFac, #contract
Contract, #this CtrVFac, #contract
Contractor, #this CtrQFac, #contractor
Contractor, #this CtrVFac, #contractor
Skill, #this SklQFac, #skill
Skill, #this SklVFac*, #skill
SkillBase, #this SklQFac, #skillBase
SkillBase, #this SklVFac, #skillBase
SkillBase, #this CtrQFac, #skillBase
SkillBase, #this CtrVFac, #skillBase
ΓòÉΓòÉΓòÉ 16.5.2. Completing the Menu Bar ΓòÉΓòÉΓòÉ
Now that all parts appear on the free-form surface, you can complete the menu
bar. The connections echo those made in Connecting to the Object Factory Parts.
Connections from the View submenu
From part, feature To part, feature
ContractMI, #commandEvent ConQFac, #new
ContractorMI, #commandEvent CtrQFac, #new
SkillMI, #commandEvent SklQFac, #new
GenInfoMI, #commandEvent VBDevelopment, #setFocus
GenInfoMI, #commandEvent VBDevelopment, #showModally
Connections from the Edit submenu
From part, feature To part, feature
ContractMI, #commandEvent ConVFac, #new
ContractorMI #commandEvent CtrVFac, #new
Once all connections are complete, you are ready to generate code. Make sure to
save your work.
ΓòÉΓòÉΓòÉ 17. Generating Source Code for Parts and Applications ΓòÉΓòÉΓòÉ
What you will achieve
Preparing for source code generation:
- Setting up Visual Builder to generate make files
- Setting up Visual Builder projects to use WorkFrame's makemake
program
Generating C++ source code for individual parts
Source files created during part code generation
Generating C++ source code for your application's main() function
Source files created during generation of main() function code
Preparing generated files for compilation
- Specifying additional libraries in the make file
- Specifying debug options for the compiler and linker programs
Compiling and linking your application
Personal notes:
ΓòÉΓòÉΓòÉ 17.1. What You Will Achieve ΓòÉΓòÉΓòÉ
All work that you do using Visual Builder is stored within the Visual Builder
development environment, including information about visual parts, nonvisual
parts, and connections.
This chapter describes all you need to know about getting your Visual Builder
application ready for others to use. The topics covered are as follows:
Preparing for source code generation
Generating C++ source code for the individual parts used within your
application
Generating C++ source code for your application (the main() function)
Preparing generated files for compilation
Compiling and linking your application
ΓòÉΓòÉΓòÉ 17.2. Preparing for Source Code Generation ΓòÉΓòÉΓòÉ
Before getting started, decide how you want to build your application's make
file. You can create make files in either of the following ways:
From Visual Builder
Using WorkFrame's makemake program
Both options require the following advance preparation.
ΓòÉΓòÉΓòÉ 17.2.1. Setting Up Visual Builder to Generate Make Files ΓòÉΓòÉΓòÉ
If you want Visual Builder to generate make files with the C++ source code,
follow these steps from the Visual Builder window:
1. From the menu bar, select Options.
2. Select Preferences; then select Generate make files.
The next step is generating C++ source code for individual parts.
ΓòÉΓòÉΓòÉ 17.2.2. Setting Up Visual Builder Projects to Use WorkFrame's makemake Program ΓòÉΓòÉΓòÉ
If you prefer to build your application's make file using WorkFrame, make sure
your Visual Builder project has the correct compile and link options set.
Follow these steps from the desktop:
1. Open the Settings notebook for your Visual Builder project.
2. Select the Target notebook tab. Type an appropriate name in the Make file
name field.
3. Select the Actions notebook tab.
4. Select the link action; then select the Options push button.
5. Select the Templates notebook tab.
6. Select the Templates used radio button; then select the compile action to
associate with the link action.
7. Select the OK push button.
8. Select the File Names notebook tab.
9. Under Libraries to use, type in:
cppoov3i.lib os2386.lib
10. Under Definition (.DEF) file name, type the appropriate module definition
file name.
11. Select the OK push button.
12. Close the Settings notebook.
The next step is generating C++ source code for individual parts.
ΓòÉΓòÉΓòÉ 17.3. Generating C++ Source Code for Individual Parts ΓòÉΓòÉΓòÉ
After you finish constructing a part, you must generate source code. If the
part is an application in itself or if you want to test a part individually,
you must also generate the code as described in Generating C++ Source Code for
Your Application's main() Function.
You can generate source code for the part being edited from any of the Visual
Builder editors.
1. From the editor's menu bar, select File.
2. Select Save and generate; then select Part source.
In addition, if you are using the Composition Editor, you can select , (the
icon for the Generate Part Code tool) on the tool bar. There is no difference
between selecting this icon and using the menu item described previously.
One of the most common causes of code generation errors is changing
the names of features that are connected to other features. For
example, suppose feature A is connected to feature B. If you change
the name of feature A and then regenerate the source code for your
part, Visual Builder displays an error. This can also occur if you
change the name of a promoted feature. To correct the error,
double-click on the connection arrow and replace the incorrect
feature name with the correct one.
For more information about the files generated, see Source Files Created
during Part Code Generation.
The next step is generating C++ source code for your application's main()
function.
ΓòÉΓòÉΓòÉ 17.3.1. Source Files Created during Part Code Generation ΓòÉΓòÉΓòÉ
For each part processed, Visual Builder generates several source code files. As
an example, the following files are created for the OAContractView part:
contractg.cpp A C++ code file.
contractg.hpp The header file for contractg.cpp.
contractg.h A resource header file for the .cpp file. This file contains the
resource IDs for your part.
contractg.rc A resource file that contains any text strings used in the part
for entry field labels, push buttons, menus, and so forth.
If you selected Default to FAT file names under the Options pull-down menu of
the Visual Builder window and your part name has more than eight characters,
Visual Builder creates an eight-character name for the part when it is
created.
Note: If you are using the File Allocation Table (FAT) file system, we
recommend that you always use part names and file names that have eight
characters or less, even if you have selected the Default to FAT file
names option. Otherwise, Visual Builder might use a file name for a
.vbb file that is the same as one that already exists and write over
the existing file.
For information about how the .h and .rc files are used for translation, see
Enabling National Language Support for an Application.
The next step is generating C++ source code for your application's main()
function.
ΓòÉΓòÉΓòÉ 17.4. Generating Source Code for Your Application's main() Function ΓòÉΓòÉΓòÉ
To create an executable application, you must generate code for the standard
C++ main() function. You can do this for parts that you want to test
individually or for your entire application. If you want to compile your entire
application, generate the function using the part that represents your
application's primary view.
You must first generate the C++ code for all parts that you intend to compile
in your application. Load into Visual Builder the .vbb files that represent all
parts that will appear in the compiled application. Then, generate the main()
function from the part that you want to appear first when your application is
started (the main part).
You can generate application source code for the main() function if the main
part is displayed in any of the Visual Builder editors.
1. From the editor's menu bar, select File.
2. Select Save and generate; then select main() for part.
For more information about the files generated, see Source Files Created
during Generation of main() Function Code.
The next step is preparing generated files for compilation.
ΓòÉΓòÉΓòÉ 17.4.1. Source Files Created during Generation of main() Function Code ΓòÉΓòÉΓòÉ
For each main part processed, Visual Builder creates several files. For the
OAMain part, the following files are created:
oamain.app The C++ code file containing the main() function declaration.
Note: If you start Visual Builder from a WorkFrame project, a file
named vbmain.cpp is generated instead of a file named
oamain.app.
oamain.mak A make file, if you opted to generate make files using Visual
Builder.
If you selected Default to FAT file names as a preference under the Options
pull-down menu of the Visual Builder window and your part name has more than
eight characters, Visual Builder creates an eight-character name for the
generated files.
Note: If you are using the File Allocation Table (FAT) file system, we
recommend that you always use part names and file names that have eight
characters or less, even if you have selected the Default to FAT file
names option. Otherwise, Visual Builder might use a file name for a
.vbb file that is the same as one that already exists and write over
the existing file.
The next step is preparing generated files for compilation.
ΓòÉΓòÉΓòÉ 17.5. Preparing Generated Files for Compilation ΓòÉΓòÉΓòÉ
Before compiling your application, be sure you have the following files:
Header files for all parts
.cpp files for all parts
A make file
An .app file for the main part
Note: If you start Visual Builder from a WorkFrame project, you should
have a file named vbmain.cpp instead of an .app file.
Final preparations for compilation and linking include the following:
Specifying additional libraries (C++ libraries and DLLs) in the make file
Specifying debug options for the compiler and linker programs
ΓòÉΓòÉΓòÉ 17.5.1. Specifying Additional Libraries in the Make File ΓòÉΓòÉΓòÉ
Review the list of libraries specified in the make file, particularly libraries
for parts that you compiled separately.
If your application uses DLLs, add the DLL names as dependent files in the
description blocks used to keep the object files up to date. The order in which
you list object files is significant. Files with external references must occur
after the referred-to files.
ΓòÉΓòÉΓòÉ 17.5.2. Specifying the Option to Generate Browser Information ΓòÉΓòÉΓòÉ
If your want the VisualAge C++ compiler to generate Browser information, you
must include the -Fb+ option when you compile your application. This option
causes the compiler to generate a file with an extension of .pdb. Once this
file is generated, you can use the Browser data when connecting features to
member functions and for other purposes. For more information, see Using
Browser Information.
ΓòÉΓòÉΓòÉ 17.5.3. Specifying Debug Options for the Compiler and Linker Programs ΓòÉΓòÉΓòÉ
If you prefer to compile and link your application using WorkFrame, you should
have already specified debug options in your Visual Builder project file. For
more information about the options you need to set, see the WorkFrame
documentation.
If you opted to let Visual Builder generate your make file, Visual Builder adds
debug options to the make file by default. If you do not want your application
compiled with debugging turned on, remove the /Ti+ option.
For more information, refer to the VisualAge C++ Language Reference.
To make Visual Builder connections easier to debug, set up a trace by following
these steps:
1. In your config.sys file, add this line:
SET ICLUI TRACETO=STDOUT
2. In your make file, add this phrase at the end of the GCPPFLAGS statement,
but before the back slash (\):
-DIC_TRACE_DEVELOP
3. When you run your compiled application, redirect the output to a file.
For example, run myapp.exe as follows:
myapp > myapp.out
Browse the output file (myapp.out) to see what connections were fired and
in what order.
ΓòÉΓòÉΓòÉ 17.6. Compiling and Linking Your Application ΓòÉΓòÉΓòÉ
You can compile your application from the OS/2 command line or from WorkFrame.
To call both the complier and linker programs, you can run the Toolkit's nmake
program. Regardless of how you choose to compile and link your Visual Builder
application, use the following compile and link options:
B"/DE /pmtype:pm" Passes the string /DE /pmtype:pm to the linker as
parameters.
C Compiles and links.
Fb+ Generates Browser information in a file with a .pdb extension.
Ft(dir) Generates files for template resolution and puts them in the
dir directory.
Gd+ Dynamically links to the runtime library.
Gm+ Builds an .exe file.
I Searches the directory of the source file for include files;
then, searches paths specified in config.sys include variable.
Q Displays the compiler logo when invoking the compiler.
Ti+ Generates debugger information. This is optional but
recommended.
Tdp Compiles all source files as C++ files and ensures that
template functions are resolved.
For more information on compiling and linking, refer to the VisualAge C++
Programming Guide.
ΓòÉΓòÉΓòÉ 18. Using Existing C and C++ Code with Visual Builder ΓòÉΓòÉΓòÉ
What you will achieve
Defining the part interface using part information files
Creating a part information file
Importing the part
Personal notes:
ΓòÉΓòÉΓòÉ 18.1. What You Will Achieve ΓòÉΓòÉΓòÉ
This chapter describes how you can use your existing C and C++ code in
applications that you create with Visual Builder.
ΓòÉΓòÉΓòÉ 18.2. Defining the Part Interface Using Part Information Files ΓòÉΓòÉΓòÉ
If C++ code already exists for your Visual Builder application, you can more
efficiently define the part interface using part information files. This
involves the following steps:
1. Determine the part's features.
2. Create a part information file using your favorite editor. This file can
include information for as many parts as you need.
3. In Visual Builder, import the part.
ΓòÉΓòÉΓòÉ 18.2.1. Creating a Part Information File ΓòÉΓòÉΓòÉ
To create a part information file, add information about your part's part
interface to a file using your preferred editor. The following example shows
how you could specify part information for the OAContractor part:
//VBBeginPartInfo: OAContractor,"Contractor part for OASearch sample"
//VBParent: IStandardNotifier
//VBIncludes: "Cntrctor.hpp" _OACONTRACTOR_,"iprofile.hpp","istring.hpp","iexcbase.hpp"
//VBPartDataFile: OANONVIS.VBB
//VBConstructor: OAContractor()
//VBComposerInfo: nonvisual,802,cppov33r
//VBEvent: ready, "ready", readyId
//VBAction: getContractor,
//VB: "Get contractor data from database",
//VB: OAContractor&,
//VB: OAContractor& getContractor()
//VBAction: putContractor,
//VB: "Add or update contractor data in database",
//VB: OAContractor&,
//VB: OAContractor& putContractor()
//VBAction: parseName,
//VB: "Parse user input to get contractor's name",
//VB: OAContractor&,
//VB OAContractor& parseName(const IString& aName)
//VBAttribute: contractorID,
//VB: "Contractor's employee identifier",
//VB: IString,
//VB: IString contractorID() const,,
//VB: contractorIDId
//VBAttribute: lastName,
//VB: "Contractor's last name",
//VB: IString,
//VB: IString lastName() const,
//VB: OAContractor& setLastName(const IString& aLastName),
//VB: lastNameId
//VBAttribute: firstName,
//VB: "Contractor's first name",
//VB: IString,
//VB: IString firstName() const,
//VB: OAContractor& setFirstName(const IString& aFirstName),
//VB: firstNameId
//VBAttribute: middleInitial,
//VB: "Contractor's middle initial",
//VB: IString,
//VB: IString middleInitial() const,
//VB: OAContractor& setMiddleInitial(const IString& aMiddleInitial),
//VB: middleInitialId
//VBAttribute: homeStreet,
//VB: "Contractor's home street address",
//VB: IString,
//VB: IString homeStreet() const,
//VB: OAContractor& setHomeStreet(const IString& aHomeStreet),
//VB: homeStreetId
//VBAttribute: homeCity,
//VB: "Contractor's home city",
//VB: IString,
//VB: IString homeCity() const,
//VB: OAContractor& setHomeCity(const IString& aHomeCity),
//VB: homeCityId
//VBAttribute: homeState,
//VB: "Contractor's home state or province",
//VB: IString,
//VB: IString homeState() const,
//VB: OAContractor& setHomeState(const IString& aHomeState),
//VB: homeStateId
//VBAttribute: homeZip,
//VB: "Contractor's home postal code",
//VB: IString,
//VB: IString homeZip() const,
//VB: OAContractor& setHomeZip(const IString& aHomeZip),
//VB: homeZipId
//VBAttribute: phoneNumber,
//VB: "Contractor's daytime phone number",
//VB: IString,
//VB: IString phoneNumber() const,
//VB: OAContractor& setPhoneNumber(const IString& aPhoneNumber),
//VB: phoneNumberId
//VBAttribute: startDate,
//VB: "Contractor's starting date with OA",
//VB: IString,
//VB: IString startDate() const,
//VB: OAContractor& setStartDate(const IString& aStartDate),
//VB: startDateId
//VBAttribute: endDate,
//VB: "Contractor's last day with OA (empty if active)",
//VB: IString,
//VB: IString endDate() const,
//VB: OAContractor& setEndDate(const IString& aEndDate),
//VB: endDateId
//VBAttribute: activeStatus,
//VB: "Whether contractor actively seeks contract work",
//VB: Boolean,
//VB: Boolean isActiveStatus() const,
//VB: OAContractor& enableActiveStatus(Boolean enable = true),
//VB: activeStatusId
//VBAttribute: currentContract,
//VB: "Contractor's current assignment, if any",
//VB: IString,
//VB: IString currentContract() const,
//VB: OAContractor& setCurrentContract(const IString& aCurrentContract),
//VB: currentContractId
//VBPreferredFeatures: enabledForNotification, getContractor, putContractor, this
//VBEndPartInfo: OAContractor
Note the following syntax:
The VBBeginPartInfo and VBEndPartInfo statements delimit the part
information for OAContractor.
The VBPart statement specifies the base class for OAContractor,
IStandardNotifier*.
The VBIncludes statement specifies a header file to be added in an
#include directive when the code is generated.
The VBPartDataFile statement specifies the .vbb file that holds the
information for OAContractor.
The VBComposerInfo statement indicates that this is a nonvisual part. The
absence of the abstract keyword indicates that this is a concrete part
that can be dropped on the free-form surface.
The VBEvent, VBAction, and VBAttribute statements define features for
this part.
For information about part definition syntax, refer to Building VisualAge C++
Parts for Fun and Profit.
The next step is importing the part.
ΓòÉΓòÉΓòÉ 18.2.2. Importing the Part ΓòÉΓòÉΓòÉ
Before importing the part, you must create a part information file. To import
the part, follow these steps from the Visual Builder window:
1. From the menu bar, select File. Select Import part information.
The Enter Name for Part Information File window appears.
2. Specify the path and name of the part information file that contains the
information that you want to import. When the import is finished, the
name of the part appears in in the Visual Builder window.
If C++ code for your part already exists, your part is finished. If you want
to change the part interface later, do either of the following:
Use the Part Interface Editor to edit feature specifications. You must
use this method to delete features.
Edit your part information file and re-import the part information.
If C++ code for your part does not exist, the next step is adding code to your
part.
ΓòÉΓòÉΓòÉ 19. Adding Categories and Parts to the Parts Palette ΓòÉΓòÉΓòÉ
What you will achieve
Preparing icons for the parts palette
Adding a category to the parts palette
Specifying a unique icon for a part you add to the parts palette
Adding a part to the parts palette
Deleting a category or part from the parts palette
Saving parts palette changes
Personal notes:
ΓòÉΓòÉΓòÉ 19.1. What You Will Achieve ΓòÉΓòÉΓòÉ
The purpose of this chapter is to introduce you to the concepts and steps
involved in adding categories and parts to and removing categories and parts
from the parts palette. You can modify the parts palette at any time and from
any of the Visual Builder editors or from the Visual Builder window.
One reason to modify the parts palette is so that you can quickly and easily
place parts that you have created and that you use often on the free-form
surface. Otherwise, you have to place them by selecting OptionsAdd part, which
requires you to know the exact class name of the part that you are placing.
Another reason to modify the parts palette is to give everyone who is working
on the same project access to the same set of standardized parts. Your company
could have a parts builder who builds these standardized parts and puts them in
a category on the parts palette for you to use.
Group parts that behave similarly in the same category. You can see by looking
at the parts palette how we have grouped the parts that we provided into
categories based on their behavior. For example, all parts that are used for
data entry are in one category, all parts that contain and display lists are in
another category, and so forth.
This chapter contains an example that uses the OAContractor nonvisual part
created in Creating Nonvisual Parts, but you can use any part that you have
created. When you finish the example, you have a new OAModels category and a
new OAContractor part on the parts palette.
ΓòÉΓòÉΓòÉ 19.2. Preparing Icons for the Parts Palette ΓòÉΓòÉΓòÉ
Each category and part on the Visual Builder parts palette is represented by an
icon, so you can recognize it visually. With Visual Builder, you can create and
use your own icons when you extend the parts palette. If you do not, you can
still extend the parts palette and accept the default category icon, , and the
default part icon, .
This example uses for the OAModels category and for the OAContractor part,
which are stored in the cppov33r.dll file as resource numbers 800 and 802,
respectively.
To prepare icons for use with Visual Builder, do the following:
1. Create your icons. One way to do this is to use your operating system
toolkit icon editor.
For VGA displays on OS/2, use the Independent VGA form (32x32). For
higher display resolutions on OS/2, use the 8514-16 colors form (40x40).
2. Create a resource DLL that contains your icons. Use files similar to the
following:
userpal.c
empty()
{
}
userpal.rc
icon 800 oamodels.ico
icon 801 oacontractor.ico
userpal.def
library userpal
description 'Icons for user-extended palette'
userpal.mak
userpal.dll: userpal.obj userpal.def userpal.res
icc userpal.obj /Feuserpal.dll userpal.def
rc userpal.res userpal.dll
userpal.obj: userpal.c
icc /C+ userpal.c
userpal.res: userpal.rc
rc -r userpal.rc
Once you have the files ready, type the following to build the resource
DLL: nmake userpal.mak
3. Place the resource DLL in a directory in your LIBPATH.
Your icons are now ready for use with Visual Builder.
The next step is adding a category to the parts palette.
ΓòÉΓòÉΓòÉ 19.3. Adding a Category to the Parts Palette ΓòÉΓòÉΓòÉ
Now that you have your icons prepared in a resource DLL, you are ready to
extend the parts palette. To add a category to the parts palette, do the
following:
1. In the Composition Editor, select Modify PaletteAdd New Category from
the Options pull-down menu.
The Add palette category window is displayed as follows:
Notice that the default category icon, , is specified. It is stored as
resource ID 150 in the dde4vr30.dll resource file provided with Visual
Builder.
2. Type OAModels or the name that you want for your category in the Category
name field.
3. Type cppov33r or the name of your resource DLL in the Module name field.
Note: Do not type the .dll file extension in the Module name field.
4. Type 800 or the resource ID of the icon in your resource DLL in the ID
field.
Note: After you enter the resource ID number, move the cursor to another
component in the window, such as the Module name field, if you
want to see the graphic that will be used before continuing.
5. Select the OK push button.
Your category with the icon specified is added to the parts palette.
The next step is specifying a unique icon for your part.
ΓòÉΓòÉΓòÉ 19.4. Specifying a Unique Icon for a Part You Add to the Parts Palette ΓòÉΓòÉΓòÉ
You can specify a unique icon for a part that you add to the parts palette, but
you must do so before you add it to the parts palette. To give your part a
unique icon, do the following:
1. Open the part.
2. Switch to the Class Editor.
3. Enter the name of the DLL file that contains the icon you want to use in
the DLL Name field.
4. Enter the resource ID number for the icon in the Resource Id field.
If you enter a valid DLL file name and resource ID number, Visual Builder
displays the icon below the Resource Id field. This allows you to verify
the icon before adding it to the parts palette.
5. Select FileSave to save the resource DLL and resource ID information in
the Class Editor.
The next step is adding a part to the parts palette.
ΓòÉΓòÉΓòÉ 19.5. Adding a Part to the Parts Palette ΓòÉΓòÉΓòÉ
You can add a part to any category on the parts palette using any of the
following methods:
Adding a part that is selected in the Visual Builder window
Adding the part that you are currently editing
Adding any part whose .vbb file is loaded
ΓòÉΓòÉΓòÉ 19.5.1. Adding a Part That Is Selected in the Visual Builder Window ΓòÉΓòÉΓòÉ
To add a part to the parts palette from the Visual Builder window, do the
following:
1. Load the .vbb file that contains the part you want to add to the parts
palette if it is not already loaded.
2. Select the .vbb file. For this example, select oanonvis.vbb.
3. Select the part you want to add. For this example, select OAContractor.
Note: You can add multiple parts by holding down the Ctrl key and
clicking on each part that you want to add.
4. Select PartAdd to palette.
Visual Builder displays the Add to Palette window, as shown in the
following figure:
5. Select the part that you want to add. For this example, select
OAContractor.
6. Select the category that you want to add the part to. For this example,
select OAModels.
7. Select the Add push button.
Visual Builder adds the OAContractor part to the parts palette in the
OAModels category.
ΓòÉΓòÉΓòÉ 19.5.2. Adding the Part That You are Currently Editing ΓòÉΓòÉΓòÉ
You can add the part that you are currently editing to the parts palette from
either the Composition Editor, the Class Editor, or the Part Interface Editor.
To add the part that you are currently editing to the parts palette, do the
following:
1. Double-click on the OAContractor part in the Visual Builder window.
Visual Builder opens the OAContractor part in the Part Interface Editor.
2. Select FileAdd to palette.
Visual Builder displays the Add to Palette window, as shown in the
following figure:
The Part name field shows the name of the part that you are editing. This
is the part that is to be added to the parts palette. You cannot change
the name of the part displayed in this field. In this example,
OAContractor is displayed in this field.
3. Select the category that you want to add the part to. For this example,
select OAModels.
4. Select the Add push button.
The OAContractor part is added to the OAModels category on the parts
palette. To see this, switch to the Composition Editor and select the
OAModels category. The icon for the OAContractor part is displayed in the
parts column.
ΓòÉΓòÉΓòÉ 19.5.3. Adding Any Part Whose .vbb File Is Loaded ΓòÉΓòÉΓòÉ
You can add any part to the parts palette as long as its .vbb file is loaded in
the Visual Builder window. The following steps explain how to do this:
1. In the Composition Editor, select Modify PaletteAdd New Part from the
Options pull-down menu. The Add to Palette window is displayed as shown
in the following figure:
To add a part to the parts palette, do the following:
a. Type OAContractor in the Part name field or the class name of the
part you want to add.
b. Select OAModels in the Category list or the name of the category to
which you want to add your part.
c. Select the Add push button.
Your part is added to the parts palette in the specified category.
Notice that the part you just added uses the same icon as the part it inherits
from. If you inherit from a part whose icon does not appear on the parts
palette, such as IStandardNotifier*, or for which you have not provided a
resource DLL, Visual Builder uses the default part icon, .
The next section tells you how to delete a category or part from the parts
palette
ΓòÉΓòÉΓòÉ 19.6. Deleting a Category or Part from the Parts Palette ΓòÉΓòÉΓòÉ
To delete a part from the parts palette, do the following:
1. Select the part on the parts palette.
2. Select Modify PaletteDelete Part from the Options pull-down menu.
The selected part is deleted from the parts palette.
To delete a category from the parts palette, do the following:
1. Select the category on the parts palette.
2. Select Modify PaletteDelete Category from the Options pull-down menu.
The selected category and all of the parts in it are deleted from the
parts palette.
ΓòÉΓòÉΓòÉ 19.7. Saving Parts Palette Changes ΓòÉΓòÉΓòÉ
Visual Builder automatically saves all parts palette changes for you. When you
create a new category or part, Visual Builder stores information about that
category or part in a file named vbpalet.dat, which is stored in your current
directory. This file is written automatically.
Once you add or delete categories or parts, the vbpalet.dat file is read each
time you start Visual Builder. The information this file contains causes any
categories or parts that you have added to be included on the parts palette. It
also prevents any categories or parts that you have deleted from appearing on
the parts palette.
If you update the icon associated with a part, the parts palette is updated the
next time you select the category in which the icon appears.
Removing a category or part that you just added
The vbpalet.dat file also allows you to undo and redo any changes you make to
the parts palette, but only during the current Composition Editor session. For
example, after adding a category or part, you can select EditUndo to remove
the part or category you just added. Selecting EditRedo would put the part or
category back on the parts palette, again.
Once you close the Composition Editor, you can no longer undo or redo any
changes. However, you can still add categories and add parts, as well as delete
categories and parts.
ΓòÉΓòÉΓòÉ 20. Enabling National Language Support ΓòÉΓòÉΓòÉ
Introduction
Using resource files for translation
Using canvases to adjust size for translated text
Specifying parts with country-sensitive formatting
Providing double-byte character support for Asian languages
Personal notes:
ΓòÉΓòÉΓòÉ 20.1. Introduction ΓòÉΓòÉΓòÉ
Because many languages exist in the world today, consider designing your
applications to be language friendly; that is, user-friendly for all languages.
There are several different aspects to consider when creating an application
that is language friendly:
First, there is the text that the user sees. This text includes labels in
your windows and messages that are displayed.
Next, there is specific country information. This includes date
separators and time formats.
Finally, some languages include characters that require two bytes to
represent those characters and are primarily found in the Asian
languages, such as Japanese.
A good rule to follow: Do not place any translatable text or
country symbols directly into your source code. Place them in an
external file where they are easily accessible for translation.
Visual Builder provides for ease of national language support in the following
ways:
Using resource files for translation
Using canvases to adjust the size for translated text
Specifying data types with country-sensitive formatting
Providing double-byte character set (DBCS) support for Asian languages
For additional information about national language and DBCS support, refer to
the IBM Open Class Library User's Guide.
ΓòÉΓòÉΓòÉ 20.2. Using Resource Files for Translation ΓòÉΓòÉΓòÉ
In Generating Source Code for Parts and Applications, you learned that Visual
Builder generates the following resource files for you:
A resource file (partname.rc), which contains the text strings used in
your part
A resource header file (partname.h), which contains the resource IDs for
your application
The resource (partname.rc) file
The .rc file groups resources into two categories:window resources and
nonwindow resources. The window resources are the text strings that are
associated with window IDs for information area text and fly-over text.
The nonwindow resources are the text strings that are displayed in your
composite part. Examples are window titles, static text used to label entry
fields and list boxes, and the text on push buttons and menu items. These text
strings are delimited by quotation marks (") and can be translated into
another language.
Here is the todolist.rc file that we generated for the To-Do List application
shown in Creating a Simple Visual Builder Application:
//*************************************************************
// Resource file for: ToDoList.cpp
//*************************************************************
#include "ToDoList.h"
#include <os2.h>
#ifndef MAIN_RESOURCES_INCLUDED
#define MAIN_RESOURCES_INCLUDED
HELPTABLE WND_ToDoList
BEGIN
HELPITEM WND_ToDoList_FrameWindow, WND_ToDoList_FrameWindow, 0
END
#define ToDoList_WINDOWRESOURCES
#define ToDoList_NONWINDOWRESOURCES
STRINGTABLE
BEGIN
1, "Visual Builder 3.0"
END
#endif
#ifdef ToDoList_NONWINDOWRESOURCES
#ifndef ToDoList_NONWINDOWRESOURCES_INCLUDED
#define ToDoList_NONWINDOWRESOURCES_INCLUDED
STRINGTABLE
BEGIN
STRRC_ToDoList_FrameWindow_title, "To-Do List"
STRRC_ToDoList_StaticText1_text, "To-do item"
STRRC_ToDoList_EntryField1_text, ""
STRRC_ToDoList_StaticText2_text, "To-do list"
STRRC_ToDoList_PushButton1_text, "Add"
STRRC_ToDoList_PushButton2_text, "Remove"
END
#endif
#endif
#ifdef ToDoList_WINDOWRESOURCES
HELPSUBTABLE (WND_ToDoList_FrameWindow)
BEGIN
END
#endif
#ifdef ToDoList_HELPITEMRESOURCES
HELPITEM WND_ToDoList_FrameWindow, WND_ToDoList_FrameWindow, 0
#endif
#ifdef ToDoList_HELPSUBITEMRESOURCES
#endif
The window resources and nonwindow resources are grouped into separate string
tables so that translators can easily find the text that is to be translated.
You may have text strings in your part, such as the application name, that you
do not want translated. If that is the case, you can prevent those text
strings from being inserted in the .rc file by inserting a number sign (#) at
the beginning of the text and enclosing the text in quotation marks ("). This
change must be made in the settings notebook for the part, not in the
Composition Editor.
For example, suppose you do not want the text in the window title, To-Do List,
to be translated. To prevent Visual Builder from inserting this text string in
the .rc file, you would open the settings notebook for the ToDoList part, find
the entry field on the General page that contains the title text, and change
it to the following:
#"To-Do List"
Notice that each text string that Visual Builder inserts in the .rc file is
preceded by a #define statement that begins with STRRC. These #define
statements represent the resource ID of each text string. Visual Builder
generates these #define statements and defines them in the partname.h file. By
inserting and defining these #define statements, Visual Builder relieves you
from the task of having to specify resource IDs for each text string.
To help Visual Builder generate these #define statements properly, you must
enter the starting resource ID for your part. The following section explains
how to do this.
The resource header (partname.h) file
The .h file contains a list of #define statements. Visual Builder uses these
#define statements in the .rc file to assign unique resource IDs to each of
the text strings that you use to create your composite part and a unique
window ID to all primitive visual parts. The only resource ID that you need to
specify is the starting resource ID for the part.
Here is the todolist.h file that we generated for the To-Do List application
shown in Creating a Simple Visual Builder Application:
//*************************************************************
// Resource header file for: ToDoList.cpp
//*************************************************************
#ifndef _ICCONST_
#include <icconst.h>
#endif
#ifndef _IVBDEFS_
#include <ivbdefs.h>
#endif
#ifndef RC_ToDoList
#define RC_ToDoList 10000
#endif
#ifndef WND_ToDoList
#define WND_ToDoList VBBASEWINDOWID
#endif
#define WNDOFFSET_ToDoList_FrameWindow 0
#define WND_ToDoList_FrameWindow WND_ToDoList
#define STRRC_ToDoList_FrameWindow_title RC_ToDoList+0
#define WNDOFFSET_ToDoList_Canvas 1
#define WND_ToDoList_Canvas WND_ToDoList + WNDOFFSET_ToDoList_Canvas
#define WNDOFFSET_ToDoList_StaticText1 2
#define WND_ToDoList_StaticText1 WND_ToDoList + WNDOFFSET_ToDoList_StaticText1
#define STRRC_ToDoList_StaticText1_text RC_ToDoList+1
#define WNDOFFSET_ToDoList_EntryField1 3
#define WND_ToDoList_EntryField1 WND_ToDoList + WNDOFFSET_ToDoList_EntryField1
#define STRRC_ToDoList_EntryField1_text RC_ToDoList+2
#define WNDOFFSET_ToDoList_StaticText2 4
#define WND_ToDoList_StaticText2 WND_ToDoList + WNDOFFSET_ToDoList_StaticText2
#define STRRC_ToDoList_StaticText2_text RC_ToDoList+3
#define WNDOFFSET_ToDoList_PushButton1 5
#define WND_ToDoList_PushButton1 WND_ToDoList + WNDOFFSET_ToDoList_PushButton1
#define STRRC_ToDoList_PushButton1_text RC_ToDoList+4
#define WNDOFFSET_ToDoList_PushButton2 6
#define WND_ToDoList_PushButton2 WND_ToDoList + WNDOFFSET_ToDoList_PushButton2
#define STRRC_ToDoList_PushButton2_text RC_ToDoList+5
#define WNDOFFSET_ToDoList_ListBox1 7
#define WND_ToDoList_ListBox1 WND_ToDoList + WNDOFFSET_ToDoList_ListBox1
Find the first #define statement in the todolist.h file. It is the RC_ToDoList
#define statement. The number to the right of this #define statement, 10000,
is the starting resource ID. This is the default number that Visual Builder
inserts when you select the check box next to the Starting resource id field
in the Class Editor. Visual Builder uses this number as the resource ID of the
first text string and increments the resource ID of each successive text
string by 1.
We chose to use the default number 10000 for the following reasons:
The resource ID must be a number.
The number specified must be either high enough or low enough that it
does not conflict with the resource IDs that Visual Builder generates for
the primitive parts (entry field, push buttons, and so forth) that are
used to compose the ToDoList part.
When determining resource IDs for window resources, Visual Builder begins with
15000 and increments the resource ID of each successive primitive part by 5.
Therefore, we recommend using starting resource IDs between 100 and 14500 for
most applications for the following reasons:
You should not use resource IDs below 100 because Presentation Manager
has reserved many of them for its own use.
Numbers between 100 and 14500 are low enough to prevent you from
experiencing any resource ID conflicts in most cases.
Specifying the starting resource ID for subparts
If you use a part that you have created as a subpart, specify a starting
resource ID for both the subpart and the part in which the subpart is
embedded. Do this to prevent conflicts between the resource IDs that Visual
Builder generates for your subpart and those it generates for the part in
which the subpart is embedded, as described in the preceding section.
Otherwise, Visual Builder uses the same starting resource IDs for both the
subpart and the part in which it is embedded, which causes compile errors.
For example, suppose you have a reusable Address part (a canvas with entry
fields and static text) that you want to embed as a subpart in the frame
window of your application's main view. You might give the main view a
starting resource ID of 5000 and the Address part a starting resource ID of
6000. Doing this would prevent conflicts with the resource IDs that Visual
Builder generates for the main view and those it generates for the Address
part.
ΓòÉΓòÉΓòÉ 20.3. Using Canvases to Adjust Size for Translated Text ΓòÉΓòÉΓòÉ
When text is translated from one language to another, the translated text often
occupies more space than the original text occupied. This can cause problems
because the layout of the user interface can be disrupted by the longer text
strings.
Two of the canvas parts that Visual Builder provides solve this problem for
you: ISetCanvas* and IMultiCellCanvas*. These parts allow you to insert
translated text and rebuild your application without having to change the
position of any of the parts in the user interface. The ISetCanvas* and
IMultiCellCanvas* parts automatically adjust their size at run time to allow
for longer text strings, taking into account the current window's text size and
font.
For example, suppose you are using an ISetCanvas* part with three vertical
decks and three rows of IRadioButton* parts in each deck. Once the text strings
for the IRadioButton* parts are translated, all you have to do is rebuild your
application. The decks in the ISetCanvas* part automatically adjust their
widths to allow for the size of the translated text strings.
The IMultiCellCanvas part is also good for translation purposes because the
rows and columns automatically adjust themselves to fit the translated text.
ΓòÉΓòÉΓòÉ 20.4. Specifying Parts with Country-Sensitive Formatting ΓòÉΓòÉΓòÉ
Visual Builder provides the following class interface parts that allow you to
specify how information is presented for specific national languages:
IDate This part allows you to customize the date formatting for the
selected part. This includes specifying the order for the month,
day, and year, and the character to use as a separator.
ITime This part allows you to customize the time formatting for the
selected part. This includes specifying the 12- or 24-hour format
and the character to use as a separator.
ΓòÉΓòÉΓòÉ 20.5. Providing Double-Byte Character Support for Asian Languages ΓòÉΓòÉΓòÉ
The following Visual Builder parts provide DBCS support:
IBuffer
Class interface part that defines the contents of an IString. This part
provides attributes to determine whether part or all of the characters in a
buffer are DBCS or multi-byte character set (MBCS) characters, and whether
they are valid DBCS or MBCS characters.
IDBCSBuffer
Class interface part that implements the version of IString contents that
supports mixed OS/2 DBCS characters. This part ensures that MBCS characters
are processed properly.
IEntryField
Visual part that creates and manages an entry field control. On the General
page of the settings notebook for this part, you can specify the type of
data that the user can enter. It can be one of the following:
SBCS Sets the entry field to accept SBCS text only.
DBCS Sets the entry field to accept DBCS text only.
Mixed Sets the entry field to accept text that is a mixture of SBCS
and DBCS characters. Conversion from an ASCII DBCS code page
to an EBCDIC DBCS code page can result in a possible increase
in the length of the data because of the addition of shift-in
and shift-out characters, but it does not exceed the text
limit of the entry field.
Any Sets the entry field to accept text that is a mixture of SBCS
and DBCS characters. This setting is the opposite of mixed.
If the text contains both SBCS and DBCS characters and is to
be converted from an ASCII code page into an EBCDIC code
page, this style causes an entry field to not account for
shift-in and shift-out characters that would be introduced
into its text.
IFrameWindow
Visual part that creates and manages a frame window control. This part has a
style option, appDBCSStatus, that includes a DBCS status area in the frame
window when it is displayed in a DBCS environment. IFrameWindow also has a
member function, shareParentDBCSStatus, that causes a child frame window to
share the DBCS status area of its parent.
IKeyboardEvent
Class interface part that represents a keyboard-related event. An
IKeyboardEvent object is created by a keyboard handler when a user presses
or releases a key. The part provides a virtualKey attribute that returns the
virtual key code of the key. Two of the codes it can return are firstDBCS
and lastDBCS.
IString
Class interface part that is an array of characters. This part provides
attributes to determine whether part or all of the characters in a string
are DBCS or MBCS characters, and whether they are valid DBCS or MBCS
characters.
ΓòÉΓòÉΓòÉ 21. Using Direct-to-SOM Objects ΓòÉΓòÉΓòÉ
Introduction
Creating and importing the part information file
Using DTS objects in a Visual Builder application
Bypassing DTS limitations
Personal notes:
ΓòÉΓòÉΓòÉ 21.1. Introduction ΓòÉΓòÉΓòÉ
This chapter shows you how to use a Direct-to-SOM object in a Visual Builder
application. SOM is the IBM System Object Model, which defines an interface
between programs, or between libraries and programs, so that an object's
interface is separated from its implementation. SOM allows classes of objects
to be defined in one programming language and used in another, and it allows
libraries of such classes to be updated without requiring client code to be
recompiled.
You can make classes and member functions in existing C++ programs
SOM-accessible without having to rewrite class and member function definitions.
You do this by adding SOM C++ compiler directives to your code. Although SOM
imposes some restrictions on C++ coding conventions, you should be able to
convert most C++ programs for SOM support with minimal effort.
VisualAge C++ can convert existing C++ classes to SOM classes. The
VisualAge C++ compiler translates C++ code into Interface Definition Language
(IDL) code, which you then compile with the SOM compiler to create your SOM
objects. This method of creating SOM objects is referred to as the C++
Direct-to-SOM, or DTS, method. Currently, the only SOM objects that Visual
Builder supports are DTS objects.
To use a DTS object in an Visual Builder application you must do the following:
1. Create the DTS object or objects.
You will need the .hh and .lib files that you created in this step when
compiling your Visual Builder application. You need the .dll when you run
your compiled Visual Builder application.
The DTS objects that you create must have the following characteristics:
DTS objects can have actions only; no attributes or events are
allowed. DTS objects are not able to notify other parts when events
occur. Therefore, no events or attribute event identifiers can be
used.
You can implement actions using C++ and classes in the IBM Open
Class Library. However, the actions can return only basic C data
types and their parameters must be basic C data types. For example,
instead of returning an IString data type, an action could return a
char*.
To learn how Visual Builder can help you avoid the DTS restrictions
stated in the preceding list, see Bypassing DTS Limitations.
2. Create and import a part information file (.vbe file) for your DTS
objects.
3. Create a Visual Builder application using DTS objects.
4. Generate and compile the code.
5. Run your application.
Make sure you have the .dll for the DTS object for this step.
The sections that follow assume that you have already created your DTS object
or objects, so they only discuss creating and importing the part information
file, and creating a Visual Builder application using DTS objects.
For information on creating DTS objects, refer to the VisualAge C++ User's
Guide. For information on generating and compiling your Visual Builder
application code, see Generating Source Code for Parts and Applications.
We begin with creating and importing the part information file.
ΓòÉΓòÉΓòÉ 21.2. Creating and Importing the Part Information File ΓòÉΓòÉΓòÉ
In Defining the Part Interface Using Part Information Files, you learned how to
create a part information file. Create a file like this for your DTS objects.
There are only two requirements when creating this file:
As we explained in the preceding section, DTS objects can only have
actions. This makes DTS objects the equivalent of class interface parts
because they have no notification capability. Therefore, you must set the
VBComposerInfo statement for each DTS object to class.
Since DTS objects can only have actions, you cannot code any attributes
or events in your part information file.
The following example shows a part information file, mydtsdt.vbe, that
contains the information for the following sample DTS objects:
MyDTSDate Returns the current date.
MyDTSTime Returns the current time.
//
// SOM classes as Visual Builder classes
//
//VBBeginPartInfo: MyDTSDate, "My DTS SOM Date Class"
//VBIncludes: "mydtsdat.hh" MyDTSDate_hh
//VBPartDataFile: 'mydtsdt.vbb'
//VBLibFile: 'mydtsdat.lib'
//VBComposerInfo: class
//VBAction: getTodaysDate
//VB: ,"Get today's date action.",char*,
//VB: char* getTodaysDate()
//VBPreferredFeatures: this, getTodaysDate
//VBEndPartInfo: MyDTSDate
//
//VBBeginPartInfo: MyDTSTime, "My DTS SOM Time Class"
//VBIncludes: "mydtstim.hh" MyDTSTime_hh
//VBPartDataFile: 'mydtsdt.vbb'
//VBLibFile: 'mydtstim.lib'
//VBComposerInfo: class
//VBAction: getCurrentTime
//VB: ,"Get current time action.",char*,
//VB: char* getCurrentTime()
//VBPreferredFeatures: this, getCurrentTime
//VBEndPartInfo: MyDTSTime
//
The mydtsdt.vbe file contains statements that refer to the following files
that are needed for each of the sample DTS objects:
mydtsdat.hh and mydtstim.hh The header files for the MyDTSDate and MyDTSTime
SOM classes.
mydtsdat.lib and mydtstim.lib The library files that were created when the DTS
objects were compiled.
mydtsdt.vbb The part (.vbb) file that is to contain the information about
the DTS parts when you import the part information from the
mydtsdt.vbe file. You must load the mydtsdt.vbb file into
Visual Builder before you can add the MyDTSDate and MyDTSTime
parts to the free-form surface in the Composition Editor.
Once you create your part information file, you must import it into Visual
Builder before you can use your DTS objects in a Visual Builder application.
For information on how to do this, see Importing Part Information.
The next step is using DTS objects in a Visual Builder application.
ΓòÉΓòÉΓòÉ 21.3. Using DTS Objects in a Visual Builder Application ΓòÉΓòÉΓòÉ
Using DTS objects in a Visual Builder application is no different from using a
class interface part. You simply place the DTS objects on the free-form surface
and make the necessary connections to use their actions.
The following figure shows how we used the MyDTSDate and MyDTSTime objects in a
simple application.
To create the application, we placed the MyDTSDate and MyDTSTime parts on the
free-form surface by selecting OptionsAdd part and providing the necessary
information in the Add Part window for each part.
In this application, when a user clicks on the Current push button, the
buttonClickEvent feature causes the getTodaysDate and getTodaysTime actions to
get the date and time that is currently set in your computer's operating
system. In addition, the actionResult attribute of each connection updates the
text attribute of each entry field with the result of the two actions, the
current date and time.
Earlier, we mentioned that actions in DTS classes can return only basic C data
types. The getTodaysDate and getTodaysTime actions in our example both return a
data type of char*. Therefore, when we connected the actionResult attribute to
the text attribute of the entry field, Visual Builder displayed a message
saying that the types did not match and asking if we wanted to continue. In
this case, we could make the connection because IString has a constructor that
takes a char*. You can find out whether to complete a connection in situations
like this by looking at the IBM Open Class Library Reference.
When you have generated your code and are ready to compile your
application, make sure you have the .hh and .lib files that contain
the code for your DTS objects in the current directory. Also, make
sure the SOM Toolkit is installed because the VisualAge C++ compiler
must have access to several of its files.
When you are ready to run your application, the .dll for the DTS
objects must be accessible.
ΓòÉΓòÉΓòÉ 21.4. Bypassing DTS Limitations ΓòÉΓòÉΓòÉ
Earlier, we told you that DTS objects have certain limitations, such as not
being able to use attributes and events, and not being able to notify other
parts. You can bypass these limitations by using nonvisual parts to manage the
things your DTS objects cannot do.
In the example shown in Using DTS Objects in a Visual Builder Application, we
could have created two nonvisual parts called MyDate and MyTime in addition to
the two DTS parts, MyDTSDate and MyDTSTime. We could give these nonvisual parts
attributes such as theDate and theTime and notify other parts when the values
of these attributes change. We could also give these attributes get and set
member functions that call actions in the DTS objects to get and set the values
of the attributes.
Once this is done, we would place the nonvisual parts MyDate and MyTime on the
free-form surface, instead of MyDTSDate and MyDTSTime, and make the same
connections as described previously.
ΓòÉΓòÉΓòÉ 22. Glossary ΓòÉΓòÉΓòÉ
ΓòÉΓòÉΓòÉ <hidden> Glossary description ΓòÉΓòÉΓòÉ
This glossary defines terms and abbreviations that are used in this book. If
you do not find the term you are looking for, refer to the IBM Dictionary of
Computing, New York:McGraw-Hill, 1994.
This glossary includes terms and definitions from the American National
Standard Dictionary for Information Systems, ANSI X3.172-1990, copyright 1990
by the American National Standards Institute (ANSI). Copies may be purchased
from the American National Standards Institute, 1430 Broadway, New York, New
York 10018.
ΓòÉΓòÉΓòÉ <hidden> Glossary listing ΓòÉΓòÉΓòÉ
A
abstract class
access
action
argument
attribute
attribute-to-action connection
attribute-to-attribute connection
attribute-to-member function connection
B
base class
behavior
C
caller
category
class
Class Editor
class hierarchy
class library
class member function
client area object
client object
collection
Common User Access (CUA)
composite part
Composition Editor
concrete class
connection
const
construction from parts
constructor
CUA
cursored emphasis
custom logic connection
D
data abstraction
data member
data model
data object
declaration
DEF file
derivation
destructor
DLL
dynamic link library (DLL)
E
encapsulation
event
event-to-action connection
event-to-attribute connection
event-to-member function connection
expansion area
F
feature
full attribute
free-form surface
G
graphical user interface (GUI)
GUI
H
handles
header file
I
inheritance
instance
L
legacy code
loaded
M
main part
member
member function
member function call
member function name
message
model
module definition file
N
nested class
nonvisual part
no-event attribute
no-set attribute
notebook part
O
object
object class
object factory
object-oriented programming
observer
operation
overloading
P
palette
parameter connection
parent class
part
part event
part event ID
part interface
Part Interface Editor
parts palette
preferred features
primary selection
private
process
program
protected
prototype
primitive part
process
property
pure virtual function
R
receiver
resource file
S
selection handles
server
service
settings view
sticky
structure
subpart
superclass
T
tear-off attribute
template
thread
tool bar
U
UI
unloaded
user interface (UI)
V
variable
view
virtual function
visual part
visual programming tool
W
white space
window
ΓòÉΓòÉΓòÉ <hidden> abstract class ΓòÉΓòÉΓòÉ
A class that provides common behavior across a set of subclasses but is not
itself designed to have instances that work. An abstract class represents a
concept; classes derived from it represent implementations of the concept. For
example, IControl is the abstract base class for control view windows; the
ICanvas and IListBox classes are controls derived from IControl. An abstract
class must have at least one pure virtual function.
See also base class.
ΓòÉΓòÉΓòÉ <hidden> access ΓòÉΓòÉΓòÉ
A property of a class that determines whether a class member is accessible in
an expression or declaration.
ΓòÉΓòÉΓòÉ <hidden> action ΓòÉΓòÉΓòÉ
A specification of a function that a part can perform. The visual builder uses
action specifications to generate connections between parts. Actions are
resolved to member function calls in the generated code.
Compare to event and attribute.
ΓòÉΓòÉΓòÉ <hidden> argument ΓòÉΓòÉΓòÉ
A data element, or value, included as part of a member function call. Arguments
provide additional information that the called member function can use to
perform the requested operation.
ΓòÉΓòÉΓòÉ <hidden> attribute ΓòÉΓòÉΓòÉ
A specification of a property of a part. For example, a customer part could
have a name attribute and an address attribute. An attribute can itself be a
part with its own behavior and attributes.
The visual builder uses attribute specifications to generate code to get and
set part properties.
Compare to event and action.
ΓòÉΓòÉΓòÉ <hidden> attribute-to-action connection ΓòÉΓòÉΓòÉ
A connection that starts an action whenever an attribute's value changes. It is
similar to an event-to-action connection because the attribute's event ID is
used to notify the action when the value of the attribute changes.
See also connection. Compare to event-to-action connection.
ΓòÉΓòÉΓòÉ <hidden> attribute-to-attribute connection ΓòÉΓòÉΓòÉ
A connection from an attribute of one part to an attribute of another part.
When one attribute is updated, the other attribute is updated automatically.
See also connection.
ΓòÉΓòÉΓòÉ <hidden> attribute-to-member function connection ΓòÉΓòÉΓòÉ
A connection from an attribute of a part to a member function. The connected
attribute receives its value from the member function, which can make
calculations based on the values of other parts.
See also connection.
ΓòÉΓòÉΓòÉ <hidden> base class ΓòÉΓòÉΓòÉ
A class from which other classes or parts are derived. A base class may itself
be derived from another base class.
See also abstract class.
ΓòÉΓòÉΓòÉ <hidden> behavior ΓòÉΓòÉΓòÉ
The set of external characteristics that an object exhibits.
ΓòÉΓòÉΓòÉ <hidden> caller ΓòÉΓòÉΓòÉ
An object that sends a member function call to another object.
Contrast with receiver.
ΓòÉΓòÉΓòÉ <hidden> category ΓòÉΓòÉΓòÉ
In the Composition Editor, a selectable grouping of parts represented by an
icon in the left-most column. Selecting a category displays the parts belonging
to that category in the next column.
See also parts palette.
ΓòÉΓòÉΓòÉ <hidden> class ΓòÉΓòÉΓòÉ
An aggregate that can contain functions, types, and user-defined operators, in
addition to data. Classes can be defined hierarchically, allowing one class to
be an expansion of another, and can restrict access to its members.
ΓòÉΓòÉΓòÉ <hidden> Class Editor ΓòÉΓòÉΓòÉ
The editor you use to specify the names of files that Visual Builder writes to
when you generate default code. You can also use this editor to do the
following:
Enter a description of the part
Specify a different .vbb file in which to store the part
See the name of the part's base class
Modify the part's default constructor
Enter additional constructor and destructor code
Specify a .lib file for the part
Specify a resource DLL and ID to assign an icon to the part
Specify other files that you want to include when you build your
application
Compare to Composition Editor and Part Interface Editor.
ΓòÉΓòÉΓòÉ <hidden> class hierarchy ΓòÉΓòÉΓòÉ
A tree-like structure showing relationships among object classes. It places one
abstract class at the top (a base class) and one or more layers of less
abstract classes below it.
ΓòÉΓòÉΓòÉ <hidden> class library ΓòÉΓòÉΓòÉ
A collection of classes.
ΓòÉΓòÉΓòÉ <hidden> class member function ΓòÉΓòÉΓòÉ
See member function.
ΓòÉΓòÉΓòÉ <hidden> client area object ΓòÉΓòÉΓòÉ
An intermediate window between a frame window (IFrameWindow) and its controls
and other child windows.
ΓòÉΓòÉΓòÉ <hidden> client object ΓòÉΓòÉΓòÉ
An object that requests services from other objects.
ΓòÉΓòÉΓòÉ <hidden> collection ΓòÉΓòÉΓòÉ
A set of features in which each feature is an object.
ΓòÉΓòÉΓòÉ <hidden> Common User Access (CUA) ΓòÉΓòÉΓòÉ
An IBM architecture for designing graphical user interfaces using a set of
standard components and terminology.
ΓòÉΓòÉΓòÉ <hidden> composite part ΓòÉΓòÉΓòÉ
A part that is composed of a part and one or more subparts. A composite part
can contain visual parts, nonvisual parts, or both.
See also nonvisual part, part, subpart, and visual part.
ΓòÉΓòÉΓòÉ <hidden> Composition Editor ΓòÉΓòÉΓòÉ
A view that is used to build a graphical user interface and to make connections
between parts.
Compare to Class Editor and Part Interface Editor.
ΓòÉΓòÉΓòÉ <hidden> concrete class ΓòÉΓòÉΓòÉ
A subclass of an abstract class that is a specialization of the abstract class.
ΓòÉΓòÉΓòÉ <hidden> connection ΓòÉΓòÉΓòÉ
A formal, explicit relationship between parts. Making connections is the basic
technique for building any visual application because that defines the way in
which parts communicate with one another. The visual builder generates the code
that then implements these connections.
See also attribute-to-action connection, attribute-to-attribute connection,
attribute-to-member function connection, parameter connection, custom logic
connection, event-to-action connection, event-to-attribute connection, and
event-to-member function connection.
ΓòÉΓòÉΓòÉ <hidden> const ΓòÉΓòÉΓòÉ
An attribute of a data object that declares that the object cannot be changed.
ΓòÉΓòÉΓòÉ <hidden> construction from parts ΓòÉΓòÉΓòÉ
A software development technology in which applications are assembled from
existing and reusable software components, known as parts.
ΓòÉΓòÉΓòÉ <hidden> constructor ΓòÉΓòÉΓòÉ
A special class member function that has the same name as the class and is used
to construct and possibly initialize class objects.
ΓòÉΓòÉΓòÉ <hidden> CUA ΓòÉΓòÉΓòÉ
See Common User Access.
ΓòÉΓòÉΓòÉ <hidden> cursored emphasis ΓòÉΓòÉΓòÉ
When the selection cursor is on a choice, that choice has cursored emphasis.
ΓòÉΓòÉΓòÉ <hidden> custom logic connection ΓòÉΓòÉΓòÉ
A connection that causes your customized C or C++ code to be run. This
connection can be triggered either when an attribute's value changes or an
event occurs.
ΓòÉΓòÉΓòÉ <hidden> data abstraction ΓòÉΓòÉΓòÉ
A data type with a private representation and a public set of operations. The
C++ language uses the concept of classes to implement data abstraction.
ΓòÉΓòÉΓòÉ <hidden> data member ΓòÉΓòÉΓòÉ
Private data that belongs to a given object and is hidden from direct access by
all other objects. Data members can only be accessed by the member functions of
the defining class and its subclasses.
ΓòÉΓòÉΓòÉ <hidden> data model ΓòÉΓòÉΓòÉ
A combination of the base classes and parts shipped with the product and the
classes and parts you save and create. They are saved in a file named
vbbase.vbb.
ΓòÉΓòÉΓòÉ <hidden> data object ΓòÉΓòÉΓòÉ
A storage area used to hold a value.
ΓòÉΓòÉΓòÉ <hidden> declaration ΓòÉΓòÉΓòÉ
A description that makes an external object or function available to a function
or a block.
ΓòÉΓòÉΓòÉ <hidden> DEF file ΓòÉΓòÉΓòÉ
See module definition file.
ΓòÉΓòÉΓòÉ <hidden> derivation ΓòÉΓòÉΓòÉ
The creation of a new or abstract class from an existing or base class.
ΓòÉΓòÉΓòÉ <hidden> destructor ΓòÉΓòÉΓòÉ
A special class member function that has the same name as the class and is used
to destruct class objects.
ΓòÉΓòÉΓòÉ <hidden> DLL ΓòÉΓòÉΓòÉ
See dynamic link library.
ΓòÉΓòÉΓòÉ <hidden> dynamic link library (DLL) ΓòÉΓòÉΓòÉ
In OS/2, a library containing data and code objects that can be used by
programs or applications during loading or at run time. Although they are not
part of the program's executable (.exe) file, they are sometimes required for
an .exe file to run properly.
ΓòÉΓòÉΓòÉ <hidden> encapsulation ΓòÉΓòÉΓòÉ
The hiding of a software object's internal representation. The object provides
an interface that queries and manipulates the data without exposing its
underlying structure.
ΓòÉΓòÉΓòÉ <hidden> event ΓòÉΓòÉΓòÉ
A specification of a notification from a part.
Compare to action, attribute, and part event.
ΓòÉΓòÉΓòÉ <hidden> event-to-action connection ΓòÉΓòÉΓòÉ
A connection that causes an action to be performed when an event occurs.
See also connection.
ΓòÉΓòÉΓòÉ <hidden> event-to-attribute connection ΓòÉΓòÉΓòÉ
A connection that changes the value of an attribute when a certain event
occurs.
See also connection.
ΓòÉΓòÉΓòÉ <hidden> event-to-member function connection ΓòÉΓòÉΓòÉ
A connection from an event of a part to a member function. When the connected
event occurs, the member function is executed.
See also connection.
ΓòÉΓòÉΓòÉ <hidden> expansion area ΓòÉΓòÉΓòÉ
The section of a multicell canvas between the current cell grid and the outer
edge of the canvas. Visually, this area is bounded by the rightmost column
gridline and the bottommost row gridline.
ΓòÉΓòÉΓòÉ <hidden> feature ΓòÉΓòÉΓòÉ
A major component of a software product that can be installed separately.
In Visual Builder, an action, attribute, or event that is available from a
part's part interface and that other parts can connect to.
ΓòÉΓòÉΓòÉ <hidden> full attribute ΓòÉΓòÉΓòÉ
An attribute that has all of the behaviors and characteristics that an
attribute can have: a data member, a get member function, a set member
function, and an event identifier.
ΓòÉΓòÉΓòÉ <hidden> free-form surface ΓòÉΓòÉΓòÉ
The large open area of the Composition Editor window. The free-form surface
holds the visual parts contained in the views you build and representations of
the nonvisual parts (models) that your application includes.
ΓòÉΓòÉΓòÉ <hidden> graphical user interface (GUI) ΓòÉΓòÉΓòÉ
A type of interface that enables users to communicate with a program by
manipulating graphical features, rather than by entering commands. Typically, a
graphical user interface includes a combination of graphics, pointing devices,
menu bars and other menus, overlapping windows, and icons.
ΓòÉΓòÉΓòÉ <hidden> GUI ΓòÉΓòÉΓòÉ
See graphical user interface.
ΓòÉΓòÉΓòÉ <hidden> handles ΓòÉΓòÉΓòÉ
Small squares that appear on the corners of a selected visual part in the
visual builder. Handles are used to resize parts.
Compare to primary selection.
ΓòÉΓòÉΓòÉ <hidden> header file ΓòÉΓòÉΓòÉ
A file that contains system-defined control information that precedes user
data.
ΓòÉΓòÉΓòÉ <hidden> inheritance ΓòÉΓòÉΓòÉ
A mechanism by which an object class can use the attributes, relationships, and
member functions defined in more abstract classes related to it (its base
classes).
An object-oriented programming technique that allows you to use existing
classes as bases for creating other classes.
ΓòÉΓòÉΓòÉ <hidden> instance ΓòÉΓòÉΓòÉ
Synonym for object, a particular instantiation of a data type.
ΓòÉΓòÉΓòÉ <hidden> legacy code ΓòÉΓòÉΓòÉ
Existing code that a user might have. Legacy applications often have
character-based, nongraphical user interfaces; usually they are written in a
nonobject-oriented language, such as C or COBOL.
ΓòÉΓòÉΓòÉ <hidden> loaded ΓòÉΓòÉΓòÉ
The state of the mouse pointer between the time you select a part from the
parts palette and deposit the part on the free-form surface.
ΓòÉΓòÉΓòÉ <hidden> main part ΓòÉΓòÉΓòÉ
The part that users see when they start an application. This is the part from
which the main() function C++ code for the application is generated.
The main part is a special kind of composite part.
See also part and subpart.
ΓòÉΓòÉΓòÉ <hidden> member ΓòÉΓòÉΓòÉ
A data object in a structure or a union.
In C++, classes and structures can also contain functions and types as members.
ΓòÉΓòÉΓòÉ <hidden> member function ΓòÉΓòÉΓòÉ
An operator or function that is declared as a member of a class. A member
function has access to the private and protected data members and member
functions of objects of its class.
ΓòÉΓòÉΓòÉ <hidden> member function call ΓòÉΓòÉΓòÉ
A communication from one object to another that requests the receiving object
to execute a member function.
A member function call consists of a member function name that indicates the
requested member function and the arguments to be used in executing the member
function. The member function call always returns some object to the requesting
object as the result of performing the member function.
Synonym for message.
ΓòÉΓòÉΓòÉ <hidden> member function name ΓòÉΓòÉΓòÉ
The component of a member function call that specifies the requested operation.
ΓòÉΓòÉΓòÉ <hidden> message ΓòÉΓòÉΓòÉ
A request from one object that the receiving object implement a member
function. Because data is encapsulated and not directly accessible, a message
is the only way to send data from one object to another. Each message specifies
the name of the receiving object, the member function to be implemented, and
any arguments the member function needs for implementation.
Synonym for member function call.
ΓòÉΓòÉΓòÉ <hidden> model ΓòÉΓòÉΓòÉ
A nonvisual part that represents the state and behavior of a object, such as a
customer or an account.
Contrast with view.
ΓòÉΓòÉΓòÉ <hidden> module definition file ΓòÉΓòÉΓòÉ
A file that describes the code segments within a load module.
Synonym for DEF file.
ΓòÉΓòÉΓòÉ <hidden> nested class ΓòÉΓòÉΓòÉ
A class defined within the scope of another class.
ΓòÉΓòÉΓòÉ <hidden> nonvisual part ΓòÉΓòÉΓòÉ
A part that has no visual representation at run time. A nonvisual part
typically represents some real-world object that exists in the business
environment.
Compare to model. Contrast with view and visual part.
ΓòÉΓòÉΓòÉ <hidden> no-event attribute ΓòÉΓòÉΓòÉ
An attribute that does not have an event identifier.
ΓòÉΓòÉΓòÉ <hidden> no-set attribute ΓòÉΓòÉΓòÉ
An attribute that does not have a set member function.
ΓòÉΓòÉΓòÉ <hidden> notebook part ΓòÉΓòÉΓòÉ
A visual part that resembles a bound notebook containing pages separated into
sections by tabbed divider pages. A user can turn the pages of a notebook or
select the tabs to move from one section to another.
ΓòÉΓòÉΓòÉ <hidden> object ΓòÉΓòÉΓòÉ
A computer representation of something that a user can work with to perform a
task. An object can appear as text or an icon.
A collection of data and member functions that operate on that data, which
together represent a logical entity in the system. In object-oriented
programming, objects are grouped into classes that share common data
definitions and member functions. Each object in the class is said to be an
instance of the class.
An instance of an object class consisting of attributes, a data structure, and
operational member functions. It can represent a person, place, thing, event,
or concept. Each instance has the same properties, attributes, and member
functions as other instances of the object class, though it has unique values
assigned to its attributes.
ΓòÉΓòÉΓòÉ <hidden> object class ΓòÉΓòÉΓòÉ
A template for defining the attributes and member functions of an object. An
object class can contain other object classes. An individual representation of
an object class is called an object.
ΓòÉΓòÉΓòÉ <hidden> object factory ΓòÉΓòÉΓòÉ
A nonvisual part capable of dynamically creating new instances of a specified
part. For example, during the execution of an application, an object factory
can create instances of a new class to collect the data being generated.
ΓòÉΓòÉΓòÉ <hidden> object-oriented programming ΓòÉΓòÉΓòÉ
A programming approach based on the concepts of data abstraction and
inheritance. Unlike procedural programming techniques, object-oriented
programming concentrates on those data objects that comprise the problem and
how they are manipulated, not on how something is accomplished.
ΓòÉΓòÉΓòÉ <hidden> observer ΓòÉΓòÉΓòÉ
An object that receives notification from a notifier object.
ΓòÉΓòÉΓòÉ <hidden> operation ΓòÉΓòÉΓòÉ
A member function or service that can be requested of an object.
ΓòÉΓòÉΓòÉ <hidden> overloading ΓòÉΓòÉΓòÉ
An object-oriented programming technique that allows you to redefine functions
and most standard C++ operators when the functions and operators are used with
class types.
ΓòÉΓòÉΓòÉ <hidden> palette ΓòÉΓòÉΓòÉ
See parts palette.
ΓòÉΓòÉΓòÉ <hidden> parameter connection ΓòÉΓòÉΓòÉ
A connection that satisfies a parameter of an action or member function by
supplying either an attribute's value or the return value of an action, member
function, or custom logic. The parameter is always the source of the
connection.
See also connection.
ΓòÉΓòÉΓòÉ <hidden> parent class ΓòÉΓòÉΓòÉ
The class from which another part or class inherits data, member functions, or
both.
ΓòÉΓòÉΓòÉ <hidden> part ΓòÉΓòÉΓòÉ
A self-contained software object with a standardized public interface,
consisting of a set of external features that allow the part to interact with
other parts. A part is implemented as a class that supports the INotifier
protocol and has a part interface defined.
The parts on the palette can be used as templates to create instances or
objects.
ΓòÉΓòÉΓòÉ <hidden> part event ΓòÉΓòÉΓòÉ
A representation of a change that occurs to a part. The events on a part's
interface enable other interested parts to receive notification when something
about the part changes. For example, a push button generates an event signaling
that it has been clicked, which might cause another part to display a window.
ΓòÉΓòÉΓòÉ <hidden> part event ID ΓòÉΓòÉΓòÉ
The name of a part static-data member used to identify which notification is
being signaled.
ΓòÉΓòÉΓòÉ <hidden> part interface ΓòÉΓòÉΓòÉ
A set of external features that allows a part to interact with other parts. A
part's interface is made up of three characteristics: attributes, actions, and
events.
ΓòÉΓòÉΓòÉ <hidden> Part Interface Editor ΓòÉΓòÉΓòÉ
An editor that the application developer uses to create and modify attributes,
actions, and events, which together make up the interface of a part.
Compare to Class Editor and Composition Editor.
ΓòÉΓòÉΓòÉ <hidden> parts palette ΓòÉΓòÉΓòÉ
The parts palette holds a collection of visual and nonvisual parts used in
building additional parts for an application. The parts palette is organized
into categories. Application developers can add parts to the palette for use in
defining applications or other parts.
ΓòÉΓòÉΓòÉ <hidden> preferred features ΓòÉΓòÉΓòÉ
A subset of the part's features that appear in a pop-up connection menu.
Generally, they are the features used most often.
ΓòÉΓòÉΓòÉ <hidden> primary selection ΓòÉΓòÉΓòÉ
In the Composition Editor, the part used as a base for an action that affects
several parts. For example, an alignment tool will align all selected parts
with the primary selection. Primary selection is indicated by closed (solid)
selection handles, while the other selected parts have open selection handles.
See also selection handles.
ΓòÉΓòÉΓòÉ <hidden> private ΓòÉΓòÉΓòÉ
Pertaining to a class member that is accessible only to member functions and
friends of that class.
ΓòÉΓòÉΓòÉ <hidden> process ΓòÉΓòÉΓòÉ
A program running under OS/2, along with the resources associated with it
(memory, threads, file system resources, and so on).
ΓòÉΓòÉΓòÉ <hidden> program ΓòÉΓòÉΓòÉ
One or more files containing a set of instructions conforming to a particular
programming language syntax.
A self-contained, executable module. Multiple copies of the same program can be
run in different processes.
ΓòÉΓòÉΓòÉ <hidden> protected ΓòÉΓòÉΓòÉ
Pertaining to a class member that is only accessible to member functions and
friends of that class, or to member functions and friends of classes derived
from that class.
ΓòÉΓòÉΓòÉ <hidden> prototype ΓòÉΓòÉΓòÉ
A function declaration or definition that includes both the return type of the
function and the types of its arguments.
ΓòÉΓòÉΓòÉ <hidden> primitive part ΓòÉΓòÉΓòÉ
A basic building block of other parts. A primitive part can be relatively
complex in terms of the function it provides.
ΓòÉΓòÉΓòÉ <hidden> process ΓòÉΓòÉΓòÉ
A collection of code, data, and other system resources, including at least one
thread of execution, that performs a data processing task.
ΓòÉΓòÉΓòÉ <hidden> property ΓòÉΓòÉΓòÉ
A unique characteristic of a part.
ΓòÉΓòÉΓòÉ <hidden> pure virtual function ΓòÉΓòÉΓòÉ
A virtual function that has a function definition of = 0;.
ΓòÉΓòÉΓòÉ <hidden> receiver ΓòÉΓòÉΓòÉ
The object that receives a member function call.
Contrast with caller.
ΓòÉΓòÉΓòÉ <hidden> resource file ΓòÉΓòÉΓòÉ
A file that contains data used by an application, such as text strings and
icons.
ΓòÉΓòÉΓòÉ <hidden> selection handles ΓòÉΓòÉΓòÉ
In the Composition Editor, small squares that appear on the corners of a
selected visual part. Selection handles are used to resize parts.
See also primary selection.
ΓòÉΓòÉΓòÉ <hidden> server ΓòÉΓòÉΓòÉ
A computer that provides services to multiple users or workstations in a
network; for example, a file server, a print server, or a mail server.
ΓòÉΓòÉΓòÉ <hidden> service ΓòÉΓòÉΓòÉ
A specific behavior that an object is responsible for exhibiting.
ΓòÉΓòÉΓòÉ <hidden> settings view ΓòÉΓòÉΓòÉ
A view of a part that provides a way to display and set the attributes and
options associated with the part.
ΓòÉΓòÉΓòÉ <hidden> sticky ΓòÉΓòÉΓòÉ
In the Composition Editor, the mode that enables you to add multiple parts of
the same class (for example, three push buttons) without going back and forth
between the parts palette and the free-form surface.
ΓòÉΓòÉΓòÉ <hidden> structure ΓòÉΓòÉΓòÉ
A construct that contains an ordered group of data objects. Unlike an array,
the data objects within a structure can have varied data types.
ΓòÉΓòÉΓòÉ <hidden> subpart ΓòÉΓòÉΓòÉ
A part that is used to create another part.
See also nonvisual part, part, and visual part.
ΓòÉΓòÉΓòÉ <hidden> superclass ΓòÉΓòÉΓòÉ
See abstract class and base class.
ΓòÉΓòÉΓòÉ <hidden> tear-off attribute ΓòÉΓòÉΓòÉ
An attribute that an application developer has exposed to work with as though
it were a stand-alone part.
ΓòÉΓòÉΓòÉ <hidden> template ΓòÉΓòÉΓòÉ
A family of classes or functions with variable types.
ΓòÉΓòÉΓòÉ <hidden> thread ΓòÉΓòÉΓòÉ
A unit of execution within a process.
ΓòÉΓòÉΓòÉ <hidden> tool bar ΓòÉΓòÉΓòÉ
The strip of icons along the top of the free-form surface. The tool bar
contains tools to help you construct composite parts.
ΓòÉΓòÉΓòÉ <hidden> UI ΓòÉΓòÉΓòÉ
See user interface.
ΓòÉΓòÉΓòÉ <hidden> unloaded ΓòÉΓòÉΓòÉ
The state of the mouse pointer before you select a part from the parts palette
and after you deposit a part on the free-form surface. In addition, you can
unload the mouse pointer by pressing the Esc key.
ΓòÉΓòÉΓòÉ <hidden> user interface (UI) ΓòÉΓòÉΓòÉ
The hardware, software, or both that enable a user to interact with a computer.
The term user interface normally refers to the visual presentation and its
underlying software with which a user interacts.
ΓòÉΓòÉΓòÉ <hidden> variable ΓòÉΓòÉΓòÉ
A storage place within an object for a data feature. The data feature is an
object, such as number or date, stored as an attribute of the containing
object.
A part that receives an identity at run time. A variable by itself contains no
data or program logic; it must be connected such that it receives runtime
identity from a part elsewhere in the application.
ΓòÉΓòÉΓòÉ <hidden> view ΓòÉΓòÉΓòÉ
A visual part, such as a window, push button, or entry field.
A visual representation that can display and change the underlying model
objects of an application. Views are both the end result of developing an
application and the basic unit of composition of user interfaces.
Compare to visual part. Contrast with model.
ΓòÉΓòÉΓòÉ <hidden> virtual function ΓòÉΓòÉΓòÉ
A function of a class that is declared with the keyword virtual. The
implementation that is executed when you make a call to a virtual function
depends on the type of the object for which it is called. This is determined at
run time.
ΓòÉΓòÉΓòÉ <hidden> visual part ΓòÉΓòÉΓòÉ
A part that has a visual representation at run time. Visual parts, such as
windows, push buttons, and entry fields, make up the user interface of an
application.
Compare to view. Contrast with nonvisual part.
ΓòÉΓòÉΓòÉ <hidden> visual programming tool ΓòÉΓòÉΓòÉ
A tool that provides a means for specifying programs graphically. Application
programmers write applications by manipulating graphical representations of
components.
ΓòÉΓòÉΓòÉ <hidden> white space ΓòÉΓòÉΓòÉ
Space characters, tab characters, form-feed characters, and new-line
characters.
ΓòÉΓòÉΓòÉ <hidden> window ΓòÉΓòÉΓòÉ
A rectangular area of the screen with visible boundaries in which information
is displayed. Windows can overlap on the screen, giving it the appearance of
one window being on top of another.
In the Composition Editor, a window is a part that can be used as a container
for other visual parts, such as push buttons.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
This book explores OO concepts and design. It shows you, through various
techniques and examples, how to develop applications using OO.
It is available through Benjamin/Cummings, Redwood City, California. Its ISBN
number is 0-8053-0091-0.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
This book explores OO programming. It shows you how to build reusable objects
through examples and provides a comparison between OO programming and
traditional programming.
It is available through the Addison-Wesley Publishing Company, Reading,
Massachusetts. Its ISBN number is 0-201-10393-1.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
This book describes the guidelines that define the Common User Access user
interface. The Common User Access user interface is an OO graphical user
interface that provides a consistent look and feel for products that adopt the
CUA interface as their standard.
It is available through QUE Corporation, Carmel, Indiana. Its ISBN number is
1-56529-170-0.
ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ
This book discusses user-centered design in its full scope: task analysis,
prototyping, empirical evaluating, interface techniques, and guidelines.
It is available through Digital Press, Maynard, Massachusetts.