home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / VSCPPv8.zip / VACPP / IBMCPP / samples / IOC / LANCELOT / LANCELOT.HLP (.txt) < prev    next >
OS/2 Help File  |  1995-06-05  |  14KB  |  380 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. What is Lancelot? ΓòÉΓòÉΓòÉ
  3.  
  4. Lancelot is a personnel data tracking tool. It tracks general personnel 
  5. information, badge, status, skills, system account information, projects, 
  6. tasks, and your timecard. This sample application is intended to show 
  7. integration rather than optimum performance or coding. 
  8.  
  9. Lancelot was written by our QA group to utilize some of the more complex 
  10. objects provided by the IBM Open Class: User Interface Class Library.  Lancelot 
  11. primarily utilizes these objects: 
  12.  
  13.      IFrameWindow 
  14.      IMenuBar 
  15.      Infoarea 
  16.      IHelp 
  17.      IFont 
  18.      IResourceLibrary 
  19.      IContainerControl 
  20.      IContainerObject 
  21.      IPopupMenu 
  22.      INotebook 
  23.      IMultiCellCanvas 
  24.      ISetCanvas 
  25.      IProfile 
  26.      IEntryField 
  27.      IPushButton 
  28.      IGraphicPushButton 
  29.      INumericSpinButton 
  30.      IComboBox 
  31.      ICheckBox 
  32.      IMenuBar 
  33.      ITitle 
  34.      IString 
  35.      ICommandHandler 
  36.      ICnrHandler 
  37.      ICnrMenuHandler 
  38.      IDM*  <Direct Manipulation (i.e. Drag/Drop)> 
  39.      IToolBar 
  40.      IToolBarButton 
  41.      IFlyOverHelp 
  42.      IFlyOverHelpHandler 
  43.      IGPie 
  44.      IGRectangle 
  45.      IGString 
  46.  
  47.  In addition, Lancelot uses a simple flat database implemented with IProfile. 
  48.  However, this flat database is used only to show data interaction with the GUI 
  49.  objects and avoid requiring a relational database installed on your system. 
  50.  
  51.  Note:  You should NOT use the flat database provided for any of your own 
  52.  applications!  We suggest you don't even look at the internals of the database 
  53.  code.  The files you should avoid are ld*.*pp. You should use a true 
  54.  relational database for your applications. 
  55.  
  56.  
  57. ΓòÉΓòÉΓòÉ 2. Lancelot Usage ΓòÉΓòÉΓòÉ
  58.  
  59. To create Lancelot, you must first compile and link the application and it's 
  60. components. 
  61.  
  62.      On AIX, issue 
  63.  
  64.                make
  65.  
  66.      On OS/2, issue 
  67.  
  68.                nmake
  69.  
  70.      For other environments, issue 
  71.  
  72.                make
  73.  
  74.  To execute Lancelot, simply issue 
  75.  
  76.      lancelot
  77.  
  78.  
  79. ΓòÉΓòÉΓòÉ 2.1. Lancelot Main window ΓòÉΓòÉΓòÉ
  80.  
  81. Lancelot's main view is what you see when the application first comes up.  It 
  82. contains the Query Personnel object and any private query objects you may have 
  83. created. The Query Personnel object queries employee information dependent on 
  84. your search criteria.  You have the option of saving the search criteria in the 
  85. main view for faster access next time. 
  86.  
  87.  
  88. ΓòÉΓòÉΓòÉ 2.2. Lancelot Query Information window ΓòÉΓòÉΓòÉ
  89.  
  90. Lancelot's Query Information window contains a notebook with pages for 
  91. specifying personnel search criteria. The pages available are: 
  92.  
  93.  General Page                  General information for a person. 
  94.  
  95.  Accounts Page                 User accounts and systems for a person. 
  96.  
  97.  Skills Page                   Individual skills for a person. 
  98.  
  99.  Badge Page                    Badge information for a person. 
  100.  
  101.  Status Page                   Employement status information for a person. 
  102.  
  103.  The buttons available are: 
  104.  
  105.  Query                         Query the personnel database given your search 
  106.                                criteria. If persons are found matching your 
  107.                                criteria, a window appears with objects 
  108.                                representing each person. 
  109.  
  110.  Save                          Save your search criteria to the main view 
  111.                                window for each access next time. 
  112.  
  113.  Help                          Provide help for a specific page 
  114.  
  115.  
  116. ΓòÉΓòÉΓòÉ 2.3. Lancelot Personnel window ΓòÉΓòÉΓòÉ
  117.  
  118. Lancelot's Personnel view is what you see when the application finds personnel 
  119. matching your search criteria. It contains an object for each person. By 
  120. opening an object, the Employee Information window appears with specific 
  121. information for this person. 
  122.  
  123.  
  124. ΓòÉΓòÉΓòÉ 2.4. Lancelot Employee Information window ΓòÉΓòÉΓòÉ
  125.  
  126. Lancelot's Employee Information window is displayed to show employee 
  127. information for a single employee.  Any changes to the employee information 
  128. will be saved in the database.  However, the Undo button can undo any changes 
  129. you entered. 
  130.  
  131. The pages available are: 
  132.  
  133.  General Page                  General information for the person. 
  134.  
  135.  Accounts Page                 User accounts and systems for the person. 
  136.  
  137.  Skills Page                   Individual skills for the person. 
  138.  
  139.  Badge Page                    Badge information for the person. 
  140.  
  141.  Status Page                   Employement status information for the person. 
  142.  
  143.  Project Page                  Projects the person has worked on. 
  144.  
  145.  Tasks Page                    Work tasks the person has worked on. 
  146.  
  147.  Timecard Page                 Timecard for the person. 
  148.  
  149.  The buttons available are: 
  150.  
  151.  Undo                          Undo any changes to the employee's information 
  152.                                you entered. 
  153.  
  154.  Help                          Provide help for a specific page 
  155.  
  156.  
  157. ΓòÉΓòÉΓòÉ 3. Lessons Learned ΓòÉΓòÉΓòÉ
  158.  
  159. In coding Lancelot, we learned alot by the fine nuances of coding GUI 
  160. applications. 
  161.  
  162.  
  163. ΓòÉΓòÉΓòÉ 3.1. General ΓòÉΓòÉΓòÉ
  164.  
  165. There are several general things we learned in coding Lancelot. 
  166.  
  167.      When instantiating IWindow objects with the new operator, you must make 
  168.       sure to delete these objects when finished.  However, there are times 
  169.       when you don't know how many windows you will have. Therefore, you can 
  170.       use setAutoDeleteObject().  This function deletes the IWindow object for 
  171.       you. 
  172.  
  173.       Example: 
  174.  
  175.                IFrameWindow* myFrame = new IFrameWindow( ID_FRAME );
  176.                myFrame->setAutoDeleteObject( true );
  177.  
  178.      IProfile changes are not visible until the IProfile object is destroyed. 
  179.  
  180.      There are two methodologies to using event handlers. 
  181.  
  182.         1. Create your own event handler class that inherits from an event 
  183.            handler 
  184.  
  185.         2. Multiply inherit from some visual object and from an event handler 
  186.       The first method is preferred. See LMainWindow (lmainwin.cpp) for an 
  187.       example. However, the second method requires less coding. See LInfoWindow 
  188.       (linfowin.cpp) for an example. 
  189.  
  190.      If you do not specify a title string or define an ITitle for a frame 
  191.       window, the frame window will get its title from the resource file if the 
  192.       resource Id for the frame window is specified in the string table. 
  193.  
  194.  
  195. ΓòÉΓòÉΓòÉ 3.2. Containers ΓòÉΓòÉΓòÉ
  196.  
  197. There are several things we learned about containers in coding Lancelot. Here 
  198. are some of the items we learned. 
  199.  
  200.      In order for a container to show detailsView, the container must know 
  201.       about offset (binary location) information for individual fields in a 
  202.       data class (data structure).  There are two approaches for the container 
  203.       to query a data class' fields: 
  204.  
  205.         1. Make the data class a friend of the container.  Then the container 
  206.            can use something like this when creating it's columns: 
  207.  
  208.                          IContainerColumn lastNameColumn(
  209.                                  offsetof( EmployeeCnrObject, theLastName ) );
  210.  
  211.         2. -or- A better solution is to create a function in the data class for 
  212.            each data field.  The function would do the following: 
  213.  
  214.                          unsigned long EmployeeObject::lastNameOffset()
  215.                          {
  216.                             return ( offsetof( EmployeeCnrObject, theLastName ) );
  217.                          }
  218.            The container column would then look like this: 
  219.  
  220.                          IContainerColumn nameColumn(
  221.                                  EmployeeCnrObject::lastNameOffset() );
  222.  
  223.       The only advantage to using option 2 is that any container can get the 
  224.       data class field offsets without having to be friends. The disadvantage 
  225.       is that if you have alot of data fields, you will have to code query 
  226.       functions for each.  A good example of each can be found in the class 
  227.       LMainCnr (lmainwin.cpp) and LPersonnelCnr (lperswin.cpp). 
  228.  
  229.      If you have a container object that contains your own data class object 
  230.       and you want your data class object's private data fields to appear in 
  231.       the container, do not specify the offset for your data class object 
  232.       itself. Instead, specify the offset of the container object's variable 
  233.       name representing your your data class and reference the data class 
  234.       object's internal data field. 
  235.  
  236.       Example: 
  237.  
  238.                IContainerColumn lastNameColumn(
  239.                          offsetof( EmployeeCnrObject, privateData.theLastName ) );
  240.  
  241.      In TreeIconView, the container allows only single selection. Therefore, 
  242.       we must disallow the Select All function since only the last cnr object 
  243.       will be selected.  And we must disallow the Deselect All function since 
  244.       an exception will be thrown. 
  245.  
  246.  
  247. ΓòÉΓòÉΓòÉ 3.3. Notebooks ΓòÉΓòÉΓòÉ
  248.  
  249. There are several things we learned about notebooks in coding Lancelot. Here 
  250. are some of the items we learned. 
  251.  
  252.      When a page is added to a notebook and using the autoPageSize style, the 
  253.       pages are automatically resized to the current notebook size.  Therefore, 
  254.       we need to resize the notebook pages to their minimum size so that the 
  255.       notebook can properly calculate it's minimum size.  See LInfoNotebook 
  256.       (linfonb.cpp) for an example. 
  257.  
  258.      In order to property size notebook tabs based on the current font size, 
  259.       we sized the major tab width to be the 
  260.  
  261.       ( average character width for the current font ) X ( number of characters 
  262.       we want to display ). 
  263.  
  264.       ISized the major tab height to be the 
  265.  
  266.       ( average uppercase height for the current font ) X 2. 
  267.  
  268.                setMajorTabSize( ISize( notebookFont.avgCharWidth() *
  269.                                        ID_INFO_NOTEBOOK_TAB_CHARS,
  270.                                        notebookFont.avgUppercase() * 2 ) );
  271.       See LInfoNotebook (linfonb.cpp) for an example. 
  272.  
  273.  
  274. ΓòÉΓòÉΓòÉ 3.4. Canvases ΓòÉΓòÉΓòÉ
  275.  
  276. There are several things we learned about canvases in coding Lancelot. Here are 
  277. some of the items we learned. 
  278.  
  279.      For aligning like objects such as radio buttons, ISetCanvas does the best 
  280.       job aligning. 
  281.  
  282.      For aligning unlike objects such as entryfields and static text, 
  283.       IMultiCellCanvas does the best job aligning. 
  284.  
  285.      When aligning unlike objects, a minimum size for one object is usually 
  286.       too large for an unlike object in the same column.  Therefore, place the 
  287.       unlike object in a different column (usually one column more is 
  288.       sufficient). 
  289.  
  290.  
  291. ΓòÉΓòÉΓòÉ 3.5. Help ΓòÉΓòÉΓòÉ
  292.  
  293. There are several things we learned about help in coding Lancelot. Here are 
  294. some of the items we learned. 
  295.  
  296.      General help is simply the panel associated with the HELPITEM in the help 
  297.       table. 
  298.  
  299.       Example: 
  300.  
  301.                HELPITEM      ID_MAIN, ......
  302.  
  303.      Help index and using help are usually generic.  So we can use the generic 
  304.       system help by getting the id from IHelpWindow::index and 
  305.       IHelpWindow::using. 
  306.  
  307.      Keys help is always specific to the application.  Therefore, we must 
  308.       write our own in the .IPF file.  There can be two approaches to making 
  309.       keys help work: 
  310.  
  311.         1. In the command() function, case off the id defined in the .RC for 
  312.            the user selecting "Keys help" and then calling help.show( id ) that 
  313.            is defined in the .IPF file. However, if the user selects "Help/Keys 
  314.            help" inside the Keys Help help window, an error can occur since the 
  315.            help window itself doesn't know about the id in the .IPF file. 
  316.         2. -or- A better way is: 
  317.              a. Identify the "Keys help" menu with SC_HELPKEYS and specify the 
  318.                 MIS_SYSCOMMAND attribute. 
  319.              b. Create an IHelpHandler in your source code 
  320.              c. Have the IHelpHandler object handleEventsFor the main window 
  321.              d. Override the keysHelpId() function to specify the .IPF id for 
  322.                 keys help. 
  323.  
  324.                 Example: 
  325.  
  326.                                    event.setResult( id-in-IPF-file );
  327.  
  328.      Product information is your own dialog defined in the .CPP. 
  329.  
  330.      F1 help for Keys Help must match the id for SC_HELPKEYS. It is defined 
  331.       for OS/2 PM in pmwin.h. It is defined for AIX Motif in ipmrc2X. 
  332.  
  333.      You don't have to create a new IHelpWindow object for each secondary 
  334.       frame window you create.  However if you don't, the following will occur: 
  335.  
  336.         1. When closing the secondary window, the help window doesn't close 
  337.         2. When closing the help window, focus returns to the owner of the 
  338.            secondary window. Nevertheless, these situations can be overcome by 
  339.            using IHelpWindow::setAssociateWindow() for the current window that 
  340.            has focus. 
  341.         3. In order to have each notebook page show help when the Help button 
  342.            is pressed, the notebook page must know about the frame window's 
  343.            help window object so that it can call help.show(...). The static 
  344.            function IHelpWindow::helpWindow() returns this object. 
  345.  
  346.            Example: 
  347.  
  348.                          helpWin = IHelpWindow::helpWindow( this );
  349.                          if ( helpWin )
  350.                               helpWin->show( IResourceId( ID_xxx ) );
  351.  
  352.  
  353. ΓòÉΓòÉΓòÉ 3.6. Toolbar ΓòÉΓòÉΓòÉ
  354.  
  355. There are several things we learned about toolbars and toolbar buttons in 
  356. coding Lancelot.  Here are some of the items we learned. 
  357.  
  358.      If the toolbar appears in the header definition (.HPP) before the client, 
  359.       the toolbar will take the focus. 
  360.  
  361.      Toolbar buttons by default have a standard size.  But some words will not 
  362.       fit inside the space provided.  Therefore, we allowed each button to size 
  363.       itself based on it's needs. 
  364.  
  365.      Since there doesn't exist a standard toolbar button bitmap for some of 
  366.       Lancelot's functions, we created our own bitmaps. These bitmaps must be 
  367.       20x17 in order to match height and width of the predefined library 
  368.       toolbar button bitmaps. 
  369.  
  370.  
  371. ΓòÉΓòÉΓòÉ 3.7. 2D Graphics ΓòÉΓòÉΓòÉ
  372.  
  373. There are several things we learned about drawing with 2D graphics in coding 
  374. Lancelot.  Here are some of the items we learned. 
  375.  
  376.      If you don't use the setClippingRect() function to explicity set the 
  377.       boundardy of a graphic string (IGString), a graphic string may expand 
  378.       into the area of another graphic string. Then the graphic string can be 
  379.       seen through the other graphic string. 
  380.