home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / BASIC / MKFORM / MAKEFORM.DOC < prev    next >
Text File  |  1994-03-28  |  50KB  |  1,076 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. MAKEFORM
  8.  
  9.  
  10.  
  11.  
  12. Merlin's Application Framework
  13.  
  14.  
  15.  
  16. MANUAL
  17.  
  18.  
  19.  
  20.  
  21.  
  22. (C) Merlin's Software
  23. P.O.Box 473
  24. Zeist NL-3700-AL
  25. THE NETHERLANDS
  26.  
  27.  
  28.  
  29. MERLIN'S SOFTWARE
  30. It's Magic!
  31. Software for Witches, Wizards
  32. and other creative people.
  33. P.O.Box 473 - Zeist NL-3700-AL - The Netherlands 
  34.  
  35. If you had a magic wand, wouldn't you banish all computers, and all red
  36. tape, and move to a nice warm sunny country? Dance in the moonlight, com-
  37. municate with the fairies, sip a glass of wine with some good friends, and
  38. simply enjoy life?
  39.  
  40. It isn't human destiny to sit behind a silly computer screen and punch
  41. buttons... But if we have to, let's at least remind ourselves of the Dream
  42. Time that our Inner Self longs for...
  43.  
  44. Merlin's Software develops computer programs that put some of the magic,
  45. the creativity and the fun of being alive into the software. 
  46. Just as we surround ourselves in our home with objects that express our
  47. innermost feelings, and wear clothes that reflect our outlook on life, so
  48. too software should be an extension of our personality. There is no reason
  49. why everyone should use the same overweight elephantware and conform to
  50. the same standard of drab office grey now, is there?
  51.  
  52. Merlin's Software tries to achieve this goal by:
  53.     developing deluxe graphical applications that go beyond simple func-
  54.      tionality and incorporate beauty and creativity.
  55.     developing custom software and modules.
  56.     developing programming tools and utilities for other creative devel-
  57.      opers.
  58.  
  59. If you have specific needs or creative ideas, and want a completely free
  60. evaluation (no strings attached), please get in touch with Merlin's
  61. Software!
  62. Life is supposed to be FUN!
  63.  
  64. Dennis ten Siethoff
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Contents
  71.  
  72.  
  73. General Section
  74. The Story So Far ...
  75. Overview
  76. Application Framework
  77. ShareWare
  78. Technicalities & Legalese
  79. Credits
  80. Quick Start
  81. PCX files
  82.  
  83. MakeForm Overview
  84. Starting MakeForm
  85. Design Stage
  86. Data Entry Screen
  87. Test Run
  88. Save Your Work
  89. Exit MakeForm
  90. Completing Your Program
  91.  
  92. Reference Section
  93. Text Fields
  94. Push Buttons
  95. Mouse Fields
  96. Scroll Bars
  97. List Boxes
  98. Creating a Menu System
  99.  
  100.  
  101. Advanced Section
  102. Event Driven Programs
  103. A Small Tutorial
  104. Out Of Memory
  105. Working With The Code
  106. Messages
  107. Asking Questions
  108. Input! Need Input!
  109. Save Yourself!
  110. Show Yourself!
  111. Various Routines
  112.  
  113. Advanced Coding
  114. Object Structure
  115. Adding Custom Objects
  116. Altering Existing Objects
  117.  
  118. Appendices
  119. Library Documentation
  120. Batch File Editor - an example
  121.  
  122.  
  123.  
  124.  
  125. The Story So Far ...
  126.  
  127. You settle back in your chair in the main hall. The presenter opens his
  128. laptop, switches on the small light next to him, and taps on the micro-
  129. phone.
  130.  
  131. "Welcome to Merlin's Graphical Application FrameWork! Say goodbye to all
  132. the tedious coding to get a nice push button on screen (never mind about
  133. getting them to work...) or to figure out how to create a scroll bar or a
  134. multi-line text entry field with proportional fonts and word wrap! Just
  135. make a VGA full screen PCX drawing of your complete interface, as fancy as
  136. you like, and create a fully working program with Merlin's Application
  137. Framework in minutes!"
  138.  
  139. Applause as the light dims...
  140. The oversized screen comes to life, showing a car dashboard with slides,
  141. buttons, meters and little blinking lights. The roar of an engine in full
  142. Dolby stereo completes the illusion.
  143. "You can design a custom front end for your annual car model database..."
  144. The presenter uses his laptop to show how to press a button, pop up a menu
  145. and start the application.
  146.  
  147. The screen fades, and slowly a medieval manuscript comes on the screen,
  148. complete with an illuminated capital on the left. Tinkling harp music can
  149. be heard in the background. On the right, some worn-looking tabs are
  150. visible, and on the bottom you can see the frayed strands of the ribbons
  151. that mark  other sections in the book. 
  152. "How do you like this as the on-screen catalogue to your antique shop?"
  153.  
  154. The screen fades again. As it comes back to life, a full featured word
  155. processor is visible, complete with three custom button bars. "This is
  156. just a mock-up, but you can designs applications that look like this..."
  157.  
  158. As the screen comes back to life for the last time, a misty forest scene
  159. in pale white and green is accompanied by soft New Age music. As the
  160. presenter opens a window, you can see that it is a catalogue of CD's,
  161. hooked to a CD player. The presenter chooses some appropriate music to end
  162. his show. As the lights in the hall come back to life, you think to
  163. yourself "Blast, I didn't know you could do all this with just a simple
  164. 16-colour VGA screen! This looks like FUN!"
  165. Meanwhile, the presenter smiles to the applause, and continues to high-
  166. light the many possibilities of this application framework....
  167.  
  168. Well, it's just a story, but it might as well be true! All that you've
  169. seen you can design with Merlin's Application Framework!
  170.  
  171.  
  172. Overview
  173.  
  174. MakeForm allows you, with absolutely no interface coding at all, to create
  175. a visually stunning graphical front-end (GUI graphical user interface) to
  176. any database or program. 
  177.  
  178. MakeForm can convert a screen drawing (PCX file) that contains buttons,
  179. scroll bars, text entry fields, list box areas and mouse regions into a
  180. real, working program for you. All you need to do is to add the code to
  181. process the user actions, like pressing a button to save something. All
  182. code to handle text input, depressing buttons, using scroll bars etc. is
  183. already present! And that is definitely not to be sneezed at: it includes
  184. proportional font text editing, word wrap, search, copy, paste, formatted
  185. text input, numeric, string, date, memo, logical fields, list boxes,
  186. scroll bars, mouse fields, push buttons, etcetera! Complete code to build
  187. menu bars, drop down menus, pop up menus etc. is included as well. There
  188. are extremely simple calls to put warnings and messages on screen, or
  189. create a pop-up edit box to ask for a file name for example. 
  190.  
  191. Makeform provides an extensive application framework to quickly build
  192. complete graphical applications for DOS, for example database entry forms,
  193. utilities, but also complete 'heavy weight' applications. Examples of what
  194. can be achieved with MakeForm are MakeForm itself, and Merlin's Deluxe
  195. Font Editor, which is part of this package.
  196.  
  197. MakeForm allows you to write sophisticated programs with just a fraction
  198. of the code you would normally have to write. To back up this claim,
  199. consider the source code of MakeForm itself. If you had to write it
  200. yourself from scratch, you would be expected to write well over 150k of
  201. source code text, not counting all the assembler routines to handle PCX
  202. files etc. However, MakeForm could be re-created using MakeForm itself by
  203. just writing about 700 lines of QuickBASIC code, divided into a MAIN block
  204. and just 5 subroutines!
  205.  
  206. And all that still results in relatively small EXE files - just consider
  207. the size of MakeForm.EXE (about 90k uncompressed). You can write similar
  208. programs as well, WITH all these nice options and possibilities, and make
  209. C++ programmers turn green with envy!
  210.  
  211.  
  212. Application Framework
  213.  
  214. What is an Application FrameWork? An Application FrameWork is a 'frame-
  215. work' of routines and modules which take care of all the things many
  216. programs have in common. For example text input, pressing buttons, moving
  217. scroll bars, updating the screen, keeping track of the cursor, opening and
  218. closing windows, etcetera. We usually think of the application interface,
  219. so in a sense Windows is an application framework which provides many
  220. services to individual programs, and the dBASE languages (dBASE, Clipper
  221. etc.) are application frameworks as well.
  222.  
  223. An Application FrameWork has advantages as well as disadvantages. The ad-
  224. vantages are obvious: only a tiny amount of code needs to be written to
  225. complete an application. Most of the 'nitty gritty' stuff is already
  226. present. As long as the capabilities of the Application Framework are what
  227. you need, there are few disadvantages.
  228.  
  229. The disadvantages are less clear, but nevertheless present. You have to
  230. become familiar with the code, and in effect are learning another (tiny)
  231. programming language. If you want to do things for which the framework
  232. wasn't designed, you may spend a lot of time figuring out how to do that.
  233. It would be less time than it would take to re-write the lot yourself, but
  234. still. Also, many Application Frameworks try to be everything to everyone,
  235. and consequently are so bloated that you end up with executables of 300k
  236. or more just to say 'Hello World'. 
  237.  
  238. How does Merlin's Application Framework tip this balance?
  239.  
  240. Area of application
  241. Merlin's Application Framework is designed to let you program visually
  242. stunning, graphical, DOS based, full screen applications. It has one edge
  243. over most other programs in this field, and that is that you can design
  244. your screen with a drawing program. So you are NOT limited to 'just'
  245. Windows-type interfaces, which although pretty, are in a sense only text-
  246. type interfaces without any room for artistic input. 
  247. To get a good idea of what is possible, visualise the examples from the
  248. story above, or take a good look at the MakeForm MF_TUTOR example, or
  249. Merlin's Deluxe Font Editor. If you want to make programs that look like
  250. that, Merlin's Application Framework is for you!
  251.  
  252. Artistic aspirations
  253. If you're creative, you like drawing or otherwise creating beautiful
  254. backgrounds, you'll love Merlin's Application Framework. If you don't, you
  255. may invest in a couple of CD-ROM's with PCX files to use. If you want to
  256. program for Windows, you'll hate Merlin's Application Framework - it
  257. wasn't designed to accommodate Windows. You can run any program created by
  258. MakeForm under Windows, provided you do it in a full screen DOS box.
  259. Windows won't let you change colour palettes for starters, and I hate
  260. programs that refuse to let me do things the way I want...
  261.  
  262. Learning
  263. Merlin's Application Framework is a sophisticated collection of modules
  264. and routines. Although you will only call 3 of these routines yourself,
  265. there will be plenty of opportunities where you can benefit from under-
  266. standing the rest of the framework. The complete QuickBASIC source code
  267. will be yours upon registration. This code is extensively commented, and
  268. if you can't figure out something we are always here, and happy to help
  269. you. In many instances the comments already indicate where customising is
  270. possible. But make no mistake: you will have to spend a little time with
  271. it to become familiar with its workings - comparable to switching from
  272. GWBasic to QuickBASIC for example.
  273. This manual also contains lots of hints and tips that will allow you to
  274. become familiar with the environment very quickly. If you invest in
  275. completing the tutorial (takes about a week of spare time) you will feel
  276. confident in tackling larger projects.
  277.  
  278. Size
  279. Merlin's Application Framework is small. MakeForm itself can be recompiled
  280. with QuickBASIC alone to about 120k. If you compare that to a Clipper
  281. database browsing utility that easily takes 300k you'll understand that
  282. there is very little overhead in Merlin's Application Framework.
  283. Modules you don't use you can remove, for example scroll bar code can be
  284. removed if your application doesn't use it, or word wrap. To decrease size
  285. even further, MakeForm itself was linked with PDQ, an alternative link-
  286. library from Crescent Software (see credits for their address), reducing
  287. the EXE file to about 90k. 'Diet' did the rest, so the result is an EXE
  288. file of about 48k. Show that to any other programmer, and show them what
  289. MakeForm does, and they start looking for a file called MAKEFORM.OVL of
  290. about 400k! Merlin's Software ... It's Magic!
  291.  
  292. Bottom line
  293. If you have decided to order MakeForm, based on your evaluation of the
  294. Shareware version, but the product does not live up to your expectations,
  295. please tell us so and we will refund your money. If there are special
  296. things you would like to do, but can't figure out how, feel free to call
  297. on us - we'll be glad to help! We may be able to present a solution very
  298. quickly, and your ideas may very well end up in the next update of the
  299. Application Framework! Sometimes it only takes finding the right spot to
  300. make your changes, sometimes it may be more complicated. And on occasion a
  301. custom module may need to be written. We will gladly give you a quote for
  302. that, no strings attached! This manual also contains instructions for
  303. writing your own custom modules to 'create objects' that MakeForm does not
  304. have.
  305.  
  306. Language
  307. Merlin's Application Framework was written in QuickBASIC and assembler,
  308. and is meant to be used with QuickBASIC. You do not need to be familiar
  309. with assembler to use Merlin's Application Framework, but you are expected
  310. to be familiar and competent with QuickBASIC. If you use other versions of
  311. BASIC, please get in touch - there may be a version of MakeForm available
  312. for your language. If not, be prepared to spend some time changing
  313. things - for PowerBASIC for example the whole library needs to be rewrit-
  314. ten because string handling is done differently in that language.
  315.  
  316. MakeForm
  317. The name 'MakeForm' comes from the word 'form', like a tax form, a sheet
  318. with various areas you are supposed to fill in. Databases often use such
  319. 'sheets' on screen for the user to fill in, and the obvious application is
  320. a database entry form. Although Merlin's Application Framework can do much
  321. more, the name of the program still reflects its origins. The complete
  322. collection of modules, library, handbook etc. is the actual Application
  323. Framework, the program MakeForm provides the link between the PCX drawing
  324. and the QuickBASIC code that will become the final program you write.
  325.  
  326. Shareware
  327.  
  328. My experiences with Shareware are great, except when it comes to people
  329. registering for it ...! So in order to protect my work, the Shareware
  330. version is a complete and fully functioning version, with only one res-
  331. triction: the actual BASIC source code and libraries are missing. You can
  332. test MakeForm, save all your work, test run your interface within MakeForm
  333. itself, and you can also look at the DEMO program source code that Make-
  334. Form creates for you, in order to evaluate how practical it looks to you.
  335. However, due to the missing source code of the other modules, you will not
  336. be able to actually run your application or complete coding it. Also, to
  337. conserve disk space, the Shareware version has a smaller manual, with much
  338. of the detailed information and examples to help you complete your ap-
  339. plication in record time removed.
  340. When you register, you will of course receive the complete source code of
  341. all the modules, the source code of MakeForm itself so you can customise
  342. it if you like, or just see how things were done, plus a registered copy
  343. of Merlin's Deluxe Font Editor so you can design your own custom fonts to
  344. use for text input and display.
  345.  
  346. Registering is well worth it: sell two or three programs created with
  347. MakeForm and your investment has paid for itself - not to mention you'll
  348. have a lot more fun programming!
  349.  
  350.  
  351.  
  352. Technicalities & legalese
  353.  
  354. MakeForm requires a VGA screen and a mouse, as will all programs created
  355. by it. Memory requirements are small: 128k will do. A fast VGA card helps
  356. all graphical programs, and Makeform is no exception, and so does a 386
  357. CPU, but the code runs on a 8086 as well.
  358.  
  359. MakeForm is provided 'as is', without any warranties of any kind. Neither
  360. does Merlin's Software accept any responsibility for any damages resulting
  361. from the use of this program. However, help is of course available - we
  362. like to support you!
  363.  
  364. The shareware version, without source code or libraries (i.e. without any
  365. files with the extension BAS, LIB or QLB) can be distributed freely.
  366. Programs you write with your registered version of MakeForm can be dis-
  367. tributed without royalties, on the explicit condition that you give credit
  368. to Merlin's Application Framework, in the program itself or the documen-
  369. tation that comes with it.
  370.  
  371.  
  372. Credits
  373.  
  374. I am very much indebted to Crescent Software's Graphics QuickScreen
  375. program in creating MakeForm. Graphics QuickScreen is a fully fledged
  376. drawing program that incorporates the same functionality as MakeForm, and
  377. will also generate DEMO source code. If you're interested in their line of
  378. products, contact them at 32 Seventy Acres, West Redding, CT 06896, USA. 
  379.  
  380. I did a complete and extensive rewrite of the software provided to accom-
  381. modate my own wishes. One of the main improvements is being able to edit
  382. text graphically, with a proportional font of your own choice and crea-
  383. tion, instead of using BASIC's PRINT statement. Other improvements include
  384. reduced code size (yep, in spite of all the improvements!), extensive
  385. mouse support, block marking, search, paste, copy and delete function-
  386. ality, paragraph indentation and word wrap, toggle-state buttons, keyboard
  387. control of scroll bars, hotkey support, mouse cursor bitmaps, list box
  388. item marking and greying, etcetera. So although the functionality is
  389. similar, MakeForm is 100% my own work and in key areas it is a great
  390. improvement!
  391.  
  392. Other programs that need mentioning are of course Microsoft's QuickBASIC,
  393. various drawing programs and conversion and special effects utilities,
  394. Merlin's Deluxe font Editor and Merlin's Library. Merlin's Application
  395. Framework was designed on an Icon 386/40 with an analogue multisync non-
  396. interlaced monitor and a Tseng ET/4000 based SVGA graphics card.
  397.  
  398.  
  399. Quick Start
  400.  
  401. There are just a few steps to creating a program with MakeForm.
  402.  
  403. 1.   Make a .PCX full screen drawing that will be the user front-end. This
  404.      contains the buttons, scroll bars, text entry areas, etcetera. More
  405.      than one screen can be used, small screens can be designed to handle
  406.      sub-tasks, act as pop-up windows or custom button bars, etc. Apart
  407.      from the areas for buttons and text input, the screen can be as fancy
  408.      as you like.
  409.  
  410. 2.   Run MakeForm to define all the fields, and let MakeForm create a
  411.      ...DEMO.BAS program for you. If you haven't made a drawing yet, and
  412.      want to try this program immediately, then load MF_TUTOR to test out
  413.      MakeForm (see below).
  414.  
  415. 3.   Start up QuickBASIC. You can run the program as it is, and finish the
  416.      coding to handle your own specific needs. 
  417.  
  418.  
  419.  
  420. If you hate reading manuals (like I do) and want to get a feel for the
  421. program right away, here are some tips:
  422.  
  423. 1.   Start MakeForm from the DOS prompt, and read the help file that pops
  424.      up. Press Escape to leave that help file, and press Enter to load
  425.      MF_TUTOR.
  426.  
  427. 2.   Press F5 to Run the form. You can now test a complete example; press
  428.      buttons, move scroll bars, enter text, press the Alt-key to check out
  429.      the complete menu, etcetera. Press Escape to get out when you get
  430.      stuck somewhere. Do not alter any data yet. MakeForm can write a
  431.      QuickBASIC source code file for you, that does exactly what you see
  432.      here and will be the framework for your application!
  433.  
  434. 3.   Press Escape until you are in the Exit warning box, then Enter, to
  435.      exit MakeForm again.
  436.  
  437.  
  438. PCX files
  439.  
  440. To create a program interface, first you have to make a PCX full screen
  441. drawing that will be presented to the user. You can make such a drawing
  442. with any drawing program you like, and save it as a PCX file. Use a
  443. graphical conversion program if your drawing program does not support PCX
  444. (unlikely).
  445.  
  446. Further sub-sections of your intended program might use smaller PCX
  447. screens that pop up over your main screen at any pixel location you like.
  448.  
  449. In order to convert PCX files successfully, there are a few rules you
  450. should be aware of. Typically the drawing will contain areas for text
  451. input and display, push buttons, scroll bars and mouse regions, and areas
  452. for list boxes or pop-up list boxes and menus. MakeForm supports the
  453. proportional fonts you design with Merlin's Deluxe Font Editor. This
  454. utility is part of this package, and is a good example of what you can
  455. achieve as well. In order to draw your own main screen, first decide on
  456. the font you will use later for text input, and note down its height in
  457. pixels. BASIC's PRINT statement uses a height of 16 pixels on a normal VGA
  458. screen, so this is a fairly common size, and will allow about 30 lines of
  459. text on screen. If you choose a smaller font, you can get more lines on
  460. screen. The width is typically more than 80 characters, because in propor-
  461. tional fonts many letters are narrower than the standard 8 pixels.
  462. With Merlin's Deluxe Font Editor you can design fonts up to 16 by 32
  463. pixels, which is four times the size of the standard characters.
  464.  
  465.  
  466.     Merlin's Application Framework does not use BASIC's PRINT statement at
  467.      all, but instead relies on its own VGAPrint routine to put text on
  468.      screen using proportional screen fonts from 6 to 32 pixels in height.
  469.      These fonts you can design with Merlin's Deluxe Font Editor, which is
  470.      part of this package.
  471.  
  472.  
  473. Although there is little point in going into the specifics about drawing
  474. and drawing programs here, a few assorted notes may be of help.
  475.  
  476.  
  477. VGA mode: 640 * 480, 16 colours
  478. MakeForm assumes that all PCX drawings are made for 640*480 VGA 16 colour
  479. mode. Any VGA card supports this format. Drawings do NOT have to be full-
  480. screen: you can make smaller drawings that you intend to use as 'pop-up'
  481. forms. MakeForm itself uses a smaller drawing to load as the data entry
  482. screen background. Any drawing can be positioned at any pixel location on
  483. screen.
  484.  
  485. Palette
  486. Even though only 16 colours are available, your drawing program will let
  487. you adjust any of those 16 colours. Don't like brown? Make it orange! A
  488. custom palette like this gives you far more 'atmosphere' than the default
  489. colour setting can. MakeForm will of course set that palette for you - the
  490. palette information is part of the PCX file that you create. If you
  491. instruct MakeForm to set the palette, you can choose a 'colour fade speed'
  492. to fade out the current colours and fade in the new palette.
  493. If you don't want to set the palette (for example when loading a smaller
  494. PCX file on top of another screen), you can do that too. However... if you
  495. intend to run your program under Windows (other than in a full screen DOS
  496. box), be aware of the fact that Windows will NOT allow you to tamper with
  497. the palette. It would change the colours of everything else on screen too!
  498. So if you are designing for Windows, stick to the default palette and use
  499. colour dithering, however ugly!
  500. Apart from the standard 16 colours, most drawing programs will also let
  501. you use hundreds of dithered 'mixed' colours.
  502.  
  503. Drawing details
  504. Most fields require only a rectangle in your drawing. Text areas need a
  505. rectangle of at least the height of the font you intend to use. Mouse
  506. areas need a rectangle to define their size, as do menus, list boxes, and
  507. pop-up list boxes. Push buttons and scroll bars are somewhat more spe-
  508. cific. Rather than split the information for all the different field types
  509. over a drawing section, a code section etc., you will find everything that
  510. has to do with scroll bars for example in the scroll bar section. Often
  511. information that has to do with the drawing is related to the code section
  512. anyway.
  513.  
  514. Snap to Grid
  515. To create text areas, menus and list boxes, you are advised to use the
  516. 'Snap to Grid' function that many drawing programs provide, and to set the
  517. height of the grid equal the height of the font you want to use later. You
  518. can use any width, although the 'Snap to Grid' function will make using a
  519. standard alignment very easy.
  520.  
  521.  
  522.  
  523.     If you draw a rectangle with the 'Snap to Grid' function, you're
  524.      advised to check the exact workings of that function in your drawing
  525.      program. Draw a small rectangle on screen, use the Zoom function and
  526.      count pixels. A 12-point font needs a height of 12 pixels. A possible
  527.      3-D outline around the text area should not overlap this space. The
  528.      width can be any value.
  529.  
  530.  
  531. MakeForm Overview
  532.  
  533. This section explains in detail how to use the program MakeForm. MakeForm
  534. converts your PCX drawing into a complete working program, where scroll
  535. bars move, buttons can be depressed, text can be entered, etc. A Quick-
  536. BASIC source code file will be created for you that performs exactly like
  537. the 'test run' you can perform in MakeForm itself. This file you can load
  538. into the QB environment, and complete at your leisure to finish your
  539. application. All code to handle proportional fonts, word wrap, masked text
  540. input, pressing buttons, moving scroll bars, popping up menus etc. is
  541. already present and will be handled transparently for you. All you need to
  542. do is complete the SELECT CASE sections in the MAIN module of the source
  543. code file that MakeForm creates for you, so that when the user presses the
  544. 'Exit' button, the program actually exits back to DOS.
  545.  
  546. MakeForm has four distinct stages of functionality:
  547.  
  548. 1.   Design stage
  549.      Define field positions and size with the mouse.
  550.          Press F1 for general help.
  551.  
  552. 2.   Data Entry Screen
  553.      Press Enter to define this field's data, help texts, colours etc.
  554.          Press F1 for help with any field you need to fill in.
  555.          Press the "Close" button to exit this stage.
  556.  
  557. 3.   Test run
  558.      Press F5 to "test run" your form.
  559.          Press Escape to exit this stage.
  560.  
  561. 4.   Save
  562.      Press F10 to save your work to disk. A DEMO.BAS program will be
  563.      created for you. This DEMO will behave exactly as the test run you can
  564.      perform in MakeForm. It contains lots of comments that allow you to
  565.      complete your program as easily as possible. Save your work often.
  566.      There are NO WARNINGS when you quit without saving!
  567.  
  568. Please note that MakeForm has no 'interface' of its own, like a menu bar
  569. or a status bar. The design stage and the test run stage look quite
  570. similar. In the design stage fields are highlighted with a square of the
  571. size of the field. During the test run you will have a blinking cursor in
  572. the text fields and can enter text etc. If you're not sure what is hap-
  573. pening, press Escape a few times. This will eventually get you to the
  574. final program exit warning. Press Escape again, to stay in MakeForm, and
  575. you are back in the design stage.
  576.  
  577. Starting MakeForm
  578.  
  579. You start MakeForm by typing MAKEFORM at the command prompt, and pressing
  580. Enter. MakeForm uses a number of program files, like its own PCX screen,
  581. and needs to be able to find those. So either start MakeForm from its own
  582. directory, or make sure the directory is listed in the PATH statement in
  583. your AutoExec.Bat file. There are no command line options.
  584.  
  585. If MakeForm cannot start, because you don't have a VGA screen, there is no
  586. mouse, or it can't find its data files, you will be warned and the program
  587. exits back to DOS.
  588.  
  589. MakeForm first presents you with a small help file. This file is just
  590. another memo-field: you can read it, browse, edit, blockmark, mess it up,
  591. etc. All changes in this help file are written back to disk, so you can
  592. jot down your own notes and hints to remember!
  593. You can call up this help file, and edit it, at any time during the design
  594. stage, by pressing F1.
  595.  
  596.  
  597.     Creating such a help file edit box in your own program couldn't be
  598.      simpler: VGALineInput x0, y0, x1, y1, Edit$ is all it takes! You pass
  599.      four pixel corners (the size defines single-line or memo field) and a
  600.      string or file contents to edit, and away you go!
  601.  
  602.  
  603. Press Escape to exit the help file and continue with the program. 
  604.  
  605. Next, you are presented with a small entry box to enter the name of the
  606. PCX drawing you've made and want to work on. You do not need to type in
  607. the PCX extension. If you do, earlier definitions for this form will NOT
  608. be loaded. 
  609. Press Escape to abort the program now, or Enter to continue loading your
  610. drawing.
  611. For a quick test run, load MF_TUTOR, which is a screen that contains
  612. examples of most field types.
  613.  
  614.  
  615.     Please remember: what you see MakeForm do, you can do too! You have
  616.      all the code you need for that! The entry-box just mentioned above for
  617.      example is called like this (patterned along LINE INPUT):
  618.      VGAQuery Prompt$, Edit$. 
  619.      Nothing could be simpler now, could it?
  620.  
  621.  
  622. Design Stage
  623.  
  624. The drawing will be loaded next. Please note that PCX files and VGA
  625. 640*480 16-colour mode are assumed! PCX files do not need to cover the
  626. complete screen: small drawings which you intend to use as sub-screens can
  627. be loaded too. MakeForm's Data Entry Screen is such an example.
  628.  
  629. The First Field
  630. If you haven't defined any fields yet during a previous session, press
  631. Insert to Insert a new (first) field. Otherwise you can continue where you
  632. left off. 
  633.  
  634. Select A Field
  635. You can click once to select any field. You can also use the cursor keys
  636. or the tab and shift-tab keys to go from field to field, and you can use
  637. the hotkeys that you have defined for each field to select a field as
  638. well. Fields are highlighted by a dark square, indicating the field size
  639. and position. All fields are accessible at this point, even 'protected'
  640. fields that the user won't be able to access later, and pop-up list box
  641. fields or menu bars that normally can't be accessed by clicking on the
  642. screen area.
  643.  
  644. Field Size
  645. If you double-click on the current field, the mouse will turn into a full
  646. size crosshair. You can now define the field's position and size. Position
  647. the crosshairs at the top left corner, click and release, and do the same
  648. for the bottom right corner. 
  649. If you need to start again, because the top-left corner is marked wrongly,
  650. press the right hand mouse button.
  651. If you don't want to re-position the field, press Escape.
  652. During this stage, you can press 'S' to toggle 'Snap to Grid'. When it
  653. gets toggled on, you have a chance to enter the grid size. Press Escape to
  654. ignore this if you like. Standard Snap uses a grid size of 8 * 16 pixels
  655. which is the default VGA BASIC PRINT character size.
  656. You can move the mouse cursor with the cursor keys as well, for exact
  657. pixel alignment, and press Enter to simulate a mouse click. I find this
  658. much easier than the mouse, or even my own drawing tablet, so I designed
  659. this to work with drawing tablets in absolute mode as well!
  660.  
  661.  
  662.     Keep working at the field positions, order and size until you are
  663.      satisfied. It is easy to insert and delete fields now, before you have
  664.      entered a lot of other field data. 
  665.  
  666.  
  667.  
  668. Insert / Delete
  669. You can insert and delete fields. Insert will add a field AFTER the
  670. current field. Delete will ask for confirmation. With these two keys, you
  671. can rearrange fields. However, it is better to start in the right order to
  672. begin with. The Delete function is actually only meant to update a form
  673. that you've already made, when you decide later on that some fields were
  674. not necessary after all.
  675.  
  676. Tab order
  677. Please note that you should define the fields in some sort of logical
  678. order. The order you use now is the order the user gets when he uses the
  679. 'Tab' key to go to the next field! Use the Tab key yourself to verify the
  680. order. The same order is used when the user presses Enter in a text field,
  681. to go to the next field. It is good practice not to put buttons or mouse
  682. fields in between the text field tab-order, so the user can fill in all
  683. text fields without losing the cursor in a mouse field, list box or button
  684. in between! This implies as well that it is easier on the user if all text
  685. fields are grouped together on screen.
  686.  
  687. Think ahead - make your day!
  688. If you want to make coding easy on yourself later, group related fields
  689. together! Make sure all menu bars and drop down menu list boxes are the
  690. first fields, so just one comparison will suffice to exclude all those.
  691. Group buttons together for the same reason. If your form design reflects
  692. such organisation, your users will find it that much easier and more
  693. intuitive to work with, and you'll find that coding your application
  694. becomes a breeze!
  695.  
  696.  
  697.     If you want to start all over again from scratch, enter the form name
  698.      WITH the PCX extension to prevent loading earlier field definitions
  699.      upon startup.
  700.  
  701.  
  702. Help
  703. Pressing F1 will call up the same help file you've seen at the start of
  704. MakeForm. You can edit this file and insert your own hints and tips -
  705. things which you think you may forget in a month or so! The help file will
  706. be saved to disk automatically. Do NOT enter help for this specific form
  707. or for the intended user - you can do that in the Data Entry Screen!
  708.  
  709.  
  710. Data Entry Screen
  711.  
  712. When a field is highlighted with a rectangle, you can press Enter to go to
  713. the data entry screen for that field. This screen is just another MakeForm
  714. example, and is drawn as a small PCX screen, that is loaded in the centre
  715. of the screen. Here you can fill in all the data for each field. It may
  716. look intimidating at first, but you will usually only fill in four or five
  717. of the entries provided. The rest is handled automatically for you, or is
  718. irrelevant for the field type you are defining. Full details you will find
  719. in the reference section. Concise help is available under F1.
  720.  
  721. Field Name
  722. The field name you provide is used in creating the DEMO program: in a TYPE
  723. array, and also in a list of CONST declarations, so that you can code
  724. SELECT CASE statements easily. Rather than trying to remember that this
  725. list box is field number 17, you code CASE cFileList: ....
  726. All field names will be prepended with a lower-case "c", which means that
  727. you can use most QuickBASIC reserved words like NAME, OPEN etc. for these
  728. field names! Field names can be 8 characters long.
  729.  
  730.  
  731.     Using a name like 'INT' would create the CONST cINT, and because CINT
  732.      is a reserved BASIC word, QB will point out that you can't use that
  733.      when your own DEMO program gets loaded. You can change such errors in
  734.      the BI file itself when QB points them out to you - MakeForm will copy
  735.      your changes the next time it runs with the same form!
  736.  
  737.  
  738. Field Type & default values
  739. Enter the field type. You can select a number from the list on screen. For
  740. more information on the field types, please check out the relevant section
  741. further on in this manual. For now, select the field type that you think
  742. is correct - you can always change it later! 
  743. If you set or change the field number, a series of default values will be
  744. loaded in the next fields. So it is quite easy to just set the field
  745. number and press the "Close" button and go on to define the next field.
  746. During the test run you can quickly determine what still needs to be
  747. changed (usually colour schemes).
  748.  
  749.  
  750.     If you're not sure what a field type does, you can always just set it,
  751.      press F10 to save your form, press F5 to run it, and try it out! If
  752.      the screen gets messed up, don't worry: MakeForm will load your PCX
  753.      file from disk again when you exit the test run with Escape.
  754.  
  755.  
  756.     Not all field numbers are in use, and beyond 23 you can define your
  757.      own custom field numbers. Field type numbers that MakeForm doesn't
  758.      know about work like mouse fields (until you code them differently of
  759.      course!)
  760.  
  761.  
  762.     There is one quirk in MakeForm: if you have a block marked in a text
  763.      field, the key combination Alt-C is used to 'Copy' that block of text.
  764.      So using Alt-C to try and press the 'Close' button will not work. Use
  765.      the cursor keys to switch the block off, and then press Alt-C, or use
  766.      the mouse to press the Close button.
  767.  
  768.  
  769.     Advanced note: You could load MakeForm itself into MakeForm (Yes!
  770.      Possible!), and re-set flags bit 128 (block is on upon entry) for all
  771.      text fields to correct this 'problem'. Or you could define another
  772.      hotkey for the 'Close' button, such as F7 or Alt-Q. But: please make
  773.      sure you have the original MakeForm.MFM file safe somewhere, just in
  774.      case!!
  775.  
  776.  
  777. Help
  778. Within each field you can press F1 to get help with what to enter. Each
  779. help text will explain what to enter for all field types that use that
  780. field. If the field type you are defining is a push button, look to the
  781. help text to find out what a push button needs in this field. If the push
  782. button is not mentioned, then skip that entry. If the entry has a meaning-
  783. less value in it, then this is probably a return value from an earlier
  784. test run you have performed on this form. You can safely ignore this, or
  785. re-set it to zero if you like.
  786. You'll quickly remember it anyway, its fairly easy throughout!
  787.  
  788.  
  789. Entering Colours
  790. All fields need 4 colours. A text field for example uses normal text
  791. foreground and background colours, as well as block foreground and back-
  792. ground colours. Even though it may feel unfamiliar at first, it is quite
  793. easy to enter four colours in hexadecimal format, like &H5D2E. The leading
  794. "&H" specify hexadecimal notation. After that follow 4 characters, which
  795. can be from 0 to 9, and from A to F. Just pick a colour from the colour
  796. map on your right, and enter the character in the correct position. 
  797. To set text field colours, press F1 to get a list of colour meanings. For
  798. text fields, the four colours from left to right are: block background,
  799. text background, block foreground, text foreground. To set the text
  800. colours to bright white on blue, you would enter 1 for blue and F for
  801. bright white in these positions: &H.1.F 
  802. Adding black on bright red, which are 0 and C, for the block colours,
  803. would result in the complete colour setting like this: &HC10F. 
  804. If you press F1, you'll get a list of all colour meanings for each field
  805. type. 
  806. MakeForm will take an intelligent guess at the colours, and will copy the
  807. colours you enter and use those for the next fields of the same type you
  808. define.
  809.  
  810.  
  811. Setting Hotkeys
  812. You may wonder how to enter the hotkey value for Alt-H as a hexadecimal
  813. value in the hotkey entry field. Well, don't worry! Pressing F1 for help
  814. when trying to figure out how to enter a Hotkey value in the data entry
  815. form will present you with the option to press the actual hotkey com-
  816. bination you would like to use! If you're defining a 'Help' button for
  817. example, and would like to use Alt-H for that, you press Alt-H now.
  818. MakeForm will enter the correct code for you in the hotkey entry field.
  819. Press Escape to keep the current hotkey setting. 
  820.  
  821.  
  822.     All keys work! So inadvertently pressing cursor down when trying to
  823.      enter a hotkey, will enter that key value! You could take advantage of
  824.      this to find out other key values.
  825.  
  826.  
  827.     MakeForm has many more key combinations available than are customary
  828.      in QuickBASIC. Ctrl-cursor-up/down, F11, F12, many Alt-cursor com-
  829.      binations, etc. Under Alt-Insert for example is a small debug-window,
  830.      that will show you the current memory use. I'll leave that in - you
  831.      may find it useful during your own program development! Just don't use
  832.      it when you're in the big help file.
  833.  
  834.  
  835.     To find a complete list of key values, including the additions that
  836.      MakeForm can generate for you, refer to the library documentation at
  837.      the end of this manual (GetKey section).
  838.  
  839.  
  840. Help texts
  841. The 'Help text' field, where you would enter the text that the user sees
  842. when he presses F1, has wordwrap turned off. This gives you full control
  843. over the width and layout of your help text. Displaying help texts with F1
  844. is built into the code - you don't have to worry about it at all.
  845. If you do not enter any text, the final program will display "No help for
  846. this field". You can change that text too, of course, in the EditForm
  847. subroutine of the code.
  848.  
  849.  
  850.     Remember that the help texts are in memory at all times, and take up
  851.      QuickBASIC string memory. So short texts are advisable. 
  852.  
  853.  
  854.     Advanced note: If you use a lot of help text, you can write your own
  855.      custom code to lift the help texts from disk when asked for. The delay
  856.      is not worth bothering about, and it saves memory.
  857.  
  858.  
  859. List Box Lists
  860. List boxes use the help text field for the list of items. Items are listed
  861. below each other, one line per item, and they all start with a one-charac-
  862. ter hotkey. Some special characters are used here as well. A full descrip-
  863. tion is available by pressing F1 when you are in the Help field. Please
  864. note that commas are NOT allowed in list box item texts - they have a
  865. special meaning! More information can also be found in the list box
  866. section of this manual.
  867.  
  868. Close
  869. When you are done, press the 'Close' button to save your entries. Use
  870. Escape to discard your changes or exit quickly if no changes were made.
  871. Make it a habit to press F10 to save your work often!
  872.  
  873.  
  874.  
  875. Warning
  876. NEVER use any of the data fields (that seem to be unused) to enter your
  877. own custom flags or data! All fields are always in use, even if you don't
  878. need to enter data yourself when defining that field!
  879. If apparently unused data fields have numbers in them that you have not
  880. entered, you can ignore them or set them to 0 again - they are return
  881. values from an earlier test run you have performed (maybe in a previous
  882. session).
  883.  
  884.  
  885.  
  886. Test Run
  887.  
  888. When you are done with defining fields, you can press F5 to 'run' your
  889. form. This will allow you to test-drive all text entry, buttons, scroll
  890. bars, mouse regions etc. and see if they perform the way they should. You
  891. can press buttons, set scroll bars, press mouse fields, enter text in text
  892. fields, etcetera. 
  893. You can also test your help function here: whenever you press F1, the help
  894. text for that field should pop up.
  895.  
  896.  
  897.     Pop-up list boxes are accessed with the TAB key, and with the hotkey
  898.      you defined for them - clicking on the area where they are supposed to
  899.      pop up is not going to work! 
  900.  
  901.  
  902.     Protected fields, which the user cannot access, are inaccessible to
  903.      you too at this stage. Remove the protection flag (Flag field, bit 1)
  904.      if you don't want that.
  905.  
  906.  
  907. Use Escape to exit this stage. Upon exit, the whole form will be drawn on
  908. screen again from disk. If by mis-aligning fields the screen was messed
  909. up, pressing F5 and then Escape will restore the original drawing.
  910.  
  911. If a field you remember defining seems to be 'missing', i.e. you can tab
  912. to it but it won't show anything, then chances are that the coordinates
  913. are wrong. Exit the test run, tab to the 'missing' field, press enter, and
  914. enter valid corner pixel coordinates.
  915.  
  916.  
  917.  
  918. Save Your Work
  919.  
  920. To save your work (you are advised to save your work often, because any
  921. serious software can crash if you try hard enough!) press F10. This will
  922. write all stuff to disk. MakeForm will create four files for you (and
  923. overwrite the old versions!):
  924.  
  925. FormName.MFM        The form you have made, with all field definitions and help
  926.                     texts. This will be loaded the next time you continue with
  927.                     this form. To avoid loading it and start from scratch
  928.                     again, enter the form name WITH the PCX extension.
  929.  
  930. FormName.BI         An include file with the field names, TYPE'd array and list
  931.                     of CONSTants. Changes you make to this file (to get QB to
  932.                     load it properly if you've chosen a reserved word for
  933.                     example) will be copied back by MakeForm again. MakeForm
  934.                     uses this file to copy the field names only - all other
  935.                     definitions like integer field, string field etc. are in
  936.                     the FormName.MFM file.
  937.  
  938. FormDEMO.BAS        Using the first four letters of the PCX file name, and the
  939.                     DEMO.BAS extension, a QuickBASIC program is made that will
  940.                     allow you to test drive the form (similar to pressing F5 in
  941.                     MakeForm). You can copy this file and start coding to com-
  942.                     plete your program.
  943.  
  944. FormDEMO.MAK        The MAK file that is necessary for a complete program.
  945.  
  946.  
  947. In order to run the DEMO program, i.e. your own program, start QB as
  948. follows:
  949.  
  950. QB /L MakeForm.QLB FormDEMO.BAS
  951.  
  952. where FormDEMO.BAS is of course the demo file that MakeForm created for
  953. your form. If you loaded a PCX file from a different subdirectory, you
  954. will have to change directory so QB can find the various include files.
  955.  
  956. Press F5 in QB to run the program.
  957.  
  958.  
  959.                    Please remember that MakeForm will overwrite FormDEMO.BAS
  960.                     the next time! So once you start coding, rename your MAIN
  961.                     module to something else! Also use copies of the other
  962.                     modules, so you can safely make changes without affecting
  963.                     other programs.
  964.  
  965.  
  966. Exit MakeForm
  967.  
  968. To exit MakeForm, press Escape. You will have a last chance to save your
  969. work by pressing F10, or you can press Enter to ignore that or lose the
  970. changes you've made since you last pressed F10.
  971.  
  972.  
  973.     Please note that MakeForm gives NO WARNING if you're about to lose
  974.      changes, neither in the data entry screen, nor at the end of the
  975.      program. So make it a habit to press F10 to save your work!
  976.  
  977.  
  978.     If you have the shareware or evaluation copy of MakeForm, the .QLB
  979.      library and other modules are not present in your copy. You can load
  980.      your DEMO.BAS file into QuickBASIC and read through it, to evaluate
  981.      how easy it would be to complete your program, but it won't run. To
  982.      see your form in a test run, you will have to press F5 from within
  983.      MakeForm. Registering is easy and well worth it!
  984.  
  985.  
  986. Completing the Program
  987.  
  988. Completing your program can be very easy or extremely difficult, depending
  989. on what you are trying to do. Further on in the manual there is a tutorial
  990. with a First Project to complete, with lots of hints and tips, that will
  991. get you started as painlessly as possible. 
  992.  
  993. However, to get the general feel of things, you could load the DEMO.BAS
  994. program that MakeForm creates for you into QuickBASIC, open the MAIN
  995. window and read through this chapter with the code in front of you.
  996.  
  997. The DEMO.BAS program that MakeForm creates for you contains a MAIN module,
  998. with your custom code in it. It also needs a number of modules, which are
  999. listed in the MAK file so that QuickBASIC will load them automatically for
  1000. you. These modules handle all text entry, push buttons, scroll bars, list
  1001. boxes, hotkey handling etc. for you. Don't look through those just yet...
  1002.  
  1003. You will have to start QB as follows:
  1004. QB /L MAKEFORM.QLB  ....DEMO.BAS
  1005.  
  1006. If you have not designed a screen of your own, load MF_TDEMO.BAS. If that
  1007. file is not present, let MakeForm create it for you by loading MF_TUTOR
  1008. and pressing F10 in MakeForm.
  1009.  
  1010. If you have the Shareware version, you can load the DEMO source code into
  1011. QB and study it, but you can't run your form from within QB. You CAN run
  1012. your form within MakeForm by pressing F5, to test everything.
  1013.  
  1014.  
  1015.     The MAIN program module looks like this (simplified):
  1016.  
  1017.      DECLARE's
  1018.  
  1019.      Housekeeping
  1020.  
  1021.      DO:       GetEvent
  1022.                EditForm
  1023.                SELECT CASE .... (three blocks)
  1024.      LOOP UNTIL ...
  1025.  
  1026.      Cleanup
  1027.  
  1028.  
  1029. Within you main program module, you will find one main LOOP, which is your
  1030. form editing loop. Within it are three SELECT CASE statements. Some of
  1031. these you will need to complete yourself. There are plenty of comments to
  1032. show you what to do, when and why. 
  1033.  
  1034. The three SELECT CASE sections handle the following events:
  1035. 1.   Completed a press on a button, mouse field, or made a choice in a list
  1036.      box: you may want to act on this. The user will be surprised if a
  1037.      button doesn't do anything...
  1038. 2.   Still in the same field: you may want to check on something
  1039. 3.   Going to a new field: you may want to update other fields
  1040.  
  1041. A few examples
  1042. If you have drawn and defined an "EXIT" button for example, then you would
  1043. code within the main SELECT CASE statement a CASE cEXIT. Here you would
  1044. code "QuitProgram = true". Now, when you press the EXIT button, the loop
  1045. will be exited and the program will tidy up itself and return you to DOS
  1046. or the QB environment.
  1047. If you have drawn and defined a "SAVE" button or option somewhere, you
  1048. would code within the main SELECT CASE statement a CASE cSAVE. Here you
  1049. would code "CALL SubSave .....", and create a SUB to handle saving what-
  1050. ever you would like to save. Both would be coded in section 1. above.
  1051.  
  1052. If you have a scroll bar that supposedly scrolls the text in a memo field,
  1053. then under heading 2. above you would check if the scroll bar was moved,
  1054. and update the memo field accordingly.
  1055.  
  1056. If you have a monetary field, and a tax field, then you may want to update
  1057. the tax field by calculating tax from the monetary field, as soon as the
  1058. user leaves that field and is done filling in the amount. This would come
  1059. under section 3. above.
  1060.  
  1061. It looks dead easy, and so it is ... provided your wishes are not too
  1062. complicated. But make no mistake: MakeForm is very sophisticated, and you
  1063. should expect a reasonable amount of time to become familiar with its
  1064. workings. Spend time studying how calls are made, and what they do,
  1065. elsewhere in the program, if you want to use any of its abilities your-
  1066. self. BUT: you do not NEED to get into the code that is provided. It works
  1067. fine, as MakeForm demonstrates, so if you can, limit yourself to coding
  1068. your MAIN module and the SELECT CASE statements in it to finish your
  1069. program!
  1070.  
  1071. The End ....
  1072. This is the end of the Shareware MakeForm.Doc file. When you register you
  1073. will receive the complete printed manual, almost 100 pages of hints, tips,
  1074. documentation, and examples, together with all source code, the library
  1075. and everything else you need to create stunning graphical programs in
  1076. record time! Please refer to the file REGISTER.DOC!