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 >
OS/2 Help File  |  1995-06-01  |  2MB  |  13,258 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About This Book ΓòÉΓòÉΓòÉ
  3.  
  4.      Welcome to Visual Builder! 
  5.  
  6.      Notices 
  7.  
  8.      Trademarks 
  9.  
  10.      Highlighting conventions 
  11.  
  12.      How to use the Contents 
  13.  
  14.      How to obtain additional information 
  15.  
  16.      How to use action bar choices 
  17.  
  18.         -  Placing bookmarks 
  19.  
  20.         -  Searching for information 
  21.  
  22.         -  Printing information 
  23.  
  24.         -  Copying information to a file 
  25.  
  26.      How to cut and paste examples 
  27.  
  28.      Other information you might find helpful 
  29.  
  30.         -  Related information 
  31.  
  32.      Communicating Your Comments to IBM 
  33.  
  34.  
  35. ΓòÉΓòÉΓòÉ 1.1. Welcome to Visual Builder! ΓòÉΓòÉΓòÉ
  36.  
  37. Welcome to Visual Builder-the quickest and easiest way to create applications 
  38. using the C++ programming language! This book, Visual Builder User's Guide, 
  39. introduces parts, tools, and features that you can use to build Visual Builder 
  40. applications. 
  41.  
  42. Visual Builder is a tool provided by VisualAge C++. It is based on the 
  43. construction-from-parts paradigm, a software development paradigm in which 
  44. applications are assembled from reusable and existing software components, 
  45. called parts. You can extend Visual Builder by adding your own reusable, custom 
  46. parts and then using these parts in your applications as you need them. 
  47.  
  48. Visual Builder gets you started by providing a set of parts as well as 
  49. interactive visual programming tools to work with those parts. You create your 
  50. applications by visually assembling and connecting these prefabricated parts. 
  51. In many cases, you do not even have to write any code. 
  52.  
  53. Programmers who want to develop C++ applications using Visual Builder should 
  54. read this book. Knowledge of object-oriented (OO) concepts, although not 
  55. required unless you are interested in extending the Visual Builder parts to 
  56. include your own parts, is highly recommended. This product incorporates OO 
  57. concepts and knowledge of them will allow you to get the maximum use from the 
  58. product, as well as an understanding of the terminology used in this book. 
  59.  
  60. If you are new to Visual Builder, read through the first section completely. If 
  61. you have used Visual Builder before, you can skim that section. 
  62.  
  63. You will find shortcut techniques and other tips wherever you see 
  64.  
  65. Before you begin to use this information, it would be helpful to understand how 
  66. to navigate through it. You can use the Table of Contents and Index facility to 
  67. locate topics and the Search facility to search the text of this document. You 
  68. can use hypertext links to acquire related information on the current topic. 
  69. Hypertext links appear in a different color (which you can customize using the 
  70. OS/2 Scheme Palette). For example, here is a link to another panel: 
  71. Communicating Your Comments to IBM. By double-clicking on the text of the link 
  72. or by pressing Enter on a highlighted link, you will open a panel of related 
  73. information. When you open a panel, the first link has the focus; to shift the 
  74. focus to other links, use the Tab key. 
  75.  
  76. We encourage you to double-click on the graphics. Many of these graphics are 
  77. hyperlinks to additional information, much like a hypertext links. 
  78.  
  79. Wherever you see , you can add your own personal notes and comments to this 
  80. book. Double-click on it to start the system editor (or any E.EXE program that 
  81. is found in your PATH). You can type your notes into the file and save them for 
  82. later retrieval. There is one note file for each section of the book. 
  83.  
  84. Note:  DO NOT change the default name given to the file in which notes are 
  85.        stored. If you change the name of this file, you cannot reopen it. 
  86.  
  87.  Shortcut techniques and other tips are provided wherever you see . 
  88.  
  89.  You should also understand: 
  90.  
  91.      How to Use the Contents 
  92.  
  93.      How to Obtain Additional Information 
  94.  
  95.      How to Use Action Bar Choices 
  96.  
  97.      How to Cut and Paste Examples 
  98.  
  99.  
  100. ΓòÉΓòÉΓòÉ 1.2. Notices ΓòÉΓòÉΓòÉ
  101.  
  102. Copyright International Business Machines Corporation, 1992, 1995. All rights 
  103. reserved. 
  104.  
  105. Note to U.S. Government Users - Documentation related to restricted rights - 
  106. Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP 
  107. Schedule Contract with IBM Corp. 
  108.  
  109. First Edition, June 1995. 
  110.  
  111. This edition applies to Version 3.0 of VisualAge C++ for OS/2 (30H1664, 
  112. 30H1665, 30H1666) and to all subsequent releases and modifications until 
  113. otherwise indicated in new editions.  Make sure you are using the correct 
  114. edition for the level of the product. 
  115.  
  116. This publication could include technical inaccuracies or typographical errors. 
  117. Changes are periodically made to the information herein; any such changes will 
  118. be reported in subsequent revisions. 
  119.  
  120. Requests for publications and for technical information about IBM products 
  121. should be made to your IBM Authorized Dealer or your IBM Marketing 
  122. Representative. 
  123.  
  124. When you send information to IBM, you grant IBM a nonexclusive right to use or 
  125. distribute the information in any ways it believes appropriate without 
  126. incurring any obligation to you. 
  127.  
  128. Any reference to an IBM licensed program in this publication is not intended to 
  129. state or imply that only IBM's licensed program may be used. Any functionally 
  130. equivalent product, program, or service that does not infringe any of IBM's 
  131. intellectual property rights may be used instead of the IBM product, program, 
  132. or service. Evaluation and verification of operation in conjunction with other 
  133. products, except  those expressly designated by IBM, is the user's 
  134. responsibility. 
  135.  
  136. IBM may have patents or pending patent applications covering subject matter in 
  137. this document.  The furnishing of this document does not give you any license 
  138. to these patents.  You can send license inquiries, in writing, to: 
  139.  
  140.       IBM Director of Licensing 
  141.       IBM Corporation 
  142.       500 Columbus Avenue 
  143.       Thornwood, NY, 10594 
  144.       USA 
  145.  
  146.  This publication contains examples of data and reports used in daily business 
  147.  operations. To illustrate them as completely as possible, the examples include 
  148.  the names of individuals, companies, brands, and products. All of these names 
  149.  are fictitious and any similarity to the names and addresses used by an actual 
  150.  business enterprise is entirely coincidental. 
  151.  
  152.  
  153. ΓòÉΓòÉΓòÉ 1.3. Trademarks ΓòÉΓòÉΓòÉ
  154.  
  155. The following terms are trademarks of the IBM Corporation in the United States 
  156. or other countries: 
  157.  
  158.       BookManager 
  159.       Common User Access 
  160.       CUA 
  161.       IBM 
  162.       IBMLink 
  163.       Library Reader 
  164.       Open Class 
  165.       OS/2 
  166.       OS/2 Warp 
  167.       Presentation Manager 
  168.       PROFS 
  169.       VisualAge 
  170.       WorkFrame 
  171.       Workplace Shell 
  172.  
  173.  The following term is a trademark of another company: 
  174.  
  175.  C++       American Telephone & Telegraph Company 
  176.  
  177.  
  178. ΓòÉΓòÉΓòÉ 1.4. Highlighting Conventions ΓòÉΓòÉΓòÉ
  179.  
  180. This book uses the following highlighting conventions: 
  181.  
  182.  
  183.  Highlighting     Element                          Example
  184.  
  185.  Bold             Key interface items in code      Select Tools from the menu bar.
  186.                   listings. Areas in code examples
  187.                   that are described in
  188.                   accompanying text
  189.  
  190.  
  191.  
  192.  Monospace        C++ coding examples, text that   The following code from the
  193.                   the user enters, and messages    IAddress illustrates ...
  194.                   (within text)
  195.                                                    The street member function
  196.                                                    returns the current street.
  197.  
  198.  
  199.  
  200.  Italics          Emphasis of words, first time a  stored in persistent objects
  201.                   glossary term is used
  202.                                                    Refer to Object-Oriented User
  203.                   Titles of books                  Interface Design - IBM Common
  204.                                                    User Access Guidelines.
  205.  
  206.  
  207. ΓòÉΓòÉΓòÉ 1.5. How to Use the Contents ΓòÉΓòÉΓòÉ
  208.  
  209. When the Contents window first appears, some topics have a plus (+) sign beside 
  210. them. The plus sign indicates that additional topics are available. 
  211.  
  212. To expand the Contents if you are using a mouse, click on the plus sign.  If 
  213. you are using the keyboard, use the Up or Down arrow key to highlight the 
  214. topic, and press the plus (+) key. For example, How to Use the Contents has a 
  215. plus sign beside it.  To see additional topics for that heading, click on the 
  216. plus sign or highlight that topic and press the plus (+) key. 
  217.  
  218. To view a topic, double-click on the topic (or press the Up or Down arrow key 
  219. to highlight the topic, and then press the Enter key). 
  220.  
  221.  
  222. ΓòÉΓòÉΓòÉ 1.6. How to Obtain Additional Information ΓòÉΓòÉΓòÉ
  223.  
  224. After you select a topic, the information for that topic appears in a window. 
  225. Highlighted words or phrases indicate that additional information is available. 
  226. Certain words and phrases are highlighted in a different color from the 
  227. surrounding text. These are called hypertext terms. 
  228.  
  229. If you are using a mouse, double-click on the highlighted word.  If you are 
  230. using a keyboard, press the Tab key to move to the highlighted word, and then 
  231. press the Enter key.  Additional information then appears in a window. 
  232.  
  233.  
  234. ΓòÉΓòÉΓòÉ 1.7. How to Use Action Bar Choices ΓòÉΓòÉΓòÉ
  235.  
  236. Several choices are available for managing the information presented in this 
  237. document. There are three menus on the action bar:  the Services menu, the 
  238. Options menu, and the Help menu. 
  239.  
  240. The actions that are selectable from the Services menu operate on the active 
  241. window currently displayed on the screen. These actions include the following: 
  242.  
  243.  Placing bookmarks 
  244.    You can set a placeholder so you can retrieve information of interest to 
  245.    you. 
  246.  
  247.  Searching for information 
  248.    You can find occurrences of a word or phrase in the current topic, selected 
  249.    topics, or all topics. 
  250.  
  251.  Printing information 
  252.    You can print one or more topics. You can also print a set of topics by 
  253.    first marking the topics in the Contents list. 
  254.  
  255.  Copying information to a file 
  256.    You can copy a topic that you are viewing to the System Clipboard or to a 
  257.    file that you can edit. This method is particularly useful for copying 
  258.    syntax definitions and program samples into the application that you are 
  259.    developing. 
  260.  
  261.  Using the actions that are selectable from the Options menu, you can change 
  262.  the way your Contents list is displayed. To expand the Contents and show all 
  263.  levels for all topics, choose Expand all from the Options pull-down. You can 
  264.  also press the Ctrl and * keys together. 
  265.  
  266.  The actions that are selectable from the Help menu allow you to select 
  267.  different types of help information. 
  268.  
  269.  For information about any of the menu choices, highlight the choice in the 
  270.  menu and press F1. 
  271.  
  272.  
  273. ΓòÉΓòÉΓòÉ 1.7.1. Placing Bookmarks ΓòÉΓòÉΓòÉ
  274.  
  275. When you place a bookmark on a topic, it is added to a list of bookmarks you 
  276. have previously set.  You can view the list, and you can remove one or all 
  277. bookmarks from the list.  If you have not set any bookmarks, the list is empty. 
  278.  
  279. To set a bookmark, do the following: 
  280.  
  281.    1. Select a topic from the Contents. 
  282.    2. When that topic appears, select the Bookmark option from the Services 
  283.       menu. 
  284.    3. If you want to change the name used for the bookmark, type the new name 
  285.       in the field. 
  286.    4. Click on the Place radio button (or press the Up or Down arrow key to 
  287.       select it). 
  288.    5. Click on OK (or select it and press Enter). The bookmark is then added to 
  289.       the bookmark list. 
  290.  
  291.  
  292. ΓòÉΓòÉΓòÉ 1.7.2. Searching for Information ΓòÉΓòÉΓòÉ
  293.  
  294. You can specify a word or phrase to be searched.  You can also limit the search 
  295. to a set of topics by first marking the topics in the Contents list. 
  296.  
  297. To search for a word or phrase in all topics, do the following: 
  298.  
  299.    1. Select the Search option from the Services menu. 
  300.    2. Type the word or words to be searched for. 
  301.    3. Click on All sections (or press the Up or Down arrow keys to select it). 
  302.    4. Click on Search (or select it and press Enter) to begin the search. 
  303.    5. The list of topics where the word or phrase appears is displayed. 
  304.  
  305.  
  306. ΓòÉΓòÉΓòÉ 1.7.3. Printing Information ΓòÉΓòÉΓòÉ
  307.  
  308. You can print one or more topics, the index, or the table of contents.  Make 
  309. sure that your printer is connected to the serial port, configured correctly, 
  310. and ready for input. To print: 
  311.  
  312.    1. Select Print from the Services pull-down. 
  313.    2. Select what you want to print. Note that the This section and Marked 
  314.       sections choices are only available if you are viewing a topic or if you 
  315.       have marked topics, respectively.  To mark topics in the table of 
  316.       contents, press the Ctrl key and click on the topics, or use the arrow 
  317.       keys. 
  318.    3. Select Print to print what you've chosen on your printer. 
  319.  
  320.  
  321. ΓòÉΓòÉΓòÉ 1.7.4. Copying Information to a File ΓòÉΓòÉΓòÉ
  322.  
  323. You can copy a topic that you are viewing in two ways: 
  324.  
  325.      Copy copies the topic that you are viewing into the System Clipboard.  If 
  326.       you are using a Presentation Manager (PM) editor (for example, the 
  327.       Enhanced Editor) that copies or cuts (or both) to the System Clipboard, 
  328.       and pastes to the System Clipboard, you can easily add the copied 
  329.       information to your program source module. 
  330.  
  331.      Copy to file copies the topic that you are viewing into a temporary file 
  332.       named TEXT.TMP.  You can later edit that file by using any editor. 
  333.       TEXT.TMP is placed in the directory where your viewable document resides. 
  334.  
  335.  To copy a topic, do the following: 
  336.  
  337.    1. Expand the Contents list and select a topic. 
  338.    2. When the topic appears, select Copy to file from the Services menu. 
  339.    3. The system puts the text pertaining to that topic into the temporary file 
  340.       TEXT.TMP. 
  341.  
  342.  
  343. ΓòÉΓòÉΓòÉ 1.8. How to Cut and Paste Examples ΓòÉΓòÉΓòÉ
  344.  
  345. You can copy examples (or information) from this reference/guide/book to 
  346. compile, link, and run them, or to paste them into your own code. 
  347.  
  348. To copy an example or information: 
  349.  
  350.    1. Make the topic you want to copy the active window. 
  351.  
  352.    2. From the Services menu, select Copy to file. The text in that topic is 
  353.       placed in the temporary file TEXT.TMP, in the same directory as this 
  354.       reference. 
  355.  
  356.    3. You can then modify or use TEXT.TMP as you want. 
  357.  
  358.  Note:  Because the system copies the entire contents of the topic to the file, 
  359.  you may need to edit it to remove additional text. Most examples in this 
  360.  reference are ready to compile, link, and run as they appear, and do not 
  361.  require any editing. 
  362.  
  363.  
  364. ΓòÉΓòÉΓòÉ 1.9. Other Information You Might Find Helpful ΓòÉΓòÉΓòÉ
  365.  
  366. This product provides a number of online guides and references that we hope you 
  367. find helpful as you develop applications. This information includes user's 
  368. guides, references, and How Do I? help that gives you specific instructions for 
  369. performing common tasks. You can get to this online information from the 
  370. Information folder inside the main product folder.  You can also get to it from 
  371. the Help menu in any of the components of the product. 
  372.  
  373.  
  374. ΓòÉΓòÉΓòÉ 1.9.1. Related Information ΓòÉΓòÉΓòÉ
  375.  
  376. The following publications can help you find more information on OO software 
  377. design and Common User Access (CUA) user interface design. Double click on a 
  378. category to see a list of book titles that pertain to that category. 
  379.  
  380.      OO programming and design 
  381.  
  382.      User interface 
  383.  
  384.  
  385. ΓòÉΓòÉΓòÉ 1.9.2. OO Programming and Design ΓòÉΓòÉΓòÉ
  386.  
  387.      Booch, Grady. Object Oriented Design with Applications. 
  388.      Cox, Brad J. Object-Oriented Programming: An Evolutionary Approach. 
  389.  
  390.  
  391. ΓòÉΓòÉΓòÉ 1.9.3. User Interface ΓòÉΓòÉΓòÉ
  392.  
  393.      Object-Oriented Interface Design - IBM Common User Access Guidelines. 
  394.      Rubenstein, R. and Hersch, H. The Human Factor: Designing Computer 
  395.       Systems For People. 
  396.  
  397.  
  398. ΓòÉΓòÉΓòÉ 1.10. Communicating Your Comments to IBM ΓòÉΓòÉΓòÉ
  399.  
  400. If there is something you like or dislike about this book, please let us know. 
  401. You can use one of the methods listed below to send your comments to IBM. 
  402. Please be sure to include the complete title of the publication that you are 
  403. commenting on. 
  404.  
  405. The comments you send should only pertain to the information in this document 
  406. and its presentation.  To request additional publications or to ask questions 
  407. or make comments about the functions of IBM products or systems, you should 
  408. talk to your IBM representative or your authorized IBM remarketer. 
  409.  
  410. When you send comments to IBM, you grant IBM a nonexclusive right to use or 
  411. distribute your comments in any way it believes appropriate without incurring 
  412. any obligation to you. 
  413.  
  414. You can send your comments to IBM in the following ways: 
  415.  
  416.      By mail to the following address: 
  417.  
  418.             IBM Canada Ltd. Laboratory
  419.             Information Development
  420.             2G/345/1150/TOR
  421.             1150 EGLINTON AVENUE EAST
  422.             NORTH YORK, ONTARIO
  423.             CANADA M3C 1H7
  424.  
  425.      By FAX to the following number: 
  426.  
  427.         -  United States and Canada: (416) 448-6161 
  428.         -  Other countries (+1) 416-448-6161 
  429.  
  430.      By electronic mail to one of the following IDs.  Be sure to include your 
  431.       entire network address if you want a reply. 
  432.  
  433.         -  Internet: torrcf@vnet.ibm.com 
  434.         -  IBMLink: toribm(torrcf) 
  435.         -  IBM/PROFS: torolab4(torrcf) 
  436.         -  IBMMAIL: ibmmail(caibmwt9 
  437.  
  438.  
  439. ΓòÉΓòÉΓòÉ 2. Getting Started ΓòÉΓòÉΓòÉ
  440.  
  441.      What Is Visual Builder? 
  442.  
  443.      What are the benefits of using Visual Builder? 
  444.  
  445.      What are the key concepts? 
  446.  
  447.  Personal notes: 
  448.  
  449.  
  450. ΓòÉΓòÉΓòÉ 2.1. What is Visual Builder? ΓòÉΓòÉΓòÉ
  451.  
  452. Visual Builder is a visual programming tool that can help you create 
  453. object-oriented (OO) programs using the C++ programming language. With Visual 
  454. Builder, you can create applications faster and easier than you ever could 
  455. using a text editor. Visual Builder provides a powerful visual editor, the 
  456. Composition Editor, which enables you to create complete applications, often 
  457. without writing code. 
  458.  
  459.  
  460. ΓòÉΓòÉΓòÉ 2.2. What Are the Benefits of Using Visual Builder? ΓòÉΓòÉΓòÉ
  461.  
  462. With Visual Builder, you can quickly create applications with advanced 
  463. graphical user interfaces (GUIs). You can use Visual Builder to build OO 
  464. applications by assembling and connecting parts. 
  465.  
  466. Visual Builder is part of VisualAge C++, a state-of-the-art C++ application 
  467. development product that includes the IBM Open Class Library, WorkFrame, code 
  468. browsing and editing tools, and a sophisticated debugger. 
  469.  
  470. With Visual Builder, you can adopt OO technology immediately and learn to use 
  471. it at the pace that is best for you. Its benefits include the following: 
  472.  
  473.      When you work with Visual Builder's visual programming tools, you are 
  474.       creating OO applications. 
  475.  
  476.      You can use Visual Builder to enhance and extend your applications 
  477.       because Visual Builder supports C++, an OO programming language. 
  478.  
  479.      You can also access other logic written in C and C++ using Visual 
  480.       Builder's support for external C and C++ program logic. 
  481.  
  482.      You can shorten your application development cycle time considerably by 
  483.       creating reusable parts. 
  484.  
  485.      You can change the way a part does its work without affecting its 
  486.       external interface by encapsulating your application into parts. 
  487.       Encapsulating your application into parts also helps you deploy your 
  488.       business logic where it needs to be. Critical calculations can be moved 
  489.       into a dynamic link library. 
  490.  
  491.      By its nature, Visual Builder caters to all skill levels, so that 
  492.       programmers using Visual Builder can build not only simple applications 
  493.       but also complex ones. 
  494.  
  495.  
  496. ΓòÉΓòÉΓòÉ 2.3. What Are the Key Concepts? ΓòÉΓòÉΓòÉ
  497.  
  498. Before we continue any further, let's look at some key Visual Builder concepts. 
  499.  
  500. Parts 
  501.  
  502. In Visual Builder, a part is a C++ class that, in addition to the usual 
  503. elements of a C++ class, includes a well-defined part interface. The part 
  504. interface defines how the part can interact with other parts. 
  505.  
  506. Three kinds of features make up a part interface. The following list provides a 
  507. brief description of each kind: 
  508.  
  509.  attributes   The logical data, often stored in data members, that other parts 
  510.               can access. This data can represent any logical property of a 
  511.               part, such as the balance of an account, the size of a shipment, 
  512.               or the text of a push button. 
  513.  
  514.  actions      Services or operations that a part can perform. Actions, such as 
  515.               placing an order or displaying a window, can be triggered by 
  516.               connections from other parts. 
  517.  
  518.  events       Signals that a part can send to notify itself or other parts that 
  519.               a change has occurred. When events are connected to attributes, 
  520.               actions, or member functions of other parts, the connections 
  521.               monitor these events and trigger the target features when the 
  522.               events occur. For example, when a push button's buttonClickEvent 
  523.               feature is connected to an action of another part, the other 
  524.               part's action is called when the push button is clicked. 
  525.  
  526.  To get you started, Visual Builder provides a set of base parts for you. These 
  527.  parts are included in the vbbase.vbb file, which Visual Builder loads each 
  528.  time it is started. The parts in this file are based on the classes in the IBM 
  529.  Open Class Library. Visual Builder does not allow you to modify these parts, 
  530.  but you can create parts of your own by subclassing or using these parts in 
  531.  parts that you create. 
  532.  
  533.  Connections 
  534.  
  535.  To define how the parts interact with each other, you can make the following 
  536.  kinds of connections. The definitions that follow apply to most cases in which 
  537.  these connections are used. Exceptions and special cases are noted in Learning 
  538.  to Use Connections 
  539.  
  540.  Attribute-to-attribute             Connections that link two data values 
  541.                                     together so that when one changes, the 
  542.                                     other changes, too. 
  543.  
  544.  Event-to-attribute                 Connections that change the value of an 
  545.                                     attribute when a certain event occurs. 
  546.  
  547.  Event-to-action                    Connections that start an action when a 
  548.                                     certain event occurs. 
  549.  
  550.  Attribute-to-action                Connections that start an action whenever 
  551.                                     an attribute's event identifier is 
  552.                                     signalled. 
  553.  
  554.  Event-to-member function           Connections that call a member function 
  555.                                     whenever a certain event occurs. 
  556.  
  557.  Attribute-to-member function       Connections that call a member function 
  558.                                     whenever an attribute's event identifier is 
  559.                                     signalled. 
  560.  
  561.  Custom logic                       Connections that call your customized C or 
  562.                                     C++ logic whenever an event or an 
  563.                                     attribute's event identifier is signalled. 
  564.  
  565.  Parameter                          Connections that provide a parameter value 
  566.                                     for an action or member function. The 
  567.                                     parameter value can be provided by 
  568.                                     connecting a parameter to an attribute, an 
  569.                                     action, a member function, or custom logic. 
  570.  
  571.  Source code generation 
  572.  
  573.  Visual Builder can generate C++ code for the GUI that you design in the 
  574.  Composition Editor, as well as for all of the connections that you make 
  575.  between parts. It can also generate C++ code for any new parts that you 
  576.  create. You can then use the code that Visual Builder generates when building 
  577.  your application. This capability allows you to concentrate on what your 
  578.  application does instead of spending time writing code for the GUI and its 
  579.  connections. 
  580.  
  581.  Besides saving you time and effort, additional advantages of letting Visual 
  582.  Builder generate your code instead of writing it yourself include the 
  583.  following: 
  584.  
  585.      Easier code modifications. 
  586.  
  587.       Do you want to replace a multiline entry field with a list box? Delete 
  588.       the entry field, drop the list box in its place, make any necessary 
  589.       connections, and regenerate the code. That's all. 
  590.  
  591.      Fewer errors. 
  592.  
  593.       Because Visual Builder can generate the majority of the code for your 
  594.       application, there is less opportunity for human errors, such as 
  595.       typographical and syntax errors, to creep into your code. That means you 
  596.       spend less time debugging your code for minor errors. 
  597.  
  598.      Support for pre-existing C and C++ code. 
  599.  
  600.       Using Visual Builder's Class Editor, you can specify files that contain 
  601.       existing C or C++ code that you want to use in your application. Then, 
  602.       when you generate the code for your application, those files are 
  603.       included. 
  604.  
  605.       In addition, you can create .vbe files that contain information about 
  606.       your C++ classes. You can then import that information into Visual 
  607.       Builder so that you can use those classes as parts. Refer to Building 
  608.       VisualAge C++ Parts for Fun and Profit for information about using .vbe 
  609.       files. 
  610.  
  611.      Standard format. 
  612.  
  613.       Another advantage is that a standard format is applied to all generated 
  614.       code. The code that Visual Builder generates is uniformly structured, 
  615.       indented, and commented. 
  616.  
  617.  
  618. ΓòÉΓòÉΓòÉ 3. Creating a Simple Visual Builder Application ΓòÉΓòÉΓòÉ
  619.  
  620.      What you will achieve 
  621.  
  622.      Creating the To-Do List application 
  623.  
  624.  Personal notes: 
  625.  
  626.  
  627. ΓòÉΓòÉΓòÉ 3.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  628.  
  629. The best way to learn about Visual Builder is to see how you can use it. The 
  630. following sections take you through an example of how you might use Visual 
  631. Builder to develop an application for creating and maintaining a simple to-do 
  632. list. Here is what the application looks like when it is finished: 
  633.  
  634. Now it is time to create the To-Do List application. 
  635.  
  636.  
  637. ΓòÉΓòÉΓòÉ 3.2. Creating the To-Do List Application ΓòÉΓòÉΓòÉ
  638.  
  639. Creating the To-Do List application consists of the following steps: 
  640.  
  641.      Starting Visual Builder for the To-Do List application 
  642.  
  643.      Creating a new visual part for the To-Do List application 
  644.  
  645.      Placing parts in the application window 
  646.  
  647.      Resizing and aligning the parts 
  648.  
  649.      Connecting the parts 
  650.  
  651.      Generating the C++ code for your application 
  652.  
  653.      Building the application 
  654.  
  655.      Running the application 
  656.  
  657.      Exiting the Composition Editor and Visual Builder 
  658.  
  659.  Personal notes: 
  660.  
  661.  
  662. ΓòÉΓòÉΓòÉ 3.2.1. Starting Visual Builder for the To-Do List Application ΓòÉΓòÉΓòÉ
  663.  
  664. Before you create the To-Do List application, start Visual Builder. For this 
  665. sample application, start Visual Builder from the Tools folder, as follows: 
  666.  
  667.    1. Double-click on the VisualAge C++ folder icon on your desktop. 
  668.  
  669.       The VisualAge C++ folder opens. 
  670.  
  671.    2. Double-click on the Tools folder icon. 
  672.  
  673.       The Tools folder opens. 
  674.  
  675.    3. Double-click on the Visual Builder icon. 
  676.  
  677.       Visual Builder displays the Visual Builder window, as shown in the 
  678.       following figure. 
  679.  
  680.  Now it is time to create a new visual part for the To-Do List application. 
  681.  
  682.  
  683. ΓòÉΓòÉΓòÉ 3.2.2. Creating a New Visual Part for the To-Do List Application ΓòÉΓòÉΓòÉ
  684.  
  685. Before you create your new visual part for the To-Do List application, set the 
  686. option for generating make files by selecting OptionsGenerate make files. 
  687. Otherwise, when you finish the application and generate the code, Visual 
  688. Builder will not generate the make file. By selecting this option now, you will 
  689. not have to come back to the Visual Builder window to select it later. 
  690.  
  691. The next thing to do when creating the To-Do List application is to create the 
  692. main part, a new visual part, as follows: 
  693.  
  694.    1. Select PartNew. 
  695.  
  696.       Visual Builder displays the Part - New window, as shown in the following 
  697.       figure: 
  698.  
  699.       The Part - New window provides the following fields in which you can 
  700.       enter information about your part: 
  701.  
  702.           The Class name field, where you enter the name of your part. Each 
  703.            composite part must have a name. 
  704.  
  705.            For the To-Do List application, enter the following: 
  706.  
  707.                       ToDoList
  708.  
  709.           The Description field, where you enter a description of your part. 
  710.  
  711.            For this example, enter the following: 
  712.  
  713.                       The To-Do List application
  714.  
  715.           The File name field, where you enter the name of the .vbb file in 
  716.            which you want Visual Builder to store your part. 
  717.  
  718.            For this example, you can either leave this field blank or enter the 
  719.            following: 
  720.  
  721.                       ToDoList.vbb
  722.  
  723.            This causes Visual Builder to store the ToDoList part in a file 
  724.            named todolist.vbb. If you leave this field blank, Visual Builder 
  725.            uses the part name as the name of the .vbb file by default, so the 
  726.            result is the same. 
  727.  
  728.           The Part type field, where you indicate the type of part. This field 
  729.            initially contains Visual part. However, you can specify a different 
  730.            type of part to create by selecting one from the field's drop-down 
  731.            list box. 
  732.  
  733.            For this example, do not select a different part type because you 
  734.            want to create a visual part for the To-Do List application. 
  735.  
  736.           The Base class field, where you specify the class that you want to 
  737.            be the base class of the part that you are creating. The base class 
  738.            is the part that part you are creating inherits attributes, events, 
  739.            and actions from. The Base class field contains the default base 
  740.            class name of IFrameWindow, which Visual Builder uses when you 
  741.            specify that you want to create a new visual part. 
  742.  
  743.            For this example, leave IFrameWindow as the base class. 
  744.  
  745.    2. Select the Open push button to create a visual part named ToDoList whose 
  746.       parent is IFrameWindow. This causes Visual Builder to display the 
  747.       Composition Editor. For more information about the Composition Editor, 
  748.       see Touring the Composition Editor. 
  749.  
  750.  If you look back at the Visual Builder window, you see that the file 
  751.  todolist.vbb is now included in the list of loaded files. This file was 
  752.  created for you when you selected the Open push button in the Part - New 
  753.  window. 
  754.  
  755.  Before you place any parts in the application window, first edit its title. 
  756.  
  757.  Changing the title of the To-Do List application window 
  758.  
  759.  The new visual part that you just created contains an IFrameWindow* part. This 
  760.  will be the To-Do List application window. Change the title of this window by 
  761.  doing the following: 
  762.  
  763.    1. Hold down the Alt key. 
  764.  
  765.    2. Click on the title bar with mouse button 1. 
  766.  
  767.    3. Type the new title text, such as To-Do List. 
  768.  
  769.    4. Press Shift+Enter after you have changed the window title. 
  770.  
  771.  
  772. ΓòÉΓòÉΓòÉ 3.2.3. Placing Parts in the Application Window ΓòÉΓòÉΓòÉ
  773.  
  774. Now that you have created your new visual part and edited the title of the 
  775. application window, it is time to place the other parts of the To-Do List 
  776. application in the application window. 
  777.  
  778. Placing a static text part in the window 
  779.  
  780. The To-Do List application needs two static text parts. Follow these steps to 
  781. place the first static text part in the To-Do List application window: 
  782.  
  783.    1. Select , the Data entry category, from the row of icons on the left-hand 
  784.       side of the parts palette. 
  785.  
  786.    2. Select , the IStaticText* icon, from the row of icons on the right-hand 
  787.       side of the parts palette. 
  788.  
  789.       When you move the mouse pointer over the free-form surface, you see that 
  790.       it has changed to crosshairs. This means the mouse pointer is loaded with 
  791.       the IStaticText* part. 
  792.  
  793.    3. Place the crosshairs in the upper-left corner of the To-Do List 
  794.       application window's client area and click mouse button 1. 
  795.  
  796.       A static text part is placed in the window. 
  797.  
  798.    4. Change the text of the static text part to To-do item. Use the same 
  799.       method for changing text that you learned previously when you changed the 
  800.       title of the To-Do List application window. 
  801.  
  802.  Placing an entry field in the window 
  803.  
  804.  The To-Do List application needs an entry field part. Follow these steps to 
  805.  place an entry field part in the To-Do List application window: 
  806.  
  807.    1. Select , the Data entry category, from the row of icons on the left-hand 
  808.       side of the parts palette. 
  809.  
  810.    2. Select , the IEntryField* icon, from the row of icons on the right-hand 
  811.       side of the parts palette. 
  812.  
  813.    3. Place the crosshairs beneath the first static text part and click mouse 
  814.       button 1. 
  815.  
  816.       The entry field part is placed beneath the static text part. 
  817.  
  818.  Placing another static text part in the window 
  819.  
  820.  The To-Do List application needs another static text part. Follow these steps 
  821.  to place and modify this part: 
  822.  
  823.    1. Place the second static text part in the To-Do List application window. 
  824.       Use the same method for placing a static text part that you learned 
  825.       previously when you placed the first static text part in the To-Do List 
  826.       application window. 
  827.  
  828.    2. Change the text of the static text part to To-do list. Use the same 
  829.       method for changing text that you learned when you changed the title of 
  830.       the To-Do List application window. 
  831.  
  832.  Placing a list box in the window 
  833.  
  834.  Because the to-do list is to consist of a list of text strings, you want to 
  835.  store that list in an IListBox* part. Follow these steps to place a list box 
  836.  part in the To-Do List application window: 
  837.  
  838.    1. Select , the Lists category, from the row of icons on the left-hand side 
  839.       of the parts palette. 
  840.  
  841.    2. Select , the IListBox* icon, from the row of icons that Visual Builder 
  842.       displays on the right-hand side of the parts palette. 
  843.  
  844.    3. Place the crosshairs below the second static text part and click mouse 
  845.       button 1. 
  846.  
  847.       The list box part is placed beneath the second static text part. 
  848.  
  849.  Placing the push buttons in the window 
  850.  
  851.  The To-Do List application needs two push buttons, one for adding items to the 
  852.  list and one for removing items from the list. Follow these steps to place two 
  853.  push button parts in the To-Do List application window: 
  854.  
  855.    1. Select , the Buttons category, from the row of icons on the left-hand 
  856.       side of the parts palette. 
  857.  
  858.    2. Select , the IPushButton* icon, from the row of icons on the right-hand 
  859.       side of the parts palette. 
  860.  
  861.    3. Place the crosshairs below the lower-left corner of the list box and 
  862.       click mouse button 1. 
  863.  
  864.       The first push button part is placed in the window. 
  865.  
  866.    4. Select the IPushButton* icon again. 
  867.  
  868.    5. Place the crosshairs to the right of the first push button and click 
  869.       mouse button 1. 
  870.  
  871.       The second push button is placed in the window. 
  872.  
  873.    6. Change the text of the first push button to Add. Use the same method you 
  874.       used to change the text in the title bar. 
  875.  
  876.    7. Change the text of the second push button to Remove. 
  877.  
  878.  
  879. ΓòÉΓòÉΓòÉ 3.2.4. Resizing and Aligning the Parts ΓòÉΓòÉΓòÉ
  880.  
  881. Now that you have placed all of the parts you need in the application window, 
  882. it is time to resize and align them. When you have finished, your application 
  883. window should look like the following figure: 
  884.  
  885. Matching the width of the list box to the width of the entry field 
  886.  
  887. Follow these steps to match the width of the list box to the width of the entry 
  888. field: 
  889.  
  890.    1. Move the mouse pointer over the list box. 
  891.  
  892.    2. Press and hold mouse button 1. 
  893.  
  894.       The selection handles appear at the four corners of the list box. 
  895.  
  896.    3. While holding down mouse button 1, move the mouse pointer to the entry 
  897.       field. 
  898.  
  899.       The selection handles on the list box become hollow and black selection 
  900.       handles appear on the four corners of the entry field. This means that 
  901.       both parts are selected, but the entry field is the anchor part. 
  902.       Therefore, any sizing actions performed using the tool bar cause the list 
  903.       box to match the size of its anchor part, the entry field. 
  904.  
  905.    4. Select , the Match Width tool, from the row of icons on the tool bar, 
  906.       located beneath the menu bar. 
  907.  
  908.       The width of the list box changes to match that of the entry field. 
  909.  
  910.  Matching the width of the Add push button to that of the Remove push button 
  911.  
  912.  Using the techniques you learned in the preceding steps, match the width of 
  913.  the Add push button to that of the Remove push button. 
  914.  
  915.  Dragging and dropping parts in the application window 
  916.  
  917.  Before you align the parts, you might want to drag and drop some of them to 
  918.  put them in closer proximity to each other. For example, you might want the 
  919.  static text parts to be closer to the parts that they label. Follow these 
  920.  steps to drag and drop the parts in the application window: 
  921.  
  922.  Note:  The following instructions are written for dragging and dropping 
  923.         multiple parts simultaneously. If you just want to drag and drop one 
  924.         part at a time, you can skip the first step. 
  925.  
  926.    1. Select all of the parts you want to drag using the technique you learned 
  927.       previously when matching the width of the list box to the width of the 
  928.       entry field. 
  929.  
  930.    2. Move the mouse pointer over one of the parts that you selected to drag. 
  931.  
  932.    3. Press and hold mouse button 2 and move the mouse cursor. 
  933.  
  934.       Visual Builder displays an outline of the parts that you are dragging. 
  935.  
  936.    4. Move the outline to the place where you want to drop the parts and 
  937.       release mouse button 2. 
  938.  
  939.       The parts are moved to their new location. 
  940.  
  941.  Resizing the application window 
  942.  
  943.  At this point, the parts in the application window are closer to the left 
  944.  window border than to the right window border. Follow these steps to resize 
  945.  the application window: 
  946.  
  947.    1. Select the application window by clicking mouse button 1 on the title 
  948.       bar. 
  949.  
  950.    2. Move the mouse pointer over the selection handle on the lower-right 
  951.       corner of the application window. 
  952.  
  953.    3. Press and hold mouse button 1. 
  954.  
  955.    4. Resize the application window by dragging the mouse pointer towards the 
  956.       left until the right border of the application window is approximately 
  957.       the same distance from the entry field and list box as the left border 
  958.       is. 
  959.  
  960.            To size the window in only one direction, either horizontally or 
  961.            vertically, hold down the Shift key while dragging the mouse 
  962.            pointer. 
  963.  
  964.  Centering the entry field and list box within the application window 
  965.  
  966.  The entry field and list box need to be centered within the application 
  967.  window. Follow these steps to center them: 
  968.  
  969.    1. Select the entry field. 
  970.  
  971.    2. Select , the Distribute Horizontally tool, from the row of icons on the 
  972.       tool bar. 
  973.  
  974.       Visual Builder centers the entry field between the left and right borders 
  975.       of the application window. 
  976.  
  977.    3. Select the list box and then the entry field, making the entry field the 
  978.       anchor part. Use the multiple part selection technique you learned 
  979.       previously. 
  980.  
  981.    4. Select , the Align Center tool, from the row of icons on the tool bar. 
  982.  
  983.       The list box is centered beneath the entry field. 
  984.  
  985.  Aligning the static text, entry field, and list box parts so their left edges 
  986.  are even 
  987.  
  988.  The static parts need to be aligned evenly with the left edges of the entry 
  989.  field and list box. Follow these steps to align them: 
  990.  
  991.    1. Select the first static text part and then select the entry field, making 
  992.       the entry field the anchor part. Use the multiple part selection 
  993.       technique you learned previously. 
  994.  
  995.    2. Select , the Align Left tool, from the row of icons on the tool bar. 
  996.  
  997.       The first static text part is aligned even with the left edge of the 
  998.       entry field. 
  999.  
  1000.    3. Repeat steps 1 and 2 for the second static text part and the list box. 
  1001.  
  1002.       The second static text part is aligned even with the left edge of the 
  1003.       list box. 
  1004.  
  1005.  Aligning the top edges of the push buttons 
  1006.  
  1007.  The push buttons need to be aligned so that their top edges are even. Follow 
  1008.  these steps to align them: 
  1009.  
  1010.    1. Select the Add push button and then select the Remove push button. Use 
  1011.       the multiple part selection technique you learned previously. 
  1012.  
  1013.    2. Select , the Align Top tool. 
  1014.  
  1015.       Visual Builder aligns the Add push button even with the top of the Remove 
  1016.       push button. 
  1017.  
  1018.  Spacing the push buttons evenly across the application window 
  1019.  
  1020.  The push buttons need to be evenly spaced across the width of the application 
  1021.  window. Follow these steps to space them: 
  1022.  
  1023.    1. Select both push buttons. You can make either push button the anchor 
  1024.       part. Use the multiple part selection technique you learned previously. 
  1025.  
  1026.    2. Select , the Distribute Horizontally tool. 
  1027.  
  1028.       Visual Builder spaces both push buttons evenly across the application 
  1029.       window. 
  1030.  
  1031.  Centering the push buttons between the bottom edge of the list box and the 
  1032.  bottom border of the application window 
  1033.  
  1034.  The push buttons need to be centered between the bottom edge of the list box 
  1035.  and the bottom border of the application window. Follow these steps to center 
  1036.  them: 
  1037.  
  1038.    1. Select both push buttons. You can make either push button the anchor 
  1039.       part. Use the multiple part selection technique you learned previously. 
  1040.  
  1041.    2. Move the mouse pointer over either push button. 
  1042.  
  1043.    3. Press and hold mouse button 2, and position the push buttons midway 
  1044.       between the bottom edge of the list box and the bottom window border. 
  1045.  
  1046.    4. When the push buttons are in place, release mouse button 2. 
  1047.  
  1048.  Your application should now look like the one shown in the following figure: 
  1049.  
  1050.  
  1051. ΓòÉΓòÉΓòÉ 3.2.5. Connecting the Parts ΓòÉΓòÉΓòÉ
  1052.  
  1053. Now it is time for you to connect the parts so that your application can add 
  1054. items to and remove items from the to-do list. You need to connect the push 
  1055. buttons to the list box and entry field. The following steps show you how to do 
  1056. this. 
  1057.  
  1058.            Before you start connecting parts, it is a good idea to make sure 
  1059.            none of your parts is selected. Otherwise, the correct pop-up menus 
  1060.            may not appear. To do this, hold down the Ctrl key, point to each 
  1061.            item that is selected, and press mouse button 1. When the selection 
  1062.            handles disappear, you know that the part is no longer selected. 
  1063.  
  1064.  Connecting the Add push button to the list box 
  1065.  
  1066.  The connection between the Add push button and the list box provides the 
  1067.  information your application needs to add items to the list box. 
  1068.  
  1069.    1. With the mouse pointer over the Add push button, click mouse button 2. 
  1070.  
  1071.       A pop-up menu is displayed. 
  1072.  
  1073.    2. Select Connect. 
  1074.  
  1075.       A cascaded menu, called the connection menu, of the Add push button is 
  1076.       displayed. 
  1077.  
  1078.    3. Select the buttonClickEvent feature. 
  1079.  
  1080.       Selecting the buttonClickEvent feature means that you want something to 
  1081.       happen whenever a user clicks this push button. The mouse pointer changes 
  1082.       to look like a spider, indicating that it is ready for you to select 
  1083.       another feature. 
  1084.  
  1085.    4. Move the mouse pointer to the list box and click mouse button 1. 
  1086.  
  1087.       A pop-up menu is displayed showing the connection menu of the list box. 
  1088.  
  1089.    5. Select the addAsLast action. 
  1090.  
  1091.       Selecting the addAsLast action means that you want new items to be added 
  1092.       to the end of the to-do list whenever a user clicks the Add push button. 
  1093.       The connection is shown in the following figure: 
  1094.  
  1095.       The line connecting the Add push button to the list box is dark green. It 
  1096.       points from the push button to the list box, showing that the event that 
  1097.       occurs when the push button is selected will cause the list box to 
  1098.       perform an action. 
  1099.  
  1100.       Notice that the connection line is dashed instead of solid. A dashed line 
  1101.       means that the connection is incomplete. The connection is supposed to 
  1102.       add something to the list box when the Add push button is clicked, but 
  1103.       you have not yet supplied what needs to be added. The next step does 
  1104.       that. 
  1105.  
  1106.    6. Move the mouse pointer to the dashed connection line between the Add push 
  1107.       button and the list box. 
  1108.  
  1109.    7. To take a shortcut to display connection menus, hold down the Alt key and 
  1110.       click mouse button 2. 
  1111.  
  1112.       The pop-up menu for the connection is displayed. 
  1113.  
  1114.    8. Select the text parameter. 
  1115.  
  1116.       The text parameter is the reason the connection line is dashed. You need 
  1117.       to give this parameter a value. 
  1118.  
  1119.    9. Move the mouse pointer over the entry field, and click mouse button 1. 
  1120.  
  1121.       Visual Builder displays the connection menu for the list box. 
  1122.  
  1123.   10. Select the text attribute. 
  1124.  
  1125.       Selecting the text attribute here means that you want to pass the text 
  1126.       that a user enters in the entry field to the text parameter of the 
  1127.       addAsLast action. This text string is added to the end of the to-do list 
  1128.       whenever the addAsLast action is called, which occurs whenever the Add 
  1129.       push button is clicked. The completed connection is shown in the 
  1130.       following figure: 
  1131.  
  1132.       The line connecting the entry field to the connection between the Add 
  1133.       push button and the list box is violet. The solid arrow head points to 
  1134.       the entry field, showing that the text attribute is the target of the 
  1135.       connection. 
  1136.  
  1137.       The hollow arrow head points to the connection line, indicating that the 
  1138.       text parameter of the addAsLast action is the source of the connection. 
  1139.       When the text parameter needs a value, which occurs when a user clicks on 
  1140.       the Add push button, the connection invokes the get member function of 
  1141.       the entry field's text attribute. The value of that attribute (the text 
  1142.       in the entry field) is returned to the text parameter and the addAsLast 
  1143.       action puts the text string in the list box. 
  1144.  
  1145.       Notice that both of the connection lines are solid. This means that the 
  1146.       connection between the Add push button and the list box now has the 
  1147.       information it needs to perform its function, so the connection is 
  1148.       complete. 
  1149.  
  1150.  Connecting the Remove push button to the list box 
  1151.  
  1152.  The connection between the Remove push button and the list box provides the 
  1153.  information your application needs to remove items from the list box. 
  1154.  
  1155.    1. With the mouse pointer over the Remove push button, hold down the Alt key 
  1156.       and click mouse button 2. 
  1157.  
  1158.       Visual Builder displays the connection menu for the Remove push button. 
  1159.  
  1160.    2. Select the buttonClickEvent feature. 
  1161.  
  1162.    3. Move the mouse pointer to the list box and click mouse button 1. 
  1163.  
  1164.       Visual Builder displays the connection menu for the list box. 
  1165.  
  1166.    4. Select the remove action. 
  1167.  
  1168.       Selecting the remove action means that you want your application to 
  1169.       remove the selected item in the to-do list whenever a user clicks the 
  1170.       Remove push button. Once again, the connection is incomplete. 
  1171.  
  1172.    5. Move the mouse pointer to the connection between the Remove push button 
  1173.       and the list box. 
  1174.  
  1175.    6. Hold down the Alt key and click mouse button 2. 
  1176.  
  1177.       Visual Builder displays the connection menu for the connection. 
  1178.  
  1179.    7. Select the index parameter. 
  1180.  
  1181.       The index parameter is the reason the connection line is dashed. You need 
  1182.       to give this parameter a value. 
  1183.  
  1184.    8. Move the mouse pointer over the list box and click mouse button 1. 
  1185.  
  1186.       Visual Builder displays the connection menu for the list box. 
  1187.  
  1188.    9. Select the selection attribute. 
  1189.  
  1190.       Selecting the selection attribute means that you want to pass the index 
  1191.       of the selected item in the list box to the index parameter of the remove 
  1192.       action. The remove action uses this index to determine which item to 
  1193.       remove whenever the Remove push button is clicked. 
  1194.  
  1195.       Making this connection completes your application. It should now look 
  1196.       like the one shown in the following figure: 
  1197.  
  1198.       Note:  In the preceding figure, we changed the shape of the connection 
  1199.              between the Remove push button and the list box to make it easier 
  1200.              for you to see. You can do this by selecting the connection and 
  1201.              dragging the middle selection handle. 
  1202.  
  1203.  Now that you have made all of the connections, the next step is to generate 
  1204.  your C++ source code. 
  1205.  
  1206.  
  1207. ΓòÉΓòÉΓòÉ 3.2.6. Generating the C++ Code for Your Application ΓòÉΓòÉΓòÉ
  1208.  
  1209. The first thing you must do to get your application ready to build is to 
  1210. generate the C++ code. This is a two-part process that consists of generating 
  1211. the source code for your new visual part and then generating the source code 
  1212. for your main procedure. 
  1213.  
  1214. Generating the source code for your visual part 
  1215.  
  1216. To generate the C++ source code for your visual part, select FileSave and 
  1217. GeneratePart source. 
  1218.  
  1219.            Another way to generate part code is to select , the Part Code 
  1220.            Generation tool, on the tool bar. The results are the same. 
  1221.  
  1222.  Visual Builder generates the following files in the working directory: 
  1223.  
  1224.  todolist.cpp   The C++ code for your ToDoList part. 
  1225.  todolist.hpp   The C++ header file for your ToDoList part. 
  1226.  todolist.h     The resource header file for your todolist.cpp file. 
  1227.  todolist.rc    The resource file for your todolist.cpp file. 
  1228.  
  1229.  Generating the source code for your main() function 
  1230.  
  1231.  To generate the source code for your main() procedure, select FileSave and 
  1232.  Generatemain() for part. Visual Builder generates the following files in the 
  1233.  working directory: 
  1234.  
  1235.  todolist.app   The main function for your application. 
  1236.  
  1237.                 Note:  If you start Visual Builder from a WorkFrame project, 
  1238.                        the name of this file is vbmain.cpp. 
  1239.  todolist.mak   The make file that you specify when you build your application. 
  1240.  
  1241.  You have now generated the C++ code for your application. The next step is to 
  1242.  build the application. 
  1243.  
  1244.  
  1245. ΓòÉΓòÉΓòÉ 3.2.7. Building the Application ΓòÉΓòÉΓòÉ
  1246.  
  1247. Building your application consists of compiling and linking it. To build your 
  1248. application, do the following: 
  1249.  
  1250.    1. Open an OS/2 window. 
  1251.  
  1252.    2. Change to your Visual Builder working directory. 
  1253.  
  1254.    3. Enter the following command: 
  1255.  
  1256.             nmake todolist.mak
  1257.  
  1258.       This command produces the following files: 
  1259.  
  1260.       todolist.exe        The executable file for your application. 
  1261.       todolist.map        The application configuration map. 
  1262.       todolist.o          The object file for your application. 
  1263.  
  1264.                           Note:  If you start Visual Builder from a WorkFrame 
  1265.                                  project, the name of this file is vbmain.obj. 
  1266.       todolist.obj        The object file for your part. Visual Builder 
  1267.                           provides a separate object module for your part that 
  1268.                           is used when compiling this part with other parts. 
  1269.       todolist.res        The binary resource file that is bound to 
  1270.                           todolist.exe. 
  1271.  
  1272.  You have now built your application; the next step is to run your application. 
  1273.  
  1274.  
  1275. ΓòÉΓòÉΓòÉ 3.2.8. Running the Application ΓòÉΓòÉΓòÉ
  1276.  
  1277. To run your application from the same OS/2 command prompt from which you 
  1278. entered the nmake command, enter the following: 
  1279.  
  1280. todolist
  1281.  
  1282. Once your application is running, experiment with it to make sure it works as 
  1283. you designed it. That is all there is to it! 
  1284.  
  1285. You can add a finishing touch to your application by creating an OS/2 program 
  1286. object. Create a program object from the OS/2 Templates folder, specifying the 
  1287. name todolist.exe as the program name and the directory that contains 
  1288. todolist.exe as the working directory. Once you have done this, you can run 
  1289. your application by simply double-clicking on the program object you just 
  1290. created. 
  1291.  
  1292.  
  1293. ΓòÉΓòÉΓòÉ 3.2.9. Exiting the Composition Editor and Visual Builder ΓòÉΓòÉΓòÉ
  1294.  
  1295. To exit either the Composition Editor or Visual Builder, do either of the 
  1296. following. 
  1297.  
  1298. Note:  You must exit Visual Builder before you can shut down OS/2. Otherwise, 
  1299.        OS/2 does not shut down completely. 
  1300.  
  1301. When you exit Visual Builder, any changes you have made to the selections in 
  1302. the Options menu are saved. Therefore, if you want certain options to be 
  1303. selected or deselected the next time you start Visual Builder, be sure to 
  1304. select or deselect them before exiting Visual Builder. 
  1305.  
  1306.      Select FileExit. 
  1307.      Double-click on the system menu icon in the window. 
  1308.  
  1309.  If you try to exit Visual Builder while one or more editor windows is open, 
  1310.  Visual Builder displays a message asking if you want to close the editors and 
  1311.  Visual Builder. You can select either of the following: 
  1312.  
  1313.      The OK push button to exit the windows. 
  1314.      The Cancel push button to cancel the exit request. 
  1315.  
  1316.  If you select the OK push button with this message displayed or try to exit an 
  1317.  editor and the open editor window contains unsaved changes, Visual Builder 
  1318.  displays a message asking if you want to save the changes for each open editor 
  1319.  before exiting. You can select either of the following: 
  1320.  
  1321.      The Yes push button to save the changes and exit. 
  1322.      The No push button to exit without saving the changes. 
  1323.      The Cancel push button to cancel the exit request. 
  1324.  
  1325.  
  1326. ΓòÉΓòÉΓòÉ 4. Setting Up and Starting Visual Builder ΓòÉΓòÉΓòÉ
  1327.  
  1328. This chapter tells you how to do the following: 
  1329.  
  1330.      Set up your WorkFrame project to use Visual Builder 
  1331.  
  1332.      Start Visual Builder 
  1333.  
  1334.  Personal notes: 
  1335.  
  1336.  
  1337. ΓòÉΓòÉΓòÉ 4.1. Setting Up Your WorkFrame Project to Use Visual Builder ΓòÉΓòÉΓòÉ
  1338.  
  1339. If you have created a WorkFrame project and will be running Visual Builder from 
  1340. the project folder, you should set up the project as follows before starting 
  1341. Visual Builder. 
  1342.  
  1343. Note:  We recommend that you use a Project Smarts Visual Builder template in 
  1344.        your WorkFrame project. Refer to the VisualAge C++ User's Guide for 
  1345.        information on how to do this. 
  1346.  
  1347.    1. Open the settings notebook for the project folder by doing the following: 
  1348.  
  1349.         a. Click on the project folder with mouse button 2. 
  1350.  
  1351.         b. Select OpenSettings. 
  1352.  
  1353.            The settings notebook appears. 
  1354.  
  1355.    2. Set the names of the executable file and the make file by doing the 
  1356.       following: 
  1357.  
  1358.         a. On the Target page, type the name that you want your executable file 
  1359.            to have in the Name field. 
  1360.  
  1361.         b. Type the name that you want your make file to have in the Makefile 
  1362.            field. 
  1363.  
  1364.    3. Set the directory in which your project files will be stored by doing the 
  1365.       following: 
  1366.  
  1367.         a. Select the tab for the Location OS/2 Files page. 
  1368.  
  1369.         b. Type the full path for the directory in which you want to store your 
  1370.            project files in the multiline edit field on this page. This is the 
  1371.            directory in which Visual Builder puts the files for your 
  1372.            application when you generate your source code. 
  1373.  
  1374.    4. Inherit the settings of a C++ project by doing the following: 
  1375.  
  1376.         a. Select the tab for the Inheritance page. 
  1377.  
  1378.         b. Select the Add push button. 
  1379.  
  1380.            A dialog is displayed in which you select the project whose settings 
  1381.            you want to inherit. 
  1382.  
  1383.         c. Double-click on the Desktop directory in the Directory list box. 
  1384.  
  1385.         d. Double-click on the VisualAge C++ 3.0 directory, also in the 
  1386.            Directory list box. 
  1387.  
  1388.         e. Select the C Set ++ Project file in the File list box. 
  1389.  
  1390.         f. Select the Inherit push button. 
  1391.  
  1392.            This puts all of the WorkFrame tools, including Visual Builder, that 
  1393.            you need for a C++ project in the project's pop-up menu, giving you 
  1394.            easier access to them. 
  1395.  
  1396.    5. Close the settings notebook. 
  1397.  
  1398.  You are now ready to start Visual Builder. 
  1399.  
  1400.  
  1401. ΓòÉΓòÉΓòÉ 4.2. Starting Visual Builder ΓòÉΓòÉΓòÉ
  1402.  
  1403. You can start Visual Builder in the following ways: 
  1404.  
  1405.      From the C/C++ window 
  1406.      From the Tools folder icon 
  1407.      From a WorkFrame Project folder 
  1408.  
  1409.  Starting Visual Builder from the C/C++ window 
  1410.  
  1411.  To start Visual Builder from the C/C++ window, do the following: 
  1412.  
  1413.    1. Double-click on the icon for the VisualAge C++ folder. 
  1414.  
  1415.       The folder opens. 
  1416.  
  1417.    2. Double-click on the C/C++ Window icon. 
  1418.  
  1419.       The C/C++ window opens. 
  1420.  
  1421.    3. Type the following: 
  1422.  
  1423.             icsvb
  1424.  
  1425.    4. Press the Enter key. 
  1426.  
  1427.       Visual Builder displays the Visual Builder window, as shown in the 
  1428.       following figure. 
  1429.  
  1430.  Starting Visual Builder from the Tools folder 
  1431.  
  1432.  To start Visual Builder from the Tools folder, do the following: 
  1433.  
  1434.    1. Double-click on the icon for the VisualAge C++ folder. 
  1435.  
  1436.       The folder opens. 
  1437.  
  1438.    2. Double-click on the Tools folder icon. 
  1439.  
  1440.       The folder opens. 
  1441.  
  1442.    3. Double-click on the Visual Builder icon. 
  1443.  
  1444.       Visual Builder displays the Visual Builder window, as shown in the 
  1445.       preceding figure. 
  1446.  
  1447.  Starting Visual Builder from a WorkFrame Project folder 
  1448.  
  1449.  You can start Visual Builder from a WorkFrame Project folder in the following 
  1450.  ways. 
  1451.  
  1452.  Note:  The following steps assume that your project inherits the settings of a 
  1453.         C Set ++ project or that it was created using a Project Smarts 
  1454.         template. 
  1455.  
  1456.      If the WorkFrame Project folder is closed, you can click on the folder 
  1457.       with mouse button 2 and select Visual from the pop-up menu. 
  1458.  
  1459.      If the WorkFrame Project folder is open, you can do any one of the 
  1460.       following: 
  1461.  
  1462.         -  Double-click on the name of the .vbb file 
  1463.  
  1464.         -  Click on the name of the .vbb file with mouse button 2 and select 
  1465.            Visual from the pop-up menu. 
  1466.  
  1467.         -  Click on the white space in the project folder with mouse button 2 
  1468.            and select Visual from the pop-up menu. 
  1469.  
  1470.       Visual Builder displays the Visual Builder window, as shown in the 
  1471.       preceding figure. If you double-clicked on a .vbb file to open Visual 
  1472.       Builder, that file and all other .vbb files that you selected are 
  1473.       preloaded. 
  1474.  
  1475.  When you start Visual Builder from a WorkFrame Project folder, the menu bar in 
  1476.  the Visual Builder window and in each of the Visual Builder editor windows 
  1477.  contains an additional Project choice. Selecting this choice displays a list 
  1478.  of the WorkFrame actions that are currently at the project scope for the 
  1479.  project with which you are working. Examples of actions you might see in this 
  1480.  list are Debug, MakeMake, Build, Run, Database, and Browse. 
  1481.  
  1482.  
  1483. ΓòÉΓòÉΓòÉ 5. Getting Acquainted with the Visual Builder Window ΓòÉΓòÉΓòÉ
  1484.  
  1485. This chapter provides the following topics that show you how to set up a 
  1486. WorkFrame project to use Visual Builder, start Visual Builder, work with .vbb 
  1487. files, and use the functions available to you in the Visual Builder window. 
  1488.  
  1489.      Getting to know the Visual Builder window. 
  1490.  
  1491.      Working with the files for storing parts, .vbb files 
  1492.  
  1493.      Customizing the information area 
  1494.  
  1495.      Seeing the base files 
  1496.  
  1497.      Seeing where part files are located 
  1498.  
  1499.      Seeing the type list 
  1500.  
  1501.      Using File Allocation Table (FAT) file names 
  1502.  
  1503.      Generating make files 
  1504.  
  1505.      Setting the working directory 
  1506.  
  1507.      Refreshing the display 
  1508.  
  1509.  Personal notes: 
  1510.  
  1511.  
  1512. ΓòÉΓòÉΓòÉ 5.1. Getting to Know the Visual Builder Window ΓòÉΓòÉΓòÉ
  1513.  
  1514. The Visual Builder window is shown in the following figure. 
  1515.  
  1516. This window contains the following areas: 
  1517.  
  1518.      The Loaded Part Files list box 
  1519.  
  1520.       Parts that you create are stored in files with an extension of .vbb. 
  1521.       These files are called part files. You can share part files that you 
  1522.       create with other programmers so that they can reuse your parts. 
  1523.  
  1524.       This list box shows all of the part files that are currently loaded. 
  1525.       Visual Builder provides the following part files: 
  1526.  
  1527.       VBBase.vbb 
  1528.              Contains the base parts that Visual Builder provides. This file is 
  1529.              always loaded. 
  1530.  
  1531.       VBMM.vbb 
  1532.              Contains multimedia parts. 
  1533.  
  1534.       VBSOM.vbe 
  1535.              Contains Direct-to-SOM parts that you can use in Visual Builder. 
  1536.              You must import this file to use the parts. 
  1537.  
  1538.       VBCC.vbe 
  1539.              Contains sample parts based on the IBM Collection Class Library. 
  1540.              You must import this file to use the parts. 
  1541.  
  1542.       VBSample.vbb 
  1543.              Contains miscellaneous sample parts. 
  1544.  
  1545.                      The .vbb files that Visual Builder provides are read-only 
  1546.                      files. Store the parts that you create in your own .vbb 
  1547.                      files. 
  1548.  
  1549.       Part files must be loaded into Visual Builder for you to use the parts 
  1550.       that they contain. Once part files are loaded, you can perform actions on 
  1551.       them and on the parts that they contain by using the choices in the 
  1552.       Visual Builder's menu bar. 
  1553.  
  1554.                      You can access the same choices that are available in the 
  1555.                      menu bar by moving the mouse pointer over a list box and 
  1556.                      pressing mouse button 2 to display a pop-up menu. Each 
  1557.                      pop-up menu contains only the menu choices that pertain to 
  1558.                      the contents of the list box over which it is displayed. 
  1559.                      The pop-up menu that Visual Builder displays for the 
  1560.                      Loaded Part Files list box, for example, contains only the 
  1561.                      menu choices that pertain to part files. 
  1562.  
  1563.                      Also, the pop-up menu for the Visual Parts list box only 
  1564.                      affects parts that are selected in that list box, even if 
  1565.                      parts are also selected in the Nonvisual Parts list box, 
  1566.                      and vice versa. For example, to simultaneously open both a 
  1567.                      visual and a nonvisual part, you must select PartOpen 
  1568.                      from the menu bar. If you select Open from the pop-up menu 
  1569.                      for the Visual Parts list box, you can only open a visual 
  1570.                      part. The same is true for the pop-up menu for the 
  1571.                      Nonvisual Parts list box. 
  1572.  
  1573.                      The choices on the Part menu apply to selected items in 
  1574.                      all of the list boxes in the Visual Builder window. This 
  1575.                      includes the Loaded Type Information list box, which you 
  1576.                      display by selecting OptionsShow type list. 
  1577.  
  1578.       For more information about part files and the actions you can perform on 
  1579.       them, see Working with the Files for Storing Parts, .vbb Files. 
  1580.  
  1581.      The Visual Parts list box 
  1582.  
  1583.       This list box displays the names of the visual parts that the selected 
  1584.       part file contains. Visual parts are parts that the person using your 
  1585.       application can see, such as frame windows, push buttons, and sliders. 
  1586.  
  1587.      The Nonvisual Parts list box 
  1588.  
  1589.       This list box displays the names of the nonvisual parts and the class 
  1590.       interface parts that the selected part file contains. Nonvisual parts are 
  1591.       parts that your application uses to perform its functions, but the person 
  1592.       using your application never sees them. For example, an object factory, 
  1593.       which creates new instances of objects, is a nonvisual part. The user 
  1594.       sees only the objects that the object factory creates, not the object 
  1595.       factory itself. 
  1596.  
  1597.       Class interface parts are nonvisual parts that have no notification 
  1598.       ability. Thus, these parts cannot send events to other parts. You can use 
  1599.       C++ classes that you have written as class interface parts in Visual 
  1600.       Builder. 
  1601.  
  1602.  
  1603. ΓòÉΓòÉΓòÉ 5.2. Working with the Files for Storing Parts, .vbb Files ΓòÉΓòÉΓòÉ
  1604.  
  1605. The topics in this section describe how to perform various actions on part 
  1606. files from the Visual Builder window. 
  1607.  
  1608. The following topics are covered: 
  1609.  
  1610.      Loading part files 
  1611.  
  1612.      Unloading part files 
  1613.  
  1614.      Selecting all part files 
  1615.  
  1616.      Deselecting all part files 
  1617.  
  1618.  Personal notes: 
  1619.  
  1620.  
  1621. ΓòÉΓòÉΓòÉ 5.2.1. Loading Part Files ΓòÉΓòÉΓòÉ
  1622.  
  1623. To give Visual Builder access to parts, you must load the contents of the part 
  1624. files that contain those parts by doing the following: 
  1625.  
  1626.    1. Select FileLoad file in the Visual Builder window. 
  1627.  
  1628.       Visual Builder displays the window shown below: 
  1629.  
  1630.    2. Select the file or files that you want to load. 
  1631.  
  1632.    3. Select the OK push button. 
  1633.  
  1634.                      When you are just loading one file, it is quicker to 
  1635.                      double-click on the file name instead of selecting the 
  1636.                      file name and the OK push button. 
  1637.  
  1638.       The file name or names are displayed in the Loaded Part Files list box in 
  1639.       the Visual Builder window. The following figure shows the Visual Builder 
  1640.       window with multiple .vbb files loaded. 
  1641.  
  1642.  For information about unloading files, see Unloading Part Files. 
  1643.  
  1644.  
  1645. ΓòÉΓòÉΓòÉ 5.2.2. Unloading Part Files ΓòÉΓòÉΓòÉ
  1646.  
  1647. If a part file appears in the Loaded Part Files list box in the Visual Builder 
  1648. window, Visual Builder has access to the parts that the part file contains. If 
  1649. you do not want Visual Builder to have access to those parts, you can unload 
  1650. the part file, with the exception of vbbase.vbb. To unload one or more part 
  1651. files, do the following: 
  1652.  
  1653.    1. Select one or more files in the Loaded Part Files list box. 
  1654.  
  1655.       To select multiple files, hold down the Ctrl key while clicking on a file 
  1656.       name with mouse button 1. 
  1657.  
  1658.    2. Select FileUnload file. 
  1659.  
  1660.       The following window is displayed showing the files you selected to 
  1661.       unload: 
  1662.  
  1663.       At this point, you can review the files that you selected and make any 
  1664.       changes by deselecting any file or files that you want to remain loaded. 
  1665.  
  1666.    3. Select the Unload push button. 
  1667.  
  1668.       The window disappears and the file names are removed from the Loaded Part 
  1669.       Files list box. 
  1670.  
  1671.  For information about loading files, see Loading Part Files. 
  1672.  
  1673.  
  1674. ΓòÉΓòÉΓòÉ 5.2.3. Selecting All Part Files ΓòÉΓòÉΓòÉ
  1675.  
  1676. To select all of the part files, select EditSelect all files. Visual Builder 
  1677. highlights all of the part files listed in the Loaded Part Files list box. 
  1678.  
  1679. At this point, you can review the list to see if you want to deselect any of 
  1680. the files. 
  1681.  
  1682.  
  1683. ΓòÉΓòÉΓòÉ 5.2.4. Deselecting All Part Files ΓòÉΓòÉΓòÉ
  1684.  
  1685. To deselect all of the part files, select EditDeselect all files. Visual 
  1686. Builder removes the highlighting from all of the selected part files listed in 
  1687. the Loaded Part Files list box. 
  1688.  
  1689. At this point, you can review the list to see if you want to select any of the 
  1690. files. 
  1691.  
  1692.  
  1693. ΓòÉΓòÉΓòÉ 5.3. Customizing the Information Area ΓòÉΓòÉΓòÉ
  1694.  
  1695. The following options allow you to specify the kind of information that Visual 
  1696. Builder displays in the information area for a selected part in the Visual 
  1697. Builder window. To use these options, select OptionsInformation area and then 
  1698. select one of the following options: 
  1699.  
  1700.  Show base class 
  1701.    Displays the C++ notation for a class and its base class. For example, if 
  1702.    you select IVBContainerControl when this option is selected, Visual Builder 
  1703.    displays the following in the information area to show that IControl is 
  1704.    IVBContainerControl's base class: 
  1705.  
  1706.       IVBContainerControl::IControl
  1707.  
  1708.  Show description 
  1709.    Displays a brief description of the selected part. For example, if you 
  1710.    select IVBContainerControl when this option is selected, Visual Builder 
  1711.    displays the following description in the information area: 
  1712.  
  1713.       Part: IVBContainerControl* - IBM VB container control
  1714.  
  1715.  Show full file names 
  1716.    Displays the name of the part file in which the part is stored. For example, 
  1717.    if you select IVBContainerControl when this option is selected, Visual 
  1718.    Builder displays the following file name in the information area to show 
  1719.    that VBBase.vbb contains the IVBContainerControl part. 
  1720.  
  1721.       VBBase.vbb
  1722.  
  1723.  
  1724. ΓòÉΓòÉΓòÉ 5.4. Seeing the Base Files ΓòÉΓòÉΓòÉ
  1725.  
  1726. Select OptionsShow base files to see the names of the parts in the .vbb files 
  1727. that Visual Builder provides, as follows: 
  1728.  
  1729.  VBBase.vbb 
  1730.    Contains the base parts that Visual Builder provides. 
  1731.  
  1732.  VBCC.vbb 
  1733.    Contains sample parts based on the IBM Collection Class Library. 
  1734.  
  1735.  VBMM.vbb 
  1736.    Contains sample multimedia parts. 
  1737.  
  1738.  
  1739. ΓòÉΓòÉΓòÉ 5.5. Seeing Where Part Files Are Located ΓòÉΓòÉΓòÉ
  1740.  
  1741. Select OptionsShow full file names to see the drive and directory where each 
  1742. of your part files is stored. 
  1743.  
  1744.  
  1745. ΓòÉΓòÉΓòÉ 5.6. Seeing the Type List ΓòÉΓòÉΓòÉ
  1746.  
  1747. The type list shows the types of data, such as enumerations and typedefs, for 
  1748. the parts contained in the .vbb file that is currently selected. If no .vbb 
  1749. file is selected or if the selected .vbb file has no data types defined, this 
  1750. list is empty. 
  1751.  
  1752. Once a type list is displayed, you can perform the following functions on data 
  1753. types that are selected: 
  1754.  
  1755.      Delete data types 
  1756.      Move data types to another part file 
  1757.      Export data type definitions into part information files 
  1758.  
  1759.  These functions are available in the Part pull-down menu. 
  1760.  
  1761.  To display a type list, do the following: 
  1762.  
  1763.    1. Select the part file or files for which you want to see defined types. 
  1764.  
  1765.    2. Select OptionsShow type list. 
  1766.  
  1767.       A list box titled Loaded Type Information is displayed at the bottom of 
  1768.       the Visual Builder window, as shown in the following figure. 
  1769.  
  1770.  
  1771. ΓòÉΓòÉΓòÉ 5.7. Using File Allocation Table (FAT) File Names ΓòÉΓòÉΓòÉ
  1772.  
  1773. Select Default to FAT file names if your system uses the File Allocation Table 
  1774. (FAT) file system instead of the High Performance File System (HPFS). This 
  1775. option is selected by default when you first install VisualAge C++. The FAT 
  1776. file system limits file names to a maximum of eight characters and file name 
  1777. extensions to a maximum of three characters. 
  1778.  
  1779. When you select this option, Visual Builder uses these limits when creating 
  1780. file names and extensions, such as in the Class Editor when it provides a file 
  1781. name and extension for you to use when generating default code. For example, 
  1782. suppose you create a part and name it MyNewPart. This name has nine characters. 
  1783. If you generate code for this part, the default file name that Visual Builder 
  1784. uses for the files it generates will have only eight characters, as will the 
  1785. .vbb file in which the part is saved if you allow Visual Builder to use a 
  1786. default name for that, too. 
  1787.  
  1788.            Be aware that Visual Builder does not check for existing file names 
  1789.            when creating default file names. If you always use the default file 
  1790.            name on a FAT system, Visual Builder may use a file name that has 
  1791.            already been used, which may cause an existing file to be written 
  1792.            over. For example, if you created another part named MyNewPart2, 
  1793.            Visual Builder would use the same default file name as it used for 
  1794.            MyNewPart. 
  1795.  
  1796.            Visual Builder assigns the file name when you create the part. 
  1797.            Deselecting the Default to FAT file names option does not change the 
  1798.            name of a file that has already been created. 
  1799.  
  1800.  
  1801. ΓòÉΓòÉΓòÉ 5.8. Generating Make Files ΓòÉΓòÉΓòÉ
  1802.  
  1803. Select Generate make files if you want Visual Builder to generate a make file 
  1804. for you when you generate the default source code for the main() function of 
  1805. your application. 
  1806.  
  1807.  
  1808. ΓòÉΓòÉΓòÉ 5.9. Setting the Working Directory ΓòÉΓòÉΓòÉ
  1809.  
  1810. Select OptionsSet working directory if you want to store files created with 
  1811. Visual Builder in a different working directory. The default working directory 
  1812. is the directory in which you installed Visual Builder. 
  1813.  
  1814. When you select this option, Visual Builder displays the following window: 
  1815.  
  1816. To change the working directory, do the following: 
  1817.  
  1818.    1. Type the complete path to the directory in which you want to store Visual 
  1819.       Builder files that you create. 
  1820.  
  1821.       The path consists of all directories that must be opened to get to the 
  1822.       working directory. 
  1823.  
  1824.    2. Select the OK push button. 
  1825.  
  1826.  If the path you enter in the Working Directory window is invalid, Visual 
  1827.  Builder displays an error message and resets the path to the last valid path 
  1828.  that was entered. 
  1829.  
  1830.  
  1831. ΓòÉΓòÉΓòÉ 5.10. Refreshing the Display ΓòÉΓòÉΓòÉ
  1832.  
  1833. You might want to ensure that the information displayed in the Visual Builder 
  1834. window is current, for example, when you have loaded and unloaded several part 
  1835. files or moved parts from one part file to another. If such a situation occurs, 
  1836. you can cause the display to show the latest updates by selecting EditRefresh. 
  1837.  
  1838.  
  1839. ΓòÉΓòÉΓòÉ 6. Getting to Know the Visual Builder Editors ΓòÉΓòÉΓòÉ
  1840.  
  1841. This chapter takes you on a tour of the Visual Builder editors. It begins with 
  1842. an overview of the editor symbols and then examines each editor in detail. The 
  1843. following topics are covered: 
  1844.  
  1845.      The editor symbols. 
  1846.  
  1847.      The Composition Editor 
  1848.  
  1849.      The Class Editor 
  1850.  
  1851.      The Part Interface Editor 
  1852.  
  1853.  Personal notes: 
  1854.  
  1855.  
  1856. ΓòÉΓòÉΓòÉ 6.1. The Editor Symbols ΓòÉΓòÉΓòÉ
  1857.  
  1858. The Editor symbols, located at the bottom-right corner of the window, provide a 
  1859. fast-path to each of the Visual Builder Editors. Double-click on one of the 
  1860. following editor symbols to learn more about that editor. 
  1861.  
  1862.    Composition Editor        Use the Composition Editor to create the views for 
  1863.                              your application, choose the parts that perform 
  1864.                              the logic you need, and make connections between 
  1865.                              the parts. 
  1866.  
  1867.    Class Editor              Use the Class Editor to specify the names of files 
  1868.                              that Visual Builder writes to when you generate 
  1869.                              default code. You can also use this editor to do 
  1870.                              the following: 
  1871.  
  1872.                                  Enter a description of the part 
  1873.  
  1874.                                  Specify a different .vbb file in which to 
  1875.                                   store the part 
  1876.  
  1877.                                  See the name of the part's base class 
  1878.  
  1879.                                  Modify the part's default constructor 
  1880.  
  1881.                                  Enter additional constructor and destructor 
  1882.                                   code 
  1883.  
  1884.                                  Specify a .lib file for the part 
  1885.  
  1886.                                  Specify a resource DLL and ID to assign an 
  1887.                                   icon to the part 
  1888.  
  1889.                                  Specify other files that you want to include 
  1890.                                   when you build your application 
  1891.  
  1892.    Part Interface Editor     You can use the Part Interface Editor to define 
  1893.                              the features (attributes, actions, and events) for 
  1894.                              your parts, along with a list of preferred 
  1895.                              features for the pop-up connections menu. These 
  1896.                              features make up the part's interface. You use 
  1897.                              them when you make connections between 
  1898.                              collaborating parts. You can also promote features 
  1899.                              of subparts from this editor. 
  1900.  
  1901.  
  1902. ΓòÉΓòÉΓòÉ 6.2. The Composition Editor ΓòÉΓòÉΓòÉ
  1903.  
  1904.      Introducing the Composition Editor 
  1905.  
  1906.      The tool bar 
  1907.  
  1908.      The parts palette 
  1909.  
  1910.      The free-form surface 
  1911.  
  1912.  Personal notes: 
  1913.  
  1914.  
  1915. ΓòÉΓòÉΓòÉ 6.2.1. Introducing the Composition Editor ΓòÉΓòÉΓòÉ
  1916.  
  1917. The heart of Visual Builder is the Composition Editor. Use the Composition 
  1918. Editor to lay out the visual parts that make up your views, choose the parts 
  1919. that perform the logic you need, and make connections between them. 
  1920.  
  1921. The Composition Editor is the editor you use to visually compose the various 
  1922. parts of your application. This section provides an overview of the Composition 
  1923. Editor's components. See Learning Visual Construction Fundamentals for 
  1924. information about visually composing an application. 
  1925.  
  1926. The Composition Editor is shown in the following figure. 
  1927.  
  1928. The next section describes the Composition Editor tool bar. 
  1929.  
  1930.  
  1931. ΓòÉΓòÉΓòÉ 6.2.2. The Tool Bar ΓòÉΓòÉΓòÉ
  1932.  
  1933. The tool bar appears below the menu bar of the Composition Editor. It contains 
  1934. icons that provide convenient access to actions that you commonly use when you 
  1935. create composite parts. These tools help you perform such tasks as: 
  1936.  
  1937.      Aligning parts within your composite part 
  1938.      Managing the connections between parts 
  1939.      Unloading the mouse pointer. 
  1940.      Generating code for the part you are editing 
  1941.  
  1942.  All of the tools in the tool bar, except the Selection tool, act on the 
  1943.  selected objects. 
  1944.  
  1945.            All of the tools available from the tool bar are also available from 
  1946.            the Tools menu found on the Composition Editor's menu bar, except 
  1947.            for the tool used to generate source code for your part. This tool 
  1948.            is available in the File menu as the Save and generatePart source 
  1949.            choice. 
  1950.  
  1951.  The tool bar contains the following tools: 
  1952.  
  1953.    Part Code Generation      Generates C++ source code for the part that you 
  1954.                              are currently editing. This tool performs the same 
  1955.                              function as the FileSave and generatePart source 
  1956.                              menu choice. For information about the source code 
  1957.                              files that Visual Builder generates, see Source 
  1958.                              Files Created during Part Code Generation. 
  1959.    Selection tool            Changes the mouse pointer from the crosshairs, 
  1960.                              which are used when the mouse pointer is loaded 
  1961.                              with a part, to the arrow that is used to select 
  1962.                              parts and perform actions on them. If the mouse 
  1963.                              pointer is not loaded, this tool is not available. 
  1964.  
  1965.  Connection tools 
  1966.  
  1967.    Show Connections          Displays all hidden connections to or from the 
  1968.                              selected parts. If no parts are selected, all 
  1969.                              connections are shown. 
  1970.    Hide Connections          Hides all displayed connections to or from the 
  1971.                              selected parts. If no parts are selected, all 
  1972.                              connections are hidden. 
  1973.  
  1974.  Grid tools 
  1975.  
  1976.    Toggle Grid               Toggles the display of the part alignment grid on 
  1977.                              and off for the selected parts. You can use 
  1978.                              separate alignment grids for parts in the 
  1979.                              Composers category and for the free-form surface. 
  1980.    Snap To Grid              Causes the selected parts to be repositioned to 
  1981.                              the nearest grid coordinate. The grid does not 
  1982.                              need to be visible for Snap To Grid to work. 
  1983.                                             Select the Snap On Drop and Snap On 
  1984.                                             Size choices found in the 
  1985.                                             Composition Editor Options menu to 
  1986.                                             automatically align to the grid all 
  1987.                                             parts that you add or size. This 
  1988.                                             allows you to align parts to the 
  1989.                                             grid without having to select the 
  1990.                                             Snap To Grid tool for each part. 
  1991.                                             Use the Snap To Grid tool if you 
  1992.                                             only want to align selected parts 
  1993.                                             to the grid. 
  1994.  
  1995.  Alignment tools 
  1996.  
  1997.    Align Left                Aligns the selected parts to the left edge of the 
  1998.                              last part selected. 
  1999.    Align Center              Aligns the selected parts along the vertical axis 
  2000.                              of the last part selected. 
  2001.    Align Right               Aligns the selected parts to the right edge of the 
  2002.                              last part selected. 
  2003.    Align Top                 Aligns the selected parts to the top edge of the 
  2004.                              last part selected. 
  2005.    Align Middle              Aligns the selected parts along the horizontal 
  2006.                              axis of the last part selected. 
  2007.    Align Bottom              Aligns the selected parts to the bottom edge of 
  2008.                              the last part selected. 
  2009.  
  2010.  Distribution tools 
  2011.  
  2012.    Distribute Horizontally   Spaces the selected parts evenly between the left 
  2013.                              and right window borders. 
  2014.    Distribute Vertically     Spaces the selected parts evenly between the top 
  2015.                              and bottom window borders. 
  2016.  
  2017.                              For information about the horizontal and vertical 
  2018.                              distribution of visual parts within a bounding 
  2019.                              box, see Space parts within a bounding box. 
  2020.  
  2021.  Sizing tools 
  2022.  
  2023.    Match Width               Sizes the width of the selected parts to match 
  2024.                              that of the last part selected. 
  2025.    Match Height              Sizes the height of the selected parts to match 
  2026.                              that of the last part selected. 
  2027.  
  2028.  
  2029. ΓòÉΓòÉΓòÉ 6.2.3. The Parts Palette ΓòÉΓòÉΓòÉ
  2030.  
  2031. The parts palette is found on the left side of the Composition Editor. It 
  2032. contains icons for the parts that you use most frequently. 
  2033.  
  2034. The parts palette organizes parts into categories. The icons in the left column 
  2035. of the parts palette represent the part categories. The right column of the 
  2036. parts palette contains the parts you use to build your application. When you 
  2037. select a category in the left column, the right column shows the parts 
  2038. contained within that category. 
  2039.  
  2040. Notes: 
  2041.  
  2042.      The information area at the bottom of the Composition Editor indicates 
  2043.       which category and part are currently selected on the palette or which 
  2044.       part or connection is currently selected on the free-form surface. 
  2045.  
  2046.      You can add categories and parts to the parts palette, as well as delete 
  2047.       categories and parts from it. See Adding Categories and Parts to the 
  2048.       Parts Palette for information about adding parts that you create to the 
  2049.       parts palette. 
  2050.  
  2051.      See Placing Parts on the Free-form surface for information about putting 
  2052.       parts on the free-form surface. 
  2053.  
  2054.  The Visual Builder parts palette contains the following categories and parts. 
  2055.  Click on a part bitmap to see more information about the part it represents. 
  2056.  
  2057.    Buttons                   Contains the following button parts: 
  2058.                                        IPushButton* 
  2059.                                        IRadioButton* 
  2060.                                        ICheckBox* 
  2061.                                        INumericSpinButton* 
  2062.                                        ITextSpinButton* 
  2063.                                        IGraphicPushButton* 
  2064.                                        IAnimatedButton* 
  2065.    Data entry                Contains the following data entry parts: 
  2066.                                        IStaticText* 
  2067.                                        IEntryField* 
  2068.                                        IMultiLineEdit* 
  2069.                                        IGroupBox* 
  2070.                                        IOutlineBox* 
  2071.                                        IBitmapControl* 
  2072.                                        IIconControl* 
  2073.    Lists                     Contains the following list parts: 
  2074.                                        IListBox* 
  2075.                                        ICollectionViewListBox* 
  2076.                                        IComboBox* 
  2077.                                        ICollectionViewComboBox* 
  2078.                                        IVBContainerControl* 
  2079.                                        IContainerColumn* 
  2080.    Frame Extensions          Contains the following parts that you can add to a 
  2081.                              window frame: 
  2082.                                        IToolBar* 
  2083.  
  2084.                                        IToolBarButton* 
  2085.                                        IMenu* 
  2086.                                        IMenuItem* 
  2087.                                        IMenuCascade* 
  2088.                                        IMenuSeparator* 
  2089.  
  2090.                                        IInfoArea* 
  2091.                                        ITitle* 
  2092.    Sliders                   Consists of the following slider parts: 
  2093.                                        IProgressIndicator* 
  2094.                                        ISlider* 
  2095.  
  2096.                                        IScrollBar* 
  2097.    Composers                 Consists of the following parts that are used to 
  2098.                              contain other visual parts: 
  2099.                                        IMultiCellCanvas* 
  2100.                                        ISetCanvas* 
  2101.                                        ISplitCanvas* 
  2102.                                        IViewPort* 
  2103.                                        INotebook* 
  2104.                                        ICanvas* 
  2105.                                        IFrameWindow* 
  2106.    Models                    Contains the following nonvisual parts to help 
  2107.                              implement the logic of your application: 
  2108.                                        IVBFactory* 
  2109.                                        IVBVariable* 
  2110.                                        IVSequence* 
  2111.    Other                     Contains the following miscellaneous parts: 
  2112.                                        IHelpWindow* 
  2113.                                        IMessageBox* 
  2114.                                        IVBFileDialog* 
  2115.                                        IVBFontDialog* 
  2116.                                        IVBFlyText* 
  2117.  
  2118.  
  2119. ΓòÉΓòÉΓòÉ 6.2.4. The Free-form Surface ΓòÉΓòÉΓòÉ
  2120.  
  2121. The large open area in the Composition Editor is called the free-form surface. 
  2122. This is the working area for visual programming, where you compose the various 
  2123. visual parts of your application and where you make connections to the logic of 
  2124. your application. 
  2125.  
  2126. You add visual parts, such as static text and push buttons, to either a frame 
  2127. window part, to another part from the Composers category, or to the free-form 
  2128. surface itself. You add nonvisual parts, such as object factories, and class 
  2129. interface parts to your application by placing them on the free-form surface, 
  2130. not on a frame window part or on any other part from the Composers category. 
  2131.  
  2132. For more information about using the free-form surface, see Working with Parts 
  2133. On the Free-form Surface. 
  2134.  
  2135.  
  2136. ΓòÉΓòÉΓòÉ 6.3. The Class Editor ΓòÉΓòÉΓòÉ
  2137.  
  2138.      Introducing the Class Editor 
  2139.  
  2140.      Entering a description of a part 
  2141.  
  2142.      Moving a part to a different .vbb file 
  2143.  
  2144.      Seeing the base class of a part 
  2145.  
  2146.      Modifying a part's constructor 
  2147.  
  2148.      Specifying your own constructor code 
  2149.  
  2150.      Specifying your own destructor code 
  2151.  
  2152.      Specifying a library file 
  2153.  
  2154.      Specifying a starting resource ID 
  2155.  
  2156.      Specifying a unique icon for your part 
  2157.  
  2158.      Specifying the names of your code generation files 
  2159.  
  2160.      Specifying files to include when you build your application 
  2161.  
  2162.  Personal notes: 
  2163.  
  2164.  
  2165. ΓòÉΓòÉΓòÉ 6.3.1. Introducing the Class Editor ΓòÉΓòÉΓòÉ
  2166.  
  2167. The Class Editor is the editor you use to specify the names of files that 
  2168. Visual Builder writes to when you generate default code. You can also use this 
  2169. editor to do the following: 
  2170.  
  2171.      Enter a description of the part 
  2172.  
  2173.      Specify a different .vbb file in which to store the part 
  2174.  
  2175.      See the name of the part's base class 
  2176.  
  2177.      Modify the part's default constructor 
  2178.  
  2179.      Enter additional constructor and destructor code 
  2180.  
  2181.      Specify a .lib file for the part 
  2182.  
  2183.      Specify a resource DLL and ID to assign an icon to the part 
  2184.  
  2185.      Specify other files that you want to include when you build your 
  2186.       application 
  2187.  
  2188.  Use your favorite text editor for creating new classes and member functions, 
  2189.  writing application logic, and modifying existing member functions. 
  2190.  
  2191.  The Class Editor is shown in the following figure: 
  2192.  
  2193.  If you cannot see all of the fields shown in the preceding figure, use the 
  2194.  scroll bar on the right side of the Class Editor to see the remaining fields. 
  2195.  
  2196.  The next section tells you how to enter a description of the part. 
  2197.  
  2198.  
  2199. ΓòÉΓòÉΓòÉ 6.3.2. Entering a Description of a Part ΓòÉΓòÉΓòÉ
  2200.  
  2201. The Description field in the Class Editor is an entry field in which you can 
  2202. enter a description of your part. This description is used in the following 
  2203. places: 
  2204.  
  2205.      If you add your part to the parts palette, the description appears in the 
  2206.       information area at the bottom of the Composition Editor when you select 
  2207.       the part. 
  2208.  
  2209.      If you export your part information into a .vbe file, the description is 
  2210.       included in the first line. 
  2211.  
  2212.       In the following example, the text shown in quotation marks was taken 
  2213.       from the Description field for the ToDoList part. 
  2214.  
  2215.             //VBBeginPartInfo: ToDoList,"To-Do List sample application"
  2216.  
  2217.  
  2218. ΓòÉΓòÉΓòÉ 6.3.3. Moving a Part to a Different .vbb File ΓòÉΓòÉΓòÉ
  2219.  
  2220. The Part file specification field in the Class Editor shows the name of the 
  2221. .vbb file that contains this part. If you want to move this part to another 
  2222. .vbb file while using the Class Editor, do the following: 
  2223.  
  2224.    1. Replace the name of the current .vbb file with the name of another .vbb 
  2225.       file in which you want to store the part. 
  2226.  
  2227.    2. Select FileSave to apply the change. 
  2228.  
  2229.       Visual Builder moves the part from the former .vbb file to the one you 
  2230.       just specified. If the .vbb file you specified does not exist, Visual 
  2231.       Builder creates it for you. 
  2232.  
  2233.  
  2234. ΓòÉΓòÉΓòÉ 6.3.4. Seeing the Base Class of a Part ΓòÉΓòÉΓòÉ
  2235.  
  2236. The Base class - access level field in the Class Editor shows the name of the 
  2237. base class for your part. This is the class name that you specified as the base 
  2238. class when you created the part. 
  2239.  
  2240. This field also shows you the current access level to the base class:  public, 
  2241. protected, or private. 
  2242.  
  2243. You cannot modify the base class name or the access level. 
  2244.  
  2245.  
  2246. ΓòÉΓòÉΓòÉ 6.3.5. Modifying a Part's Constructor ΓòÉΓòÉΓòÉ
  2247.  
  2248. The Constructor field in the Class Editor initially contains a default 
  2249. constructor that Visual Builder inserts for you. If the default constructor 
  2250. does not do exactly what you want it to do, you can modify it by typing over 
  2251. the text in this field. 
  2252.  
  2253. If you want your class to have multiple constructors, we recommend putting them 
  2254. in the .hpv and .cpv files that contain your default feature code and then 
  2255. including them when you generate your code. Otherwise, if you modify your code 
  2256. after generating it, your changes will be lost the next time you generate your 
  2257. code. 
  2258.  
  2259. For information about including files, see Specifying Files for Visual Builder 
  2260. to Include When You Build Your Application. 
  2261.  
  2262.  
  2263. ΓòÉΓòÉΓòÉ 6.3.6. Specifying Your Own Constructor Code ΓòÉΓòÉΓòÉ
  2264.  
  2265. Use the User constructor code field in the Class Editor to enter your own 
  2266. constructor code for the part that you are editing. If you enter code in this 
  2267. field, it is added at the end of the default constructor that Visual Builder 
  2268. provides for you. If you have more than one line of code, put your code into a 
  2269. function and put the function name in this field. Put the code for this 
  2270. function in the files that Visual Builder creates when you generate your 
  2271. default feature code. These file names are specified in the User .hpv file and 
  2272. User .cpv file fields. 
  2273.  
  2274.  
  2275. ΓòÉΓòÉΓòÉ 6.3.7. Specifying Your Own Destructor Code ΓòÉΓòÉΓòÉ
  2276.  
  2277. Use the User destructor code field in the Class Editor to enter your own 
  2278. destructor code for the part that you are editing. If you enter code in this 
  2279. field, it is added at the beginning of the default destructor that Visual 
  2280. Builder provides for you. If you have more than one line of code, put your code 
  2281. into a function and put the function name in this field. Put the code for this 
  2282. function in the files that Visual Builder creates when you generate your 
  2283. default feature code. These file names are specified in the User .hpv file and 
  2284. User .cpv file fields. 
  2285.  
  2286.  
  2287. ΓòÉΓòÉΓòÉ 6.3.8. Specifying a Library File ΓòÉΓòÉΓòÉ
  2288.  
  2289. Use the .LIB file name field in the Class Editor to specify the name of a 
  2290. library file (partname.lib) that you want to to be included when you generate 
  2291. the source code for your part. The library file points to a .dll file that 
  2292. contains information about a subpart in your application that was compiled 
  2293. separately. When you generate the source code for your part, Visual Builder 
  2294. includes a #pragma statement to include the library file. 
  2295.  
  2296. When Visual Builder generates make files for other parts that use this part, 
  2297. the .lib file is specified in the make file as a dependency. 
  2298.  
  2299.  
  2300. ΓòÉΓòÉΓòÉ 6.3.9. Specifying a Starting Resource ID ΓòÉΓòÉΓòÉ
  2301.  
  2302. Use the Starting resource id field in the Class Editor to specify the number 
  2303. that Visual Builder is to use as a starting point for generating resource IDs 
  2304. for your part. The resource IDs that Visual Builder generates are written into 
  2305. a file named partname.h, which Visual Builder creates when you generate code 
  2306. for your part. 
  2307.  
  2308. The check box next to the field enables the starting resource ID. The first 
  2309. time you select this check box, Visual Builder inserts a default starting 
  2310. resource ID. You can change this number. 
  2311.  
  2312. If you deselect the check box, the field is disabled. The number in the field 
  2313. is included in the partname.h file when you generate your code, but it is not 
  2314. referenced. 
  2315.  
  2316. Generating resource IDs is useful if the text in your application is being 
  2317. translated into another language. See Enabling National Language Support for an 
  2318. Application for more information about using starting resource IDs. 
  2319.  
  2320.  
  2321. ΓòÉΓòÉΓòÉ 6.3.10. Specifying a Unique Icon for Your Part ΓòÉΓòÉΓòÉ
  2322.  
  2323. Fill in the fields in the Icon group box in the Class Editor before you add 
  2324. your part to the parts palette so that you can use an icon other than the 
  2325. default icon provided by Visual Builder to represent your part. The default 
  2326. icon is . 
  2327.  
  2328. The Icon group box contains the following fields: 
  2329.  
  2330.  DLL name An entry field in which you enter the name of the resource DLL that 
  2331.    contains the icon you want to use. Enter just the file name, not the 
  2332.    extension. 
  2333.  
  2334.  Resource Id The resource ID number of the icon in the DLL whose name you 
  2335.    entered in the DLL name field. 
  2336.  
  2337.  When you enter both the DLL name and a valid resource ID number, Visual 
  2338.  Builder displays the icon that matches the resource ID number in the area 
  2339.  below the Resource Id field. This occurs when you click on another field. This 
  2340.  allows you to verify that you entered the correct resource ID number. 
  2341.  
  2342.  
  2343. ΓòÉΓòÉΓòÉ 6.3.11. Specifying the Names of Your Code Generation Files ΓòÉΓòÉΓòÉ
  2344.  
  2345. The Code generation files group box in the Class Editor contains the following 
  2346. fields: 
  2347.  
  2348.      A C++ header file (.hpp) field 
  2349.      A C++ code file (.cpp) field 
  2350.  
  2351.  The file names displayed in these fields are the files into which your C++ 
  2352.  header file code and source code are written. This occurs when you generate 
  2353.  default code from the Visual Builder window or from any of the editors by 
  2354.  selecting FileSave and GeneratePart source. 
  2355.  
  2356.  For complete information about generating default source code, see Generating 
  2357.  Source Code for Parts and Applications. 
  2358.  
  2359.  The fields in the group box initially contain .hpp and .cpp file names that 
  2360.  are based on the name of the part you are editing. To change the file names in 
  2361.  these fields, select FileSave so that Visual Builder uses the new file names. 
  2362.  
  2363.  Warning: If the files already exist, Visual Builder replaces their contents 
  2364.  with the code currently being generated. 
  2365.  
  2366.  Visual Builder writes both files to the current directory. 
  2367.  
  2368.  
  2369. ΓòÉΓòÉΓòÉ 6.3.12. Specifying Files to Include When You Build Your Application ΓòÉΓòÉΓòÉ
  2370.  
  2371. The User files included in generation group box in the Class Editor allows you 
  2372. to specify files that you want to be included when you build your application. 
  2373. These fields are typically used to contain the names of the files that hold 
  2374. user code that Visual Builder is to use when you generate default feature code 
  2375. for your part's features. 
  2376.  
  2377. The .hpv and .cpv file extensions are used because the WorkFrame Build tool 
  2378. tries to compile every .cpp file that it finds into an object module (.obj 
  2379. file). Since these files are not meant to be compiled by themselves, we 
  2380. selected a different file extension for you to use to prevent this from 
  2381. happening. 
  2382.  
  2383. The group box contains the following fields: 
  2384.  
  2385.  User .hpv file Use this field to enter the name of a header file that you want 
  2386.    to be included in the header file that Visual Builder generates. You must 
  2387.    enter a file name in this field before you can generate default feature 
  2388.    code. 
  2389.  
  2390.  User .cpv file Use this field to enter the name of a code file that you want 
  2391.    to be included in the source code file that Visual Builder generates. You 
  2392.    must enter a file name in this field before you can generate default feature 
  2393.    code. 
  2394.  
  2395.  User .h file Use this field to enter the name of a resource header file that 
  2396.    contains resource IDs for your application other than those that Visual 
  2397.    Builder generates for you in the partname.h file. This file is included in 
  2398.    partname.h. 
  2399.  
  2400.  User .rcv file Use this field to enter the name of a resource file that 
  2401.    contains text strings used in your application other than those that Visual 
  2402.    Builder generates for you in the partname.rc file. This file is included in 
  2403.    partname.rc. 
  2404.  
  2405.    The .rcv file extension is used because the WorkFrame Build tool tries to 
  2406.    compile every .rc file that it finds into a binary resource (.res) file. 
  2407.    Since partial resource files cannot always be compiled by themselves, we 
  2408.    selected a different file extension for you to use to prevent this from 
  2409.    happening. 
  2410.  
  2411.  Required include files This field is a multiline entry field in which you can 
  2412.    enter the names of other files that you want Visual Builder to include when 
  2413.    you generate default source code for your application. Some examples of 
  2414.    files that you might want to include are the following: 
  2415.  
  2416.        Standard C++ library files, such as streamio.h 
  2417.        IBM Open Class Library header files, such as IString.hpp 
  2418.  
  2419.    Visual Builder generates the #include statements in the default source code. 
  2420.  
  2421.    If you type a label next to the file name, Visual Builder uses that label to 
  2422.    generate #ifndef and #endif statements for you. For example, if you want to 
  2423.    include the header file for an address part that you created, you might 
  2424.    enter the following in the Additional Include Files field: 
  2425.  
  2426.       address.hpp  _ADDRESS_
  2427.  
  2428.    This would cause Visual Builder to generate the following in your default 
  2429.    .cpp source code file: 
  2430.  
  2431.       #ifndef _ADDRESS_
  2432.       #include <address.hpp>
  2433.       #endif
  2434.  
  2435.    If you omit the label, Visual Builder generates only the #include statement. 
  2436.  
  2437.  
  2438. ΓòÉΓòÉΓòÉ 6.4. The Part Interface Editor ΓòÉΓòÉΓòÉ
  2439.  
  2440.      Introducing the Part Interface Editor 
  2441.  
  2442.      The Attribute page 
  2443.  
  2444.      The Event page 
  2445.  
  2446.      The Action page 
  2447.  
  2448.      The Promote page 
  2449.  
  2450.      The Preferred page 
  2451.  
  2452.  Personal notes: 
  2453.  
  2454.  
  2455. ΓòÉΓòÉΓòÉ 6.4.1. Introducing the Part Interface Editor ΓòÉΓòÉΓòÉ
  2456.  
  2457. Each part that Visual Builder provides has a defined part interface that allows 
  2458. the part to interact with other parts. The part interface consists of 
  2459. features-attributes, events, and actions-that allow you to use the part in 
  2460. constructing your application. An entry field, for example, has a text 
  2461. attribute, a push button has a buttonClickEvent feature, and a frame window has 
  2462. a setFocus action. 
  2463.  
  2464. The parts that you create must also have a defined part interface so they can 
  2465. be used. Use the Part Interface Editor to define that interface. See Creating 
  2466. Parts for Reuse to learn more about building reusable parts. 
  2467.  
  2468. Other uses for the Part Interface Editor include the following: 
  2469.  
  2470.      Viewing the interface of a part 
  2471.      Modifying or extending the interface of an existing part 
  2472.      Creating or altering the list of preferred features, the features that 
  2473.       are displayed in the pop-up connection menu for a part 
  2474.  
  2475.  The Part Interface Editor is a notebook made up of the following visual 
  2476.  components: 
  2477.  
  2478.      The Attribute page 
  2479.      The Event page 
  2480.      The Action page 
  2481.      The Promote page 
  2482.      The Preferred page 
  2483.  
  2484.  
  2485. ΓòÉΓòÉΓòÉ 6.4.2. The Attribute Page ΓòÉΓòÉΓòÉ
  2486.  
  2487. Use the Attribute page of the Part Interface Editor, shown in the following 
  2488. figure, to define the attributes for your part. 
  2489.  
  2490. You can define many attributes for a part, each with unique characteristics, 
  2491. such as name and data type. An attribute's value is always acquired by using 
  2492. the attribute's get and set member functions. It is up to you whether data for 
  2493. the attribute is stored in a data member, calculated, or acquired from some 
  2494. other location. 
  2495.  
  2496. In addition, you can define three different kinds of behavior for your 
  2497. attributes, as follows: 
  2498.  
  2499.  full attribute A full attribute contains all of the characteristics and 
  2500.    behaviors that are available for an attribute, as follows: 
  2501.  
  2502.        A get member function, which is required 
  2503.        A set member function, which is optional (see no-set attribute below) 
  2504.        An event identifier, which is optional (see no-event attribute below) 
  2505.  
  2506.  no-set attribute A no-set attribute has no set member function. It can 
  2507.    initialize another attribute if it is the source of an 
  2508.    attribute-to-attribute connection, but it cannot set itself to the value of 
  2509.    another attribute. 
  2510.  
  2511.  no-event attribute A no-event attribute has no event identifier. Therefore, if 
  2512.    you use a no-event attribute as the source of a connection, it cannot signal 
  2513.    another part because of the lack of an event identifier. However, you can 
  2514.    still use it as the source of connections so that it can initialize other 
  2515.    attributes. 
  2516.  
  2517.  
  2518. ΓòÉΓòÉΓòÉ 6.4.2.1. Adding an Attribute ΓòÉΓòÉΓòÉ
  2519.  
  2520. To add an attribute in the Part Interface Editor, do one of the following: 
  2521.  
  2522.      If you want to add the attribute using the default attribute type, get 
  2523.       member function, set member function, and event identification that 
  2524.       Visual Builder provides, enter a name in the Attribute name field and 
  2525.       select the Add with defaults push button. 
  2526.  
  2527.       Visual Builder adds the attribute to the part interface. 
  2528.  
  2529.      If you want to see the default attribute type, get member function, set 
  2530.       member function, and event identification that Visual Builder provides 
  2531.       before you add the attribute, select the Defaults push button. 
  2532.  
  2533.       Visual Builder displays the default information for the attribute in the 
  2534.       fields on the right side of the Attribute page. Here are descriptions of 
  2535.       those fields: 
  2536.  
  2537.       Attribute name The name of the attribute. This name appears in the 
  2538.              connection menu for the part when you make connections to or from 
  2539.              it in the Composition Editor. 
  2540.  
  2541.       Attribute type The data type of the attribute. The first time you create 
  2542.              an attribute for your part, the default data type that Visual 
  2543.              Builder uses is int. If you change int to another data type, such 
  2544.              as IString, the new data type becomes the default data type for 
  2545.              any new attributes that you create until you change it to 
  2546.              something else or close the Part Interface Editor window. When you 
  2547.              reopen the Part Interface Editor window, the default data type for 
  2548.              any new attributes that you create reverts to int. It stays that 
  2549.              way unless you change it again when creating another attribute or 
  2550.              when modifying an existing attribute. 
  2551.  
  2552.              You typically define attributes as private data members to protect 
  2553.              them from being changed by users of the part. The get and set 
  2554.              member functions that you define for an attribute give other 
  2555.              programmers access to the attribute's value. You probably do not 
  2556.              want to expose all of the data members of your part as attributes, 
  2557.              particularly if you intend to share the part with other 
  2558.              programmers. You only need to decide which of the data members you 
  2559.              want to make available for other programmers to reference. Some of 
  2560.              your data members might be used for implementation purposes, so 
  2561.              you would not want to identify these as attributes. 
  2562.  
  2563.       Get member function The public member function used by the part and other 
  2564.              parts to query or get the value of the attribute. 
  2565.  
  2566.       Set member function The public member function used by the part and other 
  2567.              parts to set the value of the attribute. An event identifier is 
  2568.              typically signalled from within the implementation of the set 
  2569.              member function to indicate that the value of the attribute 
  2570.              changed. 
  2571.  
  2572.              If you press either the Defaults or Add with defaults push button, 
  2573.              Visual Builder uses the data type in the Attribute type field to 
  2574.              determine whether the parameter on the set member function passes 
  2575.              the actual value of the attribute being set or simply references 
  2576.              the location of that value, as follows: 
  2577.  
  2578.                -  If the data type in the Attribute type field represents the 
  2579.                   class name of a part in a loaded .vbb file, Visual Builder 
  2580.                   references the location of the value that is to be used to 
  2581.                   set the attribute. 
  2582.  
  2583.                   For example, suppose you create a part named MyPart. If you 
  2584.                   create a text attribute for MyPart with a data type of 
  2585.                   IString and select either Defaults or Add with defaults, 
  2586.                   Visual Builder puts the following in the Set member function 
  2587.                   field: 
  2588.  
  2589.                                     MyPart & setText(const IString &aText)
  2590.  
  2591.                   The & in front of the aText parameter means that, unless you 
  2592.                   modify this member function, it passes a reference to the 
  2593.                   value being used to set the text attribute. The & is used 
  2594.                   because IString is defined as a part in vbbase.vbb. 
  2595.  
  2596.                -  If the data type in the Attribute type field is not defined 
  2597.                   in any loaded .vbb file, or if it is defined in a .vbb file 
  2598.                   but it does not represent the class name of a part, Visual 
  2599.                   Builder passes the actual value that is to be set for the 
  2600.                   attribute. 
  2601.  
  2602.                   Using the MyPart example again, if you put an undefined data 
  2603.                   type in the Attribute type field before selecting either 
  2604.                   Defaults or Add with defaults, Visual Builder puts the 
  2605.                   following in the Set member function field: 
  2606.  
  2607.                                     MyPart & setText(const myType aText)
  2608.  
  2609.                   In this example, unless you modify this member function, it 
  2610.                   passes the actual value being used to set the text attribute. 
  2611.  
  2612.       Event identification The name of the event identifier that is typically 
  2613.              signalled from within the implementation of the set member 
  2614.              function. You can create one of your own or you can use the 
  2615.              default event identifier that Visual Builder supplies when you 
  2616.              select either Defaults or Add with defaults. 
  2617.  
  2618.              Use this identifier to notify this part and other parts that the 
  2619.              attribute's value has changed. This is typically done when the 
  2620.              attribute is used as the source of a connection. The connection 
  2621.              types that use an attribute as the source of a connection are: 
  2622.  
  2623.                -  Attribute-to-attribute 
  2624.                -  Attribute-to-action 
  2625.                -  Attribute-to-member function 
  2626.                -  Custom logic, which can use either an attribute or an event 
  2627.                   as the source of a connection 
  2628.  
  2629.              You are not required to specify an event identification for any 
  2630.              attribute because you are not required to notify other parts when 
  2631.              the value of the attribute changes. However, failing to do so 
  2632.              could prevent your application from passing necessary information 
  2633.              from one part to another when it is needed. 
  2634.  
  2635.              The event identifier is typically signalled from within the 
  2636.              implementation of the attribute's set member function, causing the 
  2637.              attribute to behave as an event. Therefore, you do not need to 
  2638.              specify another event with this event identifier on the Event page 
  2639.              of the Part Interface Editor. 
  2640.  
  2641.       Description A description of the attribute. This entry field is blank 
  2642.              unless you enter a description, or you select either the Defaults 
  2643.              or Add with defaults push button, in which case Visual Builder 
  2644.              supplies a default description consisting of the attribute's name. 
  2645.  
  2646.      If you want to add the attribute after seeing or modifying its default 
  2647.       information or after entering your own information, select the Add push 
  2648.       button. 
  2649.  
  2650.       Visual Builder adds the attribute to the part interface. 
  2651.  
  2652.  
  2653. ΓòÉΓòÉΓòÉ 6.4.2.2. Changing an Attribute ΓòÉΓòÉΓòÉ
  2654.  
  2655. To change, or update, an attribute in the Part Interface Editor, do the 
  2656. following. 
  2657.  
  2658. Note:  You can change anything about an attribute except its name. To change an 
  2659.        attribute's name, you must create a new attribute with the name you want 
  2660.        to use. 
  2661.  
  2662.    1. Select the attribute that you want to change or type its name in the 
  2663.       Attribute name field. 
  2664.  
  2665.    2. Make the changes that you want to make in the fields on the right side of 
  2666.       the Attribute page. 
  2667.  
  2668.    3. Select the Update push button. 
  2669.  
  2670.       Visual Builder saves the changes you made. 
  2671.  
  2672.  
  2673. ΓòÉΓòÉΓòÉ 6.4.2.3. Deleting an Attribute ΓòÉΓòÉΓòÉ
  2674.  
  2675. To delete an attribute in the Part Interface Editor, do the following: 
  2676.  
  2677.    1. Select the attribute that you want to delete or type its name in the 
  2678.       Attribute name field. 
  2679.  
  2680.    2. Select the Delete push button. 
  2681.  
  2682.       Visual Builder deletes the attribute. 
  2683.  
  2684.       Note:  If you added the attribute that you just deleted to the preferred 
  2685.              features list, you must go to the Preferred page and delete it 
  2686.              there, too. 
  2687.  
  2688.  
  2689. ΓòÉΓòÉΓòÉ 6.4.2.4. Setting Defaults for an Attribute ΓòÉΓòÉΓòÉ
  2690.  
  2691. To set defaults for an attribute in the Part Interface Editor, do the 
  2692. following: 
  2693.  
  2694.    1. Select the attribute that you want to set defaults for or type its name 
  2695.       in the Attribute name field. 
  2696.  
  2697.    2. Change the attribute type in the Attribute type field. 
  2698.  
  2699.    3. Select the Defaults push button. 
  2700.  
  2701.       Visual Builder changes all occurrences of the former attribute type to 
  2702.       the new attribute type in the fields on the right side of the Attribute 
  2703.       page. 
  2704.  
  2705.  
  2706. ΓòÉΓòÉΓòÉ 6.4.2.5. Clearing the Attribute Page Fields ΓòÉΓòÉΓòÉ
  2707.  
  2708. To clear the fields on the Attribute page, select the Clear push button. 
  2709.  
  2710. Visual Builder clears all of the fields on the Attribute page. 
  2711.  
  2712.  
  2713. ΓòÉΓòÉΓòÉ 6.4.2.6. An Attribute Example ΓòÉΓòÉΓòÉ
  2714.  
  2715. Suppose you create a nonvisual Customer part that inherits from Visual 
  2716. Builder's sample ICustomer part. You also create an age attribute for which you 
  2717. specify the following: 
  2718.  
  2719.      An attribute type of IString 
  2720.      An age get member function 
  2721.      A setAge set member function 
  2722.      An ageId event notifier 
  2723.  
  2724.  You create this attribute so other parts can access its value or so it can be 
  2725.  passed as a parameter value. 
  2726.  
  2727.  Note:  Visual Builder does not use the value that is passed on the attribute's 
  2728.         event. It uses the attribute's get member function instead. 
  2729.  
  2730.  The default feature code that Visual Builder would generate for the age 
  2731.  attribute would be similar to these code segments, which show the following: 
  2732.  
  2733.      The declarations of the get member function, set member function, event 
  2734.       identifier, and data member in the user header (.hpv) file. 
  2735.  
  2736.             public:
  2737.               IString age() const;            /* Get member function */
  2738.               Customer & setAge(
  2739.                  const IString &aAge);        /* Set member function */
  2740.  
  2741.               static INotificationId ageId;   /* Event notifier      */
  2742.  
  2743.             private:
  2744.               IString iAge;                   /* Data member         */
  2745.  
  2746.      The event notifier initialized as a text string, followed by the get and 
  2747.       set member functions for the age attribute, as defined in the user source 
  2748.       code (.cpv) file. 
  2749.  
  2750.             INotificationId Customer::ageId = "Customer::ageId";
  2751.  
  2752.             IString Customer::age() const          /* The age attribute's get */
  2753.             {                                      /* member function returns  */
  2754.               return iAge;                         /* the value of the data    */
  2755.             }                                      /* member.                  */
  2756.  
  2757.             Customer & Customer::setAge(           /* The age attribute's set */
  2758.                       const IString & aAge)        /* member function sends   */
  2759.             {                                      /* the event notification   */
  2760.               if (iAge != aAge)                    /* when the text changes.   */
  2761.               {
  2762.                 iAge = aAge;
  2763.                 IString eventData(iAge);
  2764.                 notifyObservers(INotificationEvent(Customer::ageId, *this,
  2765.                                 true, (void *)&eventData));
  2766.               } /* endif */
  2767.               return *this;
  2768.             }
  2769.  
  2770.  
  2771. ΓòÉΓòÉΓòÉ 6.4.3. The Event Page ΓòÉΓòÉΓòÉ
  2772.  
  2773. Use the Event page of the Part Interface Editor, shown in the following figure, 
  2774. to define the events you use to notify this part or other parts about changes 
  2775. you decide are significant. For example, you might notify other parts when an 
  2776. attribute is set to a certain value or when important processing is finished. 
  2777. In this way, someone using your reusable part can link to one of your part's 
  2778. events and receive automatic notification of the event whenever it is 
  2779. triggered. 
  2780.  
  2781. If you cannot see all of the fields shown in the preceding figure, use the 
  2782. scroll bar on the right side of the Part Interface Editor to see the remaining 
  2783. fields. 
  2784.  
  2785. The names of the part's events are displayed in the list box named Event name. 
  2786. When you create a new part, the first time you open the Part Interface Editor 
  2787. and turn to the Event page, you see that Visual Builder has provided an event 
  2788. for you:  the ready event. 
  2789.  
  2790.  
  2791. ΓòÉΓòÉΓòÉ 6.4.3.1. The Ready Event ΓòÉΓòÉΓòÉ
  2792.  
  2793. Visual Builder adds the ready event to every new part that you create using the 
  2794. PartNew menu choice in the Visual Builder window. However, this event is not 
  2795. added if you import part information from a part information file (.vbe file). 
  2796.  
  2797. By connecting the ready event to one of your part's subparts, you can cause an 
  2798. action or member function to be invoked when your application is executed. The 
  2799. ready event is sent to the part when both of the following occur: 
  2800.  
  2801.      All subparts of the part have been constructed. 
  2802.      All connections have been made and initialized. 
  2803.  
  2804.  For example, suppose you have a part named MyApp and this part is an 
  2805.  application that has a window that contains an animated push button. By 
  2806.  connecting the MyApp part's ready event to the animated push button's 
  2807.  startAnimation action, you cause the push button to become animated as soon as 
  2808.  the application starts running. 
  2809.  
  2810.  The ready event is not a preferred feature by default, but you can add it to 
  2811.  your part's preferred features list. For information on how to do this, see 
  2812.  The Preferred Page. 
  2813.  
  2814.  
  2815. ΓòÉΓòÉΓòÉ 6.4.3.2. Adding an Event ΓòÉΓòÉΓòÉ
  2816.  
  2817. To add an event in the Part Interface Editor, do one of the following: 
  2818.  
  2819.      If you want to add the event using the default event identification that 
  2820.       Visual Builder provides, enter a name in the Event name field and select 
  2821.       the Add with defaults push button. 
  2822.  
  2823.       Visual Builder adds the event to the part interface. 
  2824.  
  2825.      If you want to see the default event identification that Visual Builder 
  2826.       provides before you add the event, select the Defaults push button. 
  2827.  
  2828.       Visual Builder displays the default event identification in the Event 
  2829.       identification field on the right side of the Event page. Here are 
  2830.       descriptions of that field and the other fields on the page: 
  2831.  
  2832.       Event name The name of the event. This name appears in the pop-up menu 
  2833.              for the part when you make connections to or from it in the 
  2834.              Composition Editor if you add it to the preferred features list. 
  2835.  
  2836.       Event identification The name of the event identifier that is actually 
  2837.              used in a member function signalling this event. 
  2838.  
  2839.       Description A description of the event. This entry field is blank unless 
  2840.              you enter a description or unless you select either the Defaults 
  2841.              or Add with defaults push button. In the latter case, Visual 
  2842.              Builder inserts a default description consisting of the event's 
  2843.              name. 
  2844.  
  2845.       Parameters and their types A table used to define a parameter and data 
  2846.              type sent as part of an event. 
  2847.  
  2848.              Name         The name of the event parameter. 
  2849.  
  2850.              Type         The class, or data type, of the event parameter, such 
  2851.                           as IString, integer, or unsigned long. 
  2852.  
  2853.              The parameter that you specify in this table is used to specify 
  2854.              event data, or a reference to that data's location, that you want 
  2855.              to send along with the event identifier as part of the event. 
  2856.              Doing this prevents you from having to perform a separate query 
  2857.              for the data. 
  2858.  
  2859.  To add a parameter and its type to this table, do the following. 
  2860.  
  2861.  Note:  You can add only one parameter and type for each event. 
  2862.  
  2863.    1. Move the mouse pointer over the table and click mouse button 2. 
  2864.  
  2865.       Visual Builder displays a pop-up menu. 
  2866.  
  2867.    2. Select either Add before or Add after. 
  2868.  
  2869.       Visual Builder adds a row to the table with a default parameter name and 
  2870.       type. 
  2871.  
  2872.    3. If you want to change the defaults, do the following: 
  2873.  
  2874.         a. Click on the parameter name with mouse button 1. 
  2875.  
  2876.         b. Type the parameter name you want to use. 
  2877.  
  2878.         c. Click on the parameter type with mouse button 1. 
  2879.  
  2880.         d. Type the parameter type you want to use. 
  2881.  
  2882.         e. Select the Update push button. 
  2883.  
  2884.  
  2885. ΓòÉΓòÉΓòÉ 6.4.3.3. Changing an Event ΓòÉΓòÉΓòÉ
  2886.  
  2887. To change, or update, an event, do the following. 
  2888.  
  2889. Note:  You can change anything about an event except its name. To change an 
  2890.        event's name, you must create a new event with the name you want to use. 
  2891.  
  2892.    1. Select the event that you want to change or type its name in the Event 
  2893.       name field. 
  2894.  
  2895.    2. Make the changes that you want to make in the fields on the right side of 
  2896.       the Event page. 
  2897.  
  2898.    3. Select the Update push button. 
  2899.  
  2900.       Visual Builder saves the changes you made. 
  2901.  
  2902.  
  2903. ΓòÉΓòÉΓòÉ 6.4.3.4. Deleting an Event ΓòÉΓòÉΓòÉ
  2904.  
  2905. To delete an event, do the following: 
  2906.  
  2907.    1. Select the event that you want to delete or type its name in the Event 
  2908.       name field. 
  2909.  
  2910.    2. Select the Delete push button. 
  2911.  
  2912.       Visual Builder deletes the event. 
  2913.  
  2914.       Note:  If you added the event that you just deleted to the preferred 
  2915.              features list, you must go to the Preferred page and delete it 
  2916.              there, too. 
  2917.  
  2918.  
  2919. ΓòÉΓòÉΓòÉ 6.4.3.5. Setting Defaults for an Event ΓòÉΓòÉΓòÉ
  2920.  
  2921. To set defaults for an event, do the following: 
  2922.  
  2923.    1. Select the event that you want to set defaults for or type its name in 
  2924.       the Event name field. 
  2925.  
  2926.    2. Select the Defaults push button. 
  2927.  
  2928.       Visual Builder changes the former event identification to the default 
  2929.       event identification in the Event identification field. 
  2930.  
  2931.  
  2932. ΓòÉΓòÉΓòÉ 6.4.3.6. Clearing the Event Page Fields ΓòÉΓòÉΓòÉ
  2933.  
  2934. To clear the fields on the Event page, select the Clear push button. 
  2935.  
  2936. Visual Builder clears all of the fields on the Event page. 
  2937.  
  2938.  
  2939. ΓòÉΓòÉΓòÉ 6.4.3.7. An Event Example ΓòÉΓòÉΓòÉ
  2940.  
  2941. Using the same example shown for the Attribute page, suppose you also create an 
  2942. invalidDataEntered event for which you specify the following: 
  2943.  
  2944.      An invalidDataEnteredId event notifier 
  2945.      An invalidData parameter with a data type of IString 
  2946.  
  2947.  You create this event because you want to show an error message for the 
  2948.  Customer part whenever invalid data is entered for any of the Customer part's 
  2949.  attributes, such as the customer's age being outside a valid range. Then, in 
  2950.  your source code for the age attribute's set member function, you can call the 
  2951.  notifyObservers member function to display a message asking for a valid age if 
  2952.  the check fails. 
  2953.  
  2954.  The default feature code that Visual Builder would generate for the 
  2955.  invalidDataEnteredId event notifier would be similar to these code segments, 
  2956.  which show the following: 
  2957.  
  2958.      The declarations of the get member function, set member function, event 
  2959.       identifiers, and data member in the user header (.hpv) file. 
  2960.  
  2961.       Note:  Sample code highlighted in bold shows the code that was added to 
  2962.              modify the previous example. 
  2963.  
  2964.             public:
  2965.               IString age() const;            /* Get member function */
  2966.               Customer & setAge(
  2967.                  const IString &aAge);        /* Set member function */
  2968.  
  2969.               static INotificationId ageId;   /* Event notifiers     */
  2970.               static INotificationId invalidDataEnteredId;
  2971.  
  2972.             private:
  2973.               IString iAge;                   /* Data member         */
  2974.  
  2975.      The event notifier initialized as a text string, followed by the get and 
  2976.       set member functions for the age attribute, as defined in the user source 
  2977.       code (.cpv) file. 
  2978.  
  2979.             INotificationId Customer::ageId = "Customer::ageId";
  2980.             INotificationId Customer::invalidDataEnteredId =
  2981.                  "Customer::invalidDataEnteredId";
  2982.  
  2983.             IString Customer::age() const          /* The age attribute's get */
  2984.             {                                      /* member function returns  */
  2985.               return iAge;                         /* the value of the data    */
  2986.             }                                      /* member.                  */
  2987.  
  2988.             Customer & Customer::setAge(           /* The age attribute's set */
  2989.                       const IString &aAge)         /* member function sends   */
  2990.             {                                      /* the event notification   */
  2991.               if (aAge > 99)
  2992.               {
  2993.                 notifyObservers(
  2994.                       INotificationEvent(
  2995.                            Customer::invalidDataEnteredId,
  2996.                            *this,
  2997.                            true,
  2998.                            (void *) IString("Enter a value between 1 and 99.")));
  2999.               }
  3000.               else
  3001.               {
  3002.               if (iAge != aAge)
  3003.                  {
  3004.                  iAge = aAge;
  3005.                  IString eventData(iAge);
  3006.                  notifyObservers(INotificationEvent(Customer::ageId, *this,
  3007.                                  true, (void *)&eventData));
  3008.                  } /* endif */
  3009.               }
  3010.               return *this;
  3011.             }
  3012.  
  3013.  
  3014. ΓòÉΓòÉΓòÉ 6.4.4. The Action Page ΓòÉΓòÉΓòÉ
  3015.  
  3016. Use the Action page of the Part Interface Editor, shown in the following 
  3017. figure, to define the actions your reusable part uses to perform specific 
  3018. tasks. Often, you will want to perform some task when a specific event occurs. 
  3019.  
  3020. For example, you might want to update a balance attribute each time a push 
  3021. button's buttonClickEvent feature is triggered. You might create an action 
  3022. named updateBalance to perform this task and connect it to the push button's 
  3023. buttonClickEvent feature. 
  3024.  
  3025. The names of the part's actions are displayed in the list box below the Action 
  3026. name field. 
  3027.  
  3028.  
  3029. ΓòÉΓòÉΓòÉ 6.4.4.1. Adding an Action ΓòÉΓòÉΓòÉ
  3030.  
  3031. To add an action in the Part Interface Editor, do one of the following: 
  3032.  
  3033.      If you want to add the action using the part you are editing as the 
  3034.       default return type, enter a name in the Action name field and select the 
  3035.       Add with defaults push button. 
  3036.  
  3037.       Visual Builder adds the action to the part interface. 
  3038.  
  3039.      If you want to see the default return type before you add the action, 
  3040.       select the Defaults push button. 
  3041.  
  3042.       Visual Builder displays the default return type in the Return type field, 
  3043.       as well as in the Action member function field, on the right side of the 
  3044.       Action page. Here are descriptions of those fields and the other fields 
  3045.       on the page: 
  3046.  
  3047.       Action name The name of the action. This name appears in the pop-up menu 
  3048.              for the part when you make connections to or from it in the 
  3049.              Composition Editor if you add it to the preferred features list. 
  3050.  
  3051.       Action member function The name of the public member function, defined 
  3052.              within your reusable part, that performs the action. 
  3053.  
  3054.       Return type The return type of the action member function. 
  3055.  
  3056.       Description A description of the action. 
  3057.  
  3058.       Parameter Names Parameters of the selected action. Initially, the names 
  3059.              that are inserted in the Parameter Names table are the same as the 
  3060.              parameter names that are specified in the Action member function 
  3061.              field. 
  3062.  
  3063.              The parameter names in the table are linked to the action name and 
  3064.              can appear in a pop-up connection menu. The purpose of the table 
  3065.              is to allow you to change the parameter names that appear in the 
  3066.              part interface without affecting the member function definition 
  3067.              itself. That is, if you change the parameter names in the table, 
  3068.              the parameter names in the Action member function field do not 
  3069.              change. 
  3070.  
  3071.              Here are some reasons for using the Parameter Names table: 
  3072.  
  3073.                -  To give parameters descriptive names. 
  3074.  
  3075.                   You can give parameters that appear in pop-up connection 
  3076.                   menus names that are more descriptive than those in the 
  3077.                   member function definition. 
  3078.  
  3079.                -  To associate specific parameter names with actions. 
  3080.  
  3081.                   You might have more than one action name for the same public 
  3082.                   member function. If so, to make your part interface easier to 
  3083.                   use, you might not want to have the same parameter name 
  3084.                   associated with each action. The Parameter Names table allows 
  3085.                   you associate separate, descriptive parameter names with each 
  3086.                   action, even though those names represent the same parameter 
  3087.                   in the same member function. 
  3088.  
  3089.                -  To change a member function without changing its action name 
  3090.                   in the part interface. 
  3091.  
  3092.                   You might decide to change a member function. For example, 
  3093.                   you might rename a parameter or substitute another member 
  3094.                   function entirely. The Parameter Names table allows you to do 
  3095.                   this without having to change your part interface. You can 
  3096.                   modify and then update the information in the Action member 
  3097.                   function field without changing the parameter names in the 
  3098.                   table. Therefore, if other programmers are using your part, 
  3099.                   they continue to see the same part interface. They would only 
  3100.                   need to regenerate their source code. 
  3101.  
  3102.  
  3103. ΓòÉΓòÉΓòÉ 6.4.4.2. Changing an Action ΓòÉΓòÉΓòÉ
  3104.  
  3105. To change, or update, an action in the Part Interface Editor, do the following. 
  3106.  
  3107. Note:  You can change anything about an action except its name. To change an 
  3108.        action's name, you must create a new action with the name you want to 
  3109.        use. 
  3110.  
  3111.    1. Select the action that you want to change or type its name in the Action 
  3112.       name field. 
  3113.  
  3114.    2. Make the changes that you want to make in the fields on the right side of 
  3115.       the Action page. 
  3116.  
  3117.    3. Select the Update push button. 
  3118.  
  3119.       Visual Builder saves the changes you made. 
  3120.  
  3121.  
  3122. ΓòÉΓòÉΓòÉ 6.4.4.3. Deleting an Action ΓòÉΓòÉΓòÉ
  3123.  
  3124. To delete an action in the Part Interface Editor, do the following: 
  3125.  
  3126.    1. Select the action that you want to delete or type its name in the Action 
  3127.       name field. 
  3128.  
  3129.    2. Select the Delete push button. 
  3130.  
  3131.       Visual Builder deletes the action. 
  3132.  
  3133.       Note:  If you added the action that you just deleted to the preferred 
  3134.              features list, you must go to the Preferred page and delete it 
  3135.              there, too. 
  3136.  
  3137.  
  3138. ΓòÉΓòÉΓòÉ 6.4.4.4. Setting Defaults for an Action ΓòÉΓòÉΓòÉ
  3139.  
  3140. To set defaults for an action in the Part Interface Editor, do the following: 
  3141.  
  3142.    1. Select the action that you want to set defaults for or type its name in 
  3143.       the Action name field. 
  3144.  
  3145.    2. Select the Defaults push button. 
  3146.  
  3147.       Visual Builder changes the former return type to the default return type 
  3148.       in both the Action member function and the Return type fields. 
  3149.  
  3150.  
  3151. ΓòÉΓòÉΓòÉ 6.4.4.5. Clearing the Action Page Fields ΓòÉΓòÉΓòÉ
  3152.  
  3153. To clear the fields on the Action page, select the Clear push button. 
  3154.  
  3155. Visual Builder clears all of the fields on the Action page. 
  3156.  
  3157.  
  3158. ΓòÉΓòÉΓòÉ 6.4.5. The Promote Page ΓòÉΓòÉΓòÉ
  3159.  
  3160. Use the Promote page of the Part Interface Editor to specify features that you 
  3161. want to connect to another part when this part is embedded as a subpart within 
  3162. another part. The features (attributes, events, and actions) that you specify 
  3163. appear in the window that is displayed when you select More from this part's 
  3164. pop-up connection menu. For a complete description of promoting a part's 
  3165. features, see Promoting a Part's Features. 
  3166.  
  3167. The following figure shows the Promote page: 
  3168.  
  3169.  
  3170. ΓòÉΓòÉΓòÉ 6.4.5.1. Promoting a Feature ΓòÉΓòÉΓòÉ
  3171.  
  3172. To promote a feature in the Part Interface Editor for a subpart, do the 
  3173. following: 
  3174.  
  3175.    1. Select a subpart name from the list box beneath the Subpart name field or 
  3176.       type the name in the field. 
  3177.  
  3178.       Visual Builder displays the name of the subpart that you select in the 
  3179.       Subpart name field. 
  3180.  
  3181.    2. Select a feature type from the list box beneath the Feature type field or 
  3182.       type the name in the field. 
  3183.  
  3184.       Visual Builder displays the type that you select (attribute, event, or 
  3185.       action) in the the Feature type field. 
  3186.  
  3187.    3. Select the feature that you want to promote from the list box beneath the 
  3188.       Promotable feature field or type the name in the field. 
  3189.  
  3190.       Visual Builder displays the feature that you select in the Promotable 
  3191.       feature field. 
  3192.  
  3193.    4. Do one of the following: 
  3194.  
  3195.           If you want to promote the feature using the default name that 
  3196.            Visual Builder provides, select the Add with defaults push button. 
  3197.  
  3198.            Visual Builder promotes the feature and displays the feature name in 
  3199.            both the Promote feature name field and in the list box below this 
  3200.            field. 
  3201.  
  3202.           If you want to see the default feature name that Visual Builder 
  3203.            provides before you promote the feature, select the Defaults push 
  3204.            button. 
  3205.  
  3206.            Visual Builder displays the default name for the feature in the 
  3207.            Promote feature name field. 
  3208.  
  3209.           If you want to promote a feature after seeing its default name or 
  3210.            typing another name that you prefer, select the Add push button. 
  3211.  
  3212.            Visual Builder promotes the feature using the name in the Promote 
  3213.            feature name field and displays the name in the list box below this 
  3214.            field. 
  3215.  
  3216.  
  3217. ΓòÉΓòÉΓòÉ 6.4.5.2. Changing a Promoted Feature ΓòÉΓòÉΓòÉ
  3218.  
  3219. To update a feature that you have already promoted, do the following: 
  3220.  
  3221.    1. Select the promoted feature that you want to update. 
  3222.  
  3223.    2. Select those aspects of the promoted feature that you want to update in 
  3224.       the fields on the right side of the Promote page. You can select any or 
  3225.       all of the following: 
  3226.  
  3227.           Subpart name 
  3228.           Feature type 
  3229.           Promotable feature 
  3230.  
  3231.    3. Select the Update push button. 
  3232.  
  3233.       Visual Builder updates those aspects of the feature that you selected. 
  3234.  
  3235.  The only noticeable change is the subpart name if you selected a different 
  3236.  one. The subpart name shown in parentheses behind the promoted feature name 
  3237.  changes if you selected a different subpart. For example, suppose you promoted 
  3238.  the buttonClickEvent feature of PushButton1 and then realized you should have 
  3239.  promoted the buttonClickEvent feature of PushButton2. Instead of deleting the 
  3240.  promoted feature, you can update it by changing only its subpart. 
  3241.  
  3242.  
  3243. ΓòÉΓòÉΓòÉ 6.4.5.3. Deleting a Promoted Feature ΓòÉΓòÉΓòÉ
  3244.  
  3245. To delete a promoted feature, do the following: 
  3246.  
  3247.    1. Select the promoted feature that you want to delete. 
  3248.  
  3249.    2. Select the Delete push button. 
  3250.  
  3251.       Visual Builder deletes the promoted feature from the list box beneath the 
  3252.       Promote feature name field. 
  3253.  
  3254.       Note:  If you added the promoted feature that you just deleted to the 
  3255.              preferred features list, you must go to the Preferred page and 
  3256.              delete it there, too. 
  3257.  
  3258.  
  3259. ΓòÉΓòÉΓòÉ 6.4.5.4. Clearing the Promote Page Fields ΓòÉΓòÉΓòÉ
  3260.  
  3261. To clear the fields on the Promote page, select the Clear push button. Visual 
  3262. Builder removes the information from all of the fields on the page. 
  3263.  
  3264.  
  3265. ΓòÉΓòÉΓòÉ 6.4.6. The Preferred Page ΓòÉΓòÉΓòÉ
  3266.  
  3267. Use the Preferred page of the Part Interface Editor to specify the preferred 
  3268. features for your part-the features that you use most often when connecting 
  3269. this part to another part. The features (attributes, events, and actions) that 
  3270. you specify appear in the pop-up menu that is displayed when you begin a 
  3271. connection on this part. You can include any features that exist for your part, 
  3272. as well as any features that your part inherits from other parts. 
  3273.  
  3274. In addition to these features, the pop-up connection menu contains the More 
  3275. selection. This selection allows you to display a window that contains all of 
  3276. the features for this part, as well as the features it inherits. Visual Builder 
  3277. provides this window in case you need a feature that is not in the preferred 
  3278. features list. 
  3279.  
  3280. The names of the part's features are displayed in the list boxes named Actions, 
  3281. Attributes, and Events on the left side of the page. The preferred features are 
  3282. displayed in the Preferred Features list box on the right side of the page. 
  3283.  
  3284.  
  3285. ΓòÉΓòÉΓòÉ 6.4.6.1. Adding a Preferred Feature ΓòÉΓòÉΓòÉ
  3286.  
  3287. To add a preferred feature to the connection menu for a part, do the following: 
  3288.  
  3289.    1. Select a feature name from one of the list boxes on the left side of the 
  3290.       page. 
  3291.  
  3292.    2. Do either of the following: 
  3293.  
  3294.           Select the Add push button at the bottom of the page. 
  3295.  
  3296.           With the mouse pointer still over the list box in which you selected 
  3297.            the feature name, do the following: 
  3298.  
  3299.              a. Click mouse button 2. 
  3300.  
  3301.                 A pop-up menu with the Add choice appears. 
  3302.  
  3303.              b. Select Add to add the feature. 
  3304.  
  3305.       The feature name that you selected is inserted into the Preferred 
  3306.       Features list box in alphabetical order. 
  3307.  
  3308.  
  3309. ΓòÉΓòÉΓòÉ 6.4.6.2. Removing a Preferred Feature ΓòÉΓòÉΓòÉ
  3310.  
  3311. You can remove a preferred feature name from the connection menu for a part. 
  3312. Doing this removes the feature from the menu only; it does not delete the 
  3313. feature. 
  3314.  
  3315. To remove a preferred feature from the connection menu for a part, do the 
  3316. following: 
  3317.  
  3318.    1. Select the name that you want to remove from the Preferred Features list 
  3319.       box. 
  3320.  
  3321.    2. Do either of the following: 
  3322.  
  3323.           Select the Remove push button at the bottom of the page. 
  3324.  
  3325.           With the mouse pointer still over the feature name in the Preferred 
  3326.            Features list box, do the following: 
  3327.  
  3328.              a. Click mouse button 2. 
  3329.  
  3330.                 A pop-up menu appears. 
  3331.  
  3332.              b. Select Remove to remove the selected feature. 
  3333.  
  3334.       A message box is displayed to make sure you want to remove the name of 
  3335.       this preferred feature. 
  3336.  
  3337.    3. Select Yes to remove the feature name from the list. 
  3338.  
  3339.       The feature name that you selected is removed from the list. 
  3340.  
  3341.  
  3342. ΓòÉΓòÉΓòÉ 6.4.6.3. Removing All Preferred Features ΓòÉΓòÉΓòÉ
  3343.  
  3344. You can remove all of the feature names from the connection menu for a part. 
  3345. Doing this removes the features from the menu only; it does not delete the 
  3346. features. Once you remove all preferred features from the connection menu, you 
  3347. must select More to use the features in a connection. 
  3348.  
  3349. To remove all of the preferred features from the connection menu for a part, do 
  3350. either of the following: 
  3351.  
  3352.      Select the Remove all push button at the bottom of the page. 
  3353.  
  3354.      With the mouse pointer over the Preferred Features list box, do the 
  3355.       following: 
  3356.  
  3357.         1. Click mouse button 2. 
  3358.  
  3359.            A pop-up menu appears. 
  3360.  
  3361.         2. Select Remove all to remove all of the selected features. 
  3362.  
  3363.  A message box is displayed to make sure you want to remove all of the 
  3364.  preferred features. 
  3365.  
  3366.  Select Yes to remove all of the feature names from the list. All of the 
  3367.  feature names are removed from the list. 
  3368.  
  3369.  
  3370. ΓòÉΓòÉΓòÉ 6.4.6.4. Showing Inherited Preferred Features Only ΓòÉΓòÉΓòÉ
  3371.  
  3372. To show only the preferred features that your part inherits from other parts, 
  3373. select the Default push button. 
  3374.  
  3375. A message box is displayed. Select Yes to display only the inherited preferred 
  3376. features. 
  3377.  
  3378.  
  3379. ΓòÉΓòÉΓòÉ 7. Developing Applications ΓòÉΓòÉΓòÉ
  3380.  
  3381.      Designing effective applications 
  3382.  
  3383.      Designing parts for a single purpose 
  3384.  
  3385.      Taking the object-oriented approach 
  3386.  
  3387.      Identifying reusable parts 
  3388.  
  3389.      Using inheritance 
  3390.  
  3391.      Using abstract classes 
  3392.  
  3393.      Keeping your components small 
  3394.  
  3395.      Designing parts for the OASearch application 
  3396.  
  3397.      Using a simulated database 
  3398.  
  3399.      Designing nonvisual parts 
  3400.  
  3401.      Designing visual parts 
  3402.  
  3403.      How the sample application was built 
  3404.  
  3405.  Personal notes: 
  3406.  
  3407.  
  3408. ΓòÉΓòÉΓòÉ 7.1. Designing Effective Applications ΓòÉΓòÉΓòÉ
  3409.  
  3410. When designing your applications, remember that Visual Builder implements parts 
  3411. as C++ classes. Therefore, keep in mind good design practices and techniques 
  3412. that apply to both classes and parts. 
  3413.  
  3414. At the heart of Visual Builder lies visual programming and construction from 
  3415. parts. The predefined palette of reusable parts coupled with the Composition 
  3416. Editor provide a new level of power in developing applications. Of course, 
  3417. increased power does not guarantee good design and improved productivity, so 
  3418. the following sections are provided to assist you in designing more effective 
  3419. Visual Builder applications. 
  3420.  
  3421.  
  3422. ΓòÉΓòÉΓòÉ 7.2. Designing Parts for a Single Purpose ΓòÉΓòÉΓòÉ
  3423.  
  3424. Much like designing the user interface of any application, you need to design 
  3425. each part in your Visual Builder application for a single purpose. For example, 
  3426. consider an application that queries a simulated database for information about 
  3427. contractors, their skills, and the contracts to which they are assigned. These 
  3428. queries clearly identify the three actions that can be performed using the 
  3429. application. Therefore, this application needs a separate part that shows the 
  3430. results of each query. 
  3431.  
  3432. These parts could include a notebook that displays information about individual 
  3433. contractors, a window with entry fields that contain information about a 
  3434. specific contract, and a container that shows which contractors have a certain 
  3435. skill. Each of these specific queries becomes the single purpose around which 
  3436. you design your parts. Of course, supporting parts such as a main window for 
  3437. starting the queries, nonvisual parts that supply the results of a search, and 
  3438. dialogs for specifying the search targets are also required. 
  3439.  
  3440. You can then combine your parts into a single business-wide application that 
  3441. can be shared by multiple users. Each user has direct access to the parts 
  3442. needed to complete a specific query without interference from any parts of the 
  3443. application that are conducting other queries. 
  3444.  
  3445. In Designing Parts for the OASearch Application, we introduce a sample 
  3446. application that can perform the queries described in this section and explain 
  3447. the design of each of the application's parts. 
  3448.  
  3449.  
  3450. ΓòÉΓòÉΓòÉ 7.3. Taking the Object-Oriented Approach ΓòÉΓòÉΓòÉ
  3451.  
  3452. Object-oriented design seeks to find parallels between computer entities and 
  3453. real-world entities. By not blurring the lines between the roles and tasks of 
  3454. the business, and by providing a part for each, you effectively provide a 
  3455. computer application that parallels the way your business operates in the real 
  3456. world. 
  3457.  
  3458. Thinking more closely in terms of Visual Builder and the Composition Editor, 
  3459. parts that are too large can have a negative effect on usability, performance, 
  3460. and maintenance. As a general rule, for each part, you want to use the minimum 
  3461. number of visual parts, nonvisual parts, connections, and parameters necessary 
  3462. to achieve a single purpose. 
  3463.  
  3464. In addition, try to use attributes whenever possible instead of actions. 
  3465. Attribute-to-attribute connections, for example, tend to minimize the number of 
  3466. required connections because usually you do not need any additional connections 
  3467. to provide a parameter as you do with actions. 
  3468.  
  3469. Here is a sample list of steps you might follow to create an OO application 
  3470. using Visual Builder: 
  3471.  
  3472.    1. Design the application. 
  3473.  
  3474.           Decide which tasks and functions you want the application to 
  3475.            perform. 
  3476.  
  3477.           Determine how you will represent those tasks and functions on the 
  3478.            interface. 
  3479.  
  3480.           Design the user interface, deciding which windows the application 
  3481.            displays. 
  3482.  
  3483.           If more than one window is involved, decide which one is to be the 
  3484.            main window. The main window normally consists of the following: 
  3485.  
  3486.              -  The window that users first see when they start the application 
  3487.  
  3488.              -  Any other visual parts that are included in the window, such as 
  3489.                 list boxes, entry fields, and push buttons 
  3490.  
  3491.              -  Any nonvisual parts that are needed, such as object factories 
  3492.  
  3493.           Decide which parts the application needs in order to provide those 
  3494.            windows and to support the task a user wants to accomplish. 
  3495.  
  3496.           Decide which member functions the parts need by determining what 
  3497.            messages need to be sent from one object to another. 
  3498.  
  3499.           Decide which data members the parts need by determining the various 
  3500.            types of data the part is to provide. 
  3501.  
  3502.           Decide which features (attributes, events, and actions) the parts 
  3503.            need. 
  3504.  
  3505.           Decide which features of each part need to be connected to features 
  3506.            of another part. For example, a Close push button can close a window 
  3507.            only if its buttonClickEvent feature is connected to the window's 
  3508.            close action. 
  3509.  
  3510.    2. Create any parts you need that Visual Builder does not already provide, 
  3511.       or that someone else has not already created. 
  3512.  
  3513.    3. Create the main window and any other required windows using the parts and 
  3514.       connections predetermined in the previous steps. 
  3515.  
  3516.    4. Generate the C++ code for the application. 
  3517.  
  3518.    5. Make any necessary modifications to the generated C++ feature code. 
  3519.  
  3520.    6. Build and run the application. 
  3521.  
  3522.  Developing an OO application is a process in which these (and perhaps other) 
  3523.  steps are usually repeated many times. For that reason, the preceding steps 
  3524.  are provided merely as an example. You might not follow them exactly in the 
  3525.  order given when creating your applications. For example, you might not 
  3526.  realize that you need to create a certain part until you have already started 
  3527.  creating a composite part. 
  3528.  
  3529.  The next section, Identifying Reusable Parts, suggests ways to get the most 
  3530.  from parts, once you have settled upon their high-level design. 
  3531.  
  3532.  
  3533. ΓòÉΓòÉΓòÉ 7.4. Identifying Reusable Parts ΓòÉΓòÉΓòÉ
  3534.  
  3535. Once you have the high-level design of your application's parts, identify 
  3536. common elements. These common elements are perfect opportunities for reuse. 
  3537. Make them into reusable parts and add them to the parts palette. 
  3538.  
  3539. For example, go back to the application that queries for contractor, skill, and 
  3540. contract information. Consider the visual part that displays information about 
  3541. an individual contractor. Along with the information supplied for each 
  3542. contractor is the contractor's name and address. You can make this common 
  3543. address element into a reusable, composite visual part that looks like this: 
  3544.  
  3545. You can then reuse the same address part in visual parts for other applications 
  3546. you create. By reusing parts, you increase productivity. For example, you only 
  3547. have to lay out the form once. In addition, because the State and Postal code 
  3548. field formats differ from the default formats used by the other fields, you 
  3549. only have to set the formats for these fields once, as well. 
  3550.  
  3551. You also get the potentially more important benefit of improved maintenance. 
  3552. For example, if an error is discovered, you only have to fix it in one place. 
  3553. Or later, if your business decides to start using an Auxiliary address field, 
  3554. you would only have to make the change once to your visual address part. 
  3555.  
  3556. Likewise, if the business grows into worldwide sales, then you could change 
  3557. State to State/Region, and add a Country field (provided you are using a 
  3558. database that can accommodate such changes). Having to make these changes only 
  3559. once saves time. 
  3560.  
  3561. The next section, Using Inheritance, suggests more ways to reuse parts. 
  3562.  
  3563.  
  3564. ΓòÉΓòÉΓòÉ 7.5. Using Inheritance ΓòÉΓòÉΓòÉ
  3565.  
  3566. As you are scanning your application looking for common elements, do not 
  3567. overlook the possibility of reusing an entire part. You can reuse both 
  3568. nonvisual and class interface parts. 
  3569.  
  3570. Many times, you need parts that are similar to ones you have already built. 
  3571. Inheritance gives you an easy way to make new parts from the ones you already 
  3572. have. Reusing existing parts through inheritance saves most of the work that 
  3573. would usually be required to create a new part. 
  3574.  
  3575. Example 
  3576.  
  3577. Suppose you created a new nonvisual part named Person. You could use 
  3578. inheritance to build a derived Contractor part that inherits the Person part's 
  3579. features and has other features of its own. The following example assumes you 
  3580. have already created a nonvisual Person part. 
  3581.  
  3582.    1. Begin in the Visual Builder window by selecting PartNew. 
  3583.  
  3584.       The following window is displayed: 
  3585.  
  3586.    2. Type Contractor in the Class name field. 
  3587.  
  3588.    3. Change the part type to Nonvisual part in the Part type field. 
  3589.  
  3590.    4. Enter Person in the Base class field. 
  3591.  
  3592.       Your new Contractor part now inherits from your Person part. Your window 
  3593.       looks like the following: 
  3594.  
  3595.    5. Select Open to create the part and open the Part Interface Editor. 
  3596.  
  3597.       When the Part Interface Editor opens, it displays the Attribute page. 
  3598.  
  3599.    6. Add new attributes that a contractor might have, such as startDate, 
  3600.       endDate, and activeStatus. 
  3601.  
  3602.  The next section, Using Abstract Classes, suggests ways to factor out common 
  3603.  classes and member functions so you can better reuse the code that you write. 
  3604.  
  3605.  
  3606. ΓòÉΓòÉΓòÉ 7.6. Using Abstract Classes ΓòÉΓòÉΓòÉ
  3607.  
  3608. The technique of scanning your application for common elements applies as much 
  3609. to code as it does to visual parts. 
  3610.  
  3611. As you are writing member functions that enhance your visual parts, look for 
  3612. common member functions. These common member functions indicate perfect 
  3613. opportunities for reuse and can possibly be placed in an abstract class. 
  3614.  
  3615. Abstract classes are used for factoring out common behavior. They are not 
  3616. intended to define any particular real part. Therefore, never represent an 
  3617. abstract class as a part on the free-form surface of the Composition Editor. 
  3618. Instead, use the abstract class as the base class, or as an ancestor of the 
  3619. base class, of nonvisual or class interface parts that you create and place on 
  3620. the free-form surface. 
  3621.  
  3622. Abstract classes are repositories for common member functions. The similarities 
  3623. between your various parts determine which member functions are candidates to 
  3624. be grouped together under a common abstract class. 
  3625.  
  3626.            If you move a member function from a part to an abstract class, 
  3627.            remove that member function from the interface of the part from 
  3628.            which it was removed. You are not required to do this, but 
  3629.            maintaining your application is easier if each part properly 
  3630.            reflects only the member functions it contains in its part 
  3631.            interface. 
  3632.  
  3633.  All of the benefits of reuse are achieved, namely increased productivity and 
  3634.  reduced maintenance, from only having to write and maintain the member 
  3635.  functions in one place. 
  3636.  
  3637.  The next section, Keeping Your Components Small, emphasizes a common theme in 
  3638.  designing effective Visual Builder applications. 
  3639.  
  3640.  
  3641. ΓòÉΓòÉΓòÉ 7.7. Keeping Your Components Small ΓòÉΓòÉΓòÉ
  3642.  
  3643. As the topics in this chapter have probably made clear by now, a primary goal 
  3644. of any object-oriented environment, including Visual Builder, is reuse, for 
  3645. which keeping your components small is fundamental. The smaller you make the 
  3646. components of your applications, the more opportunity you have to take 
  3647. advantage of reuse. 
  3648.  
  3649. The following table provides the numbers, based on C++ research, that you 
  3650. should aim for in creating your classes, member functions, and data members. 
  3651.  
  3652. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  3653. ΓöéCriteria                    ΓöéOptimum number              ΓöéReason                      Γöé
  3654. ΓöéAverage lines per member    ΓöéFewer than 24               ΓöéA higher average generally  Γöé
  3655. Γöéfunction                    Γöé                            Γöéindicates poor              Γöé
  3656. Γöé                            Γöé                            Γöéobject-oriented design and aΓöé
  3657. Γöé                            Γöé                            Γöétendency toward             Γöé
  3658. Γöé                            Γöé                            Γöéfunction-oriented           Γöé
  3659. Γöé                            Γöé                            Γöéprogramming.                Γöé
  3660. ΓöéAverage member functions perΓöéNo more than 20             ΓöéHigher averages indicate youΓöé
  3661. Γöéclass                       Γöé                            Γöécan distribute your member  Γöé
  3662. Γöé                            Γöé                            Γöéfunctions among more        Γöé
  3663. Γöé                            Γöé                            Γöéclasses.                    Γöé
  3664. ΓöéAverage data members per    ΓöéNo more than six            ΓöéHigher averages indicate youΓöé
  3665. Γöéclass                       Γöé                            Γöécan distribute your data    Γöé
  3666. Γöé                            Γöé                            Γöémembers among more classes. Γöé
  3667. ΓöéAverage number of base      ΓöéNo more than six            ΓöéInheriting from too many    Γöé
  3668. Γöéclasses per class           Γöé                            Γöéclasses indicates too few   Γöé
  3669. Γöé                            Γöé                            Γöémember functions in each    Γöé
  3670. Γöé                            Γöé                            Γöéclass. This can cause       Γöé
  3671. Γöé                            Γöé                            Γöéperformance and size        Γöé
  3672. Γöé                            Γöé                            Γöéproblems because the more   Γöé
  3673. Γöé                            Γöé                            Γöébase classes from which yourΓöé
  3674. Γöé                            Γöé                            Γöéclasses inherit, the slower Γöé
  3675. Γöé                            Γöé                            Γöéyour compiled code runs and Γöé
  3676. Γöé                            Γöé                            Γöéthe larger it becomes.      Γöé
  3677. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  3678.  
  3679. These numbers generally depend on the complexity of the class. Less complex 
  3680. classes that take full advantage of prewritten reusable parts typically have 
  3681. fewer member functions per class. Also, the number of data members depends on 
  3682. how data-intensive the classes are. However, many of the member functions and 
  3683. data members you need can be inherited by default from classes provided by 
  3684. Visual Builder. 
  3685.  
  3686. Applying the design strategies covered in these sections and gaining experience 
  3687. should help you achieve these averages. 
  3688.  
  3689.  
  3690. ΓòÉΓòÉΓòÉ 7.8. Designing Parts for the OASearch Application ΓòÉΓòÉΓòÉ
  3691.  
  3692. A sample application is used in this part of the book to show you how to build 
  3693. a simple GUI application. You can find the nonvisual parts in oanonvis.vbb. All 
  3694. visual parts are in oawin.vbb. For in-depth information about designing your 
  3695. own parts, refer to Building VisualAge C++ Parts for Fun and Profit. 
  3696.  
  3697. This application, called OASearch, serves recruiters for a fictitious technical 
  3698. contracting services firm, called Opportunities Abound (OA). Customers call OA 
  3699. to request temporary help; recruiters use the application to match skill 
  3700. requirements with available contractors. When matches are made, the recruiters 
  3701. enter contract information into the application. 
  3702.  
  3703.  
  3704. ΓòÉΓòÉΓòÉ 7.8.1. Using a Simulated Database ΓòÉΓòÉΓòÉ
  3705.  
  3706. This sample application does not require the installation of a database 
  3707. program. Instead, the application uses the IProfile class to create and 
  3708. maintain a simple database in three .ini files. To see the implementation, 
  3709. browse the following code files: 
  3710.  
  3711.       contrctr.cpv 
  3712.       contract.cpv 
  3713.       skillb.cpv 
  3714.  
  3715.  For more information about the IProfile class, refer to the IBM Open Class 
  3716.  Library Reference. 
  3717.  
  3718.  
  3719. ΓòÉΓòÉΓòÉ 7.8.2. Designing Nonvisual Parts ΓòÉΓòÉΓòÉ
  3720.  
  3721. When designing your own application, take extra time to think through the 
  3722. nonvisual parts. One way to minimize rework during design is to use index 
  3723. cards, putting the data and tasks of each part or class on a separate card. 
  3724. This method enables you to throw away one design in favor of another, 
  3725. rearranging the cards until you are confident of your design. 
  3726.  
  3727. The OASearch application uses the following nonvisual parts to hold or manage 
  3728. data: 
  3729.  
  3730.      OAContractor, which represents OA employees 
  3731.      OAContract, which represents OA contracts 
  3732.      OASkill, which represents marketable skills held by OA's employees 
  3733.      OASkillBase, which controls traffic between the OASkillView window and 
  3734.       the skill database. This is necessary because of the one-to-many 
  3735.       relationship that exists between OAContractor and OASkill instances. That 
  3736.       is, many contractors could hold the same skill and a single contractor 
  3737.       could hold many skills. 
  3738.      SkillList, a part instance of type IVSequence. For more information about 
  3739.       sequences, refer to the Visual Builder Parts Reference. 
  3740.  
  3741.  
  3742. ΓòÉΓòÉΓòÉ 7.8.2.1. The OAContractor Part ΓòÉΓòÉΓòÉ
  3743.  
  3744. When you design a Visual Builder part, you are designing a C++ class. The part 
  3745. interface corresponds to the part interface of the underlying class. The class 
  3746. can also have member functions (public, protected, or private) that do not 
  3747. exist in the part interface. 
  3748.  
  3749. OAContractor Attributes 
  3750.  
  3751. The OAContractor part has the following attributes: 
  3752.  
  3753.      lastName, the contractor's last name 
  3754.      firstName, the contractor's first name 
  3755.      middleInitial, the contractor's middle initial 
  3756.      homeStreet, the contractor's home street address 
  3757.      homeCity, the contractor's home city 
  3758.      homeState, the contractor's home state or province 
  3759.      homeZip, the contractor's home postal code 
  3760.      phoneNumber, the contractor's daytime phone number 
  3761.      startDate, the date on which the contractor started working at 
  3762.       Opportunities Abound 
  3763.      endDate, the date on which the contractor stopped working at 
  3764.       Opportunities Abound 
  3765.      activeStatus, whether the contractor is interested in a new position 
  3766.      currentContract, the contractor's current assignment (if any) 
  3767.      contractorID, the contractor's database identifier 
  3768.  
  3769.  All attributes are of type IString, except for the activeStatus attribute, 
  3770.  which is of type Boolean. The contractorID attribute is derived from the 
  3771.  contractor's name attributes. 
  3772.  
  3773.  To enable you to use these attributes, the contractor part must also contain 
  3774.  public get and set member functions. By convention, the names of these member 
  3775.  functions follow a pattern determined by the name of the attribute. For the 
  3776.  IString attribute lastName, the get member function is called lastName, and 
  3777.  the set member function is called setLastName. For the Boolean attribute 
  3778.  activeStatus, the get member function is called isActiveStatus, and the set 
  3779.  member function is called enableActiveStatus. 
  3780.  
  3781.  To retrieve or update contractor information from the database, the 
  3782.  OAContractor part contains the following actions: 
  3783.  
  3784.      getContractor 
  3785.  
  3786.             OAContractor & getContractor();
  3787.  
  3788.      parseName 
  3789.  
  3790.             OAContractor & parseName(const IString & aName);
  3791.  
  3792.      putContractor 
  3793.  
  3794.             OAContractor & putContractor();
  3795.  
  3796.  The parseName action parses an input string to set the firstName, 
  3797.  middleInitial, and lastName attributes. The getContractor and putContractor 
  3798.  actions use the derived attribute contractorID to retrieve and store 
  3799.  contractor information in the database. The feature code for this part appears 
  3800.  in contrctr.cpv. 
  3801.  
  3802.  For a look at the visual part that OAContractor supports, see The 
  3803.  Opportunities Abound Contractor Information Window. 
  3804.  
  3805.  
  3806. ΓòÉΓòÉΓòÉ 7.8.2.2. The OAContract Part ΓòÉΓòÉΓòÉ
  3807.  
  3808. The OAContract part contains the following attributes: 
  3809.  
  3810.      accountNum, the contract's account number 
  3811.      companyName, the name of the client company 
  3812.      projectMgr, the client company's representative 
  3813.      deptName, the department within the client company that needs a position 
  3814.       filled 
  3815.      positionTitle, a description of the position to be filled 
  3816.      startDate, the first day of work at the client company 
  3817.      endDate, the last day of work at the client company 
  3818.      currContractor, the identifier of the contractor filling the position 
  3819.  
  3820.  It also contains the following actions: 
  3821.  
  3822.      getContract 
  3823.  
  3824.             OAContract & getContract(const IString & anAccountNum);
  3825.  
  3826.      putContract 
  3827.  
  3828.             OAContract & putContract(const IString & anAccountNum);
  3829.  
  3830.  All attributes are of type IString. The feature code for this part appears in 
  3831.  contract.cpv. 
  3832.  
  3833.  For a look at the visual part that OAContract supports, see The Opportunities 
  3834.  Abound Contract Information Window. 
  3835.  
  3836.  
  3837. ΓòÉΓòÉΓòÉ 7.8.2.3. The OASkill Part ΓòÉΓòÉΓòÉ
  3838.  
  3839. The OASkill part contains the following attributes: 
  3840.  
  3841.      skillName, a description of the skill required 
  3842.      yearsExp, the number of years of experience needed 
  3843.      contractorID, the identifier of the contractor holding this skill 
  3844.      key, an index used to construct the database key 
  3845.  
  3846.  All attributes are of type IString. The feature code for this part appears in 
  3847.  skill.cpv. 
  3848.  
  3849.  For a look at the visual part that OASkill supports, see The Opportunities 
  3850.  Abound Skill Information Window. 
  3851.  
  3852.  
  3853. ΓòÉΓòÉΓòÉ 7.8.2.4. The OASkillBase Part ΓòÉΓòÉΓòÉ
  3854.  
  3855. The OASkillBase part contains no attributes but has the following actions: 
  3856.  
  3857.      getSkills 
  3858.  
  3859.             OASkill & getSkills(const IString & aSkillName, IVSequence <OASkill*> & aList);
  3860.  
  3861.       This action retrieves skill information from the database, instantiates 
  3862.       OASkill objects from retrieved information, and adds pointers for the new 
  3863.       objects to the specified list of skills. 
  3864.  
  3865.      putSkill 
  3866.  
  3867.             OASkill & putSkill(const OASkill & aSkill);
  3868.  
  3869.       This action stores skill information in the database. 
  3870.  
  3871.  The feature code for this part appears in skillb.cpv. 
  3872.  
  3873.  For a look at the visual part that OASkillBase supports, see The Opportunities 
  3874.  Abound Skill Information Window. 
  3875.  
  3876.  
  3877. ΓòÉΓòÉΓòÉ 7.8.3. Designing Visual Parts ΓòÉΓòÉΓòÉ
  3878.  
  3879. Although the OASearch application was designed to illustrate variety more than 
  3880. efficiency, consider the following design decisions: 
  3881.  
  3882.      The Opportunities Abound Databases window (part OAMain) is the 
  3883.       integration point for the application. All variables found in the other 
  3884.       composite parts are resolved in OAMain. All parts except the OASkill 
  3885.       search results are instantiated here. 
  3886.  
  3887.      The connections between visual parts are minimized with the use of 
  3888.       promoted variables to pass data. Inside each visual part, 
  3889.       attribute-to-attribute connections load data from the variables into the 
  3890.       windows. 
  3891.  
  3892.      All views use multicell canvases to hold the primitive visual parts. They 
  3893.       are as follows: 
  3894.  
  3895.         -  The Opportunities Abound Databases window 
  3896.         -  The Opportunities Abound General Information window 
  3897.         -  The query windows 
  3898.         -  The Opportunities Abound Contractor Information window 
  3899.         -  The Opportunities Abound Contract Information window 
  3900.         -  The Opportunities Abound Skill Information window 
  3901.  
  3902.  
  3903. ΓòÉΓòÉΓòÉ 7.8.3.1. The Opportunities Abound Databases Window ΓòÉΓòÉΓòÉ
  3904.  
  3905. The welcome window for OASearch appears in the following figure: 
  3906.  
  3907. This first window to appear is the primary view; the part containing this 
  3908. window, OAMain, is the main part. To view information, recruiters can use the 
  3909. View submenu or press one of the three graphic push buttons. To enter 
  3910. information about new contracts or contractors, they can use the Edit submenu. 
  3911.  
  3912. This window shows use of the following: 
  3913.  
  3914.      Menu bar 
  3915.      Embedded multicell canvas 
  3916.      Icons as resources 
  3917.      Object Factory parts 
  3918.      Variables used with Object Factory parts 
  3919.  
  3920.  
  3921. ΓòÉΓòÉΓòÉ 7.8.3.2. The Opportunities Abound General Information Window ΓòÉΓòÉΓòÉ
  3922.  
  3923. When a user selects General information from the View submenu, the 
  3924. Opportunities Abound General Information window appears, as shown in the 
  3925. following figure: 
  3926.  
  3927. This window shows use of the following: 
  3928.  
  3929.      IViewPort* with multicell canvas 
  3930.      Handler class (IVBMinSizeViewPortHandler) for IViewPort* 
  3931.  
  3932.  This window uses an IViewPort* part as the client. An IMultiCellCanvas* part 
  3933.  within the IViewPort* holds the IStaticText* parts. In the compiled 
  3934.  application, the handler resizes the IMultiCellCanvas* whenever the window is 
  3935.  resized. 
  3936.  
  3937.  To see what happens when the handler is not running, open the OAGenInfo part 
  3938.  in the Composition Editor. If you resize the IFrameWindow* part, the 
  3939.  IViewPort* part is resized automatically, but the IMultiCellCanvas* part is 
  3940.  not. You must resize the IMultiCellCanvas* part manually to fit inside the 
  3941.  border of the resized IFrameWindow*. 
  3942.  
  3943.  
  3944. ΓòÉΓòÉΓòÉ 7.8.3.3. The Query Windows ΓòÉΓòÉΓòÉ
  3945.  
  3946. When recruiters select a graphic push button or View menu item from the 
  3947. Opportunities Abound Databases, a query window appears, as shown in the 
  3948. following figure: 
  3949.  
  3950. The OAQuerySkill part contains this window. Two other parts, OAQueryContract 
  3951. and OAQueryContractor, hold other query windows. 
  3952.  
  3953. When a user enters a value in the query window and selects the OK push button, 
  3954. the query window closes and the corresponding information window appears. If 
  3955. the requested value is not found, a message box appears. Users can also get 
  3956. help or return to the Opportunities Abound Databases window. 
  3957.  
  3958. This window shows use of the following: 
  3959.  
  3960.      Modal window display 
  3961.      Help enablement 
  3962.      Promoted variables features 
  3963.  
  3964.  
  3965. ΓòÉΓòÉΓòÉ 7.8.3.4. The Opportunities Abound Contractor Information Window ΓòÉΓòÉΓòÉ
  3966.  
  3967. When the requested contractor is found in the contractor database, the 
  3968. Opportunities Abound Contractor Information window appears, as shown in the 
  3969. following figure: 
  3970.  
  3971. The application retrieves the records matching the requested contractor 
  3972. identifier, sets an OAContractor* part, and displays the values in this window. 
  3973. The Contact page contains information about how to get in touch with the 
  3974. contractor. The History page contains information about the contractor's work 
  3975. history. The Skills page is provided for users of the sample application to 
  3976. update skills a hypothetical contractor has. 
  3977.  
  3978. This window shows use of the following: 
  3979.  
  3980.      INotebook* part 
  3981.      Different multicell canvas layouts 
  3982.      Event-to-member function connection 
  3983.      Event-to-custom logic connection 
  3984.      Variables used as placeholders 
  3985.      Promoted features 
  3986.  
  3987.  
  3988. ΓòÉΓòÉΓòÉ 7.8.3.5. The Opportunities Abound Contract Information Window ΓòÉΓòÉΓòÉ
  3989.  
  3990. When the requested contract is found in the contract database, the 
  3991. Opportunities Abound Contract Information window appears, as shown in the 
  3992. following figure: 
  3993.  
  3994. The application retrieves the records matching the requested contract account 
  3995. number, sets an OAContract* object, and displays the values in the window. This 
  3996. window shows basic multicell canvas layout. 
  3997.  
  3998. A variant of the OAContractView part, ContractView, appears in contract.vbb. 
  3999. This version of the Opportunities Abound Contract Information window uses an 
  4000. ICanvas* part instead of a multicell canvas. It is formatted for an XGA/8514 
  4001. display. 
  4002.  
  4003.  
  4004. ΓòÉΓòÉΓòÉ 7.8.3.6. The Opportunities Abound Skill Information Window ΓòÉΓòÉΓòÉ
  4005.  
  4006. When the requested skill is found in the skill database, the Opportunities 
  4007. Abound Skill Information window appears, as shown in the following figure: 
  4008.  
  4009. The application retrieves all records matching the requested search 
  4010. description, creating instantiating an OASkill object for each pair of records 
  4011. (contractor and years of experience) found. Each new OASkill object is put into 
  4012. a list and, from there, into the container shown in the window. Recruiters can 
  4013. search on other skills without leaving this window by typing the new skill 
  4014. description into the entry field and selecting the Refresh push button. 
  4015.  
  4016. This window shows use of the following: 
  4017.  
  4018.      IVBContainerControl* 
  4019.      IContainerColumn* 
  4020.      IVSequence* 
  4021.  
  4022.  
  4023. ΓòÉΓòÉΓòÉ 7.8.4. How the Sample Application Was Built ΓòÉΓòÉΓòÉ
  4024.  
  4025. The OASearch application was developed in the following order: 
  4026.  
  4027.    1. The major nonvisual parts were designed. 
  4028.    2. The major visual parts were designed. 
  4029.    3. The nonvisual parts were built. 
  4030.    4. The view parts were built. 
  4031.    5. The query parts were built. 
  4032.    6. The OAMain and OAGenInfo parts were built. 
  4033.    7. Code for all parts was generated at the same time from the Visual Builder 
  4034.       window. 
  4035.  
  4036.  
  4037. ΓòÉΓòÉΓòÉ 8. Creating Nonvisual Parts ΓòÉΓòÉΓòÉ
  4038.  
  4039.      What you will achieve 
  4040.  
  4041.      Defining the part interface 
  4042.  
  4043.      Adding code to your part 
  4044.  
  4045.  Personal notes: 
  4046.  
  4047.  
  4048. ΓòÉΓòÉΓòÉ 8.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  4049.  
  4050. This chapter describes how to define your own parts. For this example, we will 
  4051. create a nonvisual part, OAContractor, because it illustrates the process 
  4052. better than a visual part. 
  4053.  
  4054. For information about using the Composition Editor to create visual parts, see 
  4055. Learning Visual Construction Fundamentals. For more information about using the 
  4056. Part Interface Editor to define part interfaces, see Touring the Part Interface 
  4057. Editor. 
  4058.  
  4059. You create a part by doing the following: 
  4060.  
  4061.    1. Design the part. 
  4062.  
  4063.    2. Define the part interface, either through the Part Interface Editor or by 
  4064.       importing a part information file. 
  4065.  
  4066.    3. Add code to your part. You can use C++ code written outside of Visual 
  4067.       Builder, or you can generate default feature code in Visual Builder and 
  4068.       modify it. 
  4069.  
  4070.  If you have previously existing C++ code that you would like to use in your 
  4071.  part, the following process is probably more efficient: 
  4072.  
  4073.    1. Design the part. 
  4074.    2. Define the part interface using part information files. 
  4075.  
  4076.  
  4077. ΓòÉΓòÉΓòÉ 8.2. Defining the Part Interface ΓòÉΓòÉΓòÉ
  4078.  
  4079. When you are satisfied with your part's design, you are ready to define the 
  4080. part interface to Visual Builder. 
  4081.  
  4082.    1. Define the attributes of your part. 
  4083.  
  4084.       A part's attributes typically correlate to the class' data members and 
  4085.       can additionally include derived attributes, or attributes that are 
  4086.       determined based on the value of other attributes. 
  4087.  
  4088.    2. Define the member functions that get or set the value of those 
  4089.       attributes. 
  4090.  
  4091.    3. Define any actions that you want the part to be able to do. 
  4092.  
  4093.       A part's actions correlate to the class' public member functions. 
  4094.  
  4095.    4. Specify the event notification identifier used to signal a change in the 
  4096.       value of each attribute. 
  4097.  
  4098.  You can define the part interface in either of the following ways: 
  4099.  
  4100.      Use the Part Interface Editor. With this method, you create the part from 
  4101.       the Visual Builder window and then enter each feature of the part 
  4102.       interface individually using the pages of the Part Interface Editor. 
  4103.  
  4104.      Use a part information file. With this method, you encode part 
  4105.       information in a file and then create the part and its interface by 
  4106.       importing the information into Visual Builder. This method might be more 
  4107.       efficient if C++ code already exists for your part. See Using Existing C 
  4108.       and C++ Code with Visual Builder and refer to Building VisualAge C++ 
  4109.       Parts for Fun and Profit for information about creating part information 
  4110.       files. 
  4111.  
  4112.  
  4113. ΓòÉΓòÉΓòÉ 8.2.1. Defining the Part Interface Using the Part Interface Editor ΓòÉΓòÉΓòÉ
  4114.  
  4115. Open a new nonvisual part called OAContractor. The Part Interface Editor 
  4116. appears. 
  4117.  
  4118. On the Attribute page, do the following: 
  4119.  
  4120.    1. Type lastName in the Attribute name text-entry field and select the Add 
  4121.       with defaults push button. 
  4122.  
  4123.       Your Part Interface Editor looks like the following figure: 
  4124.  
  4125.       Notice that several default values are displayed: 
  4126.  
  4127.           The default Attribute type is IStandardNotifier*. This means that 
  4128.            the lastName attribute is an instance of the IStandardNotifier* 
  4129.            class. 
  4130.  
  4131.           The default Get member function, lastName, matches the lastName 
  4132.            member function of your design. When your contractor part is queried 
  4133.            for the value of its lastName attribute, it executes the lastName 
  4134.            member function to retrieve the contractor's last name. 
  4135.  
  4136.           The default Set member function is setLastName. When your contractor 
  4137.            part is passed the name that has been assigned to the contractor, it 
  4138.            uses the setLastName member function to store the value in its 
  4139.            lastName attribute. 
  4140.  
  4141.           The default Event notification is lastNameId. When a value is stored 
  4142.            in the lastName attribute using the setLastName member function, the 
  4143.            contractor part signals this event to let other parts know that the 
  4144.            value has changed. For example, if there is an 
  4145.            attribute-to-attribute connection between lastName and a label's 
  4146.            string value, the label part is informed so that it displays the 
  4147.            latest value. 
  4148.  
  4149.           If needed, you can explain more about the attribute in the 
  4150.            Description field. 
  4151.  
  4152.    2. Change any of the default values, if needed. For this example, change the 
  4153.       default attribute type to IString. You can do this by typing the value 
  4154.       directly into the entry field or by selecting the drop-down list box 
  4155.       arrow to the right of the entry field and selecting IString from the 
  4156.       list. 
  4157.  
  4158.       Also, edit the Get member function and Set member function fields, 
  4159.       changing IStandardNotifier to IString. This causes these member functions 
  4160.       to accept IString as a parameter instead of IStandardNotifier. 
  4161.  
  4162.    3. Select the Update push button to save the changes you just made. 
  4163.  
  4164.    4. Select the Clear push button to clear the fields before adding the next 
  4165.       attribute. 
  4166.  
  4167.    5. Repeat the previous steps for the contractor's firstName, middleInitial, 
  4168.       homeStreet, homeCity, homeState, homeZip, startDate, endDate, 
  4169.       currentContract, and phoneNumber attributes. For these attributes, 
  4170.       specify the IString attribute type before selecting the Add with defaults 
  4171.       push button in the first step. This prevents you from having to change 
  4172.       IStandardNotifier* to IString as you did previously. 
  4173.  
  4174.    6. Define the contractorID attribute as IString, with the following get 
  4175.       member function: 
  4176.  
  4177.             OAContractor & getContractorID ();
  4178.  
  4179.       This attribute is derived from other attributes; we will add the code for 
  4180.       this later. You do not want users to set this attribute directly, so do 
  4181.       not include a setContractorID member function. 
  4182.  
  4183.    7. Define the activeStatus attribute as Boolean. Note that the default get 
  4184.       member function and set member function follow a different format than 
  4185.       the ones for IString attributes. 
  4186.  
  4187.    8. To define the actions for OAContractor, select the Action page. 
  4188.  
  4189.    9. Type putContractor in the Action name field and the following into the 
  4190.       Action member function field: 
  4191.  
  4192.             OAContractor & putContractor();
  4193.  
  4194.   10. Select the Add push button; then select Clear. 
  4195.  
  4196.   11. Repeat for the getContractor and parseName actions. At this point, the 
  4197.       Action page appears as shown in the following figure: 
  4198.  
  4199.   12. Select Save from the File pull-down menu to save your work. 
  4200.  
  4201.  The next step is adding code to your part. 
  4202.  
  4203.  
  4204. ΓòÉΓòÉΓòÉ 8.3. Adding Code to Your Part ΓòÉΓòÉΓòÉ
  4205.  
  4206. Once you have specified the part interface for your part, you are ready to add 
  4207. the code to make the part work. Adding code involves the following tasks: 
  4208.  
  4209.    1. Generating default feature code. If you already have C++ code for your 
  4210.       part and have imported the part information, this step is not necessary. 
  4211.    2. Modifying the feature code. 
  4212.    3. Adding code created outside Visual Builder if it already exists. 
  4213.  
  4214.  
  4215. ΓòÉΓòÉΓòÉ 8.3.1. Generating Default Feature Code ΓòÉΓòÉΓòÉ
  4216.  
  4217. If code does not already exist for your part, you can use Visual Builder to 
  4218. generate default feature code. Default feature code consists of code that is 
  4219. based on the part interface you defined earlier. For most attributes, the 
  4220. default feature code is sufficient to define get member functions, set member 
  4221. functions, and event notifications. For actions, you have to modify the default 
  4222. feature code to add the function or logic you want your part to perform. 
  4223.  
  4224. If you also use Visual Builder to generate the default source code for your 
  4225. parts, you will find it helpful to generate default feature code separately. 
  4226. Each time you generate default source code, Visual Builder replaces the 
  4227. existing files with new ones because there is no need for you to modify these 
  4228. files. 
  4229.  
  4230. The files that you usually need to modify are the default feature code files. 
  4231. These are the files in which you write the code to tell your application how to 
  4232. perform the actions that you create in the Part Interface Editor. Each time you 
  4233. generate default feature code, Visual Builder appends the newly generated code 
  4234. to the end of each existing feature code file. This is done so that you will 
  4235. not lose any code that you have written. 
  4236.  
  4237. In addition, you do not have to generate new code for all of your features each 
  4238. time you need default code for a feature. You can create a new feature in the 
  4239. Part Interface Editor and then generate default feature code just for the new 
  4240. feature. Visual Builder appends the default code for the new feature to end of 
  4241. the existing files so that you can modify it. 
  4242.  
  4243. Note:  If you regenerate default code for a feature, be sure to remove the 
  4244.        previous code for that feature from the file to prevent compilation 
  4245.        errors or unwanted results. 
  4246.  
  4247.  To generate default feature code for the OAContractor part, follow these 
  4248.  steps. 
  4249.  
  4250.  Note:  This example is a continuation of the example in the preceding section 
  4251.         using the OAContractor part, which should be open in the Part Interface 
  4252.         Editor. 
  4253.  
  4254.    1. Switch to the Class Editor by selecting the icon in the lower-right 
  4255.       corner of the window. 
  4256.  
  4257.    2. Specify the .hpv and .cpv files for Visual Builder to use for the default 
  4258.       feature code for the OAContractor part's attributes and actions by 
  4259.       filling in the following fields: 
  4260.  
  4261.       User .hpv file        contrctr.hpv 
  4262.  
  4263.       User .cpv file        contrctr.cpv 
  4264.  
  4265.       The Class Editor with the appropriate fields filled in is shown in the 
  4266.       following figure: 
  4267.  
  4268.    3. Select FileSave and GenerateFeature source. 
  4269.  
  4270.       The Generate feature source code window appears, as shown in the 
  4271.       following figure: 
  4272.  
  4273.    4. Generate the default feature code using one of the following methods: 
  4274.  
  4275.           Select the Generate all push button to generate default feature code 
  4276.            for member functions and data members. 
  4277.  
  4278.           Select the appropriate member functions and data members from the 
  4279.            Member functions, Attribute data members, or Event data members list 
  4280.            boxes. Then, select the Generate selected push button. 
  4281.  
  4282.       The first time you will probably want to generate code for all of your 
  4283.       features. Then, you can generate code for other features as you add them. 
  4284.  
  4285.       For this example, select the Generate all push button. 
  4286.  
  4287.       The default feature code is stored in the files you specified in the 
  4288.       Class Editor, contrctr.hpv and contrctr.cpv. If these files already 
  4289.       exist, the code you just generated is appended to the ends of these 
  4290.       files. 
  4291.  
  4292.       For most parts, you must modify the default code to make your part fully 
  4293.       functional. 
  4294.  
  4295.  The next step is modifying the generated feature code. 
  4296.  
  4297.  
  4298. ΓòÉΓòÉΓòÉ 8.4. Modifying the Generated Feature Code ΓòÉΓòÉΓòÉ
  4299.  
  4300. After you have Visual Builder generate the feature code, review it. Does it do 
  4301. what you need it to do? If not, modify the code. The OAContractor part needs 
  4302. the following changes: 
  4303.  
  4304.      Modified code for the getContractor action 
  4305.      Modified code for the putContractor action 
  4306.      Modified code for the parseName action 
  4307.      Added code to set the activeStatus attribute 
  4308.      Added code to set the contractorID attribute 
  4309.  
  4310.  
  4311. ΓòÉΓòÉΓòÉ 8.4.1. Modifying Code for the getContractor Action ΓòÉΓòÉΓòÉ
  4312.  
  4313. This version of our contractor application uses an IProfile-based database to 
  4314. store information about the contractors. For our OAContractor part to use this 
  4315. database, we must complete the getContractor and putContractor actions and 
  4316. modify the activeStatus attribute. The following example shows the default code 
  4317. generated for the two actions: 
  4318.  
  4319. OAContractor & OAContractor::getContractor()
  4320. {
  4321.   return *this;
  4322. }
  4323.  
  4324. OAContractor & OAContractor::putContractor()
  4325. {
  4326.   return *this;
  4327. }
  4328.  
  4329. To modify default feature code, edit the code files using the syntax text 
  4330. editor provided by VisualAge C++ or your favorite editor. Code for our 
  4331. getContractor action follows: 
  4332.  
  4333. OAContractor & OAContractor::getContractor()
  4334. {
  4335. // Start data access code
  4336.  
  4337.   IProfile *p = new IProfile("contrctr.ini");
  4338.  
  4339. // Test for missing name information
  4340. // Necessary for proper derivation of the contractorID attribute
  4341.  
  4342.   if ((!iLastName) || (!iFirstName) || (!iMiddleInitial))
  4343.   {
  4344.   throw IException("The contractor's name is incomplete. Complete all name fields and try again.");
  4345.   delete p;
  4346.   return *this;
  4347.   }
  4348.  
  4349. // Refresh the value of contractor ID
  4350.  
  4351.    setContractorID();
  4352.  
  4353. // Check for this contractor ID in the profile collection
  4354.  
  4355.   if (!p->containsKeyName("contractorID", iContractorID))
  4356.   {
  4357.   throw IException("A record was not found for this contractor.");
  4358.   delete p;
  4359.   return *this;
  4360.   }
  4361.  
  4362. // If other data exists for this contractor,
  4363. // set the corresponding contractor attributes
  4364.  
  4365.   if (p->containsKeyName("lastName", iContractorID))
  4366.     setLastName(p->elementWithKey("lastName", iContractorID));
  4367.   if (p->containsKeyName("firstName", iContractorID))
  4368.     setFirstName(p->elementWithKey("firstName", iContractorID));
  4369.   if (p->containsKeyName("middleInitial", iContractorID))
  4370.     setMiddleInitial(p->elementWithKey("middleInitial", iContractorID));
  4371.   if (p->containsKeyName("homeStreet", iContractorID))
  4372.     setHomeStreet(p->elementWithKey("homeStreet", iContractorID));
  4373.   if (p->containsKeyName("homeCity", iContractorID))
  4374.     setHomeCity(p->elementWithKey("homeCity", iContractorID));
  4375.   if (p->containsKeyName("homeState", iContractorID))
  4376.     setHomeState(p->elementWithKey("homeState", iContractorID));
  4377.   if (p->containsKeyName("homeZip", iContractorID))
  4378.     setHomeZip(p->elementWithKey("homeZip", iContractorID));
  4379.   if (p->containsKeyName("phoneNumber", iContractorID))
  4380.     setPhoneNumber(p->elementWithKey("phoneNumber", iContractorID));
  4381.   if (p->containsKeyName("startDate", iContractorID))
  4382.     setStartDate(p->elementWithKey("startDate", iContractorID));
  4383.   if (p->containsKeyName("endDate", iContractorID))
  4384.     setEndDate(p->elementWithKey("endDate", iContractorID));
  4385.   if (p->containsKeyName("currentContract", iContractorID))
  4386.     setCurrentContract(p->elementWithKey("currentContract", iContractorID));
  4387.  
  4388. // Call overloaded set member function using string parameter
  4389.  
  4390.   if (p->containsKeyName("activeStatus", iContractorID))
  4391.     enableActiveStatus(p->elementWithKey("activeStatus", iContractorID));
  4392.  
  4393.   delete p;
  4394.  
  4395. // End data access code
  4396.  
  4397.   return *this;
  4398. }
  4399.  
  4400. The getContractor action checks for one possible error condition. If it occurs, 
  4401. the action throws an exception. Otherwise, the action retrieves data by 
  4402. contractor identifier from the contrctr.ini file. 
  4403.  
  4404. In response to these exceptions, the OAContractorView part shows a message box. 
  4405. More about the contractor view part appears in Constructing the User Interface. 
  4406. For information about how to handle exceptions visually, see Passing Exceptions 
  4407. to Message Boxes. 
  4408.  
  4409.  
  4410. ΓòÉΓòÉΓòÉ 8.4.2. Modifying Code for the putContractor Action ΓòÉΓòÉΓòÉ
  4411.  
  4412. Code the putContractor action as follows: 
  4413.  
  4414. OAContractor & OAContractor::putContractor()
  4415. {
  4416. // Start data entry code
  4417.  
  4418.   IProfile *p = new IProfile("contrctr.ini");
  4419.  
  4420. // Test for missing name information
  4421. // Necessary for proper derivation of the contractorID attribute
  4422.  
  4423.   if ((!iLastName) || (!iFirstName) || (!iMiddleInitial))
  4424.   {
  4425.   throw IException("The contractor's name is incomplete. Complete all name fields and try again.");
  4426.   delete p;
  4427.   return *this;
  4428.   }
  4429.  
  4430. // Refresh the value of contractor ID
  4431.  
  4432.   setContractorID();
  4433.   p->addOrReplaceElementWithKey("contractorID", contractorID(), iContractorID));
  4434.  
  4435. // If other data about this contractor exists, update it in the database
  4436.  
  4437.   if (lastName)
  4438.     p->addOrReplaceElementWithKey("lastName", lastName(), iContractorID));
  4439.   if (firstName)
  4440.     p->addOrReplaceElementWithKey("firstName", firstName(), iContractorID));
  4441.   if (middleInitial)
  4442.     p->addOrReplaceElementWithKey("middleInitial", middleInitial(), iContractorID));
  4443.   if (homeStreet)
  4444.     p->addOrReplaceElementWithKey("homeStreet", homeStreet(), iContractorID));
  4445.   if (homeCity)
  4446.     p->addOrReplaceElementWithKey("homeCity", homeCity(), iContractorID));
  4447.   if (homeState)
  4448.     p->addOrReplaceElementWithKey("homeState", homeState(), iContractorID));
  4449.   if (homeZip)
  4450.     p->addOrReplaceElementWithKey("homeZip", homeZip(), iContractorID));
  4451.   if (telephoneNumber)
  4452.     p->addOrReplaceElementWithKey("telephoneNumber", telephoneNumber(), iContractorID));
  4453.   if (startDate)
  4454.     p->addOrReplaceElementWithKey("startDate", startDate(), iContractorID));
  4455.   if (endDate)
  4456.     p->addOrReplaceElementWithKey("endDate", endDate(), iContractorID));
  4457.   if (currentContract)
  4458.     p->addOrReplaceElementWithKey("currentContract", currentContract(), iContractorID));
  4459.   if (iActiveStatus)
  4460.   {
  4461.     p->addOrReplaceElementWithKey("activeStatus", "yes", iContractorID));
  4462.   }
  4463.   else
  4464.   {
  4465.     p->addOrReplaceElementWithKey("activeStatus", "no", iContractorID));
  4466.   }
  4467.  
  4468.   delete p;
  4469.  
  4470. // End data entry code
  4471.  
  4472.   return *this;
  4473. }
  4474.  
  4475. The putContractor action checks for one possible error condition. If it occurs, 
  4476. the action throws an exception. Otherwise, the action stores data by contractor 
  4477. identifier in the contrctr.ini file. 
  4478.  
  4479. In response to these exceptions, the OAContractorView part shows a message box. 
  4480. More about this part appears in Constructing Containers and Notebooks. For 
  4481. information about how to handle exceptions visually, see Passing Exceptions to 
  4482. Message Boxes. 
  4483.  
  4484.  
  4485. ΓòÉΓòÉΓòÉ 8.4.3. Modifying Code for the parseName Action ΓòÉΓòÉΓòÉ
  4486.  
  4487. The parseName action parses input text from the Request for Contractor 
  4488. Information window and sets the contractor's firstName, middleInitial, and 
  4489. lastName attributes. Add code as follows: 
  4490.  
  4491. OAContractor & OAContractor::parseName(const IString & aName)
  4492. {
  4493.  
  4494. // aName is supplied by user in OAQueryContractor
  4495. // Test for missing information in newly entered name
  4496.  
  4497.   if (aName.numWords()!= 3)
  4498.   {
  4499.   throw IException("The name you entered is incomplete.
  4500.                     Enter first name, middle initial, and last name.");
  4501.   return *this;
  4502.   }
  4503.  
  4504. // Set name attributes and derive contractorID attribute
  4505.  
  4506.   setFirstName(aName.word(1));
  4507.   setMiddleInitial(aName.word(2));
  4508.   setLastName(aName.word(3));
  4509.   setContractorID;
  4510.  
  4511. // End added code
  4512.  
  4513.   return *this;
  4514. }
  4515.  
  4516.  
  4517. ΓòÉΓòÉΓòÉ 8.4.4. Adding Code to Set the activeStatus Attribute ΓòÉΓòÉΓòÉ
  4518.  
  4519. You must add a member function to pass string data to the one Boolean 
  4520. attribute, activeStatus. All data in our simple database is stored as strings, 
  4521. but the set member function for the activeStatus attribute takes a Boolean as a 
  4522. parameter. Because only OAContractor's two actions use this member function, it 
  4523. is not necessary to add this to the part interface for OAContractor. However, 
  4524. you must add the member function prototype to the contrctr.hpv file. 
  4525.  
  4526. The following example shows both the default feature code and the added code in 
  4527. contrctr.cpv: 
  4528.  
  4529. Boolean OAContractor::isActiveStatus() const
  4530. {
  4531.   return iActiveStatus;
  4532. }
  4533.  
  4534. OAContractor & OAContractor::enableActiveStatus(const Boolean enable)
  4535. {
  4536.   if (iActiveStatus != enable)
  4537.   {
  4538.     iActiveStatus = enable;
  4539.     notifyObservers(INotificationEvent(OAContractor::activeStatusId, *this));
  4540.   } // endif
  4541.   return *this;
  4542. }
  4543.  
  4544. // Start Boolean string enabler
  4545.  
  4546. OAContractor & OAContractor::enableActiveStatus(const IString & status)
  4547. {
  4548.   Boolean tempBoolean = iActiveStatus;
  4549.   if (status = "yes") iActiveStatus = true;
  4550.   if (status = "no") iActiveStatus = false;
  4551.   if (tempBoolean != iActiveStatus)
  4552.   {
  4553.     notifyObservers(INotificationEvent(OAContractor::activeStatusId, *this));
  4554.   }
  4555.   return *this;
  4556. }
  4557.  
  4558. // End Boolean string enabler
  4559.  
  4560. iActiveStatus is the private data member that corresponds to the activeStatus 
  4561. attribute. 
  4562.  
  4563. The notifyObservers function signals that the value of the activeStatus 
  4564. attribute has changed. For more information about notification, see Building 
  4565. VisualAge C++ Parts for Fun and Profit. 
  4566.  
  4567.  
  4568. ΓòÉΓòÉΓòÉ 8.4.5. Adding Code to Set the contractorID Attribute ΓòÉΓòÉΓòÉ
  4569.  
  4570. Now, add code to derive the value of the contractorID attribute. The following 
  4571. example shows the code as modified in contrctr.cpv: 
  4572.  
  4573. OAContractor & OAContractor::setContractorID()
  4574. {
  4575.   IString tempString = iFirstName+iMiddleInitial+iLastName;
  4576.   if (iContractorID != tempString)
  4577.   {
  4578.     iContractorID = tempString;
  4579.     notifyObservers(INotificationEvent(OAContractor::contractorIDId, *this));
  4580.   } // endif
  4581.   return *this;
  4582. }
  4583.  
  4584. The next step is adding code that was created outside of Visual Builder. 
  4585.  
  4586.  
  4587. ΓòÉΓòÉΓòÉ 8.5. Adding Code Created Outside Visual Builder ΓòÉΓòÉΓòÉ
  4588.  
  4589. To include previously existing member function code with generated class 
  4590. declarations, do the following: 
  4591.  
  4592.    1. Change the file extension of .cpp files to .cpv. 
  4593.    2. Change the file extension of .hpp files to .hpv. 
  4594.    3. Change the file extension of any .rc files to .rcv. 
  4595.    4. Add these files to the Class Editor for the appropriate part. 
  4596.  
  4597.  If you prefer not to use Visual Builder to develop the code for a nonvisual 
  4598.  part but you want to be able to use it in the Composition Editor, you can do 
  4599.  the following: 
  4600.  
  4601.      Write the code. 
  4602.      Compile it into a .lib file. 
  4603.      Define the part interface using a part information file. 
  4604.      Import the part information file. 
  4605.  
  4606.  For more information on part information files, see Defining the Part 
  4607.  Interface Using Part Information Files. 
  4608.  
  4609.  
  4610. ΓòÉΓòÉΓòÉ 9. Learning to Use Parts ΓòÉΓòÉΓòÉ
  4611.  
  4612.      Visual construction overview 
  4613.  
  4614.      Working with parts in the Visual Builder window 
  4615.  
  4616.      Working with parts on the free-form surface 
  4617.  
  4618.      Undoing and redoing changes in the Composition Editor 
  4619.  
  4620.      Constructing a GUI: the OASearch application 
  4621.  
  4622.  
  4623. ΓòÉΓòÉΓòÉ 9.1. Visual Construction Overview ΓòÉΓòÉΓòÉ
  4624.  
  4625. This chapter provides general information on using parts, and then shows you 
  4626. how some of this information can be applied to an actual application-the 
  4627. OASearch sample application that was introduced in Designing Parts for the 
  4628. OASearch Application. 
  4629.  
  4630. With the Composition Editor you can visually construct an application by 
  4631. placing parts on the free-form surface and making connections between them. 
  4632.  
  4633. With connections, you can construct the interactions between the parts of the 
  4634. application. For information about connecting parts to each other, see Learning 
  4635. to Use Connections. 
  4636.  
  4637. In Visual Builder you use the following kinds of parts: 
  4638.  
  4639.      Visual parts, such as IPushButton*, IListBox*, and IEntryField*, to 
  4640.       construct the graphical user interface (GUI) of the application. 
  4641.  
  4642.      Nonvisual parts, such as the sample ICustomer and ICompany parts, to 
  4643.       represent the data or objects manipulated by the application. 
  4644.  
  4645.      Class interface parts, such as IDate* and ITime*, to represent data or 
  4646.       objects, also. The difference between nonvisual parts and class interface 
  4647.       parts is that nonvisual parts can notify other parts when an event occurs 
  4648.       or an attribute value changes; class interface parts, however, do not 
  4649.       have this notification capability. 
  4650.  
  4651.  
  4652. ΓòÉΓòÉΓòÉ 9.2. Working with Parts in the Visual Builder Window ΓòÉΓòÉΓòÉ
  4653.  
  4654. The topics in this section describe how to perform various actions on part 
  4655. classes from the Visual Builder window. 
  4656.  
  4657. The following topics are covered: 
  4658.  
  4659.      Displaying part names 
  4660.  
  4661.      Selecting all parts 
  4662.  
  4663.      Deselecting all parts 
  4664.  
  4665.      Importing part information 
  4666.  
  4667.      Exporting part information 
  4668.  
  4669.      Creating a new part 
  4670.  
  4671.      Opening parts 
  4672.  
  4673.      Copying parts from one .vbb file to another 
  4674.  
  4675.      Moving parts to a different .vbb file 
  4676.  
  4677.      Deleting parts from a .vbb file 
  4678.  
  4679.      Renaming parts in .vbb files 
  4680.  
  4681.  Personal notes: 
  4682.  
  4683.  
  4684. ΓòÉΓòÉΓòÉ 9.2.1. Displaying Part Names ΓòÉΓòÉΓòÉ
  4685.  
  4686. To display the names of the parts in a .vbb file, in the Loaded Files list box 
  4687. in the Visual Builder window select the .vbb file whose parts you want to see. 
  4688. The names of the parts contained in the .vbb file that you selected are 
  4689. displayed in the Visual Builder window. Visual parts are displayed in the 
  4690. Visual Parts list box; nonvisual parts and class interface parts are displayed 
  4691. in the Nonvisual Parts list box. 
  4692.  
  4693. Once part names are displayed, you can perform actions on them, such as opening 
  4694. or deleting them. If you need information about loading .vbb files, see Loading 
  4695. .vbb Files. 
  4696.  
  4697. The following figure shows the Visual Builder window with the names of the 
  4698. parts in the vbbase.vbb file displayed: 
  4699.  
  4700.  
  4701. ΓòÉΓòÉΓòÉ 9.2.2. Selecting All Parts ΓòÉΓòÉΓòÉ
  4702.  
  4703. To select all of the parts in the selected .vbb files, select EditSelect all 
  4704. parts. 
  4705.  
  4706. At this point, you can review the list to see if you want to deselect any of 
  4707. the parts. You can do so by pressing the Ctrl key and clicking on the part name 
  4708. with mouse button 1. 
  4709.  
  4710.  
  4711. ΓòÉΓòÉΓòÉ 9.2.3. Deselecting All Parts ΓòÉΓòÉΓòÉ
  4712.  
  4713. To deselect all of the parts in the selected .vbb files, select EditDeselect 
  4714. all parts. 
  4715.  
  4716.  
  4717. ΓòÉΓòÉΓòÉ 9.2.4. Importing Part Information ΓòÉΓòÉΓòÉ
  4718.  
  4719. Using any text editor, you can create files called part information files, 
  4720. which are used to import existing C++ classes into Visual Builder as parts. 
  4721. Part information files are normally recognizable by their .vbe. extension. 
  4722.  
  4723. The import part information function loads part information files so that you 
  4724. can use the parts specified in those files in Visual Builder. 
  4725.  
  4726. To import part information, do the following: 
  4727.  
  4728.    1. Select FileImport part information. 
  4729.  
  4730.       The following window is displayed: 
  4731.  
  4732.    2. Select the part information file that you want to import. 
  4733.  
  4734.    3. Select the OK push button. 
  4735.  
  4736.       The part information in the part information file is imported. Any visual 
  4737.       parts that the part information file contains are displayed in the Visual 
  4738.       Parts list box, and any nonvisual parts and class interface parts it 
  4739.       contains are displayed in the Nonvisual Parts list box. In addition, one 
  4740.       or more .vbb files may be created. 
  4741.  
  4742.  For more information about using and creating part information files, see the 
  4743.  following: 
  4744.  
  4745.      Defining the Part Interface Using  Part Information Files (.vbb) 
  4746.      Building VisualAge C++ Parts for Fun and Profit 
  4747.  
  4748.  
  4749. ΓòÉΓòÉΓòÉ 9.2.5. Exporting Part Information ΓòÉΓòÉΓòÉ
  4750.  
  4751. Just as you can import part information from an existing part information file, 
  4752. you can also export part information for any Visual Builder part into a .vbe 
  4753. file. 
  4754.  
  4755. The Export interface function creates a part information file that you can, for 
  4756. example, use to share nonvisual and class interface parts with other 
  4757. programmers. Part information files contain usage information that programmers 
  4758. who do not have access to the part (.vbb) file can use. 
  4759.  
  4760. To export part information, do the following: 
  4761.  
  4762.    1. Select the part or parts whose information you want to export in either 
  4763.       the Visual Parts list box, the Nonvisual Parts list box, or both. 
  4764.  
  4765.    2. Select PartExport interface. 
  4766.  
  4767.       The following window is displayed: 
  4768.  
  4769.    3. Type the name of the .vbe file in which you want the part information to 
  4770.       be stored in the Open filename field. 
  4771.  
  4772.       If you do not enter a file name, Visual Builder uses exported.vbe as the 
  4773.       default file name. 
  4774.  
  4775.    4. Select the OK push button. 
  4776.  
  4777.       The part information maintained by Visual Builder is exported to the file 
  4778.       name you specified in the Open filename field. 
  4779.  
  4780.  For more information about using and creating part information files, see the 
  4781.  following: 
  4782.  
  4783.      Defining the Part Interface Using Part Information Files (.vbb) 
  4784.      Building VisualAge C++ Parts for Fun and Profit 
  4785.  
  4786.  
  4787. ΓòÉΓòÉΓòÉ 9.2.6. Creating a New Part ΓòÉΓòÉΓòÉ
  4788.  
  4789. This section provides only the basic steps for creating a new part. For a 
  4790. description of how to create a part that others can reuse, see Creating Parts 
  4791. for Reuse. 
  4792.  
  4793. To create a new part, do the following: 
  4794.  
  4795.    1. Select PartNew. 
  4796.  
  4797.       A Part - New window is displayed, as follows: 
  4798.  
  4799.    2. Enter the name that you want to give to your part in the Class name 
  4800.       field. 
  4801.  
  4802.    3. Enter a description of your part in the Description field. 
  4803.  
  4804.       Visual Builder uses the description that you enter here in the following 
  4805.       ways: 
  4806.  
  4807.           If you add the part that you create to the parts palette, Visual 
  4808.            Builder displays the part's description in the information area at 
  4809.            the bottom of the Composition Editor when the part is selected. 
  4810.  
  4811.           If you export the information about the part to a .vbe file, the 
  4812.            description is included with the other information about the part. 
  4813.  
  4814.    4. Enter the name of the .vbb file in which you want Visual Builder to store 
  4815.       the part in the File name field. 
  4816.  
  4817.       If the file does not already exist, Visual Builder creates it for you. If 
  4818.       you leave this field blank, Visual Builder creates a .vbb file as 
  4819.       follows: 
  4820.  
  4821.           If you are using the High Performance File System (HPFS) and do not 
  4822.            select OptionsDefault to FAT file names, the name of the .vbb file 
  4823.            is the same as the name of your part. 
  4824.  
  4825.           If you are using the File Allocation Table (FAT) file system and 
  4826.            have selected OptionsDefault to FAT file names, Visual Builder 
  4827.            creates a .vbb file whose name has no more than eight characters. 
  4828.            Without this selection, Visual Builder attempts to create a .vbb 
  4829.            file whose name is the same as the name of your part, which causes 
  4830.            an error if your part name has more than eight characters. 
  4831.  
  4832.            Note:  If you are using the FAT file system, we recommend that you 
  4833.                   always use part names and file names that have eight 
  4834.                   characters or less, even if you have selected the Default to 
  4835.                   FAT file names option. Otherwise, Visual Builder might use a 
  4836.                   file name for a .vbb file that is the same as one that 
  4837.                   already exists and write over the existing file. 
  4838.  
  4839.    5. Select the type of part that you want to create in the Part type field. 
  4840.       You can select one of the following: 
  4841.  
  4842.           Visual part 
  4843.           Nonvisual part 
  4844.           Class interface 
  4845.  
  4846.    6. Either keep the default class name provided by Visual Builder in the Base 
  4847.       class field, change it, or delete it. 
  4848.  
  4849.       Note the following: 
  4850.  
  4851.           A nonvisual part must have the IStandardNotifier class in its 
  4852.            inheritance so it can exhibit the behavior required for all parts-a 
  4853.            part interface (attributes, events, and actions). It must inherit 
  4854.            this behavior from IStandardNotifier. Therefore, you cannot leave 
  4855.            this field blank when creating a nonvisual part. The default base 
  4856.            class for a nonvisual part is IStandardNotifier. 
  4857.  
  4858.           A visual part must have the IWindow class in its inheritance so it 
  4859.            can inherit the visual behavior common to all windows, as well as 
  4860.            part interface behavior, which IWindow inherits from 
  4861.            IStandardNotifier. Therefore, you cannot leave this field blank when 
  4862.            creating a visual part. The default base class for a visual part is 
  4863.            IFrameWindow, which inherits from IWindow. 
  4864.  
  4865.           No inheritance is required for a class interface part. Therefore, 
  4866.            you can leave the Base class field blank when creating a class 
  4867.            interface part. The default base class for a class interface part is 
  4868.            IVBase*. 
  4869.  
  4870.    7. Select Open. 
  4871.  
  4872.       One of the following occurs: 
  4873.  
  4874.           If you are creating a visual part, the Composition Editor is 
  4875.            displayed. 
  4876.  
  4877.           If you are creating a nonvisual part or a class interface part, the 
  4878.            Part Interface Editor is displayed. 
  4879.  
  4880.    8. Use the displayed editor to create your part. 
  4881.  
  4882.  
  4883. ΓòÉΓòÉΓòÉ 9.2.7. Opening Parts ΓòÉΓòÉΓòÉ
  4884.  
  4885. Use PartOpen to open parts that are already created. You must load the .vbb 
  4886. file that contains a part before you can open the part. 
  4887.  
  4888. Visual Builder uses the question mark icon, , to represent the unloaded parts 
  4889. on the free-form surface. If you open a part that contains other parts and the 
  4890. .vbb files that contain the other parts are not loaded, Visual Builder displays 
  4891. this icon. 
  4892.  
  4893. The question mark folder icon indicates that most of the information about the 
  4894. unloaded part is not available to Visual Builder. You can select connections 
  4895. between unloaded parts and other parts to see which features are connected, but 
  4896. the features are not available in the unloaded part's connection menu. 
  4897.  
  4898. You should not make any changes to an unloaded part or generate any code when a 
  4899. part is not loaded. 
  4900.  
  4901. If you open a part and see a question mark folder icon, do the following: 
  4902.  
  4903.    1. Close the part you just opened. 
  4904.  
  4905.    2. Load the .vbb file that contains the unloaded part. 
  4906.  
  4907.    3. Reopen the part you previously opened. 
  4908.  
  4909.       The question mark folder icon is replaced by the part's icon. 
  4910.  
  4911.  The following instructions tell you how to open one part at a time or multiple 
  4912.  parts simultaneously. 
  4913.  
  4914.  Opening one part 
  4915.  
  4916.  To open one part, do the following: 
  4917.  
  4918.    1. Find the name of the part that you want to open by scrolling through the 
  4919.       appropriate list box in the Visual Builder window. 
  4920.  
  4921.       Note:  If the list boxes in the Visual Builder window are empty or if you 
  4922.              cannot find the part, the .vbb file that contains the part you 
  4923.              want to open is not selected or not loaded. See Loading .vbb Files 
  4924.              if you need help loading .vbb files. 
  4925.  
  4926.       The Visual Builder window with parts loaded from the vbbase.vbb file is 
  4927.       shown in the following figure: 
  4928.  
  4929.    2. Select the part you want to open. 
  4930.  
  4931.    3. Select Part on the menu bar. 
  4932.  
  4933.    4. Select Open in the pull-down menu. 
  4934.  
  4935.       One of the following occurs: 
  4936.  
  4937.           If you are opening a visual part, Visual Builder displays the 
  4938.            Composition Editor. 
  4939.  
  4940.           If you are opening a nonvisual part, Visual Builder displays the 
  4941.            Part Interface Editor. 
  4942.  
  4943.            A quicker way to open an existing part is to double-click on the 
  4944.            part name within the Visual Parts or Nonvisual Parts list box. 
  4945.  
  4946.  Opening multiple parts 
  4947.  
  4948.  To open multiple parts, do the following: 
  4949.  
  4950.    1. Find the name of the first part that you want to open by scrolling 
  4951.       through the Nonvisual Parts and Visual Parts list boxes shown in the 
  4952.       Visual Builder window. 
  4953.  
  4954.       Note:  If the list boxes in the Visual Builder window are empty, see 
  4955.              Loading .vbb Files if you need help loading .vbb files. 
  4956.  
  4957.       The Visual Builder window with parts loaded from the vbbase.vbb file is 
  4958.       shown in the following figure: 
  4959.  
  4960.    2. Select the first part you want to open. 
  4961.  
  4962.    3. Find the next part you want to open and press the Ctrl key while 
  4963.       selecting that part. 
  4964.  
  4965.    4. Continue finding and selecting parts in this manner, pressing the Ctrl 
  4966.       key while selecting each part, until you have selected all the parts you 
  4967.       want to open. 
  4968.  
  4969.    5. Select Part on the menu bar. 
  4970.  
  4971.    6. Select Open in the pull-down menu. 
  4972.  
  4973.       Visual Builder displays a separate window for each part that you 
  4974.       selected. The window displayed is the Composition Editor for visual parts 
  4975.       or the Part Interface Editor for nonvisual parts. 
  4976.  
  4977.  
  4978. ΓòÉΓòÉΓòÉ 9.2.8. Copying Parts from One .vbb File to Another ΓòÉΓòÉΓòÉ
  4979.  
  4980. To copy a part, do the following: 
  4981.  
  4982.    1. Select the part that you want to copy in the Visual Parts or Nonvisual 
  4983.       Parts list box. 
  4984.  
  4985.       If you select more than one part or if you do not select a part, the Copy 
  4986.       function is not available. 
  4987.  
  4988.    2. Select PartCopy. 
  4989.  
  4990.       The following window is displayed: 
  4991.  
  4992.       The Source part name field shows the name of the part that you selected 
  4993.       to copy. 
  4994.  
  4995.    3. In the Target part name field, enter the name you want the part to have 
  4996.       when you copy it. 
  4997.  
  4998.    4. In the Target file name field, enter the name of the .vbb file to which 
  4999.       you want to copy the part. If you leave this field blank, the part's 
  5000.       current file name is used. 
  5001.  
  5002.    5. Select the Copy push button. 
  5003.  
  5004.       The part is copied under the new name and stored in the designated .vbb 
  5005.       file. 
  5006.  
  5007.  
  5008. ΓòÉΓòÉΓòÉ 9.2.9. Moving Parts to a Different .vbb File ΓòÉΓòÉΓòÉ
  5009.  
  5010. Here is what happens to the .vbb file into which the part or parts are being 
  5011. moved: 
  5012.  
  5013.      If this .vbb file does not exist, Visual Builder creates and loads it for 
  5014.       you. 
  5015.  
  5016.      If this .vbb file already exists and is loaded, the part or parts are 
  5017.       moved into it. 
  5018.  
  5019.      If this .vbb file already exists but is not loaded, Visual Builder 
  5020.       displays a message to warn you that the unloaded .vbb file will be 
  5021.       overwritten by the part or parts that you are moving into it. 
  5022.  
  5023.  To move one or more parts from one .vbb file to another, do the following: 
  5024.  
  5025.    1. Select the part or parts that you want to move. 
  5026.  
  5027.       If you do not select at least one part, the Move function is not 
  5028.       available. 
  5029.  
  5030.    2. Select PartMove. 
  5031.  
  5032.    3. Use the following instructions for moving one part or multiple parts: 
  5033.  
  5034.       Moving one part 
  5035.  
  5036.       If you selected one part, the following window is displayed: 
  5037.  
  5038.       The Part name field of this window shows the name of the part that you 
  5039.       selected to move. The File name field displays the complete path of the 
  5040.       .vbb file that contains the part you want to move. 
  5041.  
  5042.       Do the following: 
  5043.  
  5044.         a. In the New file name field, enter the path and name of the .vbb file 
  5045.            to which you want to move the part. 
  5046.  
  5047.         b. Select the Move push button. 
  5048.  
  5049.            The part is moved to the .vbb file specified in the New file name 
  5050.            field. 
  5051.  
  5052.       Moving multiple parts 
  5053.  
  5054.       If you selected more than one part, the following window is displayed: 
  5055.  
  5056.       The text in the window specifies the names of the parts you selected. 
  5057.  
  5058.       Do the following: 
  5059.  
  5060.         a. In the entry field, enter the name of the .vbb file to which you 
  5061.            want to move the parts. If the .vbb file is not in your current 
  5062.            directory, specify the complete path for the .vbb file. 
  5063.  
  5064.         b. Select the OK push button. 
  5065.  
  5066.            The parts are moved to the .vbb file specified in the entry field. 
  5067.  
  5068.            An alternate method of moving a part is to change the name of the 
  5069.            .vbb file specified in the Class Editor. For more information, see 
  5070.            Using the .vbb File Specification Field 
  5071.  
  5072.  
  5073. ΓòÉΓòÉΓòÉ 9.2.10. Deleting Parts from a .vbb File ΓòÉΓòÉΓòÉ
  5074.  
  5075. To delete a part, do the following: 
  5076.  
  5077.    1. Select the part or parts that you want to delete in the Visual Parts list 
  5078.       box, Nonvisual Parts list box, or both. 
  5079.  
  5080.       If you do not select at least one part, the Delete function is not 
  5081.       available. 
  5082.  
  5083.    2. Select PartDelete. 
  5084.  
  5085.       The following window is displayed: 
  5086.  
  5087.       Deselect any parts that you do not want to delete. Once you delete a part 
  5088.       from a .vbb file, you cannot recover it unless you have another copy 
  5089.       stored in another .vbb file. 
  5090.  
  5091.    3. Select the Delete push button. 
  5092.  
  5093.       The selected parts are deleted. 
  5094.  
  5095.  
  5096. ΓòÉΓòÉΓòÉ 9.2.11. Renaming Parts in .vbb Files ΓòÉΓòÉΓòÉ
  5097.  
  5098. The PartRename menu choice allows you to change the name that a part is stored 
  5099. under in a .vbb file. 
  5100.  
  5101.            Use care when renaming parts because the name changes only in the 
  5102.            .vbb file in which the part is stored. The name of the part does not 
  5103.            change in any other part in which this part is embedded, that is, 
  5104.            used as a subpart. Therefore, the next time you open the part in 
  5105.            which you embedded the renamed part, Visual Builder will not be able 
  5106.            to find the renamed part. 
  5107.  
  5108.  To rename a part in a .vbb file, do the following: 
  5109.  
  5110.    1. Select the part that you want to rename in the Visual Parts or Nonvisual 
  5111.       Parts list box. 
  5112.  
  5113.       If you select more than one part or if you do not select a part, the 
  5114.       Rename function is not available. 
  5115.  
  5116.    2. Select PartRename. 
  5117.  
  5118.       The following window is displayed: 
  5119.  
  5120.       The Part name field shows the name of the part that you selected to 
  5121.       rename. 
  5122.  
  5123.    3. In the New part name field, enter the new name that you want to give the 
  5124.       part. 
  5125.  
  5126.    4. Select the Rename push button. 
  5127.  
  5128.       The part is renamed under the new name. 
  5129.  
  5130.  
  5131. ΓòÉΓòÉΓòÉ 9.3. Working with Parts on the Free-form Surface ΓòÉΓòÉΓòÉ
  5132.  
  5133.      Placing parts on the free-form surface 
  5134.  
  5135.      Selecting and deselecting parts 
  5136.  
  5137.      Manipulating parts, which includes: 
  5138.  
  5139.         -  Displaying pop-up menus 
  5140.         -  Copying parts 
  5141.         -  Deleting parts 
  5142.         -  Editing text strings 
  5143.         -  Renaming parts 
  5144.  
  5145.      Arranging parts, which includes: 
  5146.  
  5147.         -  Moving parts 
  5148.         -  Positioning parts on the grid 
  5149.         -  Sizing parts 
  5150.         -  Matching part sizes 
  5151.         -  Aligning parts 
  5152.         -  Spacing parts within Composer parts 
  5153.         -  Spacing parts within a bounding box 
  5154.  
  5155.      Changing settings for a part 
  5156.  
  5157.      Tearing off an attribute 
  5158.  
  5159.  Personal notes: 
  5160.  
  5161.  
  5162. ΓòÉΓòÉΓòÉ 9.3.1. Placing Parts on the Free-form Surface ΓòÉΓòÉΓòÉ
  5163.  
  5164. In the Composition Editor, you place visual, nonvisual, and class interface 
  5165. parts on the free-form surface. This section explains how to place parts there 
  5166. that appear on the parts palette, as well as parts that do not appear on the 
  5167. parts palette. 
  5168.  
  5169. Placing a part that appears on the parts palette 
  5170.  
  5171.    1. From the left column of the parts palette, select the appropriate 
  5172.       category. Then, from the right column, select the part you want to add. 
  5173.  
  5174.       When the mouse pointer is moved over a place where the part can be 
  5175.       placed, it changes to a crosshair, indicating that it is loaded with the 
  5176.       part. 
  5177.  
  5178.    2. Move the mouse pointer to where you want to add the part. 
  5179.  
  5180.    3. Click mouse button 1. 
  5181.  
  5182.       If you hold down mouse button 1 instead of clicking it, an outline of the 
  5183.       part is displayed under the pointer to help you position the part. After 
  5184.       the part is in position, release mouse button 1. 
  5185.  
  5186.  See Touring the Parts Palette and Touring the Free-form Surface for more 
  5187.  information. 
  5188.  
  5189.  To unload the mouse pointer at any time, do either of the following: 
  5190.  
  5191.      Select , the Selection tool, on the tool bar. 
  5192.  
  5193.      Select ToolsSelection Tool on the menu bar. 
  5194.  
  5195.            To add several copies of the same part, select Sticky on the parts 
  5196.            palette. When Sticky is selected, the mouse pointer remains loaded 
  5197.            with the part you last selected. When Sticky is not selected, the 
  5198.            mouse pointer becomes unloaded after you add a part. 
  5199.  
  5200.  Placing a part that is not on the parts palette 
  5201.  
  5202.  You can place on the free-form surface any part whose .vbb file is loaded by 
  5203.  doing the following: 
  5204.  
  5205.    1. Select Add part from the Options pull-down menu. 
  5206.  
  5207.       The Add Part window appears, as shown in the following figure: 
  5208.  
  5209.    2. Type the part's class name in the Part class field. 
  5210.  
  5211.       This is the class name that was specified when the part was created. When 
  5212.       you begin typing, you replace the highlighted prompt with the name of the 
  5213.       part you want to add. 
  5214.  
  5215.       The asterisk at the end of the name is a reminder that you are actually 
  5216.       entering a pointer to the part. When you enter a valid class name for the 
  5217.       part without deleting the asterisk, Visual Builder automatically selects 
  5218.       the Part radio button. You can change this by selecting the Variable 
  5219.       radio button if you want to place a pointer to a variable on the 
  5220.       free-form surface. The following figure shows how you could place a 
  5221.       notebook part on the free-form surface using the Add Part window: 
  5222.  
  5223.       If you delete the asterisk, the Part radio button is not available. This 
  5224.       means that you can only place a variable on the free-form surface; Visual 
  5225.       Builder automatically selects the Variable radio button indicating that 
  5226.       you will be adding a variable whose type is the class name you entered in 
  5227.       the Part class field, as shown in the following figure: 
  5228.  
  5229.       Note:  You cannot add abstract parts or template parts using the Add Part 
  5230.              window. For example, IButton* is the abstract part that 
  5231.              IPushButton* inherits from. You can add IPushButton*, but not 
  5232.              IButton*. 
  5233.  
  5234.       Similarly, you cannot add an object factory part or a variable part using 
  5235.       the Add Part window because they are templates. You must add them by 
  5236.       selecting them on the parts palette. 
  5237.  
  5238.    3. Type a name for the part in the Name field. 
  5239.  
  5240.       This name will appear in the information area at the bottom of the 
  5241.       Composition Editor when you select the part after it is placed; it is 
  5242.       also used for the part when you generate your part code. 
  5243.  
  5244.       The Name field is optional. If you leave it blank, the part's class name 
  5245.       is used. 
  5246.  
  5247.    4. Select the Add push button to add the part. 
  5248.  
  5249.       The Add Part window disappears and the mouse pointer turns into the same 
  5250.       crosshairs used for placing a part on the free-form surface. 
  5251.  
  5252.       Note:  If you did not enter the name of a part that is known to Visual 
  5253.              Builder in the Part class field, the Add push button is not 
  5254.              enabled. 
  5255.  
  5256.    5. Move the crosshairs to the place where you want to add the part and click 
  5257.       mouse button 1. 
  5258.  
  5259.  
  5260. ΓòÉΓòÉΓòÉ 9.3.2. Guidelines for Placing Parts on the Free-form Surface ΓòÉΓòÉΓòÉ
  5261.  
  5262. Following are guidelines for placing parts on the free-form surface: 
  5263.  
  5264.      Avoid overlaying parts 
  5265.  
  5266.       You can overlay visual parts. Generally speaking, however, it is not good 
  5267.       interface design for one part to overlay another part, such as one push 
  5268.       button either completely or partially covering another push button. Be 
  5269.       aware that completely overlaying a part can cause focus problems, meaning 
  5270.       that runtime users may be able to see, but not select, the part. 
  5271.  
  5272.       Partially overlaying a part can cause problems, too, because the runtime 
  5273.       users might not be able to see where the overlaying occurs. When they try 
  5274.       to select the part that is partially overlaid, they may be lucky and 
  5275.       select the right spot, or they may select the part that is overlaying the 
  5276.       part they are trying to select. If you overlay parts, be sure to do it in 
  5277.       a way in which the user can understand why the parts are overlaid and how 
  5278.       to select them. 
  5279.  
  5280.       You cannot overlay, or cover up, nonvisual parts. You can overlay visual 
  5281.       parts, but you should avoid doing this if possible unless you are placing 
  5282.       parts on top of a part in the Composers category (see the next 
  5283.       guideline). 
  5284.  
  5285.      Place other parts on top of parts in the Composers category 
  5286.  
  5287.       Parts included in the Composers category have a special behavior; these 
  5288.       parts can contain any other visual parts that are placed on top of them. 
  5289.       The parts that the Composers part contains automatically become subparts 
  5290.       of the Composers part. For example, if you place an entry field, a list 
  5291.       box, and two push buttons in a frame window, the frame window contains 
  5292.       the other parts and they, in turn, become the frame window's subparts. 
  5293.  
  5294.       The following table lists each of the Visual Builder categories and 
  5295.       specifies how you can use the parts in each category. 
  5296.  
  5297.             ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  5298.             ΓöéCategory          ΓöéUse Parts to Contain    ΓöéUse Parts as Subparts?  Γöé
  5299.             Γöé                  ΓöéOther Parts?            Γöé                        Γöé
  5300.             ΓöéButtons           ΓöéNo                      ΓöéYes                     Γöé
  5301.             ΓöéData entry        ΓöéNo                      ΓöéYes                     Γöé
  5302.             ΓöéLists             ΓöéNo                      ΓöéYes                     Γöé
  5303.             ΓöéFrame Extensions  ΓöéNo                      ΓöéNo                      Γöé
  5304.             ΓöéSliders           ΓöéNo                      ΓöéYes                     Γöé
  5305.             ΓöéComposers         ΓöéYes                     ΓöéYes                     Γöé
  5306.             ΓöéModels            ΓöéNo                      ΓöéNo                      Γöé
  5307.             ΓöéOther             ΓöéNo                      ΓöéNo                      Γöé
  5308.             ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  5309.  
  5310.      Use supplementary composite parts as subparts 
  5311.  
  5312.       Suppose you create a visual composite part that consists of a canvas on 
  5313.       which you have placed other visual parts, such as radio buttons and check 
  5314.       boxes, with each radio button and check box connected to a variable, as 
  5315.       shown in the following figure: 
  5316.  
  5317.       Assume this part is not your main composite part but is instead a 
  5318.       supplementary part that you want to use in your application's user 
  5319.       interface. When you place this part in your main composite part, such as 
  5320.       in a frame window, as shown in the following figure, you place it and 
  5321.       work with it as one part, not as a canvas and separate radio buttons and 
  5322.       check boxes. The frame window contains the entire supplementary part, 
  5323.       which becomes a subpart of the frame window. 
  5324.  
  5325.       One of the first things you have probably noticed is that the connections 
  5326.       for a supplementary composite part are not displayed when that part is 
  5327.       added to another part. The connections and variables are still there; you 
  5328.       just cannot see them because you cannot edit them directly from the 
  5329.       Composition Editor window that contains the main composite part. Also, 
  5330.       you cannot select the individual radio buttons, check boxes, or their 
  5331.       connections in the supplementary part that you placed in your main part. 
  5332.  
  5333.       To change the connections or the default text on the radio buttons and 
  5334.       check boxes, or to do anything else to alter this part, you must edit the 
  5335.       part indirectly, as described in Editing Parts Placed on the Free-form 
  5336.       Surface. 
  5337.  
  5338.  
  5339. ΓòÉΓòÉΓòÉ 9.3.3. Selecting and Deselecting Parts ΓòÉΓòÉΓòÉ
  5340.  
  5341. Before you can perform an action on a part that you have placed on the 
  5342. free-form surface, such as sizing it, you must first select the part. The name 
  5343. of the part currently selected is displayed in the information area at the 
  5344. bottom of the Composition Editor. If more than one part is selected, then 
  5345. *Multiple selection* is displayed. 
  5346.  
  5347. You cannot select parts and connections together. They are mutually exclusive. 
  5348. However, if you delete a part that is connected to other parts, Visual Builder 
  5349. deletes the connections in addition to the part. 
  5350.  
  5351. When a part is selected, small boxes, called selection handles, are displayed 
  5352. on its corners. If more than one part is selected, the one you selected last 
  5353. has solid selection handles, indicating that it is the anchor part. The other 
  5354. selected parts have hollow selection handles as shown in the following figure: 
  5355.  
  5356. Some parts are not sizable and, therefore, do not have any selection handles. 
  5357. These parts have their background reverse colored. Parts with this behavior 
  5358. include variables, menus, and tear-off attributes, among others. 
  5359.  
  5360. The following sections describe how to select and deselect a single part and 
  5361. multiple parts. 
  5362.  
  5363. Selecting a single part 
  5364.  
  5365. To select a part that you have placed on the free-form surface, click on the 
  5366. part with mouse button 1. If other parts are already selected, they are 
  5367. deselected automatically. 
  5368.  
  5369. Selecting multiple parts 
  5370.  
  5371. Selecting multiple parts enables you to perform the same operation on several 
  5372. parts at once. To select multiple parts, do one of the following: 
  5373.  
  5374.      Hold down the Ctrl key and click mouse button 1 on each additional part 
  5375.       you want to select. 
  5376.  
  5377.      Hold down mouse button 1 instead of clicking it; then move the mouse 
  5378.       pointer over each additional part you want to select. After you select 
  5379.       the parts, release mouse button 1. 
  5380.  
  5381.  Note:  Depending on the operation you want to perform, remember to consider 
  5382.         which part you want to be the anchor part because that is the part you 
  5383.         want to select last. For example, if you select two parts because you 
  5384.         want to match the width of one part to the width of the other, the part 
  5385.         you select last is the anchor part, the part whose width is used for 
  5386.         the operation. 
  5387.  
  5388.  Deselecting parts 
  5389.  
  5390.  To deselect a part after you have selected it, do the following: 
  5391.  
  5392.    1. Hold down the Ctrl key. 
  5393.  
  5394.    2. Click on the selected part with mouse button 1. 
  5395.  
  5396.  To deselect multiple parts, do the following: 
  5397.  
  5398.    1. Hold down the Ctrl key. 
  5399.  
  5400.    2. Click on a selected part with mouse button 1. 
  5401.  
  5402.    3. Without releasing either the Ctrl key or mouse button 1, move the mouse 
  5403.       pointer to another selected part. 
  5404.  
  5405.    4. Repeat the previous step until all parts that you want to deselect have 
  5406.       been deselected. 
  5407.  
  5408.  
  5409. ΓòÉΓòÉΓòÉ 9.3.4. Manipulating Parts ΓòÉΓòÉΓòÉ
  5410.  
  5411. Once a part is added to the free-form surface, you can manipulate it in a 
  5412. number of different ways. The following sections explain each of those ways. 
  5413.  
  5414.      Displaying pop-up menus 
  5415.  
  5416.      Copying parts 
  5417.  
  5418.      Deleting parts 
  5419.  
  5420.      Editing text strings 
  5421.  
  5422.      Renaming parts on the free-form surface 
  5423.  
  5424.  Personal notes: 
  5425.  
  5426.  
  5427. ΓòÉΓòÉΓòÉ 9.3.4.1. Displaying Pop-up Menus ΓòÉΓòÉΓòÉ
  5428.  
  5429. To display the pop-up menu of a part, click on the part with mouse button 2. 
  5430. The pop-up menu displays the operations you can perform on that part. 
  5431.  
  5432. A part does not have to be selected for you to display its pop-up menu. The 
  5433. pop-up menu that is displayed is for the part the mouse pointer is over when 
  5434. mouse button 2 is clicked, even if another part is selected. 
  5435.  
  5436.  
  5437. ΓòÉΓòÉΓòÉ 9.3.4.2. Copying Parts ΓòÉΓòÉΓòÉ
  5438.  
  5439. To copy parts by dragging them, do the following: 
  5440.  
  5441.    1. Select all the parts you want to copy. 
  5442.  
  5443.       If you only want to copy one part, you do not have to select it. 
  5444.  
  5445.    2. Move the mouse pointer over the part you want to copy or one of the 
  5446.       selected parts. 
  5447.  
  5448.    3. Hold down the Ctrl key and mouse button 2. 
  5449.  
  5450.    4. Drag a copy of the part or parts by moving the mouse pointer to a new 
  5451.       position. 
  5452.  
  5453.       An outline of the part or parts is displayed to help you with 
  5454.       positioning. When you are copying multiple parts, the outlines of each 
  5455.       part move together as a group. 
  5456.  
  5457.    5. Release the Ctrl key and mouse button 2 when the part or parts are where 
  5458.       you want them to be. 
  5459.  
  5460.       A copy of the part or parts appears where you positioned the outline or 
  5461.       outlines. 
  5462.  
  5463.  Copying parts using the clipboard 
  5464.  
  5465.  To copy parts by using the clipboard, do the following: 
  5466.  
  5467.    1. Select all the parts you want to copy. 
  5468.  
  5469.    2. From the Edit pull-down menu, select Copy. 
  5470.  
  5471.       A copy of each selected part is placed on the clipboard. 
  5472.  
  5473.    3. Select Paste from the Edit pull-down menu when you are ready to use the 
  5474.       parts. 
  5475.  
  5476.       The mouse pointer turns to crosshairs to show that it is loaded with the 
  5477.       copied parts. 
  5478.  
  5479.    4. Position the mouse pointer where you want the parts to be copied. 
  5480.  
  5481.    5. Click mouse button 1. 
  5482.  
  5483.       Copies of the parts are pasted at the position of the mouse pointer. 
  5484.  
  5485.            Parts that you copy remain on the clipboard until you copy something 
  5486.            else. Therefore, you can continue to paste copies of those parts by 
  5487.            selecting Paste, positioning the mouse pointer, and clicking mouse 
  5488.            button 1. 
  5489.  
  5490.            If you select Paste and then decide against pasting the parts, you 
  5491.            can unload the mouse pointer by either selecting the Selection Tool 
  5492.            on the tool bar or by selecting ToolsSelection Tool on the menu 
  5493.            bar. 
  5494.  
  5495.  
  5496. ΓòÉΓòÉΓòÉ 9.3.4.3. Deleting Parts ΓòÉΓòÉΓòÉ
  5497.  
  5498. To delete one or more parts, do the following: 
  5499.  
  5500.    1. Select all of the parts you want to delete. 
  5501.  
  5502.       If you are deleting just one part, you do not have to select it. 
  5503.  
  5504.    2. Position the mouse pointer over the part you want to delete or one of the 
  5505.       selected parts. 
  5506.  
  5507.    3. Click mouse button 2. 
  5508.  
  5509.    4. From the part pop-up menu, select Delete. 
  5510.  
  5511.       The part or parts are deleted. 
  5512.  
  5513.            Any connections between the part that you are deleting and other 
  5514.            parts are also deleted. Visual Builder displays a message to alert 
  5515.            you to this. However, the EditUndo function also restores any 
  5516.            connections that were removed when you deleted the part. 
  5517.  
  5518.  
  5519. ΓòÉΓòÉΓòÉ 9.3.4.4. Editing Text Strings ΓòÉΓòÉΓòÉ
  5520.  
  5521. Some visual parts, such as push buttons and menus, have text strings. To 
  5522. directly edit a part's text string, do the following: 
  5523.  
  5524.    1. Hold down the Alt key. 
  5525.  
  5526.    2. Click mouse button 1 on the text string. 
  5527.  
  5528.    3. Edit the text string. 
  5529.  
  5530.    4. When you have finished, do either of the following: 
  5531.  
  5532.           Click mouse button 1 anywhere outside of the text string. 
  5533.  
  5534.           Press Shift+Enter. 
  5535.  
  5536.            You can also use this direct editing technique to edit the names of 
  5537.            nonvisual parts. The name of a nonvisual part is displayed directly 
  5538.            below its icon. 
  5539.  
  5540.  
  5541. ΓòÉΓòÉΓòÉ 9.3.4.5. Renaming Parts On the Free-form Surface ΓòÉΓòÉΓòÉ
  5542.  
  5543. When you use parts in the Composition Editor, Visual Builder gives those parts 
  5544. a name based on the names given to the parts on the parts palette or the names 
  5545. you specify when you place parts on the free-form surface. For example, the 
  5546. first push button part that you use is named PushButton1. When you select this 
  5547. part, the information area at the bottom of the Composition Editor shows the 
  5548. message "PushButton1 selected." The second push button you use is named 
  5549. PushButton2, the third is named PushButton3, and so forth. These default names 
  5550. are assigned to help Visual Builder distinguish one part from another, as well 
  5551. as the connections between parts, when you generate the code to build your 
  5552. application. 
  5553.  
  5554. If you want to give parts names that are more descriptive or meaningful to your 
  5555. application, you can do so as follows: 
  5556.  
  5557.    1. Move the mouse pointer over the part whose name you want to change. 
  5558.  
  5559.    2. Click mouse button 2 to display the pop-up menu for the part. 
  5560.  
  5561.    3. Select Change Name. 
  5562.  
  5563.       A Name Change Request window is displayed. The following figure shows a 
  5564.       Name Change Request window for a push button part. 
  5565.  
  5566.    4. Type a new name in the entry field. 
  5567.  
  5568.    5. Select OK. 
  5569.  
  5570.       Visual Builder changes the name of the part to the name that you typed in 
  5571.       the entry field. 
  5572.  
  5573.  You can also change a part's name by opening the part's settings notebook and 
  5574.  changing the name in the Subpart name field. 
  5575.  
  5576.  
  5577. ΓòÉΓòÉΓòÉ 9.3.5. Arranging Parts ΓòÉΓòÉΓòÉ
  5578.  
  5579. You can arrange parts on the free-form surface in a number of different ways. 
  5580. The following sections explain each of those ways. 
  5581.  
  5582.      Moving parts 
  5583.  
  5584.      Positioning parts on the grid 
  5585.  
  5586.      Specifying grid spacing 
  5587.  
  5588.      Showing and hiding the grid 
  5589.  
  5590.      Sizing parts 
  5591.  
  5592.      Matching part sizes 
  5593.  
  5594.      Aligning parts 
  5595.  
  5596.      Spacing subparts within Composers parts 
  5597.  
  5598.  Personal notes: 
  5599.  
  5600.  
  5601. ΓòÉΓòÉΓòÉ 9.3.5.1. Moving Parts ΓòÉΓòÉΓòÉ
  5602.  
  5603. To move a part, move the mouse pointer over the part, hold down mouse button 2, 
  5604. and move the mouse pointer to drag the part to the new position. 
  5605.  
  5606.            You can move several parts at once by first selecting all the parts 
  5607.            you want to move and then dragging one of the parts as described. 
  5608.            All of the selected parts will move together, maintaining their 
  5609.            position relative to each other. 
  5610.  
  5611.  
  5612. ΓòÉΓòÉΓòÉ 9.3.5.2. Positioning Parts on the Grid ΓòÉΓòÉΓòÉ
  5613.  
  5614. The free-form surface has a grid that you can use to position parts. In 
  5615. addition, parts that can contain other parts (any Composers part, such as a 
  5616. frame window) have a grid associated with them. You can use this grid to align 
  5617. and evenly space subparts that Composers parts contain. 
  5618.  
  5619. To position the top-left corner of parts to the nearest grid coordinate, do the 
  5620. following: 
  5621.  
  5622.    1. Select all the parts you want to position to the grid. 
  5623.  
  5624.       Note:  If the parts you select are subparts, they are positioned to the 
  5625.              grid set up inside the Composers part, not the grid for the 
  5626.              free-form surface. 
  5627.  
  5628.    2. Select , the Snap To Grid tool. 
  5629.  
  5630.            You can automatically position a part to the nearest grid coordinate 
  5631.            when it is added to the free-form surface or a Composers part by 
  5632.            selecting Snap On Drop from the Options pull-down menu. 
  5633.  
  5634.  
  5635. ΓòÉΓòÉΓòÉ 9.3.5.3. Specifying Grid Spacing ΓòÉΓòÉΓòÉ
  5636.  
  5637. To specify the grid spacing, do the following: 
  5638.  
  5639.    1. From the pop-up menu of a Composers part or the free-form surface, select 
  5640.       Set Grid Spacing. 
  5641.  
  5642.    2. Specify the horizontal and vertical distance between the lines of the 
  5643.       grid in pixels. 
  5644.  
  5645.  
  5646. ΓòÉΓòÉΓòÉ 9.3.5.4. Showing and Hiding the Grid ΓòÉΓòÉΓòÉ
  5647.  
  5648. To toggle between showing and hiding the grid for the free-form surface, do one 
  5649. of the following: 
  5650.  
  5651.      If no parts are selected, you can select , the Toggle Grid tool to toggle 
  5652.       the grid for the free-form surface. 
  5653.  
  5654.      If a Composers part is selected, selecting the Toggle Grid tool toggles 
  5655.       the grid for the Composers part instead of the free-form surface. 
  5656.  
  5657.  Toggling between showing and hiding the grid for a Composers part 
  5658.  
  5659.  To toggle between showing and hiding the grid for a Composers part, do one of 
  5660.  the following: 
  5661.  
  5662.      Select the Composers part and the select , the Toggle Grid tool. 
  5663.  
  5664.      From the Composers part's pop-up menu, select Toggle Grid. 
  5665.  
  5666.  
  5667. ΓòÉΓòÉΓòÉ 9.3.5.5. Sizing Parts ΓòÉΓòÉΓòÉ
  5668.  
  5669. To change the size of a part, select it and use mouse button 1 to drag one of 
  5670. the selection handles to the new position. An outline of the part is displayed 
  5671. under the mouse pointer to show you the new size of the part. 
  5672.  
  5673.            You can size several parts at once by first selecting all the parts 
  5674.            you want to size. 
  5675.  
  5676.            To size a part in only one direction, press and hold the Shift key 
  5677.            while using mouse button 1 to size the part. Holding down the Shift 
  5678.            key prevents one dimension of the part from changing while you 
  5679.            resize the other dimension. For example, to change the width of a 
  5680.            part but prevent its height from changing, hold down the Shift key 
  5681.            while changing the width. 
  5682.  
  5683.            You can also size a part to the grid coordinates by selecting Snap 
  5684.            On Size from the Options pull-down menu. 
  5685.  
  5686.  
  5687. ΓòÉΓòÉΓòÉ 9.3.5.6. Matching Part Sizes ΓòÉΓòÉΓòÉ
  5688.  
  5689. To size parts to the same width or height of another part, do the following: 
  5690.  
  5691.    1. Select all the parts you want to size, making sure the last part you 
  5692.       select is the part whose size you want the others to match. 
  5693.  
  5694.    2. Select one of the following sizing tools from the tool bar: 
  5695.  
  5696.         Match Width                        Match Height 
  5697.  
  5698.       The size of all the parts you selected, with the exception of the last 
  5699.       part, changes to match the size of the last part selected. 
  5700.  
  5701.  
  5702. ΓòÉΓòÉΓòÉ 9.3.5.7. Aligning Parts ΓòÉΓòÉΓòÉ
  5703.  
  5704. To align parts to the same position as another part, do the following: 
  5705.  
  5706.    1. Select all the parts you want to align, and then select the part you want 
  5707.       the others to be aligned with. 
  5708.  
  5709.    2. Select one of the following alignment tools from the tool bar: 
  5710.  
  5711.         Align Left                         Align Top 
  5712.         Align Center                       Align Middle 
  5713.         Align Right                        Align Bottom 
  5714.  
  5715.  
  5716. ΓòÉΓòÉΓòÉ 9.3.5.8. Spacing Subparts Within Composers Parts ΓòÉΓòÉΓòÉ
  5717.  
  5718. To evenly space subparts within their Composers part, do the following: 
  5719.  
  5720.    1. Select all the parts you want to evenly space. 
  5721.  
  5722.    2. Select one the following spacing tools from the tool bar: 
  5723.  
  5724.         Distribute Horizontally 
  5725.         Distribute Vertically 
  5726.  
  5727.  
  5728. ΓòÉΓòÉΓòÉ 9.3.5.9. Spacing Parts Within a Bounding Box ΓòÉΓòÉΓòÉ
  5729.  
  5730. To evenly space parts within the unseen bounding box that contains the selected 
  5731. parts, do the following: 
  5732.  
  5733.    1. Select all the parts you want to evenly space. You must select a minimum 
  5734.       of three parts. 
  5735.  
  5736.    2. From the pop-up menu of one of the selected parts, select 
  5737.       LayoutDistribute, and then one of the following: 
  5738.  
  5739.       Horizontally In Bounding Box Evenly distributes the selected parts within 
  5740.              the region bounded by the leftmost edge and rightmost edge of the 
  5741.              selected parts. 
  5742.  
  5743.       Vertically In Bounding Box Evenly distributes the selected parts within 
  5744.              the region bounded by the topmost edge and bottommost edge of the 
  5745.              selected parts. 
  5746.  
  5747.  For more information on tool bar tools, see Tool Bar. 
  5748.  
  5749.  
  5750. ΓòÉΓòÉΓòÉ 9.3.6. Changing Settings for a Part ΓòÉΓòÉΓòÉ
  5751.  
  5752. The settings notebook of a part provides a way to display and set attributes 
  5753. and options for the part. 
  5754.  
  5755. Opening the settings notebook for one part 
  5756.  
  5757. To open the settings notebook for a part, move the mouse pointer over the part 
  5758. and do one of the following: 
  5759.  
  5760.      Double-click mouse button 1. 
  5761.  
  5762.      Click mouse button 2 and select Open settings from the part's pop-up 
  5763.       menu. 
  5764.  
  5765.  Opening settings notebooks for multiple parts 
  5766.  
  5767.  You can open the settings notebooks for multiple parts by doing the following: 
  5768.  
  5769.    1. Select the parts whose settings you want to change. 
  5770.    2. Move the mouse pointer over one of the selected parts. 
  5771.    3. Click mouse button 2. 
  5772.    4. Select Open settings from the pop-up menu. 
  5773.  
  5774.       Visual Builder opens a settings notebook for each of the selected parts. 
  5775.  
  5776.  Navigating through a settings notebook 
  5777.  
  5778.  You can navigate through the notebook pages in the following ways: 
  5779.  
  5780.      To turn the pages of a notebook, use the small left- and right-arrow push 
  5781.       buttons at the bottom right corner of each page. 
  5782.  
  5783.      To move to a different settings category, select one of the tabs to the 
  5784.       right of the pages. 
  5785.  
  5786.       Note:  When a category has more than one page, the page number and total 
  5787.              number of pages within the category are displayed at the bottom of 
  5788.              the page. 
  5789.  
  5790.      If all the category tabs cannot fit below the pages of the notebook, 
  5791.       small double left- and right-arrow push buttons are displayed to the left 
  5792.       and right of the category tabs. Use these buttons to move through the 
  5793.       available category tabs. 
  5794.  
  5795.  About the settings pages 
  5796.  
  5797.  The following list contains a description of each of the pages a settings 
  5798.  notebook may contain: 
  5799.  
  5800.  General 
  5801.    A page for setting the name of the part, any static text that may appear on 
  5802.    the part, and other part-specific settings. For example, the General page 
  5803.    for an IMenuItem* part contains a group box for setting the keyboard 
  5804.    accelerator for the menu item. Refer to the Visual Builder Parts Reference 
  5805.    for descriptions of specific settings for parts. 
  5806.  
  5807.  Control 
  5808.    A page that allows you to specify information for the part in its role as an 
  5809.    OS/2 control, such as fly over text, a window ID, and whether the part is 
  5810.    available for the user to select. 
  5811.  
  5812.  Styles 
  5813.    A page that provides style settings from the IBM Open Class Library. The 
  5814.    style settings generally correspond to those of the class on which the part 
  5815.    is based. Refer to the IBM Open Class Library Reference for descriptions of 
  5816.    the style settings. 
  5817.  
  5818.    Selecting the defaultStyle check box means you want Visual Builder to use 
  5819.    the default style provided for the class by the IBM Open Class Library. You 
  5820.    can select this check box and then modify the default settings by selecting 
  5821.    the On and Off radio buttons on the page beside each style setting. Doing 
  5822.    this means you want Visual Builder to use the default style except for any 
  5823.    exceptions that you have made by turning style settings on or off. 
  5824.  
  5825.    The Default column shows which style settings are the defaults as specified 
  5826.    for the class in the IBM Open Class Library. Visual Builder has not turned 
  5827.    these style bits on or off. They are set to whatever the default settings 
  5828.    are supposed to be. 
  5829.  
  5830.                   If you deselect the defaultStyle check box and also turn off 
  5831.                   one or more of the required settings, you will get errors 
  5832.                   when you generate and compile your code. However, selecting 
  5833.                   this check box ensures that no required settings will be 
  5834.                   omitted. Therefore, we recommend that you keep the 
  5835.                   defaultStyle check box selected so that you always have the 
  5836.                   required settings. 
  5837.  
  5838.                   Selecting one style setting does not cause another to be 
  5839.                   automatically deselected. For example, selecting minor tabs 
  5840.                   for a notebook page does not cause major tabs to be 
  5841.                   deselected. In this case, the major tab style setting 
  5842.                   overrides the minor tab setting. Be sure to deselect the 
  5843.                   styles that you do not want to use. 
  5844.  
  5845.  Handlers 
  5846.    A page that allows you to list handlers that you want to attach to this 
  5847.    part. You can use handlers instead of event connections, such as 
  5848.    event-to-action connections. List the handlers in the order in which they 
  5849.    should be called. 
  5850.  
  5851.    Adding a handler 
  5852.  
  5853.    To add a handler, do the following: 
  5854.  
  5855.      1. Enter the name of the handler class in the Handler Name field, along 
  5856.         with the list of parameters that you want to send to the handler's 
  5857.         constructor. If you use any part names as parameters, be sure to use 
  5858.         the default name that Visual Builder has assigned unless you have 
  5859.         changed the name. Also, put a lower case "i" before those parameters 
  5860.         because Visual Builder prefixes the part name with an "i" when it 
  5861.         generates the code files. For example, if you are using the first entry 
  5862.         field that you placed in a frame window as a parameter and have not 
  5863.         changed the default name that Visual Builder assigns, the parameter 
  5864.         name would be iEntryField1. 
  5865.  
  5866.      2. If the Handler List list box contains other handlers, select the 
  5867.         handler that you want your new handler to either precede or follow. 
  5868.  
  5869.      3. Select either the Add after or Add before push button. 
  5870.  
  5871.         If you did not import the handler class from a .vbe file, Visual 
  5872.         Builder displays a message saying that the name you entered is not a 
  5873.         valid part and asks if you want to continue. 
  5874.  
  5875.      4. Select the Yes push button. 
  5876.  
  5877.         The message disappears and the handler is added either after or before 
  5878.         the handler that is selected in the Handler List list box, depending on 
  5879.         which push button you select. 
  5880.  
  5881.      5. Select the OK push button to save the new handler in the handler list 
  5882.         and close the settings notebook. 
  5883.  
  5884.                   We recommend that you put your handler class declaration and 
  5885.                   code in separate user .hpv and .cpv files rather than 
  5886.                   modifying the files that Visual Builder generates. This way, 
  5887.                   if you need to regenerate the files, you do not have to 
  5888.                   recreate your handler code. 
  5889.  
  5890.                   Be sure to include the names of the files that contain the 
  5891.                   handler code in the User .hpv file and User .cpv file fields 
  5892.                   in the Class Editor. 
  5893.  
  5894.                   For information about implementing handlers, refer to the IBM 
  5895.                   Open Class Library User's Guide and the IBM Open Class 
  5896.                   Library Reference. 
  5897.  
  5898.    Moving a handler 
  5899.  
  5900.    To move a handler to a different position in the list, do the following: 
  5901.  
  5902.      1. Select the handler that you want to move. 
  5903.  
  5904.      2. Select the Move push button. 
  5905.  
  5906.      3. In the dialog that is displayed, select the handler that is to precede 
  5907.         or follow the handler being moved. 
  5908.  
  5909.      4. Select the Move after push button to move the handler after the 
  5910.         selected handler, or select the Move before push button to move the 
  5911.         handler before the selected handler. 
  5912.  
  5913.         The dialog disappears and the handler is moved. 
  5914.  
  5915.    Removing a handler 
  5916.  
  5917.    To remove a handler from the list, do the following: 
  5918.  
  5919.      1. Select the handler you want to remove from the list. 
  5920.  
  5921.      2. Select the Remove push button. 
  5922.  
  5923.         The selected handler is removed from the list. 
  5924.  
  5925.  Color 
  5926.    A page that allows you to change the color of the part. 
  5927.  
  5928.    Changing the color 
  5929.  
  5930.    To change the color, do the following: 
  5931.  
  5932.      1. In the Color Area group box, select the area, such as foreground or 
  5933.         background, whose color you want to change. 
  5934.  
  5935.      2. Do one of the following: 
  5936.  
  5937.             If you want to specify red-green-blue values, select the RGB check 
  5938.              box and specify values in the fields in the RGB Values group box. 
  5939.  
  5940.             If you want to select a color by its name, deselect the RGB check 
  5941.              box and select a color from the Colors drop-down list box. 
  5942.  
  5943.      3. Select either the Apply push button to see how this color looks for 
  5944.         your part without saving the change or the OK push button to close the 
  5945.         settings notebook and save the color change. 
  5946.  
  5947.  Size/Position 
  5948.    A page that allows you to specify the size and position of a part. 
  5949.  
  5950.    Specifying the size and position of a part 
  5951.  
  5952.    To specify the size and position of a part, do the following: 
  5953.  
  5954.      1. In the x and y fields, specify the initial x/y coordinates for the 
  5955.         part. These coordinates determine the position of the part's upper left 
  5956.         corner. 
  5957.  
  5958.      2. In the width and height fields, specify the number of pixels for the 
  5959.         width and height of the part. 
  5960.  
  5961.      3. Optionally, you can also specify the smallest size the part can have by 
  5962.         using the Minimum Size group box to do either of the following: 
  5963.  
  5964.             If you want the minimum size to be calculated for you, select the 
  5965.              Calculate at execution time radio button. 
  5966.  
  5967.             If you want to specify the minimum size for the part, select the 
  5968.              Set value here radio button and then enter the width and height in 
  5969.              pixels in the corresponding fields. 
  5970.  
  5971.  Font 
  5972.    A page that allows you to specify the font that is to be used for the part. 
  5973.  
  5974.    Changing the font for a part 
  5975.  
  5976.    To change the font for a part, do one of the following: 
  5977.  
  5978.        If you know the name and size of the font you want to use, you can 
  5979.         enter them in their respective fields. 
  5980.  
  5981.        If you do not know the name and size of the font you want to use or if 
  5982.         you want to change the style or emphasis, select the Edit push button. 
  5983.         Visual Builder displays a standard font dialog on which you can select 
  5984.         the name, size, style, and emphasis you want to use for the part's 
  5985.         font. 
  5986.  
  5987.  Using code strings to supply initial field values 
  5988.  
  5989.  Many settings pages provide fields in which you can specify initial values for 
  5990.  part settings. For example, the General page of the IEntryField* settings 
  5991.  notebook contains a Text field and a Limit field. In the Text field, you can 
  5992.  enter a text string that you want Visual Builder to initially display in the 
  5993.  entry field. The Limit field contains a default value of 32, which represents 
  5994.  the maximum number of characters a user can type in the entry field, and you 
  5995.  can change this number. 
  5996.  
  5997.  To facilitate National Language Support (NLS) translation and code changes in 
  5998.  providing settings values, such as the ones just described, you can enter a 
  5999.  code string to provide those values. You must precede the code string with a 
  6000.  number sign (#). If the first character of your code string is a #, be sure to 
  6001.  enter two #s-the first one to signify that a code string follows and the 
  6002.  second one to begin your code string. 
  6003.  
  6004.  For example, suppose you want the initial text in an entry field to be Enter a 
  6005.  name here. Further, suppose that you want the limit for this entry field to be 
  6006.  18 characters. In a user header file (.hpv or .h), you could insert the 
  6007.  following #define statements: 
  6008.  
  6009.   #define NAME_PROMPT  "Enter a name here"
  6010.   #define NAME_LENGTH 18
  6011.  
  6012.            Be sure to enter the name of the file that contains these #define 
  6013.            statements in the Required include files field in the Class Editor. 
  6014.            Otherwise, this file is not included when you generate the code for 
  6015.            this part. 
  6016.  
  6017.  Then, on the General page of the IEntryField* settings notebook you could 
  6018.  enter the following in the Text and Limit fields, respectively: 
  6019.  
  6020.   #NAME_PROMPT
  6021.   #NAME_LENGTH
  6022.  
  6023.  By doing this, the values that you defined for NAME_PROMPT and NAME_LENGTH are 
  6024.  used when you generate the source code for the part being edited. 
  6025.  
  6026.  For an example that uses a code string to specify an icon to represent items 
  6027.  in a container, see the subsection titled "Specifying the container type and 
  6028.  layout" in Adding Container Parts. 
  6029.  
  6030.  Activating settings changes 
  6031.  
  6032.  After you make changes to the settings, you can activate them in the following 
  6033.  ways: 
  6034.  
  6035.      Select the OK push button to immediately activate and save the settings 
  6036.       changes you have made, and close the settings notebook. 
  6037.  
  6038.      Select the Apply push button to apply the settings changes you have made 
  6039.       and keep the settings notebook open. 
  6040.  
  6041.       This allows you to see whether you need to modify any of the changes you 
  6042.       have made. The changes remain applied until you change them again. 
  6043.  
  6044.  Select the Cancel push button to remove the settings notebook. If you made 
  6045.  changes and selected the Apply push button, the changes are saved. 
  6046.  
  6047.  Select the Help push button for more help with using the settings notebook. 
  6048.  
  6049.  For information about the settings of a particular part, refer to the settings 
  6050.  section of the part in the Visual Builder Parts Reference. 
  6051.  
  6052.  
  6053. ΓòÉΓòÉΓòÉ 9.3.7. Using the Generic Settings Notebook ΓòÉΓòÉΓòÉ
  6054.  
  6055. When you create a part, Visual Builder provides a settings notebook for that 
  6056. part. The settings notebook for your part has one page, which contains the 
  6057. following types of settings: 
  6058.  
  6059.      An entry field for each attribute that has a set member function 
  6060.  
  6061.       The #define statements are supported for the generic settings notebook, 
  6062.       just as they are for a regular settings notebook. See Changing Settings 
  6063.       for a Part for information about using #define statements in a settings 
  6064.       notebook. 
  6065.  
  6066.      A check box for each Boolean attribute 
  6067.  
  6068.  If your part has no attributes, the page displays a message saying that there 
  6069.  are no values to set. 
  6070.  
  6071.  To view the settings notebook for your part, do one of the following: 
  6072.  
  6073.      To set values for an instance of your part that you are using in a 
  6074.       composite part, do the following: 
  6075.  
  6076.         1. Place the part in the Composition Editor. 
  6077.  
  6078.         2. Move the mouse pointer over the part and click mouse button 2. 
  6079.  
  6080.         3. Select Open settings from the pop-up menu. 
  6081.  
  6082.            Visual Builder displays the settings notebook for the part. 
  6083.  
  6084.      To set attribute values for your part that will be available each time 
  6085.       your part is used, do the following: 
  6086.  
  6087.         1. Open the part. 
  6088.  
  6089.         2. If the part is a nonvisual or class interface part, switch to the 
  6090.            Composition Editor. You will already be in the Composition Editor if 
  6091.            your part is a visual part. 
  6092.  
  6093.         3. Move the mouse pointer over the free-form surface and click mouse 
  6094.            button 2. 
  6095.  
  6096.         4. Select Open settings from the pop-up menu. 
  6097.  
  6098.                           A quicker way to open the generic settings notebook 
  6099.                           is to double-click on the part. 
  6100.  
  6101.            Visual Builder displays the settings notebook for the part. 
  6102.  
  6103.  The following figure shows the generic settings notebook for the OAContract 
  6104.  part: 
  6105.  
  6106.  The notebook page includes settings for attributes that your part inherits 
  6107.  from other parts in addition to attributes for the part you created. For 
  6108.  example, the enabledForNotification check box is present because the 
  6109.  OAContract part inherits this Boolean attribute from IStandardNotifier. 
  6110.  
  6111.  
  6112. ΓòÉΓòÉΓòÉ 9.3.8. Setting the Tabbing Order ΓòÉΓòÉΓòÉ
  6113.  
  6114. The tabbing order specifies the order that the input focus moves from part to 
  6115. part as the user presses the Tab key. The tabbing order can further specify the 
  6116. order that the input focus moves to parts within a tab group as the user 
  6117. presses the arrow keys. 
  6118.  
  6119. The tabbing order can only be set or displayed for parts that are placed within 
  6120. a Composers part. For example, if you place a row of push buttons in a frame 
  6121. window, you can set the tabbing order for the push buttons. 
  6122.  
  6123. The initial order of the parts in the tabbing order list is determined by the 
  6124. order in which you place the parts on the Composers part. Also, the first part 
  6125. in the list is the part that receives the initial input focus. For example, if 
  6126. the first part in the list is a push button, that push button receives the 
  6127. initial input focus when the application starts. 
  6128.  
  6129. Displaying the tabbing order list 
  6130.  
  6131. To display the tabbing order list, do the following: 
  6132.  
  6133.    1. Move the mouse pointer to the Composers part whose tab order you want to 
  6134.       change. 
  6135.  
  6136.    2. Click mouse button 2. 
  6137.  
  6138.       Visual Builder displays the pop-up menu for the Composers part. 
  6139.  
  6140.    3. Select Tabbing And Depth Order. 
  6141.  
  6142.       A list of the current tabbing order is displayed. The following figure 
  6143.       shows the tabbing order list for a canvas part that contains three push 
  6144.       buttons. 
  6145.  
  6146.  When the tabbing order is displayed, you can do the following: 
  6147.  
  6148.      Change the positions of parts in the tabbing order list. 
  6149.  
  6150.      Set groups and tab stops. 
  6151.  
  6152.      Perform operations on parts in the tabbing order list. 
  6153.  
  6154.  
  6155. ΓòÉΓòÉΓòÉ 9.3.8.1. Changing the Positions of Parts in the Tabbing Order List ΓòÉΓòÉΓòÉ
  6156.  
  6157. Since the order in which parts are placed on a Composers part determines the 
  6158. tabbing order, you will probably need to change the order of the list as you 
  6159. add or rearrange parts. For example, suppose you decide to rearrange the three 
  6160. push buttons from the example in the preceding section so that PushButton3 is 
  6161. between PushButton1 and PushButton2, as shown in the following figure: 
  6162.  
  6163. As shown in the following figure, the tabbing order of these push buttons is 
  6164. PushButton1, PushButton2, PushButton3, even though PushButton3 is now between 
  6165. PushButton1 and PushButton2. 
  6166.  
  6167. By moving PushButton3 between PushButton1 and PushButton2 in the tabbing order 
  6168. list, you can change the order so that you can cursor directly from PushButton1 
  6169. to PushButton3 instead of jumping over to PushButton 2 first. The changed 
  6170. tabbing order list is shown in the following figure: 
  6171.  
  6172. To change the position of a part within the tabbing order list, do the 
  6173. following: 
  6174.  
  6175.    1. Move the mouse pointer to the part whose position you want to change. 
  6176.  
  6177.    2. Press and hold mouse button 2. 
  6178.  
  6179.    3. Drag the part to a new position in the list. 
  6180.  
  6181.    4. Release mouse button 2. 
  6182.  
  6183.            You can change the position of several parts within the tabbing 
  6184.            order at the same time by first selecting all the parts you want to 
  6185.            move. You select multiple parts by holding down the Ctrl key and 
  6186.            clicking on the parts with mouse button 1. 
  6187.  
  6188.            You cannot move a subpart to a new Composers part by changing the 
  6189.            tabbing order. You must do this in the Composition Editor. 
  6190.  
  6191.  
  6192. ΓòÉΓòÉΓòÉ 9.3.8.2. Setting Groups and Tab Stops ΓòÉΓòÉΓòÉ
  6193.  
  6194. If you want the user to be able to move the input focus to a part using the Tab 
  6195. and Backtab keys, select the Tab stop check box to the left of the part in the 
  6196. tabbing order list. 
  6197.  
  6198. If you want the user to be able to move the input focus to a part with the 
  6199. keyboard arrow keys, select the Group check box to the left of the first part 
  6200. in the group. All other parts listed below the part that has Group selected are 
  6201. included in the group. 
  6202.  
  6203. To start another group, select the Group check box for the part that you want 
  6204. to be the first part in that group. If a part has both Group and Tab stop 
  6205. selected, a user can tab to the first part in the group and then use the arrow 
  6206. keys to move to the other parts in the group. 
  6207.  
  6208. Special considerations for radio buttons and entry fields 
  6209.  
  6210. When you put radio buttons in groups, they become mutually exclusive within 
  6211. their group. For example, suppose you have four consecutive radio buttons in 
  6212. your list and you select the Group check box for RadioButton1 and RadioButton3. 
  6213. In this case, RadioButton1 and RadioButton2 become mutually exclusive in their 
  6214. group, with RadioButton3 and RadioButton4 mutually exclusive in their group, as 
  6215. well. The following figure shows an example. Tab stops are also set so a user 
  6216. can tab between the two groups. 
  6217.  
  6218. Consider setting a tab stop on each entry field that a user can type in to 
  6219. allow the user to move the input focus from one entry field to another. 
  6220. Read-only entry fields do not need a tab stop and arrow keys only move the 
  6221. cursor within an entry field; only the Tab key, the Backtab key, and the mouse 
  6222. can change the input focus from one entry field to another. 
  6223.  
  6224. Style guidelines for setting groups and tab stops 
  6225.  
  6226. The following are some typical style guidelines for setting groups and tab 
  6227. stops: 
  6228.  
  6229.      The position of the parts in the tabbing order should be the same as the 
  6230.       order in which they are displayed in the window, from left to right and 
  6231.       then top to bottom. 
  6232.  
  6233.      Parts that are not in groups, such as entry fields and list boxes, should 
  6234.       have Group and Tab stop selected. 
  6235.  
  6236.      Each group of related parts, such as check boxes and radio buttons, 
  6237.       should be put within an outline box or a group box. 
  6238.  
  6239.       If there is only one group of related parts, such as push buttons, you do 
  6240.       not need to put them within an outline box or group box. Select only Tab 
  6241.       stop for these parts. 
  6242.  
  6243.      Parts that should not receive input focus, such as static text parts, 
  6244.       should not have either Group or Tab stop selected. 
  6245.  
  6246.  
  6247. ΓòÉΓòÉΓòÉ 9.3.8.3. Performing Operations on Parts in the Tabbing Order List ΓòÉΓòÉΓòÉ
  6248.  
  6249. You can perform many of the same operations on parts listed in the tabbing 
  6250. order that you can perform on the parts on the free-form surface. Visual 
  6251. Builder provides pop-up menus that contain the allowable operations for each 
  6252. part in the list. Examples of typical operations are opening a part's settings, 
  6253. editing a part, and browsing a part's features. 
  6254.  
  6255. To perform an operation on a part in the tabbing order list, do the following: 
  6256.  
  6257.    1. Move the mouse pointer over the part. 
  6258.  
  6259.    2. Click mouse button 2. 
  6260.  
  6261.       Visual Builder displays the pop-up menu for the part. 
  6262.  
  6263.    3. Select the operation you want to perform. 
  6264.  
  6265.  
  6266. ΓòÉΓòÉΓòÉ 9.3.9. Editing Parts Placed on the Free-form Surface ΓòÉΓòÉΓòÉ
  6267.  
  6268. Suppose you create a composite part, add it to another composite part that you 
  6269. are creating, and then realize that you need to change the first composite 
  6270. part. With Visual Builder you do not have to start over. It provides a way for 
  6271. you to edit the part that needs to be changed right from the free-form surface. 
  6272.  
  6273. The only exception is the base parts that Visual Builder provides. Visual 
  6274. Builder does not allow you to modify these parts. This includes all of the 
  6275. parts that the vbbase.vbb file contains. If you place one of these base parts 
  6276. on either a Composers part or the free-form surface, you can modify the subpart 
  6277. by doing any of the following: 
  6278.  
  6279.      If you want to add an action to the subpart, consider connecting to a 
  6280.       member function or custom logic that belongs to the composite part, 
  6281.       instead. Write a member function or provide custom logic if you need to 
  6282.       perform an action of limited usefulness, that is, one that you do not 
  6283.       anticipate using very often, and that you do not want derived parts to 
  6284.       inherit. For information about using member functions and custom logic in 
  6285.       connections, see the following: 
  6286.  
  6287.         -  Adding an Event-to-Member Function Connection 
  6288.  
  6289.         -  Connecting Features to Custom Logic 
  6290.  
  6291.      If you want to add a new feature that you plan to use often, create a new 
  6292.       part that is derived from the base part. For example, to add a new 
  6293.       feature to an IEntryField* part, create a new visual part whose base part 
  6294.       is the IEntryField* part and replace the IEntryField* part that you were 
  6295.       using with your new part. You can then add as many new features to your 
  6296.       new part as you need. 
  6297.  
  6298.      If you derive a new part from a base part, you also have the option of 
  6299.       adding handlers to the new part. One reason for adding handlers is that 
  6300.       you might want to monitor Presentation Manager messages to see when 
  6301.       certain events occur and then notify observers. Another reason is that 
  6302.       you might want to add special behavior to your part. You can add handlers 
  6303.       to parts that Visual Builder provides on the Handlers page of the part's 
  6304.       settings notebook. For more information about handlers, refer to the IBM 
  6305.       Open Class Library User's Guide. 
  6306.  
  6307.  If you need to edit a part that was added to the part you are currently 
  6308.  editing, do the following: 
  6309.  
  6310.    1. If you have not already done so, load the .vbb file that contains the 
  6311.       part you want to edit. 
  6312.  
  6313.    2. Move the mouse pointer over the part you want to edit. 
  6314.  
  6315.    3. Click mouse button 2. 
  6316.  
  6317.       The part's pop-up menu appears. 
  6318.  
  6319.    4. Select Edit Part. 
  6320.  
  6321.       Visual Builder displays the appropriate editor for the part, as follows: 
  6322.  
  6323.           If you are editing a visual part, Visual Builder displays the 
  6324.            Composition Editor 
  6325.  
  6326.           If you are editing a nonvisual or class interface part, Visual 
  6327.            Builder displays the Part Interface Editor. 
  6328.  
  6329.    5. Edit the part. 
  6330.  
  6331.                      If you want to promote any of the features of the parts 
  6332.                      used to create the composite part you are editing, doing 
  6333.                      so now keeps you from having to edit this part again 
  6334.                      later. See Promoting a Part's Features if you need more 
  6335.                      information about doing this. 
  6336.  
  6337.    6. Select FileSave to save the part. 
  6338.  
  6339.    7. Close the editor by doing one of the following: 
  6340.  
  6341.           Double-click on the system menu icon. 
  6342.           Select FileExit. 
  6343.  
  6344.       The editor you are using disappears and you are returned to the 
  6345.       Composition Editor you were using previously. However, Visual Builder has 
  6346.       not applied the changes you made to the part you just edited, so those 
  6347.       changes are not visible yet. 
  6348.  
  6349.    8. Select FileSave to save the original part. 
  6350.  
  6351.    9. Close the Composition Editor for the original part that you were editing, 
  6352.       as described above. 
  6353.  
  6354.   10. Reopen the original part you were editing by double-clicking on the 
  6355.       part's name in the Visual Builder window. 
  6356.  
  6357.       You should now be able to see the changes you made to the part that you 
  6358.       edited. 
  6359.  
  6360.  
  6361. ΓòÉΓòÉΓòÉ 9.3.10. Promoting a Part's Features ΓòÉΓòÉΓòÉ
  6362.  
  6363. In Guidelines for Placing Parts on the Free-form Surface, we explained the 
  6364. relationship between parts in the Composers category and parts that are placed 
  6365. on top of them, called subparts. When you create a visual part that consists of 
  6366. a part from the Composers category that contains subparts, you can then place 
  6367. that visual part on top of another part from the Composers category. However, 
  6368. if you do this, the features of the subparts in the visual part that you 
  6369. created are not automatically available. You must promote these features to use 
  6370. them in connections. 
  6371.  
  6372. For example, suppose you create a visual part called Buttons whose base class 
  6373. is ICanvas*. This part consists of a canvas part that contains three push 
  6374. button parts. Here is what the Buttons part looks like: 
  6375.  
  6376. Suppose you create another visual part whose base class is IFrameWindow* and 
  6377. then add the Buttons part to the frame window part. Here is what the frame 
  6378. window part with the Buttons part looks like: 
  6379.  
  6380. Now, suppose that you want to connect the buttonClickEvent feature of the 
  6381. Cancel push button to the close feature of the Frame Window so that the window 
  6382. closes whenever the Cancel push button is selected. However, features of the 
  6383. push button parts are not automatically available for connections because the 
  6384. push buttons are subparts of the canvas. 
  6385.  
  6386. When you use a part such as Buttons as a subpart, only the features of the 
  6387. Buttons part's ancestor parts (ICanvas, IWindow, and so forth) are available in 
  6388. the connections menu for the Buttons part. To use the features of the push 
  6389. button parts, you must promote them to the Buttons part. You can do this either 
  6390. before or after you add the Buttons part to the frame window. 
  6391.  
  6392. The following steps show you how to promote a part's features from the 
  6393. Composition Editor. 
  6394.  
  6395.            To promote features of several subparts, we recommend using Promote 
  6396.            page of the Part Interface Editor. For information about promoting a 
  6397.            part's features from the Part Interface Editor, see The Promote 
  6398.            Page. 
  6399.  
  6400.    1. If you have not already done so, load the .vbb file that contains the 
  6401.       composite part whose features you want to promote. 
  6402.  
  6403.    2. If you have not already done so, open the composite part or edit the 
  6404.       subpart, whichever is necessary. 
  6405.  
  6406.       Visual Builder displays the Composition Editor with the part that you are 
  6407.       opening or the subpart that you are editing on the free-form surface. 
  6408.  
  6409.    3. Move the mouse pointer over a part whose features you want to promote. 
  6410.  
  6411.    4. Click mouse button 2 to display the part's pop-up menu. 
  6412.  
  6413.    5. Select Promote Part Feature. 
  6414.  
  6415.       Visual Builder displays a window with three columns of features:  one for 
  6416.       attributes, one for events, and one for actions. The following figure 
  6417.       shows the window that is displayed for a push button part. 
  6418.  
  6419.    6. Select a feature. 
  6420.  
  6421.       The name of the feature you selected is displayed in the Promote feature 
  6422.       name entry field prefixed with the name of the part. This is done so that 
  6423.       when you make the connection, you can tell which push button part the 
  6424.       feature belongs to. For example, if you selected the buttonClickEvent 
  6425.       feature for the PushButton2 part, the feature name displayed in the entry 
  6426.       field would be pushButton2ButtonClickEvent, as shown in the following 
  6427.       figure. This is how the feature name will appear in the connections menu 
  6428.       unless you change it before performing the next step. 
  6429.  
  6430.    7. Select the Promote push button. 
  6431.  
  6432.       The feature name is added to the Previously promoted list box, as shown 
  6433.       inthe following figure: 
  6434.  
  6435.    8. Repeat the previous two steps until you have promoted all of the features 
  6436.       you need to make the necessary connections. 
  6437.  
  6438.    9. Close the window for promoting features. 
  6439.  
  6440.   10. Select FileSave to save the features you just promoted. 
  6441.  
  6442.   11. Close the Composition Editor. 
  6443.  
  6444.       You can now use the feature or features that you promoted to make 
  6445.       connections. 
  6446.  
  6447.  
  6448. ΓòÉΓòÉΓòÉ 9.3.11. Tearing Off an Attribute ΓòÉΓòÉΓòÉ
  6449.  
  6450. Select Tear-Off Attribute from a part's pop-up menu to work with an attribute 
  6451. as if it were a standalone part. The torn-off attribute is not actually a 
  6452. separate part but a variable that either represents the attribute itself or 
  6453. points to it. 
  6454.  
  6455. When you select Tear-Off Attribute, Visual Builder displays the list of 
  6456. attributes for the part that you are tearing from. After you select an 
  6457. attribute from the list, you can drop the torn-off attribute on the free-form 
  6458. surface. Visual Builder creates an attribute-to-attribute connection between 
  6459. the original part and the torn-off attribute. You can then make other 
  6460. connections to or from the torn-off attribute. 
  6461.  
  6462. You might want to tear off an attribute to do the following: 
  6463.  
  6464.      Allow direct access from one that is nested inside of another 
  6465.      Enable direct access to an attribute's events and actions 
  6466.  
  6467.  For example, in an address book application you might tear off attributes as 
  6468.  follows: 
  6469.  
  6470.      You might have a Person part that contains both homeAddress and 
  6471.       workAddress attributes, both of which, in turn, could contain street, 
  6472.       city, and state attributes. 
  6473.  
  6474.      By tearing off either the homeAddress or workAddress attribute, you can 
  6475.       create a new part that contains street, city, and state attributes. 
  6476.  
  6477.      Tearing off a homeAddress or workAddress attribute makes the nested 
  6478.       street, city, and state attributes directly accessible. Now that the 
  6479.       nested attributes are directly accessible, you can make connections to 
  6480.       and from them, as well as to their associated events and actions. 
  6481.  
  6482.  
  6483. ΓòÉΓòÉΓòÉ 9.3.12. Undoing and Redoing Changes in the Composition Editor ΓòÉΓòÉΓòÉ
  6484.  
  6485. If you change something in the Composition Editor and then decide that you 
  6486. should have left things as they were, select Undo from the Edit pull-down menu 
  6487. to restore the part to its previous state. You can undo as many operations as 
  6488. you want, all the way back to when you opened the Composition Editor. 
  6489.  
  6490. If you undo an operation and then decide that you did the right thing in the 
  6491. first place, select Redo from the Edit pull-down menu. Redo restores the part 
  6492. to the state it was in before the last Undo, including any connections that 
  6493. were deleted. 
  6494.  
  6495. If you are not sure which operations you want to undo or redo, select Undo/Redo 
  6496. list from the Edit pull-down menu to display two lists of operations, one for 
  6497. undoing and one for redoing. From these lists, you can select an operation and 
  6498. then select the Undo or Redo push button. The operation that you select and all 
  6499. of the operations listed below it are undone or redone. 
  6500.  
  6501. Note:  Undo, Redo, and Undo/Redo list only affect operations you perform on the 
  6502.        free-form surface and parts palette in the Composition Editor. They have 
  6503.        no affect on any of the functions in the File pull-down menu, such as 
  6504.        Save, Save As, and Save and Generate, which you cannot undo. 
  6505.  
  6506.  
  6507. ΓòÉΓòÉΓòÉ 9.4. Constructing a GUI: the OASearch Application ΓòÉΓòÉΓòÉ
  6508.  
  6509.      GUI construction overview 
  6510.  
  6511.      Adding basic visual parts 
  6512.  
  6513.         -  Adding the parts 
  6514.  
  6515.         -  Changing the settings 
  6516.  
  6517.      Adding a variable to a composite part 
  6518.  
  6519.         -  Changing the variable's type 
  6520.  
  6521.         -  Adding the variable to the part interface 
  6522.  
  6523.  Personal notes: 
  6524.  
  6525.  
  6526. ΓòÉΓòÉΓòÉ 9.4.1. GUI Construction Overview ΓòÉΓòÉΓòÉ
  6527.  
  6528. The remainder of this chapter describes how to visually construct the graphical 
  6529. user interface (GUI) of an application using the OASearch application as an 
  6530. example. You construct a GUI by adding visual parts, such as push buttons, 
  6531. lists, and menus, to a window part. For a list of the visual parts available on 
  6532. the Composition Editor, see The Parts Palette. 
  6533.  
  6534.  
  6535. ΓòÉΓòÉΓòÉ 9.4.2. Adding Basic Visual Parts ΓòÉΓòÉΓòÉ
  6536.  
  6537. The purpose of this section is to guide you through constructing a version of 
  6538. the Opportunities Abound Contract Information window for the OASearch sample 
  6539. application. You construct this part (ContractView) in the Composition Editor 
  6540. using the basic visual parts. When finished, the Opportunities Abound Contract 
  6541. Information window looks like the following figure: 
  6542.  
  6543. To see the finished part, open contract.vbb. Begin with adding the parts. 
  6544.  
  6545.  
  6546. ΓòÉΓòÉΓòÉ 9.4.2.1. Adding the Parts ΓòÉΓòÉΓòÉ
  6547.  
  6548. Before starting this new visual part, make sure that oanonvis.vbb is loaded 
  6549. into Visual Builder. 
  6550.  
  6551. Adding the parts 
  6552.  
  6553.    1. Because you are constructing a new user interface, begin by creating a 
  6554.       visual part. Call it ContractView. 
  6555.  
  6556.       When you create a visual part, the Composition Editor opens a part that 
  6557.       inherits from IFrameWindow*. By default, the client area of the 
  6558.       IFrameWindow* appears as a canvas. 
  6559.  
  6560.    2. Change the title of the window. 
  6561.  
  6562.    3. Add the following parts to the window part: 
  6563.  
  6564.           Static text and entry field parts for Account Number, Company Name, 
  6565.            Project Manager, and Department. 
  6566.  
  6567.           A group-box part for the Position Details group. Resize the group 
  6568.            box. 
  6569.  
  6570.           Static-text and entry-field parts for the items inside the group 
  6571.            box. 
  6572.  
  6573.           Push-button parts. 
  6574.  
  6575.       See the figure below to see how the window should look after the parts 
  6576.       are added. 
  6577.  
  6578.  Changing the Labels 
  6579.  
  6580.  Directly edit the static text so that the text matches the figure shown in 
  6581.  What You Will Achieve. 
  6582.  
  6583.  Arranging the Parts 
  6584.  
  6585.  Arrange the parts on the frame window part so they are aligned and positioned 
  6586.  as shown in  What You Will Achieve. 
  6587.  
  6588.  For more information on how to perform these operations, see Using Parts. 
  6589.  
  6590.  Now that all the parts have been added, continue on with changing the 
  6591.  settings. 
  6592.  
  6593.  
  6594. ΓòÉΓòÉΓòÉ 9.4.2.2. Changing the Settings ΓòÉΓòÉΓòÉ
  6595.  
  6596. Now that the parts have been added for the user interface, customize the parts 
  6597. by modifying their settings. 
  6598.  
  6599. Specifying a push button label with mnemonic 
  6600.  
  6601. On the General settings page for the middle push button, type ~Save in the Text 
  6602. field. Select the OK push button. 
  6603.  
  6604. The middle push button of your window now reads Save, with a mnemonic of S. 
  6605. This means the user can select the push button by pressing Alt+S. 
  6606.  
  6607. Repeat this procedure for the push button to the right of the Save push button, 
  6608. specifying Cl~ear as the push button label. This push button now reads Clear, 
  6609. with a mnemonic of E. 
  6610.  
  6611. For the rightmost push button, specify ~Cancel as the label. This push button 
  6612. now reads Cancel, with a mnemonic of C. 
  6613.  
  6614. Specifying the default push button 
  6615.  
  6616. On the General settings page for the leftmost push button, type ~Refresh in the 
  6617. Text field. Select the Apply push button. The leftmost push button of your 
  6618. window now reads Refresh, with a mnemonic of R. 
  6619.  
  6620. On the Styles settings page, select the On radio button for the defaultButton 
  6621. style. Select the OK push button. The Refresh push button is now the default 
  6622. button for the window. This means the user can select the push button by 
  6623. pressing the Enter key. 
  6624.  
  6625. For details on the settings of a particular part, refer to the Visual Builder 
  6626. Parts Reference. For more information on how to perform these operations, see 
  6627. Changing Settings. 
  6628.  
  6629. Now that the settings have been specified, the next step is making connections 
  6630. between the parts. 
  6631.  
  6632.  
  6633. ΓòÉΓòÉΓòÉ 9.4.3. Adding a Variable to a Composite Part ΓòÉΓòÉΓòÉ
  6634.  
  6635. Variables serve an important role in complex applications. Use variables 
  6636. instead of parts in the following situations: 
  6637.  
  6638.      To act as a placeholder inside a composite part for parts not found in 
  6639.       the composite part. Using variables for nonvisual parts enables you to 
  6640.       pass data or function between composite parts. 
  6641.  
  6642.      To represent part instances created with Object Factory parts. For more 
  6643.       information on using Object Factory parts, see Adding Parts as Dynamic 
  6644.       Instances. 
  6645.  
  6646.  Each variable must be set to the part type it represents. Once set, the 
  6647.  variable takes on the interface of that part type. Unlike using a part, using 
  6648.  a variable does not cause the part constructor to run. 
  6649.  
  6650.  Begin by opening the ContractView part (found in contract.vbb) in the 
  6651.  Composition Editor. If you prefer to use the OAContractView part, you can find 
  6652.  this part in oawin.vbb. At this point, the ContractView part appears as shown 
  6653.  in the following figure: 
  6654.  
  6655.  We are using a variable instead of an OAContract* part because the contract 
  6656.  data varies with the information entered from the OAQueryContract* part. 
  6657.  
  6658.  To add a variable to the free-form surface, select , the Models category, from 
  6659.  the parts palette; then add , an IVBVariable* part, to the free-form surface. 
  6660.  Change its name to Contract. The ContractView with a variable added appears as 
  6661.  shown in the following figure: 
  6662.  
  6663.            Notice the square bracket symbols around the variable part. You can 
  6664.            always identify a variable by these symbols. Also note that tear-off 
  6665.            attributes also have square brackets and are in fact variables with 
  6666.            a special connection. 
  6667.  
  6668.  The next step is changing the variable's type. 
  6669.  
  6670.  
  6671. ΓòÉΓòÉΓòÉ 9.4.3.1. Changing the Variable's Type ΓòÉΓòÉΓòÉ
  6672.  
  6673. When you add a variable part, its type is initially IStandardNotifier*, meaning 
  6674. that the variable can stand for any part. This variable is supposed to stand 
  6675. for an OAContract* in this example, so you must change its type. 
  6676.  
  6677. Note:  You cannot use variables to represent template-based parts, such as 
  6678.        IVSequence*. 
  6679.  
  6680.    1. First, make sure the the .vbb file holding the OAContract part 
  6681.       (oanonvis.vbb) is loaded into Visual Builder. 
  6682.  
  6683.    2. Select Change Type on the variable's pop-up menu; then type OAContract* 
  6684.  
  6685.  The next step is adding the variable to the part interface. 
  6686.  
  6687.  
  6688. ΓòÉΓòÉΓòÉ 9.4.3.2. Adding the Variable to the Part Interface ΓòÉΓòÉΓòÉ
  6689.  
  6690. So far, the Contract variable is empty. To make the variable available for 
  6691. passing values from the main view (or any part outside ContractView), we must 
  6692. add the variable to the part interface of ContractView), Do this by selecting 
  6693. Promote Part Feature from the variable's pop-up menu. See Promoting a Part's 
  6694. Features if you need information about doing this. 
  6695.  
  6696. The next step is connecting the variable. 
  6697.  
  6698.  
  6699. ΓòÉΓòÉΓòÉ 10. Learning to Use Connections ΓòÉΓòÉΓòÉ
  6700.  
  6701.      Connection types overview 
  6702.  
  6703.      Connection type summary 
  6704.  
  6705.      Making the connections 
  6706.  
  6707.      Connecting features to member functions 
  6708.  
  6709.      Connecting features to custom logic 
  6710.  
  6711.      Connecting exception events to actions and member functions 
  6712.  
  6713.      Manipulating connections 
  6714.  
  6715.      Rearranging connections 
  6716.  
  6717.      Making connections for the OASearch application 
  6718.  
  6719.  Personal notes: 
  6720.  
  6721.  
  6722. ΓòÉΓòÉΓòÉ 10.1. Connection Types Overview ΓòÉΓòÉΓòÉ
  6723.  
  6724. This chapter describes the types of connections that you can make and how to 
  6725. make them. Each connection description provides a definition of the connection, 
  6726. the color of the connection, whether the arrows are unidirectional or 
  6727. bidirectional, and whether the connection requires you to satisfy parameters to 
  6728. complete it. 
  6729.  
  6730. Attribute-to-attribute connection 
  6731.  
  6732. An attribute-to-attribute connection links two attribute values together. The 
  6733. purpose of this type of connection is to cause the value of one attribute to 
  6734. change when the value of another attribute changes. 
  6735.  
  6736. An attribute-to-attribute connection uses a bidirectional cyan arrow with the 
  6737. solid arrow head pointing to the target and the hollow arrow head pointing to 
  6738. the source. The bidirectional arrow indicates that a change in the value of 
  6739. either attribute can cause the value of the other attribute to change 
  6740. accordingly, except as noted in the table below. When your part is created 
  6741. within an application, the target attribute is set to the value of the source 
  6742. attribute. Attribute-to-attribute connections never take any parameters. 
  6743.  
  6744. Note:  You can use a class interface part as the source of a connection only 
  6745.        when making an attribute-to-attribute connection. An attribute of a 
  6746.        class interface part can be used to initialize an attribute of another 
  6747.        part without using notification. 
  6748.  
  6749.  In the following example, the text attribute of the entry field is connected 
  6750.  to the accountNum attribute of the Contract. This connection causes the value 
  6751.  of the accountNum attribute to change whenever the value of the text attribute 
  6752.  changes, and vice versa. 
  6753.  
  6754.  The effect of attribute types on connections 
  6755.  
  6756.  It is important to know the types of attributes that you are connecting. 
  6757.  Otherwise, you might not achieve the results that you anticipate. 
  6758.  
  6759.  The following table shows the results of connecting attributes that have 
  6760.  different behavior types. See The Attribute Page for descriptions of the 
  6761.  attribute types. 
  6762.  
  6763.   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  6764.   ΓöéIf the source is a...ΓöéAnd the target is a  ΓöéAnd the target is a  ΓöéAnd the target is a  Γöé
  6765.   Γöé                     Γöéfull attribute...    Γöéno-set attribute...  Γöéno-event attribute...Γöé
  6766.   Γöéfull attribute       ΓöéAll attribute        ΓöéThe target attribute ΓöéThe target attribute Γöé
  6767.   Γöé                     Γöébehaviors are        Γöécannot set itself to Γöécannot notify the    Γöé
  6768.   Γöé                     Γöéavailable to both theΓöéthe value of the     Γöésource attribute whenΓöé
  6769.   Γöé                     Γöésource and target    Γöésource attribute.    Γöéthe target           Γöé
  6770.   Γöé                     Γöéattributes.          Γöé                     Γöéattribute's value    Γöé
  6771.   Γöé                     Γöé                     Γöé                     Γöéchanges.             Γöé
  6772.   Γöéno-set attribute     ΓöéThe source attribute ΓöéThis is an invalid   ΓöéThe source attribute Γöé
  6773.   Γöé                     Γöécannot set itself to Γöéconnection.          Γöécannot set itself to Γöé
  6774.   Γöé                     Γöéthe value of the     Γöé                     Γöéthe value of the     Γöé
  6775.   Γöé                     Γöétarget attribute.    Γöé                     Γöétarget attribute; theΓöé
  6776.   Γöé                     Γöé                     Γöé                     Γöétarget attribute     Γöé
  6777.   Γöé                     Γöé                     Γöé                     Γöécannot notify the    Γöé
  6778.   Γöé                     Γöé                     Γöé                     Γöésource attribute whenΓöé
  6779.   Γöé                     Γöé                     Γöé                     Γöéthe target           Γöé
  6780.   Γöé                     Γöé                     Γöé                     Γöéattribute's value    Γöé
  6781.   Γöé                     Γöé                     Γöé                     Γöéchanges.             Γöé
  6782.   Γöéno-event attribute   ΓöéThe source attribute ΓöéThe source attribute ΓöéThe source attribute Γöé
  6783.   Γöé                     Γöéinitializes the      Γöéinitializes the      Γöéinitializes the      Γöé
  6784.   Γöé                     Γöétarget attribute; no Γöétarget attribute; no Γöétarget attribute; no Γöé
  6785.   Γöé                     Γöéevent notification   Γöéevent notification   Γöéevent notification   Γöé
  6786.   Γöé                     Γöéoccurs.              Γöéoccurs; the target   Γöéoccurs; the target   Γöé
  6787.   Γöé                     Γöé                     Γöéattribute cannot set Γöéattribute cannot     Γöé
  6788.   Γöé                     Γöé                     Γöéitself to the value  Γöénotify the source    Γöé
  6789.   Γöé                     Γöé                     Γöéof the source        Γöéattribute when the   Γöé
  6790.   Γöé                     Γöé                     Γöéattribute.           Γöétarget attribute's   Γöé
  6791.   Γöé                     Γöé                     Γöé                     Γöévalue changes.       Γöé
  6792.   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  6793.  
  6794.  Event-to-attribute connection 
  6795.  
  6796.  An event-to-attribute connection allows the occurrence of the source event to 
  6797.  change the value of the target attribute. To accomplish this, the connection 
  6798.  calls the attribute's set member function whenever the event occurs. If the 
  6799.  attribute is a no-set attribute, you cannot make the connection. 
  6800.  
  6801.  An event-to-attribute connection uses a unidirectional dark green arrow with 
  6802.  the arrow head pointing to the target. If the attribute's set member function 
  6803.  requires data to satisfy its parameter, the connection line is initially 
  6804.  dashed to show that it is incomplete unless event data is provided, causing it 
  6805.  to turn solid. 
  6806.  
  6807.  You can satisfy the missing parameter value or override any event data that is 
  6808.  present by connecting the parameter to an attribute, action, member function 
  6809.  or custom logic, or by supplying a constant parameter value. See Satisfying 
  6810.  Parameters for Incomplete Connections for information about providing 
  6811.  parameter values. 
  6812.  
  6813.  In the following example, the buttonClickEvent feature of the Refresh push 
  6814.  button is connected to the text attribute of the entry field. 
  6815.  
  6816.  Event-to-action connection 
  6817.  
  6818.  An event-to-action connection allows an action to start whenever the event 
  6819.  that the action is connected to occurs. 
  6820.  
  6821.  An event-to-action connection uses a unidirectional, dark green arrow with the 
  6822.  arrow head pointing to the target. If the action requires data to satisfy its 
  6823.  parameter, the connection line is initially dashed to show that it is 
  6824.  incomplete unless event data is provided, causing it to turn solid. 
  6825.  
  6826.  You can satisfy the missing parameter value or override any event data that is 
  6827.  present by connecting the parameter to an attribute, action, member function 
  6828.  or custom logic, or by supplying a constant parameter value. See Satisfying 
  6829.  Parameters for Incomplete Connections for information about providing 
  6830.  parameter values. 
  6831.  
  6832.  Also, the action that is the target of this connection can have a return 
  6833.  value. If it does, you can treat the return value as a no-set attribute of the 
  6834.  connection and use it as the source of another connection. The return value 
  6835.  appears in the connection menu for the connection as actionResult. 
  6836.  
  6837.  In the following example, the buttonClickEvent feature of the Add push button 
  6838.  is connected to the addAsLast action of the multiline edit control. 
  6839.  
  6840.  Event-to-member function connection 
  6841.  
  6842.  An event-to-member function connection calls a member function of the part 
  6843.  currently being edited whenever the event that the member function is 
  6844.  connected to occurs. 
  6845.  
  6846.  An event-to-member function connection uses a unidirectional, light green 
  6847.  arrow with the arrow head pointing to the target. If the member function 
  6848.  requires data to satisfy its parameter, the connection line is initially 
  6849.  dashed to show that it is incomplete unless event data is provided, causing it 
  6850.  to turn solid. 
  6851.  
  6852.  You can satisfy the missing parameter value or override any event data that is 
  6853.  present by connecting the parameter to an attribute, action, member function 
  6854.  or custom logic, or by supplying a constant parameter value. See Satisfying 
  6855.  Parameters for Incomplete Connections for information about providing 
  6856.  parameter values. 
  6857.  
  6858.  Also, the member function that is the target of this connection may have a 
  6859.  return value. If it does, you can treat the return value as a no-set attribute 
  6860.  of the connection and use it as the source of another connection. The return 
  6861.  value appears in the connection menu for the connection as actionResult. 
  6862.  
  6863.  In the following example, the buttonClickEvent feature of the Clear push 
  6864.  button is connected to a resetFields member function. 
  6865.  
  6866.  Attribute-to-action connection 
  6867.  
  6868.  An attribute-to-action connection allows an action to start whenever the event 
  6869.  identification that is associated with the attribute is triggered. This 
  6870.  connection is similar to an event-to-action connection because the connection 
  6871.  calls the action whenever the attribute's event is triggered. 
  6872.  
  6873.  An attribute-to-action connection uses a unidirectional, dark green arrow with 
  6874.  the arrow head pointing to the target. If the action requires data to satisfy 
  6875.  its parameter, the connection line is initially dashed to show that it is 
  6876.  incomplete unless event data is provided, causing it to turn solid. 
  6877.  
  6878.  The attribute's value is passed as the first parameter of the action if no 
  6879.  parameter is explicitly specified. You can satisfy any other missing parameter 
  6880.  values or override the attribute value that is present by connecting the 
  6881.  parameter to an attribute, action, member function or custom logic, or by 
  6882.  supplying a constant parameter value. See Satisfying Parameters for Incomplete 
  6883.  Connections for information about providing parameter values. 
  6884.  
  6885.  Also, the action that is the target of this connection can have a return 
  6886.  value. If it does, you can treat the return value as a no-set attribute of the 
  6887.  connection and use it as the source of another connection. The return value 
  6888.  appears in the connection menu for the connection as actionResult. 
  6889.  
  6890.  In the following example, the text attribute of the entry field is connected 
  6891.  to the addAsLast action of the list box. 
  6892.  
  6893.  Attribute-to-member function connection 
  6894.  
  6895.  An attribute-to-member function connection allows a member function to start 
  6896.  whenever the event identification that is associated with the attribute is 
  6897.  triggered. This connection is similar to an event-to-member function 
  6898.  connection because the connection calls the action whenever the attribute's 
  6899.  event is triggered. However, if the attribute is a no-event attribute, the 
  6900.  member function is not signalled because a no-event attribute does not have an 
  6901.  event identifier. 
  6902.  
  6903.  An attribute-to-member function connection uses a unidirectional, light green 
  6904.  arrow with the arrow head pointing to the target. If the member function 
  6905.  requires data to satisfy its parameter, the connection line is initially 
  6906.  dashed to show that it is incomplete unless event data is provided, causing it 
  6907.  to turn solid. 
  6908.  
  6909.  You can satisfy the missing parameter value or override any event data that is 
  6910.  present by connecting the parameter to an attribute, action, member function 
  6911.  or custom logic, or by supplying a constant parameter value. See Satisfying 
  6912.  Parameters for Incomplete Connections for information about providing 
  6913.  parameter values. 
  6914.  
  6915.  Also, the member function that is the target of this connection can have a 
  6916.  return value. If it does, you can treat the return value as a no-set attribute 
  6917.  of the connection and use it as the source of another connection. The return 
  6918.  value appears in the connection menu for the connection as actionResult. 
  6919.  
  6920.  In the following example, a member function is called to calculate the 
  6921.  presentation space in the list box. 
  6922.  
  6923.  Custom logic connection 
  6924.  
  6925.  A custom logic connection allows your customized logic to run whenever either 
  6926.  of the following happens: 
  6927.  
  6928.      The value of the attribute that you connect it to changes. 
  6929.      The event that you connect it to occurs. 
  6930.  
  6931.  If you connect an attribute to your custom logic, use the attribute's event 
  6932.  identifier to execute the custom logic when the attribute's value changes. 
  6933.  
  6934.  A custom logic connection uses a unidirectional, blue arrow with the arrow 
  6935.  head pointing to the target. 
  6936.  
  6937.  Also, the custom logic that is the target of this connection may have a return 
  6938.  value. If it does, you can treat the return value as a no-set attribute 
  6939.  attribute of the connection and use it as the source of another connection. 
  6940.  The return value appears in the connection menu for the connection as 
  6941.  actionResult. 
  6942.  
  6943.  In the following example, custom logic is called to clear all of the entry 
  6944.  fields in a notebook. Otherwise, you would need to make a separate connection 
  6945.  from the push button's buttonClickEvent feature to the clear action of each 
  6946.  entry field. 
  6947.  
  6948.  Parameter connections 
  6949.  
  6950.  A parameter connection satisfies a parameter of an action or member function 
  6951.  by passing either an attribute's value or the return value from an action, 
  6952.  member function, or custom logic. This connection looks similar to an 
  6953.  attribute-to-attribute connection; it uses a bidirectional arrow, with the 
  6954.  solid arrow pointing to the target and the hollow arrow pointing to the 
  6955.  source. The difference you see on your screen is that parameter connections 
  6956.  are violet instead of cyan. 
  6957.  
  6958.  In addition, the parameter names are included in the connection menu. 
  6959.  Therefore, if you are in doubt about a connection that you want to make, you 
  6960.  can browse a part's features to see the parameter names. Be aware, however, 
  6961.  that any parameter names that you specified for an action in the Parameter 
  6962.  Names table on the Action page of the Part Interface Editor appear in the 
  6963.  connection menu instead of the actual parameter names. 
  6964.  
  6965.  The parameter is always the source of the connection because the parameter 
  6966.  cannot store any values. If you connect an attribute, action, member function, 
  6967.  or custom logic to a parameter, which makes the parameter the target of the 
  6968.  connection, Visual Builder reverses the direction to make the parameter the 
  6969.  source. 
  6970.  
  6971.  Whenever the parameter needs a value, the connection attempts to satisfy the 
  6972.  parameter in one of the following ways: 
  6973.  
  6974.      If the parameter is connected to an attribute, the connection invokes the 
  6975.       attribute's get member function to get the attribute's value and return 
  6976.       it to the parameter. 
  6977.  
  6978.      If the parameter is connected to an action, the connection invokes the 
  6979.       action and passes the action's return value to the parameter. The same is 
  6980.       true when a parameter is connected to a member function or to custom 
  6981.       logic. 
  6982.  
  6983.      You can supply a constant parameter value. See Satisfying Parameters for 
  6984.       Incomplete Connections for information about doing this. 
  6985.  
  6986.  If you connect a parameter to two different attributes, the first attribute 
  6987.  that you connect the parameter to has precedence over the second. You can 
  6988.  change this, if necessary, by reordering the connections or deleting one of 
  6989.  the connections. 
  6990.  
  6991.  Visual Builder uses a dashed line to give you a visual cue so that you know 
  6992.  when a parameter connection is needed. For example, if you connect an event to 
  6993.  a member function and the member function has a parameter that needs to be 
  6994.  satisfied, the connection line between the event and the member function is 
  6995.  dashed. See Satisfying Parameters for Incomplete Connections for more 
  6996.  information about parameter connections. 
  6997.  
  6998.  
  6999. ΓòÉΓòÉΓòÉ 10.2. Connection Type Summary ΓòÉΓòÉΓòÉ
  7000.  
  7001. The following table summarizes the types of connections that Visual Builder 
  7002. provides: 
  7003.  
  7004. Note:  In the table below, the return value is supplied by the connection's 
  7005.        actionResult attribute. 
  7006.  
  7007.  
  7008.    If you want to...     Use this connection     Color         Arrows           Return value
  7009.                          type                                                   allowed?
  7010.    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  7011.    Cause one data value  attribute-to-attribute  Cyan          Bidirectional    No
  7012.    to change another
  7013.    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  7014.    Change a data value   event-to-attribute      Dark green    Unidirectional   Yes
  7015.    whenever an event
  7016.    occurs
  7017.    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  7018.    Invoke an action      event-to-action         Dark green    Unidirectional   Yes
  7019.    whenever an event
  7020.    occurs
  7021.    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  7022.    Invoke a member       event-to-member         Light green   Unidirectional   Yes
  7023.    function whenever an  function
  7024.    event occurs
  7025.    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  7026.    Invoke an action      attribute-to-action     Dark green    Unidirectional   Yes
  7027.    whenever a data value
  7028.    changes
  7029.    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  7030.    Invoke a member       attribute-to-member     Light green   Unidirectional   Yes
  7031.    function whenever a   function
  7032.    data value changes
  7033.    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  7034.    Call customized code  custom logic            Blue          Unidirectional   Yes
  7035.    whenever a data value
  7036.    changes or an event
  7037.    occurs
  7038.    ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
  7039.    Satisfy a parameter   parameter               Violet        Bidirectional    Yes
  7040.    with a data value
  7041.  
  7042.  
  7043. ΓòÉΓòÉΓòÉ 10.3. Making the Connections ΓòÉΓòÉΓòÉ
  7044.  
  7045. In this section, you learn how to make attribute-to-attribute, 
  7046. event-to-attribute, event-to-action, and attribute-to-action connections. This 
  7047. section provides the following information: 
  7048.  
  7049.      Determining the source and target 
  7050.  
  7051.      Browsing a part's features 
  7052.  
  7053.      Connecting features to features 
  7054.  
  7055.      Satisfying parameters for incomplete connections 
  7056.  
  7057.  Member function connections are discussed in Connecting Features to Member 
  7058.  Functions. Custom logic connections are discussed in Connecting Features to 
  7059.  Custom Logic. 
  7060.  
  7061.  
  7062. ΓòÉΓòÉΓòÉ 10.3.1. Determining the Source and Target ΓòÉΓòÉΓòÉ
  7063.  
  7064. A connection is directional; it has a source and a target. The direction in 
  7065. which you draw the connection determines the source and target. The part on 
  7066. which the connection begins is the source and the part on which it ends is the 
  7067. target. 
  7068.  
  7069. When you make a connection, Visual Builder draws an arrow on the connection 
  7070. line between the two parts. The arrow points from the source to the target. If 
  7071. information can pass through the connection in both directions, as it can in an 
  7072. attribute-to-attribute connection, a hollow arrow points to the source and a 
  7073. solid arrow points to the target. 
  7074.  
  7075. Often, it does not matter which part you choose as the source or target, but 
  7076. there are connections where direction is important. 
  7077.  
  7078. Here are the source and target rules: 
  7079.  
  7080.      With an attribute-to-action, event-to-action, or event-to-attribute 
  7081.       connection, the event is always the source and the action or attribute is 
  7082.       always the target. If you try to make an action-to-attribute, 
  7083.       action-to-event, or attribute-to-event connection, Visual Builder 
  7084.       automatically reverses it for you. 
  7085.  
  7086.      For attribute-to-attribute connections, if only one of the attributes has 
  7087.       a set member function Visual Builder makes that attribute the target. 
  7088.       This is done so that the attribute that has the set member function can 
  7089.       be initialized when the application starts. 
  7090.  
  7091.      When you make attribute-to-attribute connections, the order in which you 
  7092.       choose the source and target is important. The source and target 
  7093.       attribute values are probably different when your view is first 
  7094.       initialized. If they are, Visual Builder resolves the difference by 
  7095.       changing the target end of the connection to match the source. 
  7096.       Thereafter, if both attributes have set member functions, the connection 
  7097.       updates either attribute if the other changes. 
  7098.  
  7099.  Refer to the attributes, actions, and events sections of the particular part 
  7100.  in the Visual Builder Parts Reference for information that is specific to a 
  7101.  part's features. 
  7102.  
  7103.  
  7104. ΓòÉΓòÉΓòÉ 10.3.2. Browsing a Part's Features ΓòÉΓòÉΓòÉ
  7105.  
  7106. Sometimes it is useful to browse a part's features before using them in a 
  7107. connection. For example, you might want to look at an attribute to see if it 
  7108. has a set member function so that it can update itself when it receives new 
  7109. data from another attribute. 
  7110.  
  7111. By using Browse Part Features, you can see all of a part's features in one 
  7112. window and browse, but not change, the information about each feature. To 
  7113. modify a feature, use the Part Interface Editor. 
  7114.  
  7115. There is an important distinction between browsing a part's features and 
  7116. displaying its features for making a connection. When you browse a part's 
  7117. features, you see all of its features, including inherited and promoted 
  7118. features, even if some of them are not available for connections. When you 
  7119. display a part's connection menu, however, you see only those features that are 
  7120. available for connections. 
  7121.  
  7122. To browse the features of a part, do the following: 
  7123.  
  7124.    1. Move the mouse pointer over the part and click mouse button 2. 
  7125.  
  7126.       Visual Builder displays the part's pop-up menu. 
  7127.  
  7128.    2. Select Browse Part Features. 
  7129.  
  7130.       Visual Builder displays a browse window that contains three columns: one 
  7131.       for actions, one for attributes, and one for events. For example, the 
  7132.       following figure shows the browse window that Visual Builder displays for 
  7133.       browsing the features of a push button: 
  7134.  
  7135.    3. Select the feature you want to browse. 
  7136.  
  7137.       Visual Builder displays information about the feature that you select in 
  7138.       the entry fields below the feature columns. Different sets of entry 
  7139.       fields are displayed depending on whether you select an attribute, an 
  7140.       event, or an action. 
  7141.  
  7142.       The information that Visual Builder displays when you browse a part's 
  7143.       features is the same as the information that you would see in the Part 
  7144.       Interface Editor. See Touring the Part Interface Editor to learn about 
  7145.       the information that Visual Builder displays for features. 
  7146.  
  7147.    4. If the information about a part's features should change, you can select 
  7148.       the Refresh push button to see those changes reflected in the browse 
  7149.       window. 
  7150.  
  7151.    5. When you have finished browsing the features, select the Close push 
  7152.       button to close the browse window. 
  7153.  
  7154.  
  7155. ΓòÉΓòÉΓòÉ 10.3.3. Connecting Features to Features ΓòÉΓòÉΓòÉ
  7156.  
  7157. When you connect features to features, you can use any of the following 
  7158. source-target combinations: 
  7159.  
  7160. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  7161. ΓöéIf source is a...  ΓöéThe target can be a...  Γöé
  7162. Γöépart               Γöépart or connection      Γöé
  7163. Γöéconnection         Γöépart                    Γöé
  7164. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  7165.  
  7166. Follow these steps to connect features: 
  7167.  
  7168.    1. Position the mouse pointer over the source, the part or connection that 
  7169.       you want to connect from, click mouse button 2, and select Connect from 
  7170.       its pop-up menu. 
  7171.  
  7172.                      To display the connection pop-up menu more quickly, hold 
  7173.                      down the Alt key while clicking mouse button 2. 
  7174.  
  7175.       A menu appears showing the names of the most commonly used attributes, 
  7176.       actions, and events, called the preferred features. If the source is a 
  7177.       part, there is usually a More selection at the bottom of the list. 
  7178.  
  7179.       If the More selection is not there, this means the list contains all of 
  7180.       the available features, not just the preferred ones, and there are no 
  7181.       more from which to select. 
  7182.  
  7183.    2. Do one of the following: 
  7184.  
  7185.           If the feature you want appears in the list, select it. 
  7186.  
  7187.           If the feature you want does not appear in the list, but the More 
  7188.            selection is available, select More and then select the feature you 
  7189.            want from the complete list of features. 
  7190.  
  7191.           If the feature you want does not appear in either the preferred list 
  7192.            or the expanded list that is displayed when you select More, you can 
  7193.            edit the part to add the feature you need. For more information 
  7194.            about this, see Editing Parts Placed on the Free-form Surface. 
  7195.  
  7196.                           If, at this point, you decide not to complete the 
  7197.                           connection, do one of the following: 
  7198.                             -  If a pop-up menu is displayed, move the mouse 
  7199.                                pointer away from the connection menu and click 
  7200.                                mouse button 1. 
  7201.  
  7202.                             -  If a window showing all of the features is 
  7203.                                displayed, select the Cancel push button at the 
  7204.                                bottom of the window. 
  7205.  
  7206.                           The menu or window disappears and the connection is 
  7207.                           not completed. 
  7208.  
  7209.    3. Position the mouse pointer over the part or connection that you want to 
  7210.       connect to. 
  7211.  
  7212.       While moving the mouse, notice that a dashed line trails from the mouse 
  7213.       pointer to the source of the connection. 
  7214.  
  7215.    4. Click mouse button 1 and a pop-up menu appears, again showing a list of 
  7216.       features. 
  7217.  
  7218.    5. Select a name from the pop-up menu or from the More list. 
  7219.  
  7220.       The same instructions regarding the presence of More apply as described 
  7221.       previously. 
  7222.  
  7223.  A colored connection line appears when both ends of the connection have been 
  7224.  made. The color indicates the connection's type, based on the selections you 
  7225.  made in the connection pop-up menu. See Connection Type Summary for a table 
  7226.  that shows the colors that are used for each connection type. 
  7227.  
  7228.  If the line is dashed, it requires parameters. To specify parameters, you make 
  7229.  an attribute-to-parameter connection or specify constant parameter values. You 
  7230.  can learn more about specifying parameters in Satisfying Parameters for 
  7231.  Incomplete Connections. 
  7232.  
  7233.  
  7234. ΓòÉΓòÉΓòÉ 10.3.4. Satisfying Parameters for Incomplete Connections ΓòÉΓòÉΓòÉ
  7235.  
  7236. Event-to-action, attribute-to-action, event-to-attribute, event-to-member 
  7237. function, and attribute-to-member function connections sometimes require 
  7238. parameters, or input arguments. If a connection requires parameters that have 
  7239. not been specified, it appears as a dashed arrow indicating that it is 
  7240. incomplete. When you have made all the necessary parameter connections, the 
  7241. connection line becomes solid indicating that the connection is complete. 
  7242.  
  7243. The following sections describe how to complete connections when input 
  7244. parameters are required and how to change source and target features without 
  7245. deleting a connection and starting over. 
  7246.  
  7247. Satisfying a parameter using a connection 
  7248.  
  7249. One way to satisfy parameters is to make connections from the dashed connection 
  7250. lines to the parts that supply the values to the parameters. Most of the time, 
  7251. the values you need are those of attributes of other parts that you are working 
  7252. with in the Composition Editor. Sometimes, however, the value you need is the 
  7253. return value from an action, a member function, or custom logic. 
  7254.  
  7255. To supply a parameter value, do the following: 
  7256.  
  7257.    1. Start a new connection using the dashed connection line that requires the 
  7258.       parameter as the source. 
  7259.  
  7260.    2. For the target, select the attribute, action, member function, or custom 
  7261.       logic that is to provide the value that the parameter needs. 
  7262.  
  7263.            While making a connection, when the mouse pointer is directly over 
  7264.            the connection line, you see a small box as a visual cue that the 
  7265.            pointer is positioned correctly. 
  7266.  
  7267.  The following example illustrates how to complete a connection using an 
  7268.  attribute to supply the input value to the parameter. The figure shows an 
  7269.  incomplete event-to-action connection. When a user selects the Add push 
  7270.  button, its buttonClickEvent feature notifies the addAsLast action of the 
  7271.  IListBox* part to add something to the list box as the last item in the list. 
  7272.  The connection is incomplete because the addAsLast action has a parameter that 
  7273.  needs an input value, which is the text to add to the list box. 
  7274.  
  7275.  The next example shows how a parameter connection, in which an attribute of 
  7276.  the IEntryField* part is used to supply the input value for the parameter, 
  7277.  completes the event-to-action connection shown above. The text parameter of 
  7278.  the incomplete connection is connected to the text attribute of the 
  7279.  IEntryField* part. Therefore, when the Add push button is selected, its 
  7280.  buttonClickEvent feature notifies the addAsLast action of the IListBox* part 
  7281.  to add the text in the IEntryField* part as the last item in the list box. 
  7282.  
  7283.            The return type of an action displays as the actionResult attribute 
  7284.            of the connection. For example, you can connect the actionResult 
  7285.            attribute to an attribute of the same part or another part. 
  7286.  
  7287.  Satisfying a parameter using a constant value 
  7288.  
  7289.  When connections need parameters whose input values are constant, you provide 
  7290.  these values by using the settings window of the incomplete connection, as 
  7291.  follows: 
  7292.  
  7293.    1. Select Open settings from the incomplete (dashed) connection's pop-up 
  7294.       menu. 
  7295.  
  7296.                      A quicker way to open the settings window is to 
  7297.                      double-click on the connection line. 
  7298.  
  7299.       The settings window of the incomplete connection is displayed. 
  7300.  
  7301.    2. Select the Set parameters push button. 
  7302.  
  7303.       The Constant Parameter Value Settings notebook is displayed showing the 
  7304.       parameters for which you can set constant values. 
  7305.  
  7306.    3. Enter the constant parameter values you want to use. 
  7307.  
  7308.       Type the parameter values just as you would type them as parameters for 
  7309.       the member function if you were coding it by hand. For example, to 
  7310.       provide a constant value for a text parameter, enter the text string that 
  7311.       you want the parameter to receive. Visual Builder copies them as strings 
  7312.       to the output files when you generate your default code. 
  7313.  
  7314.                      In event-to-attribute connections, the attribute's set 
  7315.                      member function sometimes has more than one parameter. In 
  7316.                      this case, Visual Builder only allows you to provide a 
  7317.                      constant parameter value for the first parameter. The 
  7318.                      other parameters are given default settings. 
  7319.  
  7320.                      For example, a set member function called setRange might 
  7321.                      have a range parameter and an override parameter. If you 
  7322.                      followed the instructions provided in this section, when 
  7323.                      you selected the Set parameters push button the settings 
  7324.                      page would only provide a field for a constant value for 
  7325.                      the range parameter; you would not be given an opportunity 
  7326.                      to change the default setting of the override parameter. 
  7327.  
  7328.                      To change the default values assigned to parameters, use a 
  7329.                      custom logic connection. See Connecting Features to Custom 
  7330.                      Logic for information about making custom logic 
  7331.                      connections. 
  7332.  
  7333.    4. Do one of the following: 
  7334.  
  7335.           Select the OK push button to apply the values and save them. 
  7336.  
  7337.           Select the Apply push button if you want to see what effect these 
  7338.            values have before saving them. 
  7339.  
  7340.           Select the Cancel push button to remove the notebook without saving 
  7341.            any of the parameter values you entered. 
  7342.  
  7343.       You can select Help for additional information about entering parameter 
  7344.       values. 
  7345.  
  7346.  Specifying defaults for parameters 
  7347.  
  7348.  There are two places in Visual Builder in which you can specify defaults for 
  7349.  the parameters of actions in the declaration of the action's member function: 
  7350.  
  7351.      In the part's .vbe file 
  7352.      On the Action page of the Part Interface Editor 
  7353.  
  7354.  Either of these allows a default value to be passed in an event-to-action 
  7355.  connection, thus avoiding the need to satisfy a parameter. 
  7356.  
  7357.  For example, suppose you want to connect the buttonClickEvent feature of a 
  7358.  Remove push button to a removeSelected action that you created for an 
  7359.  IListBox* part. Normally, you would also need to connect the selection 
  7360.  attribute of the subclassed IListBox* part to the index attribute of the 
  7361.  connection between buttonClickEvent and removeSelected. This connection would 
  7362.  be required to get the index of the selected item in the list box. 
  7363.  
  7364.  However, in the .vbe file of the IListBox* part, you can specify the following 
  7365.  default parameter value for the removeSelected action: //VBAction: 
  7366.  removeSelected, "removeSelected",, //VB:       removeSelected(unsigned long 
  7367.  index=selection()) 
  7368.  
  7369.  This means that if no attribute of the IListBox* part is connected to the 
  7370.  index attribute, the selection member function (the get member function of the 
  7371.  selection attribute) is called by default to provide the index of the selected 
  7372.  item. 
  7373.  
  7374.  You could do the same thing by creating a removeSelected action on the Action 
  7375.  page of the Part Interface Editor for the IListBox* part. You would specify 
  7376.  the default parameter in the declaration of the removeSelected member function 
  7377.  in the Action member function field, as follows: virtual unsigned long 
  7378.  removeSelected(unsigned long index=selection()) 
  7379.  
  7380.  Missing or invalid parameters 
  7381.  
  7382.  When an action connection requires arguments, be sure that you make the 
  7383.  correct number of parameter connections. Also be sure that you make the 
  7384.  parameter connections before you generate the default code for your part. See 
  7385.  Manipulating Connections to learn how to re-order connections. 
  7386.  
  7387.  
  7388. ΓòÉΓòÉΓòÉ 10.4. Connecting Features to Member Function Connections ΓòÉΓòÉΓòÉ
  7389.  
  7390.      About connections between features and member functions 
  7391.  
  7392.      Adding an event-to-member function connection 
  7393.  
  7394.      Using Browser information 
  7395.  
  7396.  Personal notes: 
  7397.  
  7398.  
  7399. ΓòÉΓòÉΓòÉ 10.4.1. About Connections Between Features and Member Functions ΓòÉΓòÉΓòÉ
  7400.  
  7401. A common use for member functions is with event-to-member function connections 
  7402. and attribute-to-member function connections. These connections link an event 
  7403. to a member function so that the member function is called when the event 
  7404. occurs. Event-to-member function connections make this link directly from an 
  7405. event to a member function connection. Attribute-to-member function connections 
  7406. make this link indirectly using the attribute's event identifier, passing the 
  7407. value of the attribute as the first parameter of the member function. The 
  7408. member function that you connect the event or attribute to must belong to the 
  7409. part being edited. 
  7410.  
  7411. For example, suppose you are creating a composite part that consists of several 
  7412. individual parts, such as a frame window, an entry field, a list box, and two 
  7413. push buttons. In this case, you can connect the attributes and events of all 
  7414. individual parts to a member function that belongs to the composite part that 
  7415. you are editing. 
  7416.  
  7417. When to connect attributes or events to member functions 
  7418.  
  7419. How do you know when to connect an attribute or event to an action and when to 
  7420. connect it to a member function? After all, an action is simply a member 
  7421. function with a part interface. Therefore, it seems there should be little 
  7422. difference between connecting to one and connecting to the other. 
  7423.  
  7424. The difference is accessibility. Anyone can use actions that you include in 
  7425. your part's interface, but only you can use the member functions that belong to 
  7426. your part. When you create actions and include them in your part's interface, 
  7427. other programmers who use your part can create their own event-to-action or 
  7428. attribute-to-action connections using the actions that you have defined for the 
  7429. part. That is the reason for including functions in the part's interface as 
  7430. actions-to make them available to other programmers. 
  7431.  
  7432. However, you may have functions that you want to invoke for your part without 
  7433. including them in the part's interface. For example, your part may need to 
  7434. perform a calculation internally whenever the value of an attribute changes. 
  7435. However, another programmer who is using your part may not need to be aware 
  7436. that this is happening. This is when you use member functions instead of 
  7437. actions. By using event-to-member function connections and attribute-to-member 
  7438. function connections, you can call these member functions when specific events 
  7439. occur or when attribute values change, but no one else can. 
  7440.  
  7441.  
  7442. ΓòÉΓòÉΓòÉ 10.4.2. Adding an Event-to-Member Function Connection ΓòÉΓòÉΓòÉ
  7443.  
  7444. The requirements for connecting an event to a member function are a visual part 
  7445. that has at least one event specified for it, as well as at least one member 
  7446. function. 
  7447.  
  7448. The following figure shows the OAContractorView part used in the OASearch 
  7449. sample application in this book. The steps for adding an event-to-member 
  7450. function connection, which follow the figure, are based on this part. For 
  7451. information about how to construct this part, see Adding Notebook Parts. 
  7452.  
  7453.    1. With the mouse pointer over the Clear push button, hold down the Alt key 
  7454.       and click mouse button 2. 
  7455.  
  7456.       Visual Builder displays the connection menu for the Clear push button. 
  7457.  
  7458.    2. From this menu, select the buttonClickEvent choice, an event. 
  7459.  
  7460.    3. Move the mouse pointer to a point on the free-form surface outside the 
  7461.       OAContractorView notebook part and click mouse button 1. Doing this 
  7462.       indicates to Visual Builder that you want to connect the event to the 
  7463.       OAContractorView notebook part instead of one of its subparts. 
  7464.  
  7465.       Visual Builder displays the connection menu with the preferred features 
  7466.       that have been defined for OAContractorView. The member function that you 
  7467.       want to connect your event to is not on this menu. Member functions are 
  7468.       not considered to be preferred features unless you define them as actions 
  7469.       in the Part Interface Editor. 
  7470.  
  7471.    4. Select More. 
  7472.  
  7473.       Visual Builder displays a window that contains three list boxes. The left 
  7474.       and middle boxes show the actions and attributes of the OAContractorView 
  7475.       notebook that you can connect the buttonClickEvent feature to. The third 
  7476.       list box is for events; this list box is empty because you cannot connect 
  7477.       one event, in this case buttonClickEvent, to another event. 
  7478.  
  7479.       Below the three list boxes is another section of the window titled Member 
  7480.       Function Connection. This is where you specify the member function that 
  7481.       you want to connect the buttonClickEvent feature to. 
  7482.  
  7483.       The For class field contains the class name of the part that you are 
  7484.       editing. This field is actually a drop-down list box. The list box is 
  7485.       initially empty. See the definition of the Browser pull-down menu item in 
  7486.       Browsing Part Information to find out how to display the names of the 
  7487.       classes that your part inherits from, as well as how to display the 
  7488.       member functions that your part contains in the list box at the bottom of 
  7489.       the window. 
  7490.  
  7491.       For this example, the For class field should contain OAContractorView, 
  7492.       the part that you are editing. 
  7493.  
  7494.       The Access field is another drop-down list box. This field is where you 
  7495.       specify the access level (public, protected, or private) for the member 
  7496.       functions that you want to see in the list. You must open the Browser 
  7497.       data to see a list of member functions. See Using Browser Information to 
  7498.       learn how to do this. 
  7499.  
  7500.       For this example, the Access field should contain public. 
  7501.  
  7502.    5. Type the member function to which the buttonClickEvent feature is to be 
  7503.       connected in the entry field below the Access field. Be sure to type the 
  7504.       full declaration of the member function, including return type and 
  7505.       parameters. 
  7506.  
  7507.       For this example, enter the following member function to clear all of the 
  7508.       fields in OAContractorView: void resetFields(); 
  7509.  
  7510.       You must also create an .hpv file that contains this member function 
  7511.       declaration and a .cpv file that contains the code for this member 
  7512.       function. The member function declaration that you enter in this field 
  7513.       must be identical to the declaration that you put in the .hpv file. For 
  7514.       information about .hpv and .cpv files, see Specifying Files for Visual 
  7515.       Builder to Include When You Build Your Application 
  7516.  
  7517.       In addition, before you generate the code for your part, you must switch 
  7518.       to the Class Editor and enter the names of these files so that Visual 
  7519.       Builder will include them in the code for your part. For more information 
  7520.       about including these files, see Specifying Files for Visual Builder to 
  7521.       Include When You Build Your Application. 
  7522.  
  7523.    6. Select the OK push button. 
  7524.  
  7525.       The connection window disappears and a light green connection arrow is 
  7526.       drawn from the Clear push button toward the edge of the free-form 
  7527.       surface. It looks like this: 
  7528.  
  7529.       If the resetFields member function had parameters, the connection arrow 
  7530.       would be dashed instead of solid to give you a visual cue that you would 
  7531.       need to provide values for the parameters. For information about the 
  7532.       various ways to do this, see Satisfying Parameters for Incomplete 
  7533.       Connections. 
  7534.  
  7535.  
  7536. ΓòÉΓòÉΓòÉ 10.4.3. Using Browser Information ΓòÉΓòÉΓòÉ
  7537.  
  7538. When connecting attributes or events to member functions, you might find it 
  7539. helpful to see the classes and member functions in your inheritance tree, as 
  7540. well as member functions that your part contains. You can get this information 
  7541. by selecting FileBrowser when using any of the Visual Builder editors. This 
  7542. menu choice provides access to a list of the classes that your part inherits 
  7543. from. 
  7544.  
  7545. You can use this list when you make attribute-to-member function and 
  7546. event-to-member function connections. The window that Visual Builder displays 
  7547. when you are making these connections contains a drop-down list box titled For 
  7548. class. In this list box, you can select one of the classes that your part 
  7549. inherits from. This causes Visual Builder to display a list of the member 
  7550. functions that the class contains in another list box at the bottom of the 
  7551. connection window. 
  7552.  
  7553. The connection window is modal. Therefore, to display browser data in this 
  7554. window, you must select the Open browser data menu choice before you begin the 
  7555. connection. Otherwise, the For class drop-down list box contains only the class 
  7556. name of your part, and the member function list box can display only the member 
  7557. functions that your part contains. 
  7558.  
  7559. The VisualAge C++ compiler generates the browser information when you have 
  7560. compiled your application. Therefore, except for the Quick browse menu choice, 
  7561. browser information is not available until after you compile your application. 
  7562.  
  7563. The VisualAge C++ compiler stores the browser information in a file whose name 
  7564. is based on the part name and whose extension is .pdb. To generate this file, 
  7565. you must include the -Fb+ compiler option in your make file. 
  7566.  
  7567. The cascaded menu that Visual Builder displays when you select FileBrowser 
  7568. contains the following selections: 
  7569.  
  7570.  Quick browse 
  7571.    Causes Visual Builder to retrieve a list of the classes that the part you 
  7572.    are editing inherits from, as well as a list of the member functions that 
  7573.    your part and the part it inherits from contains. If you select one of the 
  7574.    classes in the list, Visual Builder retrieves a list of the member functions 
  7575.    that the class contains. 
  7576.  
  7577.    This function is available only if you start Visual Builder from a WorkFrame 
  7578.    project. It gives you access to browser information before you compile your 
  7579.    application. 
  7580.  
  7581.  Open browser data 
  7582.    Works the same as Quick browse except you must compile your application with 
  7583.    the -Fb+ option before using this function. Also, you do not have to start 
  7584.    Visual Builder from a WorkFrame project to use this function. 
  7585.  
  7586.  Refresh browser data 
  7587.    Refreshes the list of the classes that the part you are editing inherits 
  7588.    from, as well as the list that is displayed in the member function list box 
  7589.    for the current class. If you reparse a part or recompile your application, 
  7590.    use this function afterwards to ensure the data in the list boxes is 
  7591.    current. 
  7592.  
  7593.  Close browser data 
  7594.    Removes the list of the classes that the part you are editing inherits from, 
  7595.    as well as the member functions those classes contain. 
  7596.  
  7597.  
  7598. ΓòÉΓòÉΓòÉ 10.5. Connecting Features to Custom Logic ΓòÉΓòÉΓòÉ
  7599.  
  7600.      About connections between features and custom logic 
  7601.  
  7602.      Adding a custom logic connection 
  7603.  
  7604.  Personal notes: 
  7605.  
  7606.  
  7607. ΓòÉΓòÉΓòÉ 10.5.1. About Connections Between Features and Custom Logic ΓòÉΓòÉΓòÉ
  7608.  
  7609. Custom logic connections enable you to connect small, specialized code snippets 
  7610. to events and attributes. These connections link an event to your code so that 
  7611. it is called when the event occurs. Custom logic connections that use events 
  7612. make this link directly from an event to the custom logic; custom logic 
  7613. connections that use attributes make this link indirectly using the attribute's 
  7614. event identifier. 
  7615.  
  7616. Use custom logic for unique logic requirements because the logic is stored as 
  7617. part of the connection and is not reusable. 
  7618.  
  7619.  
  7620. ΓòÉΓòÉΓòÉ 10.5.2. Adding a Custom Logic Connection ΓòÉΓòÉΓòÉ
  7621.  
  7622. The requirements for connecting an event or attribute to custom logic are a 
  7623. visual part that has at least one event or attribute specified for it. 
  7624. Following are the steps to follow for adding a custom logic connection. The 
  7625. following figure shows the History page of the OAContractorView part used in 
  7626. the OASearch sample application in this book. The example used in the following 
  7627. steps is based on this part. 
  7628.  
  7629.    1. Select the right arrow in the lower right corner of the notebook to 
  7630.       display the History page. 
  7631.  
  7632.    2. With the mouse pointer over the Clear push button, hold down the Alt key 
  7633.       and click mouse button 2. 
  7634.  
  7635.       Visual Builder displays the connection menu for the Clear push button. 
  7636.  
  7637.    3. From this menu, select the buttonClickEvent choice, an event. 
  7638.  
  7639.    4. Move the mouse pointer to a point on the free-form surface outside the 
  7640.       OAContractorView part and click mouse button 1. Doing this indicates to 
  7641.       Visual Builder that you want to connect the event to the OAContractorView 
  7642.       part instead of one of its subparts. 
  7643.  
  7644.       Visual Builder displays the connection menu with the preferred features 
  7645.       that have been defined for the OAContractorView part. 
  7646.  
  7647.    5. Select Custom logic. 
  7648.  
  7649.       Visual Builder displays the following window: 
  7650.  
  7651.    6. Enter the following in the Description field: 
  7652.  
  7653.             Custom logic code to clear all entry fields
  7654.  
  7655.       The Description field serves two purposes. After you complete the 
  7656.       connection, if you select the connection line Visual Builder displays the 
  7657.       text that you entered in this field in the information area at the bottom 
  7658.       of the Composition Editor. Also, when you generate the code for this 
  7659.       part, Visual Builder inserts a comment line that contains this 
  7660.       description. 
  7661.  
  7662.    7. The buttonClickEvent feature is the event you want to connect to your 
  7663.       custom logic, so do not change the Event name field for this example. 
  7664.  
  7665.       This field contains the event that you selected previously from the 
  7666.       connection menu. You can change this by selecting an event name from the 
  7667.       drop-down list box. 
  7668.  
  7669.    8. The default return type of void is the return type you want to use, so do 
  7670.       not change the Return type field for this example. 
  7671.  
  7672.       This field contains the return type for your custom logic. If you leave 
  7673.       void as the return type, your custom logic will have no return value. If 
  7674.       you want to pass a return value from your custom logic to another part, a 
  7675.       member function, or other custom logic, be sure to change the return type 
  7676.       to the type of data that you want to pass. 
  7677.  
  7678.    9. Select the Target push button. 
  7679.  
  7680.       Visual Builder inserts target-> in the Custom logic field. 
  7681.  
  7682.       The Custom logic field is a multiline entry field. This is where you 
  7683.       enter your custom logic. You can specify whether the code you enter here 
  7684.       is to effect the source part or the target part by selecting the Source 
  7685.       or Target push button before entering a line of code. You only need to 
  7686.       select one of these push buttons before entering the first line of a 
  7687.       group of lines. 
  7688.  
  7689.       In the generated code, the entry fields that we want to clear are created 
  7690.       using the new operator. For the StartEF part, the resulting pointer is 
  7691.       called iStartEF. 
  7692.  
  7693.   10. Type the following to the right of target->: 
  7694.  
  7695.             iStartEF->removeAll();
  7696.  
  7697.       This code calls the removeAll member function for the StartEF part, the 
  7698.       entry field labeled OA Start Date. 
  7699.  
  7700.   11. Press the Enter key to move the cursor to a new line. 
  7701.  
  7702.   12. Select the Target push button again. 
  7703.  
  7704.   13. Type the following to the right of target->: 
  7705.  
  7706.             iEndEF->removeAll();
  7707.  
  7708.       This code calls the removeAll member function for the EndEF part, the 
  7709.       entry field labeled OA End Date. 
  7710.  
  7711.   14. Press the Enter key to move the cursor to a new line. 
  7712.  
  7713.   15. Select the Target push button again. 
  7714.  
  7715.   16. Type the following to the right of target->: 
  7716.  
  7717.             iContractEF->removeAll();
  7718.       and put the following line beneath it: 
  7719.  
  7720.             return;
  7721.  
  7722.       This code calls the removeAll member function for the ContractEF part, 
  7723.       the entry field labeled Current Contract. 
  7724.  
  7725.       The connection window should now look like the following figure: 
  7726.  
  7727.   17. Select the Add push button. 
  7728.  
  7729.       The connection window disappears and a blue connection arrow is drawn 
  7730.       from the Clear push button toward the edge of the free-form surface. It 
  7731.       should look like this: 
  7732.  
  7733.  
  7734. ΓòÉΓòÉΓòÉ 10.6. Connecting Exception Events to Actions and Member Functions ΓòÉΓòÉΓòÉ
  7735.  
  7736. In C++, an exception is any user, logic, or system error detected by a function 
  7737. that does not deal with the error itself but passes the error on to a handling 
  7738. routine, called an exception handler. In Visual Builder, you can catch 
  7739. exceptions by connecting an exception event to either an action or a member 
  7740. function. 
  7741.  
  7742. An exception event is a feature of a connection, not a part. It is typically 
  7743. connected to an IMessageBox* part, which is used to display an error message 
  7744. associated with the exception. 
  7745.  
  7746. To connect an exception event, do the following: 
  7747.  
  7748.    1. Use your favorite text editor to create an action or member function that 
  7749.       throws an exception. 
  7750.  
  7751.       The easiest way to do this is to include the following in your action or 
  7752.       member function source code: 
  7753.  
  7754.                   throw IException("Error message.");
  7755.  
  7756.       where the text of the error message that you want to display in the 
  7757.       message box is the only parameter given for the IException constructor. 
  7758.  
  7759.       For example, the following isEntryFieldEmpty member function uses the 
  7760.       strcmp function to check the contents of an entry field in a To-Do List 
  7761.       application. The application adds the contents of the entry field to the 
  7762.       to-do list whenever the user clicks the Add push button. If the entry 
  7763.       field is empty and the user clicks on Add, the member function throws an 
  7764.       exception, which consists of an error message. 
  7765.  
  7766.             void ToDoList::isEntryFieldEmpty()
  7767.             {
  7768.                if (strcmp(this->iEntryField->text(), "") == 0)
  7769.                   throw IException("Type a to-do item in the entry field
  7770.                                     before selecting Add.");
  7771.             }
  7772.  
  7773.    2. Connect an event to the action or member function you just created. 
  7774.  
  7775.       The event that you connect here is the event for which you want to throw 
  7776.       an exception if an error occurs. In this example, you want to throw an 
  7777.       exception if the user clicks on Add when the entry field is empty. 
  7778.       Therefore, you would connect the buttonClickEvent feature on the Add push 
  7779.       button to the isEntryFieldEmpty member function. 
  7780.  
  7781.    3. Drop an IMessageBox* part on the free-form surface. 
  7782.  
  7783.       This message box is used to display the error message. 
  7784.  
  7785.    4. Move the mouse pointer to the connection you just made. 
  7786.  
  7787.    5. While holding down the Alt key, press mouse button 2. 
  7788.  
  7789.    6. Select the exceptionOccurred event from the connection menu. 
  7790.  
  7791.    7. Move the mouse pointer to the IMessageBox* part. 
  7792.  
  7793.    8. Click mouse button 1. 
  7794.  
  7795.    9. Select the show action from the connection menu. 
  7796.  
  7797.       This connection causes the application to show a message box that 
  7798.       contains the exception error message whenever the exception is thrown. 
  7799.  
  7800.  For an example using the OAContractorView part from the OASearch application, 
  7801.  see Passing Exceptions to Message Boxes. 
  7802.  
  7803.  
  7804. ΓòÉΓòÉΓòÉ 10.7. Manipulating Connections ΓòÉΓòÉΓòÉ
  7805.  
  7806. Once a connection is made, you can manipulate it by doing the following: 
  7807.  
  7808.      Changing settings for a connection 
  7809.  
  7810.      Reordering connections 
  7811.  
  7812.      Deleting connections 
  7813.  
  7814.      Showing and hiding connections 
  7815.  
  7816.  
  7817. ΓòÉΓòÉΓòÉ 10.7.1. Changing Settings for a Connection ΓòÉΓòÉΓòÉ
  7818.  
  7819. The settings window of a connection provides a way for you to select different 
  7820. features as the source and target of the connection. If a member function is 
  7821. the target of the connection, this window allows you to specify or select a 
  7822. different member function as the target. 
  7823.  
  7824. Note:  If you are changing the settings of a connection whose target is a 
  7825.        member function, you might want the connection settings window to show 
  7826.        the classes that your part inherits from, as well as the member 
  7827.        functions that those classes contain. To display the class and member 
  7828.        function names, you must open the browser data before opening this 
  7829.        settings window. See See  Browsing Part Information for information 
  7830.        about opening browser data. 
  7831.  
  7832.  To open the settings window for a connection, move the mouse pointer over the 
  7833.  connection and do one of the following: 
  7834.  
  7835.      Double-click mouse button 1. 
  7836.  
  7837.      Click mouse button 2 and select Open settings from the connection's 
  7838.       pop-up menu. 
  7839.  
  7840.  Visual Builder displays different connection settings windows depending on 
  7841.  whether the target of the connection is an attribute, action, or member 
  7842.  function. The following sections describe these three windows. 
  7843.  
  7844.      Changing settings when an attribute is the target 
  7845.  
  7846.      Changing settings when an action is the target 
  7847.  
  7848.      Changing settings when a member function is the target 
  7849.  
  7850.  
  7851. ΓòÉΓòÉΓòÉ 10.7.1.1. Changing Settings for Attribute-to-Attribute Connections ΓòÉΓòÉΓòÉ
  7852.  
  7853. The following figure shows the window that Visual Builder displays when you 
  7854. open the settings window for an attribute-to-attribute connection: 
  7855.  
  7856. The connection settings window for an attribute-to-attribute connection 
  7857. contains two columns of attributes. The left column contains the attributes 
  7858. that belong to the source part. The right column contains the attributes that 
  7859. belong to the target part. 
  7860.  
  7861. To change the attribute to be used as either the source or target of the 
  7862. connection, select an attribute from the list. 
  7863.  
  7864. This connection settings window has the following push buttons: 
  7865.  
  7866.  OK 
  7867.    Removes the connection settings window and puts any changes made into 
  7868.    effect. 
  7869.  
  7870.  Reverse 
  7871.    Reverses the order of the connection; the source part becomes the target and 
  7872.    the target part becomes the source. 
  7873.  
  7874.  Delete 
  7875.    Deletes the connection. 
  7876.  
  7877.  Cancel 
  7878.    Removes the connection settings window without putting any changes into 
  7879.    effect. 
  7880.  
  7881.  Help 
  7882.    Provides helpful information about the window. 
  7883.  
  7884.  
  7885. ΓòÉΓòÉΓòÉ 10.7.1.2. Changing Settings When an Action Is the Target ΓòÉΓòÉΓòÉ
  7886.  
  7887. When you open a settings window for a connection whose target is an action, 
  7888. Visual Builder displays the following window: 
  7889.  
  7890. The connection settings window contains two columns of features. The features 
  7891. in the left column belong to the source part; these features are the same type 
  7892. of feature as the one currently selected for the source part. For example, if 
  7893. the feature selected for the source part is an event, this column contains a 
  7894. list of the events that belong to the source part. 
  7895.  
  7896. Likewise, the features in the right column belong to the target part; these 
  7897. features are all actions or attributes that have set member functions. 
  7898.  
  7899. The entry fields above each list contain the names of the features that are 
  7900. currently selected. To change the feature to be used as either the source or 
  7901. target of a connection, select a feature from the list. 
  7902.  
  7903. This connection settings window has the following push buttons: 
  7904.  
  7905.  OK 
  7906.    Removes the connection settings window and puts any changes made into 
  7907.    effect. 
  7908.  
  7909.  Cancel 
  7910.    Removes the connection settings window without putting any changes into 
  7911.    effect. 
  7912.  
  7913.  Delete 
  7914.    Deletes the connection. 
  7915.  
  7916.  Set parameters 
  7917.    Opens another window in which you can specify a constant parameter value for 
  7918.    each parameter the action has. 
  7919.  
  7920.  Help 
  7921.    Provides helpful information about the window. 
  7922.  
  7923.  
  7924. ΓòÉΓòÉΓòÉ 10.7.1.3. Changing Settings When a Member Function Is the Target ΓòÉΓòÉΓòÉ
  7925.  
  7926. Two types of connections can use a member function as the target: 
  7927. attribute-to-member function and event-to-member function connections. The 
  7928. following figure shows a settings window for an event-to-member function 
  7929. connection: 
  7930.  
  7931. The Event name or Attribute name field 
  7932.  
  7933. The Event name field shows the name of the event that is connected to the 
  7934. member function. If this was an attribute-to-member function connection, this 
  7935. field would be the Attribute name field and would contain an attribute name. 
  7936.  
  7937. To change this name, select an attribute or event from the drop-down list box 
  7938. below the entry field. 
  7939.  
  7940. The For class field 
  7941.  
  7942. The For class field shows the name of the class that the target member function 
  7943. belongs to. This field can contain either the class name of the part that you 
  7944. are editing or the class name of a part that the part you are editing inherits 
  7945. from. 
  7946.  
  7947. To change this class name, select a class name from the drop-down list box 
  7948. below the entry field if you opened the browser data before opening this 
  7949. window. 
  7950.  
  7951. The Access field and member function list 
  7952.  
  7953. The Access field shows the current access type, which is either public, 
  7954. protected, or private. Member functions of this access type that belong to the 
  7955. class shown in the For class field are displayed in the list box at the bottom 
  7956. of the window. These member function names are displayed only if you opened the 
  7957. browser data before opening this window. The list includes the currently 
  7958. selected member function, which is shown in the entry field above the list. 
  7959.  
  7960. To change the access type, do one of the following: 
  7961.  
  7962.      Move the mouse pointer over the Access field, click mouse button 1, and 
  7963.       type the letter p. 
  7964.  
  7965.       Each time you type the letter p, the next access type appears. For 
  7966.       example, if the entry field contains public, typing the letter p causes 
  7967.       protected to appear. 
  7968.  
  7969.      Select an access type from the drop-down list box. 
  7970.  
  7971.  To change the member function that is used for the connection, do one of the 
  7972.  following: 
  7973.  
  7974.      Type a different member function in the entry field. 
  7975.  
  7976.      Select a member function from the list displayed below the entry field if 
  7977.       you opened the browser data before opening this window. 
  7978.  
  7979.  The push buttons 
  7980.  
  7981.  The connection settings window for member functions has the following push 
  7982.  buttons: 
  7983.  
  7984.  OK 
  7985.    Removes the connection settings window and puts any changes made into 
  7986.    effect. 
  7987.  
  7988.  Cancel 
  7989.    Removes the connection settings window without putting any changes into 
  7990.    effect. 
  7991.  
  7992.  Delete 
  7993.    Deletes the connection. 
  7994.  
  7995.  Set parameters 
  7996.    Opens another window in which you can specify a constant parameter value for 
  7997.    each parameter the member function has. 
  7998.  
  7999.  Help 
  8000.    Provides helpful information about the window. 
  8001.  
  8002.  
  8003. ΓòÉΓòÉΓòÉ 10.7.1.4. Changing Settings When Custom Logic Is the Target ΓòÉΓòÉΓòÉ
  8004.  
  8005. The following figure shows a settings window for a custom logic connection: 
  8006.  
  8007. The fields in this window are the same as those used to create the connection. 
  8008. See Adding a Custom Logic Connection for information about these fields and 
  8009. push buttons. 
  8010.  
  8011. The only push button that differs on this window is the Update push button. Use 
  8012. this push button to save any changes you make and close the window. 
  8013.  
  8014.  
  8015. ΓòÉΓòÉΓòÉ 10.7.2. Reordering Connections ΓòÉΓòÉΓòÉ
  8016.  
  8017. If you make several connections from the same part, they run in the order in 
  8018. which you made the connections. To ensure the correct flow of control when you 
  8019. generate the source code, you may need to reorder the connections. If so, do 
  8020. the following: 
  8021.  
  8022.    1. Select the source part. 
  8023.  
  8024.    2. From the source part's pop-up menu, select Reorder Connections From. 
  8025.  
  8026.       Visual Builder displays the Reorder Connections window showing a list of 
  8027.       your connections. 
  8028.  
  8029.    3. With the mouse pointer over the connection you want to reorder, press and 
  8030.       hold mouse button 2. 
  8031.  
  8032.    4. Drag the connection to the place in the list where you want the 
  8033.       connection to occur. 
  8034.  
  8035.    5. Release mouse button 2. 
  8036.  
  8037.    6. Repeat these steps until the connections are listed in the order in which 
  8038.       you want them to occur. 
  8039.  
  8040.    7. Close the window. 
  8041.  
  8042.  
  8043. ΓòÉΓòÉΓòÉ 10.7.3. Deleting Connections ΓòÉΓòÉΓòÉ
  8044.  
  8045. You can delete a connection in either of the following ways: 
  8046.  
  8047.      From the connection's pop-up menu. 
  8048.  
  8049.       Note:  You do not have to select a connection to delete it using this 
  8050.              method. 
  8051.  
  8052.       To delete a connection from its pop-up menu, do the following: 
  8053.  
  8054.         1. Click on the connection with mouse button 2 to display its pop-up 
  8055.            menu. 
  8056.  
  8057.         2. Select Delete. 
  8058.  
  8059.      From the connection's settings window 
  8060.  
  8061.       To delete a connection from its settings window, do the following: 
  8062.  
  8063.         1. Open the settings window for the connection by doing one of the 
  8064.            following: 
  8065.  
  8066.              -  Double-clicking on the connection 
  8067.  
  8068.              -  Clicking on the connection with mouse button 2 to display its 
  8069.                 pop-up menu and selecting Open Settings 
  8070.  
  8071.         2. Select the Delete push button. 
  8072.  
  8073.  
  8074. ΓòÉΓòÉΓòÉ 10.7.4. Showing and Hiding Connections ΓòÉΓòÉΓòÉ
  8075.  
  8076. You can show and hide connections by using , the Hide Connections tool, and , 
  8077. the Show Connections tool on the Tool bar. These tools show or hide all 
  8078. connections that have the selected part or parts as their source or target. If 
  8079. no parts are selected, these tools show or hide all of the connections. 
  8080.  
  8081.            If you hide connections, the Composition Editor free-form surface is 
  8082.            drawn faster and is less cluttered, making it easier for you to 
  8083.            work. 
  8084.  
  8085.  If no parts are selected, these tools show and hide all of the connections in 
  8086.  the view. If a part or parts are selected, these tools show and hide the 
  8087.  connections between the selected part or parts. 
  8088.  
  8089.  Another way to show and hide connections is to move the mouse pointer over a 
  8090.  part, click mouse button 2, and select the Browse Connections choice from the 
  8091.  part's pop-up menu, which displays a cascaded menu. The choices in the menu 
  8092.  affect only connections going to and from the part the mouse pointer was over 
  8093.  when you displayed the pop-up menu. 
  8094.  
  8095.  The Browse Connections cascaded menu contains the following choices: 
  8096.  
  8097.  Show To 
  8098.    Shows all connections for which the part is the target. 
  8099.  
  8100.  Show From 
  8101.    Shows all connections for which the part is the source. 
  8102.  
  8103.  Show To/From 
  8104.    Shows all connections for which the part is either the source or the target. 
  8105.  
  8106.  Show All 
  8107.    Shows all connections that have been made, regardless of where the mouse 
  8108.    pointer is when you click mouse button 2. 
  8109.  
  8110.  Hide To 
  8111.    Hides all connections for which the part is the target. 
  8112.  
  8113.  Hide From 
  8114.    Hides all connections for which the part is the source. 
  8115.  
  8116.  Hide To/From 
  8117.    Hides all connections for which the part is either the source or the target. 
  8118.  
  8119.  Hide All 
  8120.    Hides all connections that have been made, regardless of where the mouse 
  8121.    pointer is when you click mouse button 2. 
  8122.  
  8123.  
  8124. ΓòÉΓòÉΓòÉ 10.8. Rearranging Connections ΓòÉΓòÉΓòÉ
  8125.  
  8126. You can rearrange a connection by doing the following: 
  8127.  
  8128.      Selecting connections 
  8129.  
  8130.      Deselecting connections 
  8131.  
  8132.      Changing the source and target of connections 
  8133.  
  8134.  
  8135. ΓòÉΓòÉΓòÉ 10.8.1. Selecting Connections ΓòÉΓòÉΓòÉ
  8136.  
  8137. You select connections in the same way that you select parts. When you select a 
  8138. connection, three boxes called selection handles appear on it to show that it 
  8139. is selected: one at each end and one in the middle. You can use these boxes to 
  8140. change either of the following: 
  8141.  
  8142.      The end points of the connection, as described in Changing the Source and 
  8143.       Target of Connections. 
  8144.  
  8145.      The shape of the connection arrow by dragging the middle box to another 
  8146.       location. This helps you distinguish among several connection lines that 
  8147.       are close together. 
  8148.  
  8149.  Selecting a single connection 
  8150.  
  8151.    1. Move the mouse pointer over the connection you want to select. 
  8152.  
  8153.    2. Click mouse button 1 to select the connection. 
  8154.  
  8155.       The connection is selected. 
  8156.  
  8157.  Selecting multiple connections 
  8158.  
  8159.  If you want to select several connections, do one of the following: 
  8160.  
  8161.      To select multiple connections using just the mouse, do the following: 
  8162.  
  8163.         1. Move the mouse pointer over one of the connections you want to 
  8164.            select. 
  8165.  
  8166.         2. Hold down mouse button 1 instead of clicking it. 
  8167.  
  8168.         3. Move the mouse pointer over each connection that you want to select. 
  8169.  
  8170.            The selection boxes appear on each connection that the mouse pointer 
  8171.            passes over to show they are selected. 
  8172.  
  8173.         4. After the connections are selected, release mouse button 1. 
  8174.  
  8175.      To select multiple connections using both the mouse and the keyboard, do 
  8176.       the following: 
  8177.  
  8178.         1. Hold down the Ctrl key. 
  8179.  
  8180.         2. Move the mouse pointer over a connection. 
  8181.  
  8182.         3. Click mouse button 1 while the mouse pointer is over the connection 
  8183.            line. 
  8184.  
  8185.         4. Without releasing the Ctrl key, repeat the preceding steps until all 
  8186.            connections that you want to select are selected. 
  8187.  
  8188.  
  8189. ΓòÉΓòÉΓòÉ 10.8.2. Deselecting Connections ΓòÉΓòÉΓòÉ
  8190.  
  8191. If you want to deselect a connection without selecting another part or 
  8192. connection, do the following: 
  8193.  
  8194.    1. Move the mouse pointer over the connection line. 
  8195.  
  8196.    2. Hold down the Ctrl key. 
  8197.  
  8198.    3. Click mouse button 1. 
  8199.  
  8200.  
  8201. ΓòÉΓòÉΓòÉ 10.8.3. Changing the Source and Target of Connections ΓòÉΓòÉΓòÉ
  8202.  
  8203. Visual Builder gives you the ability to change what a connection is pointing to 
  8204. (the target) or pointing from (the source). Of course, you could always just 
  8205. delete the connection and create a new one. However, the following steps show 
  8206. you a quicker way to do this. 
  8207.  
  8208. To move either end of a connection, do the following: 
  8209.  
  8210.    1. Select the connection. 
  8211.  
  8212.    2. Move the mouse pointer over either selection handle that appears on the 
  8213.       ends of the connection. 
  8214.  
  8215.    3. Press and hold mouse button 2. 
  8216.  
  8217.    4. Move the mouse pointer to the new part or connection. 
  8218.  
  8219.    5. Release the mouse button. 
  8220.  
  8221.  Depending on the connection type, you may get a pop-up menu asking you for new 
  8222.  information for the connection. 
  8223.  
  8224.  What you can change 
  8225.  
  8226.  You can change the source and target of either end of any connection. However, 
  8227.  depending on the feature that you connect to when you make the change, you 
  8228.  might get a different type of connection than the one you started with. 
  8229.  
  8230.  The following table gives you a closer look at the connection types and what 
  8231.  you can change without changing the connection type: 
  8232.  
  8233.   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  8234.   ΓöéConnection type               ΓöéMove either end  ΓöéMove source end  ΓöéMove target end  Γöé
  8235.   Γöéattribute-to-attribute        Γöéx                Γöé                 Γöé                 Γöé
  8236.   Γöéattribute-to-member function  Γöé                 Γöéx                Γöé                 Γöé
  8237.   Γöéattribute-to-action           Γöéx                Γöé                 Γöé                 Γöé
  8238.   Γöéevent-to-action               Γöéx                Γöé                 Γöé                 Γöé
  8239.   Γöéevent-to-attribute            Γöéx                Γöé                 Γöé                 Γöé
  8240.   Γöéevent-to-member function      Γöé                 Γöéx                Γöé                 Γöé
  8241.   Γöécustom logic                  Γöéx                Γöé                 Γöé                 Γöé
  8242.   Γöéparameter connection          Γöéx                Γöé                 Γöé                 Γöé
  8243.   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  8244.  
  8245.  
  8246. ΓòÉΓòÉΓòÉ 10.9. Making Connections for the OASearch Application ΓòÉΓòÉΓòÉ
  8247.  
  8248. The following sections show you how to connect the parts that were used to 
  8249. create a GUI for the OAContractView part in Constructing a GUI: the OASearch 
  8250. Application 
  8251.  
  8252.      Enabling push buttons when an entry field contains a value 
  8253.  
  8254.      Enabling a window to be cleared of all entry values 
  8255.  
  8256.      Connecting the variable part 
  8257.  
  8258.      Passing exceptions to message boxes 
  8259.  
  8260.  Personal notes: 
  8261.  
  8262.  
  8263. ΓòÉΓòÉΓòÉ 10.9.1. Enabling Push Buttons When an Entry Field Contains a Value ΓòÉΓòÉΓòÉ
  8264.  
  8265. This section shows you how to make the connections that enable the Refresh and 
  8266. Save push buttons in the OAContractView window. When you have made these 
  8267. connections, the window appears as shown in the following figure: 
  8268.  
  8269. Follow these steps to enable the push buttons: 
  8270.  
  8271.    1. From the Account Number pop-up menu, select Connect. 
  8272.  
  8273.    2. Select text from the list. 
  8274.  
  8275.    3. Click on the Refresh push button. 
  8276.  
  8277.    4. Select enabled from the pop-up menu. 
  8278.  
  8279.       This connection means that the Refresh push button will only be enabled 
  8280.       whenever the contents of the Account Number text changes, whether by 
  8281.       typing text in it or by another connection. Here, you use an 
  8282.       attribute-to-action connection because you want the enabled action to 
  8283.       occur whenever the value of the text attribute changes. 
  8284.  
  8285.    5. Follow the same procedure to connect the text attribute of the Account 
  8286.       Number text part to the enabled attribute of the Save push button part. 
  8287.  
  8288.  
  8289. ΓòÉΓòÉΓòÉ 10.9.2. Enabling a Window to be Cleared of All Entry Values ΓòÉΓòÉΓòÉ
  8290.  
  8291. You can enable the Clear push button to empty all entry fields of their 
  8292. contents using more than one method. One way would be to connect the 
  8293. buttonClickEvent feature of the Clear push button to the removeAll action of 
  8294. each entry field in the window. Another way would be to connect the 
  8295. buttonClickEvent feature of the Clear push button to a resetFields member 
  8296. function of the OAContractView composite part. 
  8297.  
  8298. For this example, assume that the member function has been written. Make the 
  8299. connection as follows: 
  8300.  
  8301.    1. From the Composition Editor, use Alt-mouse button 2 to select the 
  8302.       buttonClickEvent of the Clear push button. 
  8303.  
  8304.       The connection spider appears. 
  8305.  
  8306.    2. Use Alt-mouse button 2 to select an empty section of the free-form 
  8307.       surface. 
  8308.  
  8309.    3. Select More from the pop-up menu. 
  8310.  
  8311.    4. Enter the member function declaration in the entry field as shown in the 
  8312.       following figure: 
  8313.  
  8314.    5. Select the OK push button. 
  8315.  
  8316.    6. Switch to the Class Editor. 
  8317.  
  8318.       Include the files containing the member function code. For this example, 
  8319.       the file names are oafwclr.cpv and oafwclr.hpv. 
  8320.  
  8321.         a. In the User .hpv file field, type the name of the header file, 
  8322.            oafwclr.hpv 
  8323.         b. In the User .cpv file field, type the name of the code file, 
  8324.            oafwclr.cpv 
  8325.  
  8326.  For details on the attributes, actions, or events of a particular part, refer 
  8327.  to the Visual Builder Parts Reference. For more information on how to perform 
  8328.  these operations, see Making the Connections. 
  8329.  
  8330.  
  8331. ΓòÉΓòÉΓòÉ 10.9.3. Connecting the Variable Part ΓòÉΓòÉΓòÉ
  8332.  
  8333. Once you have added the variable to the free-form surface and set its name and 
  8334. type, you need to connect it to the OAContractView composite part. 
  8335.  
  8336. Making the attribute-to-attribute connections 
  8337.  
  8338. So that recruiters can display and update contract information held by the 
  8339. Contract variable, you must make attribute-to-attribute connections between the 
  8340. composite visual part and the Contract variable as follows: 
  8341.  
  8342.  From part, feature            To part, feature 
  8343.  
  8344.  Contract,#accountNum          EntryField1,#text 
  8345.  
  8346.  Contract,#companyName         EntryField2,#text 
  8347.  
  8348.  Contract,#projectMgr          EntryField3,#text 
  8349.  
  8350.  Contract,#deptName            EntryField4,#text 
  8351.  
  8352.  Contract,#positionTitle       EntryField5,#text 
  8353.  
  8354.  Contract,#startDate           EntryField6,#text 
  8355.  
  8356.  Contract,#endDate             EntryField7,#text 
  8357.  
  8358.  Contract,#currContractor      EntryField8,#text 
  8359.  
  8360.  So far, the connections appear as shown in the following figure: 
  8361.  
  8362.  Making the event-to-action connections 
  8363.  
  8364.  To enable push buttons on the composite visual part, you must make 
  8365.  event-to-action connections. This is a two-step process, because you specified 
  8366.  an input parameter for each of the data access actions. First, connect each 
  8367.  push button to the Contract variable. The connection line appears dashed, 
  8368.  indicating an incomplete connection. Next, connect the attribute that 
  8369.  represents the input parameter to the event-to-action connection itself. 
  8370.  
  8371.  For this example, make the following connections: 
  8372.  
  8373.  From part, feature                        To part, feature 
  8374.  
  8375.  PushButton1,#buttonClickEvent             Contract,#getContract 
  8376.  
  8377.  EntryField1,#text (Account Number text)   The anAccountNum parameter of the 
  8378.                                            PushButton1,#buttonClickEvent--> 
  8379.                                            Contract,#getContract connection. 
  8380.                                            Visual Builder draws the parameter 
  8381.                                            connection in the opposite 
  8382.                                            direction. 
  8383.  
  8384.  PushButton2,#buttonClickEvent             Contract,#putContract 
  8385.  
  8386.  EntryField1,#text (Account Number text)   The anAccountNum parameter of the 
  8387.                                            PushButton2,#buttonClickEvent--> 
  8388.                                            Contract,#putContract connection. 
  8389.                                            Visual Builder draws the parameter 
  8390.                                            connection in the opposite 
  8391.                                            direction. 
  8392.  
  8393.  The connections now appear as shown in the following figure: 
  8394.  
  8395.  The putContract and getContract actions throw exceptions when the account 
  8396.  number is not found in the database. 
  8397.  
  8398.  The next step is passing the exception to a message box. 
  8399.  
  8400.  
  8401. ΓòÉΓòÉΓòÉ 10.9.4. Passing Exceptions to Message Boxes ΓòÉΓòÉΓòÉ
  8402.  
  8403. You can trigger the display of a message box when an exception is thrown. 
  8404. Although a message box is a user-interface element, Visual Builder treats 
  8405. message boxes as nonvisual parts. 
  8406.  
  8407. Adding the message box 
  8408.  
  8409. To add a message box to the free-form surface, select , the Other category, 
  8410. from the parts palette; then add , an IMessageBox* part, to the free-form 
  8411. surface. 
  8412.  
  8413. Making the connections 
  8414.  
  8415. Now, connect the exceptionOccurred event of each event-to-action connection to 
  8416. the showException action of the message box. 
  8417.  
  8418. The connections appear as shown in the following figure. Save and close your 
  8419. visual part. 
  8420.  
  8421.  
  8422. ΓòÉΓòÉΓòÉ 11. Displaying Objects in a List Box ΓòÉΓòÉΓòÉ
  8423.  
  8424. The following steps show you how to modify the original To-Do List application 
  8425. to use objects instead of text strings. If you have not already done so, please 
  8426. complete the original application, shown in Creating a Simple Visual Builder 
  8427. Application, before continuing with this example. 
  8428.  
  8429.      Introduction 
  8430.  
  8431.      Copying the ToDoList part 
  8432.  
  8433.      Creating the ToDoItem nonvisual part 
  8434.  
  8435.      Replacing and modifying the list box 
  8436.  
  8437.      Placing and modifying an IVBFactory* part 
  8438.  
  8439.      Placing and modifying an IVSequence* part 
  8440.  
  8441.      Making the new connections 
  8442.  
  8443.      Generating the source code for your visual part and main() procedure 
  8444.  
  8445.      Building and running the modified application 
  8446.  
  8447.  Personal notes: 
  8448.  
  8449.  
  8450. ΓòÉΓòÉΓòÉ 11.1. Introduction ΓòÉΓòÉΓòÉ
  8451.  
  8452. In Creating a Simple Visual Builder Application, you use an IListBox* part to 
  8453. display the items in a to-do list. The items that you put in the IListBox* part 
  8454. are text strings that you create by entering them in an entry field and 
  8455. clicking on a push button. In this case, the text strings displayed in the list 
  8456. box are just text strings. 
  8457.  
  8458. Besides viewing a list of text strings, you can also use a list box to view a 
  8459. collection of nonvisual objects. List boxes that can display objects include 
  8460. the following: 
  8461.  
  8462.      ICollectionViewListBox* 
  8463.      ICollectionViewComboBox* 
  8464.  
  8465.  By connecting a collection of objects, such as an IVSequence* part, to one of 
  8466.  these list boxes, you can view a collection of objects instead of simple text 
  8467.  strings. 
  8468.  
  8469.  The procedure outlined in this section modifies the original To-Do List 
  8470.  application so that the list box contains objects rather than text strings. In 
  8471.  this case, text strings are again displayed in the list box, but this time 
  8472.  they are used to show the names of the objects in the sequence. When you 
  8473.  select an item in the list box after completing this procedure, you are really 
  8474.  selecting an object in the sequence, not the text string that represents the 
  8475.  object. 
  8476.  
  8477.  The modified To-Do List application differs from the original application in 
  8478.  that it uses the following parts: 
  8479.  
  8480.      An ICollectionViewListBox* part instead of an IListBox* part. 
  8481.  
  8482.       The ICollectionViewListBox* part can contain objects instead of just text 
  8483.       strings. 
  8484.  
  8485.      An IVBFactory* part. 
  8486.  
  8487.       The IVBFactory* part creates new objects to put in the list box. 
  8488.  
  8489.      An IVSequence* part. 
  8490.  
  8491.       The IVSequence* part contains the sequence of objects that is reflected 
  8492.       in the list box. 
  8493.  
  8494.      A ToDoItem part. 
  8495.  
  8496.       ToDoItem is a nonvisual part that is used as the type of objects that the 
  8497.       list box and sequence will contain, and that the object factory will 
  8498.       create. 
  8499.  
  8500.  The following prerequisites must be met to reflect a sequence of objects in a 
  8501.  list box: 
  8502.  
  8503.      The class name of the type of objects in the list box and sequence, as 
  8504.       well as the type of objects that the object factory creates, must be the 
  8505.       same. This class name must also be the name of a part that inherits from 
  8506.       IStandardNotifier. It does not have to inherit from IStandardNotifier 
  8507.       directly, but IStandardNotifier must be somewhere above it in its class 
  8508.       hierarchy. 
  8509.  
  8510.      The objects in the sequence must override the asString member function 
  8511.       inherited from the IVBase part. This is necessary so that at least one 
  8512.       attribute of each object, such as the object's name, can be displayed in 
  8513.       the list box. 
  8514.  
  8515.       In the procedure that you will follow for the To-Do List application, the 
  8516.       ToDoItem nonvisual part has its own asString member function. This member 
  8517.       function overrides the asString member function of IVBase by calling the 
  8518.       toDoItemName attribute's get member function, which returns the name of 
  8519.       the to-do item, as follows: 
  8520.  
  8521.             IString ToDoItem :: asString () const
  8522.             {
  8523.               return toDoItemName();
  8524.             }
  8525.  
  8526.  
  8527. ΓòÉΓòÉΓòÉ 11.2. Copying the ToDoList Part ΓòÉΓòÉΓòÉ
  8528.  
  8529. First, you must copy the ToDoList part, as follows: 
  8530.  
  8531.    1. Select todolist.vbb. 
  8532.  
  8533.       Visual Builder displays the name of the ToDoList part in the Visual Parts 
  8534.       list box. 
  8535.  
  8536.    2. Select the ToDoList part. 
  8537.  
  8538.    3. Select PartCopy. 
  8539.  
  8540.       Visual Builder displays the Copy Part window. 
  8541.  
  8542.    4. Enter ToDoLst2 in the Target part name field. 
  8543.  
  8544.    5. Enter todolst2.vbb in the Target file name field. 
  8545.  
  8546.    6. Select the Copy push button. 
  8547.  
  8548.       Visual Builder creates a copy of the ToDoList part, gives it the name 
  8549.       ToDoLst2, and stores it in the todolst2.vbb file. 
  8550.  
  8551.  
  8552. ΓòÉΓòÉΓòÉ 11.3. Creating the ToDoItem Nonvisual Part ΓòÉΓòÉΓòÉ
  8553.  
  8554. The next step is to create a nonvisual part called ToDoItem, as follows: 
  8555.  
  8556.    1. Open a new nonvisual part by doing the following: 
  8557.  
  8558.         a. In the Visual Builder window, select PartNew. 
  8559.  
  8560.            Visual Builder displays the Part - New window. 
  8561.  
  8562.         b. Fill in the fields in this window as follows. 
  8563.  
  8564.            Class name         ToDoItem 
  8565.  
  8566.            Description        Type of objects in To-Do List 
  8567.  
  8568.            File name          ToDoLst2.vbb 
  8569.  
  8570.            Part type          Nonvisual part 
  8571.  
  8572.            Base class         IStandardNotifier 
  8573.  
  8574.         c. Select the Open push button. 
  8575.  
  8576.            Visual Builder displays the Part Interface Editor. 
  8577.  
  8578.    2. Create a new attribute called toDoItemName by doing the following: 
  8579.  
  8580.         a. On the Attribute page, fill in the following fields: 
  8581.  
  8582.            Attribute name        toDoItemName 
  8583.  
  8584.            Attribute type        IString 
  8585.  
  8586.         b. Select the Add with defaults push button. 
  8587.  
  8588.            Visual Builder adds the toDoItemName attribute to the ToDoItem part. 
  8589.  
  8590.                      You can add the toDoItemName attribute to the preferred 
  8591.                      features list so that it will be readily available for 
  8592.                      making connections by doing the following: 
  8593.                        a. Switch to the Part Interface Editor. 
  8594.  
  8595.                        b. Select the Preferred page. 
  8596.  
  8597.                        c. Scroll down the list of attributes until you find the 
  8598.                           toDoItemName attribute and select it. 
  8599.  
  8600.                        d. Select the Add>> push button. 
  8601.  
  8602.                           Visual Builder adds the toDoItemName attribute to the 
  8603.                           list of preferred features so that it will appear in 
  8604.                           the pop-up connection menu. 
  8605.  
  8606.    3. Specify the .hpv and .cpv files for Visual Builder to use for the default 
  8607.       feature code for the toDoItemName attribute by doing the following: 
  8608.  
  8609.         a. Switch to the Class Editor if you followed the steps in the 
  8610.            preceding hint. 
  8611.  
  8612.         b. Fill in the following fields: 
  8613.  
  8614.            User .hpv file        ToDoItem.hpv 
  8615.  
  8616.            User .cpv file        ToDoItem.cpv 
  8617.  
  8618.    4. Generate the default source and feature code for the ToDoItem part by 
  8619.       doing the following: 
  8620.  
  8621.         a. Select FileSave and generatePart source. 
  8622.  
  8623.            Visual Builder generates the code for the ToDoItem part and stores 
  8624.            it in files named ToDoItem.hpp and ToDoItem.cpp. These files contain 
  8625.            the appropriate include statements for the ToDoItem.hpv and 
  8626.            ToDoItem.cpv files. 
  8627.  
  8628.         b. Select FileSave and generateFeature source 
  8629.  
  8630.            Visual Builder generates the default code for the toDoItemName 
  8631.            attribute and stores it in the ToDoItem.hpv and ToDoItem.cpv files. 
  8632.  
  8633.    5. Override the asString member function in the IVBase* part by doing the 
  8634.       following: 
  8635.  
  8636.         a. Using your favorite text editor, edit the ToDoItem.hpv file and 
  8637.            insert the following at the bottom of the public section: 
  8638.  
  8639.                         IString ToDoItem :: asString () const;
  8640.  
  8641.         b. Save the file. 
  8642.  
  8643.         c. Edit the ToDoItem.cpv file and insert the following at the bottom of 
  8644.            the file: 
  8645.  
  8646.                       IString ToDoItem :: asString () const
  8647.                       {
  8648.                         return toDoItemName();
  8649.                       }
  8650.  
  8651.         d. Save the file and close the text editor. 
  8652.  
  8653.    6. Close the Part Interface Editor. 
  8654.  
  8655.  The ToDoItem part is now completed. 
  8656.  
  8657.  
  8658. ΓòÉΓòÉΓòÉ 11.4. Replacing and Modifying the List Box ΓòÉΓòÉΓòÉ
  8659.  
  8660. You need a list box that can display objects instead of just text strings, so 
  8661. next you must replace the IListBox* part with an ICollectionViewListBox* part, 
  8662. and then modify the ICollectionViewListBox* part to specify the type of objects 
  8663. it can display. 
  8664.  
  8665. Replacing IListBox* with ICollectionViewListBox* 
  8666.  
  8667.    1. Open the ToDoLst2 part. 
  8668.  
  8669.    2. Delete the IListBox* part. 
  8670.  
  8671.       The IListBox* part only accepts strings. You want a part that accepts 
  8672.       objects. 
  8673.  
  8674.       Visual Builder displays a message warning you that it will delete the 
  8675.       connections as well as the list box if you continue. You want to delete 
  8676.       the connections because you need different connections for this example. 
  8677.  
  8678.    3. Select the OK push button. 
  8679.  
  8680.       Visual Builder deletes the list box and the connections. 
  8681.  
  8682.    4. Select , the Lists category, from the row of icons on the left-hand side 
  8683.       of the parts palette. 
  8684.  
  8685.    5. Select , the ICollectionViewListBox* icon, from the row of icons that 
  8686.       Visual Builder displays on the right-hand side of the parts palette. 
  8687.  
  8688.    6. Place the crosshairs below the bottom left corner of the second static 
  8689.       text part and click mouse button 1. 
  8690.  
  8691.       A list box part that displays the items in a collection is placed beneath 
  8692.       the second static text part. 
  8693.  
  8694.  Specifying the type of items the list box can contain 
  8695.  
  8696.    1. Move the mouse pointer to the list box, click mouse button 2, and select 
  8697.       Open Settings. 
  8698.  
  8699.       Visual Builder displays the settings notebook for the list box. 
  8700.  
  8701.    2. Enter ToDoItem* in the Class name of items field. 
  8702.  
  8703.    3. Select the OK push button. 
  8704.  
  8705.       The list box can now accept only ToDoItem* objects. 
  8706.  
  8707.  
  8708. ΓòÉΓòÉΓòÉ 11.5. Placing and Modifying an IVBFactory* Part ΓòÉΓòÉΓòÉ
  8709.  
  8710. You need an IVBFactory* part to create the objects to be displayed in the list 
  8711. box. In addition, you must specify the type of objects the IVBFactory* part can 
  8712. create. 
  8713.  
  8714. Placing an IVBFactory* part on the free-form surface 
  8715.  
  8716.    1. Select , the Models category, from the row of icons on the left-hand side 
  8717.       of the parts palette. 
  8718.  
  8719.    2. Select , the IVBFactory* icon, from the row of icons that Visual Builder 
  8720.       displays on the right-hand side of the parts palette. 
  8721.  
  8722.    3. Place an object factory part on the free-form surface to the right of the 
  8723.       To-Do List window adjacent to the entry field. 
  8724.  
  8725.    4. Change the text beneath the object factory icon to ItemFactory. 
  8726.  
  8727.  Specifying the type of objects the object factory can create 
  8728.  
  8729.    1. Move the mouse pointer to the object factory, click mouse button 2, and 
  8730.       select Change Type. 
  8731.  
  8732.       Visual Builder displays a window in which you are to enter the type of 
  8733.       objects that the object factory is to create. 
  8734.  
  8735.    2. Enter ToDoItem* in the entry field in this window. 
  8736.  
  8737.    3. Select the OK push button. 
  8738.  
  8739.       The object factory can now create only ToDoItem objects. 
  8740.  
  8741.  
  8742. ΓòÉΓòÉΓòÉ 11.6. Placing and Modifying an IVSequence* Part ΓòÉΓòÉΓòÉ
  8743.  
  8744. You also need to place an IVSequence* part to put the objects that the 
  8745. IVBFactory* part creates into a sequence; you must also specify the type of 
  8746. objects the sequence can contain. 
  8747.  
  8748. Placing an IVSequence* part on the free-form surface 
  8749.  
  8750.    1. Select OptionsAdd part. 
  8751.  
  8752.       Visual Builder displays the Add part window. 
  8753.  
  8754.    2. Enter ItemSequence in the Name field. 
  8755.  
  8756.    3. Enter IVSequence* in the Part class field. 
  8757.  
  8758.    4. Select the Add push button. 
  8759.  
  8760.    5. Place an IVSequence* part on the free-form surface surface to the right 
  8761.       of the To-Do List window adjacent to the list box. 
  8762.  
  8763.  Specifying the type of objects in the sequence 
  8764.  
  8765.    1. Move the mouse pointer to the sequence, click mouse button 2, and select 
  8766.       Open Settings. 
  8767.  
  8768.       Visual Builder displays the settings notebook for the sequence. 
  8769.  
  8770.    2. Enter ToDoItem* in the Class name of items field. 
  8771.  
  8772.    3. Select the OK push button. 
  8773.  
  8774.       The sequence can now accept only ToDoItem objects. 
  8775.  
  8776.  
  8777. ΓòÉΓòÉΓòÉ 11.7. Making the New Connections ΓòÉΓòÉΓòÉ
  8778.  
  8779. The following steps describe the connections that this example requires to add 
  8780. objects to and remove objects from the list box. To review the instructions for 
  8781. connecting features, see Making the Connections. 
  8782.  
  8783.    1. Connect the buttonClickEvent feature of the Add push button to the new 
  8784.       action of the object factory. 
  8785.  
  8786.       This connection causes the object factory to create a new ToDoItem object 
  8787.       whenever a user clicks the Add push button. 
  8788.  
  8789.    2. Connect the toDoItemName attribute of the object factory to the text 
  8790.       attribute of the entry field. 
  8791.  
  8792.       This connection causes text in the entry field to be used as the name of 
  8793.       ToDoItem objects that the object factory creates. Notice that the 
  8794.       connection line is violet, the color of a parameter connection, instead 
  8795.       of cyan, which is the color of an attribute-to-attribute connection. The 
  8796.       connection line is violet because the text attribute of the entry field 
  8797.       supplies a value for the toDoItemName attribute only when the object 
  8798.       factory creates a new object, just as if it were satisfying a parameter 
  8799.       of the new action. 
  8800.  
  8801.    3. Connect the newEvent attribute of the object factory to the addAsLast 
  8802.       action of the sequence. 
  8803.  
  8804.       This connection causes each new ToDoItem object to be added as the last 
  8805.       object in the sequence. 
  8806.  
  8807.    4. Connect the this attribute of the sequence to the items attribute of the 
  8808.       list box. 
  8809.  
  8810.       This connection causes the list box to display all of the ToDoItem 
  8811.       objects that the sequence contains. 
  8812.  
  8813.    5. Connect the buttonClickEvent feature of the Remove push button to the 
  8814.       removeAtPosition action of the sequence. 
  8815.  
  8816.       This connection causes the object at a specified position in the sequence 
  8817.       to be removed. This connection is incomplete because the removeAtPosition 
  8818.       action's position parameter must be satisfied. 
  8819.  
  8820.    6. Connect the position parameter of the previous connection to the 
  8821.       selectedCollectionPosition attribute of the list box. 
  8822.  
  8823.       This connection provides the position of the selected item in the 
  8824.       collection of objects, which is required by the previous connection in 
  8825.       order to remove an object. 
  8826.  
  8827.  
  8828. ΓòÉΓòÉΓòÉ 11.8. Generating the Source Code for Your Visual Part and main() Procedure ΓòÉΓòÉΓòÉ
  8829.  
  8830. To generate the C++ source code for your visual part, select FileSave and 
  8831. GeneratePart source. Visual Builder generates the following files in the 
  8832. working directory: 
  8833.  
  8834.  todolst2.cpp   The C++ code for your todolst2 part. 
  8835.  todolst2.hpp   The C++ header file for your todolst2 part. 
  8836.  todolst2.h     The resource header file for your todolst2.cpp file. 
  8837.  todolst2.rc    The resource file for your todolst2.cpp file. 
  8838.  
  8839.  Generating the source code for your main() procedure 
  8840.  
  8841.  To generate the source code for your main() procedure, select FileSave and 
  8842.  Generatemain() for part. Visual Builder generates the following files in the 
  8843.  working directory: 
  8844.  
  8845.  todolst2.app   The main function for your application. 
  8846.  
  8847.                 Note:  If you start Visual Builder from a WorkFrame project, 
  8848.                        the name of this file is vbmain.cpp. 
  8849.  todolst2.mak   The make file that you specify when you build your application. 
  8850.  
  8851.                 Note:  You must select OptionsGenerate make files in the 
  8852.                        Visual Builder window to generate this file. 
  8853.  
  8854.  
  8855. ΓòÉΓòÉΓòÉ 11.9. Building and Running the Modified Application ΓòÉΓòÉΓòÉ
  8856.  
  8857. You should now be ready to build and run your modified To-Do List application, 
  8858. as follows: 
  8859.  
  8860. Building the new To-Do List application 
  8861.  
  8862.    1. Open an OS/2 window. 
  8863.  
  8864.    2. Change to your Visual Builder working directory. 
  8865.  
  8866.    3. Enter the following command: 
  8867.  
  8868.             nmake todolst2.mak
  8869.  
  8870.       This command produces the following files: 
  8871.  
  8872.       todolst2.exe        The executable file for your application. 
  8873.       todolst2.map        The application configuration map. 
  8874.       todolst2.o          The object file for your application. 
  8875.  
  8876.                           Note:  If you start Visual Builder from a WorkFrame 
  8877.                                  project, the name of this file is vbmain.obj. 
  8878.       todolst2.obj        The object file for your part. Visual Builder 
  8879.                           provides a separate object module for your part that 
  8880.                           is used when compiling this part with other parts. 
  8881.       todolst2.res        The binary resource file that is bound to 
  8882.                           todolst2.exe. 
  8883.  
  8884.  Running the new To-Do List application 
  8885.  
  8886.  To run your application from the same OS/2 command prompt from which you 
  8887.  entered the nmake command, enter the following: 
  8888.  
  8889.   todolst2
  8890.  
  8891.  Once your application is running, experiment with it to make sure it works as 
  8892.  you designed it. That is all there is to it! 
  8893.  
  8894.  You can add a finishing touch to your application by creating an OS/2 program 
  8895.  object. Create a program object from the OS/2 Templates folder, specifying the 
  8896.  name todolst2.exe as the program name and the directory that contains 
  8897.  todolst2.exe as the working directory. Once you have done this, you can run 
  8898.  your application by simply double-clicking on the program object you just 
  8899.  created. 
  8900.  
  8901.  
  8902. ΓòÉΓòÉΓòÉ 12. Creating Resizable Windows ΓòÉΓòÉΓòÉ
  8903.  
  8904.      What you will achieve 
  8905.  
  8906.      What are the benefits of using multicell canvases? 
  8907.  
  8908.      Adding a multicell canvas 
  8909.  
  8910.      Adding parts to the multicell canvas 
  8911.  
  8912.      Changing the multicell canvas grid 
  8913.  
  8914.      Extending a part to span more than one cell 
  8915.  
  8916.      Adding a group box 
  8917.  
  8918.      Changing the settings for a multicell canvas 
  8919.  
  8920.  Personal notes: 
  8921.  
  8922.  
  8923. ΓòÉΓòÉΓòÉ 12.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  8924.  
  8925. The purpose of this chapter is to show you how to use multicell canvases to 
  8926. build a window that can be resized dynamically. 
  8927.  
  8928. All visual parts of the OASearch sample application except OAContractorView use 
  8929. multicell canvases as client areas. (OAContractorView uses multicell canvases 
  8930. as notebook page clients.) The example built in this chapter is based on the 
  8931. following figure: 
  8932.  
  8933. For the finished panel, see the OAContractView part in oawin.vbb. 
  8934.  
  8935.  
  8936. ΓòÉΓòÉΓòÉ 12.2. What Are the Benefits of Using Multicell Canvases? ΓòÉΓòÉΓòÉ
  8937.  
  8938. Because multicell canvases are dynamically resizable, they are the best canvas 
  8939. choice for applications that will be used in a variety of display resolutions. 
  8940. Using multicell canvases also makes it easier to plan for translation of your 
  8941. interface into other languages. 
  8942.  
  8943. Multicell canvases contain rows and columns of cells into which you can drop 
  8944. parts. Cells are referred to by row and column location: the cell at row 2, 
  8945. column 3 is called cell (2,3). Each cell is initially very small, 10 pixels 
  8946. wide and 10 pixels high. A grid of 5 rows and 5 columns appears when you first 
  8947. drop a multicell canvas into a client area. 
  8948.  
  8949. Any extra space between the grid and the bounds of the client area appears to 
  8950. the right of the rightmost grid line and below the bottommost grid line. This 
  8951. extra space is called the expansion area. The expansion area can also change 
  8952. size at run time when the user resizes the window. 
  8953.  
  8954. When you drop a visual part into the cell, the cell resizes to fit the minimum 
  8955. size of the dropped part. This minimum size is calculated for you based on 
  8956. limits that are set for the dropped part. 
  8957.  
  8958. For example, suppose you want an entry field that holds 10 characters. You drop 
  8959. the part and use the settings notebook to set its limit to 10 characters. The 
  8960. minimum size of the entry field is then calculated based on holding 10 
  8961. characters of the font defined for the entry field. 
  8962.  
  8963. The minimum size of a cell also depends on the size of parts that span the cell 
  8964. but are not contained within it. For specific examples of how layout influences 
  8965. minimum size, refer to the sample visual parts contained in oawin.vbb. 
  8966.  
  8967. Rows and columns are either fixed or expandable, depending on how their size is 
  8968. calculated. 
  8969.  
  8970.      The size of a fixed row or column is based on the minimum size of the 
  8971.       largest cell in that row or column. If no part occupies a cell in that 
  8972.       row or column, the row or column takes the default minimum size. 
  8973.  
  8974.      Expandable rows or columns can grow from their minimum size (the same as 
  8975.       if their size were fixed) to include the expansion area. If two or more 
  8976.       expandable rows or columns exist, the expansion area is parceled out 
  8977.       among them. Examples of the use of expandable columns appear in 
  8978.       oawin.vbb. 
  8979.  
  8980.  When first created, all rows and columns have a fixed size. To make them 
  8981.  expandable, edit the settings for the multicell canvas. For more information, 
  8982.  see Changing the Settings. 
  8983.  
  8984.  Working with multicell canvases does not require the Visual Builder alignment 
  8985.  tools. You alternate between the free-form surface and the settings notebook 
  8986.  for the multicell canvas. Begin by adding a multicell canvas. 
  8987.  
  8988.  
  8989. ΓòÉΓòÉΓòÉ 12.3. Adding a Multicell Canvas ΓòÉΓòÉΓòÉ
  8990.  
  8991. This example is based on OAContractView, found in oawin.vbb. 
  8992.  
  8993.    1. Because you are constructing a new user interface, begin by creating a 
  8994.       visual part. Call it contractView. 
  8995.  
  8996.       When you create a visual part, the Composition Editor opens and an 
  8997.       IFrameWindow* part is automatically added for you. By default, the client 
  8998.       area of the IFrameWindow* part appears as a canvas. 
  8999.  
  9000.    2. Delete the default canvas client. 
  9001.  
  9002.    3. Select , the Composers category, from the left side of the parts palette. 
  9003.  
  9004.    4. Select , the IMultiCellCanvas* part, from the right side of the parts 
  9005.       palette and drop it on the IFrameWindow* part. 
  9006.  
  9007.  Your visual part now looks like the following figure: 
  9008.  
  9009.  The next step is adding parts to the multicell canvas. 
  9010.  
  9011.  
  9012. ΓòÉΓòÉΓòÉ 12.4. Adding Parts to the Multicell Canvas ΓòÉΓòÉΓòÉ
  9013.  
  9014. When you first drop a multicell canvas, the cell grid appears at its default 
  9015. size in the upper-left corner of the client area. You can now drop parts into 
  9016. the canvas. For the contractView example, do the following: 
  9017.  
  9018.    1. Select , the Data Entry category, from the left side of the parts 
  9019.       palette. 
  9020.  
  9021.    2. Select , the IStaticText* part, from the right side of the parts palette. 
  9022.       When you move the mouse pointer over the free-form surface, the pointer 
  9023.       changes to crosshairs. 
  9024.  
  9025.    3. Drop the part at cell (2,2) of the multicell canvas. 
  9026.  
  9027.       Row 1 was left as a spacer between the top of the multicell canvas and 
  9028.       the window border. When you drop the IStaticText* part, cell (2,2) 
  9029.       expands to contain the dropped part. The multicell canvas now looks like 
  9030.       the following figure: 
  9031.  
  9032.    4. Drop another IStaticText* part at cell (4,2), leaving row 3 as a spacer. 
  9033.       The multicell canvas now looks like the following figure: 
  9034.  
  9035.    5. Drop two more IStaticText* parts into the expansion area below the 
  9036.       StaticText2 part. 
  9037.  
  9038.       Each time you drop a part into the expansion area, a new row is created 
  9039.       for you. 
  9040.  
  9041.    6. Drop three more IStaticText* parts in column 3 as shown in the following 
  9042.       figure: 
  9043.  
  9044.       No spacer rows exist yet between these new rows. We will add these in 
  9045.       Adding Rows or Columns. Now add some IEntryField* parts. 
  9046.  
  9047.    7. Select , the Data Entry category, from the left side of the parts 
  9048.       palette. 
  9049.  
  9050.    8. Select , the IEntryField* part, from the right side of the parts palette. 
  9051.  
  9052.    9. Drop IEntryField* parts in the expansion area to the right of the 
  9053.       IStaticText* parts, starting at row 2. A new column 6 is created, as 
  9054.       shown in the following figure: 
  9055.  
  9056.  
  9057. ΓòÉΓòÉΓòÉ 12.5. Changing the Multicell Canvas Grid ΓòÉΓòÉΓòÉ
  9058.  
  9059. You can add or delete rows or columns from a multicell canvas as follows: 
  9060.  
  9061.      To add rows or columns from the expansion area, you can just drop parts 
  9062.       into it, as discussed in Adding Parts to the Multicell Canvas. 
  9063.  
  9064.      To add several rows or columns at a time, you might find it easiest to 
  9065.       change the grid using the multicell canvas's settings notebook. This 
  9066.       method is discussed in Changing the Multicell Canvas Grid Using the 
  9067.       Settings Notebook. 
  9068.  
  9069.      With the multicell canvas selected, you can press mouse button 2 and use 
  9070.       the contextual menu. For more information on this method, see the 
  9071.       following: 
  9072.  
  9073.         -  Adding Rows or Columns Using the Contextual Menu 
  9074.  
  9075.         -  Deleting Rows or Columns Using the Contextual Menu 
  9076.  
  9077.  
  9078. ΓòÉΓòÉΓòÉ 12.5.1. Adding Rows or Columns Using the Contextual Menu ΓòÉΓòÉΓòÉ
  9079.  
  9080. You can add rows or columns anywhere on the multicell canvas as follows: 
  9081.  
  9082.    1. Select a cell next to where you want to add the row or column. 
  9083.  
  9084.       Note:  No selection handles are shown on the cell if it is empty. Also, 
  9085.              you can only open the contextual menu for an empty cell. 
  9086.  
  9087.    2. Press mouse button 2 to open the contextual menu. 
  9088.  
  9089.    3. To add a row, select Rows. To add a column, select Columns. 
  9090.  
  9091.       A cascade menu appears. 
  9092.  
  9093.    4. If you want to insert the row above the cell you selected, select Add row 
  9094.       before from the cascade menu. 
  9095.  
  9096.       If you want to insert the row below the cell you selected, select Add row 
  9097.       after from the cascade menu. 
  9098.  
  9099.       For columns, Add column before inserts a column to the right of the 
  9100.       selected cell. Add column after inserts a column to the left of the 
  9101.       selected cell. 
  9102.  
  9103.  For practice, add spacer rows to the contractView example as follows: 
  9104.  
  9105.    1. Select the empty cell to the left of StaticText3.  Add a row after it. 
  9106.  
  9107.    2. Add one row each after StaticText4 through StaticText7. 
  9108.  
  9109.  At this point, the contractView window looks like the following figure: 
  9110.  
  9111.  
  9112. ΓòÉΓòÉΓòÉ 12.5.2. Deleting Rows or Columns Using the Contextual Menu ΓòÉΓòÉΓòÉ
  9113.  
  9114. You can delete rows or columns from anywhere on the multicell canvas as 
  9115. follows: 
  9116.  
  9117.    1. Select a cell in the row or column you want to delete. 
  9118.  
  9119.    2. Press mouse button 2 to open the contextual menu. 
  9120.  
  9121.    3. To delete the row, select Rows. Then select Delete row. 
  9122.  
  9123.       To delete the column, select Columns. Then select Delete column. 
  9124.  
  9125.  
  9126. ΓòÉΓòÉΓòÉ 12.6. Extending a Part to Span More than One Cell ΓòÉΓòÉΓòÉ
  9127.  
  9128. Parts can span more than one column or row. This is necessary when placing a 
  9129. part entirely within one cell would distort the multicell canvas. Consider what 
  9130. happens when you add three push buttons individually to the sample multicell 
  9131. canvas, as shown in the following figure: 
  9132.  
  9133. Clearly, this was not intended. Instead, build a deck of push buttons using an 
  9134. ISetCanvas* part as a base, as follows: 
  9135.  
  9136.    1. Drop an ISetCanvas* part in the bottom expansion area of column 2. 
  9137.  
  9138.    2. Extend the span of the ISetCanvas* as follows: 
  9139.  
  9140.         a. Select the ISetCanvas* part. 
  9141.  
  9142.         b. Holding the Alt key with one hand, drag either right-hand part 
  9143.            handle over to the column that contains the IEntryField* parts. 
  9144.  
  9145.         c. Release the mouse. The sample window now looks like the following 
  9146.            figure: 
  9147.  
  9148.    3. Add three IPushButton* parts to the ISetCanvas* part. 
  9149.  
  9150.       The ISetCanvas* and multicell canvas parts expand to contain the newly 
  9151.       dropped IPushButton* parts. 
  9152.  
  9153.                      To change the way minimum size is calculated for the 
  9154.                      IPushButton* parts, edit Pack Type settings for the 
  9155.                      ISetCanvas* part. 
  9156.  
  9157.    4. Edit the IStaticText* parts so that they appear as shown in the following 
  9158.       figure: Extend each column 2 IStaticText* part into column 3. 
  9159.  
  9160.  
  9161. ΓòÉΓòÉΓòÉ 12.7. Adding a Group Box ΓòÉΓòÉΓòÉ
  9162.  
  9163. To organize groups of related visual parts on the multicell canvas, add a group 
  9164. box. You can drop the IGroupBox* part before or after you drop the visual parts 
  9165. contained within it. 
  9166.  
  9167.      If you prefer to drop the IGroupBox* part first, consider carefully how 
  9168.       many rows and columns you need within the group box. Add any extra rows 
  9169.       and columns before you drop the IGroupBox* part. It can be difficult to 
  9170.       add others in the correct locations later. 
  9171.  
  9172.      If you prefer to drop the contained parts first, you must edit tabbing 
  9173.       and depth order after you have dropped the IGroupBox* part. This is 
  9174.       necessary because parts are added to the window's tabbing and depth order 
  9175.       in the order in which they are dropped. To work properly, the IGroupBox* 
  9176.       part must appear in the tabbing and depth order before the parts 
  9177.       contained within it. 
  9178.  
  9179.  In the contractView sample, the column 3 IStaticText* parts and their entry 
  9180.  fields belong to the Position Details group shown in the following figure: 
  9181.  
  9182.  The group box will extend from cell (10,2) to cell (18,8). 
  9183.  
  9184.  Adding the extra rows and columns to hold the group box 
  9185.  
  9186.  Extra cells are necessary to hold the group box and provide space between the 
  9187.  group box and the parts within it. 
  9188.  
  9189.    1. Add 2 rows above Title. 
  9190.  
  9191.    2. Add 2 rows after Contractor. 
  9192.  
  9193.    3. Add 2 columns after the corresponding IEntryField* parts. 
  9194.  
  9195.  The sample window now looks like the following figure: 
  9196.  
  9197.  Dropping and extending the group box 
  9198.  
  9199.    1. Select , the Data Entry category, from the left side of the parts 
  9200.       palette. 
  9201.  
  9202.    2. Select , the IGroupBox* part, from the right side of the parts palette. 
  9203.  
  9204.    3. Drop the IGroupBox* part into cell (10,2). 
  9205.  
  9206.       This temporarily distorts the multicell canvas. Resize the IFrameWindow* 
  9207.       part to see the extra columns on the right. 
  9208.  
  9209.    4. Select the IGroupBox* part. Holding the Alt key with 1 hand, drag the 
  9210.       lower right part handle to cell (18,8) as shown in the following figure: 
  9211.  
  9212.       If necessary, press Alt-Backspace to undo and retry. Edit the IGroupBox* 
  9213.       text to read Position Details. Remember to move the IGroupBox* part up in 
  9214.       the tabbing and depth order. 
  9215.  
  9216.  
  9217. ΓòÉΓòÉΓòÉ 12.8. Changing the Settings for a Multicell Canvas ΓòÉΓòÉΓòÉ
  9218.  
  9219. You can use the General page of the multicell canvas settings notebook to do 
  9220. the following: 
  9221.  
  9222.      Move a dropped part 
  9223.  
  9224.      Change the default minimum size for rows or columns 
  9225.  
  9226.      Add rows or columns 
  9227.  
  9228.      Delete rows or columns 
  9229.  
  9230.      Make fixed rows and columns expandable 
  9231.  
  9232.  This page consists of a series of directly editable tables. 
  9233.  
  9234.  
  9235. ΓòÉΓòÉΓòÉ 12.8.1. Moving Dropped Parts ΓòÉΓòÉΓòÉ
  9236.  
  9237. From the free-form surface, you can move dropped parts by selecting and 
  9238. dragging them to their new locations. You can also move dropped parts between 
  9239. cells in a multicell canvas using the settings notebook as follows: 
  9240.  
  9241.    1. Open settings for the multicell canvas. 
  9242.  
  9243.    2. At the top of the General page is a scrollable list of all parts 
  9244.       contained in the multicell canvas as shown in the following figure: 
  9245.  
  9246.    3. Select the table entry you want to change and edit the highlighted value. 
  9247.       Row and column numbering starts from (1,1) in the upper-left corner of 
  9248.       the multicell canvas. 
  9249.  
  9250.    4. Select the OK push button to close settings. 
  9251.  
  9252.  Use this table for reference whenever you edit row and column settings. 
  9253.  
  9254.  
  9255. ΓòÉΓòÉΓòÉ 12.8.2. Changing Default Minimum Size for Rows or Columns ΓòÉΓòÉΓòÉ
  9256.  
  9257. You can change the minimum size of a row or column when it is empty. As stated 
  9258. previously, the default minimum size is 10 pixels wide (columns) and 10 pixels 
  9259. high (rows), but you can change the default minimum size for individual rows 
  9260. and columns as follows: 
  9261.  
  9262.    1. Open settings for the multicell canvas. 
  9263.  
  9264.    2. The second table on the General settings page is called Rows, as shown in 
  9265.       the following figure: 
  9266.  
  9267.    3. The default height appears as nil. To change the minimum height for row 
  9268.       1, select the Row 1 table entry under Height. Change this to the new 
  9269.       default value in pixels. For example, the minimum height of row 1 in most 
  9270.       views of the OASearch sample application is 20. 
  9271.  
  9272.    4. Scroll down the General page a little more to see the third table on the 
  9273.       page, called Columns. You can edit values in this table in the same way 
  9274.       you edited the Rows table. 
  9275.  
  9276.    5. Select the OK push button to close settings. 
  9277.  
  9278.  
  9279. ΓòÉΓòÉΓòÉ 12.8.3. Adding Rows or Columns Using the Settings Notebook ΓòÉΓòÉΓòÉ
  9280.  
  9281. To save time when adding more than one row or column at a time, use the 
  9282. settings notebook. The methods for adding rows and columns are similar, as 
  9283. follows: 
  9284.  
  9285.    1. Open settings for the multicell canvas. The tables on the General page 
  9286.       are described in Moving Dropped Parts and Changing Default Minimum Size 
  9287.       for Rows or Columns 
  9288.  
  9289.    2. If necessary, scroll down to the Rows table. For a complex layout, 
  9290.       consider resizing the window so that the Controls table is also 
  9291.       displayed. 
  9292.  
  9293.    3. Select the number of a row next to the insertion point. Select the Add 
  9294.       push button. 
  9295.  
  9296.    4. Select either Add before or Add after. 
  9297.  
  9298.           Add before inserts the new row above the selected row. 
  9299.           Add after inserts the new row below the selected row. 
  9300.  
  9301.    5. Select the OK push button to close settings. 
  9302.  
  9303.  
  9304. ΓòÉΓòÉΓòÉ 12.8.4. Deleting Rows or Columns Using the Settings Notebook ΓòÉΓòÉΓòÉ
  9305.  
  9306. To save time when deleting more than one row or column at a time, use the 
  9307. settings notebook. The methods for deleting rows and columns are similar, as 
  9308. follows: 
  9309.  
  9310.    1. Open settings for the multicell canvas. The tables on the General page 
  9311.       are described in Moving Dropped Parts and Changing Default Minimum Size 
  9312.       for Rows or Columns 
  9313.  
  9314.    2. If necessary, scroll down to the Rows table. For a complex layout, 
  9315.       consider resizing the window so that the Controls table is also 
  9316.       displayed. 
  9317.  
  9318.    3. Select the number of the row you want deleted. Select the Delete push 
  9319.       button. 
  9320.  
  9321.    4. Select the OK push button to close settings. 
  9322.  
  9323.  
  9324. ΓòÉΓòÉΓòÉ 12.8.5. Making Rows or Columns Expandable ΓòÉΓòÉΓòÉ
  9325.  
  9326. To allocate extra client space, make at least one row and one column 
  9327. expandable. In most of the OASearch windows, the row immediately above the deck 
  9328. of push buttons is expandable. In the OAContractView part, the rightmost column 
  9329. is expandable. For a more complicated example involving several expandable rows 
  9330. and columns, see the OAMain part in oawin.vbb. 
  9331.  
  9332. The methods for making rows and columns expandable are similar, as follows: 
  9333.  
  9334.    1. Open settings for the multicell canvas. The tables on the General page 
  9335.       are described in Moving Dropped Parts and Changing Default Minimum Size 
  9336.       for Rows or Columns 
  9337.  
  9338.    2. If necessary, scroll down to the Rows table. For a complex layout, 
  9339.       consider resizing the window so that the Controls table is also 
  9340.       displayed. 
  9341.  
  9342.    3. The default expansion value appears as nil. Select the appropriate entry 
  9343.       from the Rows table under Expand. For the contractView example, select 
  9344.       the row 19 entry. 
  9345.  
  9346.    4. The value d is highlighted. Change it to y and select the Apply push 
  9347.       button. 
  9348.  
  9349.    5. Move the settings notebook window over so you can see the result of your 
  9350.       work, as shown in the following figure: 
  9351.  
  9352.       The expansion area is now hidden. All extra vertical space becomes part 
  9353.       of row 19. 
  9354.  
  9355.    6. When you are finished adjusting row and column expansion settings, select 
  9356.       the OK push button. 
  9357.  
  9358.  To make this row fixed later, enter n in the Expand column. 
  9359.  
  9360.  
  9361. ΓòÉΓòÉΓòÉ 13. Constructing Containers and Notebooks ΓòÉΓòÉΓòÉ
  9362.  
  9363.      What you will achieve 
  9364.  
  9365.      Adding container parts 
  9366.  
  9367.         -  Setting up the container 
  9368.  
  9369.         -  Adding container columns 
  9370.  
  9371.         -  Filling the container 
  9372.  
  9373.      Adding notebook parts 
  9374.  
  9375.         -  Adding the notebook 
  9376.  
  9377.         -  Adding notebook pages 
  9378.  
  9379.  Personal notes: 
  9380.  
  9381.  
  9382. ΓòÉΓòÉΓòÉ 13.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  9383.  
  9384. The purpose of this chapter is to show how easy Visual Builder makes it to use 
  9385. IBM Open Class Library container and notebook controls. 
  9386.  
  9387. Container controls hold objects; for example, an OS/2 program folder holds 
  9388. program objects. You can display containers in different views including the 
  9389. following: 
  9390.  
  9391.      Icon view, like an OS/2 program folder. Container objects appear inside 
  9392.       the container as icons. 
  9393.  
  9394.      Details view. Attributes of container objects appear in tabular columns. 
  9395.       To use this view, you must define the container columns as well as the 
  9396.       container itself. 
  9397.  
  9398.      Tree view, for container objects that are related hierarchically. 
  9399.  
  9400.  Notebook controls present related information on tabbed pages that the user 
  9401.  can display sequentially or randomly. For an example of a notebook control, 
  9402.  open any Visual Builder settings editor. 
  9403.  
  9404.  
  9405. ΓòÉΓòÉΓòÉ 13.2. Adding Container Parts ΓòÉΓòÉΓòÉ
  9406.  
  9407. In this section, you set up a container in the OASkillView part to hold the 
  9408. OASkill* objects returned as a result of a user's skill query. The completed 
  9409. window looks like the following figure: 
  9410.  
  9411. This example is based on the OASkillView* part, found in oawin.vbb. Before 
  9412. constructing this new visual part, make sure that oanonvis.vbb is loaded into 
  9413. Visual Builder. 
  9414.  
  9415.    1. Create a new visual part and name it OASkillView. 
  9416.  
  9417.       A frame window and default canvas appear. 
  9418.  
  9419.    2. Select , the Lists category, from the left side of the parts palette. 
  9420.  
  9421.    3. Select , the IVBContainerControl* part, from the right side of the parts 
  9422.       palette and drop the part onto the default canvas. 
  9423.  
  9424.    4. Change the container's name to SkillCnr. 
  9425.  
  9426.    5. Resize the container part as needed. 
  9427.  
  9428.  The next step is Setting Up the Container. 
  9429.  
  9430.  
  9431. ΓòÉΓòÉΓòÉ 13.2.1. Setting Up the Container ΓòÉΓòÉΓòÉ
  9432.  
  9433. You set some container values in the container part and some in the container 
  9434. column part. Set the following values in the container part: 
  9435.  
  9436.      Title and title format 
  9437.      View style 
  9438.      Type of contained objects 
  9439.  
  9440.  Set the following values in the container column parts: 
  9441.  
  9442.      Column title and width 
  9443.      Attribute to appear in the column 
  9444.      Vertical and horizontal separators 
  9445.      Whether contents can be changed by the user 
  9446.  
  9447.  For information about container columns, see Adding Container Columns. 
  9448.  
  9449.  Setting the container titles 
  9450.  
  9451.    1. Open the settings notebook for SkillCnr. 
  9452.  
  9453.    2. Specify the general settings. In the Title Attributes group, type 
  9454.       Contractors Holding This Skill into the Title field. 
  9455.  
  9456.    3. Select both Show title and Show title separator. 
  9457.  
  9458.    4. Select the Left radio button for left title alignment. 
  9459.  
  9460.  Specifying the container type and layout 
  9461.  
  9462.    1. Select showDetailsView from the View type list box. 
  9463.  
  9464.    2. Scroll down on the General page. In the Container Item Attributes group, 
  9465.       type OASkill* into the Part type field. 
  9466.  
  9467.    3. Select contractorID from the Text drop-down combination box. The Text 
  9468.       field specifies which OASkill attribute would appear as text in the 
  9469.       container's icon view. 
  9470.  
  9471.    4. The Icon field specifies the icon to be used for each item in the 
  9472.       container. Type the following into the Icon field: 
  9473.  
  9474.             #IDynamicLinkLibrary("cppov33r").loadIcon(803)
  9475.  
  9476.       cppov33r.dll is the resource DLL containing the icons for this 
  9477.       application, and 803 is the resource ID for the skill icon that would 
  9478.       appear in the container's icon view. 
  9479.  
  9480.    5. Select the Refresh container after changes check box. 
  9481.  
  9482.    6. Select the OK push button to save and close the settings notebook. 
  9483.  
  9484.  
  9485. ΓòÉΓòÉΓòÉ 13.2.2. Adding Container Columns ΓòÉΓòÉΓòÉ
  9486.  
  9487. Once you have added a container, add container columns. This is a good idea 
  9488. even if you intend for the container to be used mainly as an icon view. 
  9489.  
  9490.    1. Select , the Lists category, from the parts palette. 
  9491.  
  9492.    2. Select the Sticky check box. 
  9493.  
  9494.    3. Select , the IContainerColumn* part, from the parts palette. 
  9495.  
  9496.    4. Drop two IContainerColumn* parts on the SkillCnr part. 
  9497.  
  9498.  Setting up the container columns 
  9499.  
  9500.    1. Open up the settings notebook for the first container column. 
  9501.  
  9502.    2. On the General settings page, type Contractor ID in the Heading text 
  9503.       field. 
  9504.  
  9505.    3. Specify the column's width (in pixels) in the Width field. For this 
  9506.       example, enter 200. 
  9507.  
  9508.    4. Specify the OASkill attribute to appear in this column. Select the Use 
  9509.       the Text attribute set in the container radio button because you want to 
  9510.       display the same information in this container column that the container 
  9511.       displays as text on the icon view. 
  9512.  
  9513.    5. Set the container so that its elements cannot be changed by the user. 
  9514.       Select the following from the Styles settings page: 
  9515.  
  9516.           For the readOnlyHeading style, select the On radio button. 
  9517.           For the readOnly style, select the On radio button. 
  9518.  
  9519.    6. Set a vertical separator for container column 1 only. For the 
  9520.       verticalSeparator style, select the On radio button. 
  9521.  
  9522.    7. Select the OK push button to close the settings notebook. 
  9523.  
  9524.  Repeat this procedure for the second container column, adjusting the width of 
  9525.  the column to fit. The second column is supposed to display the number of 
  9526.  years of experience each contractor has for a certain skill, so use the 
  9527.  following settings: 
  9528.  
  9529.      Select the Use an attribute from the part radio button 
  9530.      Choose yearsExp to populate the container column. 
  9531.      Do not add a vertical separator. 
  9532.  
  9533.  The next step is Filling the Container. 
  9534.  
  9535.  
  9536. ΓòÉΓòÉΓòÉ 13.2.3. Filling the Container ΓòÉΓòÉΓòÉ
  9537.  
  9538. The easiest way to fill the container is to use a collection part. The 
  9539. OASkillView part uses an IVSequence* part named SkillList. Basically, you 
  9540. manage container objects through the collection and use a single connection 
  9541. between it and the container to load the contents of the collection into the 
  9542. container. 
  9543.  
  9544. Adding the nonvisual parts 
  9545.  
  9546. The OASearch application uses static parts that are actually found in OAMain 
  9547. part. All nonvisual parts in this view except SkillList are variables that will 
  9548. be connected later to the actual parts. 
  9549.  
  9550.    1. Add an OASkill* part as a variable. Name it Skill. 
  9551.  
  9552.       For help on how to do this, see Adding a Variable to a Composite Part. 
  9553.  
  9554.    2. Add an OASkillBase* part as a variable. Name it SkillBase. 
  9555.  
  9556.    3. Add an IVSequence* part. Name it SkillList. 
  9557.  
  9558.    4. Add an IMessageBox* part to handle exceptions. 
  9559.  
  9560.  Populating the collection 
  9561.  
  9562.  The SkillBase part contains the action (getSkills) needed to populate the 
  9563.  skill list. The getSkills action takes two parameters, a skill description and 
  9564.  a sequence. Make the following connections: 
  9565.  
  9566.  From                             To 
  9567.  
  9568.  Skill,#skillName                 EntryField1,#text 
  9569.  
  9570.  PushButton1,#buttonClickEvent    SkillBase,#getSkills 
  9571.  
  9572.  Skill,#skillName                 The aSkillName parameter of the 
  9573.                                   PushButton1,#buttonClickEvent--> 
  9574.                                   SkillBase#getSkills connection 
  9575.  
  9576.  SkillList,#this                  The aList parameter of the 
  9577.                                   PushButton1,#buttonClickEvent--> 
  9578.                                   SkillBase#getSkills connection 
  9579.  
  9580.  To handle exceptions, connect the exceptionOccurred feature of the getSkills 
  9581.  connection to the showException feature of the message box part. 
  9582.  
  9583.  Connecting parts to fill the container 
  9584.  
  9585.  To fill the container, connect the this attribute of the SkillList part to the 
  9586.  items attribute of the container. 
  9587.  
  9588.  
  9589. ΓòÉΓòÉΓòÉ 13.3. Adding Notebook Parts ΓòÉΓòÉΓòÉ
  9590.  
  9591. The purpose of this section is to guide you through using a notebook part to 
  9592. create the OAContractorView part. The completed window looks like the following 
  9593. figure: 
  9594.  
  9595. The steps in creating a notebook are as follows: 
  9596.  
  9597.      Add the notebook and set it up. 
  9598.      Add notebook pages and set them up. 
  9599.  
  9600.  Begin by adding the notebook. 
  9601.  
  9602.  
  9603. ΓòÉΓòÉΓòÉ 13.3.1. Adding the Notebook ΓòÉΓòÉΓòÉ
  9604.  
  9605. Before constructing this new visual part, make sure that oanonvis.vbb is loaded 
  9606. into Visual Builder. 
  9607.  
  9608.    1. Create a new visual part. Call it OAContractorView. 
  9609.  
  9610.       A frame window and default canvas appear. 
  9611.  
  9612.    2. Delete the default canvas part from the frame window and resize the 
  9613.       window as necessary. 
  9614.  
  9615.    3. Select , the Composers category, from the left side of the parts palette. 
  9616.  
  9617.    4. Select , the INotebook* part, from the right side of the parts palette 
  9618.       and drop the part onto the frame window. 
  9619.  
  9620.  Specifying the notebook layout 
  9621.  
  9622.  You change the notebook's appearance using its settings notebook. As you make 
  9623.  selections, notice that the Preview area changes to reflect your choices. 
  9624.  
  9625.    1. Open the settings notebook for the notebook part. 
  9626.  
  9627.    2. On the General settings page, select the icon that represents the 
  9628.       orientation that you want for the notebook. For this example, select from 
  9629.       the Layout group. 
  9630.  
  9631.    3. From the Binding group, select the Spiral radio button. 
  9632.  
  9633.    4. From the Tab Shape group, select the Round radio button. 
  9634.  
  9635.    5. From the Justification group, select the two Center radio buttons. 
  9636.  
  9637.    6. Select the OK push button to close the settings notebook. 
  9638.  
  9639.  The next step is adding notebook pages. 
  9640.  
  9641.  
  9642. ΓòÉΓòÉΓòÉ 13.3.2. Adding Notebook Pages ΓòÉΓòÉΓòÉ
  9643.  
  9644. You add notebook pages using the notebook part's Composition Editor contextual 
  9645. menu. 
  9646.  
  9647.    1. To add the first page of the notebook, select Add initial page. 
  9648.  
  9649.    2. To add each additional page, select Add page before or Add page after. 
  9650.  For this example, add one page after the initial page. 
  9651.  
  9652.  Setting up the notebook page and tab 
  9653.  
  9654.    1. Open the settings notebook for the first notebook page. 
  9655.  
  9656.                      To open the settings for the notebook page instead of the 
  9657.                      canvas that is on the notebook page, move the mouse 
  9658.                      pointer to the small area around the canvas before opening 
  9659.                      the settings. 
  9660.  
  9661.    2. On the General page, type ContactPage into the Subpart name field. 
  9662.  
  9663.    3. Type Contact into the Tab text field. This text is what appears on the 
  9664.       notebook tab. 
  9665.  
  9666.    4. Type Vital statistics into the Status text field. This text is what 
  9667.       appears in the status area at the bottom of the notebook page. 
  9668.  
  9669.    5. On the Style page, select the On radio button for the following styles: 
  9670.  
  9671.           The autoPageSize style, to enable automatic sizing of the notebook 
  9672.            page 
  9673.  
  9674.           The statusText style, to enable display of the status text that you 
  9675.            entered in the previous step to be displayed 
  9676.  
  9677.           The majorTab style, to give the notebook page a major tab 
  9678.  
  9679.  Adding parts to a notebook page 
  9680.  
  9681.  Each notebook page initially contains an ICanvas* part. If you want to use a 
  9682.  different part, delete the ICanvas* part and select another part from the 
  9683.  Composers category, such as IMultiCellCanvas*. 
  9684.  
  9685.  Note:  A notebook page allows only one subpart, which should be a part from 
  9686.         the Composers category. You can, of course, add other subparts to the 
  9687.         Composers part. 
  9688.  
  9689.  The ContactPage subpart contains the primitive parts shown in the following 
  9690.  figure: 
  9691.  
  9692.  To see the other notebook pages, open the OAContractView part in oawin.vbb. 
  9693.  
  9694.  
  9695. ΓòÉΓòÉΓòÉ 14. Adding Menus to Your Application ΓòÉΓòÉΓòÉ
  9696.  
  9697.      What you will achieve 
  9698.  
  9699.      Types of menus and menu items 
  9700.  
  9701.      Adding a menu bar 
  9702.  
  9703.      Connecting the menu bar to the window 
  9704.  
  9705.      Adding menu choices 
  9706.  
  9707.      Adding menu separators 
  9708.  
  9709.      Connecting menu choices to actions 
  9710.  
  9711.  Personal notes: 
  9712.  
  9713.  
  9714. ΓòÉΓòÉΓòÉ 14.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  9715.  
  9716. The purpose of this section is to guide you through adding menus to the welcome 
  9717. window of the sample recruitment application. The completed menu parts and 
  9718. connections are shown in the following figure: 
  9719.  
  9720. First, read about types of menus. Then, begin with adding a menu bar to the 
  9721. window. 
  9722.  
  9723.  
  9724. ΓòÉΓòÉΓòÉ 14.2. Types of Menus and Menu Items ΓòÉΓòÉΓòÉ
  9725.  
  9726. In Visual Builder, you use the same menu part to build several different menu 
  9727. types, as follows: 
  9728.  
  9729.  Menu bars      This menu type is attached to a window. It appears horizontally 
  9730.                 under the window's title bar. 
  9731.  
  9732.  Pop-up menus   This menu type is attached to a control, such as an entry 
  9733.                 field, within the window. It appears vertically when the user 
  9734.                 selects the control and presses mouse button 2. 
  9735.  
  9736.  Cascaded menus This menu type is attached to a cascade menu item. 
  9737.  
  9738.                      If the cascade menu item is part of a menu bar, the 
  9739.                      cascaded menu appears below the menu item as a pull-down 
  9740.                      menu. 
  9741.  
  9742.                      If the cascade menu item is part of a pop-up menu, the 
  9743.                      cascaded menu appears beside the menu item. 
  9744.  
  9745.  Begin with adding a menu bar to the window. 
  9746.  
  9747.  
  9748. ΓòÉΓòÉΓòÉ 14.3. Adding a Menu Bar ΓòÉΓòÉΓòÉ
  9749.  
  9750. Begin by opening the visual part that contains the OASearch welcome window, the 
  9751. OAMain part. 
  9752.  
  9753.    1. Select , the Frame Extensions category, from the left side of the parts 
  9754.       palette. 
  9755.  
  9756.    2. Select , the IMenu* part, from the right side of the parts palette and 
  9757.       drop it on the free-form surface next to the window, as shown in the 
  9758.       following figure: 
  9759.  
  9760.    3. To add two of the menu choices to the menu bar, add two menu parts on top 
  9761.       of the menu part for the menu bar. 
  9762.  
  9763.       As you add each menu part, a cascade button part is added to the menu bar 
  9764.       and a connection is made between the cascade button part and the menu 
  9765.       part you added. This connection causes the menu part to be displayed when 
  9766.       the user selects the cascade button part. See the following figure: 
  9767.  
  9768.    4. Edit the text of the menu choices as shown in the following figure: To do 
  9769.       this, select each one and press Alt-mouse button 1. 
  9770.  
  9771.  
  9772. ΓòÉΓòÉΓòÉ 14.4. Connecting the Menu Bar to the Window ΓòÉΓòÉΓòÉ
  9773.  
  9774. To make the menu a menu bar, connect the this attribute of the IMenu* part to 
  9775. the menu attribute of the window part. Although the menu continues to appear 
  9776. vertically on the free-form surface, this connection defines the menu part as a 
  9777. menu bar. 
  9778.  
  9779.            Since the menu bar is shown outside the frame window, be sure to 
  9780.            leave enough space for it below the window title. 
  9781.  
  9782.  Making this same connection to a part other than a window part, such as a list 
  9783.  part, makes the menu part a pop-up menu instead of a menu bar. See Types of 
  9784.  Menus and Menu Items 
  9785.  
  9786.  Now that the menu bar has been added, the next step is adding the menu 
  9787.  choices. 
  9788.  
  9789.  
  9790. ΓòÉΓòÉΓòÉ 14.5. Adding Menu Choices ΓòÉΓòÉΓòÉ
  9791.  
  9792. Once the menu structure is complete, you need to add menu choices that do 
  9793. something other than open other menus. 
  9794.  
  9795.    1. Select , the Frame Extensions category, from the left side of the parts 
  9796.       palette. 
  9797.  
  9798.    2. Select , the IMenuItem* part, from the right side of the parts palette. 
  9799.  
  9800.    3. The position at which you click the mouse is where the part is added 
  9801.       within the menu. Drop menu items as follows: 
  9802.  
  9803.           One part as the last item in the Menu1 part 
  9804.           Four items in the Menu2 part 
  9805.           Two items in the Menu3 part 
  9806.  
  9807.  You can change the position of a menu choice part within the menu part by 
  9808.  using mouse button 2 to drag each item to a new position. Position these parts 
  9809.  and change their text as shown in the following figure: The next step is 
  9810.  connecting menu choices to actions. 
  9811.  
  9812.  
  9813. ΓòÉΓòÉΓòÉ 14.6. Adding Menu Separators ΓòÉΓòÉΓòÉ
  9814.  
  9815. Once you have added and edited the OAMain menu items, add a separator bar to 
  9816. Menu2 between Skill and General Information as follows: 
  9817.  
  9818.    1. Select , the Frame Extensions category, from the left side of the parts 
  9819.       palette. 
  9820.  
  9821.    2. Select , the IMenuSeparator* part, from the right side of the parts 
  9822.       palette. 
  9823.  
  9824.  
  9825. ΓòÉΓòÉΓòÉ 14.7. Connecting Menu Choices to Actions ΓòÉΓòÉΓòÉ
  9826.  
  9827. Once you have added menu choices, you can connect them to actions in this or 
  9828. other parts. As an example, connect the Exit menu bar item so that when the 
  9829. item is selected, the main window closes, as follows: 
  9830.  
  9831.  From part, feature            To part, feature 
  9832.  
  9833.  ExitMI,#commandEvent          FrameWindow,#close 
  9834.  
  9835.  Command events occur when a user selects a menu item, push button, or 
  9836.  accelerator key. In this case, the user' selection of Exit generates a command 
  9837.  event to perform the close action on the Frame Window. 
  9838.  
  9839.  Note:  You cannot promote menu item events to the part interface. 
  9840.  
  9841.  The other menu choices, shown in the following figure, connect to other parts 
  9842.  that are not on this free-form surface. These connections are completed in 
  9843.  Completing the Menu Bar. 
  9844.  
  9845.  
  9846. ΓòÉΓòÉΓòÉ 15. Adding Help To Visual Builder Applications ΓòÉΓòÉΓòÉ
  9847.  
  9848.      Introduction 
  9849.  
  9850.      Creating the help file 
  9851.  
  9852.      Providing context-sensitive help 
  9853.  
  9854.      Providing general help 
  9855.  
  9856.      Providing the application help window 
  9857.  
  9858.      Providing help for factory-generated frame windows 
  9859.  
  9860.      Providing a Help push button 
  9861.  
  9862.      Displaying fly-over help when the mouse pointer is over a part 
  9863.  
  9864.      Displaying help in an information area 
  9865.  
  9866.  Personal notes: 
  9867.  
  9868.  
  9869. ΓòÉΓòÉΓòÉ 15.1. Introduction ΓòÉΓòÉΓòÉ
  9870.  
  9871. In this section, you learn about adding different types of help to your 
  9872. application. Generally, in application development, you develop your user 
  9873. interface and then provide the necessary help panels. The basic help types are 
  9874. as follows: 
  9875.  
  9876.  Help Type                Description 
  9877.  
  9878.  Context-sensitive help   Help information for the current choice, object, or 
  9879.                           group of choices or objects. The user can display 
  9880.                           context-sensitive help by tabbing or cursoring to a 
  9881.                           subpart and doing either of the following: 
  9882.  
  9883.                               Pressing the F1 key. You do not have to do 
  9884.                                anything to make this happen. Presentation 
  9885.                                Manager handles it for you. 
  9886.  
  9887.                               Selecting the Help push button if you have 
  9888.                                provided one. See Providing a Help Push Button 
  9889.                                for information on how to do this. 
  9890.  
  9891.  General help             Help for a specific window, explaining the purpose of 
  9892.                           the window and how it operates. 
  9893.  
  9894.  To show you how to add help, we are going to write help for the main window of 
  9895.  the OASearch application, introduced in The Welcome Window section and shown 
  9896.  below. 
  9897.  
  9898.  The example we use in this chapter assumes that you have already built the 
  9899.  main view for the OASearch application. If you want to do the example along 
  9900.  with us, you must build this view first. 
  9901.  
  9902.  The first step in providing help is to create the help file. 
  9903.  
  9904.  
  9905. ΓòÉΓòÉΓòÉ 15.2. Creating the Help File ΓòÉΓòÉΓòÉ
  9906.  
  9907. Before we can connect the help, we must first create the help file. 
  9908.  
  9909. Writing the help 
  9910.  
  9911. For convenience sake, we have provided the help source so you do not have to 
  9912. retype it. Double-click here to see the help source and select Copy from the 
  9913. Services pull-down menu to copy the panel text to the system clipboard. Using 
  9914. your favorite editor, create a new file and paste this text into the file. 
  9915.  
  9916. Note:  Be sure to use an .ipf extension when naming the file. 
  9917.  
  9918.            When creating your own help files, try using a Project Smarts IPF 
  9919.            template, which provides the basic tags for creating online help 
  9920.            using the OS/2 Information Presentation Facility. For more 
  9921.            information on writing online help, refer to the OS/2 Information 
  9922.            Presentation Facility Guide and Reference. 
  9923.  
  9924.  The :h1 tags are heading tags. These tags cause IPF to create a new help panel 
  9925.  using the text on the tag as the panel's title. 
  9926.  
  9927.  The res parameter specifies the panel's resource number. See Providing 
  9928.  Context-sensitive Help to learn how these resource numbers are used. 
  9929.  
  9930.  The :i1 tags are index tags. These tags allow you to provide an index of help 
  9931.  topics for your application. If you provide a Help index choice in the Help 
  9932.  pull-down menu on the menu bar, the user can select this choice to display the 
  9933.  help index. When the user double-clicks on a topic in the help index, IPF 
  9934.  displays the help panel whose :h1 tag precedes the index tag in the help file. 
  9935.  
  9936.  Save this file with a name similar to cppov33.ipf. 
  9937.  
  9938.  Building the help file 
  9939.  
  9940.  Ensure that you have the IPF compiler installed on your system and that your 
  9941.  environment variables are set up to run the IPF compiler. The IPF compiler 
  9942.  comes with the OS/2 2.1 Toolkit and the OS/2 Warp Toolkit. 
  9943.  
  9944.  To build the help file, simply run the Information Presentation Facility (IPF) 
  9945.  compiler. For example, if you saved your help file with the name cppov33.ipf, 
  9946.  you would enter the following command in the directory where you saved your 
  9947.  file: 
  9948.  
  9949.   ipfc cppov33.ipf
  9950.  
  9951.  This command generates a file called cppov33.hlp. 
  9952.  
  9953.  You have now built your help file. The next step is to provide 
  9954.  context-sensitive help in your application. 
  9955.  
  9956.  
  9957. ΓòÉΓòÉΓòÉ <hidden> Sample Help Source Code ΓòÉΓòÉΓòÉ
  9958.  
  9959. :userdoc.
  9960. :title.Opportunities Abound Databases Help
  9961. :docprof toc=1 ctrlarea=page.
  9962. :ctrl ctrlid=buttons controls='ESC SEARCH PRINT' page.
  9963. :h1 res=9998.
  9964. General Help for the Opportunities Abound Databases
  9965. :i1.general help
  9966. :p.Text goes here.
  9967. :h1 res=9999.
  9968. Request for Skill Information Help
  9969. :i1.requesting skill information, help for
  9970. :p.Text goes here.
  9971. :h1 id=10000.
  9972. Skill Information Help
  9973. :i1.skill information, help for
  9974. :p.Text goes here.
  9975. :h1 res=10001.
  9976. Request for Contract Information Help
  9977. :i1.requesting contract information, help for
  9978. :p.Text goes here.
  9979. :h1 res=10002.
  9980. Contract Information Help
  9981. :i1.contract information, help for
  9982. :p.Text goes here.
  9983. :h1 res=10003.
  9984. Request for Contractor Information Help
  9985. :i1.requesting contractor information, help for
  9986. :p.Text goes here.
  9987. :h1 res=10004.
  9988. Contractor Information Help
  9989. :i1.contractor information, help for
  9990. :p.Text goes here.
  9991. :euserdoc.
  9992.  
  9993.  
  9994. ΓòÉΓòÉΓòÉ 15.3. Providing Context-sensitive Help ΓòÉΓòÉΓòÉ
  9995.  
  9996. This section tells you how to provide context-sensitive help for subparts in 
  9997. your application. 
  9998.  
  9999. For this example, we use the graphic push buttons on the window. 
  10000.  
  10001. To provide context-sensitive help for a subpart, do the following: 
  10002.  
  10003.    1. Open the cppov33.ipf file in your text editor and find the "Request for 
  10004.       Skill Information Help" heading. 
  10005.  
  10006.       Above this heading is the heading tag, :h1, with a res attribute. This 
  10007.       attribute contains the resource number for the help panel for the Skills 
  10008.       push button. 
  10009.  
  10010.    2. Open the settings notebook for the subpart, in this case the Skill push 
  10011.       button. 
  10012.  
  10013.    3. Select the Control page. It looks like the following figure: 
  10014.  
  10015.    4. Enter the resource number for the Skills push button help panel in the 
  10016.       Help panel id field. 
  10017.  
  10018.       When you generate the code for your application, Visual Builder creates a 
  10019.       help table in the resource (.rc) file that it generates and inserts this 
  10020.       number into the help table. 
  10021.  
  10022.    5. If the Enable check box is not checked, select it. 
  10023.  
  10024.    6. Select the OK push button. 
  10025.  
  10026.    7. Repeat steps 2 through 6 for the Contract push button and the Contractor 
  10027.       push button. Use the resource numbers for the "Request for Contract 
  10028.       Information Help" and "Request for Contractor Information Help", 
  10029.       respectively. 
  10030.  
  10031.  You have now provided context-sensitive help for the push buttons. The next 
  10032.  step is to provide general help in your application. 
  10033.  
  10034.  
  10035. ΓòÉΓòÉΓòÉ 15.4. Providing General Help ΓòÉΓòÉΓòÉ
  10036.  
  10037. This section tells you how to provide general help for your application. For 
  10038. this example, we use the frame window. 
  10039.  
  10040. To provide context-sensitive help for your application, do the following: 
  10041.  
  10042.    1. Open the cppov33.ipf file in your text editor and find the "General Help 
  10043.       for the Opportunities Abound Databases" heading. 
  10044.  
  10045.       Above this heading is the heading tag, :h1, with a res attribute. This 
  10046.       attribute contains the resource number for the general information help 
  10047.       panel. 
  10048.  
  10049.    2. Open the settings notebook for the subpart, in this case the frame 
  10050.       window. 
  10051.  
  10052.    3. Select the Control page. It looks like the following figure: 
  10053.  
  10054.    4. Enter the resource number for the general information help panel in the 
  10055.       Help panel id field. 
  10056.  
  10057.       When you generate the code for your application, Visual Builder creates a 
  10058.       help table in the resource (.rc) file that it generates and inserts this 
  10059.       number into the help table. 
  10060.  
  10061.    5. If the Enable check box is not checked, select it. 
  10062.  
  10063.    6. Select the OK push button. 
  10064.  
  10065.  You have now provided general help for the main window. The next step is to 
  10066.  provide a help window to display the help panels in. 
  10067.  
  10068.  
  10069. ΓòÉΓòÉΓòÉ 15.5. Providing the Application Help Window ΓòÉΓòÉΓòÉ
  10070.  
  10071. Now that you have added the context-sensitive help and the general help for the 
  10072. main window, you need a help window to display the help panels in. You must 
  10073. place an IHelpWindow* part on the free-form surface to give Visual Builder a 
  10074. window in which to display the help information. The default owner of the 
  10075. IHelpWindow* part is the primary part for your application. Therefore, no 
  10076. connections are required. 
  10077.  
  10078. To add a help window to your application, do the following: 
  10079.  
  10080.    1. Select , the Other category, on the parts palette. 
  10081.  
  10082.    2. Select , the IHelpWindow* part, and place it on the free-form surface. 
  10083.  
  10084.    3. Open the settings notebook for the IHelpWindow* part. It looks like the 
  10085.       following figure: 
  10086.  
  10087.    4. In the Title field, enter the title of the help window. 
  10088.  
  10089.       This must be the same title that you entered on the :title tag in your 
  10090.       .ipf file. 
  10091.  
  10092.    5. In the Help libraries field, enter the name of the help file that you 
  10093.       compiled, such as oasearch.hlp. 
  10094.  
  10095.       If you had created multiple help files for your application, you would 
  10096.       enter all of their names in this field. 
  10097.  
  10098.    6. We recommend that you leave the Help table id field empty and let Visual 
  10099.       Builder generate it for you unless you need a specific help table ID. 
  10100.       Otherwise, you could have conflicts in your resource (.rc) file. 
  10101.  
  10102.    7. Select the OK push button. 
  10103.  
  10104.  
  10105. ΓòÉΓòÉΓòÉ 15.6. Providing Help for Factory-generated Frame Windows ΓòÉΓòÉΓòÉ
  10106.  
  10107. You can associate a help window with a part that is generated by an object 
  10108. factory if the base class of that part is IFrameWindow*. To do this, you can do 
  10109. either of the following: 
  10110.  
  10111.      Edit the part that the object factory generates, place an IHelpWindow* 
  10112.       part on the free-form surface next to it, and do all the things described 
  10113.       in the preceding sections to use the help window properly. Repeat this 
  10114.       step for each IFrameWindow*-based part that is generated by an object 
  10115.       factory. 
  10116.  
  10117.       You should use this method if you have created multiple help library 
  10118.       (.hlp) files for your library instead of putting all of your help panels 
  10119.       in one library file. 
  10120.  
  10121.      Place an IHelpWindow* part on the free-form surface in the same view with 
  10122.       the object factory if you have created only one help library file for all 
  10123.       of your help panels. Then, do the following: 
  10124.  
  10125.         1. Open the settings notebook for the IHelpWindow* part. 
  10126.  
  10127.         2. Enter the help window title and the name of the library (.hlp) file. 
  10128.  
  10129.         3. Close the settings notebook by selecting the OK push button. 
  10130.  
  10131.         4. Connect the newEvent feature of the object factory to the 
  10132.            setAssociatedWindow action of the help window. 
  10133.  
  10134.         5. Repeat step 4 for each object factory in the view. 
  10135.  
  10136.         6. Edit each IFrameWindow*-based part that an object factory generates 
  10137.            and specify the appropriate help panel IDs for the subparts that you 
  10138.            want to provide help for. Each help panel ID must be a resource ID 
  10139.            in the library file that you specified in step 2. 
  10140.  
  10141.  
  10142. ΓòÉΓòÉΓòÉ 15.7. Providing a Help Push Button ΓòÉΓòÉΓòÉ
  10143.  
  10144. The main window of the OASearch application, which we have been using for this 
  10145. help example, does not contain a Help push button. However, many applications 
  10146. provide such a push button to give users quick and easy access to the help 
  10147. information that the application provides. 
  10148.  
  10149. To provide a Help push button in your application, do the following: 
  10150.  
  10151.    1. Select , the Buttons category, in the left-hand column on the parts 
  10152.       palette. 
  10153.  
  10154.    2. Select , the IPushButton* part, and place it where you want it to be. 
  10155.  
  10156.    3. Change the text on the push button to Help. 
  10157.  
  10158.    4. Open the settings notebook for the push button. 
  10159.  
  10160.    5. Select the Styles tab. 
  10161.  
  10162.    6. Find help on the Styles page and select the On radio button. 
  10163.  
  10164.       This style turns a regular push button into a help push button. 
  10165.  
  10166.    7. On the same page, find noPointerFocus and select the On radio button. 
  10167.  
  10168.       This style keeps the Help push button from getting the input focus when a 
  10169.       user clicks on it. By setting this style, you enable your application to 
  10170.       display help for the part that has the input focus when a user clicks the 
  10171.       Help push button. Otherwise, the user sees the help panel that you assign 
  10172.       to the Help push button. 
  10173.  
  10174.       When this style is set, the user must use the cursor keys to set the 
  10175.       input focus on the Help push button. After doing this, the user can click 
  10176.       on the Help push button to display the help panel that you assign to it. 
  10177.  
  10178.    8. Select the OK push button to close the settings notebook. 
  10179.  
  10180.  You now have a Help push button. If you have followed the steps in the 
  10181.  preceding sections, clicking this button causes the contextual help panel for 
  10182.  the part that currently has the input focus to be displayed. If no part has 
  10183.  the focus, the main help panel for the window is displayed. The behavior of 
  10184.  the Help push button is identical to that of the F1 key. 
  10185.  
  10186.  To provide a help panel for the Help push button itself, follow the 
  10187.  instructions in Providing Context-sensitive Help. 
  10188.  
  10189.  
  10190. ΓòÉΓòÉΓòÉ 15.8. Displaying Fly-over Help When the Mouse Pointer Is Over a Part ΓòÉΓòÉΓòÉ
  10191.  
  10192. Another type of help that you can provide in your application is called 
  10193. fly-over help, which is intended to provide instant help for novice users. This 
  10194. type of help consists of a text string that your application displays when the 
  10195. user positions the mouse pointer over a subpart, such as a push button or list 
  10196. box. The text string should be short and precise, giving the user information 
  10197. such as the purpose of the subpart. 
  10198.  
  10199. Your application can provide the following types of fly-over help: 
  10200.  
  10201.      A short text string that your application displays next to the subpart 
  10202.       that the mouse pointer is over 
  10203.  
  10204.      A longer text string that your application displays in a text control 
  10205.  
  10206.  Providing fly-over help for a subpart 
  10207.  
  10208.  To provide fly-over help for a subpart, do the following: 
  10209.  
  10210.    1. Place an IVBFlyText* part on the free-form surface by doing the 
  10211.       following: 
  10212.  
  10213.         a. Select , the Other category, on the parts palette. 
  10214.  
  10215.         b. Select , the IVBFlyText* part, and place it on the free-form 
  10216.            surface. 
  10217.  
  10218.    2. Add fly-over help text to one or more subparts by doing the following: 
  10219.  
  10220.         a. Open the settings notebook for a subpart, such as an entry field or 
  10221.            push button. 
  10222.  
  10223.         b. Select the Control notebook tab. 
  10224.  
  10225.         c. Enter fly-over text strings in the Fly over short text field, the 
  10226.            Fly over long text field, or both. 
  10227.  
  10228.            Text that you enter in the Fly over short text field is displayed in 
  10229.            a pop-up window next to a subpart when the user positions the mouse 
  10230.            pointer over that subpart. 
  10231.  
  10232.            Text that you enter in the Fly over long text field is displayed in 
  10233.            a text control that you specify. For example, you might add an 
  10234.            information area to a window and display the long fly-over help text 
  10235.            there. See Displaying Long Fly-over Text In an Information Area to 
  10236.            see how this is done. 
  10237.  
  10238.                           If one of your application views contains two or more 
  10239.                           frame windows, do not use the same IVBFlyText* part 
  10240.                           to assign long fly-over text strings to text controls 
  10241.                           in each window. If you do, your fly-over text 
  10242.                           probably will not appear in the window that you 
  10243.                           expect it to appear in. 
  10244.  
  10245.                           For example, suppose your view contains two frame 
  10246.                           windows: one that is displayed when your application 
  10247.                           starts and another one that is displayed when a menu 
  10248.                           item in the first window is selected. In this case, 
  10249.                           place two IVBFlyText* parts on the free-form surface. 
  10250.                           The first IVBFlyText* part is associated by default 
  10251.                           with the window that is displayed when your 
  10252.                           application starts. However, you must specify the 
  10253.                           owner of the second IVBFlyText* part by opening the 
  10254.                           IVBFlyText* part's settings notebook and entering the 
  10255.                           name of the owner part in the Owner field, such as 
  10256.                           iFrameWindow1. 
  10257.  
  10258.         d. Select the OK push button to save the text strings that you just 
  10259.            entered. 
  10260.  
  10261.  That is all you need to do. There are no connections to make. 
  10262.  
  10263.  
  10264. ΓòÉΓòÉΓòÉ 15.9. Displaying Help in an Information Area ΓòÉΓòÉΓòÉ
  10265.  
  10266. There are times when it is helpful to provide an information area in an 
  10267. application window that your application can use to give the user feedback. For 
  10268. example, the information area might let the user know whether the application 
  10269. performed an operation successfully or it might provide a description of a menu 
  10270. choice. 
  10271.  
  10272. Visual Builder provides the IInfoArea* part that you can use for this purpose. 
  10273. An information area is considered to be an extension of a frame window. You can 
  10274. only add it to an IFrameWindow* part. Visual Builder positions the information 
  10275. area at the bottom of the frame window's client area. 
  10276.  
  10277. The following sections provide specific information about displaying help in an 
  10278. information area: 
  10279.  
  10280.      Adding an information area to a frame window 
  10281.  
  10282.      Displaying help for menu choices in an information area 
  10283.  
  10284.      Displaying information about successful actions 
  10285.  
  10286.  
  10287. ΓòÉΓòÉΓòÉ 15.9.1. Adding an Information Area to a Frame Window ΓòÉΓòÉΓòÉ
  10288.  
  10289. To add an information area to a frame window, do the following: 
  10290.  
  10291.    1. Select , the Frame Extensions category, on the parts palette. 
  10292.  
  10293.    2. Select , the IInfoArea* part. 
  10294.  
  10295.    3. Move the mouse pointer over the title bar or window border of the frame 
  10296.       window and click mouse button 1. 
  10297.  
  10298.       Visual Builder places an information area at the bottom of the frame 
  10299.       window. 
  10300.  
  10301.    4. Open the settings notebook for the information area. 
  10302.  
  10303.    5. Enter text that you want your application to display in the following 
  10304.       fields: 
  10305.  
  10306.       Disabled text 
  10307.              Text to display when the selected menu choice is disabled. 
  10308.  
  10309.       Inactive text 
  10310.              Text to display when no menu choice is selected. 
  10311.  
  10312.       Missing text 
  10313.              Text to display when the information area cannot find and display 
  10314.              specific help for a menu choice. 
  10315.  
  10316.  
  10317. ΓòÉΓòÉΓòÉ 15.9.2. Displaying Help for Menu Choices in an Information Area ΓòÉΓòÉΓòÉ
  10318.  
  10319. To display help text for menu choices in an information area, do the following: 
  10320.  
  10321.    1. Create the menu bar and pull-down menus for your application. 
  10322.  
  10323.    2. Open the settings notebook for each menu choice. 
  10324.  
  10325.    3. Enter a description of the menu choice in the Info area text field. 
  10326.  
  10327.    4. Select the OK push button to save the description you just entered. 
  10328.  
  10329.  
  10330. ΓòÉΓòÉΓòÉ 15.9.3. Displaying Long Fly-over Text In an Information Area ΓòÉΓòÉΓòÉ
  10331.  
  10332. Earlier in this chapter, we showed you how to add an IVBFlyText* part and 
  10333. display a short text string in a pop-up window. This section shows you how to 
  10334. display a longer text string in an IInfoArea* part, although you can use any 
  10335. text control, such as an IEntryField*. 
  10336.  
  10337. To display a long fly-over text string in an information area, do the 
  10338. following. 
  10339.  
  10340. Note:  The following steps assume that you have already added an IVBFlyText* 
  10341.        part and an IInfoArea* part to a frame window. If you have not, you 
  10342.        should complete the steps in the following sections and then return 
  10343.        here. 
  10344.  
  10345.      Displaying Fly-over Help When the Mouse Pointer Is Over a Part 
  10346.  
  10347.       When following these steps, make sure you enter a text string in the Fly 
  10348.       over long text field in the settings notebook for a subpart, such as an 
  10349.       entry field or push button. 
  10350.  
  10351.      Adding an Information Area to a Frame Window 
  10352.  
  10353.    1. Display the connection menu for the information area. 
  10354.  
  10355.    2. Select the this attribute. 
  10356.  
  10357.    3. Display the connection menu for the fly-over text part. 
  10358.  
  10359.    4. Select the longTextControl attribute. 
  10360.  
  10361.  That is all you have to do. 
  10362.  
  10363.  
  10364. ΓòÉΓòÉΓòÉ 15.9.4. Displaying Information about Successful Actions ΓòÉΓòÉΓòÉ
  10365.  
  10366. One way to make your applications more user-friendly is to provide feedback to 
  10367. the user when an action or member function performs successfully, such as the 
  10368. successful completion of an action that is triggered by a buttonClickEvent 
  10369. feature. We recommend that you display this information in an IInfoArea* part. 
  10370.  
  10371. To display information in an information area when an action or member function 
  10372. completes successfully, do the following: 
  10373.  
  10374.    1. Create an event-to-attribute connection using the text attribute of the 
  10375.       IInfoArea* part as the target. The source event can be one of the 
  10376.       following: 
  10377.  
  10378.           The same event that triggered the action or member function 
  10379.  
  10380.            If the action or member function was triggered by an event, you can 
  10381.            use the same event, such as the buttonClickEvent or commandEvent 
  10382.            feature. In this case, be sure to check the connection order to make 
  10383.            sure the event-to-action or event-to-member function connection 
  10384.            occurs before the event-to-attribute connection. 
  10385.  
  10386.           The actionResult event of the connection that triggered the action 
  10387.            or member function 
  10388.  
  10389.            All connections have both an actionResult event and an actionResult 
  10390.            attribute. Therefore, be sure you use the actionResult event as the 
  10391.            source of the connection. 
  10392.  
  10393.    2. Double-click on the connection you just made to open the settings window 
  10394.       for the connection. 
  10395.  
  10396.    3. Select the Set parameters push button to open the Constant Parameter 
  10397.       Value Settings window. 
  10398.  
  10399.    4. In the text field, enter the text string that you want to assign to the 
  10400.       text attribute. 
  10401.  
  10402.       Your application will display this text string in the information area 
  10403.       each time the action or member function completes successfully. 
  10404.  
  10405.    5. Select the OK push button to close the Constant Parameter Value Settings 
  10406.       window. 
  10407.  
  10408.    6. Select the Cancel push button to close the connection settings window. 
  10409.  
  10410.  
  10411. ΓòÉΓòÉΓòÉ 16. Integrating Visual Parts into a Single Application ΓòÉΓòÉΓòÉ
  10412.  
  10413.      What you will achieve 
  10414.  
  10415.      Adding nonvisual support parts to the primary part 
  10416.  
  10417.      Adding static visual parts 
  10418.  
  10419.      Adding visual parts as dynamic instances 
  10420.  
  10421.         -  Adding and setting Object Factory parts 
  10422.  
  10423.         -  Adding variable parts 
  10424.  
  10425.         -  Connecting to the Object Factory parts 
  10426.  
  10427.         -  Connecting the Object Factory parts to their corresponding variable 
  10428.            parts 
  10429.  
  10430.      Making the final connections 
  10431.  
  10432.         -  Connecting the nonvisual parts to the variables that represent them 
  10433.  
  10434.         -  Completing the menu bar 
  10435.  
  10436.  Personal notes: 
  10437.  
  10438.  
  10439. ΓòÉΓòÉΓòÉ 16.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  10440.  
  10441. In this chapter, you combine all visual parts of the OASearch sample 
  10442. application in preparation for generating code and compiling. This chapter 
  10443. includes the following tasks: 
  10444.  
  10445.      Adding nonvisual support parts to the primary part 
  10446.      Adding static visual parts 
  10447.      Adding visual parts as dynamic instances 
  10448.      Making the final connections 
  10449.  
  10450.  To follow this example, load oanonvis.vbb and oawin.vbb into Visual Builder. 
  10451.  
  10452.  
  10453. ΓòÉΓòÉΓòÉ 16.2. Adding Nonvisual Support Parts to the Primary Part ΓòÉΓòÉΓòÉ
  10454.  
  10455. For this example, refer to the primary view, OAMain, in oawin.vbb, shown in the 
  10456. following figure: 
  10457.  
  10458.    1. Begin by building the primary part as you would any IFrameWindow*-based 
  10459.       part. For information about building the menu bar, see Adding Menus to 
  10460.       Your Application. 
  10461.  
  10462.    2. The OASearch application starts up with a small number of static 
  10463.       nonvisual instances to support the visual parts. Add the following parts: 
  10464.  
  10465.           OAContractor*.  Name it Contractor. 
  10466.           OAContract*.  Name it Contract. 
  10467.           OASkill*.  Name it Skill. 
  10468.           OASkillBase*.  Name it SkillBase. 
  10469.  
  10470.       You must connect these part instances to the variables that represent 
  10471.       them in the other visual parts. First, you must add the visual parts. 
  10472.  
  10473.  
  10474. ΓòÉΓòÉΓòÉ 16.3. Adding Static Parts ΓòÉΓòÉΓòÉ
  10475.  
  10476. One visual part, OAGenInfo, exists statically in the OASearch application as a 
  10477. modal window. The disadvantage of using static visual parts is that once the 
  10478. user closes the window, the part is destroyed and cannot be instantiated again 
  10479. in the same session. 
  10480.  
  10481. Add the OAGenInfo* part. Name it VBDevelopment. You must also connect 
  10482. OAGEnInfo* to the menu item that causes it to display. For details, see 
  10483. Completing the Menu Bar. 
  10484.  
  10485.  
  10486. ΓòÉΓòÉΓòÉ 16.4. Adding Visual Parts as Dynamic Instances ΓòÉΓòÉΓòÉ
  10487.  
  10488. All OASearch visual parts except for OAMain and OAGenInfo are created at run 
  10489. time as the user requests them from a menu or button selection. The dynamic 
  10490. windows are represented in the OAMain part by Object Factory parts. Like static 
  10491. visual parts, dynamic visual parts are destroyed when the user closes them. 
  10492. However, the existence of the Object Factory enables the creation of a new 
  10493. instance of that same part the next time the user requests it. 
  10494.  
  10495. Like variable parts, Object Factory parts are placeholders for other parts. 
  10496. Each Object Factory part is set to the part it represents. The Object Factory 
  10497. part works in tandem with a variable part that represents the dynamic part 
  10498. instance. You can use Object Factory parts to create both visual and nonvisual 
  10499. parts. 
  10500.  
  10501. Unlike variable parts, Object Factory parts run the corresponding part class 
  10502. constructor, creating a new instance. Variable parts merely stand in for 
  10503. instances created elsewhere. 
  10504.  
  10505. Implementing dynamic parts involves the following tasks: 
  10506.  
  10507.      Adding and setting Object Factory parts 
  10508.      Adding variable parts 
  10509.      Connecting to the Object Factory parts 
  10510.      Connecting the Object Factory parts to the corresponding variable parts 
  10511.  
  10512.  The first step is adding and setting Object Factory parts. 
  10513.  
  10514.  
  10515. ΓòÉΓòÉΓòÉ 16.4.1. Adding and Setting Object Factory Parts ΓòÉΓòÉΓòÉ
  10516.  
  10517. Before you can use Object Factory parts, you must have created the part classes 
  10518. to be represented. Before you start, be sure to load the .vbb files that 
  10519. contain those parts into Visual Builder. 
  10520.  
  10521. Adding the Object Factory parts 
  10522.  
  10523.    1. Select , the Models category, from the left side of the parts palette. 
  10524.  
  10525.    2. Select the Sticky check box. 
  10526.  
  10527.    3. Select , the Object Factory part, from the right side of the parts 
  10528.       palette. 
  10529.  
  10530.    4. Drop six Object Factory parts on the free-form surface. 
  10531.  
  10532.    5. Unload the mouse pointer by selecting , the Selection tool, from the 
  10533.       Visual Builder tool bar. 
  10534.  
  10535.  Setting an Object Factory part 
  10536.  
  10537.    1. Change the part name using the Composition Editor contextual menu. 
  10538.  
  10539.       In the OASearch example, the Object Factory parts are named as follows: 
  10540.  
  10541.       ConQFac             Request for Contract Information window 
  10542.       ConVFac             Contract Information window 
  10543.       CtrQFac             Request for Contractor Information window 
  10544.       CtrVFac             Contractor Information window 
  10545.       SklQFac             Request for Skill Information window 
  10546.       SklVFac             Skill Information window 
  10547.  
  10548.    2. Change the part type from the default (IStandardNotifier*) using the 
  10549.       Composition Editor contextual menu. 
  10550.  
  10551.       In the OASearch example, the Object Factory parts have the following 
  10552.       types: 
  10553.  
  10554.       ConQFac             OAQueryContract* 
  10555.       ConVFac             OAContractView* 
  10556.       CtrQFac             OAQueryContractor* 
  10557.       CtrVFac             OAContractorView* 
  10558.       SklQFac             OAQuerySkill* 
  10559.       SklVFac             OASkillView* 
  10560.  
  10561.    3. Set the Object Factory part to automatically delete each instance, as 
  10562.       follows: 
  10563.  
  10564.         a. Open the settings notebook for the part. 
  10565.         b. Switch to the General page. 
  10566.         c. Select the AutoDelete check box. 
  10567.  
  10568.  
  10569. ΓòÉΓòÉΓòÉ 16.4.2. Adding Variable Parts ΓòÉΓòÉΓòÉ
  10570.  
  10571. When used with Object Factory parts, variable parts represent the newly created 
  10572. part instance. Add and set variable parts as follows: 
  10573.  
  10574.  ContractQ      Set the type to OAQueryContract*. 
  10575.  ContractorQ    Set the type to OAQueryContractor*. 
  10576.  SkillQ         Set the type to OAQuerySkill*. 
  10577.  ContractV      Set the type to OAContractView*. 
  10578.  ContractorV    Set the type to OAContractorView*. 
  10579.  SkillV         Set the type to OASkillView*. 
  10580.  
  10581.  For more information on variables, see Adding a Variable to a Composite Part. 
  10582.  
  10583.  
  10584. ΓòÉΓòÉΓòÉ 16.4.3. Connecting to the Object Factory Parts ΓòÉΓòÉΓòÉ
  10585.  
  10586. Once you have added and set both the Object Factory and variable parts, connect 
  10587. the IGraphicPushButton* parts on the welcome window to the Object Factory parts 
  10588. representing the query windows, as follows: 
  10589.  
  10590.  
  10591.  From part, feature             To part, feature
  10592.  
  10593.  ContractGB, #buttonClickEvent  ConQFac, #new
  10594.  
  10595.  ContractorGB, #                CtrQFac, #new
  10596.  buttonClickEvent
  10597.  
  10598.  SkillGB, #buttonClickEvent     SklQFac, #new
  10599.  
  10600. Next, connect promoted button actions in the query windows to the Object 
  10601. Factory parts representing the information windows, as follows: 
  10602.  
  10603.  
  10604.  From part, feature             To part, feature
  10605.  
  10606.  ContractQ, #okPB               ConVFac, #new
  10607.  ButtonClickEvent
  10608.  
  10609.  ContractorQ, #okPB             CtrVFac, #new
  10610.  ButtonClickEvent
  10611.  
  10612.  SkillQ, #okPBButtonClickEvent  SklVFac, #new
  10613.  
  10614.  
  10615. ΓòÉΓòÉΓòÉ 16.4.4. Connecting the Object Factory Parts to Their Corresponding Variable Parts ΓòÉΓòÉΓòÉ
  10616.  
  10617. Once you have set both Object Factory and variable parts, you must connect 
  10618. them. In OAMain, the connections vary depending on whether the window is modal. 
  10619. Modal windows retain focus until they are closed; the user cannot switch focus 
  10620. to another window without closing the modal window. In OAMain, OAGenInfo and 
  10621. the query windows are modal; the other windows are modeless. 
  10622.  
  10623. Connections for modal windows 
  10624.  
  10625. Make the following connections for the query window parts. The connections for 
  10626. OAGenInfo* are listed in Completing the Menu Bar. 
  10627.  
  10628.  
  10629.  From part, feature             To part, feature
  10630.  
  10631.  ConQFac, #newEvent             ContractQ, #this
  10632.  
  10633.  ConQFac, #newEvent             ContractQ, #setFocus
  10634.  
  10635.  ConQFac, #newEvent             ContractQ, #showModally
  10636.  
  10637.  CtrQFac, #newEvent             ContractorQ, #this
  10638.  
  10639.  CtrQFac, #newEvent             ContractorQ, #setFocus
  10640.  
  10641.  CtrQFac, #newEvent             ContractorQ, #showModally
  10642.  
  10643.  SklQFac, #newEvent             SkillQ, #this
  10644.  
  10645.  SklQFac, #newEvent             SkillQ, #setFocus
  10646.  
  10647.  SklQFac, #newEvent             SkillQ, #showModally
  10648.  
  10649. Connections for modeless windows 
  10650.  
  10651. Now make the following connections for the modeless information windows: 
  10652.  
  10653.  
  10654.  From part, feature             To part, feature
  10655.  
  10656.  ConVFac, #newEvent             ContractV, #this
  10657.  
  10658.  ConVFac, #newEvent             ContractV, #setFocus
  10659.  
  10660.  ConVFac, #newEvent             ContractV, #visible
  10661.  
  10662.  CtrVFac, #newEvent             ContractorV, #this
  10663.  
  10664.  CtrVFac, #newEvent             ContractorV, #setFocus
  10665.  
  10666.  CtrVFac, #newEvent             ContractorV, #visible
  10667.  
  10668.  SklVFac, #newEvent             SkillV, #this
  10669.  
  10670.  SklVFac, #newEvent             SkillV, #setFocus
  10671.  
  10672.  SklVFac, #newEvent             SkillV, #visible
  10673.  
  10674.  
  10675. ΓòÉΓòÉΓòÉ 16.5. Making the Final Connections ΓòÉΓòÉΓòÉ
  10676.  
  10677. With all parts represented in the primary part, you have only to make the final 
  10678. connections. This includes the following: 
  10679.  
  10680.      Connecting the nonvisual parts to their corresponding variable parts 
  10681.      Completing the menu bar 
  10682.  
  10683.  
  10684. ΓòÉΓòÉΓòÉ 16.5.1. Connecting the Nonvisual Parts to the Variables that Represent Them ΓòÉΓòÉΓòÉ
  10685.  
  10686. Each visual part contains promoted variables as placeholders for the static 
  10687. nonvisual parts dropped in OAMain. Now, connect the static parts to the 
  10688. variables that represent them as follows: 
  10689.  
  10690.  
  10691.  From part, feature             To part, feature
  10692.  
  10693.  Contract, #this                ConQFac, #contract
  10694.  
  10695.  Contract, #this                ConVFac, #contract
  10696.  
  10697.  Contract, #this                CtrVFac, #contract
  10698.  
  10699.  Contractor, #this              CtrQFac, #contractor
  10700.  
  10701.  Contractor, #this              CtrVFac, #contractor
  10702.  
  10703.  Skill, #this                   SklQFac, #skill
  10704.  
  10705.  Skill, #this                   SklVFac*, #skill
  10706.  
  10707.  SkillBase, #this               SklQFac, #skillBase
  10708.  
  10709.  SkillBase, #this               SklVFac, #skillBase
  10710.  
  10711.  SkillBase, #this               CtrQFac, #skillBase
  10712.  
  10713.  SkillBase, #this               CtrVFac, #skillBase
  10714.  
  10715.  
  10716. ΓòÉΓòÉΓòÉ 16.5.2. Completing the Menu Bar ΓòÉΓòÉΓòÉ
  10717.  
  10718. Now that all parts appear on the free-form surface, you can complete the menu 
  10719. bar. The connections echo those made in Connecting to the Object Factory Parts. 
  10720.  
  10721. Connections from the View submenu 
  10722.  
  10723.  
  10724.  From part, feature             To part, feature
  10725.  
  10726.  ContractMI, #commandEvent      ConQFac, #new
  10727.  
  10728.  ContractorMI, #commandEvent    CtrQFac, #new
  10729.  
  10730.  SkillMI, #commandEvent         SklQFac, #new
  10731.  
  10732.  GenInfoMI, #commandEvent       VBDevelopment, #setFocus
  10733.  
  10734.  GenInfoMI, #commandEvent       VBDevelopment, #showModally
  10735.  
  10736. Connections from the Edit submenu 
  10737.  
  10738.  
  10739.  From part, feature             To part, feature
  10740.  
  10741.  ContractMI, #commandEvent      ConVFac, #new
  10742.  
  10743.  ContractorMI #commandEvent     CtrVFac, #new
  10744.  
  10745. Once all connections are complete, you are ready to generate code. Make sure to 
  10746. save your work. 
  10747.  
  10748.  
  10749. ΓòÉΓòÉΓòÉ 17. Generating Source Code for Parts and Applications ΓòÉΓòÉΓòÉ
  10750.  
  10751.      What you will achieve 
  10752.  
  10753.      Preparing for source code generation: 
  10754.  
  10755.         -  Setting up Visual Builder to generate make files 
  10756.  
  10757.         -  Setting up Visual Builder projects to use WorkFrame's makemake 
  10758.            program 
  10759.  
  10760.      Generating C++ source code for individual parts 
  10761.  
  10762.      Source files created during part code generation 
  10763.  
  10764.      Generating C++ source code for your application's main() function 
  10765.  
  10766.      Source files created during generation of main() function code 
  10767.  
  10768.      Preparing generated files for compilation 
  10769.  
  10770.         -  Specifying additional libraries in the make file 
  10771.  
  10772.         -  Specifying debug options for the compiler and linker programs 
  10773.  
  10774.      Compiling and linking your application 
  10775.  
  10776.  Personal notes: 
  10777.  
  10778.  
  10779. ΓòÉΓòÉΓòÉ 17.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  10780.  
  10781. All work that you do using Visual Builder is stored within the Visual Builder 
  10782. development environment, including information about visual parts, nonvisual 
  10783. parts, and connections. 
  10784.  
  10785. This chapter describes all you need to know about getting your Visual Builder 
  10786. application ready for others to use. The topics covered are as follows: 
  10787.  
  10788.      Preparing for source code generation 
  10789.  
  10790.      Generating C++ source code for the individual parts used within your 
  10791.       application 
  10792.  
  10793.      Generating C++ source code for your application (the main() function) 
  10794.  
  10795.      Preparing generated files for compilation 
  10796.  
  10797.      Compiling and linking your application 
  10798.  
  10799.  
  10800. ΓòÉΓòÉΓòÉ 17.2. Preparing for Source Code Generation ΓòÉΓòÉΓòÉ
  10801.  
  10802. Before getting started, decide how you want to build your application's make 
  10803. file. You can create make files in either of the following ways: 
  10804.  
  10805.      From Visual Builder 
  10806.      Using WorkFrame's makemake program 
  10807.  
  10808.  Both options require the following advance preparation. 
  10809.  
  10810.  
  10811. ΓòÉΓòÉΓòÉ 17.2.1. Setting Up Visual Builder to Generate Make Files ΓòÉΓòÉΓòÉ
  10812.  
  10813. If you want Visual Builder to generate make files with the C++ source code, 
  10814. follow these steps from the Visual Builder window: 
  10815.  
  10816.    1. From the menu bar, select Options. 
  10817.  
  10818.    2. Select Preferences; then select Generate make files. 
  10819.  
  10820.  The next step is generating C++ source code for individual parts. 
  10821.  
  10822.  
  10823. ΓòÉΓòÉΓòÉ 17.2.2. Setting Up Visual Builder Projects to Use WorkFrame's makemake Program ΓòÉΓòÉΓòÉ
  10824.  
  10825. If you prefer to build your application's make file using WorkFrame, make sure 
  10826. your Visual Builder project has the correct compile and link options set. 
  10827. Follow these steps from the desktop: 
  10828.  
  10829.    1. Open the Settings notebook for your Visual Builder project. 
  10830.  
  10831.    2. Select the Target notebook tab. Type an appropriate name in the Make file 
  10832.       name field. 
  10833.  
  10834.    3. Select the Actions notebook tab. 
  10835.  
  10836.    4. Select the link action; then select the Options push button. 
  10837.  
  10838.    5. Select the Templates notebook tab. 
  10839.  
  10840.    6. Select the Templates used radio button; then select the compile action to 
  10841.       associate with the link action. 
  10842.  
  10843.    7. Select the OK push button. 
  10844.  
  10845.    8. Select the File Names notebook tab. 
  10846.  
  10847.    9. Under Libraries to use, type in: 
  10848.  
  10849.             cppoov3i.lib os2386.lib
  10850.  
  10851.   10. Under Definition (.DEF) file name, type the appropriate module definition 
  10852.       file name. 
  10853.  
  10854.   11. Select the OK push button. 
  10855.  
  10856.   12. Close the Settings notebook. 
  10857.  
  10858.  The next step is generating C++ source code for individual parts. 
  10859.  
  10860.  
  10861. ΓòÉΓòÉΓòÉ 17.3. Generating C++ Source Code for Individual Parts ΓòÉΓòÉΓòÉ
  10862.  
  10863. After you finish constructing a part, you must generate source code. If the 
  10864. part is an application in itself or if you want to test a part individually, 
  10865. you must also generate the code as described in Generating C++ Source Code for 
  10866. Your Application's main() Function. 
  10867.  
  10868. You can generate source code for the part being edited from any of the Visual 
  10869. Builder editors. 
  10870.  
  10871.    1. From the editor's menu bar, select File. 
  10872.  
  10873.    2. Select Save and generate; then select Part source. 
  10874.  
  10875.  In addition, if you are using the Composition Editor, you can select , (the 
  10876.  icon for the Generate Part Code tool) on the tool bar. There is no difference 
  10877.  between selecting this icon and using the menu item described previously. 
  10878.  
  10879.            One of the most common causes of code generation errors is changing 
  10880.            the names of features that are connected to other features. For 
  10881.            example, suppose feature A is connected to feature B. If you change 
  10882.            the name of feature A and then regenerate the source code for your 
  10883.            part, Visual Builder displays an error. This can also occur if you 
  10884.            change the name of a promoted feature. To correct the error, 
  10885.            double-click on the connection arrow and replace the incorrect 
  10886.            feature name with the correct one. 
  10887.  
  10888.  For more information about the files generated, see Source Files Created 
  10889.  during Part Code Generation. 
  10890.  
  10891.  The next step is generating C++ source code for your application's main() 
  10892.  function. 
  10893.  
  10894.  
  10895. ΓòÉΓòÉΓòÉ 17.3.1. Source Files Created during Part Code Generation ΓòÉΓòÉΓòÉ
  10896.  
  10897. For each part processed, Visual Builder generates several source code files. As 
  10898. an example, the following files are created for the OAContractView part: 
  10899.  
  10900.  contractg.cpp A C++ code file. 
  10901.  contractg.hpp The header file for contractg.cpp. 
  10902.  contractg.h A resource header file for the .cpp file. This file contains the 
  10903.            resource IDs for your part. 
  10904.  contractg.rc A resource file that contains any text strings used in the part 
  10905.            for entry field labels, push buttons, menus, and so forth. 
  10906.  
  10907.  If you selected Default to FAT file names under the Options pull-down menu of 
  10908.  the Visual Builder window and your part name has more than eight characters, 
  10909.  Visual Builder creates an eight-character name for the part when it is 
  10910.  created. 
  10911.  
  10912.  Note:  If you are using the File Allocation Table (FAT) file system, we 
  10913.         recommend that you always use part names and file names that have eight 
  10914.         characters or less, even if you have selected the Default to FAT file 
  10915.         names option. Otherwise, Visual Builder might use a file name for a 
  10916.         .vbb file that is the same as one that already exists and write over 
  10917.         the existing file. 
  10918.  
  10919.  For information about how the .h and .rc files are used for translation, see 
  10920.  Enabling National Language Support for an Application. 
  10921.  
  10922.  The next step is generating C++ source code for your application's main() 
  10923.  function. 
  10924.  
  10925.  
  10926. ΓòÉΓòÉΓòÉ 17.4. Generating Source Code for Your Application's main() Function ΓòÉΓòÉΓòÉ
  10927.  
  10928. To create an executable application, you must generate code for the standard 
  10929. C++ main() function. You can do this for parts that you want to test 
  10930. individually or for your entire application. If you want to compile your entire 
  10931. application, generate the function using the part that represents your 
  10932. application's primary view. 
  10933.  
  10934. You must first generate the C++ code for all parts that you intend to compile 
  10935. in your application. Load into Visual Builder the .vbb files that represent all 
  10936. parts that will appear in the compiled application. Then, generate the main() 
  10937. function from the part that you want to appear first when your application is 
  10938. started (the main part). 
  10939.  
  10940. You can generate application source code for the main() function if the main 
  10941. part is displayed in any of the Visual Builder editors. 
  10942.  
  10943.    1. From the editor's menu bar, select File. 
  10944.  
  10945.    2. Select Save and generate; then select main() for part. 
  10946.  
  10947.  For more information about the files generated, see Source Files Created 
  10948.  during Generation of main() Function Code. 
  10949.  
  10950.  The next step is preparing generated files for compilation. 
  10951.  
  10952.  
  10953. ΓòÉΓòÉΓòÉ 17.4.1. Source Files Created during Generation of main() Function Code ΓòÉΓòÉΓòÉ
  10954.  
  10955. For each main part processed, Visual Builder creates several files. For the 
  10956. OAMain part, the following files are created: 
  10957.  
  10958.  oamain.app The C++ code file containing the main() function declaration. 
  10959.  
  10960.            Note:  If you start Visual Builder from a WorkFrame project, a file 
  10961.                   named vbmain.cpp is generated instead of a file named 
  10962.                   oamain.app. 
  10963.  
  10964.  oamain.mak A make file, if you opted to generate make files using Visual 
  10965.            Builder. 
  10966.  
  10967.  If you selected Default to FAT file names as a preference under the Options 
  10968.  pull-down menu of the Visual Builder window and your part name has more than 
  10969.  eight characters, Visual Builder creates an eight-character name for the 
  10970.  generated files. 
  10971.  
  10972.  Note:  If you are using the File Allocation Table (FAT) file system, we 
  10973.         recommend that you always use part names and file names that have eight 
  10974.         characters or less, even if you have selected the Default to FAT file 
  10975.         names option. Otherwise, Visual Builder might use a file name for a 
  10976.         .vbb file that is the same as one that already exists and write over 
  10977.         the existing file. 
  10978.  
  10979.  The next step is preparing generated files for compilation. 
  10980.  
  10981.  
  10982. ΓòÉΓòÉΓòÉ 17.5. Preparing Generated Files for Compilation ΓòÉΓòÉΓòÉ
  10983.  
  10984. Before compiling your application, be sure you have the following files: 
  10985.  
  10986.      Header files for all parts 
  10987.      .cpp files for all parts 
  10988.      A make file 
  10989.      An .app file for the main part 
  10990.  
  10991.       Note:  If you start Visual Builder from a WorkFrame project, you should 
  10992.              have a file named vbmain.cpp instead of an .app file. 
  10993.  
  10994.  Final preparations for compilation and linking include the following: 
  10995.  
  10996.      Specifying additional libraries (C++ libraries and DLLs) in the make file 
  10997.      Specifying debug options for the compiler and linker programs 
  10998.  
  10999.  
  11000. ΓòÉΓòÉΓòÉ 17.5.1. Specifying Additional Libraries in the Make File ΓòÉΓòÉΓòÉ
  11001.  
  11002. Review the list of libraries specified in the make file, particularly libraries 
  11003. for parts that you compiled separately. 
  11004.  
  11005. If your application uses DLLs, add the DLL names as dependent files in the 
  11006. description blocks used to keep the object files up to date. The order in which 
  11007. you list object files is significant. Files with external references must occur 
  11008. after the referred-to files. 
  11009.  
  11010.  
  11011. ΓòÉΓòÉΓòÉ 17.5.2. Specifying the Option to Generate Browser Information ΓòÉΓòÉΓòÉ
  11012.  
  11013. If your want the VisualAge C++ compiler to generate Browser information, you 
  11014. must include the -Fb+ option when you compile your application. This option 
  11015. causes the compiler to generate a file with an extension of .pdb. Once this 
  11016. file is generated, you can use the Browser data when connecting features to 
  11017. member functions and for other purposes. For more information, see Using 
  11018. Browser Information. 
  11019.  
  11020.  
  11021. ΓòÉΓòÉΓòÉ 17.5.3. Specifying Debug Options for the Compiler and Linker Programs ΓòÉΓòÉΓòÉ
  11022.  
  11023. If you prefer to compile and link your application using WorkFrame, you should 
  11024. have already specified debug options in your Visual Builder project file. For 
  11025. more information about the options you need to set, see the WorkFrame 
  11026. documentation. 
  11027.  
  11028. If you opted to let Visual Builder generate your make file, Visual Builder adds 
  11029. debug options to the make file by default. If you do not want your application 
  11030. compiled with debugging turned on, remove the /Ti+ option. 
  11031.  
  11032. For more information, refer to the VisualAge C++ Language Reference. 
  11033.  
  11034. To make Visual Builder connections easier to debug, set up a trace by following 
  11035. these steps: 
  11036.  
  11037.    1. In your config.sys file, add this line: 
  11038.  
  11039.             SET ICLUI TRACETO=STDOUT
  11040.  
  11041.    2. In your make file, add this phrase at the end of the GCPPFLAGS statement, 
  11042.       but before the back slash (\): 
  11043.  
  11044.             -DIC_TRACE_DEVELOP
  11045.  
  11046.    3. When you run your compiled application, redirect the output to a file. 
  11047.       For example, run myapp.exe as follows: 
  11048.  
  11049.             myapp > myapp.out
  11050.  
  11051.       Browse the output file (myapp.out) to see what connections were fired and 
  11052.       in what order. 
  11053.  
  11054.  
  11055. ΓòÉΓòÉΓòÉ 17.6. Compiling and Linking Your Application ΓòÉΓòÉΓòÉ
  11056.  
  11057. You can compile your application from the OS/2 command line or from WorkFrame. 
  11058. To call both the complier and linker programs, you can run the Toolkit's nmake 
  11059. program. Regardless of how you choose to compile and link your Visual Builder 
  11060. application, use the following compile and link options: 
  11061.  
  11062.  B"/DE /pmtype:pm" Passes the string /DE /pmtype:pm to the linker as 
  11063.                 parameters. 
  11064.  
  11065.  C              Compiles and links. 
  11066.  
  11067.  Fb+            Generates Browser information in a file with a .pdb extension. 
  11068.  
  11069.  Ft(dir)        Generates files for template resolution and puts them in the 
  11070.                 dir directory. 
  11071.  
  11072.  Gd+            Dynamically links to the runtime library. 
  11073.  
  11074.  Gm+            Builds an .exe file. 
  11075.  
  11076.  I              Searches the directory of the source file for include files; 
  11077.                 then, searches paths specified in config.sys include variable. 
  11078.  
  11079.  Q              Displays the compiler logo when invoking the compiler. 
  11080.  
  11081.  Ti+            Generates debugger information. This is optional but 
  11082.                 recommended. 
  11083.  
  11084.  Tdp            Compiles all source files as C++ files and ensures that 
  11085.                 template functions are resolved. 
  11086.  
  11087.  For more information on compiling and linking, refer to the VisualAge C++ 
  11088.  Programming Guide. 
  11089.  
  11090.  
  11091. ΓòÉΓòÉΓòÉ 18. Using Existing C and C++ Code with Visual Builder ΓòÉΓòÉΓòÉ
  11092.  
  11093.      What you will achieve 
  11094.  
  11095.      Defining the part interface using part information files 
  11096.  
  11097.      Creating a part information file 
  11098.  
  11099.      Importing the part 
  11100.  
  11101.  Personal notes: 
  11102.  
  11103.  
  11104. ΓòÉΓòÉΓòÉ 18.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  11105.  
  11106. This chapter describes how you can use your existing C and C++ code in 
  11107. applications that you create with Visual Builder. 
  11108.  
  11109.  
  11110. ΓòÉΓòÉΓòÉ 18.2. Defining the Part Interface Using Part Information Files ΓòÉΓòÉΓòÉ
  11111.  
  11112. If C++ code already exists for your Visual Builder application, you can more 
  11113. efficiently define the part interface using part information files. This 
  11114. involves the following steps: 
  11115.  
  11116.    1. Determine the part's features. 
  11117.  
  11118.    2. Create a part information file using your favorite editor. This file can 
  11119.       include information for as many parts as you need. 
  11120.  
  11121.    3. In Visual Builder, import the part. 
  11122.  
  11123.  
  11124. ΓòÉΓòÉΓòÉ 18.2.1. Creating a Part Information File ΓòÉΓòÉΓòÉ
  11125.  
  11126. To create a part information file, add information about your part's part 
  11127. interface to a file using your preferred editor. The following example shows 
  11128. how you could specify part information for the OAContractor part: 
  11129.  
  11130. //VBBeginPartInfo: OAContractor,"Contractor part for OASearch sample"
  11131. //VBParent: IStandardNotifier
  11132. //VBIncludes: "Cntrctor.hpp" _OACONTRACTOR_,"iprofile.hpp","istring.hpp","iexcbase.hpp"
  11133. //VBPartDataFile: OANONVIS.VBB
  11134. //VBConstructor: OAContractor()
  11135. //VBComposerInfo: nonvisual,802,cppov33r
  11136. //VBEvent: ready, "ready", readyId
  11137. //VBAction: getContractor,
  11138. //VB:       "Get contractor data from database",
  11139. //VB:       OAContractor&,
  11140. //VB:       OAContractor& getContractor()
  11141. //VBAction: putContractor,
  11142. //VB:       "Add or update contractor data in database",
  11143. //VB:       OAContractor&,
  11144. //VB:       OAContractor& putContractor()
  11145. //VBAction: parseName,
  11146. //VB:       "Parse user input to get contractor's name",
  11147. //VB:       OAContractor&,
  11148. //VB        OAContractor& parseName(const IString& aName)
  11149. //VBAttribute: contractorID,
  11150. //VB:          "Contractor's employee identifier",
  11151. //VB:          IString,
  11152. //VB:          IString contractorID() const,,
  11153. //VB:          contractorIDId
  11154. //VBAttribute: lastName,
  11155. //VB:          "Contractor's last name",
  11156. //VB:          IString,
  11157. //VB:          IString lastName() const,
  11158. //VB:          OAContractor& setLastName(const IString& aLastName),
  11159. //VB:          lastNameId
  11160. //VBAttribute: firstName,
  11161. //VB:          "Contractor's first name",
  11162. //VB:          IString,
  11163. //VB:          IString firstName() const,
  11164. //VB:          OAContractor& setFirstName(const IString& aFirstName),
  11165. //VB:          firstNameId
  11166. //VBAttribute: middleInitial,
  11167. //VB:          "Contractor's middle initial",
  11168. //VB:          IString,
  11169. //VB:          IString middleInitial() const,
  11170. //VB:          OAContractor& setMiddleInitial(const IString& aMiddleInitial),
  11171. //VB:          middleInitialId
  11172. //VBAttribute: homeStreet,
  11173. //VB:          "Contractor's home street address",
  11174. //VB:          IString,
  11175. //VB:          IString homeStreet() const,
  11176. //VB:          OAContractor& setHomeStreet(const IString& aHomeStreet),
  11177. //VB:          homeStreetId
  11178. //VBAttribute: homeCity,
  11179. //VB:          "Contractor's home city",
  11180. //VB:          IString,
  11181. //VB:          IString homeCity() const,
  11182. //VB:          OAContractor& setHomeCity(const IString& aHomeCity),
  11183. //VB:          homeCityId
  11184. //VBAttribute: homeState,
  11185. //VB:          "Contractor's home state or province",
  11186. //VB:          IString,
  11187. //VB:          IString homeState() const,
  11188. //VB:          OAContractor& setHomeState(const IString& aHomeState),
  11189. //VB:          homeStateId
  11190. //VBAttribute: homeZip,
  11191. //VB:          "Contractor's home postal code",
  11192. //VB:          IString,
  11193. //VB:          IString homeZip() const,
  11194. //VB:          OAContractor& setHomeZip(const IString& aHomeZip),
  11195. //VB:          homeZipId
  11196. //VBAttribute: phoneNumber,
  11197. //VB:          "Contractor's daytime phone number",
  11198. //VB:          IString,
  11199. //VB:          IString phoneNumber() const,
  11200. //VB:          OAContractor& setPhoneNumber(const IString& aPhoneNumber),
  11201. //VB:          phoneNumberId
  11202. //VBAttribute: startDate,
  11203. //VB:          "Contractor's starting date with OA",
  11204. //VB:          IString,
  11205. //VB:          IString startDate() const,
  11206. //VB:          OAContractor& setStartDate(const IString& aStartDate),
  11207. //VB:          startDateId
  11208. //VBAttribute: endDate,
  11209. //VB:          "Contractor's last day with OA (empty if active)",
  11210. //VB:          IString,
  11211. //VB:          IString endDate() const,
  11212. //VB:          OAContractor& setEndDate(const IString& aEndDate),
  11213. //VB:          endDateId
  11214. //VBAttribute: activeStatus,
  11215. //VB:          "Whether contractor actively seeks contract work",
  11216. //VB:          Boolean,
  11217. //VB:          Boolean isActiveStatus() const,
  11218. //VB:          OAContractor& enableActiveStatus(Boolean enable = true),
  11219. //VB:          activeStatusId
  11220. //VBAttribute: currentContract,
  11221. //VB:          "Contractor's current assignment, if any",
  11222. //VB:          IString,
  11223. //VB:          IString currentContract() const,
  11224. //VB:          OAContractor& setCurrentContract(const IString& aCurrentContract),
  11225. //VB:          currentContractId
  11226. //VBPreferredFeatures: enabledForNotification, getContractor, putContractor, this
  11227. //VBEndPartInfo: OAContractor
  11228.  
  11229. Note the following syntax: 
  11230.  
  11231.      The VBBeginPartInfo and VBEndPartInfo statements delimit the part 
  11232.       information for OAContractor. 
  11233.  
  11234.      The VBPart statement specifies the base class for OAContractor, 
  11235.       IStandardNotifier*. 
  11236.  
  11237.      The VBIncludes statement specifies a header file to be added in an 
  11238.       #include directive when the code is generated. 
  11239.  
  11240.      The VBPartDataFile statement specifies the .vbb file that holds the 
  11241.       information for OAContractor. 
  11242.  
  11243.      The VBComposerInfo statement indicates that this is a nonvisual part. The 
  11244.       absence of the abstract keyword indicates that this is a concrete part 
  11245.       that can be dropped on the free-form surface. 
  11246.  
  11247.      The VBEvent, VBAction, and VBAttribute statements define features for 
  11248.       this part. 
  11249.  
  11250.  For information about part definition syntax, refer to Building VisualAge C++ 
  11251.  Parts for Fun and Profit. 
  11252.  
  11253.  The next step is importing the part. 
  11254.  
  11255.  
  11256. ΓòÉΓòÉΓòÉ 18.2.2. Importing the Part ΓòÉΓòÉΓòÉ
  11257.  
  11258. Before importing the part, you must create a part information file. To import 
  11259. the part, follow these steps from the Visual Builder window: 
  11260.  
  11261.    1. From the menu bar, select File. Select Import part information. 
  11262.  
  11263.       The Enter Name for Part Information File window appears. 
  11264.  
  11265.    2. Specify the path and name of the part information file that contains the 
  11266.       information that you want to import. When the import is finished, the 
  11267.       name of the part appears in in the Visual Builder window. 
  11268.  
  11269.  If C++ code for your part already exists, your part is finished. If you want 
  11270.  to change the part interface later, do either of the following: 
  11271.  
  11272.      Use the Part Interface Editor to edit feature specifications. You must 
  11273.       use this method to delete features. 
  11274.      Edit your part information file and re-import the part information. 
  11275.  
  11276.  If C++ code for your part does not exist, the next step is adding code to your 
  11277.  part. 
  11278.  
  11279.  
  11280. ΓòÉΓòÉΓòÉ 19. Adding Categories and Parts to the Parts Palette ΓòÉΓòÉΓòÉ
  11281.  
  11282.      What you will achieve 
  11283.  
  11284.      Preparing icons for the parts palette 
  11285.  
  11286.      Adding a category to the parts palette 
  11287.  
  11288.      Specifying a unique icon for a part you add to the parts palette 
  11289.  
  11290.      Adding a part to the parts palette 
  11291.  
  11292.      Deleting a category or part from the parts palette 
  11293.  
  11294.      Saving parts palette changes 
  11295.  
  11296.  Personal notes: 
  11297.  
  11298.  
  11299. ΓòÉΓòÉΓòÉ 19.1. What You Will Achieve ΓòÉΓòÉΓòÉ
  11300.  
  11301. The purpose of this chapter is to introduce you to the concepts and steps 
  11302. involved in adding categories and parts to and removing categories and parts 
  11303. from the parts palette. You can modify the parts palette at any time and from 
  11304. any of the Visual Builder editors or from the Visual Builder window. 
  11305.  
  11306. One reason to modify the parts palette is so that you can quickly and easily 
  11307. place parts that you have created and that you use often on the free-form 
  11308. surface. Otherwise, you have to place them by selecting OptionsAdd part, which 
  11309. requires you to know the exact class name of the part that you are placing. 
  11310.  
  11311. Another reason to modify the parts palette is to give everyone who is working 
  11312. on the same project access to the same set of standardized parts. Your company 
  11313. could have a parts builder who builds these standardized parts and puts them in 
  11314. a category on the parts palette for you to use. 
  11315.  
  11316. Group parts that behave similarly in the same category. You can see by looking 
  11317. at the parts palette how we have grouped the parts that we provided into 
  11318. categories based on their behavior. For example, all parts that are used for 
  11319. data entry are in one category, all parts that contain and display lists are in 
  11320. another category, and so forth. 
  11321.  
  11322. This chapter contains an example that uses the OAContractor nonvisual part 
  11323. created in Creating Nonvisual Parts, but you can use any part that you have 
  11324. created. When you finish the example, you have a new OAModels category and a 
  11325. new OAContractor part on the parts palette. 
  11326.  
  11327.  
  11328. ΓòÉΓòÉΓòÉ 19.2. Preparing Icons for the Parts Palette ΓòÉΓòÉΓòÉ
  11329.  
  11330. Each category and part on the Visual Builder parts palette is represented by an 
  11331. icon, so you can recognize it visually. With Visual Builder, you can create and 
  11332. use your own icons when you extend the parts palette. If you do not, you can 
  11333. still extend the parts palette and accept the default category icon, , and the 
  11334. default part icon, . 
  11335.  
  11336. This example uses for the OAModels category and for the OAContractor part, 
  11337. which are stored in the cppov33r.dll file as resource numbers 800 and 802, 
  11338. respectively. 
  11339.  
  11340. To prepare icons for use with Visual Builder, do the following: 
  11341.  
  11342.    1. Create your icons. One way to do this is to use your operating system 
  11343.       toolkit icon editor. 
  11344.  
  11345.       For VGA displays on OS/2, use the Independent VGA form (32x32). For 
  11346.       higher display resolutions on OS/2, use the 8514-16 colors form (40x40). 
  11347.  
  11348.    2. Create a resource DLL that contains your icons. Use files similar to the 
  11349.       following: 
  11350.  
  11351.           userpal.c 
  11352.  
  11353.                         empty()
  11354.                         {
  11355.                         }
  11356.  
  11357.           userpal.rc 
  11358.  
  11359.                         icon 800 oamodels.ico
  11360.                         icon 801 oacontractor.ico
  11361.  
  11362.           userpal.def 
  11363.  
  11364.                         library userpal
  11365.                         description 'Icons for user-extended palette'
  11366.  
  11367.           userpal.mak 
  11368.  
  11369.                         userpal.dll: userpal.obj userpal.def userpal.res
  11370.                           icc userpal.obj /Feuserpal.dll userpal.def
  11371.                             rc userpal.res userpal.dll
  11372.  
  11373.                         userpal.obj: userpal.c
  11374.                           icc /C+ userpal.c
  11375.  
  11376.                         userpal.res: userpal.rc
  11377.                           rc -r userpal.rc
  11378.  
  11379.       Once you have the files ready, type the following to build the resource 
  11380.       DLL: nmake userpal.mak 
  11381.  
  11382.    3. Place the resource DLL in a directory in your LIBPATH. 
  11383.  
  11384.  Your icons are now ready for use with Visual Builder. 
  11385.  
  11386.  The next step is adding a category to the parts palette. 
  11387.  
  11388.  
  11389. ΓòÉΓòÉΓòÉ 19.3. Adding a Category to the Parts Palette ΓòÉΓòÉΓòÉ
  11390.  
  11391. Now that you have your icons prepared in a resource DLL, you are ready to 
  11392. extend the parts palette. To add a category to the parts palette, do the 
  11393. following: 
  11394.  
  11395.    1. In the Composition Editor, select Modify PaletteAdd New Category from 
  11396.       the Options pull-down menu. 
  11397.  
  11398.       The Add palette category window is displayed as follows: 
  11399.  
  11400.       Notice that the default category icon, , is specified. It is stored as 
  11401.       resource ID 150 in the dde4vr30.dll resource file provided with Visual 
  11402.       Builder. 
  11403.  
  11404.    2. Type OAModels or the name that you want for your category in the Category 
  11405.       name field. 
  11406.  
  11407.    3. Type cppov33r or the name of your resource DLL in the Module name field. 
  11408.  
  11409.       Note:  Do not type the .dll file extension in the Module name field. 
  11410.  
  11411.    4. Type 800 or the resource ID of the icon in your resource DLL in the ID 
  11412.       field. 
  11413.  
  11414.       Note:  After you enter the resource ID number, move the cursor to another 
  11415.              component in the window, such as the Module name field, if you 
  11416.              want to see the graphic that will be used before continuing. 
  11417.  
  11418.    5. Select the OK push button. 
  11419.  
  11420.  Your category with the icon specified is added to the parts palette. 
  11421.  
  11422.  The next step is specifying a unique icon for your part. 
  11423.  
  11424.  
  11425. ΓòÉΓòÉΓòÉ 19.4. Specifying a Unique Icon for a Part You Add to the Parts Palette ΓòÉΓòÉΓòÉ
  11426.  
  11427. You can specify a unique icon for a part that you add to the parts palette, but 
  11428. you must do so before you add it to the parts palette. To give your part a 
  11429. unique icon, do the following: 
  11430.  
  11431.    1. Open the part. 
  11432.  
  11433.    2. Switch to the Class Editor. 
  11434.  
  11435.    3. Enter the name of the DLL file that contains the icon you want to use in 
  11436.       the DLL Name field. 
  11437.  
  11438.    4. Enter the resource ID number for the icon in the Resource Id field. 
  11439.  
  11440.       If you enter a valid DLL file name and resource ID number, Visual Builder 
  11441.       displays the icon below the Resource Id field. This allows you to verify 
  11442.       the icon before adding it to the parts palette. 
  11443.  
  11444.    5. Select FileSave to save the resource DLL and resource ID information in 
  11445.       the Class Editor. 
  11446.  
  11447.  The next step is adding a part to the parts palette. 
  11448.  
  11449.  
  11450. ΓòÉΓòÉΓòÉ 19.5. Adding a Part to the Parts Palette ΓòÉΓòÉΓòÉ
  11451.  
  11452. You can add a part to any category on the parts palette using any of the 
  11453. following methods: 
  11454.  
  11455.      Adding a part that is selected in the Visual Builder window 
  11456.  
  11457.      Adding the part that you are currently editing 
  11458.  
  11459.      Adding any part whose .vbb file is loaded 
  11460.  
  11461.  
  11462. ΓòÉΓòÉΓòÉ 19.5.1. Adding a Part That Is Selected in the Visual Builder Window ΓòÉΓòÉΓòÉ
  11463.  
  11464. To add a part to the parts palette from the Visual Builder window, do the 
  11465. following: 
  11466.  
  11467.    1. Load the .vbb file that contains the part you want to add to the parts 
  11468.       palette if it is not already loaded. 
  11469.  
  11470.    2. Select the .vbb file. For this example, select oanonvis.vbb. 
  11471.  
  11472.    3. Select the part you want to add. For this example, select OAContractor. 
  11473.  
  11474.       Note:  You can add multiple parts by holding down the Ctrl key and 
  11475.              clicking on each part that you want to add. 
  11476.  
  11477.    4. Select PartAdd to palette. 
  11478.  
  11479.       Visual Builder displays the Add to Palette window, as shown in the 
  11480.       following figure: 
  11481.  
  11482.    5. Select the part that you want to add. For this example, select 
  11483.       OAContractor. 
  11484.  
  11485.    6. Select the category that you want to add the part to. For this example, 
  11486.       select OAModels. 
  11487.  
  11488.    7. Select the Add push button. 
  11489.  
  11490.       Visual Builder adds the OAContractor part to the parts palette in the 
  11491.       OAModels category. 
  11492.  
  11493.  
  11494. ΓòÉΓòÉΓòÉ 19.5.2. Adding the Part That You are Currently Editing ΓòÉΓòÉΓòÉ
  11495.  
  11496. You can add the part that you are currently editing to the parts palette from 
  11497. either the Composition Editor, the Class Editor, or the Part Interface Editor. 
  11498. To add the part that you are currently editing to the parts palette, do the 
  11499. following: 
  11500.  
  11501.    1. Double-click on the OAContractor part in the Visual Builder window. 
  11502.  
  11503.       Visual Builder opens the OAContractor part in the Part Interface Editor. 
  11504.  
  11505.    2. Select FileAdd to palette. 
  11506.  
  11507.       Visual Builder displays the Add to Palette window, as shown in the 
  11508.       following figure: 
  11509.  
  11510.       The Part name field shows the name of the part that you are editing. This 
  11511.       is the part that is to be added to the parts palette. You cannot change 
  11512.       the name of the part displayed in this field. In this example, 
  11513.       OAContractor is displayed in this field. 
  11514.  
  11515.    3. Select the category that you want to add the part to. For this example, 
  11516.       select OAModels. 
  11517.  
  11518.    4. Select the Add push button. 
  11519.  
  11520.       The OAContractor part is added to the OAModels category on the parts 
  11521.       palette. To see this, switch to the Composition Editor and select the 
  11522.       OAModels category. The icon for the OAContractor part is displayed in the 
  11523.       parts column. 
  11524.  
  11525.  
  11526. ΓòÉΓòÉΓòÉ 19.5.3. Adding Any Part Whose .vbb File Is Loaded ΓòÉΓòÉΓòÉ
  11527.  
  11528. You can add any part to the parts palette as long as its .vbb file is loaded in 
  11529. the Visual Builder window. The following steps explain how to do this: 
  11530.  
  11531.    1. In the Composition Editor, select Modify PaletteAdd New Part from the 
  11532.       Options pull-down menu. The Add to Palette window is displayed as shown 
  11533.       in the following figure: 
  11534.  
  11535.       To add a part to the parts palette, do the following: 
  11536.  
  11537.         a. Type OAContractor in the Part name field or the class name of the 
  11538.            part you want to add. 
  11539.  
  11540.         b. Select OAModels in the Category list or the name of the category to 
  11541.            which you want to add your part. 
  11542.  
  11543.         c. Select the Add push button. 
  11544.  
  11545.            Your part is added to the parts palette in the specified category. 
  11546.  
  11547.  Notice that the part you just added uses the same icon as the part it inherits 
  11548.  from. If you inherit from a part whose icon does not appear on the parts 
  11549.  palette, such as IStandardNotifier*, or for which you have not provided a 
  11550.  resource DLL, Visual Builder uses the default part icon, . 
  11551.  
  11552.  The next section tells you how to delete a category or part from the parts 
  11553.  palette 
  11554.  
  11555.  
  11556. ΓòÉΓòÉΓòÉ 19.6. Deleting a Category or Part from the Parts Palette ΓòÉΓòÉΓòÉ
  11557.  
  11558. To delete a part from the parts palette, do the following: 
  11559.  
  11560.    1. Select the part on the parts palette. 
  11561.  
  11562.    2. Select Modify PaletteDelete Part from the Options pull-down menu. 
  11563.  
  11564.       The selected part is deleted from the parts palette. 
  11565.  
  11566.  To delete a category from the parts palette, do the following: 
  11567.  
  11568.    1. Select the category on the parts palette. 
  11569.  
  11570.    2. Select Modify PaletteDelete Category from the Options pull-down menu. 
  11571.  
  11572.       The selected category and all of the parts in it are deleted from the 
  11573.       parts palette. 
  11574.  
  11575.  
  11576. ΓòÉΓòÉΓòÉ 19.7. Saving Parts Palette Changes ΓòÉΓòÉΓòÉ
  11577.  
  11578. Visual Builder automatically saves all parts palette changes for you. When you 
  11579. create a new category or part, Visual Builder stores information about that 
  11580. category or part in a file named vbpalet.dat, which is stored in your current 
  11581. directory. This file is written automatically. 
  11582.  
  11583. Once you add or delete categories or parts, the vbpalet.dat file is read each 
  11584. time you start Visual Builder. The information this file contains causes any 
  11585. categories or parts that you have added to be included on the parts palette. It 
  11586. also prevents any categories or parts that you have deleted from appearing on 
  11587. the parts palette. 
  11588.  
  11589. If you update the icon associated with a part, the parts palette is updated the 
  11590. next time you select the category in which the icon appears. 
  11591.  
  11592. Removing a category or part that you just added 
  11593.  
  11594. The vbpalet.dat file also allows you to undo and redo any changes you make to 
  11595. the parts palette, but only during the current Composition Editor session. For 
  11596. example, after adding a category or part, you can select EditUndo to remove 
  11597. the part or category you just added. Selecting EditRedo would put the part or 
  11598. category back on the parts palette, again. 
  11599.  
  11600. Once you close the Composition Editor, you can no longer undo or redo any 
  11601. changes. However, you can still add categories and add parts, as well as delete 
  11602. categories and parts. 
  11603.  
  11604.  
  11605. ΓòÉΓòÉΓòÉ 20. Enabling National Language Support ΓòÉΓòÉΓòÉ
  11606.  
  11607.      Introduction 
  11608.  
  11609.      Using resource files for translation 
  11610.  
  11611.      Using canvases to adjust size for translated text 
  11612.  
  11613.      Specifying parts with country-sensitive formatting 
  11614.  
  11615.      Providing double-byte character support for Asian languages 
  11616.  
  11617.  Personal notes: 
  11618.  
  11619.  
  11620. ΓòÉΓòÉΓòÉ 20.1. Introduction ΓòÉΓòÉΓòÉ
  11621.  
  11622. Because many languages exist in the world today, consider designing your 
  11623. applications to be language friendly; that is, user-friendly for all languages. 
  11624. There are several different aspects to consider when creating an application 
  11625. that is language friendly: 
  11626.  
  11627.      First, there is the text that the user sees. This text includes labels in 
  11628.       your windows and messages that are displayed. 
  11629.  
  11630.      Next, there is specific country information. This includes date 
  11631.       separators and time formats. 
  11632.  
  11633.      Finally, some languages include characters that require two bytes to 
  11634.       represent those characters and are primarily found in the Asian 
  11635.       languages, such as Japanese. 
  11636.  
  11637.            A good rule to follow:  Do not place any translatable text or 
  11638.            country symbols directly into your source code. Place them in an 
  11639.            external file where they are easily accessible for translation. 
  11640.  
  11641.  Visual Builder provides for ease of national language support in the following 
  11642.  ways: 
  11643.  
  11644.      Using resource files for translation 
  11645.  
  11646.      Using canvases to adjust the size for translated text 
  11647.  
  11648.      Specifying data types with country-sensitive formatting 
  11649.  
  11650.      Providing double-byte character set (DBCS) support for Asian languages 
  11651.  
  11652.  For additional information about national language and DBCS support, refer to 
  11653.  the IBM Open Class Library User's Guide. 
  11654.  
  11655.  
  11656. ΓòÉΓòÉΓòÉ 20.2. Using Resource Files for Translation ΓòÉΓòÉΓòÉ
  11657.  
  11658. In Generating Source Code for Parts and Applications, you learned that Visual 
  11659. Builder generates the following resource files for you: 
  11660.  
  11661.      A resource file (partname.rc), which contains the text strings used in 
  11662.       your part 
  11663.  
  11664.      A resource header file (partname.h), which contains the resource IDs for 
  11665.       your application 
  11666.  
  11667.  The resource (partname.rc) file 
  11668.  
  11669.  The .rc file groups resources into two categories:window resources and 
  11670.  nonwindow resources. The window resources are the text strings that are 
  11671.  associated with window IDs for information area text and fly-over text. 
  11672.  
  11673.  The nonwindow resources are the text strings that are displayed in your 
  11674.  composite part. Examples are window titles, static text used to label entry 
  11675.  fields and list boxes, and the text on push buttons and menu items. These text 
  11676.  strings are delimited by quotation marks (") and can be translated into 
  11677.  another language. 
  11678.  
  11679.  Here is the todolist.rc file that we generated for the To-Do List application 
  11680.  shown in Creating a Simple Visual Builder Application: 
  11681.  
  11682.   //*************************************************************
  11683.   // Resource file for: ToDoList.cpp
  11684.   //*************************************************************
  11685.   #include "ToDoList.h"
  11686.  
  11687.   #include <os2.h>
  11688.  
  11689.   #ifndef MAIN_RESOURCES_INCLUDED
  11690.   #define MAIN_RESOURCES_INCLUDED
  11691.  
  11692.   HELPTABLE WND_ToDoList
  11693.      BEGIN
  11694.         HELPITEM  WND_ToDoList_FrameWindow,  WND_ToDoList_FrameWindow,  0
  11695.      END
  11696.  
  11697.   #define ToDoList_WINDOWRESOURCES
  11698.   #define ToDoList_NONWINDOWRESOURCES
  11699.   STRINGTABLE
  11700.      BEGIN
  11701.         1,  "Visual Builder 3.0"
  11702.      END
  11703.  
  11704.   #endif
  11705.  
  11706.   #ifdef ToDoList_NONWINDOWRESOURCES
  11707.   #ifndef ToDoList_NONWINDOWRESOURCES_INCLUDED
  11708.   #define ToDoList_NONWINDOWRESOURCES_INCLUDED
  11709.   STRINGTABLE
  11710.      BEGIN
  11711.         STRRC_ToDoList_FrameWindow_title,  "To-Do List"
  11712.         STRRC_ToDoList_StaticText1_text,  "To-do item"
  11713.         STRRC_ToDoList_EntryField1_text,  ""
  11714.         STRRC_ToDoList_StaticText2_text,  "To-do list"
  11715.         STRRC_ToDoList_PushButton1_text,  "Add"
  11716.         STRRC_ToDoList_PushButton2_text,  "Remove"
  11717.      END
  11718.  
  11719.   #endif
  11720.   #endif
  11721.  
  11722.   #ifdef ToDoList_WINDOWRESOURCES
  11723.   HELPSUBTABLE (WND_ToDoList_FrameWindow)
  11724.      BEGIN
  11725.      END
  11726.  
  11727.   #endif
  11728.  
  11729.   #ifdef ToDoList_HELPITEMRESOURCES
  11730.         HELPITEM  WND_ToDoList_FrameWindow,  WND_ToDoList_FrameWindow,  0
  11731.   #endif
  11732.  
  11733.   #ifdef ToDoList_HELPSUBITEMRESOURCES
  11734.   #endif
  11735.  
  11736.  The window resources and nonwindow resources are grouped into separate string 
  11737.  tables so that translators can easily find the text that is to be translated. 
  11738.  
  11739.  You may have text strings in your part, such as the application name, that you 
  11740.  do not want translated. If that is the case, you can prevent those text 
  11741.  strings from being inserted in the .rc file by inserting a number sign (#) at 
  11742.  the beginning of the text and enclosing the text in quotation marks ("). This 
  11743.  change must be made in the settings notebook for the part, not in the 
  11744.  Composition Editor. 
  11745.  
  11746.  For example, suppose you do not want the text in the window title, To-Do List, 
  11747.  to be translated. To prevent Visual Builder from inserting this text string in 
  11748.  the .rc file, you would open the settings notebook for the ToDoList part, find 
  11749.  the entry field on the General page that contains the title text, and change 
  11750.  it to the following: 
  11751.  
  11752.   #"To-Do List"
  11753.  
  11754.  Notice that each text string that Visual Builder inserts in the .rc file is 
  11755.  preceded by a #define statement that begins with STRRC. These #define 
  11756.  statements represent the resource ID of each text string. Visual Builder 
  11757.  generates these #define statements and defines them in the partname.h file. By 
  11758.  inserting and defining these #define statements, Visual Builder relieves you 
  11759.  from the task of having to specify resource IDs for each text string. 
  11760.  
  11761.  To help Visual Builder generate these #define statements properly, you must 
  11762.  enter the starting resource ID for your part. The following section explains 
  11763.  how to do this. 
  11764.  
  11765.  The resource header (partname.h) file 
  11766.  
  11767.  The .h file contains a list of #define statements. Visual Builder uses these 
  11768.  #define statements in the .rc file to assign unique resource IDs to each of 
  11769.  the text strings that you use to create your composite part and a unique 
  11770.  window ID to all primitive visual parts. The only resource ID that you need to 
  11771.  specify is the starting resource ID for the part. 
  11772.  
  11773.  Here is the todolist.h file that we generated for the To-Do List application 
  11774.  shown in Creating a Simple Visual Builder Application: 
  11775.  
  11776.   //*************************************************************
  11777.   // Resource header file for: ToDoList.cpp
  11778.   //*************************************************************
  11779.   #ifndef _ICCONST_
  11780.   #include <icconst.h>
  11781.   #endif
  11782.  
  11783.   #ifndef _IVBDEFS_
  11784.   #include <ivbdefs.h>
  11785.   #endif
  11786.  
  11787.   #ifndef RC_ToDoList
  11788.   #define RC_ToDoList  10000
  11789.   #endif
  11790.  
  11791.   #ifndef WND_ToDoList
  11792.   #define WND_ToDoList  VBBASEWINDOWID
  11793.   #endif
  11794.  
  11795.   #define WNDOFFSET_ToDoList_FrameWindow  0
  11796.   #define WND_ToDoList_FrameWindow  WND_ToDoList
  11797.   #define STRRC_ToDoList_FrameWindow_title  RC_ToDoList+0
  11798.  
  11799.   #define WNDOFFSET_ToDoList_Canvas  1
  11800.   #define WND_ToDoList_Canvas  WND_ToDoList + WNDOFFSET_ToDoList_Canvas
  11801.  
  11802.   #define WNDOFFSET_ToDoList_StaticText1  2
  11803.   #define WND_ToDoList_StaticText1  WND_ToDoList + WNDOFFSET_ToDoList_StaticText1
  11804.   #define STRRC_ToDoList_StaticText1_text  RC_ToDoList+1
  11805.  
  11806.   #define WNDOFFSET_ToDoList_EntryField1  3
  11807.   #define WND_ToDoList_EntryField1  WND_ToDoList + WNDOFFSET_ToDoList_EntryField1
  11808.   #define STRRC_ToDoList_EntryField1_text  RC_ToDoList+2
  11809.  
  11810.   #define WNDOFFSET_ToDoList_StaticText2  4
  11811.   #define WND_ToDoList_StaticText2  WND_ToDoList + WNDOFFSET_ToDoList_StaticText2
  11812.   #define STRRC_ToDoList_StaticText2_text  RC_ToDoList+3
  11813.  
  11814.   #define WNDOFFSET_ToDoList_PushButton1  5
  11815.   #define WND_ToDoList_PushButton1  WND_ToDoList + WNDOFFSET_ToDoList_PushButton1
  11816.   #define STRRC_ToDoList_PushButton1_text  RC_ToDoList+4
  11817.  
  11818.   #define WNDOFFSET_ToDoList_PushButton2  6
  11819.   #define WND_ToDoList_PushButton2  WND_ToDoList + WNDOFFSET_ToDoList_PushButton2
  11820.   #define STRRC_ToDoList_PushButton2_text  RC_ToDoList+5
  11821.  
  11822.   #define WNDOFFSET_ToDoList_ListBox1  7
  11823.   #define WND_ToDoList_ListBox1  WND_ToDoList + WNDOFFSET_ToDoList_ListBox1
  11824.  
  11825.  
  11826.  Find the first #define statement in the todolist.h file. It is the RC_ToDoList 
  11827.  #define statement. The number to the right of this #define statement, 10000, 
  11828.  is the starting resource ID. This is the default number that Visual Builder 
  11829.  inserts when you select the check box next to the Starting resource id field 
  11830.  in the Class Editor. Visual Builder uses this number as the resource ID of the 
  11831.  first text string and increments the resource ID of each successive text 
  11832.  string by 1. 
  11833.  
  11834.  We chose to use the default number 10000 for the following reasons: 
  11835.  
  11836.      The resource ID must be a number. 
  11837.  
  11838.      The number specified must be either high enough or low enough that it 
  11839.       does not conflict with the resource IDs that Visual Builder generates for 
  11840.       the primitive parts (entry field, push buttons, and so forth) that are 
  11841.       used to compose the ToDoList part. 
  11842.  
  11843.  When determining resource IDs for window resources, Visual Builder begins with 
  11844.  15000 and increments the resource ID of each successive primitive part by 5. 
  11845.  Therefore, we recommend using starting resource IDs between 100 and 14500 for 
  11846.  most applications for the following reasons: 
  11847.  
  11848.      You should not use resource IDs below 100 because Presentation Manager 
  11849.       has reserved many of them for its own use. 
  11850.  
  11851.      Numbers between 100 and 14500 are low enough to prevent you from 
  11852.       experiencing any resource ID conflicts in most cases. 
  11853.  
  11854.  Specifying the starting resource ID for subparts 
  11855.  
  11856.  If you use a part that you have created as a subpart, specify a starting 
  11857.  resource ID for both the subpart and the part in which the subpart is 
  11858.  embedded. Do this to prevent conflicts between the resource IDs that Visual 
  11859.  Builder generates for your subpart and those it generates for the part in 
  11860.  which the subpart is embedded, as described in the preceding section. 
  11861.  Otherwise, Visual Builder uses the same starting resource IDs for both the 
  11862.  subpart and the part in which it is embedded, which causes compile errors. 
  11863.  
  11864.  For example, suppose you have a reusable Address part (a canvas with entry 
  11865.  fields and static text) that you want to embed as a subpart in the frame 
  11866.  window of your application's main view. You might give the main view a 
  11867.  starting resource ID of 5000 and the Address part a starting resource ID of 
  11868.  6000. Doing this would prevent conflicts with the resource IDs that Visual 
  11869.  Builder generates for the main view and those it generates for the Address 
  11870.  part. 
  11871.  
  11872.  
  11873. ΓòÉΓòÉΓòÉ 20.3. Using Canvases to Adjust Size for Translated Text ΓòÉΓòÉΓòÉ
  11874.  
  11875. When text is translated from one language to another, the translated text often 
  11876. occupies more space than the original text occupied. This can cause problems 
  11877. because the layout of the user interface can be disrupted by the longer text 
  11878. strings. 
  11879.  
  11880. Two of the canvas parts that Visual Builder provides solve this problem for 
  11881. you:  ISetCanvas* and IMultiCellCanvas*. These parts allow you to insert 
  11882. translated text and rebuild your application without having to change the 
  11883. position of any of the parts in the user interface. The ISetCanvas* and 
  11884. IMultiCellCanvas* parts automatically adjust their size at run time to allow 
  11885. for longer text strings, taking into account the current window's text size and 
  11886. font. 
  11887.  
  11888. For example, suppose you are using an ISetCanvas* part with three vertical 
  11889. decks and three rows of IRadioButton* parts in each deck. Once the text strings 
  11890. for the IRadioButton* parts are translated, all you have to do is rebuild your 
  11891. application. The decks in the ISetCanvas* part automatically adjust their 
  11892. widths to allow for the size of the translated text strings. 
  11893.  
  11894. The IMultiCellCanvas part is also good for translation purposes because the 
  11895. rows and columns automatically adjust themselves to fit the translated text. 
  11896.  
  11897.  
  11898. ΓòÉΓòÉΓòÉ 20.4. Specifying Parts with Country-Sensitive Formatting ΓòÉΓòÉΓòÉ
  11899.  
  11900. Visual Builder provides the following class interface parts that allow you to 
  11901. specify how information is presented for specific national languages: 
  11902.  
  11903.  IDate      This part allows you to customize the date formatting for the 
  11904.             selected part. This includes specifying the order for the month, 
  11905.             day, and year, and the character to use as a separator. 
  11906.  
  11907.  ITime      This part allows you to customize the time formatting for the 
  11908.             selected part. This includes specifying the 12- or 24-hour format 
  11909.             and the character to use as a separator. 
  11910.  
  11911.  
  11912. ΓòÉΓòÉΓòÉ 20.5. Providing Double-Byte Character Support for Asian Languages ΓòÉΓòÉΓòÉ
  11913.  
  11914. The following Visual Builder parts provide DBCS support: 
  11915.  
  11916.  IBuffer 
  11917.    Class interface part that defines the contents of an IString. This part 
  11918.    provides attributes to determine whether part or all of the characters in a 
  11919.    buffer are DBCS or multi-byte character set (MBCS) characters, and whether 
  11920.    they are valid DBCS or MBCS characters. 
  11921.  
  11922.  IDBCSBuffer 
  11923.    Class interface part that implements the version of IString contents that 
  11924.    supports mixed OS/2 DBCS characters. This part ensures that MBCS characters 
  11925.    are processed properly. 
  11926.  
  11927.  IEntryField 
  11928.    Visual part that creates and manages an entry field control. On the General 
  11929.    page of the settings notebook for this part, you can specify the type of 
  11930.    data that the user can enter. It can be one of the following: 
  11931.  
  11932.    SBCS           Sets the entry field to accept SBCS text only. 
  11933.  
  11934.    DBCS           Sets the entry field to accept DBCS text only. 
  11935.  
  11936.    Mixed          Sets the entry field to accept text that is a mixture of SBCS 
  11937.                   and DBCS characters. Conversion from an ASCII DBCS code page 
  11938.                   to an EBCDIC DBCS code page can result in a possible increase 
  11939.                   in the length of the data because of the addition of shift-in 
  11940.                   and shift-out characters, but it does not exceed the text 
  11941.                   limit of the entry field. 
  11942.  
  11943.    Any            Sets the entry field to accept text that is a mixture of SBCS 
  11944.                   and DBCS characters. This setting is the opposite of mixed. 
  11945.                   If the text contains both SBCS and DBCS characters and is to 
  11946.                   be converted from an ASCII code page into an EBCDIC code 
  11947.                   page, this style causes an entry field to not account for 
  11948.                   shift-in and shift-out characters that would be introduced 
  11949.                   into its text. 
  11950.  
  11951.  IFrameWindow 
  11952.    Visual part that creates and manages a frame window control. This part has a 
  11953.    style option, appDBCSStatus, that includes a DBCS status area in the frame 
  11954.    window when it is displayed in a DBCS environment. IFrameWindow also has a 
  11955.    member function, shareParentDBCSStatus, that causes a child frame window to 
  11956.    share the DBCS status area of its parent. 
  11957.  
  11958.  IKeyboardEvent 
  11959.    Class interface part that represents a keyboard-related event. An 
  11960.    IKeyboardEvent object is created by a keyboard handler when a user presses 
  11961.    or releases a key. The part provides a virtualKey attribute that returns the 
  11962.    virtual key code of the key. Two of the codes it can return are firstDBCS 
  11963.    and lastDBCS. 
  11964.  
  11965.  IString 
  11966.    Class interface part that is an array of characters. This part provides 
  11967.    attributes to determine whether part or all of the characters in a string 
  11968.    are DBCS or MBCS characters, and whether they are valid DBCS or MBCS 
  11969.    characters. 
  11970.  
  11971.  
  11972. ΓòÉΓòÉΓòÉ 21. Using Direct-to-SOM Objects ΓòÉΓòÉΓòÉ
  11973.  
  11974.      Introduction 
  11975.  
  11976.      Creating and importing the part information file 
  11977.  
  11978.      Using DTS objects in a Visual Builder application 
  11979.  
  11980.      Bypassing DTS limitations 
  11981.  
  11982.  Personal notes: 
  11983.  
  11984.  
  11985. ΓòÉΓòÉΓòÉ 21.1. Introduction ΓòÉΓòÉΓòÉ
  11986.  
  11987. This chapter shows you how to use a Direct-to-SOM object in a Visual Builder 
  11988. application. SOM is the IBM System Object Model, which defines an interface 
  11989. between programs, or between libraries and programs, so that an object's 
  11990. interface is separated from its implementation. SOM allows classes of objects 
  11991. to be defined in one programming language and used in another, and it allows 
  11992. libraries of such classes to be updated without requiring client code to be 
  11993. recompiled. 
  11994.  
  11995. You can make classes and member functions in existing C++ programs 
  11996. SOM-accessible without having to rewrite class and member function definitions. 
  11997. You do this by adding SOM C++ compiler directives to your code. Although SOM 
  11998. imposes some restrictions on C++ coding conventions, you should be able to 
  11999. convert most C++ programs for SOM support with minimal effort. 
  12000.  
  12001. VisualAge C++ can convert existing C++ classes to SOM classes. The 
  12002. VisualAge C++ compiler translates C++ code into Interface Definition Language 
  12003. (IDL) code, which you then compile with the SOM compiler to create your SOM 
  12004. objects. This method of creating SOM objects is referred to as the C++ 
  12005. Direct-to-SOM, or DTS, method. Currently, the only SOM objects that Visual 
  12006. Builder supports are DTS objects. 
  12007.  
  12008. To use a DTS object in an Visual Builder application you must do the following: 
  12009.  
  12010.    1. Create the DTS object or objects. 
  12011.  
  12012.       You will need the .hh and .lib files that you created in this step when 
  12013.       compiling your Visual Builder application. You need the .dll when you run 
  12014.       your compiled Visual Builder application. 
  12015.  
  12016.       The DTS objects that you create must have the following characteristics: 
  12017.  
  12018.           DTS objects can have actions only; no attributes or events are 
  12019.            allowed. DTS objects are not able to notify other parts when events 
  12020.            occur. Therefore, no events or attribute event identifiers can be 
  12021.            used. 
  12022.  
  12023.           You can implement actions using C++ and classes in the IBM Open 
  12024.            Class Library. However, the actions can return only basic C data 
  12025.            types and their parameters must be basic C data types. For example, 
  12026.            instead of returning an IString data type, an action could return a 
  12027.            char*. 
  12028.  
  12029.       To learn how Visual Builder can help you avoid the DTS restrictions 
  12030.       stated in the preceding list, see Bypassing DTS Limitations. 
  12031.  
  12032.    2. Create and import a part information file (.vbe file) for your DTS 
  12033.       objects. 
  12034.  
  12035.    3. Create a Visual Builder application using DTS objects. 
  12036.  
  12037.    4. Generate and compile the code. 
  12038.  
  12039.    5. Run your application. 
  12040.  
  12041.       Make sure you have the .dll for the DTS object for this step. 
  12042.  
  12043.  The sections that follow assume that you have already created your DTS object 
  12044.  or objects, so they only discuss creating and importing the part information 
  12045.  file, and creating a Visual Builder application using DTS objects. 
  12046.  
  12047.  For information on creating DTS objects, refer to the VisualAge C++ User's 
  12048.  Guide. For information on generating and compiling your Visual Builder 
  12049.  application code, see Generating Source Code for Parts and Applications. 
  12050.  
  12051.  We begin with creating and importing the part information file. 
  12052.  
  12053.  
  12054. ΓòÉΓòÉΓòÉ 21.2. Creating and Importing the Part Information File ΓòÉΓòÉΓòÉ
  12055.  
  12056. In Defining the Part Interface Using Part Information Files, you learned how to 
  12057. create a part information file. Create a file like this for your DTS objects. 
  12058. There are only two requirements when creating this file: 
  12059.  
  12060.      As we explained in the preceding section, DTS objects can only have 
  12061.       actions. This makes DTS objects the equivalent of class interface parts 
  12062.       because they have no notification capability. Therefore, you must set the 
  12063.       VBComposerInfo statement for each DTS object to class. 
  12064.  
  12065.      Since DTS objects can only have actions, you cannot code any attributes 
  12066.       or events in your part information file. 
  12067.  
  12068.  The following example shows a part information file, mydtsdt.vbe, that 
  12069.  contains the information for the following sample DTS objects: 
  12070.  
  12071.  MyDTSDate      Returns the current date. 
  12072.  
  12073.  MyDTSTime      Returns the current time. 
  12074.  
  12075.   //
  12076.   // SOM classes as Visual Builder classes
  12077.   //
  12078.   //VBBeginPartInfo: MyDTSDate, "My DTS SOM Date Class"
  12079.   //VBIncludes: "mydtsdat.hh" MyDTSDate_hh
  12080.   //VBPartDataFile: 'mydtsdt.vbb'
  12081.   //VBLibFile: 'mydtsdat.lib'
  12082.   //VBComposerInfo: class
  12083.   //VBAction: getTodaysDate
  12084.   //VB:       ,"Get today's date action.",char*,
  12085.   //VB:       char* getTodaysDate()
  12086.   //VBPreferredFeatures: this, getTodaysDate
  12087.   //VBEndPartInfo: MyDTSDate
  12088.   //
  12089.   //VBBeginPartInfo: MyDTSTime, "My DTS SOM Time Class"
  12090.   //VBIncludes: "mydtstim.hh" MyDTSTime_hh
  12091.   //VBPartDataFile: 'mydtsdt.vbb'
  12092.   //VBLibFile: 'mydtstim.lib'
  12093.   //VBComposerInfo: class
  12094.   //VBAction: getCurrentTime
  12095.   //VB:       ,"Get current time action.",char*,
  12096.   //VB:       char* getCurrentTime()
  12097.   //VBPreferredFeatures: this, getCurrentTime
  12098.   //VBEndPartInfo: MyDTSTime
  12099.   //
  12100.  
  12101.  The mydtsdt.vbe file contains statements that refer to the following files 
  12102.  that are needed for each of the sample DTS objects: 
  12103.  
  12104.  mydtsdat.hh and mydtstim.hh The header files for the MyDTSDate and MyDTSTime 
  12105.                 SOM classes. 
  12106.  
  12107.  mydtsdat.lib and mydtstim.lib The library files that were created when the DTS 
  12108.                 objects were compiled. 
  12109.  
  12110.  mydtsdt.vbb    The part (.vbb) file that is to contain the information about 
  12111.                 the DTS parts when you import the part information from the 
  12112.                 mydtsdt.vbe file. You must load the mydtsdt.vbb file into 
  12113.                 Visual Builder before you can add the MyDTSDate and MyDTSTime 
  12114.                 parts to the free-form surface in the Composition Editor. 
  12115.  
  12116.  Once you create your part information file, you must import it into Visual 
  12117.  Builder before you can use your DTS objects in a Visual Builder application. 
  12118.  For information on how to do this, see Importing Part Information. 
  12119.  
  12120.  The next step is using DTS objects in a Visual Builder application. 
  12121.  
  12122.  
  12123. ΓòÉΓòÉΓòÉ 21.3. Using DTS Objects in a Visual Builder Application ΓòÉΓòÉΓòÉ
  12124.  
  12125. Using DTS objects in a Visual Builder application is no different from using a 
  12126. class interface part. You simply place the DTS objects on the free-form surface 
  12127. and make the necessary connections to use their actions. 
  12128.  
  12129. The following figure shows how we used the MyDTSDate and MyDTSTime objects in a 
  12130. simple application. 
  12131.  
  12132. To create the application, we placed the MyDTSDate and MyDTSTime parts on the 
  12133. free-form surface by selecting OptionsAdd part and providing the necessary 
  12134. information in the Add Part window for each part. 
  12135.  
  12136. In this application, when a user clicks on the Current push button, the 
  12137. buttonClickEvent feature causes the getTodaysDate and getTodaysTime actions to 
  12138. get the date and time that is currently set in your computer's operating 
  12139. system. In addition, the actionResult attribute of each connection updates the 
  12140. text attribute of each entry field with the result of the two actions, the 
  12141. current date and time. 
  12142.  
  12143. Earlier, we mentioned that actions in DTS classes can return only basic C data 
  12144. types. The getTodaysDate and getTodaysTime actions in our example both return a 
  12145. data type of char*. Therefore, when we connected the actionResult attribute to 
  12146. the text attribute of the entry field, Visual Builder displayed a message 
  12147. saying that the types did not match and asking if we wanted to continue. In 
  12148. this case, we could make the connection because IString has a constructor that 
  12149. takes a char*. You can find out whether to complete a connection in situations 
  12150. like this by looking at the IBM Open Class Library Reference. 
  12151.  
  12152.            When you have generated your code and are ready to compile your 
  12153.            application, make sure you have the .hh and .lib files that contain 
  12154.            the code for your DTS objects in the current directory. Also, make 
  12155.            sure the SOM Toolkit is installed because the VisualAge C++ compiler 
  12156.            must have access to several of its files. 
  12157.  
  12158.            When you are ready to run your application, the .dll for the DTS 
  12159.            objects must be accessible. 
  12160.  
  12161.  
  12162. ΓòÉΓòÉΓòÉ 21.4. Bypassing DTS Limitations ΓòÉΓòÉΓòÉ
  12163.  
  12164. Earlier, we told you that DTS objects have certain limitations, such as not 
  12165. being able to use attributes and events, and not being able to notify other 
  12166. parts. You can bypass these limitations by using nonvisual parts to manage the 
  12167. things your DTS objects cannot do. 
  12168.  
  12169. In the example shown in Using DTS Objects in a Visual Builder Application, we 
  12170. could have created two nonvisual parts called MyDate and MyTime in addition to 
  12171. the two DTS parts, MyDTSDate and MyDTSTime. We could give these nonvisual parts 
  12172. attributes such as theDate and theTime and notify other parts when the values 
  12173. of these attributes change. We could also give these attributes get and set 
  12174. member functions that call actions in the DTS objects to get and set the values 
  12175. of the attributes. 
  12176.  
  12177. Once this is done, we would place the nonvisual parts MyDate and MyTime on the 
  12178. free-form surface, instead of MyDTSDate and MyDTSTime, and make the same 
  12179. connections as described previously. 
  12180.  
  12181.  
  12182. ΓòÉΓòÉΓòÉ 22. Glossary ΓòÉΓòÉΓòÉ
  12183.  
  12184.  
  12185. ΓòÉΓòÉΓòÉ <hidden> Glossary description ΓòÉΓòÉΓòÉ
  12186.  
  12187. This glossary defines terms and abbreviations that are used in this book. If 
  12188. you do not find the term you are looking for, refer to the IBM Dictionary of 
  12189. Computing, New York:McGraw-Hill, 1994. 
  12190.  
  12191. This glossary includes terms and definitions from the American National 
  12192. Standard Dictionary for Information Systems, ANSI X3.172-1990, copyright 1990 
  12193. by the American National Standards Institute (ANSI). Copies may be purchased 
  12194. from the American National Standards Institute, 1430 Broadway, New York, New 
  12195. York 10018. 
  12196.  
  12197.  
  12198. ΓòÉΓòÉΓòÉ <hidden> Glossary listing ΓòÉΓòÉΓòÉ
  12199.  
  12200. A
  12201. abstract class
  12202. access
  12203. action
  12204. argument
  12205. attribute
  12206. attribute-to-action connection
  12207. attribute-to-attribute connection
  12208. attribute-to-member function connection
  12209. B
  12210. base class
  12211. behavior
  12212. C
  12213. caller
  12214. category
  12215. class
  12216. Class Editor
  12217. class hierarchy
  12218. class library
  12219. class member function
  12220. client area object
  12221. client object
  12222. collection
  12223. Common User Access (CUA)
  12224. composite part
  12225. Composition Editor
  12226. concrete class
  12227. connection
  12228. const
  12229. construction from parts
  12230. constructor
  12231. CUA
  12232. cursored emphasis
  12233. custom logic connection
  12234. D
  12235. data abstraction
  12236. data member
  12237. data model
  12238. data object
  12239. declaration
  12240. DEF file
  12241. derivation
  12242. destructor
  12243. DLL
  12244. dynamic link library (DLL)
  12245. E
  12246. encapsulation
  12247. event
  12248. event-to-action connection
  12249. event-to-attribute connection
  12250. event-to-member function connection
  12251. expansion area
  12252. F
  12253. feature
  12254. full attribute
  12255. free-form surface
  12256. G
  12257. graphical user interface (GUI)
  12258. GUI
  12259. H
  12260. handles
  12261. header file
  12262. I
  12263. inheritance
  12264. instance
  12265. L
  12266. legacy code
  12267. loaded
  12268. M
  12269. main part
  12270. member
  12271. member function
  12272. member function call
  12273. member function name
  12274. message
  12275. model
  12276. module definition file
  12277. N
  12278. nested class
  12279. nonvisual part
  12280. no-event attribute
  12281. no-set attribute
  12282. notebook part
  12283. O
  12284. object
  12285. object class
  12286. object factory
  12287. object-oriented programming
  12288. observer
  12289. operation
  12290. overloading
  12291. P
  12292. palette
  12293. parameter connection
  12294. parent class
  12295. part
  12296. part event
  12297. part event ID
  12298. part interface
  12299. Part Interface Editor
  12300. parts palette
  12301. preferred features
  12302. primary selection
  12303. private
  12304. process
  12305. program
  12306. protected
  12307. prototype
  12308. primitive part
  12309. process
  12310. property
  12311. pure virtual function
  12312. R
  12313. receiver
  12314. resource file
  12315. S
  12316. selection handles
  12317. server
  12318. service
  12319. settings view
  12320. sticky
  12321. structure
  12322. subpart
  12323. superclass
  12324. T
  12325. tear-off attribute
  12326. template
  12327. thread
  12328. tool bar
  12329. U
  12330. UI
  12331. unloaded
  12332. user interface (UI)
  12333. V
  12334. variable
  12335. view
  12336. virtual function
  12337. visual part
  12338. visual programming tool
  12339. W
  12340. white space
  12341. window
  12342.  
  12343.  
  12344. ΓòÉΓòÉΓòÉ <hidden> abstract class ΓòÉΓòÉΓòÉ
  12345.  
  12346. A class that provides common behavior across a set of subclasses but is not 
  12347. itself designed to have instances that work. An abstract class represents a 
  12348. concept; classes derived from it represent implementations of the concept. For 
  12349. example, IControl is the abstract base class for control view windows; the 
  12350. ICanvas and IListBox classes are controls derived from IControl. An abstract 
  12351. class must have at least one pure virtual function. 
  12352.  
  12353. See also  base class. 
  12354.  
  12355.  
  12356. ΓòÉΓòÉΓòÉ <hidden> access ΓòÉΓòÉΓòÉ
  12357.  
  12358. A property of a class that determines whether a class member is accessible in 
  12359. an expression or declaration. 
  12360.  
  12361.  
  12362. ΓòÉΓòÉΓòÉ <hidden> action ΓòÉΓòÉΓòÉ
  12363.  
  12364. A specification of a function that a part can perform. The visual builder uses 
  12365. action specifications to generate connections between parts. Actions are 
  12366. resolved to member function calls in the generated code. 
  12367.  
  12368. Compare to  event and  attribute. 
  12369.  
  12370.  
  12371. ΓòÉΓòÉΓòÉ <hidden> argument ΓòÉΓòÉΓòÉ
  12372.  
  12373. A data element, or value, included as part of a member function call. Arguments 
  12374. provide additional information that the called member function can use to 
  12375. perform the requested operation. 
  12376.  
  12377.  
  12378. ΓòÉΓòÉΓòÉ <hidden> attribute ΓòÉΓòÉΓòÉ
  12379.  
  12380. A specification of a property of a part. For example, a customer part could 
  12381. have a name attribute and an address attribute. An attribute can itself be a 
  12382. part with its own behavior and attributes. 
  12383.  
  12384. The visual builder uses attribute specifications to generate code to get and 
  12385. set part properties. 
  12386.  
  12387. Compare to  event and  action. 
  12388.  
  12389.  
  12390. ΓòÉΓòÉΓòÉ <hidden> attribute-to-action connection ΓòÉΓòÉΓòÉ
  12391.  
  12392. A connection that starts an action whenever an attribute's value changes. It is 
  12393. similar to an event-to-action connection because the attribute's event ID is 
  12394. used to notify the action when the value of the attribute changes. 
  12395.  
  12396. See also  connection. Compare to  event-to-action connection. 
  12397.  
  12398.  
  12399. ΓòÉΓòÉΓòÉ <hidden> attribute-to-attribute connection ΓòÉΓòÉΓòÉ
  12400.  
  12401. A connection from an attribute of one part to an attribute of another part. 
  12402. When one attribute is updated, the other attribute is updated automatically. 
  12403.  
  12404. See also  connection. 
  12405.  
  12406.  
  12407. ΓòÉΓòÉΓòÉ <hidden> attribute-to-member function connection ΓòÉΓòÉΓòÉ
  12408.  
  12409. A connection from an attribute of a part to a member function. The connected 
  12410. attribute receives its value from the member function, which can make 
  12411. calculations based on the values of other parts. 
  12412.  
  12413. See also  connection. 
  12414.  
  12415.  
  12416. ΓòÉΓòÉΓòÉ <hidden> base class ΓòÉΓòÉΓòÉ
  12417.  
  12418. A class from which other classes or parts are derived. A base class may itself 
  12419. be derived from another base class. 
  12420.  
  12421. See also  abstract class. 
  12422.  
  12423.  
  12424. ΓòÉΓòÉΓòÉ <hidden> behavior ΓòÉΓòÉΓòÉ
  12425.  
  12426. The set of external characteristics that an object exhibits. 
  12427.  
  12428.  
  12429. ΓòÉΓòÉΓòÉ <hidden> caller ΓòÉΓòÉΓòÉ
  12430.  
  12431. An object that sends a member function call to another object. 
  12432.  
  12433. Contrast with  receiver. 
  12434.  
  12435.  
  12436. ΓòÉΓòÉΓòÉ <hidden> category ΓòÉΓòÉΓòÉ
  12437.  
  12438. In the Composition Editor, a selectable grouping of parts represented by an 
  12439. icon in the left-most column. Selecting a category displays the parts belonging 
  12440. to that category in the next column. 
  12441.  
  12442. See also  parts palette. 
  12443.  
  12444.  
  12445. ΓòÉΓòÉΓòÉ <hidden> class ΓòÉΓòÉΓòÉ
  12446.  
  12447. An aggregate that can contain functions, types, and user-defined operators, in 
  12448. addition to data. Classes can be defined hierarchically, allowing one class to 
  12449. be an expansion of another, and can restrict access to its members. 
  12450.  
  12451.  
  12452. ΓòÉΓòÉΓòÉ <hidden> Class Editor ΓòÉΓòÉΓòÉ
  12453.  
  12454. The editor you use to specify the names of files that Visual Builder writes to 
  12455. when you generate default code. You can also use this editor to do the 
  12456. following: 
  12457.  
  12458.      Enter a description of the part 
  12459.      Specify a different .vbb file in which to store the part 
  12460.      See the name of the part's base class 
  12461.      Modify the part's default constructor 
  12462.      Enter additional constructor and destructor code 
  12463.      Specify a .lib file for the part 
  12464.      Specify a resource DLL and ID to assign an icon to the part 
  12465.      Specify other files that you want to include when you build your 
  12466.       application 
  12467.  
  12468.  Compare to  Composition Editor and  Part Interface Editor. 
  12469.  
  12470.  
  12471. ΓòÉΓòÉΓòÉ <hidden> class hierarchy ΓòÉΓòÉΓòÉ
  12472.  
  12473. A tree-like structure showing relationships among object classes. It places one 
  12474. abstract class at the top (a base class) and one or more layers of less 
  12475. abstract classes below it. 
  12476.  
  12477.  
  12478. ΓòÉΓòÉΓòÉ <hidden> class library ΓòÉΓòÉΓòÉ
  12479.  
  12480. A collection of classes. 
  12481.  
  12482.  
  12483. ΓòÉΓòÉΓòÉ <hidden> class member function ΓòÉΓòÉΓòÉ
  12484.  
  12485. See  member function. 
  12486.  
  12487.  
  12488. ΓòÉΓòÉΓòÉ <hidden> client area object ΓòÉΓòÉΓòÉ
  12489.  
  12490. An intermediate window between a frame window (IFrameWindow) and its controls 
  12491. and other child windows. 
  12492.  
  12493.  
  12494. ΓòÉΓòÉΓòÉ <hidden> client object ΓòÉΓòÉΓòÉ
  12495.  
  12496. An object that requests services from other objects. 
  12497.  
  12498.  
  12499. ΓòÉΓòÉΓòÉ <hidden> collection ΓòÉΓòÉΓòÉ
  12500.  
  12501. A set of features in which each feature is an object. 
  12502.  
  12503.  
  12504. ΓòÉΓòÉΓòÉ <hidden> Common User Access (CUA) ΓòÉΓòÉΓòÉ
  12505.  
  12506. An IBM architecture for designing graphical user interfaces using a set of 
  12507. standard components and terminology. 
  12508.  
  12509.  
  12510. ΓòÉΓòÉΓòÉ <hidden> composite part ΓòÉΓòÉΓòÉ
  12511.  
  12512. A part that is composed of a part and one or more subparts. A composite part 
  12513. can contain visual parts, nonvisual parts, or both. 
  12514.  
  12515. See also  nonvisual part, part, subpart, and  visual part. 
  12516.  
  12517.  
  12518. ΓòÉΓòÉΓòÉ <hidden> Composition Editor ΓòÉΓòÉΓòÉ
  12519.  
  12520. A view that is used to build a graphical user interface and to make connections 
  12521. between parts. 
  12522.  
  12523. Compare to  Class Editor and  Part Interface Editor. 
  12524.  
  12525.  
  12526. ΓòÉΓòÉΓòÉ <hidden> concrete class ΓòÉΓòÉΓòÉ
  12527.  
  12528. A subclass of an abstract class that is a specialization of the abstract class. 
  12529.  
  12530.  
  12531. ΓòÉΓòÉΓòÉ <hidden> connection ΓòÉΓòÉΓòÉ
  12532.  
  12533. A formal, explicit relationship between parts. Making connections is the basic 
  12534. technique for building any visual application because that defines the way in 
  12535. which parts communicate with one another. The visual builder generates the code 
  12536. that then implements these connections. 
  12537.  
  12538. See also  attribute-to-action connection, attribute-to-attribute connection, 
  12539. attribute-to-member function connection, parameter connection, custom logic 
  12540. connection, event-to-action connection, event-to-attribute connection, and 
  12541. event-to-member function connection. 
  12542.  
  12543.  
  12544. ΓòÉΓòÉΓòÉ <hidden> const ΓòÉΓòÉΓòÉ
  12545.  
  12546. An attribute of a data object that declares that the object cannot be changed. 
  12547.  
  12548.  
  12549. ΓòÉΓòÉΓòÉ <hidden> construction from parts ΓòÉΓòÉΓòÉ
  12550.  
  12551. A software development technology in which applications are assembled from 
  12552. existing and reusable software components, known as parts. 
  12553.  
  12554.  
  12555. ΓòÉΓòÉΓòÉ <hidden> constructor ΓòÉΓòÉΓòÉ
  12556.  
  12557. A special class member function that has the same name as the class and is used 
  12558. to construct and possibly initialize class objects. 
  12559.  
  12560.  
  12561. ΓòÉΓòÉΓòÉ <hidden> CUA ΓòÉΓòÉΓòÉ
  12562.  
  12563. See  Common User Access. 
  12564.  
  12565.  
  12566. ΓòÉΓòÉΓòÉ <hidden> cursored emphasis ΓòÉΓòÉΓòÉ
  12567.  
  12568. When the selection cursor is on a choice, that choice has cursored emphasis. 
  12569.  
  12570.  
  12571. ΓòÉΓòÉΓòÉ <hidden> custom logic connection ΓòÉΓòÉΓòÉ
  12572.  
  12573. A connection that causes your customized C or C++ code to be run. This 
  12574. connection can be triggered either when an attribute's value changes or an 
  12575. event occurs. 
  12576.  
  12577.  
  12578. ΓòÉΓòÉΓòÉ <hidden> data abstraction ΓòÉΓòÉΓòÉ
  12579.  
  12580. A data type with a private representation and a public set of operations. The 
  12581. C++ language uses the concept of classes to implement data abstraction. 
  12582.  
  12583.  
  12584. ΓòÉΓòÉΓòÉ <hidden> data member ΓòÉΓòÉΓòÉ
  12585.  
  12586. Private data that belongs to a given object and is hidden from direct access by 
  12587. all other objects. Data members can only be accessed by the member functions of 
  12588. the defining class and its subclasses. 
  12589.  
  12590.  
  12591. ΓòÉΓòÉΓòÉ <hidden> data model ΓòÉΓòÉΓòÉ
  12592.  
  12593. A combination of the base classes and parts shipped with the product and the 
  12594. classes and parts you save and create. They are saved in a file named 
  12595. vbbase.vbb. 
  12596.  
  12597.  
  12598. ΓòÉΓòÉΓòÉ <hidden> data object ΓòÉΓòÉΓòÉ
  12599.  
  12600. A storage area used to hold a value. 
  12601.  
  12602.  
  12603. ΓòÉΓòÉΓòÉ <hidden> declaration ΓòÉΓòÉΓòÉ
  12604.  
  12605. A description that makes an external object or function available to a function 
  12606. or a block. 
  12607.  
  12608.  
  12609. ΓòÉΓòÉΓòÉ <hidden> DEF file ΓòÉΓòÉΓòÉ
  12610.  
  12611. See  module definition file. 
  12612.  
  12613.  
  12614. ΓòÉΓòÉΓòÉ <hidden> derivation ΓòÉΓòÉΓòÉ
  12615.  
  12616. The creation of a new or abstract class from an existing or base class. 
  12617.  
  12618.  
  12619. ΓòÉΓòÉΓòÉ <hidden> destructor ΓòÉΓòÉΓòÉ
  12620.  
  12621. A special class member function that has the same name as the class and is used 
  12622. to destruct class objects. 
  12623.  
  12624.  
  12625. ΓòÉΓòÉΓòÉ <hidden> DLL ΓòÉΓòÉΓòÉ
  12626.  
  12627. See  dynamic link library. 
  12628.  
  12629.  
  12630. ΓòÉΓòÉΓòÉ <hidden> dynamic link library (DLL) ΓòÉΓòÉΓòÉ
  12631.  
  12632. In OS/2, a library containing data and code objects that can be used by 
  12633. programs or applications during loading or at run time. Although they are not 
  12634. part of the program's executable (.exe) file, they are sometimes required for 
  12635. an .exe file to run properly. 
  12636.  
  12637.  
  12638. ΓòÉΓòÉΓòÉ <hidden> encapsulation ΓòÉΓòÉΓòÉ
  12639.  
  12640. The hiding of a software object's internal representation. The object provides 
  12641. an interface that queries and manipulates the data without exposing its 
  12642. underlying structure. 
  12643.  
  12644.  
  12645. ΓòÉΓòÉΓòÉ <hidden> event ΓòÉΓòÉΓòÉ
  12646.  
  12647. A specification of a notification from a part. 
  12648.  
  12649. Compare to  action, attribute, and  part event. 
  12650.  
  12651.  
  12652. ΓòÉΓòÉΓòÉ <hidden> event-to-action connection ΓòÉΓòÉΓòÉ
  12653.  
  12654. A connection that causes an action to be performed when an event occurs. 
  12655.  
  12656. See also  connection. 
  12657.  
  12658.  
  12659. ΓòÉΓòÉΓòÉ <hidden> event-to-attribute connection ΓòÉΓòÉΓòÉ
  12660.  
  12661. A connection that changes the value of an attribute when a certain event 
  12662. occurs. 
  12663.  
  12664. See also  connection. 
  12665.  
  12666.  
  12667. ΓòÉΓòÉΓòÉ <hidden> event-to-member function connection ΓòÉΓòÉΓòÉ
  12668.  
  12669. A connection from an event of a part to a member function. When the connected 
  12670. event occurs, the member function is executed. 
  12671.  
  12672. See also  connection. 
  12673.  
  12674.  
  12675. ΓòÉΓòÉΓòÉ <hidden> expansion area ΓòÉΓòÉΓòÉ
  12676.  
  12677. The section of a multicell canvas between the current cell grid and the outer 
  12678. edge of the canvas. Visually, this area is bounded by the rightmost column 
  12679. gridline and the bottommost row gridline. 
  12680.  
  12681.  
  12682. ΓòÉΓòÉΓòÉ <hidden> feature ΓòÉΓòÉΓòÉ
  12683.  
  12684. A major component of a software product that can be installed separately. 
  12685.  
  12686. In Visual Builder, an action, attribute, or event that is available from a 
  12687. part's part interface and that other parts can connect to. 
  12688.  
  12689.  
  12690. ΓòÉΓòÉΓòÉ <hidden> full attribute ΓòÉΓòÉΓòÉ
  12691.  
  12692. An attribute that has all of the behaviors and characteristics that an 
  12693. attribute can have:  a data member, a get member function, a set member 
  12694. function, and an event identifier. 
  12695.  
  12696.  
  12697. ΓòÉΓòÉΓòÉ <hidden> free-form surface ΓòÉΓòÉΓòÉ
  12698.  
  12699. The large open area of the Composition Editor window. The free-form surface 
  12700. holds the visual parts contained in the views you build and representations of 
  12701. the nonvisual parts (models) that your application includes. 
  12702.  
  12703.  
  12704. ΓòÉΓòÉΓòÉ <hidden> graphical user interface (GUI) ΓòÉΓòÉΓòÉ
  12705.  
  12706. A type of interface that enables users to communicate with a program by 
  12707. manipulating graphical features, rather than by entering commands. Typically, a 
  12708. graphical user interface includes a combination of graphics, pointing devices, 
  12709. menu bars and other menus, overlapping windows, and icons. 
  12710.  
  12711.  
  12712. ΓòÉΓòÉΓòÉ <hidden> GUI ΓòÉΓòÉΓòÉ
  12713.  
  12714. See  graphical user interface. 
  12715.  
  12716.  
  12717. ΓòÉΓòÉΓòÉ <hidden> handles ΓòÉΓòÉΓòÉ
  12718.  
  12719. Small squares that appear on the corners of a selected visual part in the 
  12720. visual builder. Handles are used to resize parts. 
  12721.  
  12722. Compare to  primary selection. 
  12723.  
  12724.  
  12725. ΓòÉΓòÉΓòÉ <hidden> header file ΓòÉΓòÉΓòÉ
  12726.  
  12727. A file that contains system-defined control information that precedes user 
  12728. data. 
  12729.  
  12730.  
  12731. ΓòÉΓòÉΓòÉ <hidden> inheritance ΓòÉΓòÉΓòÉ
  12732.  
  12733. A mechanism by which an object class can use the attributes, relationships, and 
  12734. member functions defined in more abstract classes related to it (its base 
  12735. classes). 
  12736.  
  12737. An object-oriented programming technique that allows you to use existing 
  12738. classes as bases for creating other classes. 
  12739.  
  12740.  
  12741. ΓòÉΓòÉΓòÉ <hidden> instance ΓòÉΓòÉΓòÉ
  12742.  
  12743. Synonym for  object, a particular instantiation of a data type. 
  12744.  
  12745.  
  12746. ΓòÉΓòÉΓòÉ <hidden> legacy code ΓòÉΓòÉΓòÉ
  12747.  
  12748. Existing code that a user might have. Legacy applications often have 
  12749. character-based, nongraphical user interfaces; usually they are written in a 
  12750. nonobject-oriented language, such as C or COBOL. 
  12751.  
  12752.  
  12753. ΓòÉΓòÉΓòÉ <hidden> loaded ΓòÉΓòÉΓòÉ
  12754.  
  12755. The state of the mouse pointer between the time you select a part from the 
  12756. parts palette and deposit the part on the free-form surface. 
  12757.  
  12758.  
  12759. ΓòÉΓòÉΓòÉ <hidden> main part ΓòÉΓòÉΓòÉ
  12760.  
  12761. The part that users see when they start an application. This is the part from 
  12762. which the main() function C++ code for the application is generated. 
  12763.  
  12764. The main part is a special kind of composite part. 
  12765.  
  12766. See also  part and  subpart. 
  12767.  
  12768.  
  12769. ΓòÉΓòÉΓòÉ <hidden> member ΓòÉΓòÉΓòÉ
  12770.  
  12771. A data object in a structure or a union. 
  12772.  
  12773. In C++, classes and structures can also contain functions and types as members. 
  12774.  
  12775.  
  12776. ΓòÉΓòÉΓòÉ <hidden> member function ΓòÉΓòÉΓòÉ
  12777.  
  12778. An operator or function that is declared as a member of a class. A member 
  12779. function has access to the private and protected data members and member 
  12780. functions of objects of its class. 
  12781.  
  12782.  
  12783. ΓòÉΓòÉΓòÉ <hidden> member function call ΓòÉΓòÉΓòÉ
  12784.  
  12785. A communication from one object to another that requests the receiving object 
  12786. to execute a member function. 
  12787.  
  12788. A member function call consists of a member function name that indicates the 
  12789. requested member function and the arguments to be used in executing the member 
  12790. function. The member function call always returns some object to the requesting 
  12791. object as the result of performing the member function. 
  12792.  
  12793. Synonym for  message. 
  12794.  
  12795.  
  12796. ΓòÉΓòÉΓòÉ <hidden> member function name ΓòÉΓòÉΓòÉ
  12797.  
  12798. The component of a member function call that specifies the requested operation. 
  12799.  
  12800.  
  12801. ΓòÉΓòÉΓòÉ <hidden> message ΓòÉΓòÉΓòÉ
  12802.  
  12803. A request from one object that the receiving object implement a member 
  12804. function. Because data is encapsulated and not directly accessible, a message 
  12805. is the only way to send data from one object to another. Each message specifies 
  12806. the name of the receiving object, the member function to be implemented, and 
  12807. any arguments the member function needs for implementation. 
  12808.  
  12809. Synonym for  member function call. 
  12810.  
  12811.  
  12812. ΓòÉΓòÉΓòÉ <hidden> model ΓòÉΓòÉΓòÉ
  12813.  
  12814. A nonvisual part that represents the state and behavior of a object, such as a 
  12815. customer or an account. 
  12816.  
  12817. Contrast with  view. 
  12818.  
  12819.  
  12820. ΓòÉΓòÉΓòÉ <hidden> module definition file ΓòÉΓòÉΓòÉ
  12821.  
  12822. A file that describes the code segments within a load module. 
  12823.  
  12824. Synonym for DEF file. 
  12825.  
  12826.  
  12827. ΓòÉΓòÉΓòÉ <hidden> nested class ΓòÉΓòÉΓòÉ
  12828.  
  12829. A class defined within the scope of another class. 
  12830.  
  12831.  
  12832. ΓòÉΓòÉΓòÉ <hidden> nonvisual part ΓòÉΓòÉΓòÉ
  12833.  
  12834. A part that has no visual representation at run time. A nonvisual part 
  12835. typically represents some real-world object that exists in the business 
  12836. environment. 
  12837.  
  12838. Compare to  model. Contrast with  view and  visual part. 
  12839.  
  12840.  
  12841. ΓòÉΓòÉΓòÉ <hidden> no-event attribute ΓòÉΓòÉΓòÉ
  12842.  
  12843. An attribute that does not have an event identifier. 
  12844.  
  12845.  
  12846. ΓòÉΓòÉΓòÉ <hidden> no-set attribute ΓòÉΓòÉΓòÉ
  12847.  
  12848. An attribute that does not have a set member function. 
  12849.  
  12850.  
  12851. ΓòÉΓòÉΓòÉ <hidden> notebook part ΓòÉΓòÉΓòÉ
  12852.  
  12853. A visual part that resembles a bound notebook containing pages separated into 
  12854. sections by tabbed divider pages. A user can turn the pages of a notebook or 
  12855. select the tabs to move from one section to another. 
  12856.  
  12857.  
  12858. ΓòÉΓòÉΓòÉ <hidden> object ΓòÉΓòÉΓòÉ
  12859.  
  12860. A computer representation of something that a user can work with to perform a 
  12861. task. An object can appear as text or an icon. 
  12862.  
  12863. A collection of data and member functions that operate on that data, which 
  12864. together represent a logical entity in the system. In object-oriented 
  12865. programming, objects are grouped into classes that share common data 
  12866. definitions and member functions. Each object in the class is said to be an 
  12867. instance of the class. 
  12868.  
  12869. An instance of an object class consisting of attributes, a data structure, and 
  12870. operational member functions. It can represent a person, place, thing, event, 
  12871. or concept. Each instance has the same properties, attributes, and member 
  12872. functions as other instances of the object class, though it has unique values 
  12873. assigned to its attributes. 
  12874.  
  12875.  
  12876. ΓòÉΓòÉΓòÉ <hidden> object class ΓòÉΓòÉΓòÉ
  12877.  
  12878. A template for defining the attributes and member functions of an object. An 
  12879. object class can contain other object classes. An individual representation of 
  12880. an object class is called an object. 
  12881.  
  12882.  
  12883. ΓòÉΓòÉΓòÉ <hidden> object factory ΓòÉΓòÉΓòÉ
  12884.  
  12885. A nonvisual part capable of dynamically creating new instances of a specified 
  12886. part. For example, during the execution of an application, an object factory 
  12887. can create instances of a new class to collect the data being generated. 
  12888.  
  12889.  
  12890. ΓòÉΓòÉΓòÉ <hidden> object-oriented programming ΓòÉΓòÉΓòÉ
  12891.  
  12892. A programming approach based on the concepts of data abstraction and 
  12893. inheritance. Unlike procedural programming techniques, object-oriented 
  12894. programming concentrates on those data objects that comprise the problem and 
  12895. how they are manipulated, not on how something is accomplished. 
  12896.  
  12897.  
  12898. ΓòÉΓòÉΓòÉ <hidden> observer ΓòÉΓòÉΓòÉ
  12899.  
  12900. An object that receives notification from a notifier object. 
  12901.  
  12902.  
  12903. ΓòÉΓòÉΓòÉ <hidden> operation ΓòÉΓòÉΓòÉ
  12904.  
  12905. A member function or service that can be requested of an object. 
  12906.  
  12907.  
  12908. ΓòÉΓòÉΓòÉ <hidden> overloading ΓòÉΓòÉΓòÉ
  12909.  
  12910. An object-oriented programming technique that allows you to redefine functions 
  12911. and most standard C++ operators when the functions and operators are used with 
  12912. class types. 
  12913.  
  12914.  
  12915. ΓòÉΓòÉΓòÉ <hidden> palette ΓòÉΓòÉΓòÉ
  12916.  
  12917. See  parts palette. 
  12918.  
  12919.  
  12920. ΓòÉΓòÉΓòÉ <hidden> parameter connection ΓòÉΓòÉΓòÉ
  12921.  
  12922. A connection that satisfies a parameter of an action or member function by 
  12923. supplying either an attribute's value or the return value of an action, member 
  12924. function, or custom logic. The parameter is always the source of the 
  12925. connection. 
  12926.  
  12927. See also  connection. 
  12928.  
  12929.  
  12930. ΓòÉΓòÉΓòÉ <hidden> parent class ΓòÉΓòÉΓòÉ
  12931.  
  12932. The class from which another part or class inherits data, member functions, or 
  12933. both. 
  12934.  
  12935.  
  12936. ΓòÉΓòÉΓòÉ <hidden> part ΓòÉΓòÉΓòÉ
  12937.  
  12938. A self-contained software object with a standardized public interface, 
  12939. consisting of a set of external features that allow the part to interact with 
  12940. other parts. A part is implemented as a class that supports the INotifier 
  12941. protocol and has a part interface defined. 
  12942.  
  12943. The parts on the palette can be used as templates to create instances or 
  12944. objects. 
  12945.  
  12946.  
  12947. ΓòÉΓòÉΓòÉ <hidden> part event ΓòÉΓòÉΓòÉ
  12948.  
  12949. A representation of a change that occurs to a part. The events on a part's 
  12950. interface enable other interested parts to receive notification when something 
  12951. about the part changes. For example, a push button generates an event signaling 
  12952. that it has been clicked, which might cause another part to display a window. 
  12953.  
  12954.  
  12955. ΓòÉΓòÉΓòÉ <hidden> part event ID ΓòÉΓòÉΓòÉ
  12956.  
  12957. The name of a part static-data member used to identify which notification is 
  12958. being signaled. 
  12959.  
  12960.  
  12961. ΓòÉΓòÉΓòÉ <hidden> part interface ΓòÉΓòÉΓòÉ
  12962.  
  12963. A set of external features that allows a part to interact with other parts. A 
  12964. part's interface is made up of three characteristics: attributes, actions, and 
  12965. events. 
  12966.  
  12967.  
  12968. ΓòÉΓòÉΓòÉ <hidden> Part Interface Editor ΓòÉΓòÉΓòÉ
  12969.  
  12970. An editor that the application developer uses to create and modify attributes, 
  12971. actions, and events, which together make up the interface of a part. 
  12972.  
  12973. Compare to  Class Editor and  Composition Editor. 
  12974.  
  12975.  
  12976. ΓòÉΓòÉΓòÉ <hidden> parts palette ΓòÉΓòÉΓòÉ
  12977.  
  12978. The parts palette holds a collection of visual and nonvisual parts used in 
  12979. building additional parts for an application. The parts palette is organized 
  12980. into categories. Application developers can add parts to the palette for use in 
  12981. defining applications or other parts. 
  12982.  
  12983.  
  12984. ΓòÉΓòÉΓòÉ <hidden> preferred features ΓòÉΓòÉΓòÉ
  12985.  
  12986. A subset of the part's features that appear in a pop-up connection menu. 
  12987. Generally, they are the features used most often. 
  12988.  
  12989.  
  12990. ΓòÉΓòÉΓòÉ <hidden> primary selection ΓòÉΓòÉΓòÉ
  12991.  
  12992. In the Composition Editor, the part used as a base for an action that affects 
  12993. several parts. For example, an alignment tool will align all selected parts 
  12994. with the primary selection. Primary selection is indicated by closed (solid) 
  12995. selection handles, while the other selected parts have open selection handles. 
  12996.  
  12997. See also  selection handles. 
  12998.  
  12999.  
  13000. ΓòÉΓòÉΓòÉ <hidden> private ΓòÉΓòÉΓòÉ
  13001.  
  13002. Pertaining to a class member that is accessible only to member functions and 
  13003. friends of that class. 
  13004.  
  13005.  
  13006. ΓòÉΓòÉΓòÉ <hidden> process ΓòÉΓòÉΓòÉ
  13007.  
  13008. A program running under OS/2, along with the resources associated with it 
  13009. (memory, threads, file system resources, and so on). 
  13010.  
  13011.  
  13012. ΓòÉΓòÉΓòÉ <hidden> program ΓòÉΓòÉΓòÉ
  13013.  
  13014. One or more files containing a set of instructions conforming to a particular 
  13015. programming language syntax. 
  13016.  
  13017. A self-contained, executable module. Multiple copies of the same program can be 
  13018. run in different processes. 
  13019.  
  13020.  
  13021. ΓòÉΓòÉΓòÉ <hidden> protected ΓòÉΓòÉΓòÉ
  13022.  
  13023. Pertaining to a class member that is only accessible to member functions and 
  13024. friends of that class, or to member functions and friends of classes derived 
  13025. from that class. 
  13026.  
  13027.  
  13028. ΓòÉΓòÉΓòÉ <hidden> prototype ΓòÉΓòÉΓòÉ
  13029.  
  13030. A function declaration or definition that includes both the return type of the 
  13031. function and the types of its arguments. 
  13032.  
  13033.  
  13034. ΓòÉΓòÉΓòÉ <hidden> primitive part ΓòÉΓòÉΓòÉ
  13035.  
  13036. A basic building block of other parts. A primitive part can be relatively 
  13037. complex in terms of the function it provides. 
  13038.  
  13039.  
  13040. ΓòÉΓòÉΓòÉ <hidden> process ΓòÉΓòÉΓòÉ
  13041.  
  13042. A collection of code, data, and other system resources, including at least one 
  13043. thread of execution, that performs a data processing task. 
  13044.  
  13045.  
  13046. ΓòÉΓòÉΓòÉ <hidden> property ΓòÉΓòÉΓòÉ
  13047.  
  13048. A unique characteristic of a part. 
  13049.  
  13050.  
  13051. ΓòÉΓòÉΓòÉ <hidden> pure virtual function ΓòÉΓòÉΓòÉ
  13052.  
  13053. A virtual function that has a function definition of = 0;. 
  13054.  
  13055.  
  13056. ΓòÉΓòÉΓòÉ <hidden> receiver ΓòÉΓòÉΓòÉ
  13057.  
  13058. The object that receives a member function call. 
  13059.  
  13060. Contrast with  caller. 
  13061.  
  13062.  
  13063. ΓòÉΓòÉΓòÉ <hidden> resource file ΓòÉΓòÉΓòÉ
  13064.  
  13065. A file that contains data used by an application, such as text strings and 
  13066. icons. 
  13067.  
  13068.  
  13069. ΓòÉΓòÉΓòÉ <hidden> selection handles ΓòÉΓòÉΓòÉ
  13070.  
  13071. In the Composition Editor, small squares that appear on the corners of a 
  13072. selected visual part. Selection handles are used to resize parts. 
  13073.  
  13074. See also  primary selection. 
  13075.  
  13076.  
  13077. ΓòÉΓòÉΓòÉ <hidden> server ΓòÉΓòÉΓòÉ
  13078.  
  13079. A computer that provides services to multiple users or workstations in a 
  13080. network; for example, a file server, a print server, or a mail server. 
  13081.  
  13082.  
  13083. ΓòÉΓòÉΓòÉ <hidden> service ΓòÉΓòÉΓòÉ
  13084.  
  13085. A specific behavior that an object is responsible for exhibiting. 
  13086.  
  13087.  
  13088. ΓòÉΓòÉΓòÉ <hidden> settings view ΓòÉΓòÉΓòÉ
  13089.  
  13090. A view of a part that provides a way to display and set the attributes and 
  13091. options associated with the part. 
  13092.  
  13093.  
  13094. ΓòÉΓòÉΓòÉ <hidden> sticky ΓòÉΓòÉΓòÉ
  13095.  
  13096. In the Composition Editor, the mode that enables you to add multiple parts of 
  13097. the same class (for example, three push buttons) without going back and forth 
  13098. between the parts palette and the free-form surface. 
  13099.  
  13100.  
  13101. ΓòÉΓòÉΓòÉ <hidden> structure ΓòÉΓòÉΓòÉ
  13102.  
  13103. A construct that contains an ordered group of data objects. Unlike an array, 
  13104. the data objects within a structure can have varied data types. 
  13105.  
  13106.  
  13107. ΓòÉΓòÉΓòÉ <hidden> subpart ΓòÉΓòÉΓòÉ
  13108.  
  13109. A part that is used to create another part. 
  13110.  
  13111. See also  nonvisual part, part, and  visual part. 
  13112.  
  13113.  
  13114. ΓòÉΓòÉΓòÉ <hidden> superclass ΓòÉΓòÉΓòÉ
  13115.  
  13116. See  abstract class and  base class. 
  13117.  
  13118.  
  13119. ΓòÉΓòÉΓòÉ <hidden> tear-off attribute ΓòÉΓòÉΓòÉ
  13120.  
  13121. An attribute that an application developer has exposed to work with as though 
  13122. it were a stand-alone part. 
  13123.  
  13124.  
  13125. ΓòÉΓòÉΓòÉ <hidden> template ΓòÉΓòÉΓòÉ
  13126.  
  13127. A family of classes or functions with variable types. 
  13128.  
  13129.  
  13130. ΓòÉΓòÉΓòÉ <hidden> thread ΓòÉΓòÉΓòÉ
  13131.  
  13132. A unit of execution within a process. 
  13133.  
  13134.  
  13135. ΓòÉΓòÉΓòÉ <hidden> tool bar ΓòÉΓòÉΓòÉ
  13136.  
  13137. The strip of icons along the top of the free-form surface. The tool bar 
  13138. contains tools to help you construct composite parts. 
  13139.  
  13140.  
  13141. ΓòÉΓòÉΓòÉ <hidden> UI ΓòÉΓòÉΓòÉ
  13142.  
  13143. See  user interface. 
  13144.  
  13145.  
  13146. ΓòÉΓòÉΓòÉ <hidden> unloaded ΓòÉΓòÉΓòÉ
  13147.  
  13148. The state of the mouse pointer before you select a part from the parts palette 
  13149. and after you deposit a part on the free-form surface. In addition, you can 
  13150. unload the mouse pointer by pressing the Esc key. 
  13151.  
  13152.  
  13153. ΓòÉΓòÉΓòÉ <hidden> user interface (UI) ΓòÉΓòÉΓòÉ
  13154.  
  13155. The hardware, software, or both that enable a user to interact with a computer. 
  13156.  
  13157. The term user interface normally refers to the visual presentation and its 
  13158. underlying software with which a user interacts. 
  13159.  
  13160.  
  13161. ΓòÉΓòÉΓòÉ <hidden> variable ΓòÉΓòÉΓòÉ
  13162.  
  13163. A storage place within an object for a data feature. The data feature is an 
  13164. object, such as number or date, stored as an attribute of the containing 
  13165. object. 
  13166.  
  13167. A part that receives an identity at run time. A variable by itself contains no 
  13168. data or program logic; it must be connected such that it receives runtime 
  13169. identity from a part elsewhere in the application. 
  13170.  
  13171.  
  13172. ΓòÉΓòÉΓòÉ <hidden> view ΓòÉΓòÉΓòÉ
  13173.  
  13174. A visual part, such as a window, push button, or entry field. 
  13175.  
  13176. A visual representation that can display and change the underlying model 
  13177. objects of an application. Views are both the end result of developing an 
  13178. application and the basic unit of composition of user interfaces. 
  13179.  
  13180. Compare to  visual part. Contrast with  model. 
  13181.  
  13182.  
  13183. ΓòÉΓòÉΓòÉ <hidden> virtual function ΓòÉΓòÉΓòÉ
  13184.  
  13185. A function of a class that is declared with the keyword virtual. The 
  13186. implementation that is executed when you make a call to a virtual function 
  13187. depends on the type of the object for which it is called. This is determined at 
  13188. run time. 
  13189.  
  13190.  
  13191. ΓòÉΓòÉΓòÉ <hidden> visual part ΓòÉΓòÉΓòÉ
  13192.  
  13193. A part that has a visual representation at run time. Visual parts, such as 
  13194. windows, push buttons, and entry fields, make up the user interface of an 
  13195. application. 
  13196.  
  13197. Compare to  view. Contrast with  nonvisual part. 
  13198.  
  13199.  
  13200. ΓòÉΓòÉΓòÉ <hidden> visual programming tool ΓòÉΓòÉΓòÉ
  13201.  
  13202. A tool that provides a means for specifying programs graphically. Application 
  13203. programmers write applications by manipulating graphical representations of 
  13204. components. 
  13205.  
  13206.  
  13207. ΓòÉΓòÉΓòÉ <hidden> white space ΓòÉΓòÉΓòÉ
  13208.  
  13209. Space characters, tab characters, form-feed characters, and new-line 
  13210. characters. 
  13211.  
  13212.  
  13213. ΓòÉΓòÉΓòÉ <hidden> window ΓòÉΓòÉΓòÉ
  13214.  
  13215. A rectangular area of the screen with visible boundaries in which information 
  13216. is displayed. Windows can overlap on the screen, giving it the appearance of 
  13217. one window being on top of another. 
  13218.  
  13219. In the Composition Editor, a window is a part that can be used as a container 
  13220. for other visual parts, such as push buttons. 
  13221.  
  13222.  
  13223. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  13224.  
  13225. This book explores OO concepts and design. It shows you, through various 
  13226. techniques and examples, how to develop applications using OO. 
  13227.  
  13228. It is available through Benjamin/Cummings, Redwood City, California. Its ISBN 
  13229. number is 0-8053-0091-0. 
  13230.  
  13231.  
  13232. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  13233.  
  13234. This book explores OO programming. It shows you how to build reusable objects 
  13235. through examples and provides a comparison between OO programming and 
  13236. traditional programming. 
  13237.  
  13238. It is available through the Addison-Wesley Publishing Company, Reading, 
  13239. Massachusetts. Its ISBN number is 0-201-10393-1. 
  13240.  
  13241.  
  13242. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  13243.  
  13244. This book describes the guidelines that define the Common User Access user 
  13245. interface. The Common User Access user interface is an OO graphical user 
  13246. interface that provides a consistent look and feel for products that adopt the 
  13247. CUA interface as their standard. 
  13248.  
  13249. It is available through QUE Corporation, Carmel, Indiana. Its ISBN number is 
  13250. 1-56529-170-0. 
  13251.  
  13252.  
  13253. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  13254.  
  13255. This book discusses user-centered design in its full scope:  task analysis, 
  13256. prototyping, empirical evaluating, interface techniques, and guidelines. 
  13257.  
  13258. It is available through Digital Press, Maynard, Massachusetts.