Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / TPBOOK.ZIP / TPBOOK.EXE / TPR9.TXT < prev

Wrap

Text File | 1992-10-19 | 72.9 KB | 1,747 lines

Chapter 9 of the Turbo Pascal Reference The Turbo Vision Reference (continued) 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. TFrame object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TFrame Discussion TFrameobjects, like many of the objects in Turbo Vision, are automatically managed by Turbo Vision and you will rarely need to instantiate, let alone, directly access any of its methods. The TFrame object defines the border or "frame" that wraps around each window and is automatically created by TWindow.Init which calls TWindow.InitFrame. Fields None Methods procedure Draw; virtual; This method draws the frame, adding the owner's Title string, and the appropriate icons such as the close box, the zoom icon and the resize icon, as specified by the inherited TView.State flags. function GetPalette: PPalette; virtual; Returns a pointer to the default palette CFrame. In the unlikely event that you need to change a TFrame's color, you need to override TWindow.InitFrame to instantiate a new, TFrame-derived object with an overridden GetPalette. The overridden GetPalette then returns a pointer to the modified color palette mapping. You need to go through this indirect approach of overriding both TWindow.InitFrame and creating a new TFrame-type object because TFrame is normally used only internally to Turbo Vision. Hence, you must override the routine in TWindow that actually instantiates the TFrame. You can see an example of this type of operation in the description of TBackground. procedure HandleEvent(Event : TEvent); Calls TView.HandleEvent for general event processing, and then processes events for the TFrame icons. constructor Init(var Bounds: TRect); Creates a new TFrame object having the size and location specified by Bounds. This method is called by TWindow.InitFrame. See: TWindow.InitFrame procedure SetState(AState: Word; Enable: Boolean; virtual; TFrame.SetState passes its parameters to TView.SetState, and then checks TView.State to see if either sfActive or sfDragging are set. If these bits are set, then TFrame.SetState calls TView.DrawView. TGroup object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TGroup TWindow TDialog TDeskTop TProgram Discussion The TGroup object manages groups of objects, all of which are descended from TView. In effect, TGroup keeps track of a group of subviews, such as multiple windows on the desktop, or all of the controls within a dialog. TGroup provides the functionality to manipulate the grouped views as if they were a single view, although TGroup itself, surprisingly, is an invisible view. That's because each of the subviews contained within a group defines the group itself. For example, a TDialog contains a window, a frame, a dialog interior and a collection of controls such as input lines, checkboxes and buttons. The TDialog object is the manager of these dialog box components and is actually invisible. WhenTDialog.Draw is called to draw itself on the screen, it doesn't actually draw anything; instead, TDialog.Draw calls each of the subview's Draw methods (the window, the frame, the buttons and so on). Commonly Used Features For most applications you will use only a few of the methods provided by TGroup, including the Init constructor (via the subview's inherited Init methods), ExecView to execute a modal dialog box, Insert to add a subview to the group, and GetData and SetData to read and write the data fields of the owned views (particularly for dialogs). TGroup is an internal object used to support other Turbo Vision objects (such as TWindow or TDialog), and the remaining methods are used to implement their specific functionality. It is unlikely that you will need to instantiate a TGroup directly. Example See TApplication, TDeskTop, TDialog, TWindow Fields Buffer: PVideoBuf; { Read only } When caching of views is in effect, the contents of the group of views is stored in a temporary cache buffer to speed up screen redrawing. Buffer points to the memory buffer used for caching, or is nil if no cache buffer has been defined. See GetBufMem, TGroup.Draw, TGroup.Lock, TGroup.Unlock Current: PView; { Read only } Is a pointer to the currently selected view (the view whose Select method has been called). See: TView.Select, Chapters 16 and 18. Last: PView; { Read only } Last is a pointer to the subview that is on the bottom of the Z-ordered list of views. Each view contains a TView.Next pointer that points to the next view in the list. Phase: (phFocused, phPreProcess, phPostProcess); { Read only } Subviews can examine this field to determine at which phase in the event processing their HandleEvent method was called. See Chapter 13, "More Turbo Vision Features" in the Borland Pascal Developer's Guide for a more in depth discussion of phased event processing. Methods procedure ChangeBounds(var Bounds: TRect); virtual; Override: Never A group is resized or moved by calling ChangeBounds, which, in turn, calls TView.CalcBounds to recalculate new boundaries for its subviews, and then ChangeBounds to reposition the subviews. These calls are made for every subview in the group. function DataSize: Word; virtual; Calls each subview's DataSize method and creates a total data size value for the entire group. This function is normally used in conjunction with GetData and SetData for retrieiving specific field values. procedure Delete(P: PView); Use Delete to remove a previously inserted view from a group. For example, if you have inserted a view, like this, Insert(DirWindow); you remove the subview by calling, Delete(DirWindow); destructor Done; virtual; Call Done to dispose of the group and its contents. Done first hides the group and then calls each view's Done destructor, and finally disposes of itself. procedure Draw; virtual; If Buffer is nil, then TGroup.Draw calls each subview's Draw method. If Buffer is not nil, then Draw calls TView.WriteBuf to copy the cached view image to the screen. See: TGroup.Buffer procedure EndModal(Command: Word)(; virtual; Override: Never When the currently active dialog, for instance, that has been placed on the screen with the TGroup.ExecView method, it is the current modal view. A call to this procedure terminates the modal nature of the view and passes the Command value to ExecView, which in turn, returns Command to the caller. If a group is not currently a modal view, TGroup.EndModal calls TView.EndModal which has approximately the same result, causing ExecView to return Command to its caller. See: TView.EndModal procedure EventError(var Event: TEvent); virtual; If TGroup.Execute encounters an event that it cannot handle, it first calls TGroup.EventError, which attempts to call its owner's EventError method. You can override this function to intercept errors, if needed. function ExecView(P: PView): Word; Besides Init, Done and Insert, this is one of the most commonly used methods in a TGroup object. Call ExecView to display a modal view, such as a dialog box, on the screen. When a modal view is on the screen, all events are handled by the modal view. You can not, for instance, make menu selections or press short cut keys to activate non-dialog box functions. You must first terminate the modal dialog before resuming regular program operation. ExecView returns the command code that caused the view to complete. This might be cmOk, cmCancel or some other code that you have defined as part of the dialog definition. See: TGroup.Insert, TGroup.Delete, Chapter 12 function Execute: Word; virtual; Execute is the TGroup's main event processing loop, fetching events and then calling HandleEvent to process each event. The loop is terminated when a view calls EndModal. Execute returns the command code that caused the termination, and that is passed to ExecView for return to the caller. See: TGroup.EndModal, TGroup.HandleEvent function First: PView; Returns a pointer to the subview within the group that is currently "on top" or closest to the screen. If, for some reason, this is called when the group has no subviews, First returns nil. function FirstThat(Test: Pointer): PView; Test is a pointer to a far local function having one Pointer parameter and returning either True or False. This iterator function operates identically to the TCollection.FirstThat iterator, except that TGroup.FirstThat scans through the list of subviews within the group, in Z-order (see Chapter 13, "More Turbo Vision Features".) See: Chapter 14, "Collections", TCollection.FirstThat procedure ForEach(Action: Pointer); Action is a pointer to a far local procedure having one Pointer (or PView) parameter. ForEach scans through the subviews in Z-order, and for each subview it calls the Action procedure with a pointer to the subview. TGroup.ForEach operates similarly to TCollection.ForEach, except that you should normally call TGroup.Lock prior to calling TGroup.ForEach, and TGroup.Unlock after calling ForEach. This is particularly important when the ForEach iterator is used such that each subview is redrawn on the screen and TGroup is using a cache Buffer. Lock causes subsequent screen writes to go only to the cache Buffer, and Unlock then copies the entire Buffer to the screen. If you do not use Lock/Unlock, each of the subviews will repaint on the screen individually, causing a potentially annoying visual effect. See: Chapter 14, "Collections", TGroup.Buffer, TGroup.Lock, TGroup.Unlock procedure GetData(var Rec); virtual; Calls each subview's GetData procedure in reverse Z-order, copy each subview's data to the Rec variable. After calling each subview's GetData procedure, GetData adds the subview's DataSize value to Rec so that Rec now points past the data it just copied, making it ready to read the next subview's data. See: TView.DataSize, TGroup.SetData function GetHelpCtx: Word; virtual; Calls the currently Selected subview's GetHelpCtx to return the subview's context sensitive help index. If the subview doesn't have any context sensitive help, then GetHelpCtx returns the value of the help context for the entire TGroup. procedure GetSubViewPtr(var S: TStream; var P); This procedure is called from within TGroup.Load to read a subview pointer P from stream S. See: TGroup.Load, TGroup.PutSubViewPtr, TGroup.Store procedure HandleEvent(Event: TEvent); virtual; The TGroup.HandleEvent method passes most events onto the appropriate subview's HandleEvent method according to whether the event is a focused event, positional event or broadcast event. See Chapters 12 and 13 in the Borland Pascal Developer's Guide for a detailed description of event processing. constructor Init(var Bounds: TRect); TGroup's Init method calls TView.Init, and sets the TView.Options variable to ofSelectable and ofBuffered. The latter option enables cache buffering of the view's Draw output, if sufficient memory is available. TView's EventMask field is set to $FFFF which causes this view (or group) to respond to all classes of events. procedure Insert(P: PView); Use Insert to place a non-modal view into the group. For example, Insert is used to place windows onto the TDeskTop group object, as well as all of the individual controls within a dialog object. See: TGroup.Delete, TGroup.ExecView, TGroup.InsertBefore procedure InsertBefore(P, Target: PView); InsertBefore enables you to insert a view at any location within an existing group. The view P becomes inserted before (in Z-Order) the view specified by Target. If Target is nil, then P is inserted at the very back of the view, furthest from the screen. constructor Load(var S: TStream); Load creates a new TGroup object and reads each subview from stream S. procedure Lock; When using the cache Buffer to speed up screen output, setting Lock prevents the Buffer contents from being written to the screen. This way, multiple items or views can be written to the Buffer without causing annoying flicker, and then by calling Unlock, the entire Buffer is copied to the screen in one operation. Lock operates by incrementing a lock counter each time that it is called. Unlock decrements the counter and once the counter reaches zero, copies the Buffer to the screen. Important: Lock and Unlock must always be called in matched pairs to avoid leaving the Buffer in a locked state. If that happens, no output will be sent to the screen. See: GetBufMem, TGroup.ForEach, TGroup.Unlock procedure PutSubViewPtr(var S: TStream,; P: PView); This method is used in conjunction with the TGroup.Store method to write a subview pointer to stream S. See: TGroup.GetSubViewPtr, TGroup.Load, TGroup.Store procedure Redraw; Redraw forces an actual screen draw to occur, rather than merely copying from the cache Buffer. Otherwise, Redraw is the same as TGroup.Draw. procedure SelectNext(Forwards: Boolean); SelectNext complements the TView.Select method for making a view the focused view. If Forwards is True, then the next subview in Z-Order from the currently selected view becomes the focused view. If Forwards is False, then SelectNext moves to the previous subview. procedure SetData(var Rec); virtual; SetData is used in conjunction with GetData for accessing the data in the group. SetData calls each subview's SetData method, copying data from Rec to the subviews. procedure SetState(AState: Word; Enable: Boolean); virtual; TGroup.SetState sets or clears the bits in each subview's State field, to accomodate setting focused, active, exposed or dragging bits within State. See: TView.SetState, sfXXXX constants procedure Store(var S: TStream); Outputs all the TGroup and all of its subviews to stream S. procedure Unlock; Unlocks a previously locked cache Buffer and copies the contents of the Buffer to the screen. See: TGroup.Locked function Valid(Command: Word): Boolean; virtual; If all of the subview's Valid functions return True, then TGroup.Valid returns True, otherwise TGroup.Valid returns False. Since Valid is called when the Execute procedure is going to exit, a subview can retain control and prohbit the group from terminating by setting its Valid function to return False. See: TGroup.Execute, TView.Valid THistory object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView THistory Discussion THistory implements the history windows that display a down arrow icon on the right hand side of dialog input fields. Using THistory, a history of previously entered data is retained for future reference. Each time you enter a new value into an input field that is linked to a THistory object, the old value is stored away in a THistory list. Later, when you return to the input field, you can press down arrow or click on the down arrow icon to open a small list viewer showing your previous entries. This feature is especially useful in applications such as the Turbo Pascal IDE, where you tend to refer back to files you have opened previously. Hence, the open file dialog contains a history of the files you have recently opened. The THistory object is surprisingly easy to use considering the functions that is provides. All that needs to be done is to create the object using its Init constructor and insert it into the dialog. Data is then automatically copied from the TInputLine field to the THistory and back again, as appropriate. It is not recommended that you attempt to override any of the defined methods, except perhaps THistory.GetPalette. If you must override any of the methods, you are strongly encouraged to view the Turbo Vision source, available as a separate product from Borland. Example This short example demonstrates the use of the THistory object in a dialog, by modifying the TShell.ConfigureData procedure of TVSHELL8 (and example proggram shown in the Borland Pascal Developer's Guide), so that the EditorName field now contains a THistory list. The variable AnHistory is declared as a PHistory pointer. In the original procedure, EditorName is declared as a PView so it is recast to a PInputLine for passing to the THistory.Init constructor. To use THistory, define a Bounds rectangle for the THistory icon, typically immediately to the right of the input field, call the Init constructor, passing to it the location, a pointer to the linked input field, and a numeric value. The numeric value (from 0 to 255) uniquely defines this THistory list so that you could gain access to it from other fields. That means, more than one input field can reference the same history list by always referencing the same history list number. Alternatively, you can use different history identification numbers for each input field and have as many separate history lists as your application requires. { Editor name } Bounds.Assign (18, 2, 50, 3); EditorName := New( PInputLine, Init(Bounds, ConfigNameSize) ); Insert(EditorName); { Define the location for the THistory down arrow icon } Bounds.Assign(50, 2, 52, 3); AnHistory := New(PHistory, Init(Bounds, PInputLine(EditorName), 1 )); Insert(AnHistory); Bounds.Assign (2, 2, 15, 3); Insert( New (PLabel, Init(Bounds, '~E~ditor name:', EditorName ))); Fields HistoryId: Word; { Read only } Contains the history list number assigned as the third parameter to the Init constructor. Link: PInputLine; { Read only } Points to the input line field's TInputLine object that is associated with this history list. Methods procedure Draw; virtual; Displays the icon representing the THistory object, at the location determined by the Bounds parameter to Init. function GetPalette: PPalette; virtual; Returns a pointer to the CHistory color palette, which is intended for mapping onto the CDialog color palette. constructor Init(var Bounds: TRect; ALink: PInputLine; AHistoryId: Word);] Creates the THistory object, defining its location at Bounds, and linking to the ALink input field. AHistoryID is a number assigned by you to uniquely identify this particular history list. If you want, you can initialize other THistory objects that are linked to other input fields using the same AHistory number. When the input fields have the same AHistory number, they will all share the same history list. constructor Load(var S: TStream); Creates and reads a THistory object from stream S. procedure Store(var S: TStream); Writes this THistory object to stream S. THistoryViewer object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TListViewer THistoryViewer Discussion THistoryViewer manages the history list viewer that is displayed and owned by THistory. Normally, you will access the THistory object when you wish to use history lists in your applications, and will unlikely have any need to directly use THistoryViewer. Fields HistoryId: Word; { Read only } This contains the history identification number (see THistory) selecting which history list is to be displayed in the list box managed by THistoryViewer. Methods function GetPalette: PPalette; virtual; Returns a pointer to CHistoryViewer. function GetText (Item: Integer; MaxLen: Integer): String; virtual; GetText is the overridden TListViewer function, implemented here to return the specific history list string indexed by Item, such that the returned string is less than or equal to MaxLen in size. See TListViewer.GetText procedure HandleEvent(var Event: TEvent); virtual; HandleEvent processes mouse double clicks and the Enter key for selecting a file from the list box, and pressing the Esc key in order to cancel the list box. function HistoryWidth: Integer; Determines the longest string in the history list. constructor Init (var Bounds: TRect; AHScrollBar, AVScrollBar: PScrollBar; AHistoryId: Word); Calls TListViewer.Init to create a single column listbox with the specified scroll bars, and links it to the THistory specified by AHistory. Basically, when the THistory object is made active by selecting its icon or pressing the down arrow key, THistory creates a THistoryWindow object by calling InitHistoryWindow, and the THistoryWindow object, in turn, creates this TListViewer object to display the history list and manage the selections. THistoryWindow object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TGroup TWindow THistoryWindow Discussion When the THistory history list icon is selected, the THistory object creates a TWindow object in which to insert the THistoryViewer. Therefore,the THistoryWindow is primarily useful to the implementation of THistory and is not likely to be used directly by your programs. See the THistory object for an example use of history lists. Fields Viewer: PListViewer; Contains a pointer to the THistoryViewer list box that is created by this object. Methods function GetPalette: PPalette; virtual; Returns a pointer to CHistoryWindow, which is designed to map onto a dialog palette. function GetSelection: String; virtual; Determines which list box item in the THistoryViewer has the focus, and returns that specific string. constructor Init(var Bounds: TRect; HistoryId: Word); Creates the THistoryWindow by calling TWindow.Init with appropriate parameters, and then calls InitViewer. procedure InitViewer(HistoryId: Word); virtual; This is the routine that creates the THistoryViewer list box. TInputLine object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TInputLine Discussion Use TInputLine as an edit field in dialog boxes when you need to have the user type in information such as a filename or other text. TinputLine is a powerful single line editor, providing horizontal scrolling, line editing, text selection and block deletion. If the size of the input line field is less than the maximum permitted length of the input, then TInputLine will automatically provide left and right scrolling. Commonly Used Methods and Fields When TInputLine is inserted into a dialog, you will generally use only TInputLine.Init to create the input field and will not likely have use for any of the other methods or fields. The TInputLine will become active when it receives the focus and will automatically process its input via its HandleEvent method. TInputLine processes string input however you could override several of its methods in order to process other types of data. For instance, to handle numeric input, you would create a new TInputLine-derived object and override TInputLine.Valid to check for valid numeric entries, and modify GetData to convert the entered string into a numeric representation for processing. You would also need to modify SetData, and if you intend to use the object with streams, you'd need to create new versions of Load and Store. Example This example shows instantiating a TInputLine object having a maximum input length of 40 character, and places within the rectangle defined by (3, 3, 44, 4). The TInputLine object is then inserted into the dialog group, and a TLabel is attached as a prompt. (See also TLabel). At the completion of the dialog setup, the dialog will be displayed for editing with Control := DeskTop^.ExecView( Dialog ); Be sure to look at the examples in the TVSHELL program described in Chapters 11-12 of the Borland Pascal Developer's Guide: with Dialog^ do begin ... { Add the Rename from this filename item } Bounds.Assign (3, 3, 44, 4); OldFileName := New( PInputLine, Init(Bounds, 40) ); Insert(OldFileName); Bounds.Assign (2, 2, 44, 3); Insert( New (PLabel, Init(Bounds, 'Rename this file:', OldFileName ))); ... end; { with Dialog } Fields CurPos: Integer; { Read/Write } This field is used internally to keep track of the cursor's location within the input field. Data: PString; { Read/Write } Contains the pointer to the string that is being edited by the TInputLine. FirstPos: Integer; When horizontal scrolling is being used to display portions of the line that do not fit within the specified bounds of the TInputLine, FirstPos contains the index of the first byte that appears at the left of the field. MaxLen: Integer; MaxLen contains the maximum number of characters for the line length, as specified in the TInputLine.Init method. Methods destructor Done; virtual; Disposes of the memory used by TInputLine and disposes of the object. function DataSize: Word; virtual; GetData and SetData call DataSize to determine how much space needs to be reserved for the data returned by TInputLine. Normally this is equal to MaxLen + 1, which is the maximum number of characters that can be entered, plus the length byte. See: TInputLine.GetData, TInputLine.SetData procedure Draw; virtual; Draw takes care of displaying the input line text on the screen, adding arrows when horizontal scrolling is in effect. procedure GetData(var Rec); virtual; Copies the Data^ text string to Rec. See: TInputLine.DataSize, TInputLine.SetData function GetPalette: PPalette; virtual; Returns a pointer to the CInputLine color palette. If you desire to use a different color mapping, you should derive a new object from TInputLine and override GetPalette as per the instructions in Chapter 13, "More Turbo Vision Features", of the Borland Pascal Developer's Guide. procedure HandleEvent(var Event: TEvent); virtual; When the input line is the focused event, TInputLine.HandleEvent process the mouse and editing keystroke events, including entering and selecting text, horizontal scrolling and so on. constructor Init( var Bounds: TRect; AMaxLen: Integer); Use TInputLine.Init to create a new TInputLine object located at the position specified by Bounds (which specifies the length of the visible data entry field) and AMaxLen (which specifies the maximum length that the entered string can become). Bounds should describe a one line input field; if you specify a multi-line rectangle, TInputLine will not behave correctly. constructor Load(var S: TStream); Creates and reads a TInputLine object from stream S. procedure SelectAll(Enable: Boolean); If Enable is True, SelectAll block selects the entire data input line and resets all the internal pointers (such as CurPos cursor location) to the beginning of the string. If Enable is False, all selection is turned off. In both cases, the resultant input field is displayed on the screen by calling the inherited TView.DrawView. procedure SetData(var Rec); virtual; Copies the string value in Rec to Data^ and calls SelectAll. See: TInputLine.SelectAll procedure SetState(AState: Word; Enable: Boolean); virtual; Calls TView.SetState (See TView.SetState for more information) and performs additional processing for TInputLine. procedure Store(var S: TStream); Writes the TInputLine object to stream S. TItemList type ------------------------------------------------------------ Declaration: TItemList = array[0..MaxCollectionSize-1] of Pointer; Unit: Objects Purpose: This is an internal object type used for maintaining an array of pointers in TCollection objects. TLabel object ------------------------------------------------------------ Turbo Vision Hierarchy: TObject TView TStaticText TLabel Discussion TLabel objects are similar to TStaticText in that they are typically used to display a prompt line for dialog box controls such as an input field or a group of radio buttons. TLabel objects differ from TStaticText only in that they are explicitly linked to the control such that if you click with the mouse to select the TLabel object you actually select the attached control. Using this feature, you can use keyboard Alt-letter shortcut keys to reach input fields and other controls in a dialog box. Example { Create an input line field 40 spaces wide } Bounds.Assign(3, 3, 44, 4); OldFileName := New( PInputLine, Init( Bounds, 40) ); Insert( OldFileName ); { Create a prompt label for the input field and link to the OldFileName inputline field } Bounds.Assign( 2, 2, 44, 3); Insert( New( PLabel, Init( Bounds, 'Rename this file:', OldFileName ))); Fields Link : PView { Read Only } When a TLabel object is linked to a control, such as an input line, this field contains a pointer to that control. Light: Boolean; { Read Only } Methods procedure Draw; virtual; Override: NEVER Draws the TLabel object using the color palette pointed to by GetPalette. constructor Init (var Bounds: TRect; AText; String; ALink: PView); The Init constructor creates a new TLabel object with the size and location specified in Bounds, and assigns to the label the text specified in AText. The last parameter specifies a pointer to the control that is associated with this label. function GetPalette: PPalette; virtual; Override: As needed to change colors. Returns a pointer to the CLabel color palette. To change the colors of the TLabel object, override this function to return a pointer to a different color palette. The CLabel color palette is defined to properly map onto a dialog's color palette. If, for some reason, you are creating a label to be placed on top of some other type of object, you will almost certainly need to override this function. See: Chapter 13, "More Turbo Vision Features". procedure HandleEvent( var Event: TEvent ); virtual; Override: Never HandleEvent performs the usual event processing by calling TStaticText.HandleEvent to do most of the work. However, TLabel.HandleEvent intercepts certain mouse down and keyboard shortcut keys in order to select attached controls. constructor Load( var S: TStream ); Loads a TLabel object from stream S. See: Chapter 15, "Streams" procedure Store( var S: TStream ); Stores this view on to stream S. See: Chapter 15, "Streams" TListBox object ------------------------------------------------------------ Turbo Vision Hierarchy: TObject TView TListViewer TListBox Discussion Use TListBox to implement list boxes containing collections of strings. For example, a dialog box to open a file typically contains a list of filenames and subdirectories. To use TListBox you must create and initialize a collection of PStrings containing the items to appear in the list box, and then instantiate and initialize the list box. While TListBox is intended for use with string data, you can optionally override TListBox.GetText to process non-string data. TListBox is derived from TListViewer, so all of TListViewer's methods and fields are available to TListBox objects. See: TListViewer Commonly Used Features To use the TListBox, you'll call Init to create the box, and then NewList to initialize the list that is displayed. If you wish to display items other than simple strings, you'll need to override GetText. Example TListBox is nearly identical to TListViewer except that TListBox does not support the horizontal scroll bar. Further, TListBox manages the data list internally since its designed, by default to have GetText return a string. To use TListBox, you call TListBox.Init in a manner identical to TListViewer.Init (except that there is no horizontal scroll bar). Next, you call TListBox.NewList to pass a collection of strings to the TListBox for display. Fields List: PCollection; { Read only } Holds a pointer to the collection of items to display. Typically this would be a collection of PStrings, however, if you store other object types you will also need to override GetText. See: TListBox.GetText Methods constructor Init(var Bounds: TRect; ANumCols: Word; AScrollBar: PScrollBar ); Init creates the new TListBox object using the size provided in Bounds, the number of columns specified by ANumCols, and links it to the scroll bar passed as the AScrollBar parameter, or nil if there is no scroll bar. If you do add a scroll bar, you'll need to instantiate the TScroller object prior to calling Init, and you'll need to insert both the list box and the scroller into the owner's view. After calling Init, you should call NewList to assign the data collection to this list box. There is no Done destructor for TListBox since it is inherited from TListViewer. However, you do need to dispose of the contents of List. Oneway to do that is to call NewList(nil) which then disposes of the current List and sets List to nil. See: TListBox.NewList function DataSize : Word; virtual; Override: As needed. This method is used in conjunction with the TListBox GetData and SetData methods for writing and retrieving TListBox dialog data. The default definition of DataSize returns SizeOf(Pointer) + SizeOf(Word). See: GetData, SetData, "The List Box Viewer", in Chapter 12, "Turbo Vision Dialogs and Events", in the Borland Pascal Developer's Guide. procedure GetData(var Rec); virtual; Override: As needed. GetData copies the List and Focused (from TListViewer) fields to Rec. See: DataSize, SetData, Chapter 12 function GetText(Item: Integer; MaxLen: Integer):String; virtual; GetText is called by the inherited TListViewer.Draw method to obtain the string to draw on the display. The standard implementation retrieves the Item'th entry in the List^ collection as, PString(List^.At(Item))^ Its possible to store non-string items in a TListBox type, but to do so you will need to override GetText. constructor Load( var S: TStream ); Creates and reads a TListBox object from stream S, including the data collection linked to the list box. See: Store, Chapter 16, "Collections". procedure NewList(AList: PCollection); virtual; After calling Init to create a new TListBox objecct, you need to link a data collection to the list box. You do this by passing the collection as a parameter to the NewList method, which sets List to point to the collection, and sets the list box Range to the collection's Count field and draw's the list box view by calling DrawView. If List is not nil when NewList is called, NewList disposes of the previous collection before setting List to the new collection. procedure SetData(var Rec); virtual; Copies values from Rec into the List and Focused fields and then calls NewList(List) in order to reset and display the new list. See: DataSize, GetData procedure Store(var S: TStream); Stores the contents of the list box object, including the data collection that is pointed to by List, to the stream S. See: Load, Chapter 15, "Streams". TListViewer object ------------------------------------------------------------ Turbo Vision Hierarchy: TObject TView TListViewer TListBox Discussion Use the TListViewer object type for creating various types of list box viewers. List boxes typically contain lists of information, such as filenames, through which you can scroll and select the desired item. Usingthe TListViewer object, you can create both vertical and horizontal scroll bars. Horizontal scroll bars might be used when creating a simple file viewer for viewing text wider than the list box. Commonly Used Features Call TListViewer.Init to create the list viewer. While the TListViewer manages the display of the list box it is up to you to provide the data structures that store the data shown within the box. You do this by deriving a new TListViewer object type and overriding the GetText function, which returns a string containing one line of text. GetText has two paremeters, an item index and a maximum length value. Its up to GetText to retrieve the Item'th entry in the list and format it into a string of no longer than the specified maximum length. If you insert the TListViewer into any other TGroup besides TDialog, you will almost certainly need to override GetPalette so that the color mapping works correctly. Example { Define TDirList, derived from TListViewer } PDirViewer = ^TDirList; TDirList = object( TListViewer ); function GetText( Item: Integer; MaxLen: Integer):String; virtual; function GetPalette: PPalette; virtual; procedure HandleEvent( var Event: TEvent); virtual end; ... { Instantiate a scroll bar object } ListScroller := New( PScrollerBar, Init( BarBounds )); { Instantiate a list viewer and link it to the scroll bar } ListViewer := New( PDirViewer, Init( Bounds, 1, Nil, ListScroller )); { Insert both objects into the controlling group view } Insert(ListScroller); Insert(ListViewer); Fields HScrollBar: PScrollBar; { Read only } Holds the pointer to the horizontal scroll bar object attached to this list viewer, or is nil if there is no horizontal scroll bar. VScrollBar: PScrollBar; { Read only } Holds the pointer to the vertical scroll bar object attached to this list viewer, or is nil if there is no vertical scroll bar. NumCols : Integer { Read only } This stores the number of columns specified for the list viewer and is initialized with the Init constructor. TopItem: Integer; { Read/Write } TopItem specifies the item appearing at the top of the list box viewer. TopItem varies from 0 to Range-1. Focused: Integer; { Read only } Focused specifies the item number of the focused or selected item and ranges from 0 to Range-1. Keyboard navigation keys, scroll bar movements and mouse clicks and drags all cause the focused item to be updated to point to the current location of the list box cursor. Range: Integer; { Read only } Holds the total number of items in the list. See: TListViewer.SetRange Methods constructor Init( var Bounds: TRect; ANumCols: Integer; AHScrollBar, AVScrollBar: PScrollBar ); Creates a TListViewer object with the size specified by Bounds and the number of columns specified by ANumCols. If you wish to have scroll bars, create the TScroller objects before calling Init, and then pass pointers to those scroll bars to the AHScrollBar and AVScrollBar parameters, for horizontal or vertical scroll bars, respectively, to link them to the list box. Use a value of nil if one or both scroll bars is not defined for this list box. procedure ChangeBounds( var Bounds : TRect ); virtual; Call ChangeBounds to resize the list box viewer to the size specified by the Bounds parameter. procedure Draw; virtual; Override: Never. Draws the list viewer object by calling GetText for each of the objects that could be shown on the screen. procedure FocusItem ( Item : Integer ); virtual; Override: Never. Use FocusItem to make a specific Item in the list box become the focused item. This method automatically causes the scroll bar to be adjusted accordingly. function GetPalette: PPalette; virtual; Override: As needed. Returns a pointer to the color palette for TListViewer objects. The default palette, CListViewer is intended to map directly into a CDialog palette. If you insert the TListViewer object into a view other than the TDialog, you must override the GetPalette function. See: CListViewer, CDialog, Chapter 19, More on Turbo Vision function GetText (Item : Integer; MaxLen: Integer): String; virtual; Override: Always You must implement your own GetText method to return a string representing the data that should appear in the list box at the Item'th position. Your data can be stored in whatever internal representation is appropriate for your application. This might include a collection, an array of records, a linked list, or a simple string array, as shown in this example code: { Fetch data item from internal data structure } StrBuffer := MyData[Item]; { Truncate data string if too long } if Length(StrBuffer) > MaxLen then StrBuffer[0] := Chr( MaxLen); GetText := StrBuffer; function IsSelected (Item: Integer): Boolean; virtual; Use IsSelected to check if a specific item is also the focused item. IsSelected returns True if the entry specified by Item is currently selected, False otherwise. procedure HandleEvent( var Event: TEvent ); virtual; Override: As needed. Performs event processing for the TListViewer, including mouse navigation and clicking in the list box to select an item, the use of the space bar to perform keyboard selection, and all keyboard navigation keys (up and down arrow, PgUp, PgDn, Home, End, etc). Navigation events that move through the list automatically cause the associated scroll bars to update themselves. See: See Chapter 11, "Turbo Vision Tutorial" in the Borland Pascal Developer's Guide for an example. constructor Load( var S : TStream ); Loads a TListViewer object from stream S, and also loads any associated scrollbars. procedure SelectItem( Item: Integer ); virtual; This is intended to be used and overridden by descendants, to make the Item'th entry in the list selected. This routine is essentially equivalent to TListViewer.FocusItem. procedure SetRange( ARange : Integer ); Sets the Range field to ARange or the number of items in the list and automatically adjusts the scroll bars, as needed. If the new range would put the current Focused item value out of range, then Focused is reset to zero. See: TListViewer.Range procedure SetState( AState: Word; Enable: Boolean); virtual; Basically, this calls TView.SetState to set or reset the sfOptions bits in the TView.State variable. See: sfOptions, TView.State procedure Store( var S: TStream); Stores this TListViewer object onto stream S, and stores any associated scroll bars. TMenuBar object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TMenuView TMenuBar TMenuBox Discussion The TMenuBar object manages the menu bar across the top of the application screen. Most applications merely call the TMenuBar.Init method with a series of nested NewMenu, NewSubMenu, NewLine and NewItem function calls to create an entire list of pull down menu items. It's unlikely that you will use any other TMenuBar methods. Example MenuBar := New(PMenuBar, Init(Bounds, NewMenu( NewSubMenu('~R~un', hcNoContext, NewMenu( NewItem('~R~un', '', 0, cmRunProgram, hcNoContext, NewItem('~E~dit', 'Alt-E', kbAltE, cmEdit, hcNoContext, NewItem('~V~iew', 'Alt-V', kbAltV, cmView, hcNoContext, NewItem('~U~se DOS','Alt-D', kbAltS, cmUseDOS, hcNoContext, NewItem('E~x~it', 'Alt-X', kbAltX, cmQuit, hcNoContext, nil)))))), ... Fields None Methods procedure Draw; virtual; Draws the menu bar on the display and highlights the selected item. procedure GetItemRect(Item: PMenuItem; var R: TRect); virtual; This internal method is used to determine if a mouse click occurred on a particular menu item. constructor Init(var Bounds: TRect; AMenu: PMenu); Creates an initializes the menu bar. See the example above, and also look at NewMenu, NewSubMenu, NewItem, and NewLine functions. TMenuBox object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TMenuView TMenuBar TMenuBox Discussion The TMenuBox object implements the menu box that drops down from the menu bar. TMenuBox displays the contents of the pulldown menu and processes the keyboard and mouse inputs to make a selection. Commonly Used Features Most applications will never reference the TMenuBox object directly. Instead, pulldown menus are created with the NewSubMenu function nested within the TMenuBar.Init constructor. However, it is possible to use the TMenuBox as a standalone pulldown menu providing a group of items from which to select. For instance, sometimes its not practical to display every option on one of the standard pulldown menus. Instead, consider adding a submenu that gets displayed only when one of the standard pulldown options is selected or perhaps as the result of a button press in a dialog box. The example code below shows how to create and execute a standalone pulldown menu, here emulating the Watches submenu from the Turbo Pascal IDE's Debug menu. Example AMenuBox is a PView-type variable. When passed to DeskTop^.ExecView(), the standalone menu is displayed at the location specified by Bounds. Oncea selection is made from the menu, Command is set to the cmXXXX constant corresponding the selected item. Begin Bounds.Assign(10,5, 40,12 ); AMenuBox := New(PMenuBox, Init( Bounds, NewMenu( NewItem('~A~dd Watch', 'Ctrl-F7', kbCtrlF7, cmAddWatch, hcNoContext, NewItem('~D~elete Watch', '', 0, cmDelWatch, hcNoContext, NewItem('~E~dit Watch...', '', 0, cmEditWatch, hcNoContext, NewItem('~R~emove all Watches', '', 0, cmRemWatch, hcNoContext, nil))))),nil)); Command := DeskTop^.ExecView(AMenuBox); End; Fields None Methods procedure Draw; virtual; Displays the menu box and contents. procedure GetItemRec(Item: PMenuItem, var R: TRect); virtual; GetItemRec is used internally determine if the particular Item was selected by a mouse click. constructor Init(var Bounds: TRect; AMenu: PMenu; AParentMenu: PMenuView ); Use Init to create a new TMenuBox object, where Bounds describes both the size and location of the menu box, and AMenu is normally constructed from a series of nest calls to NewMenu, NewItem and so on. For standard pulldown menus, AParentMenu points to the menu bar, but for standalone menu boxes, this parameter can be set to nil. TMenu type ------------------------------------------------------------ Declaration: TMenu = record Items : PMenuItem; Default : PMenuItem; end; Unit: Menus Purpose: TMenu is used for building up menu bar and pulldown menu records and is created by the NewMenu function. TMenu records are unlikely to be used except for creation and maintanance of the menu bar object. TMenuItem type ------------------------------------------------------------ Declaration: { TMENUITM.PAS } PMenuItem = ^TMenuItem; TMenuItem = record Next: PMenuItem; Name: PString; Command: Word; Disabled: Boolean; KeyCode: Word; HelpCtx: Word; case Integer of 0: (Param: PString); 1: (SubMenu: PMenu); end; Unit: Menus Purpose: TMenuItem records are created using the NewItem, NewLine and NewSubMenu functions, and are used to store a list of TMenuItem records describing each menu item on a pulldown menu. The various fields store the values passed to the NewItem or NewSubMenu functions as follows: Next points to the next item in the menu structure, or is nil if it is the last item in the menu. Name is a PString pointer to the item name, or nil in the case of a NewLine. Command contains the cmXXXX constant value used as an evCommand message to your view's HandleEvent procedure when the item is selected from the menu. Disabled is False normally, but set to True if the item has been disabled. KeyCode contains the hot key's scan code, if any, or zero if there is not hot key defined for this item. HelpCtx contains the help constant identifier for use in an on-line help system. The last variant field contains either Param, a pointer to the text displayed next to a menu item, normally the hot key prompt, such as 'Alt-A' (or nil if there is no parameter string), or SubMenu as a pointer to the submenu structure. See: Chapter 11, "Turbo Vision Tutorial", NewItem, NewLine, NewSubMenu, TMenu. TMenuStr type ------------------------------------------------------------ Declaration: TMenuStr = String[31]; Unit: Menus Purpose: TMenuStr defines the string type used for storing menu item names, and limits menu names and item names to a maximum of 31 characters in length. See: NewItem, NewSubMenu TMenuView object ------------------------------------------------------------ Turbo Vision Hierarchy TMenuView TView TMenuView TMenuBar TMenuBox Discussion TMenuView implements much of the functionality for TMenuBar and TMenuBox and is not used directly. Refer to TMenuBar and TMenuBox for examples of the menu facilities. Most of the methods shown below are used internally by the derived object types and rarely used in a typical application. Fields ParentMenu: PMenuView; { Read only } Points to the TMenuView-type object that owns this menu object. Menu: PMenu; { Read only } Points to a TMenu-type record, which in turn points to a linked list of TMenuItem records defining each of the menu items that appear on the menu. See: TMenu type, TMenuItem type Current: PMenuItem; { Read only } Keeps track of which menu item is the currently selected one. Methods function Execute: Word; virtual; Override: Never ExecView calls Execute to process the modal nature of the pulldown menu. Execute returns cmXXXX constant that was defined for the menu selection, or 0 if the Esc key was pressed and nor selection was made. function FindItem(Ch: Char); PMenuItem; FindItem scans through the menu box structure looking for a menu item that has Ch has its shortcut key, and returns a pointer to that menu item, or nil if not matches were found. procedure GetItemRect(Item: PMenuItem; var R: TRect); virtual; This internal method helps the menu code determine which menu item on which a mouse click occurred. function GetHelpCtx: Word; virtual; Returns the value of the help context constant for the current menu item. If the menu item's help context is hcNoContext, then GetHelpCtx checks the owner of the menu and return's its help context. function GetPalette: PPalette; virtual; Returns a pointer to CMenuView, the default color palette for menus. See: CMenuView procedure HandleEvent(var Event: TEvent); virtual; Override: Never. Process all events for the menu object. function HotKey(KeyCode: Word): PMenuItem; Scans through the menu structure looking for the menu item that has the hot key specified by KeyCode defined, and if found, returns a pointer to that menu item. Otherwise, if KeyCode is not found, then it returns nil. constructor Init(var Bounds: TRect); Creates a view having the indicated Bounds. TMenuView.Init should only be called by TMenuBar and TMenuBox. constructor Load(var S: TStream); Creates and loads a TMenuView object from stream S. procedure Store(var S: TStream); Writes the TMenuView object to stream S. TObject object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TCollection TStream TStringList TStrListMaker TResourceFile Discussion Nearly all objects used in Turbo Vision are defined from this root object type, and all objects written to streams must be descended from TObject. Fields None Methods destructor Done; Disposes a dynamically allocated object. procedure Free; Descendants of TObject actually call TObject.Free to dispose of the dynamically allocated object. constructor Init; TObject.Init is called from all descended object's Init constructors. Descendant's should always call their parent's Init method prior to performing their own initialization since TObject carefully zeroes all allocated fields as part of its initialization. TPalette type ------------------------------------------------------------ Declaration: TPalette = String; Unit: Views Purpose: Defines the data type used for storing color palettes. Since all color palettes are equivalent to strings, you can use, if you wish, all of the various string manipulation functions, including indexing, Copy, Delete, Insert and so on. See: Chapter 13, "More Turbo Vision Features" TParamText object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TStaticText TLabel TParamText Discussion TParamText is essentially equivalent to TStaticText, for displaying text strings in dialog boxes except that TParamText provides enhanced flexibility in the formatting of the text strings. The string parameter passed to TParamText.Init may contain embedded formatting information and is passed directly to the FormatStr procedure. See: FormatStr, TStaticText, TLabel, TDialog Commonly Used Features If you use this object type, you will probably create the object with the Init constructor and then insert it into a dialog and are unlikely to directly access the other methods. You will need to directly assign a value to the ParamList pointer as shown in the example. Example This example of TParamText shows how a variable FileName might be inserted into a TParamText derived object, AParam. Each time that the dialog is displayed, or particularly if the dialog is normally stored in a resource file, the FileName parameter can be automatically inserted into the TParamText message prompt by changing Parameters.AParamStr to a new value. var AParam : PParamText; Parameters : record AParamStr : PString; end; ... { Set up the contents of the Delete dialog } with Dialog^ do begin ... { Add the Delete Okay? } Bounds.Assign ( 8, 2, 45, 3 ); AParam := New (PParamText, Init( Bounds, 'Okay to Delete %s', 1 )); Parameters.AParamStr := NewStr(FileName); AParam^.ParamList := @Parameters; Insert( AParam ); end; { with } Control := DeskTop^.ExecView (Dialog); Fields ParamCount: Integer; Specifies the number of parameters in the ParamList^ parameter array or record. ParamList: Pointer; Points to the parameter array or parameter record that specifies the data values to be inserted into the Text string (which is inherited from TStaticText). See FormatStr for a complete description of string formatting. Methods function DataSize: Word; virtual; Used in conjunction with GetData and SetData, DataSize returns the size in bytes of the data storage used by a TParamCount object. procedure GetText(var S: String); virtual; Calls FormatStr( S, Text^, ParamList^ ) to format and merge the parameters in TParamText.ParamList^ with the TParamText.Text^ string (Text is a field inherited from TStaticText to hold the contents of this item's text) and produces the resultant output string S. See: FormatStr, TParamText.ParamList, TParamText.Text, TStaticText.Text constructor Init(var Bounds: TRect; AText: String; AParamCount: Integer); TParamText.Init calls TStaticText.Init to create the object, and then stores AParamCount into TParamText.ParamCount. AText is the text to be used for the message prompt. You must separately assign the parameter array or record to ParamList. constructor Load(var S: TStream); Creates and reads a TParamText object from stream S. procedure SetData(var Rec); virtual; Copies the number of bytes specified by DataSize into Rec. procedure Store(var S: TStream); Writes the TParamText object to stream S. TPoint object ------------------------------------------------------------ Turbo Vision Hierarchy Fields X: Integer; Y: Integer; Defines a point (X,Y) on the screen. TProgram object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TGroup TProgram TApplication Discussion TProgram contains most of the functionality present in TApplication. Usually you will derive your application directly from TApplication but it is possible to derive it from TProgram instead. All Turbo Vision programs must be derived from either TApplication (preferred) or TProgram. Commonly Used Features The following are the frequently used methods of TProgram: Init, Done, HandleEvent, Idle, InitMenuBar, InitStatusLine, OutOfMemory, Run, SetScreenMode Example See TVSHELL8 in the Borland Pascal Developer's Guide for a complete example of a finished application using the frequently used methods of TProgram (except Idle). Fields None Methods destructor Done; TProgram.Done disposes of all the application related objects, including StatusLine, MenuBar and DeskTop and essentially terminates the Turbo Vision program. procedure GetEvent(var Event: TEvent); virtual; This is the application's event processing loop. GetEvent checks for mouse and keyboard events and since TProgram owns all of the application's views, GetEvent sends the event record to the appropriate view for processing. If no events occurred, then GetEvent calls TProgram.Idle (see TProgram.Idle). function GetPalette: PPalette; virtual; Returns a pointer to the default color palette for the application. Since TProgram.GetPalette points to the application level palette, of which there are 3, CColor, CBlackWhite and CMonochrome, GetPalette checks the AppPalette variable to determine which application palette is the currently active palette. See: appPalette, apXXXX constants, CBlackWhite, CColor, CMonochrome procedure HandleEvent(var Event: TEvent); virtual; Override: Always, to implement an application's functions. Every application will override HandleEvent (but don't forget to call TProgram.HandleEvent first), to process the cmXXXX commands returned by the various menu selections and short cut keys. See: Chapter 11, "Turbo Vision Tutorial", and TVSHELL8 for examples. procedure Idle; virtual; You can have your Turbo Vision application perform background tasks during idle periods in the program's execution. To make use of idle time, override TProgram.Idle to perform your background tasks (always remember to call TProgram.Idle as the first statement within your overwritten Idle procedure). TProgram.Idle should only perform operations that can be done quickly as Idle is called from within TProgram's GetEvent loop. This means that if TProgram.Idle takes a lengthy time to complete operation, your program's execution appear to be slow down to unacceptable levels. constructor Init; Initialize's Turbo Vision support for an application, including the video screen modes, and calls InitDeskTop, InitStatusLine and InitMenuBar. You must override the last three methods to provide your application's status line and menu bar definitions. procedure InitDeskTop; virtual; Initializes an application's TDeskTop object and sets the global DeskTop pointer to point to this object. See the listing given in TBackground for an example of how this method can be overriden to create a TDeskTop object other than the default desktop. procedure InitMenuBar; virtual; You should always override InitMenuBar so that it creates a new menu bar and associated pulldown menus and setsMenuBar to point to the new menu structure. See Chapter 11. procedure InitScreen; virtual; This internal routine is called by TProgram.SetScreenMode to initialize all of the Turbo Vision screen mode dependant values: ShadowSize, AppPalette and ShowMarker. procedure InitStatusLine; virtual; You should always override InitStatusLine so that it creates a new statusline and set the global variable StatusLine to point to the new status line structure. See Chapter 11. procedure OutOfMemory; virtual; Whenever TProgram.ValidView finds that LowMemory is True, meaning that the low memory buffer area has been entered, TProgram.ValidView calls OutOfMemory. You should override this procedure to display an error or warning message to the user with information about the low memory problem. See: LowMemory, TProgram.ValidView procedure PutEvent(var Event: TEvent); virtual; PutEvent inserts Event into the pending Event queue so that the next call to GetEvent returns Event. procedure Run; virtual; Calls the inherited TGroup.Execute method, which is the main event loop of the application. procedure SetScreenMode( Mode: Word ); When you need to switch between the 3 application level color palettes, CColor, CBlackWhite or CMonochrome, or switch between 25- and 43/50-line screen modes, call TProgram.SetScreenMode, setting the Mode parameter with the values smCO80, smBW80 or smMono, OR'd, as needed, with smFont8x8. See the procedure SetVideoMode for complete details; normally you will call TProgram.SetScreenMode rather than SetVideoMode. function TProgram.ValidView(P: PView): PView; ValidView is used to determine if a newly constructed view was created appropriately. It does this by checking the LowMemory flag and if True, automatically calls TProgram.OutOfMemory. ValidView also insures that P is not nil, and if any errors are founds, ValidView returns a nil pointer. You can use ValidView to check the instantiation of new views directly as they are inserted into a group. DeskTop^.Insert(ValidView( New( PStaticText, Init( ... ) ) ) ); This results in an automatic error handling sequence, calling OutOfMemory or what not, as Insert will ignore a nil pointer and will not insert the failed view. See: TProgram.OutOfMemory, TView.Valid, TGroup.Valid, Chapter 13, "More Turbo Vision Features". TRadioButtons object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TView TCluster TRadioButtons TCheckBoxes Discussion Use TRadioButtons to implement groups of radio buttons in dialog boxes. Chapter 11 in the Borland Pascal Developer's Guide contains a tutorial on the creation and use of TRadioButtons objects. See TCheckBoxes, TDialogs Commonly Used Features Most applications will use the inherited TCluster.Init method to initialize a radio button group, and then Insert the group into the dialog. There is little need to use any of the other available methods directly. Example This example shows creating and inserting a radio button into an owner, which is normally a TDialog object, and linking it to a TLabel prompt line: Bounds.Assign(3, 2, 20, 4); VideoOptions := New (PRadioButtons, Init (Bounds, NewSItem('~2~5 lines', NewSItem('~4~3/50 lines', nil)) )); Insert(VideoOptions); Bounds.Assign( 3, 1, 20, 2); Insert( New( PLabel, Init( Bounds, 'Screen size', VideoOptions))); Fields None Methods procedure Draw; virtual; Displays each radio button, including the "( )" selection fields. function Mark(Item: Integer): Boolean; virtual; Use Mark to determine if a specific radio button, specified by Item, is currently pressed. procedure MovedTo(Item: Integer); virtual; MovedTo is identical to Press and sets the Item'th radio button to "pressed". procedure Press(Item: Integer); virtual; Makes the Item'th radio button the currently pressed radio button. procedure SetData(var Rec); virtual; Copies the Value and Sel fields from Rec, and then sets the selected item indicated by Sel to the "pressed" state. TRect object ------------------------------------------------------------ Turbo Vision Hierarchy TRect is a standalone object. Discussion TRect primarly defines two coordinates, A and B, which are the upper left and the lower right corners of a rectangle. TRect parameters are used throughout Turbo Vision to specify the screen location and size of windows, dialog boxes and entry fields. Commonly Used Features The mostly commonly used method is Assign, used to initialize the coordinate values, but several utility methods also enable quick changes in the values of the coordinate fields and making copies of the TRect object. Example var Bounds: TRect; ARectangle : TRect; ... { Initialize to the coordinates (0,0) and (80,2) } Bounds.Assign(0, 0, 80, 2); ... { Copy the contents of Bounds to ARectangle } ARectangle.Copy( Bounds ); Fields A: TPoint; A TPoint defining the upper left corner of a rectangle. B: TPoint; A TPoint defining the lower right corner of a rectangle. Methods procedure Assign( XA, YA, XB, YB: Integer); Sets A.X := XA, A.Y := YA, B.X := XB and B.Y := YB. procedure Copy(R: TRect); Sets the A and B fields to the values in R. procedure Move(ADX, ADY: Integer); Adds ADX to the X values and ADY to the Y values of A and B. Sets A.X := A.X + ADX, B.X := B.X + ADX and sets A.Y := A.Y + ADY, B.Y := B.Y + ADY. procedure Grow(ADX, ADY: Integer); Adjusts A and B as follows: A.X := A.X - ADX; B.X := B.X + ADX; A.Y := A.Y- ADY; B.Y := B.Y + ADY; procedure Intersect(R: TRect); Determines the area that this rectangle overlaps with the rectangle specified by R, and sets A and B to the intersection of the two rectangles. procedure Union(R: TRect); Creates a new rectangle that encompasses A and B and the rectangle R. function Contains(P: TPoint): Boolean; Returns True if P lies within the rectangle specified by A and B. function Equals(R: TRect): Boolean; Compares A and B to R, and returns True if they are equal, and False if they are not. function Empty: Boolean; If A and B are equal, then A and B describe a rectangle containing no spaces. Empty returns True if A = B. TResourceFile object ------------------------------------------------------------ Turbo Vision Hierarchy TObject TResourceFile Discussion TResourceFile is a special purpose random access TStream that let's you find records by a key string instead of a record number. Using TResourceFile, you can implement simple data base retrievals, as well as store Turbo Vision components. See Chapter 16, "Resources" in the Borland Pascal Developer's Guide for a complete discussion and tutorial on the use of TResourceFile objects. Commonly Used Features In addition to Init, Put, Get and Done are the most frequently used methods of the TResourceFile object. Fields Stream: PStream; Points to the stream used by this TResourceFile object. Modified: Boolean; If the file has been modified, then this flag is set to True. The TResourceFile.Flush procedure checks this flag to determine if it should update the resourc file. Methods function Count: Integer; Computes and returns the number of items or resources stored in the file. procedure Delete(Key: String); Removes the key from the index and marks the space it previously occuppied as being deleted. See TResourceFile.SwitchTo for a method to reclaim the now unused space. destructor Done; virtual; Calls TResourceFile.Flush and disposes of the index collection and resource stream file. procedure Flush; Checks the Modified flag, and if True, updates the resource stream file, and then resets Modified to False. function Get(Key: String); PObject; Uses Key as an index into the resource and returns a pointer to the object that it references, or nil if the Key is not in the file. See TResourceFile.Put constructor Init( AStream: PStream ); TResourceFile.Init is called after opening a stream. The opened stream is passed as a parameter to Init and becomes the stream that holds the resource file. See Chapter 16, "Resources". function KeyAt(I: Integer): String; Use KeyAt to scan through the entire resource file. I is an index to each resource in the file, numbered 0 to TResourceFile.Count minus 1. KeyAt returns the string corresponding to the key value at the I'th index position. procedure Put(Item: PObject; Key: String); Stores the object pointed to by Item into the resource file, using the specified Key. See TResourceFile.Get function SwitchTo(AStream: PStream; Pack: Boolean): PStream; Use SwitchTo to copy the current resource file to another stream specified by AStream. If Pack is True, SwitchTo will not copy objects marked as deleted, thereby compressing the resulting resource file. See: TResourceFile.Delete