Monster Media 1994 #1

home *** CD-ROM | disk | FTP | other *** search

/ Monster Media 1994 #1 / monster.zip / monster / PROG_GEN / TVGRAPH.ZIP / TVGRAFIC.DOC < prev next >

Wrap

Text File | 1994-01-04 | 82KB | 1,831 lines

Documenting TVGraphic Ver 1.5, January 4, 1994 TVGraphic is a port of Borland's text based Turbo Vision to DOS graphics mode with extensions, enhancements and a pleasing graph- ic look. It runs using the Borland EGA/VGA graphics driver in color or black and white. It requires Turbo Vision TPU's plus the Graph unit to compile programs. Core functionality is nearly identical to Turbo Vision but the BGI coordinate system is used. Minor source changes are required to port existing TV applica- tions that use standard views. Version 1.5 is shareware - see license and registration info on pages five and six. TVGraphic consists of TPU's that replace the correspondingly named TPU's of Turbo Vision, a TPU supplementing the BGI Graph unit, a Mouse Cursor TPU, two Bitmap TPU's and a Window TPU. TPU's for both Turbo Pascal 6 and 7 are available. Most units are overlayable. TVGraphic is currently based on Turbo Vision 1.0 with bug fixes and many features from Turbo Vision 2.0. It is in a developmental phase. Comments are actively sought. It is being incrementally upgraded to Turbo Vision 2.0 level. Bitmaps and an intrinsic blinking text cursor plus the ability to work with a visual design tool for Dialogs are new in ver 1.5. See files BITMAP.DOC and TOOLS.DOC. Future directions may include Protected mode version for BP 7.0, VESA 800x600 support, C++ version, macro recorder/playback. Major Extensions beyond Turbo Vision include 1. intrinsic support for larger than screen interiors (drawing surfaces) in all TGroup descendants (such as a window). These interiors can have TView/TGroup/TWindow descendants inserted in them. Nesting of new TSubWindow view is allowed. Non-modal Dia- logs can be inserted into a window. 2. automatic sizing and handling of the graphic viewport and the Clip variable during partial screen redraws. Functions pro- vided both to return coords needed to set the viewport as well as to return viewport relative screen coords needed for BGI graphic calls. 3. Fonts !FAST! 8x8 and 14x8 bit mapped text fonts that clip at pixel boundaries. also added TView field to store two fonts. 4. Color functions provided to parse colors from palette into form needed for BGI graphic calls. Function provided to alter a single pal- ette color. TView field added to store two color pairs to elimi- nate need for palette if desired. New colors in the primary Application color palette. 1 5. Mouse Cursor grid graphic mouse cursor can be optionally locked (snapped) to user specified grid to match drawing grid or text size. 6. Safer disk loads intrinsic support in TGroup.Load and TCollection.Load for low memory checking as each subview is loaded. 7. Hooks for programmers TView has an added general purpose virtual method and fields. These allow TVGraphic users to extend the library functionality a bit without re-deriving all the classes. Several Turbo Vision methods in TView and descendants have been made virtual to allow more programing flexibility. 8. TimerTick event class added. 9. Bitmaps - bitmapped buttons, toolbar and a bitmap view. Works with type .BMP bitmap files which may be loaded from disk or linked into your unit/program. Limitations of TVGraphic: 1. only runs on hardware supporting EGA or standard 16 color VGA mode. (Will run on super VGA in standard VGA mode. Has palette for black and white monitors.) 2. bit mapped fonts print only horizontally in single size. Significant Portions of Turbo Vision not emulated in this version 1. History unit 2. Editors unit - development in process 3. TV2.0 MultiCheckBox 4. TV2.0 Validators 5. TV2.0 Extended Dialog Palette 6. TV2.0 Outline unit TextView unit:a file of mods to the TV source code is supplied. 2 CONTENTS page 0. Contact Information, License and Support Policy........4 1. Compatibility with Turbo Vision Objects................7 A. Stream Registration numbers 2. General Discussion of TVGraphic........................7 1. Coordinate system...................................7 2. TGroup Interiors {larger than screen}...............8 3. Coordinate Transformation...........................9 4. Drawing in TVGraphic...............................10 General Color ViewPort Mouse Cursor and drawing Outline of a .Draw routine MyGraph3 and Graph - referencing, conflicts with TV Text, fonts A Limitation of TVGraphic's redraw Mechanism 5. Mouse Cursor.......................................16 1. Grids and Sizing Views to work with them 6. Sizing the DeskTop,Menu,StatusLine.................18 3. Environment and Object Behavior vs Turbo Vision.......18 4. Converting from Turbo Vision..........................21 5. Customizing TVGraphic's Appearance....................22 6. Hooks for TVGraphic users.............................24 7. Intrinsic LowMemory checking during TGroup, TCollection.Load....................24 8. GWindows unit.........................................26 9. TimerTick events......................................27 10. Blinking text cursor..................................28 11. Button choices........................................28 12. Compiling with TVGraphic..............................29 List of Units, Paths, Caution on USES statements,Errors Bitmaps - see file BITMAP.DOC Design tool info - see file TOOLS.DOC Tutorial on fundamentals - see file BEGINNER.DOC See file README.DOC for latest info The DEMO program is an important part of the documentation. Object by Object REFERENCE Section - see file REFER.DOC ------------------------------------------------------- 3 CONTACT INFO and SUPPORT POLICY Author Richard P Andresen RR2 Box 900 Hinesburg, Vermont 05461 U.S.A. CompuServe User# 71222,1200 (via Internet: 71222.1200@compuserve.com) Support Version 1.5 is a second release and should be considered very usable but in a developmental phase. Feedback, good and bad, is appreciated. Please send feedback, bugs and questions by Compu- Serve E-mail or postal mail. You can Email from Internet to CompuServe. Users requiring ongoing support will be asked to register. Since TVGraphic is based on Turbo Vision, Turbo Vision documenta- tion is an integral part of working with TVGraphic. In addition, any problem/question that also appears in Turbo Vision should be addressed to Borland support on Borland's CompuServe Pascal forum. Note that Turbo Vision 2.0 documentation is noticeably better than version 1.0. An environment as complex as Turbo Vision or TVGraphic can be extended in ways the designers had in mind without too much trouble. But it is almost impossible to make changes that affect the entire unit or object hierarchy without the source code. As a compiled library, TVGraphic comes with built in hooks for users to make some level of modification possible. If enough people express an interest in certain features, then TVGraphic can incorporate them in a future release. If you want to try modifying the basic functionality of TVGraph- ic, refer to Turbo Vision source code (either rev) to gain in- sight into functionality shared with TVGraphic. Read the Envi- ronment and Object Behavior and the Reference section for TVGraphic. Leave me a message/questions on CompuServe AFTER you have studied things. Source code Source code rights rest jointly with the author and Borland International for TVGraphic modules whose names are analogous to Turbo Vision names and solely with the author for other modules and demo code/programs. If interested in licensing source code, contact the author for availability of source/Difference files. Turbo Vision is a trademark of Borland International. TVGraphic is a trademark of Richard P. Andresen. TVGraphic and its documentation are Copyright (C) 1993,1994 Richard P Andresen 4 License Agreement and Limited Warranty Copies of TVGraphic Ver 1.5 and its documentation may be freely distributed so long as no modifications are made and all files and this notice are included. Distribution with commer- cial programs is prohibited without specific permission. You may use this software for your personal use without charge. If you find it useful, please register to support the program. Distribution of programs created with TVGraphic: You or your organization may distribute programs that you create using the TVGraphic library only if you have extended this license by registering for commercial use. This applies whether or not a charge will be made for the program. It also applies to distribution within an organization. Distributed programs must bear a valid copyright notice. You are solely responsible to users of your programs for all support and warranty. You will indemnify and hold harm- less Richard P Andresen (the copyright holder) from all claims and liabilities arising from the use of your pro- grams. You may not distribute any portion of TVGraphic as part of a library of your own without specific permission and license, nor may you decompile or disassemble the software. Under this license, you may not use TVGraphic in programs involving human health or safety. (A sign of the times.) Limited Warranty The user acknowledges that this software is shareware where- in users have an opportunity to use the software and read this license and warranty before registering. Users shall determine suitability of this software for their purposes before regis- tering. Users acknowledge that portions of TVGraphic's behavior are intentionally different from the behavior of Borland's Turbo Vision (TM). Licensor warrants to registered users that the software will perform substantially in accordance with the accompanying written materials for a period of 90 days after registration, provided that it is the current version at time of registra- tion. The Licensor disclaims all other warranties, either express or implied, including, but not limited to, implied warranties of merchantability, fitness for a particular purpose and non- infringement. This limited warranty gives you specific rights. You may have others which vary state to state. 5 Licensor's entire liability and your sole remedy shall be the licensor's choice of A. return of the registration fee or B. making publicly available a new version of the software. In no event will the Licensor be liable to you for damages, including any loss of profits or other incidental or consequen- tial damages arising out of your use or inability to use the software. This may not apply to you since some states do not allow this exclusion. ------------------------------------------------------- REGISTRATION - read license and limited warranty first. A personal use registration is $35. A single user commercial use registration for Version 1.5 is $95. ($65 if previously registered as a personal user.) Multi user - contact the author. Registration can be made via (Check README.DOC for latest) CompuServe's Shareware Registration forum - Go Computer Mail (US dollars - check, money order, cash) Telephone/credit card see Readme.Doc TVGraphic mail REGISTRATION FORM Name ____________________________________________ CompuServe or other user# ________________________ Address ___________________________________________ Address ___________________________________________ Postal code/Country _____________________________ I have version number __________________ ____ $35 Personal use (does not allow distribution of programs created with TVGraphic) ____ $95 single user Commercial use ____ $65 Upgrade personal to Commercial use Mail address Richard P Andresen RR2 Box 900 Hinesburg, Vermont 05461 U.S.A. 6 (**************************************************************) 1. COMPATIBILITY WITH TURBO VISION OBJECTS (CLASSES) Due to additional data fields in TView, TVGraphic is not directly compatible with TViews and descendants stored by Turbo Vision in streams and resource files. It is compatible with Turbo Vision data type objects (TRect,TCollection,etc.) and with Turbo Vision streams and resources. Stream Registration numbers Stream registration numbers of 60,000 and above are reserved for TVGraphic. The registration numbers of TVGraphic's TView and its descendants equal the Turbo Vision number plus 60,000. The regis- tration numbers of other objects match Turbo Vision. (**************************************************************) 2. GENERAL DISCUSSION of TVGraphic In the following sections the differences between TVGraphic and Turbo Vision will be discussed. There is extended discussion about areas unique to TVGraphic. It is assumed that the reader has some familiarity with Turbo Vision. In some cases, details of Turbo Vision's operation will be explained to help users of both environments. See also the separate BEGINNER.DOC file for some tutorial material on TV/TVGraphic. Change Summary - OBJECTS Only the visible objects of Turbo Vision (TView and descendants) plus TRect methods (see Coordinate System) have been changed. See Turbo Vision documentation for the others. The Mouse Cursor object and some others have been added. Change Summary - NON-OBJECTS The DOS Critical error handler has been changed. Also almost everything having to do with drawing has changed - see Drawing. ------------------------ 2.1 The COORDINATE SYSTEM and TRect TVGraphic uses the same coordinate system as the Graph unit while Turbo Vision uses its own unique coordinate system. This has required code changes in TRect's methods to match the different coordinate system. Using the same coordinate system as the Graph unit is necessary for sanity when using the BGI drawing commands. It also means that it is easy to unintentionally specify adjacent screen rec- tangles so they overlap by a pixel. This will happen if you use the same screen coord to end one view and to start an adjacent view (which is correct practice in Turbo Vision). Often this overlap doesn't cause a problem in TVGraphic. But if an edge of a view seems to disappear or flicker on redraws, be sure the view's outline coordinates for that edge differ by one from its neigh- 7 bor. Remember when thinking of coord systems in the Graphic world, that all graphic drawing procedures draw relative to the current origin of the graphic ViewPort. ------------------------ 2.2 Larger than Screen Drawing - TGROUP INTERIORS The largest TGroup (or TWindow) you can define meaningfully is still the size of the screen as in Turbo Vision. But imagine that each TGroup has an INTERIOR which is larger than its screen outline, larger than the screen itself. Then the screen outline of a TGroup is a viewing window looking onto a portion of this large interior. By shifting this interior vertically and horizon- tally, we can place any portion of it under the TGroup screen outline. With TVGraphic, the subviews inserted in any TGroup (or TWindow) are imagined to be in this Interior and can have Origins and/or Sizes much larger than the screen. (Both Origins and Sizes must still be positive.) (Note: To find the maximum permitted value of a subview's Origin plus Size - For each axis, the subview's Origin plus its Size plus the sum of the Origins all the way up the view chain (TView.Owner.Origin, TView.Owner.Owner.Origin, etc.) must be less than the maximum value of an integer (32767) to prevent arithmetic overflow.) Shifting the Interior TView and its descendants have an added field for a variable called VOffset along with a method to set it. (VOffset is type TPoint, a dual integer. TPoint and TRect are used so often in Turbo Vision talk that you need to be familiar with them.) VOff- set is the number pair that determines the point in this extended Interior that draws at the upper left corner of the TGroup (i.e. at the Group's Origin). VOffset defaults to 0,0 at initialization so the interior is not shifted. When you use SetVOffset to change it and then redraw, the TGroup's interior will appear to move on the screen. Making VOffset.x more positive will move the interior to the left. Making VOffset.y more positive will move it up. It is legal to have negative values for VOffset though it's unlikely you would want them. Nesting Offset TGroups (TWindows) Any level of nesting is legal. (For TWindows, must use TVGraph- ic's TSubWindow or a descendant thereof for all subwindows.) Handling Mouse Events Event passing is unchanged from Turbo Vision - i.e whatever view 8 the mouse cursor is over receives the mouse event. When you call MakeLocal to convert the mouse position to local View coordi- nates, MakeLocal automatically takes into account all the TGroup VOffsets along the view chain. Same for MakeGlobal. Getting Drawing Coords See the Coordinate Transformation and the Drawing sections. ------------------------ 2.3 COORDINATE Transformations TVGraphic provides Coordinate transformation routines (as TView methods) for drawing that compute the absolute screen coords needed by the Graph unit drawing procedure even if the line or text is in a subview of a nested set of windows, each with non- zero VOffsets. Some of these transformations also take the cur- rent ViewPort setting into account. MakeLocal Used to convert from mouse coords (absolute screen coords) into the coord system of the Interior of the calling view. With TVGraphic, this means the returned values are in the coord system of the calling View's Interior. This is the same as Turbo Vision except you are not limited to the Size of the view. IMPORTANT NOTE:If you want to convert mouse coords into the coord system of something like a Window's TFrame which doesn't move with the Window's Interior, then TFrame must call its Owner's MakeLocal, i.e. Owner^.MakeLocal(). Otherwise your TFrame will shift as the Interior shifts.This is different from Turbo Vision! MakeGlobal Used to convert the calling View's Interior coords into abso- lute screen coords (mouse coords). (Do NOT use to convert the View's Origin - Origins are already in the View's Owner's coord system.) Returned values can be used for repositioning the mouse. Not normally used for drawing because it doesn't take the View- Port into account which TVGraphic changes during partial screen redraws. GetScreenCoords(var R : TRect) Used to get the outline of the calling View in absolute screen coords. Calling GetScreenCoords(Glob) will return the view's Origin in Glob.A, its lower right corner in Glob.B. Use the re- turned numbers to set the ViewPort if you want to clip at the View's boundaries. GetVPRelCoords(var R : TRect) Used to get the outline of the calling View in ViewPort rela- tive coords. Calling GetVPRelCoords(Glob) will return the View's Viewport relative Origin in Glob.A, its Viewport relative lower right corner in Glob.B. In your Draw routines, add this relative Origin to the Interior coords of any line, circle, text, etc. you 9 are drawing and pass the sum to the BGI drawing function(s). If you reset Viewport during a Draw, call GetVPRelCoords again to get updated coords. (If the ViewPort is set to full screen, GetVPRelCoords returns the same values as GetScreenCoords.) ------------------------ 2.4 DRAWING in TVGraphic Read previous sections first. Covers General Color ViewPort Mouse Cursor and drawing Outline of a .Draw routine MyGraph3 and Graph - referencing, conflicts with TV Text, fonts A Limitation of TVGraphic's redraw Mechanism Be aware that the Turbo Vision SetState methods usually include indirect calls to the Draw methods and to the automatic partial screen redraws that TVGraphic handles. HandleEvent methods also call Draw as you might expect. Your Draw methods must be ready to draw at any time, singly or as part of a group. Always use GetVPRelCoords to find your View's Origin coords and draw rela- tive to these coords unless you have a specific reason not to. ---- Drawing in TVGraphic and graphics in general. In Turbo Vision, all drawing is done to memory buffers and spe- cial routines are used to load text into the buffer. Turbo Vision Views often draw as many as three times to the buffer before the image is final and is transferred to the screen. Graphics is different. A buffer for a full, 16 color VGA graphic screen is over 130K! Early VGA adaptors had only 256K of memory so there is only one screen page. Also GetImage/PutImage transfer time on a 386 is surprising slow for even small views like menus - it is actually faster to redraw them. Therefore all drawing in TVGraphic is direct to screen. The drawback is that if you draw a view larger than a button multiple times to the screen you will likely see some flicker. Flicker occurs since the first operation of a graphic Draw method is usually to call Bar or Bar3d to fill the area of the View with a background. These routines are very fast even for a full screen. Then the graphic shapes and text are redrawn. Lines are very fast while text is the slowest to redraw. However, if only the color of the graphic objects needs to change and you know the view will never be partially obscured by another view (not true in most applications), you might try not redrawing the back- ground. Then you won't see flicker. 10 A better solution is to split the drawing into two sections as done for TCircles in the demo program. Let SetState and HandleE- vent call your routine DrawIt which draws only the foreground. Then have Draw first draw the background and then call DrawIt. TVGraphic will call Draw while you can selectively call DrawIt. When fine tuning your application, pay careful attention to how many times and ways SetState changes the state of your view. Most state changes call for a Draw somewhere in the tortuous path that is Turbo Vision's inner working. (Note that SetState often calls itself again recursively.) You can override SetState to eliminate some of these indirect Draw calls {be sure to let the state change!} and override others right in your Draw routine by check- ing the current state. In TVGraphic's standard views, much of this has been done for you. Run the demo program to see how well the standard objects draw themselves. ---- Color Hints and Hooks If you are creating objects with drawing behavior quite differ- ent from text based applications, the color Palette system shared by Turbo Vision and TVGraphic can seem very restrictive. To help, each TView in TVGraphic has a spare field of type word named VColor. It can store a simple color or one or two color pairs in the form used by the palette. I suggest ignoring the palette and using a mixture of global variables and VColor to start, moving towards palettes only as the application firms up. The Application palette contains the actual colors for TV/TVGraphic and is a Pascal string. TProgram.GetPalette returns a pointer to the string which you can then use to load a differ- ent color palette. (You will need to typecast this pointer to a PString which is TV's string pointer type.) As an alternative, once you have a pointer to the palette string, you can index into it to change individual color pairs. example: const newcolorpair : byte = my color choice; var Pal : PString; n : byte; {offset of color into the palette} .... .... Pal := PString(TProgram.GetPalette); Pal^[n] := Chr(newcolorpair); The default colors in the Application palette are different from Turbo Vision's choices. See the specific objects descriptions for their mapping into the palette - some changes from TV. Accessing Colors Several new functions are provided to sort out the colors re- turned by GetColor from the palette. (GetColor returns up to 4 colors in a single call.) 11 (var ColorPair,4Colors : word) First make your usual call: ColorPair := GetColor(PaletteIndex) then get individual colors using two new functions ForeColor(ColorPair) => foreground color BackColor(ColorPair) => background color OR (usual four color call) 4Colors := GetColor(HighlightPaletteIndex,PaletteIndex,) ForeColor(Lo(4Colors)) => foreground color BackColor(Lo(4Colors)) => background color ForeColor(Hi(4Colors)) => highlight foreground color BackColor(Hi(4Colors)) => highlight background color ---- ViewPort Borland's Graph unit supports an invisible ViewPort that can be sized from a pixel to screen sized and positioned anywhere over the screen. All Graph unit drawing calls are relative to the upper left corner of the ViewPort which is always 0,0. If Clip- ping is turned on, then drawing is clipped at the viewport bound- aries. TVGraphic expects you to set the Viewport to the size of the DeskTop in your TMyApp.Init. Suggest you turn clipping on. You may also set the Viewport to full screen. If you do not write any Draw routines for your application, this is the only time you will set the ViewPort. TVGraphic handles it from then on. Alternatively, you may change the Viewport within any Draw routine if you follow certain rules. You must be sure to save the current viewport settings upon entering your Draw routine and restore them before exiting. And you must compute the TRect.Intersect(ion) of the current viewport with the boundaries of the viewport you wish to set - then use the computed Intersec- tion to set the viewport within your .Draw. (The Intersection is only the area covered by both rectangles). If you forget, TVGraphic will get confused when it attempts to redraw just a portion of the screen using the viewport. Parts of the screen may not redraw or portions of overlapped views may seem to draw in the wrong order. See Demo program source code for examples. IMPORTANT : If you are using subviews that extend outside the screen in any way, and you reset the viewport, be sure to keep Viewport clipping ON or you may trash memory. ---- Graphic mouse cursor and .Draw routines You must hide the mouse before drawing in a .Draw and restore it after. It is not done automatically. DO NOT Call Turbo Vi- sion's HideMouse and ShowMouse! The cursor you see is not the one controlled by these calls. Do not call the mouse driver directly ( the mouse driver's cursor should be kept turned off.) The MCur unit provides some methods to control the driver. More info on the mouse cursor in section 2.5. The mouse cursor object is named MCur. 12 See unit MCur in Reference file. Also see .Draw program example. In a TView descendent Draw method, use MCur.Hide and MCur.Show. In a TGroup descendent, you do not need to do anything about the mouse cursor if it does not have its own Draw routine. (Then it just calls TGroup.Draw.) However, if you write your own Group Draw, then you should use MCur.LockHide and MCur.LockShow. These commands both hide/show the mouse and increment/decrement a counter that starts at 0. Every time you call MCur.LockHide the counter is incremented. MCur.LockShow decrements it. As long as the counter is not zero, the cursor remains hidden and the calls to MCur.Hide and MCur.Show return without any action. Thus if you are drawing a number of subviews, each of which should have its pair of Hide and Show, the cursor won't keep flashing on and off. Note that if you have more LockHides than LockShows, the cursor will remain locked invisible throughout your program. ---- Outline of a .Draw routine {call order is important} {see Demo.PAS for examples} {local variable Glob is type TRect} Hide the mouse MCur.Hide if setting Viewport, save current settings Compute the Intersection of the current and desired Viewports Set the Viewport, if necessary, using the Intersected area Get the Origin of this view in viewport relative coordinates by calling GetVPRelCoords(Glob). Set the drawing color. Set text font if drawing text. Make your drawing calls relative to the view's Origin: Line(Glob.A.x+LineStart.x, Glob.A.y+LineStart.y Glob.A.x+LineEnd.x , Glob.A.y+LineEnd.y); Reset Viewport to previous settings if changed. UnHide the mouse MCur.Show ---- Referencing the Graph/MyGraph3 Units ! IMPORTANT ! Do not reference the Borland's Graph unit directly from your program. In other words, use MyGraph3 in the Uses statement, not Graph. Make graphic calls to the MyGraph3 unit with the same names as if calling to the Graph unit. User Heap management is not supported. Some calls to Graph routines are intercepted in MyGraph3 - Set- TextStyle and Bar for example, and possibly more in the future. If printing capability is added, it will also function by inter- cepting calls here. Note that the MyGraph3 contains the drivers for Font8x8 and Font14x8. Conflicts between Turbo Vision Names and Graph/MyGraph3 Unit Names 13 ! CAUTION - guaranteed to byte you ! Gotcha #33 : Both TView and the BGI have a MoveTo command! If you say MoveTo(10,140) in your Draw routine, the View will try to move!!! Must say : MyGraph3.MoveTo(10,140). When your Draw routines absolutely refuses to write in the cor- rect spot on the screen late at night, this is what is happening. Gotcha #34 : Both TView and the BGI have a GetColor command! GetColor in a Draw routine calls TView.GetColor. You can call the graph unit's MyGraph3.GetColor but I suggest avoiding it in your program design if you want to get to bed on time. ---- TEXT in TVGraphic You can use any of the four Borland fonts (ten in version 7.0) or after market fonts but read on... The standard fonts supplied with the BGI don't give one any good alternatives for text in many graphic applications. The Default font is a bitmapped 8x8 font which cannot be clipped in the middle of a character and won't draw at all if a string starts off the left side of the screen. All the nine stroke fonts with the exception of Smallfont are illegible when drawn at the size of a standard textmode character (around 8x14 pixels). Smallfont will work in this size though it is not particularly attractive. The Good News TVGraphic provides two fast bitmapped fonts that clip at the pixel level. Font8x8 is 8x8 pixels and Font8x14 is 8x14 which is the size of EGA text. Font8x8 is useful if you want a drawing grid of 10x10 pixels - you can snap the mouse cursor to a grid like this, for example, and position the text so that an on-grid line can be drawn above and below it. (A capital M is only 7x7 pixels in an 8x8 bitmapped font. The other bit is for space between lines and chars.) These fonts draw Much faster than BGI Default font for long strings. Bitmapped text draws fast on slow CPU machines. The Bad News These two bitmapped fonts can only draw horizontally, size is not changeable, and the BGI text justification commands have no effect on them. Starting with version 1.5, bitmap text speed has been improved threefold so there is no longer any bad news about that. Other news Font8x14 is the default font for TVGraphic menus and Dialogs (you can change these default fonts - see Reference section). All supplied Views (except the scrollbar) use the font stored in added field TView.VFont. Many of these views compute the length of text they display for various internal purposes. They 14 expect text to be 8 pixels wide which limits you to SmallFont, Font8x8, Font8x14 or any 8 pixel wide font you have. (See TStat- icText in Reference section for a few exceptions to this.) In your own Views, you can use any font, store your font selec- tion(s) in VFont and set it with SetTextStyle. Be aware that most vector fonts (except SmallFont) do not have uniform character widths. This means a string of characters varies in length de- pending on which characters it contains. Text Support Variables and Routines In Turbo Vision, all drawing is done to buffers and special routines are used to load text into the buffer. In TVGraphic, the standard Graph unit procedures OutText,Out- TextXY, plus two special routines, WriteCStr and WriteCStrXY handle text. To write Turbo Vision's special highlighted strings with the embedded tilde characters '~' , position the graphics cursor with MyGraph3.MoveTo(x,y), then call WriteCStr. Or use WriteCStrXY. Function CStrLen will return the length of the string without the tilde's. WriteCStr takes the text string plus the normal and highlight text colors. Otherwise it behaves like OutText, which it calls, and may be used to write any string to the screen. WriteCStr, WriteCStrXY and Turbo Vision's CStrLen are global, not part of an object. See Reference Section. A dynamic vertical justification value of BYOffset is provided for use with Font8x8, Font8x14, SmallFont. See Reference section. Adding Your Own Fonts Follow the usual BGI procedures. Font8x8 is font number 14 and Font8x14 is number 15. Pascal version 7.0 has assigned font names for numbers 0 through 10 despite what the printed documentation says. You can still add your own fonts and I am assuming that they will be assigned at 11,12, and 13. If the BGI assigns your font a number of 14 or higher, TVGraphic will substitute its fonts. Storing fonts numbers Use TView.Vfont which is a byte. Since the maximum font number in TVGraphic is 15, you can pack two fonts into VFont and use the TVGraphic color methods ForeColor and BackColor to separate them. Failed Calls to SetTextStyle TVGraphic will substitute Font8x8 if your call to SetTextStyle fails to select the designated font. See SetTextStyle in Borland documentation. ---- ! Limitation of TVGraphic Automatic Redrawing mechanism ! TVGraphic's partial redraw scheme isn't aware of open submenu(s) extending over the DeskTop. This is because they are inserted in the Application, not the DeskTop. If submenus are open and you create an overlapping modal 15 view, such as a Help dialog, you must manually call the submenu chain to redraw themselves when the dialog closes as shown here. example Control := ExecDialog(HelpDialog); { or Control := DeskTop^.ExecView(HelpDialog); Dispose(HelpDialog,Done);} {redraw the submenu chain} P := MenuBar^.Target; {first submenu in the chain} while P <> nil do begin {redraw all open submenus} P^.DrawView; P := P^.Target; end; ------------------------ 2.5 MOUSE CURSOR Do not call the mouse driver directly. Do not call Turbo Vision ShowMouse, HideMouse. Make calls using the MCur (mouse cursor object) methods. See Section ENVIRONMENT and OBJECT BEHAVIOR, Mouse Button Phi- losophy for how to alter behavior of right mouse button to match Turbo Vision. The demo program shows a way of suppressing consecutive "Event.Double" 's. This can be handy in programs which try to get a lot of different actions from mouse button activity. Otherwise it shouldn't be necessary. GRIDS AND SIZING VIEWS TO WORK WITH THEM Mouse Cursor Grids A mouse cursor grid causes the cursor to jump from point to point on the grid instead passing through every pixel. TVGraphic defaults to a 10x10 pixel grid on startup. To override this, set the grid in your application's .Init after the call to MCur.Init. See below and demo program for code. Two types of mouse grids may be desired. One would be for views that are text based such as Dialogs, Menus and Text Scrollers and the other would be for graphic drawing to grid where a square grid of 5x5 or 10x10 pixels might be convenient. (A 10x10 grid and Font8x8 work well together.) Of course all grids can be turned off. See Demo program source for actual code. See MCur in Reference Section for all mouse cursor calls. 16 To turn off all mouse grids : MouseSnapToDialogGrid = false MouseSnapToMenuGrid = false MCur.SetGrid(1,1,0,0) {sets the mouse grid to single pixel, no offset} Setting a Grid MCur is the mouse cursor object. SetGrid is the method to set the mouse cursor grid. SetGrid(XGridpitch,YGridpitch,XGridOffset,YGirdOffset) The first two parameters set the grid pitch and the last two set the offset of the grid points from the upper left corner of the screen. (In addition to setting a grid, you might also want to restrict the mouse movement on the screen for a portion of a program. Do not call the mouse driver directly. Use MCur methods. See Refer- ence Section.) Note that the mouse grid is referenced to the upper left corner of the screen, not the DeskTop. Therefore you usually must take the height of the MenuBar into account since your views are inserted in the DeskTop. Suggested heights of the MenuBar are 15 or 20 pixels. (See DefaultMenuBarHeight in Reference Section.) If you wanted a 10x10 mouse grid, you would probably make the size of your windows multiples of 10. Conversely if the windows display text and you use the bit mapped fonts, it is convenient to dimension the windows using the TVGraphic constants Charlen and Boxheight. Saving a Grid Call MCur.GetGrid(var AGrid : MGridRec) to get the current Grid settings. Automatic Grids A feature that makes life easier is that snapping the mouse to the Dialog and Menu grid is automatic in TVGraphic if you enable it. These snaps are based on a standard text box that is Box- height tall by N*Charlen wide. (Font8x8,Font8x14 and SmallFont can work in this box.) Furthermore these snaps are active only when a box submenu or Dialog box is executing and they restore the previous user specified grid when the menu or Dialog returns. They also correct for the height of the MenuBar. The box subMenus are automatically sized using this standard text box. If you size your Dialogs using integer multiples of the Charlen and Boxheight constants as well as setting the Origin of all the views you insert into the Dialog with integer multiples of these same constants, the automatic grid will work. (i.e. R.A.x := I*Charlen; R.B.x := R.A.x + J*Charlen R.A.y := M*Boxheight; R.B.y := R.A.y + N*Boxheight; 17 where I,J,M,N : integer, R,Bounds : TRect Bounds := R; TView.Init(Bounds); ) One additional point - when inserting the Dialog into the DeskTop, again use integer multiples of the Charlen and Boxheight constants for the Dialogs Origin. Or even easier, just set the ofCentered flag in the Dialog.Option field (not VOptions field) and set the Origin to (0,0). Then call DeskTop^.ExecView or ExecuteDialog. TVGraphic will center your Dialog in the DeskTop regardless of the height of your MenuBar. If the Dialog cursor snap is on, it will modify its centering slightly so the Dialog is perfectly positioned on this mouse text grid. Using the Text Grid (Charlen x Boxheight) in your own views: First follow the above rules on view sizing. Then when you call OutTextXY or MyGraph3.MoveTo, add the TVGraphic variable BYOffset to your Y coordinate. It is adjusted by TVGraphic to match the text grid and the currently selected font (bit mapped or Small- font). ------------------------ 2.6 Sizing the DeskTop,Menu,StatusLine see demo program In TVGraphic the MenuBar height is sized based on global variable MenuBarHeight (default value = 15). The Bounds.B.y value you pass when calling .Init is ignored. To change the height, change the value of MenuBarHeight before calling TProgram.Init. See demo program for example of changing it. In TVGraphic's TProgram.Init, the DeskTop is sized automati- cally based on the height of the Menubar and the height of the StatusLine, if they exist. If you won't be using a top menubar or a StatusLine, you must still override TProgram.InitMenuBar and/or InitStatusLine to prevent a default version from being created. If your application has a natural vertical grid - say 14 pixels for lines of text or 10 pixels for a drawing program - you may be able to choose the heights of menubar and statusline to give you an integral number of grid spacings in the Desktop. (**************************************************************) 3. ENVIRONMENT and OBJECT BEHAVIOR In general the default behavior of objects is the same in TVGraphic as in Turbo Vision. Some exceptions are noted below. TView has an added field VOptions which is used by some Views to hold flags that modify their behavior. VOptions and its flags will evolve as TVGraphic evolves. See the Reference Section. evTimerTick There is a new class of events based on the DOS timer tick. See GDrivers in the Reference Section. Mouse Button Philosophy 18 As a graphical environment where the mouse may be involved in drawing as well as selecting, TVGraphic has different rules for mouse buttons than Turbo Vision. The left button selects, starts, moves, etc. while the right button cancels, quits without action. The return key maps to the left button and the escape key to the right button. Turbo Vision's mouse handler does not distinguish between left and right button releases so often TVGraphic re- sponds to button presses (evMouseDown events), not releases. BUT NOW you can change some of this starting with Version 1.5 . Unit GViews defines a global variable used by all standard views. AllowBothMButtons : boolean = False; By setting AllowBothMButtons true, TVGraphic will respond to the right mouse button as TV does. (Will not change response to mouse down events.) This includes NOT exiting a modal dialog on a right button press. Note: With ver 1.5, TVGraphic returns left and right button codes in TEvent.Buttons for evMouseUp . Mouse Movement As is described elsewhere, a user adjustable mouse cursor grid is part of the environment. The grid and its offset from the upper left corner of the screen is setable in pixel increments. The grid may be set to character size in the Menus and Dialogs but be different for the screen in general. See MCur in the Reference section. Note: The mouse cursor you see in TVGraphic is not the mouse driver's cursor. Menus The behavior of the mouse in the menus differs significantly from Turbo Vision. Right mouse button cancels a menu, left button immediately selects the entry. Unless you are used to the MacIn- tosh computer, you probably won't notice. Also TV bug where menu returns if mouse clicks on menu background is eliminated. Right button for popup submenu is not supported. TBackground Gets its pattern from the palette. You have four pattern choices. TButton The method of keeping track of which button is the Default button is completely different from Turbo Vision. This should not be noticeable unless you try to make further modifications. See Reference section on how to change the default button after initializing. Bitmapped buttons are covered in file Bitmap.Doc. TCollection.Load See section heading in this file on TGroup/TCollection Loads. 19 TDialog Unlike TV, a dialog can be Inserted into a window. i.e. MyWin.Insert(MyDialog). TFileDialog/TChDirDialog The instant erase feature of the inputline has been disabled. It can be enabled by clearing the KillInstantErase bit in the PFileDialog^.FileName^.VOptions field. TFrame The TFrame does not draw frames for subviews (depending on the ofFramed bit) as in TV. Instead the subviews are responsible for drawing their own frame depending on ofFramed. See ofXXXX in reference section. If the proper VOptions flag is set, a TFrame will draw a com- plete background for its window. By default, it does not redraw the interior. This can reduce flicker during redraws. Other VOption flags are set by TWindow.StandardScrollBar to let TFrame know if right and bottom edge scrollbars are present. If so, it fills in background areas under and next to them. TGroup.Load Tests after each subview for LowMemory. Exits if true. User should verify top object being loaded with ValidView to insure complete Group and subgroups were loaded. See section heading in this file on TGroup/TCollection Loads. TInputLine, TgInputLine A VOptions flag is available to turn off the maddening instant erasure of an existing entry when you touch a key. Also a flag to cause the input line to be right justified.See Reference Section. TScrollBar In TV, a scrollbar depends on a TScroller view to tell it to display or hide as the TScroller (and its window) goes Active/inActive (sfActive). In TVGraphic, scrollbars do not need a scroller object - they respond directly to the state of the window they are inserted in just like a TFrame. TScrollBar.SetState handles sfActive state changes itself. The TScroller does not control the scrollbar(s). Also, a scrollbar draws its background when its window is inActive rather than disappearing. TScroller TScroller scrolls by pixel increments. See demo program's TMyScroller for full example of a standard text based scroller. TStaticText, TgStaticText Does NOT draw its own background unless you set Opts := txDraw- Background in the constructor call or VOptions := VOptions or txDrawBackground after constructing. TStatusLine, TgStatusLine Events broadcast by the StatusLine have the InfoPtr set to Ptr(0000,0001) rather than nil as in Turbo Vision. 20 TView and descendants - Drawing Almost every method that has to do directly or indirectly with drawing has been modified or replaced including TView.Exposed. The Turbo Vision source code won't help much here. The Clip variable is in use. A routine is provided so you can access it although TView.Exposed is checking it already. TWindow The interior of a window does not draw while the window is being dragged. Mouse clicking on the window's number will cause the next window to be selected. Windows with no window number have a different appearance than regular windows. A function is provided to return the bounds inside the window's frame that should be covered by views. (**************************************************************) 4. CONVERTING FROM TURBO VISION Converting View Sizes from Turbo Vision If you use the bitmapped fonts or Smallfont, it is a snap to convert from Turbo Vision coordinates to TVGraphic coords. TVGraphic defines the constants Charlen and Boxheight. Simply multiply all X coords by Charlen and all Y coords by Boxheight. Where views touch, take the lower right corner coords obtained from this multiplication and subtract one from both x and y. This prevents views from overlapping. Buttons Sizes The above conversion makes rather fat looking Buttons since the button shadow is very thin in TVGraphic. The suggested alterna- tive is to use the TVGraphic constant DefaultButHt : integer = 20; to set the vertical button size Bounds.A.y := .... Bounds.B.y := Bound.A.y + DefaultButHt; AButton.Init(Bounds); (You may also set DefaultButHt to another value.) Converting HandleEvent and Draw methods If you have written your own HandleEvent methods in Turbo Vision read on... If they use view or mouse coords (from mouse events), the coords will now be in pixel units. If you want to retain text based thinking, divide the X coord by Charlen and divide the Y coord by Boxheight (this is the inverse of Converting View Sizes above). If you are dividing the view's Size to get back to text coords, then remember that, in graphic mode, views run from 0 to Size pixels so do as follows: NumXchar's := (Size.x+1) div Charlen NumLines := (Size.y+1) div Boxheight 21 If you want to pan in TVGraphic using the larger than screen Interior of a TVGraphic Group and you are converting a TFrame, Scrollbar or other view that is inserted in the panning Group BUT you want the view to stay fixed as the Interior scrolls/pans, then Whenever you need to call MakeLocal, MakeGlobal, GetScreenCoords, GetVPRelScreenCoords for this fixed view, actually call the routine of the view's owner, i.e. call Owner^.MakeLocal() instead of MakeLocal. If you fail to do this, your view will pan along will the rest of the inserted views. More on Draw Methods Because of the change to Graphics mode, Draw methods are not really convertible. You must rewrite them following the approach described in section Drawing in TVGraphic and examples in the demo source code. Converting Dialog Unit Init's TVGraphic provides an additional parameter in the Init con- structors for several views in the GDialogs unit. This parameter comes last in the parameter list, after the parameters defined by Turbo Vision. It is used for setting options that affect view behavior and font selection. The simplest approach to conversion is to set this parameter equal to the constant DefaultOpts. This will match Turbo Vision and cause a default font to be stored in the view's VFont. After your program is running, you can examine the TVGraphic options in the Reference Section to see if you want to set any of them. (**************************************************************) 5. Customizing TVGraphic's Appearance How to change TVGraphic's appearance TVGraphic has the usual Turbo Vision style color palette but there are many other things that can be changed. This is a sum- mary of material on settings for changing appearance. If you don't see what you want here, also check the Reference file under likely Unit name(s) and/or Object names for user changeable set- tings. Be sure to look at the demo program for examples. GAPP procedure ImprovePaletteColors; improves look of dark gray and brown on VGA monitors, no effect in EGA 22 GBUT const {use with Opts field of TIconButton} tbDrawFrame draws a button shadow frame over the perimeter of the bitmap tbAutoSize the button sizes itself to match the bitmap tbDrawDisabled bitmap colors change when Command is disabled, see TIconButton.DrawState tbDrawThickFrame GDIALOG DefaultButHt : integer = 20; default button height in standard views TextButtonsMatchBitMapButtons : boolean = false; whether text based buttons should look like Turbo Vision or look similar to TVGraphic's bitmapped buttons DefaultDialogFont : byte = font8x14; affects TButton,TInputLine. Also all Text views unless overridden in Init(..,..,.,Opts); parameter. MouseSnapToDialogGrid : boolean = true; causes mouse cursor to snap to a 8x14 pixel grid while a modal Dialog is visible VOptions constants DefaultOpts behavior most like Turbo Vision {TgStaticText,TgParamText} used with Opts field of text.Init's txDrawBackground txCentered txAdjustSize txAuto = txCentered + txAdjustSize; To override the default font, set lower four bits of OPts field to name of font. {TgInputLine} KillInstantErase lnRightJustify GMENU6 MenuBarheight : integer = 15; height of the MenuBar in pixels, minimum value is 15 if using Font8x14 as assigned in Init. Set BEFORE initializing the menubar. MenuBoxheight : integer = Boxheight; vertical line spacing in Box menus MouseSnapToMenuGrid : boolean = true; causes mouse cursor to snap to a properly located Charlen by Boxheight grid while a BoxMenu executes. Set false to use current grid with BoxMenus. DefaultMenuFont : byte = Font8x14; 23 GVIEWS DefaultListViewerFont : byte = font8x14; TVColor = $FFFF; (used in TView field VColor) This value tells views to use TV palette color(s). currently used only in other units that use GViews AllowBothMButtons : boolean = false; used in Views to determine if they should react to the right mouse button as in Turbo Vision VOptions constants {TFrame drawing control} tfDrawBackground draw a complete background rather than a partial one MCURSOR2 The mouse has an hour glass "wait" cursor. Switch to it with MCur.SelectHourGlass, back with MCur.SelectStdCursor. EnableHourGlass : boolean = true; views in GSTDDLG and your views that use MCur.SelectHourGlass show the hourglass cursor only if EnableHourGlass is true. (**************************************************************) 6. HOOKS For TVGraphic Users Embed your stuff without re-deriving all the library objects Color, Font TView fields VColor,VFont available for storage Text Cursors In Turbo Vision, each View has a local text cursor and a set of TView methods to manipulate it. TView.ResetCursor is a private method which normally does the cursor drawing. In TVGraphic, it has been made public and virtual. Starting with ver 1.5, Reset- Cursor does draw TV's intrinsic blinking cursor. User Overridable Function Boolean function UserHook is an added virtual TView method that takes a pointer and a TUserRec as parameters. TView.UserHook returns false and does not alter its parameters. (You can also use it as a procedure by using Pascal's Extended syntax.) Over- ride it in your descendants. TVGraphic does not call this func- tion. See Reference section. User field TView has an added field Hook of record type TUserRec. TUserRec is multiple declared as a TRect, two pointers, and four integers. TVGraphic does not reference this field. See Reference section. (**************************************************************) 7. INTRINSIC LOW MEMORY CHECKING DURING TGROUP.LOAD and TCollection.Load Dangers in Using TCollection's Collections are so useful and widely used in Turbo Vision that 24 one assumes they must be safe. Not so. In TV, anytime a TCollec- tion is being created or expanded, you may unexpectedly run out of memory and abort with a RunTime error. This becomes especially likely when it is time to expand a large collection - TV must allocate space for a new array of item pointers before discarding any old memory. Further, it must find a single memory block large enough for this expanded pointer array. As discussed in this section, TVGraphic avoids memory induced runtime errors for TCollection.Load from a Stream. Otherwise it is the same as TV. Users are encouraged to suggest general pur- pose ways for TVGraphic to handle the other cases. Turbo Vision has no intrinsic means to check memory during a TGroup.Load or TCollection.Load. If a Group or Collection with many subviews/subgroups/items runs out of memory while loading from disk, your program will halt with a runtime error. TVGraphic's TGroup.Load checks for low memory after each view is inserted. It exits if LowMemory is true. This means that as long as each subview is no larger than the safety pool (LowMemory, safety pool - see TV documentation), your program won't halt and you can recover. When TGroup.Load exits due to finding LowMemory, the Group it was loading is not complete. You do not want to insert this Group in your program - it could crash! To detect this condition, use function ValidView on the pointer returned by S.Get() or test LowMemory yourself. ValidView will automatically dispose the Group, call the OutOfMemory method and return a nil pointer if LowMemory is true. If testing yourself, you must dispose the Group. Note that there is no need to check if you are certain that the entire Group you are loading needs less memory than the safety pool. TVGraphic's TCollection.Load checks for low memory after each item is loaded. It exits if LowMemory is true and sets Count equal to the number of items loaded. The shortened collection is usable. If the collection is being loaded as part of a TGroup, follow instructions for TGroup above. Version 1.5 Update: The above load is still not perfectly safe. Problem occurs if there is not a big enough free block of memory to create the array of pointers needed by a TCollection (four bytes times the initial Limit of the collection plus any expan- sion that has occurred}. In TV and earlier TVGraphic, this situa- tion aborts with a runtime error. TVGraphic Ver1.5 TCollections will not abort. Ver1.5 checks that enough memory exists to allo- cate the array. If not, it builds an empty collection with Limit=1, Count=0, sets flag and exits. Method Valid has been added to TCollection to check for errors during .Load. It returns an error number or 0. See TCollection.Valid in file REFER.DOC. (**************************************************************) 25 8. GWINDOWS.UNIT See also file REFER.DOC TSubWindow TSubWindow is a descendent of TWindow designed to be inserted into another window. The only thing different is the GetPalette method. It returns nil if its owner is a TWindow or a descendant of TWindow. Otherwise it calls TWindow.GetPalette. You can use TSubWindow anywhere you would use a TWindow. Descendants of TSubWindow inherit its capabilities. In versions of TVGraphic prior to 1.5, descendants of TSubWin- dow needed to override the GetPalette function. This should no longer be done. TPanWindow TPanWindow is a special window that has an Interior larger than the screen and will pan across this Interior when the mouse cursor reaches the edge of the screen. Panning at the sides of the screen is automatic. Panning at the top and bottom of the screen occurs if the user presses the right mouse button. With the mouse cursor at the top or bottom of the screen, the Message- Bar (unit GMenu: a view that temporarily overwrites the MenuBar) appears if vertical panning is possible to indicate this to the user. Sizing the interior and the pan steps follows rules - see TPan- Window in file REFER.DOC. TShiftView TShiftView detects the mouse cursor at the screen edge for the panning function of TPanWindow. The two views communicate via broadcast commands. TShiftView also controls the MessageBar to display and clear the 'press right mouse button to shift' mes- sage. TShiftView is invisible but it must still be in the right spot on the screen. This is up to the user. Panning at the top of the screen is only possible when the mouse cursor is over TShiftView. It is normally sized to cover the top row of pixels on the screen. For example Bounds.Assign(0, 0, GetMaxX, 0); Panning at the bottom of the screen is enabled when the mouse cursor is at its lowest allowed position on the screen. The exact position depends on the vertical pitch of the mouse cursor grid. To make all this work, you must initialize a TShiftView in your Application.Init and assign it to global pointer ShiftViewPtr BEFORE calling TProgram.Init. Also, call TShiftView.HandleEvent in your application's HandleEvent BEFORE calling TProgram.Hand- leEvent. See demo program for example. TShiftView gets its colors through the Menu palette. Mixing Windows and Views in a TPanWindow TSubWindows (not TWindow) and all other views can be used in a TPanWindow. However there are some restrictions. Mixing subwin- 26 dows and non-selectable views (StaticText for example) is OK. If you want to use F6,ShiftF6 keys to move through the windows, then insert the subwindows on top of (after) all the other subviews. If you don't, the initial ordering of windows may shift as you use F6,ShiftF6 or a window may remain trapped behind non- selectable views. Mixing subwindows with other selectable views requires some thought and has not been fully tested. Note that when a view other than a subwindow is selected, the window commands (cmNext,cmPrev,etc.) will be disabled per standard TV. This means you can't select a window with F6,ShiftF6 - yet if you press F6 while a window is selected, it will work. Consider creating a descendent of TPanWindow and clearing the F6,ShiftF6 keyboard Events yourself in its HandleEvent. From this new HandleEvent, be sure to call the TPanWindow.HandleEvent AFTER you modify window command behavior. If none of the subwindows you insert uses the TAB key, this could be coded to move through the subviews as in Dialog boxes. Note that a selected view won't move to the top unless its ofTopSelect Option bit is set. TWinBackground If you want a background for a window there are two choices. The usual is to set the tfDrawBackground flag in the VOptions field of the window's Frame. Alternatively, insert a TWinBack- ground view into the window. It will draw itself using the same palette colors as the Frame would to fill the window. Or it will draw itself using VColor if you set VColor to a color. Use TWin- dow.GetMaxViewSize to find the Bounds for TWinBackground.Init. TWinBackground will work in a Window without a frame. (**************************************************************) 9. TimerTick events evTimerTick events are generated by TProgram.GetEvent by calling GetBiosTickEvent(Event) if no other event has occurred. GetBio- sTickEvent checks the DOS timer-tick counter. These events will occur about every 18 milliseconds whenever no other events are being processed. If busy with other events, the event will be skipped. TProgram.GetEvent calls HandleEvent to distribute the tick event to all views. The tick count for the event is in Event.InfoLong. If you need to, you can also get the current timer tick count by calling function GetBiosTicks. This returns a longint. DOS increments the tick count every 18.2 msec and resets it to 0 at midnight. To use Timer tick events: Set view's EventMask EventMask := EventMask or evTimerTick; In view's HandleEvent, check if Event.What = evTimerTick 27 (**************************************************************) 10. Blinking Text Cursor TV's Intrinsic Blinking Text Cursor Yes its here and its new so it may not be entirely bug free. Using the cursor is a little different from Turbo Vision. To enable the cursor in a view, you need to set the view's Event- Mask to include evTimerTick and later call ShowCursor. You also MUST store the name of the font you are using in the view's VFont field. (The cursor needs the name to see how big your font is.) Graphic mode doesn't support a blinking cursor in hardware, so you are responsible for hiding the text cursor when directly calling your own redrawing methods. TVGraphic will handle the text cursor if you redraw by calling DrawView. As usual, TVGraphic handles the automatic screen redraws. It helps to remember that you must erase the cursor just BEFORE you change a view by redrawing. The cursor stores an image of the background under itself and restores this background to erase itself. If the view has changed, the restored background won't match. Use a call to ResetCursor(true) to momentarily erase the cursor - the cursor will reappear when the next evTimertick event is processed by HandleEvent. If you also want to change the present cursor position, call SetCursor which calls ResetCursor. The cursor will size itself and set its horizontal movement to match the font named in VFont. It calls TView functions VertText- Spacing, VertTextOffset and HorzTextOffset to position itself exactly on your text. If you choose not to use the TVGraphic constants Boxheight and ByOffset to space your text vertically, you will need to override VertTextSpacing and possibly VertTex- tOffset so they return your values. Similarly override HorzTex- tOffset if you want it to return a value other than zero. See utility function CalcVertTextOffset, the TView methods men- tioned above plus SetCursor, ResetCursor in Reference file. (**************************************************************) 11. Button choices TVGraphic defaults to Turbo Vision text style buttons in its standard views. But it lets you use TV style and bitmapped but- tons in your own views. Bitmapped buttons respond to all the Turbo Vision options but, being bitmapped, do so in their own style as described in BITMAP.DOC. To unify the look of the two kinds of buttons, TVGraphic provides a variable TextButtonsMatchBitMapButtons : boolean = false; that you can set. If true, text buttons draw with the same look as bitmapped buttons. Creating Bitmapped buttons Use Borland's Resource Workshop or the Paintbrush program that 28 comes with Microsoft's Windows to create bitmaps for your but- tons. You create only one bitmap with the button's normal appear- ance. TVGraphic will draw a button frame if the button has the correct flag set so you do not need one in your bitmap. The background color of the bitmap should usually be matched to the background color of TButton as described in BITMAP.DOC. Each bitmap button also has a settable flag that will cause the button to draw with altered colors if the button is disabled. (**************************************************************) 12. Compiling with TVGraphic List of Units, Paths, Caution on USES statements,Errors TVGraphic Unit names for BP7.0 users: unit fully up to TV2.0 BMPDrvr N/A GApp GBut N/A GColors GDialogs GDrivers GMenu6 GMsgBox GObjects yes GStdDlg yes GViews GWindow N/A MCursor2 N/A MyGraph3 N/A Rodent N/A Paths The compiler must have a path to the standard Graph unit and to the Turbo Vision TPU's. If you are using Borland's stroked fonts, then a path to the fonts will be needed. The EGA/VGA driver is already linked into TVGraphic and so doesn't need to be on the path. Compiler Version TVGraphic is available in units for TP6.0 and 7.0. You must use the units that match your version of the compiler. If not, expect the compiler's unit version mismatch error. Modified Turbo Vision units If you modify the Interface section of the Memory unit, the compiler will give you a Unit Version Mismatch error when you try to compile with TVGraphic. This could result from a change as small as adding or changing a constant! This is due to the way Pascal units behave. Caution on USES statements The compiler will not usually (should not) allow you to create 29 descendants of the objects in the Turbo Vision units and call them from within TVGraphic objects (it might for TObject and TPoint). TO BE SAFE : ALWAYS descend from the TVGraphic versions of the object. Since most object names are the same as Turbo Vision, NEVER list in a USES statement a Turbo Vision unit whose name corresponds to a TVGraphic unit ! example: use GObjects, never Objects In Borland demo programs, be sure to change the units in the USES statement to the corresponding TVGraphic units. ALSO Always refer to MyGraph3 in a uses statement, never Graph ! 30