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