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