Chapter 6 of the Turbo Pascal Reference The Turbo Vision Reference This chapter is part of the Turbo Pascal Reference electronic freeware book (C) Copyright 1992 by Ed Mitchell. This freeware book contains supplementary material to Borland Pascal Developer's Guide, published by Que Corporation, 1992. However, Que Corporation has no affiliation with nor responsibility for the content of this free book. Please see Chapter 1 of the Turbo Pascal Reference for important information about your right to distribute and use this material freely. If you find this material of use, I would appreciate your purchase of one my books, such as the Borland Pascal Developer's Guide or Secrets of the Borland C++ Masters, Sams Books, 1992. Thank you. For additional information on using Turbo Vision, including a detailed tutorial, please see Chapters 11 through 16 of the Borland Pascal Developer's Guide. About the Turbo Vision Reference The Turbo Vision Reference contains an alphabetized list of all Turbo Vision objects, global variables, procedures, functions, types and constant. This reference is substantially different than Borland's reference because: 1. Where possible, example code that actually uses the object type is shown. Borland's documentation generally does not show sample code within their Reference on Turbo Vision. 2. The reference includes all Turbo Vision features, including object types, types, constants, variables, procedures and function. All are grouped together in one alphabetized section, unlike Borland's reference, where you must look in several sections to find the desired item. 3. Most importantly, I have highlighted the methods that you are most likely to use within each object type. A problem with reading Borland's documentation is that they present each object type followed by all twenty to fifty possible methods within the object type. In real applications, though, you may only need to concern yourself with perhaps five to ten methods. Some of the variables and procedures are only useful to the underlying implementation of Turbo Vision and may not be particularly useful to your applications. Nonetheless, these internal procedures, where available, are included in the Reference and are designated as "internal" procedures. When reading the Reference entires, keep in mind that since Turbo Vision objects are themselves usually derived from other Turbo Vision objects, it can be difficult to locate the definition of a particular method. For example, you may see a procedure call such as, Shell.ReDraw; where Shell is derived from TApplication. You will need to look at the description of TProgram from which TApplication is derived, and then back to TView where you will finally locate the Redraw method. object which defines them. Naming Conventions Turbo Vision uses standardized naming conventions as an aid to making source code readable. The most important conventions are: 1. Type declarations begin with a capital letter T. 2. Pointers to object types begin with a capital letter P. 3. Registration records for stream I/O begin with a capital letter R. 4. Except for color palette constants, identifiers beginning with lower case letters are standard Turbo Vision constants. The following table shows the standard constant prefix characters: Prefix Definition Example ap Application palette apcolor bf Button flag bfdefault C Color palettes CListViewer cm Command constant cmok co Collection codes cooverflow dm Drag mode dmdraggrow ev Event constant evcommand gf Grow mode flag gfgrowall hc Help context hcnocontext kb Keyboard code constant kbalta mb Mouse button constant mbrightbutton of Option flag oftopselect P Pointer equivalent PCollection R Registration record RCollection sb Scroll bar sbrightarrow sf State flag sfactive sm Screen mode constant smfont8x8 st Stream code stok T Object type TCollection wf Window flags wfmove wp Window color palettes wpbluewindow The Turbo Vision Object Hierarchy -------------------------------- All Turbo Vision objects are descended from the TObject type. All displayable objects are descendants of TView (which is itself descended from TObject). Displayable objects include items such as dialogs, check boxes, buttons, windows and list boxes. Non-displayable objects are the TCollection, TStream, TResourceFile, TStringList and TStrListMaker data structure objects. The line of descent shown in the illustration, below, identifies how functionality is inherited between the objeccts. For example, TDialog is descended from TWindow and inherits functionality from the TWindow object. Illustration showing inheritance relationships between the Turbo Vision object types. TObject TView TBackground TButton TCluster TCheckBoxes TRadioButtons TFrame TGroup TProgram TApplication TDeskTop TWindow TDialog THistoryWindow THistory TInputLine TListViewer TListBox THistoryViewer TMenuView TMenuBar TMenuBox TScroller TTextDevice TTerminal TScrollBar TStaticText TLabel TParamText TStatusLine TCollection TSortedCollection TStringCollection TResourceCollection TStream TDosStream TBufStream TEmsStream TResourceFile TStringList TStrListMaker Turbo Vision Object Descriptions The following reference section contains each procedure, function, variable, type and constant declaration defined in Turbo Vision, plus each of the primary Turbo Vision objects. For the object descriptions, the information as organized into sections: Turbo Vision Hierarchy This section displays the derivation order of each object to help you understand how functionally has been inherited from parent to descendant. For example, the TMenuBar object's derivation is indicated by this drawing: TObject TView TMenuView TMenuBar This shows that TMenuBar is a descendant of TMenuView, which is a descendant of TView, which is a descendant of TObject. Discussion A brief overview of the purpose of each object is given in this section. Commonly Used Features This section summarizes the primary methods that your applications will likely use so that you will not need to spend much time attempting to understand the other facilities of the object. Many Turbo Vision objects have a large variety of fields and methods available for use. However, many of these are needed only for the implementation of Turbo Vision itself, and in most practical applications you will only need to reference a small selection of the fields and methods. Example Where appropriate, a typical example usage of the object is given here. Fields Each field is described. After the field's definition, a comment indicating { Read only } or { Read/Write } indicates whether or not its okay to directly access this field. Methods Every method defined for the object is presented in this section. Generally, more details are provided for those methods you are actually likely to use, than for methods that are primarily of interest to understanding the internal implementation of Turbo Vision. Abstract procedure ------------------------------------------------------------ Declaration: procedure Abstract; Unit: Objects Purpose: Calling this procedure terminates the program with run-time error 211. Theprocedure is normally placed in methods that must be overridden in descendent object types. By calling Abstract within such methods, this insures that the program will stop execution if the programmer has failed to override the method. Application variable ------------------------------------------------------------ Declaration: Application : PApplication = nil; Unit: App Purpose: TApplication.Init, via TProgram.Init, sets Application to @Self, hence, Application points to the application object. TApplication.Done resets Application to Nil. AppPalette variable ------------------------------------------------------------ Declaration: AppPalette : Integer = apColor; Unit: App Purpose: Holds the current application color palette selection (either apcolor, apblackwhite or apmonochrome). See: TView.Setscreemode, apxxxx constants apXXXX constants ------------------------------------------------------------ Application Palette constants Unit: App Purpose: These values are kept in Apppalette, indicating which application color palette is in use. Constant Value Usage apcolor 0 Selects color screen palette apblackwhite 1 Selects black & white palette apmonochrome 2 Selects the monochrome screen palette See: Apppalette AssignDevice procedure ------------------------------------------------------------ Declaration: procedure AssignDevice (var T: Text; Screen: PTextDevice); Unit:TexTView Purpose: This appears to be an internal Turbo Vision routine used in the TTerminal object class for the purpose of implementing a scroll buffer that might be used in computer terminal software program. bfXXXX constants ------------------------------------------------------------ Button Flags constants Unit: Dialogs Purpose: The bfxxxx values are passed as a bit mask to TButton.Init and specify button attributes, as shown in the table: Constant Value Usage bfnormal $00 non-default button bfdefault $01 This will be the default button bfleftadjust $02 If OR'd with either bfnormal or bfdefault, the button label will be left justified instead of centered. bfbroadcast $04 If this bit is set, when a button is pressed, TButton sends an evbroadcast message. If not set, TButton inserts a new event with Putevent. Caution: Its up to the programmer to insure that each TGroup entity (TDialog is descended from TGroup) has only one default button. See: Example code in Chapter 11, "Turbo Vision Tutorial" in the Borland Pascal Developer's Guide, also see TButton.Flags, TButton.Makedefault ButtonCount variable ------------------------------------------------------------ Declaration: ButtonCount : Byte = 0; Unit: Drivers Purpose: If a mouse is installed, Buttoncount holds the number of buttons on the mouse. If zero, then no mouse is installed. Check the value of Buttoncount when your program needs to know if a mouse is installed. CheckSnow variable ------------------------------------------------------------ Declaration: CheckSnow : Boolean; Unit: Drivers Purpose: If a CGA adaptor is detected, Turbo Vision sets Checksnow to TRUE. Older CGA video adaptor cards require special programming to avoid "snow" or static-like lines on the display. If the CGA video adaptor does not require snow checking, the program may set Checksnow to FALSE, resulting in faster output to the screen. Do not set or check Checksnow until after calling TApplication.Init. Cxxxxxx Color Palette constants ------------------------------------------------------------ See "Using Color Palettes" in chapter 13, "More Turbo Vision Features" in the Borland Pascal Developer's Guide for complete details regarding use of the color palettes. Except for CColor, CBlackWhite and CMonoChrome, all of the color palette constants contains indices into their owner's palette. For CColor, CBlackWhite and CMonoChrome, each entry contains an actual BIOS video color attribute byte. You can use these color palette maps to determine what color a particular object or component will have when it appears on the screen. For example, if you place a TButton object into a TDialog object, you can trace through the color palettes to determine what color it will have. A "normal" button will have the attribute "Text Normal" shown in the first byte of the CButton color palette. This color entry is an index into its owner's palette, CDialog. Looking at the 10th entry of CDialog, we see that this maps to entry 41 in the application-level palette. In the case of CColor (color display in use), this corresponds to black lettering on a green background. CBackground Byte Usage Maps to On this palette [ 1] Background 1 Application palettes CButton Byte Usage Maps to On this palette [ 1] Text Normal 10 CDialog palette [ 2] Text Default 11 [ 3] Text Selected 12 [ 4] Text Disabled 13 [ 5] Shortcut Normal 14 [ 6] Shortcut Default 14 [ 7] Shortcut Selected 14 [ 8] Shadow 15 CCluster (used for TRadioButtons and TCheckBoxes) Byte Usage Maps to On this palette [ 1] Text Normal 16 CDialog [ 2] Text Selected 17 [ 3] Shortcut Normal 18 [ 4] Shortcut Selected 18 CDialog Byte Usage Maps to On this palette [ 1] Frame Passive 32 Application palettes [ 2] Frame Active 33 [ 3] Frame Icon 34 [ 4] Scrollbar Page 35 [ 5] Scrollbar controls 36 [ 6] StaticText 37 [ 7] Label Normal 38 [ 8] Label Highlight 39 [ 9] Label Shortcut 40 [10] Button Normal 41 [11] Button Default 42 [12] Button Selected 43 [13] Button Disabled 44 [14] Button Shortcut 45 [15] Button Shadow 46 [16] Cluster Normal 47 [17] Cluster Selected 48 [18] Cluster Shortcut 49 [19] Inputline Normal 50 [20] Inputline Selected 51 [21] Inputline Arrows 52 [22] History Arrows 53 [23] History sides 54 [24] HistoryWindow Scrollbar page 55 [25] HistoryWindow Scrollbar controls 56 [26] ListViewer Normal 57 [27] ListViewer Focused 58 [28] ListViewer Selected 59 [29] ListViewer Divided 60 [30] InfoPane 61 [31] Reserved 62 [32] Reserved 63 CFrame Byte Usage Maps to On this palette [ 1] Passive frame 1 Standard window palettes [ 2] Passive Title 1 [ 3] Active Frame 2 [ 4] Active Title 2 [ 5] Icons CHistory Byte Usage Maps to On this palette [ 1] Arrow 14 CDialog palette [ 2] Sides 20 CHistoryViewer Byte Usage Maps to On this palette [ 1] Active 6 CDialog palette [ 2] Inactive 6 [ 3] Focused 7 [ 4] Selected 6 [ 5] Divider 6 CHistoryWindow Byte Usage Maps to On this palette [ 1] Frame passive 19 CDialog palette [ 2] Frame active 19 [ 3] Frame icon 21 [ 4] ScrollBar page area 24 [ 5] Scrollbar controls 25 [ 6] HistoryViewer normal text 19 [ 7] History Viewer selected text 20 CInputLine Byte Usage Maps to On this palette [ 1] Passive 19 CDialog palette [ 2] Active 19 [ 3] Selected 20 [ 4] Arrow 21 CLabel Byte Usage Maps to On this palette [ 1] Text Normal 7 CDialog palette [ 2] Text Selected 8 [ 3] Shortcut Normal 9 [ 4] Shortcut Selected 9 CListViewer (used for TListViewer and TLIistBox Byte Usage Maps to On this palette [ 1] Active 26 Application palette [ 2] Inactive 26 [ 3] Focused 27 [ 4] Selected 28 [ 5] Divider 29 CMenuView (used for TMenuBar and TMenuBox) Byte Usage Maps to On this palette [ 1] Text Normal 2 Application palette [ 2] Text Disabled 3 [ 3] Text Shortcut 4 [ 4] Selected Normal 5 [ 5] Selected Disabled 6 [ 6] Selected Shortcut 7 CColor (for TProgram and TApplication) Byte Usage Attribute Actual color displayed Bytes 1 to 7 are used by menus and status lines [ 1] Background Text $71 Blue on White [ 2] Normal Text $70 Black on White [ 3] Disabled Text $78 Blue on Gray [ 4] Shortcut text $74 Blue on Red [ 5] Normal selection $20 Green on Black [ 6] Disabled selection $28 Green on Gray [ 7] Shortcut selection $24 Green on Red Bytes 8 to 15 are used by blue windows [ 8] Frame Passive $17 White on Blue [ 9] Frame Active $1F Bright White on Blue [10] Frame Icon $1A Light Green on Blue [11] Scrollbar page $31 Blue on Cyan [12] Scrollbar reserved $31 Blue on Cyan [13] Scroller Normal text $1E Yellow on Blue [14] Scroller Selected text $71 Blue on White [15] Reserved $00 Bytes 16 to 23 are used by cyan windows [16] Frame Passive $37 White on Cyan [17] Frame Active $3F Bright White on Cyan [18] Frame Icon $3A Light Green on Cyan [19] Scrollbar page $13 Cyan on Blue [20] Scrollbar reserved $13 Cyan on Blue [21] Scroller Normal text $3E Yellow on Cyan [22] Scroller Selected text $21 Blue on Green [23] Reserved $00 Bytes 24 to 31 are used by gray windows [24] Frame Passive $70 Black on White [25] Frame Active $7F Bright White on White [26] Frame Icon $7A Light Green on White [27] Scrollbar page $13 Cyan on Blue [28] Scrollbar reserved $13 Cyan on Blue [29] Scroller Normal text $70 Black on White [30] Scroller Selected text $7F Bright White on White [31] Reserved $00 Bytes 32 to 63 are used by dialog box components. [32] Frame Passive $70 Black on White [33] Frame Active $7F Bright White on White [34] Frame Icon $7A Light Green on White [35] Scrollbar Page $13 Cyan on Blue [36] Scrollbar controls $13 Cyan on Blue [37] Static text $70 Black on White [38] Label Normal $70 Black on White [39] Label Highlight $7F Bright White on White [40] Label Shortcut $7E Yellow on White [41] Button Normal $20 Black on Green [42] Button Default $2B Light Cyan on Green [43] Button Selected $2F Bright White on Green [44] Button Disabled $78 Gray on White [45] Button Shortcut $2E Yellow on Green [46] Button Shadow $70 Black on White [47] Cluster Normal $30 Black on Cyan [48] Cluster Selected $3F Bright White on Cyan [49] Cluster Shortcut $3E Yellow on Cyan [50] InputLine Normal $1F Bright White on Blue [51] InputLine Selected $2F Bright White on Green [52] InputLine Arrows $1A Light Green on Blue [53] History Arrow $20 Black on Green [54] History Sides $72 Green on White [55] Hist.Win. Scrollbar pg $31 Blue on Cyan [56] H.W.Scrollbar $31 Blue on Cyan [57] ListViewer Normal $30 Black on Cyan [58] ListViewer Focused $2F Bright White on Green [59] ListViewer Selected $3E Yellow on Cyan [60] ListViewer Divider $31 Blue on Cyan [61] InfoPane $13 Cyan on Blue [62] Reserved $00 [63] Reserved $00 CBlackWhite (for TProgram and TApplication) Byte Usage Attribute Actual color displayed Bytes 1 to 7 are used by menus and status lines [ 1] Background Text $70 Black on White [ 2] Normal Text $70 Black on White [ 3] Disabled Text $78 Gray on White [ 4] Shortcut text $7F Bright White on White [ 5] Normal selection $07 White on Black [ 6] Disabled selection $07 White on Black [ 7] Shortcut selection $0F Bright White on Black Bytes 8 to 15 are used by blue windows [ 8] Frame Passive $07 White on Black [ 9] Frame Active $0F Bright White on Black [10] Frame Icon $07 White on Black [11] Scrollbar page $70 Black on White [12] Scrollbar reserved $70 Black on White [13] Scroller Normal text $07 White on Black [14] Scroller Selected text $70 White on Black [15] Reserved $00 Bytes 16 to 23 are used by cyan windows [16] Frame Passive $07 White on Black [17] Frame Active $0F Bright White on Black [18] Frame Icon $07 White on Black [19] Scrollbar page $70 Black on White [20] Scrollbar reserved $70 Black on White [21] Scroller Normal text $07 White on Black [22] Scroller Selected text $70 Black on White [23] Reserved $00 Bytes 24 to 31 are used by gray windows [24] Frame Passive $70 Black on White [25] Frame Active $7F Bright White on White [26] Frame Icon $7F Bright White on White [27] Scrollbar page $70 Black on White [28] Scrollbar reserved $07 White on Black [29] Scroller Normal text $70 Black on White [30] Scroller Selected text $07 White on Black [31] Reserved $00 Bytes 32 to 63 are used by dialog box components. [32] Frame Passive $70 Black on White [33] Frame Active $7F Bright White on White [34] Frame Icon $7F Bright White on White [35] Scrollbar Page $70 Black on White [36] Scrollbar controls $07 White on Black [37] Static text $70 Black on White [38] Label Normal $70 Black on White [39] Label Highlight $7F Bright White on White [40] Label Shortcut $7F Bright White on White [41] Button Normal $07 White on Black [42] Button Default $0F Bright White on Black [43] Button Selected $0F Bright White on Black [44] Button Disabled $78 Gray on White [45] Button Shortcut $0F Bright White on Black [46] Button Shadow $78 Gray on White [47] Cluster Normal $07 White on Black [48] Cluster Selected $0F Bright White on Black [49] Cluster Shortcut $0F Bright White on Black [50] InputLine Normal $0F Bright White on Black [51] InputLine Selected $70 Black on White [52] InputLine Arrows $0F Bright White on Black [53] History Arrow $07 White on Black [54] History Sides $70 Black on White [55] Hist.Win. Scrollbar pg $70 Black on White [56] H.W.ScrollBar $70 Black on White [57] ListViewer Normal $07 White on Black [58] ListViewer Focused $70 Black on White [59] ListViewer Selected $0F Bright White on Black [60] ListViewer Divider $07 White on Black [61] InfoPane $07 White on Black [62] Reserved $00 [63] Reserved $00 CMonoChrome (for TProgram and TApplication) Byte Usage Attribute Actual color displayed Bytes 1 to 7 are used by menus and status lines [ 1] Background Text $70 Black on White [ 2] Normal Text $07 White on Black [ 3] Disabled Text $07 White on Black [ 4] Shortcut text $0F Bright White on Black [ 5] Normal selection $70 Black on White [ 6] Disabled selection $70 Black on White [ 7] Shortcut selection $70 Black on White Bytes 8 to 15 are used by blue windows [ 8] Frame Passive $07 White on Black [ 9] Frame Active $0F Bright White on Black [10] Frame Icon $07 White on Black [11] Scrollbar page $70 Black on White [12] Scrollbar reserved $70 Black on White [13] Scroller Normal text $07 White on Black [14] Scroller Selected text $70 Black on White [15] Reserved $00 Bytes 16 to 23 are used by cyan windows [16] Frame Passive $07 White on Black [17] Frame Active $0F Bright White on Black [18] Frame Icon $07 White on Black [19] Scrollbar page $70 Black on White [20] Scrollbar reserved $70 Black on White [21] Scroller Normal text $07 White on Black [22] Scroller Selected text $70 Black on White [23] Reserved $00 Bytes 24 to 31 are used by gray windows [24] Frame Passive $70 Black on White [25] Frame Active $70 Black on White [26] Frame Icon $70 Black on White [27] Scrollbar page $07 White on Black [28] Scrollbar reserved $07 White on Black [29] Scroller Normal text $70 Black on White [30] Scroller Selected text $07 White on Black [31] Reserved $00 Bytes 32 to 63 are used by dialog box components. [32] Frame Passive $70 Black on White [33] Frame Active $70 Black on White [34] Frame Icon $70 Black on White [35] Scrollbar Page $07 White on Black [36] Scrollbar controls $07 White on Black [37] Static text $70 Black on White [38] Label Normal $70 Black on White [39] Label Highlight $70 Black on White [40] Label Shortcut $7F Bright White on White [41] Button Normal $07 White on Black [42] Button Default $07 White on Black [43] Button Selected $0F Bright White on Black [44] Button Disabled $70 Black on White [45] Button Shortcut $0F Bright White on Black [46] Button Shadow $70 Black on White [47] Cluster Normal $07 White on Black [48] Cluster Selected $0F Bright White on Black [49] Cluster Shortcut $0F Bright White on Black [50] InputLine Normal $07 White on Black [51] InputLine Selected $70 Black on White [52] InputLine Arrows $07 White on Black [53] History Arrow $07 White on Black [54] History Sides $70 Black on White [55] Hist.Win. Scrollbar pg $07 White on Black [56] H.W.ScrollBar $07 White on Black [57] ListViewer Normal $07 White on Black [58] ListViewer Focused $70 Black on White [59] ListViewer Selected $0F Bright White on Black [60] ListViewer Divider $07 White on Black [61] InfoPane $07 White on Black [62] Reserved $00 [63] Reserved $00 CScrollBar Byte Usage Maps to On this palette [ 1] Page 4 Application palette [ 2] Arrows 5 [ 3] Indicator 5 CScroller Byte Usage Maps to On this palette [ 1] Normal 6 Application palette [ 2] Highlight 7 CStaticText Byte Usage Maps to On this palette [ 1] Text color 6 CDialog CStatusLine Byte Usage Maps to On this palette [ 1] Text Normal 2 Application palette [ 2] Text Disabled 3 [ 3] Text Shortcut 4 [ 4] Selected Normal 5 [ 5] Selected Disabled 6 [ 6] Selected Shortcut 7 CGrayWindow Byte Usage Maps to On this palette [ 1] Frame Passive 24 Application palette [ 2] Frame Active 25 [ 3] Frame Icon 26 [ 4] ScrollBar page 27 [ 5] ScrollBar reserved 28 [ 6] Scroller Normal Text 29 [ 7] Scroller Selected Text 30 [ 8] Reserved 31 CBlueWindow Byte Usage Maps to On this palette [ 1] Frame Passive 8 Application palette [ 2] Frame Active 9 [ 3] Frame Icon 10 [ 4] ScrollBar page 11 [ 5] ScrollBar reserved 12 [ 6] Scroller Normal Text 13 [ 7] Scroller Selected Text 14 [ 8] Reserved 15 CCyanWindow Byte Usage Maps to On this palette [ 1] Frame Passive 16 Application palette [ 2] Frame Active 17 [ 3] Frame Icon 18 [ 4] ScrollBar page 19 [ 5] ScrollBar reserved 20 [ 6] Scroller Normal Text 21 [ 7] Scroller Selected Text 22 [ 8] Reserved 23 ClearHistory procedure ------------------------------------------------------------ Declaration: procedure ClearHistory; Unit: HistList Purpose: Removes all strings from all history lists. ClearScreen procedure ------------------------------------------------------------ Declaration: procedure ClearScreen; Unit: Drivers Purpose: After Initvideo has been called by TApplication.Init, this procedure will clear the screen. However, most Turbo Vision applications will have no need to use this procedure. cmxxxx constants ------------------------------------------------------------ Command constants Unit: Views Purpose: The cmxxxx constants are the predefined commands within Turbo Vision and are passed to Handleevent methods in the Event.Command field. Constant values of 0 to 99, and 256 to 999 are reserved for use by Turbo Vision. Your applications can define command constants in the range 100 to 255, and 1000 to 65535. Constant Value Usage cmvalid 0 Message passed to TView.Valid cmquit 1 Upon receipt of cmquit, TProgram.Handleevent terminates the application. The Alt-X keystroke is normally mapped to the cmquit command. cmerror 2 No object should handle this command. Instead, use cmerror as away of trapping any unimplemented commands (i.e. while the program is still in development). cmmenu 3 This internal command is used to initiate menu selection. The status line, as shown in Chapter 14, typically maps the F10 key to cmmenu. See TSTATUSLINE. cmclose 4 For modeless window's, clicking in a window'sclose box causes the cmclose command to be sent to the window and the window's Close method is called. To prevent closing a window, you can intercept the cmclose command in your derived window's Handleevent method (also see the wfclose constants). Typically a status line item such as Alt-F3 is mapped to the cmclose command. The TVSHELL1 program in Chapter 14 uses the F3 key to generate cmclose for opening and closing subdirectories. cmzoom 5 The cmzoom flag is generated when the window is zoomed. You can prevent zooming by intercepting the cmzoom command (also see the wfzoom constant). By convention, Turbo Vision applications often use the F5 key to denote a zoom. cmresize 6 cmresize is sent when a window is resized. Also see wfmove and wfgrow. By convention, Ctrl-F5 is often used to zoom a window. cmnext 7 Causes the last window on the desktop to be moved to in front of all the others. F6 is often used as a short cut key for this command. cmprev 8 Moves the first window on the desktop to behind all the other windows. Shift-F6 is often used as a short cut key for this command. cmok 9 In a dialog, this value is returned if the Okay button was pressed. cmcancel 10 In a dialog, this value is returned if the Cancel button was pressed, or if the keyboard Escape key was pressed, or a dialog's close icon was clicked. cmyes 11 In a dialog, this is a standard value to be returned by a Yes button. cmno 12 In a dialog, this is the standard value to be returned by a No button. cmdefault 13 Is used to indicate a "default" button selection. cmreceivedfocus 50 Together with cmreleasedfocus, this command is sent by TView.Setstate to inform peer views of a change in focus. Views may use these messages to change their appearance (for example, a when a button loses focus, it is no longer highlighted). cmreleasedfocus 51 See above. cmcommandsetchanged 52 Whenever Enablecommands, Disablecommands or Setcommands changes the command set, this message is broadcast to every view's Handleevent method, giving them a chance to redraw themselves if the command set change affects how they should appear. cmscrollbarchanged 53 When a scroll bar's position indicator moves, the scrollbar sends this broadcast message to its owner. cmscrollbarclicked 54 When the mouse is clicked on a Scroll bar, the scroll bar broadcasts this message to its owner. cmselectwindownum 55 This broadcast message is sent when the keyboard keys Alt-1 through Alt-9 are pressed to select a specific window. The window who's TWindow.Number field matches the selection number (passed in Event.Infoint), responds by selecting itself with TView.Select. cmlistitemselected 56 Whenever an item in a list viewer is selected, the TListViewer sends this as an evbroadcast message. cmrecordhistory 60 When received by a THISTORY object, this message causes it to record the contents of the TINPUTLINE object that it owns. coxxxx constants ------------------------------------------------------------ Collection Error contants Unit: Objects Purpose: When a TCollection error occurs, the method TCollection.Error is called, with the Code parameter having one of the values shown in the table. Constant Value Usage coindexerror -1 Means that the index is out of range. In this case, the Info parameter of Error contains the invalid index. cooverflow -2 The collection could not be expanded any further. cStrLen Function -------------------------------------------------------------- Declaration: function CStrLen( S : String ) : Integer; Unit: Drivers Purpose: Returns the length of control strings, which are any strings containing short-cut characters surrounded by tilde '~' characters, minus the number of tilde characters. For example, CStrLen( '~F~ile' ) has a length of 4. CtrlBreakHit variable ------------------------------------------------------------ Declaration: CtrlBreakHit : Boolean = False; Unit: Drivers Purpose: Whenever the user presses Ctrl-Break at the keyboard, this flag is set to TRUE. You can clear it any time by resetting to FALSE. CtrlToArrow function ------------------------------------------------------------ Declaration: function CtrlToArrow( KeyCode : Word): Word; Unit: Drivers Purpose: This esoteric function converts certain control-key combinations to standard kbxxxx constant values. The original Wordstar word processor used a standard set of Ctrl-letter combinations as equivalents to IBM cursor movement keys and set a standard interpretation of these keys when used in word processing. To assist in providing Wordstar compatibility, Ctrltoarrow can be used to convert Event.Keycode values to their corresponding kbxxxx values. The following chart shows the mapping from control keys to kbxxxx values. Control key Lo(Keycode) Maps to Ctrl-A $01 kbhome Ctrl-D $04 kbright Ctrl-E $05 kbup Ctrl-F $06 kbend Ctrl-G $07 kbdel Ctrl-S $13 kbleft Ctrl-V $16 kbins Ctrl-X $18 kbdown CursorLines variable ------------------------------------------------------------ Declaration: CursorLines : Word; Unit: Drivers Purpose: Contains the height of the video cursor encoded such that the high 4 bits contains the top scan line and the low 4 bits contain the bottom scan line. For example, on a CGA screen a character is made up of 8 scan lines, with the topmost scan line being 0 and the bottommost scan line being 7 (the number of scan lines varies according to the type of the video adaptor card in use). The shape of the character cursor is determined with BIOS interrupt 10H, function 01H. For more information, consult the DOS Programmer's Reference, 2nd Edition, Que Books, page 424 "BIOS INT 10H Function 01h Set Cursor Type". See: TView.Showcursor, TView.Hidecursor, TView.Normalcursor (to set cursor shape to an underline), TView.BlockCursor (to set cursor to a solid block). DeskTop variable ------------------------------------------------------------ Declaration: DeskTop: PDeskTop = nil; Unit: App Purpose: Contains a pointer to the application's TDESKTOP object, and can be used to insert a window or dialog on to the desktop. For example, DeskTop^.Insert( New( PDirectoryWindow, Init(Bounds, 'Directory Listing', 0 ))); DisposeMenu procedure ------------------------------------------------------------ Declaration: procedure DisposeMenu( Menu: PMenu ); Unit: Menus Purpose: Disposes of a menu and all of its submenus. DisposeStr procedure ------------------------------------------------------------ Declaration: procedure DisposeStr(P : PString); Unit: Objects Purpose: Disposes of PSTRINGS allocated by Newstr. See Chapter 20, "Collections" for an example of using the PSTRING type, and the Newstr and Disposestr routines. dmXXXX constants ------------------------------------------------------------ Drag Mode constants Unit: Views Purpose: The TView.Dragmode field controls whether or not a view can be dragged or have it size changed. The Dragmode field is stored in a byte, with the bits set by the constants shown in the following table, and Limits is a TRECT parameter to TView.Dragview. Constant Value Usage dmdragmove $01 Allow the view to move. dmdraggrow $02 Allow the view to change size. dmlimitlox $10 The left hand side cannot move outside Limits. dmlimitloy $20 The top side cannot move outside Limits. dmlimithix $40 The right hand side cannot move outside Limits. dmlimithiy $80 The bottom side cannot move outside Limits. dmlimitall $F0 None of the view can move outside Limits. DoneEvents procedure ------------------------------------------------------------ Declaration: procedure DoneEvents; Unit: Drivers Purpose: This is a Turbo Vision internal routine that will not normally be used by your applications. Doneevents disables the mouse interrupt handler and hides the mouse. DoneHistory procedure ------------------------------------------------------------ Declaration: procedure DoneHistory; Unit: HistList Purpose: This internal Turbo Vision routine is called automatically by TApplication.Done to free up the history block allocated by Inithistory. DoneMemory procedure ------------------------------------------------------------ Declaration: procedure DoneMemory; Unit: Memory Purpose: This internal Turbo Vision routine is called automatically by TApplication.Done to free up all memory buffers that were allocated by Getbufmem. DoneSysError procedure ------------------------------------------------------------ Declaration: procedure DoneSysError; Unit: Drivers Purpose: This internal routine is called automatically by TApplication.Done, terminating Turbo Vision's system error trapping and restoring the interrupt vectors 09h, 1bh, 21h, 23h and 24h and the Ctrl-Break checking of DOS, to their original settings. DoneVideo procedure ------------------------------------------------------------ Declaration: procedure DoneVideo; Unit: Drivers Purpose: This internal routine is called automatically by TApplication.Done and terminates Turbo Vision's video support. DoubleDay variable ------------------------------------------------------------ Declaration: DoubleDelay : Word = 8; Unit: Drivers Purpose: Doubledelay holds the time interval (in 1/18.2 of a second intervals) defining how quickly two mouse clicks must occur in order to be treated as a double click (rather than two separate single clicks). By default, the two mouse clicks must occur with 8/18'ths of a second to be considered a double click event (with TEVENT.Double set to TRUE). EmsCurHandle variable ------------------------------------------------------------ Declaration: EmsCurHandle: Word = $FFFF; Unit: Objects ErrorAttr variable ------------------------------------------------------------ Declaration: const ErrorAttr: Byte = $CF; Unit: Views Purpose: If the TView.Getcolor method is unable to map a color palette index into a video attribute byte because the index is out of range, TView.Getcolor returns this value. $CF is the video attribute for flashing white characters on a red background - if you see flashing white on red, you need to check or override the Getpalette method. An example of how this works can be seen in the TVSHELL program. If the TDIRLIST.Getpalette method is removed from TDIRLIST, the listbox text will appear as flashing white on red. This occurs because the palette indices for a TListViewer, 26, 27, 28 and 29 are out of range for the window palette into which the list viewer is inserted. The solution is to override Getpalette to return values within an acceptable range. See: Chapter 13, "More Turbo Vision Features" in Borland Pascal Developer's Guide, Que Books, 1992. evXXXX constants ------------------------------------------------------------ Event constants Unit: Drivers Purpose: The evxxxx constants are used to designate event types and event masks, particularly as used in the What field of an event record but also in other places within Turbo Vision. Constant Value Usage ---------------------------------------- evmousedown $0001 Mouse button pressed evmouseup $0002 Mouse button released evmousemove $0004 Mouse has changed location evmouseauto $0008 This event occurs periodically while the mouse button is held down evkeydown $0010 A key has been pressed. evcommand $0100 The event type is a command event. evbroadcast $0200 The event type is a broadcast event. evnothing $0000 This event was already handled. evmouse $000F The event type is a mouse event. evkeyboard $0010 The event type is a keyboard event. evmessage $FF00 The event is a message event, which can be either user defined, an evCommand or evBroadcast event. See: See "Introduction to Events and the HandleEvent Method", in Chapter 11, "Turbo Vision Tutorial" in the Borland Pascal Developer's Guide. Also see Positionalevents and Focusedevents. FNameStr type ------------------------------------------------------------ Declaration: type FNameStr = string[79]; Unit: Objects Purpose: This type is used to declare strings containing DOS file names. FocusedEvents variable ------------------------------------------------------------ Declaration: FocusedEvents: Word = evKeyboard + evCommand; Unit: Views Purpose: Focusedevents contains a bit mask for identifying events that are focused. Any event that is neither a focused event nor a positional event, is classed as a broadcast event. See: Positionalevents variable, and "Positional Events" in Chapter 13, "More Turbo Vision Features" in the Borland Pascal Developer's Guide. FormatStr procedure ------------------------------------------------------------ Declaration: FormatStr( var Result: String; Format: String; var Params); Unit: Drivers Purpose: Formatstr takes a string Format and a list of parameters in Params and produces a formatted string that is returned in Result. Formatstr is typically used to insert parameter values into predefined strings, such as those used for error messages, or general program strings stored in a resource file. The Format string contains both text and imbedded formatting information, as in this example: 'File %s is %d bytes in size.' The formatting characters %s and %d indicate that a string and a decimal value, respectively, should be substituted in these locations. The values for the substitutions are specified in the Params parameter as shown in the example code, below. Format specifiers have the form % [-] [nnn] X, where the brackets indicate optional items and X is a format character. Table of Format Specifiers % Marks the beginning of a format specifier - Indicates the items should be left justified (default is right justified) nnn Specifies the width of the result, where nnn is in the range from 0 to 255. 0 is equivalent to not specifying a width. If nnn is less than the width needed to display a particular item, the the item is truncated to fit within the width value. For example, %3s allocates 3 character spaces. Ifthe string parameter contains 'Turbo', then only the last 3 characters 'rbo' will be inserted into the result. If you use %-3s, then only the first 3 characters will be inserted, giving 'Tur'. s Format character indicating the parameter is a string pointer. d Format character indicating the parameter is a Longint and is to be displayed in decimal. c Format character specifying the low byte of the parameter is a character value. x Format character specifying the parameter is a Longint to be displayed in hexadecimal. # Resets the parameter index to the optional nnn value. Params Parameter The Params parameter variable contains the data corresponding to each item specified in the format string. There are two ways that the Params variable can be initialized: 1) Use a record structure, 2) Or, use an array of Longint. Listing FORMAT1.PAS shows the record structure method, and Listing FORMAT2.PAS shows the array method. The record structure has the advantage of being easier to read, since each parameter is named in the record, while the array structure is more flexible, in that it can be dynamically set up to accomodate many different types of parameters. Listing FORMAT1.PAS: ------------------- program DemoFormat; { FORMAT1.PAS Demonstrates use of the Turbo Vision FormatStr procedure using a parameter record. } uses Drivers, Objects; type TParamRec = record FName : PString; FBytes: LongInt; end; var ParamRec : TParamRec; ResultStr: String; begin ParamRec.FName := NewStr('SAMPLE.TXT'); ParamRec.FBytes := 654321; FormatStr( ResultStr, 'File %s is %d bytes in size.', ParamRec ); Writeln( ResultStr ); Write('Press Enter to Continue.'); Readln; end. Listing FORMAT2.PAS: ------------------- program DemoFormat; { FORMAT2.PAS Demonstrates use of the Turbo Vision FormatStr procedure using a parameter array. } uses Drivers, Objects; type TParamArray = array[0..1] of LongInt; var ParamArray : TParamArray; ResultStr: String; begin ParamArray[0] := LongInt(NewStr('SAMPLE.TXT')); ParamArray[1] := 654321; FormatStr( ResultStr, 'File %s is %d bytes in size.', ParamArray ); Writeln( ResultStr ); Write('Press Enter to Continue.'); Readln; end. FreeBufMem procedure ------------------------------------------------------------ Declaration: procedure FreeBufMem(P : Pointer); Unit: Memory Purpose: Frees up the cache buffer pointed to by P. See Getbufmem for details. GetAltChar function ------------------------------------------------------------ Declaration: function GetAltChar(KeyCode: Word): Char; Unit: Drivers Purpose: When Keycode specifies an Alt-Ch character combination, where Ch is a letter from A to Z, Getaltchar extracts and returns the Ch character value. For example, writeln( GetAltChar( kbAltA )); prints the single letter A. Procedure Getaltcode maps characters back to Alt-Ch combinations. GetAltCode function ------------------------------------------------------------ Declaration: function GetAltCode( Ch: Char): Word; Unit: Drivers Purpose: Maps a single character 'A' to 'Z' to the Keycode equivalent value for pressing Alt-Ch. For example, GetAltCode ('A') returns $1E00, which is the value of kbalta. Getaltcode is the inverse function to Getaltchar. GetBufMem procedure ------------------------------------------------------------ Declaration: procedure GetBufMem( var P : Pointer; Size : Word ); Unit: Memory Purpose: Used to allocate a cache buffer where the cache buffer is a heap allocation that may be moved or disposed of at any time by the memory manager. As a result, the pointer variable passed to Getbufmem may be changed by the memory manager at any time during program execution to point to a different memory area, or even be reset to NIL. Turbo Vision uses cache buffers to speed up output the screen (also see TView's Options field and the ofxxxx constants) by having views store their display image in memory so that, if possible, the screen can be updated quickly merely by copying the memory image back to the screen (this is faster than regenerating the text and other data in the Draw method). However, when Turbo Vision begins to run low on memory, it starts throwing away the cache buffers, as needed until enough memory is freed up. In addition to Turbo Vision's use of cache buffers, your application can use cache buffers for storage that can be deleted by the memory manager in case memory is running low. An example use might be to cache the disk directory read into the TVSHELL8 sample program of Chapter 12 in the Borland Pascal Developer's Guide. If for some reason Turbo Vision or some other part of the program requests memory and there is not enough free memory in the heap, then the memory manager will dispose of one or more cache buffers, and set the corresponding pointer to NIL. Since the TVSHELL program can always recreate the directory structure by reading the disk directory again, its okay to reallocate this memory to some other function. Cache buffers are useful for speeding up access to items that can always be recreated. See: Freebufmem. GetKeyEvent procedure ------------------------------------------------------------ Declaration: procedure GetKeyEvent(var Event: TEvent); Unit: Drivers Purpose: Uses the BIOS function INT 16H, Function 01H "Read Keyboard Status" to determine if a key has been pressed on the keyboard. If so, Event.What is set to evkeydown and Event.Keycode is set to the scan code of the key. If no keys have been pressed, Event.What is set to evnothing. This is an internal procedure called by TProgram.Getevent. See: evxxxx constants, also DOS Programmer's Reference, 2nd Edition, Que Books, page 496, GetMouseEvent procedure ------------------------------------------------------------ Declaration: procedure GetMouseEvent(var Event: TEvent); Unit: Drivers Purpose: Similar to Getkeyevent, but for mouse events. This internal procedure checks Turbo Vision's internal mouse event queue, and if a mouse event has occurred, sets Event.What to the appropriate evmousexxxx constant; Event.Buttons to mbleftbutton or mbrightbutton; Event.Double to True or False; and Event.Where to the mouse position in TApplication coordinates. If no mouse events have occurred, Event.What is set to evnothing. gfxxxx constants ------------------------------------------------------------ GrowMode Field constants Unit: Views Purpose: The gfxxxx constants set the TView.Growmode field, which controls how a view grows in relation to the view that own's it. Constant Value Usage gfgrowlox $01 The left side of the view will stay a constant distance from it's owner's left side. gfgrowloy $02 The top of the view will stay a constant distance from it's owner's top. gfgrowhix $04 The right side of the view will stay a constant distance from it's owner's right side. gfgrowhiy $08 The bottom of the view will stay a constant distance from it's owner's bottom side. gfgrowrel $10 The view will maintain its size relative to the owner. This flag should only be used on TWindow derived objects and is intended for keeping windows adjusted relative to their owner when switching between 25 line mode and 43/50 line screen modes. gfgrowall $0F The view should maintain the same size and move with respect to the lower right corner of the owner. hcXXXX constants ------------------------------------------------------------ Help Context constants Unit: Views Purpose: The hcxxxx constants are used in conjunction with on-line help. Values 0 through 999 are reserved by Turbo Vision, but user written applications may use any value in the range 1,000 to 65,535. Constant Value Usage hcnocontext 0 No help context specified. hcdragging 1 The object is being dragged. See: See "Adding On-line Help to Turbo Vision Programs" in Chapter 13, "More Turbo Vision Features" in the Borland Pascal Developer's Guide. HideMouse procedure ------------------------------------------------------------ Declaration: procedure HideMouse; Unit: Drivers Purpose: This procedure is used to hide the mouse, making it invisible on the screen. Each time Hidemouse is called, it increments an internal "hide" counter. Showmouse decrements the internal counter and when the counter returns to zero, the mouse cursor will reappear. Therefore, you can nest calls to Hidemouse and Showmouse but there must always be the same number of each. HiResScreen variable ------------------------------------------------------------ Declaration: HiResScreen : Boolean; Unit: Drivers Purpose: Returns True if the screen supports 43 or 40 line modes, False if these modes are not supported. This routine should only be called after Initvideo is called via TApplication.Init.