+This chapter describes the CRT unit for Free Pascal, both under dos +linux and Windows. The unit was first written for dos by Florian klaempfl. +The unit was ported to linux by Mark May and enhanced by Michael Van Canneyt +and Peter Vreman. It works on the linux console, and in xterm and rxvt windows +under X-Windows. The functionality for both is the same, except that under +linux the use of an early implementation (versions 0.9.1 and earlier of the +compiler) the crt unit automatically cleared the screen at program startup. +
++There are some caveats when using the CRT unit: +
++LowVideo switches the output to non-highlighted text. (It clears the high +intensity bit of the video attribute) +
++For an example, see +
++NormVideo switches the output to the defaults, read at startup. (The +defaults are read from the cursor position at startup) +
++For an example, see +
++ReadKey reads 1 key from the keyboard buffer, and returns this. +If an extended or function key has been pressed, then the zero ASCII code is +returned. You can then read the scan code of the key with a second ReadKey +call. +
++Key mappings under Linux can cause the wrong key to be +reported by ReadKey, so caution is needed when using +ReadKey. +
++TextMode sets the textmode of the screen (i.e. the number of lines +and columns of the screen). The lower byte is use to set the VGA text mode. +
++This procedure is only implemented on dos. +
+
+The
+The unit was first written for dos by Florian Klaempfl. It was ported to +linux by Mark May and enhanced by Michael Van Canneyt. +The Amiga version was ported by Nils Sjoholm. +
++Under non-DOS systems, some of the functionality is lost, as it is either impossible +or meaningless to implement it. Other than that, the functionality for all +operating systems is the same. +
++The File Attribute constants are used in , + to +determine what type of special file to search for in addition to normal files. +These flags are also used in the and routines to +set and retrieve attributes of files. For their definitions consult +. +
+| Constant | Description | Value | +
| readonly | $01 | |
| hidden | $02 | |
| sysfile | | $04 |
| volumeid | | $08 |
| directory | | $10 |
| archive | | $20 |
| anyfile | | $3F |
+These constants are used in the Mode field of the TextRec +record. Gives information on the filemode of the text I/O. For their +definitions consult the following table: +
+| Constant | Description | Value | +
| fmclosed | $D7B0 | |
| fminput | $D7B1 | |
| fmoutput | $D7B2 | |
| fminout | $D7B3 |
+Routines to handle files on disk. +
+| Name | Description | +
| Expand filename to full path | |
| Close finfirst/findnext session | |
| Start find of file | |
| Find next file | |
| Search for file in a path | |
| Split filename in parts | |
| Return file attributes | |
| Return file time | |
| Convert short filename to long filename (DOS only) | |
| Convert long filename to short filename (DOS only) | |
| Set file attributes | |
| Set file time |
+Routines to handle disk information. +
+| Name | Description | +
| Add disk to list of disks (UNIX only) | |
| Return size of free disk space | |
| Return total disk size |
+Functions to handle process information and starting new processes. +
+| Name | Description | +
| Exit code of last executed program | |
| Return number of environment variables | |
| Return environment string pair | |
| Execute program | |
| Return specified environment string |
+Functions for retrieving and setting general system information such as date +and time. +
+| Name | Description | +
| Get OS version | |
| Get setting of control-break handling flag | |
| Get system date | |
| Get interrupt vector status | |
| Get system time | |
| Get verify flag | |
| Execute an interrupt | |
| Keep process in memory and exit | |
| Execute MS-dos function call | |
| Pack time for file time | |
| Set control-break handling flag | |
| Set system date | |
| Set interrupt vectors | |
| Set system time | |
| Set verify flag | |
| Swap interrupt vectors | |
| Unpack file time |
+SearchRec is filled by the call and can be +used in subsequent calls to search for files. The +structure of this record depends on the platform. Only the following +fields are present on all platforms: +
++TextRec describes the internal working of a Text file. +
++Remark that this is not binary compatible with the Turbo Pascal definition +of TextRec, since the sizes of the different fields are different. +
++The DosError variable is used by the procedures in the dos unit to +report errors. It can have the following values : +
+| Value | Meaning | +
| 2 | File not found. |
| 3 | path not found. |
| 5 | Access denied. |
| 6 | Invalid handle. |
| 8 | Not enough memory. |
| 10 | Invalid environment. |
| 11 | Invalid format. |
| 18 | No more files. |
+Other values are possible, but are not documented. +
++AddDisk adds a filename S to the internal list of disks. It is +implemented for systems which do not use DOS type drive letters. + This list is used to determine which disks to use in the +and calls. +The and functions need a file on the +specified drive, since this is required for the statfs system call. +The names are added sequentially. The dos +initialization code presets the first three disks to: +
++The first call to AddDisk will therefore add a name for the second +harddisk, The second call for the third drive, and so on until 23 drives +have been added (corresponding to drives 'D:' to 'Z:') +
++DiskFree returns the number of free bytes on a disk. The parameter +Drive indicates which disk should be checked. This parameter is 1 for +floppy a:, 2 for floppy b:, etc. A value of 0 returns the free +space on the current drive. +
++There is room for 1-26 drives. You can add a drive with the + procedure. +These settings can be coded in dos.pp, in the initialization part. +
++DiskSize returns the total size (in bytes) of a disk. The parameter +Drive indicates which disk should be checked. This parameter is 1 for +floppy a:, 2 for floppy b:, etc. A value of 0 returns the size +of the current drive. +
++There is room for 1-26 drives. You can add a drive with the + procedure. +These settings can be coded in dos.pp, in the initialization part. +
++For an example, see . +
++DosVersion returns the operating system or kernel version. The +low byte contains the major version number, while the high byte +contains the minor version number. +
++Exec executes the program in Path, with the options given by +ComLine. +
++After the program has terminated, the procedure returns. The Exit value of +the program can be consulted with the DosExitCode function. +
++For an example, see +
++FExpand takes its argument and expands it to a complete filename, i.e. +a filename starting from the root directory of the current drive, prepended +with the drive-letter or volume name (when supported). +
++FindClose frees any resources associated with the search record +F. +
++This call is needed to free any internal resources allocated by the + or calls. +
++The unix implementation of the dos unit therefore keeps a table of open +directories, and when the table is full, closes one of the directories, and +reopens another. This system is adequate but slow if you use a lot of +searchrecs. +
++So, to speed up the findfirst/findnext system, the FindClose call was +implemented. When you don't need a searchrec any more, you can tell +this to the dos unit by issuing a FindClose call. The directory +which is kept open for this searchrec is then closed, and the table slot +freed. +
++FindFirst searches the file specified in Path. Normal files, +as well as all special files which have the attributes specified in +Attr will be returned. +
++It returns a SearchRec record for further searching in F. +Path can contain the wildcard characters ? (matches any single +character) and * (matches 0 ore more arbitrary characters). In this +case FindFirst will return the first file which matches the specified +criteria. +If DosError is different from zero, no file(s) matching the criteria +was(were) found. +
++FindNext takes as an argument a SearchRec from a previous +FindNext call, or a FindFirst call, and tries to find another +file which matches the criteria, specified in the FindFirst call. +If DosError is different from zero, no more files matching the +criteria were found. +
++For an example, see . +
++FSearch searches the file Path in all directories listed in +DirList. The full name of the found file is returned. +DirList must be a list of directories, separated by semi-colons. +When no file is found, an empty string is returned. +
++GetCBreak gets the status of CTRL-Break checking under dos and Amiga. +When BreakValue is false, then dos only checks for the +CTRL-Break key-press when I/O is performed. When it is set to True, +then a check is done at every system call. +
++Getenv returns the value of the environment variable EnvVar. +When there is no environment variable EnvVar defined, an empty +string is returned. +
++GetFAttr returns the file attributes of the file-variable f. + F can be a untyped or typed file, or of type Text. f must +have been assigned, but not opened. The attributes can be examined with the +following constants : +
++Under linux, supported attributes are: +
++GetIntVec returns the address of interrupt vector +IntNo. +
++This function is only implemented in the GO32V2 version of Free Pascal. +
++GetLongName changes the filename p to a long filename +if the dos call to do this is successful. The resulting string +is the long file name corresponding to the short filename p. +
++The function returns True if the dos call was successful, +False otherwise. +
++This function should only be necessary when using the DOS extender +under Windows 95 and higher. +
++This function is only implemented in the GO32V2 version of Free Pascal. +
++GetShortName changes the filename p to a short filename +if the dos call to do this is successful. The resulting string +is the short file name corresponding to the long filename p. +
++The function returns True if the dos call was successful, +False otherwise. +
++This function should only be necessary when using the DOS extender +under Windows 95 and higher. +
++GetTime returns the system's time. Hour is a on a 24-hour time +scale. sec100 is in hundredth of a +second. +
++GetVerify returns the status of the verify flag under dos. When +Verify is True, then dos checks data which are written to disk, +by reading them after writing. If Verify is False, then data +written to disk are not verified. +
++Intr executes a software interrupt number IntNo (must be between +0 and 255), with processor registers set to Regs. After the interrupt call +returned, the processor registers are saved in Regs. +
++Keep terminates the program, but stays in memory. This is used for TSR +(Terminate Stay Resident) programs which catch some interrupt. +ExitCode is the same parameter as the Halt function takes. +
++MSDos executes an operating system call. This is the same as doing a +Intr call with the interrupt number for an os call. +
++SetCBreak sets the status of CTRL-Break checking. When +BreakValue is false, then dos only checks for the CTRL-Break +key-press when I/O is performed. When it is set to True, then a +check is done at every system call. +
++SetDate sets the system's internal date. Year is a number +between 1980 and 2099. +
++SetFAttr sets the file attributes of the file-variable F. + F can be a untyped or typed file, or of type Text. F must +have been assigned, but not opened. The attributes can be a sum of the +following constants: +
++SetFTime sets the modification time of a file, +this time is encoded and must be encoded with PackTime. +F must be a file type, which has been assigned, and +opened. +
++SetIntVec sets interrupt vector IntNo to Vector. +Vector should point to an interrupt procedure. +
++SetTime sets the system's internal clock. The Hour parameter is +on a 24-hour time scale. +
++SetVerify sets the status of the verify flag under dos. When +Verify is True, then dos checks data which are written to disk, +by reading them after writing. If Verify is False, then data +written to disk are not verified. +
++SwapVectors swaps the contents of the internal table of interrupt +vectors with the current contents of the interrupt vectors. +This is called typically in before and after an Exec call. +
++UnPackTime converts the file-modification time in p +to a DateTime record. The file-modification time can be +returned by GetFTime, FindFirst or FindNext calls. +
++For an example, see . +
+
+The
+A custom keyboard driver can be installed using the +function. The current keyboard driver can be retrieved using the + function. The last section of this chapter +demonstrates how to make a keyboard driver. +
++The TKeyEvent type is the base type for all keyboard events. +
++The key stroke is encoded in the 4 bytes of the TKeyEvent type. +The various fields of the key stroke encoding can be obtained by typecasting +the TKeyEvent type to the type. +
++The structure of a TKeyRecord structure is explained in the +following table: +
+| Field | Meaning | +
| KeyCode | +Depending on flags either the physical representation of a key +(under DOS scancode, ascii code pair), or the translated +ASCII/unicode character. + |
| ShiftState | ++Shift-state when this key was pressed (or shortly after) + |
| Flags | ++Determine how to interpret KeyCode + |
+The shift-state can be checked using the various shift-state constants, +and the flags in the last byte can be checked using one of the +kbASCII, kbUniCode, kbFnKey, kbPhys, kbReleased constants. +
++If there are two keys returning the same char-code, there's no way to find +out which one was pressed (Gray+ and Simple+). If it needs to be known which +was pressed, the untranslated keycodes must be used, but these are system +dependent. System dependent constants may be defined to cover those, with +possibily having the same name (but different value). +
++The TKeyboardDriver record can be used to install a custom keyboard +driver with the function. +
++The various fields correspond to the different functions of the keyboard unit +interface. For more information about this record see +
++DoneKeyboard de-initializes the keyboard interface if the keyboard +driver is active. If the keyboard driver is not active, the function does +nothing. +
++This will cause the keyboard driver to clear up any allocated memory, +or restores the console or terminal the program was running in to its +initial state before the call to . This function should +be called on program exit. Failing to do so may leave the terminal or +console window in an unusable state. Its exact action depends on the +platform on which the program is running. +
++For an example, see most other functions. +
++GetKeyBoardDriver returns in Driver the currently active +keyboard driver. This function can be used to enhance an existing +keyboarddriver. +
++For more information on getting and setting the keyboard driver +. +
++GetKeyEvent returns the last keyevent if one was stored in +PendingKeyEvent, or waits for one if none is available. +A non-blocking version is available in . +
++The returned key is encoded as a TKeyEvent type variable, and +is normally the physical key scan code, (the scan code is driver +dependent) which can be translated with one of the translation +functions or . +See the types section for a description of how the key is described. +
++GetKeyEventChar returns the charcode part of the given +KeyEvent, if it contains a translated character key +keycode. The charcode is simply the ascii code of the +character key that was pressed. +
++It returns the null character if the key was not a character key, but e.g. a +function key. +
++For an example, see +
++GetKeyEventCode returns the translated function keycode part of +the given KeyEvent, if it contains a translated function key. +
++If the key pressed was not a function key, the null character is returned. +
++GetKeyEventFlags returns the flags part of the given +KeyEvent. +
++For an example, see +
++GetKeyEventShiftState returns the shift-state values of +the given KeyEvent. This can be used to detect which of the modifier +keys Shift, Alt or Ctrl were pressed. If none were +pressed, zero is returned. +
++Note that this function does not always return expected results; +In a unix X-Term, the modifier keys do not always work. +
++InitKeyboard initializes the keyboard driver. +If the driver is already active, it does nothing. When the driver is +initialized, it will do everything necessary to ensure the functioning of +the keyboard, including allocating memory, initializing the terminal etc. +
++This function should be called once, before using any of the +keyboard functions. When it is called, the function +should also be called before exiting the program or changing the keyboard +driver with . +
++For an example, see most other functions. +
++KeyEventToString translates the key event in KeyEvent to a +human-readable description of the pressed key. It will use the constants +described in the constants section to do so. +
++For an example, see most other functions. +
++PollKeyEvent checks whether a key event is available, +and returns it if one is found. If no event is pending, +it returns 0. +
++Note that this does not remove the key from the pending keys. +The key should still be retrieved from the pending key events +list with the function. +
++SetKeyBoardDriver sets the keyboard driver to Driver, if the +current keyboard driver is not yet initialized. If the current +keyboard driver is initialized, then SetKeyboardDriver does +nothing. Before setting the driver, the currently active driver should +be disabled with a call to . +
++The function returns True if the driver was set, False if not. +
++For more information on setting the keyboard driver, see . +
++ShiftStateToString returns a string description of the shift state +of the key event KeyEvent. This can be an empty string. +
++The shift state is described using the strings in the SShift constant. +
++For an example, see . +
++TranslateKeyEvent performs ASCII translation of the KeyEvent. +It translates a physical key to a function key if the key is a function key, +and translates the physical key to the ordinal of the ascii character if +there is an equivalent character key. +
++For an example, see +
++Special physical keys are encoded with the DOS scan codes for these keys +in the second byte of the type. +A complete list of scan codes can be found in the below table. +This is the list of keys that is used by the default key event translation mechanism. +When writing a keyboard driver, either these constants should be returned +by the various key event functions, or the TranslateKeyEvent hook +should be implemented by the driver. +
+| Code | Key | Code | Key | Code | Key | +
| 00 | NoKey | 3D | F3 | 70 | ALT-F9 |
| 01 | ALT-Esc | 3E | F4 | 71 | ALT-F10 |
| 02 | ALT-Space | 3F | F5 | 72 | CTRL-PrtSc |
| 04 | CTRL-Ins | 40 | F6 | 73 | CTRL-Left |
| 05 | SHIFT-Ins | 41 | F7 | 74 | CTRL-Right |
| 06 | CTRL-Del | 42 | F8 | 75 | CTRL-end |
| 07 | SHIFT-Del | 43 | F9 | 76 | CTRL-PgDn |
| 08 | ALT-Back | 44 | F10 | 77 | CTRL-Home |
| 09 | ALT-SHIFT-Back | 47 | Home | 78 | ALT-1 |
| 0F | SHIFT-Tab | 48 | Up | 79 | ALT-2 |
| 10 | ALT-Q | 49 | PgUp | 7A | ALT-3 |
| 11 | ALT-W | 4B | Left | 7B | ALT-4 |
| 12 | ALT-E | 4C | Center | 7C | ALT-5 |
| 13 | ALT-R | 4D | Right | 7D | ALT-6 |
| 14 | ALT-T | 4E | ALT-GrayPlus | 7E | ALT-7 |
| 15 | ALT-Y | 4F | end | 7F | ALT-8 |
| 16 | ALT-U | 50 | Down | 80 | ALT-9 |
| 17 | ALT-I | 51 | PgDn | 81 | ALT-0 |
| 18 | ALT-O | 52 | Ins | 82 | ALT-Minus |
| 19 | ALT-P | 53 | Del | 83 | ALT-Equal |
| 1A | ALT-LftBrack | 54 | SHIFT-F1 | 84 | CTRL-PgUp |
| 1B | ALT-RgtBrack | 55 | SHIFT-F2 | 85 | F11 |
| 1E | ALT-A | 56 | SHIFT-F3 | 86 | F12 |
| 1F | ALT-S | 57 | SHIFT-F4 | 87 | SHIFT-F11 |
| 20 | ALT-D | 58 | SHIFT-F5 | 88 | SHIFT-F12 |
| 21 | ALT-F | 59 | SHIFT-F6 | 89 | CTRL-F11 |
| 22 | ALT-G | 5A | SHIFT-F7 | 8A | CTRL-F12 |
| 23 | ALT-H | 5B | SHIFT-F8 | 8B | ALT-F11 |
| 24 | ALT-J | 5C | SHIFT-F9 | 8C | ALT-F12 |
| 25 | ALT-K | 5D | SHIFT-F10 | 8D | CTRL-Up |
| 26 | ALT-L | 5E | CTRL-F1 | 8E | CTRL-Minus |
| 27 | ALT-SemiCol | 5F | CTRL-F2 | 8F | CTRL-Center |
| 28 | ALT-Quote | 60 | CTRL-F3 | 90 | CTRL-GreyPlus |
| 29 | ALT-OpQuote | 61 | CTRL-F4 | 91 | CTRL-Down |
| 2B | ALT-BkSlash | 62 | CTRL-F5 | 94 | CTRL-Tab |
| 2C | ALT-Z | 63 | CTRL-F6 | 97 | ALT-Home |
| 2D | ALT-X | 64 | CTRL-F7 | 98 | ALT-Up |
| 2E | ALT-C | 65 | CTRL-F8 | 99 | ALT-PgUp |
| 2F | ALT-V | 66 | CTRL-F9 | 9B | ALT-Left |
| 30 | ALT-B | 67 | CTRL-F10 | 9D | ALT-Right |
| 31 | ALT-N | 68 | ALT-F1 | 9F | ALT-end |
| 32 | ALT-M | 69 | ALT-F2 | A0 | ALT-Down |
| 33 | ALT-Comma | 6A | ALT-F3 | A1 | ALT-PgDn |
| 34 | ALT-Period | 6B | ALT-F4 | A2 | ALT-Ins |
| 35 | ALT-Slash | 6C | ALT-F5 | A3 | ALT-Del |
| 37 | ALT-GreyAst | 6D | ALT-F6 | A5 | ALT-Tab |
| 3B | F1 | 6E | ALT-F7 | ||
| 3C | F2 | 6F | ALT-F8 |
+A list of scan codes for special keys and combinations with the SHIFT, ALT +and CTRL keys can be found in the following table: They are for quick reference +only. +
+| Key | Code | SHIFT-Key | CTRL-Key | Alt-Key | +
| NoKey | 00 | |||
| F1 | 3B | 54 | 5E | 68 |
| F2 | 3C | 55 | 5F | 69 |
| F3 | 3D | 56 | 60 | 6A |
| F4 | 3E | 57 | 61 | 6B |
| F5 | 3F | 58 | 62 | 6C |
| F6 | 40 | 59 | 63 | 6D |
| F7 | 41 | 5A | 64 | 6E |
| F8 | 42 | 5A | 65 | 6F |
| F9 | 43 | 5B | 66 | 70 |
| F10 | 44 | 5C | 67 | 71 |
| F11 | 85 | 87 | 89 | 8B |
| F12 | 86 | 88 | 8A | 8C |
| Home | 47 | 77 | 97 | |
| Up | 48 | 8D | 98 | |
| PgUp | 49 | 84 | 99 | |
| Left | 4B | 73 | 9B | |
| Center | 4C | 8F | ||
| Right | 4D | 74 | 9D | |
| end | 4F | 75 | 9F | |
| Down | 50 | 91 | A0 | |
| PgDn | 51 | 76 | A1 | |
| Ins | 52 | 05 | 04 | A2 |
| Del | 53 | 07 | 06 | A3 |
| Tab | 8 | 0F | 94 | A5 |
| GreyPlus | 90 | 4E |
+Writing a keyboard driver means that hooks must be created for most of the +keyboard unit functions. The TKeyBoardDriver record contains a field +for each of the possible hooks: +
+
+TKeyboardDriver = Record
+ InitDriver : Procedure;
+ DoneDriver : Procedure;
+ GetKeyEvent : Function : TKeyEvent;
+ PollKeyEvent : Function : TKeyEvent;
+ GetShiftState : Function : Byte;
+ TranslateKeyEvent : Function (KeyEvent: TKeyEvent): TKeyEvent;
+ TranslateKeyEventUniCode: Function (KeyEvent: TKeyEvent): TKeyEvent;
+end;
+
++The meaning of these hooks is explained below: +
++Strictly speaking, only the GetKeyEvent and PollKeyEvent +hooks must be implemented for the driver to function correctly. +
++The example unit demonstrates how a keyboard driver can be installed. +It takes the installed driver, and hooks into the GetKeyEvent +function to register and log the key events in a file. This driver +can work on top of any other driver, as long as it is inserted in the +uses clause after the real driver unit, and the real driver unit +should set the driver record in its initialization section. +
++Note that with a simple extension of this unit could be used to make a +driver that is capable of recording and storing a set of keyboard strokes, +and replaying them at a later time, so a 'keyboard macro' capable driver. +This driver could sit on top of any other driver. +
++The TMouseEvent is the central type of the mouse unit, it is used +to describe all mouse events. +
++The Buttons field describes which buttons were down when the event +occurred. The x,y fields describe where the event occurred on the +screen. The Action describes what action was going on when the event +occurred. The Buttons and Action field can be examined using the +constants defined in the unit interface. +
++DetectMouse detects whether a mouse is attached to the system or not. +If there is no mouse, then zero is returned. If a mouse is attached, then +the number of mouse buttons is returnead. +
++This function should be called after the mouse driver was initialized. +
++DoneMouse De-initializes the mouse driver. It cleans up any memory +allocated when the mouse was initialized, or removes possible mouse hooks +from memory. The mouse functions will not work after DoneMouse was +called. If DoneMouse is called a second time, it will exit at once. +InitMouse should be called before DoneMouse can be called again. +
++For an example, see most other mouse functions. +
++GetMouseButtons returns the current button state of the mouse, i.e. +it returns a or-ed combination of the following constants: +
++GetMouseDriver returns the currently set mouse driver. It can be used +to retrieve the current mouse driver, and override certain callbacks. +
++A more detailed explanation about getting and setting mouse drivers can be found in +. +
++For an example, see the section on writing a custom mouse driver, + +
++GetMouseEvent returns the next mouse event (a movement, button press or +button release), and waits for one if none is available in the queue. +
++Some mouse drivers can implement a mouse event queue which can hold multiple +events till they are fetched. Others don't, and in that case, a one-event +queue is implemented for use with . +
++GetMouseY returns the current Y position of the mouse. Y is +measured in characters, starting at 0 for the top of the screen. +
++For an example, see +
++InitMouse Initializes the mouse driver. This will allocate any data +structures needed for the mouse to function. All mouse functions can be +used after a call to InitMouse. +
++A call to InitMouse must always be followed by a call to +at program exit. Failing to do so may leave the mouse in an unusable state, +or may result in memory leaks. +
++For an example, see most other functions. +
++PollMouseEvent checks whether a mouse event is available, and +returns it in MouseEvent if one is found. The function result is +True in that case. If no mouse event is pending, the function result +is False, and the contents of MouseEvent is undefined. +
++Note that after a call to PollMouseEvent, the event should still +be removed from the mouse event queue with a call to GetMouseEvent. +
++PutMouseEvent adds MouseEvent to the input queue. The next +call to or PollMouseEvent will then return +MouseEvent. +
++Please note that depending on the implementation the mouse event queue +can hold only one value. +
++SetMouseDriver sets the mouse driver to Driver. This function +should be called before is called, or after DoneMouse +is called. If it is called after the mouse has been initialized, it does +nothing. +
++For more information on setting the mouse driver, . +
++For an example, see +
++ShowMouse shows the mouse cursor if it was previously hidden. The +capability to hide or show the mouse cursor depends on the driver. +
++For an example, see +
+
+The
+The following unit shows how a mouse driver can be enhanced by adding some +logging capabilities to the driver. +
+
+This document documents the
+The methods and fields that are in a Private part of an object +declaration have been left out of this documentation. +
++NewStr makes a copy of the string S on the heap, +and returns a pointer to this copy. If the string is empty then +Nil is returned. +
++The allocated memory is not based on the declared size of the string passed +to NewStr, but is baed on the actual length of the string. +
++SetStr makes a copy of the string S on the heap and +returns the pointer to this copy in P. If P pointed to +another string (i.e. was not Nil, the memory is released first. +Contrary to , if the string is empty then a pointer to +an empty string is returned. +
++The allocated memory is not based on the declared size of the string passed +to NewStr, but is based on the actual length of the string. +
++DisposeStr removes a dynamically allocated string from the heap. +
++For an example, see . +
++When implementing abstract methods, do not declare them as abstract. +Instead, define them simply as virtual. In the implementation of such +abstract methods, call the Abstract procedure. This allows explicit +control of what happens when an abstract method is called. +
++The current implementation of Abstract terminates the program with +a run-time error 211. +
++RegisterObjects registers the following objects for streaming: +
++RegisterType registers a new type for streaming. An object cannot +be streamed unless it has been registered first. +The stream record S needs to have the following fields set: +
++The VMT of the object can be retrieved with the +following expression: +
+
+ VmtLink: Ofs(TypeOf(MyType)^);
+
++Equals returns True if the rectangle has the +same corner points A,B as the rectangle R, and False +otherwise. +
++For an example, see +
++Grow expands the rectangle with an amount ADX in the X +direction (both on the left and right side of the rectangle, thus adding a +length 2*ADX to the width of the rectangle), and an amount ADY in +the Y direction (both on the top and the bottom side of the rectangle, +adding a length 2*ADY to the height of the rectangle. +
++ADX and ADY can be negative. If the resulting rectangle is empty, it is set +to the empty rectangle at (0,0). +
++Assign sets the corner points of the rectangle to (XA,YA) and +(Xb,Yb). +
++For an example, see . +
++Instantiates a new object of type TObject. It fills the instance up +with Zero bytes. +
++For an example, see Free +
++Done, the destructor of TObject does nothing. It is mainly +intended to be used in the method. +
++The destructore Done does not free the memory occupied by the object. +
++The TStream object is the ancestor for all streaming objects, i.e. +objects that have the capability to store and retrieve data. +
++It defines a number of methods that are common to all objects that implement +streaming, many of them are virtual, and are only implemented in the +descendent types. +
++Programs should not instantiate objects of type TStream directly, but +instead instantiate a descendant type, such as TDosStream, +TMemoryStream. +
++Open is an abstract method, that should be overridden by descendent +objects. Since opening a stream depends on the stream's type this is not +surprising. +
++For an example, see . +
++Close is an abstract method, that should be overridden by descendent +objects. Since Closing a stream depends on the stream's type this is not +surprising. +
++for an example, see . +
++Flush is an abstract method that should be overridden by descendent +objects. It serves to enable the programmer to tell streams that implement +a buffer to clear the buffer. +
++for an example, see . +
++Truncate is an abstract procedure that should be overridden by +descendent objects. It serves to enable the programmer to truncate the +size of the stream to the current file position. +
++For an example, see . +
++Put writes the object pointed to by P. P should be +non-nil. The object type must have been registered with . +
++After the object has been written, it can be read again with Get. +
++For an example, see ; +
++StrWrite writes the null-terminated string P to the stream. +P can only be 65355 bytes long. +
++For an example, see . +
++StrWrite writes the pascal string pointed to by P to the stream. +
++For an example, see . +
++Seek sets the position to Pos. This position is counted +from the beginning, and is zero based. (i.e. seeek(0) sets the position +pointer on the first byte of the stream) +
++For an example, see . +
++Error sets the stream's status to Code and ErrorInfo +to Info. If the StreamError procedural variable is set, +Error executes it, passing Self as an argument. +
++This method should not be called directly from a program. It is intended to +be used in descendent objects. +
++Read is an abstract method that should be overridden by descendent +objects. +
++Read reads Count bytes from the stream into Buf. +It updates the position pointer, increasing it's value with Count. +Buf must be large enough to contain Count bytes. +
++Write is an abstract method that should be overridden by descendent +objects. +
++Write writes Count bytes to the stream from Buf. +It updates the position pointer, increasing it's value with Count. +
++For an example, see . +
++TDosStream is a stream that stores it's contents in a file. +it overrides a couple of methods of for this. +
++In addition to the fields inherited from TStream (see ), +there are some extra fields, that describe the file. (mainly the name and +the OS file handle) +
++No buffering in memory is done when using TDosStream. +All data are written directly to the file. For a stream that buffers +in memory, see . +
++Init instantiates an instance of TDosStream. The name of the +file that contains (or will contain) the data of the stream is given in +FileName. The Mode parameter determines whether a new file +should be created and what access rights you have on the file. +It can be one of the following constants: +
++For an example, see . +
++Done closes the file if it was open and cleans up the +instance of TDosStream. +
++for an example, see e.g. . +
++Close closes the file if it was open, and sets Handle to -1. +Contrary to Done it does not clean up the instance +of TDosStream +
++For an example, see . +
++If the Stream is open and the stream status is stOK then +Read will read Count bytes from the stream and place them +in Buf. +
++For an example, see . +
++If the Stream is open and the stream status is stOK then +Write will write Count bytes from Buf and place them +in the stream. +
++For an example, see . +
++Bufstream implements a buffered file stream. That is, all data written +to the stream is written to memory first. Only when the buffer is full, or +on explicit request, the data is written to disk. +
++Also, when reading from the stream, first the buffer is checked if there is +any unread data in it. If so, this is read first. If not the buffer is +filled again, and then the data is read from the buffer. +
++The size of the buffer is fixed and is set when constructing the file. +
++This is useful if you need heavy throughput for your stream, because it +speeds up operations. +
++Init instantiates an instance of TBufStream. The name of the +file that contains (or will contain) the data of the stream is given in +FileName. The Mode parameter determines whether a new file +should be created and what access rights you have on the file. +It can be one of the following constants: +
++The Size parameter determines the size of the buffer that will be +created. It should be different from zero. +
++For an example see . +
++Done flushes and closes the file if it was open and cleans up the +instance of TBufStream. +
++For an example see . +
++Close flushes and closes the file if it was open, and sets Handle to -1. +Contrary to Done it does not clean up the instance +of TBufStream +
++For an example see . +
++If the status of the stream is stOK, then Truncate tries to +flush the buffer, and then truncates the stream size to the current +file position. +
++For an example, see . +
++If the stream's status is stOK, then Seek sets the +file position to Pos. Pos is a zero-based offset, counted from +the beginning of the file. +
++For an example, see ; +
++If the stream's status is stOK, and the stream is closed then +Open re-opens the file stream with mode OpenMode. +This call can be used after a Close call. +
++For an example, see . +
++If the Stream is open and the stream status is stOK then +Read will read Count bytes from the stream and place them +in Buf. +
++Read will first try to read the data from the stream's internal +buffer. If insufficient data is available, the buffer will be filled before +contiunuing to read. This process is repeated until all needed data +has been read. +
++For an example, see . +
++If the Stream is open and the stream status is stOK then +Write will write Count bytes from Buf and place them +in the stream. +
++Write will first try to write the data to the stream's internal +buffer. When the internal buffer is full, then the contents will be written +to disk. This process is repeated until all data has been written. +
++For an example, see . +
++The TMemoryStream object implements a stream that stores it's data +in memory. The data is stored on the heap, with the possibility to specify +the maximum amout of data, and the the size of the memory blocks being used. +
++Init instantiates a new TMemoryStream object. The +memorystreamobject will initially allocate at least ALimit bytes memory, +divided into memory blocks of size ABlockSize. +The number of blocks needed to get to ALimit bytes is rounded up. +
++By default, the number of blocks is 1, and the size of a block is 8192. This +is selected if you specify 0 as the blocksize. +
++For an example, see e.g . +
++Done releases the memory blocks used by the stream, and then cleans up +the memory used by the stream object itself. +
++For an example, see e.g . +
++Read reads Count bytes from the stream to Buf. It updates +the position of the stream. +
++For an example, see . +
++Write copies Count bytes from Buf to the stream. It +updates the position of the stream. +
++If not enough memory is available to hold the extra Count bytes, +then the stream will try to expand, by allocating as much blocks with +size BlkSize (as specified in the constuctor call +Init) as needed. +
++For an example, see . +
++The TCollection object manages a collection of pointers or objects. +It also provides a series of methods to manipulate these pointers or +objects. +
++Whether or not objects are used depends on the kind of calls you use. +All kinds come in 2 flavors, one for objects, one for pointers. +
++Init initializes a new instance of a collection. It sets the (initial) maximum number +of items in the collection to ALimit. ADelta is the increase +size : The number of memory places that will be allocatiod in case ALimit is reached, +and another element is added to the collection. +
++For an example, see . +
++Done frees all objects in the collection, and then releases all memory +occupied by the instance. +
++For an example, see . +
+ ++FreeItem calls the destructor of Item if it is not +nil. +
++ForEach calls Action for each element in the collection, +and passes the element as an argument to Action. +
++Action is a procedural type variable that accepts a pointer as an +argument. +
++SetLimit sets the maximum number of elements in the collection. +ALimit must not be less than Count, and should not be larger +than MaxCollectionSize +
++For an example, see Pack. +
++Error is called by the various TCollection methods +in case of an error condition. The default behaviour is to make +a call to RunError with an error of 212-Code. +
++This method can be overridden by descendent objects to implement +a different error-handling. +
++AtPut sets the element at position Index in the collection +to Item. Any previous value is overwritten. +
++For an example, see Pack. +
++Store writes the collection to the stream S. It does +this by writeing the current Count, Limit and Delta +to the stream, and then writing each item to the stream. +
++The contents of the stream are then suitable for instantiating another +collection with Load. +
++For an example, see . +
++TSortedCollection is an abstract class, implementing a sorted +collection. You should never use an instance of TSortedCollection +directly, instead you should declare a descendent type, and override the +Compare method. +
++Because the collection is ordered, TSortedCollection overrides some +TCollection methods, to provide faster routines for lookup. +
++The Compare method decides how elements +in the collection should be ordered. Since TCollection has no way +of knowing how to order pointers, you must override the compare method. +
++Additionally, TCollection provides a means to filter out duplicates. +if you set Duplicates to False (the default) then duplicates +will not be allowed. +
++The example below defines a descendent of TSortedCollection which +is used in the examples. +
++Init calls the inherited constuctor (see ) and +sets the Duplicates flag to false. +
++You should not call this method directly, since TSortedCollection is a +abstract class. Instead, the descendent classes should call it via the +inherited keyword. +
++Load calls the inherited constuctor (see ) and +reads the Duplicates flag from the stream.. +
++You should not call this method directly, since TSortedCollection is a +abstract class. Instead, the descendent classes should call it via the +inherited keyword. +
++For an example, see . +
++KeyOf returns the key associated with Item. +TSortedCollection returns the item itself as the key, descendent +objects can override this method to calculate a (unique) key based on the +item passed (such as hash values). +
++Keys are used to sort the objects, they are used to search and sort +the items in the collection. If descendent types override this method then +it allows possibly for faster search/sort methods based on keys rather than +on the objects themselves. +
++IndexOf returns the index of Item in the collection. It searches +for the object based on it's key. If duplicates are allowed, then it returns +the index of last object that matches Item. +
++In case Item is not found in the collection, -1 is returned. +
++For an example, see +
++Compare is an abstract method that should be overridden by descendent +objects in order to compare two items in the collection. This method is used +in the Search method and in the +Insert method to determine the ordering of +the objects. +
++The function should compare the two keys of items and return the following +function results: +
++Search looks for the item with key Key and returns the position +of the item (if present) in the collection in Index. +
++Instead of a linear search as TCollection does, TSortedCollection +uses a binary search based on the keys of the objects. It uses the +Compare function to implement this +search. +
++If the item is found, Search returns True, otherwise False +is returned. +
++Insert inserts an item in the collection at the correct position, such +that the collection is ordered at all times. You should never use +Atinsert, since then the collection ordering +is not guaranteed. +
++If Item is already present in the collection, and Duplicates is +False, the item will not be inserted. +
++Store writes the collection to the stream S. It does this by +calling the inherited , and then writing the +Duplicates flag to the stream. +
++After a Store, the collection can be loaded from the stream with the +constructor Load +
++For an example, see . +
++The TStringCollection object manages a sorted collection of pascal +strings. +To this end, it overrides the Compare +method of TSortedCollection, and it introduces methods to read/write +strings from a stream. +
++GetItem reads a string from the stream S and returns a pointer +to it. It doesn't insert the string in the collection. +
++This method is primarily introduced to be able to load and store the +collection from and to a stream. +
++TStringCollection overrides the Compare function so it compares +the two keys as if they were pointers to strings. The compare is done case +sensitive. It returns the following results: +
++PutItem writes the string pointed to by Item to the stream +S. +
++This method is primarily used in the Load and Store methods, +and should not be used directly. +
++The TStrCollection object manages a sorted collection +of null-terminated strings (pchar strings). +To this end, it overrides the Compare +method of TSortedCollection, and it introduces methods to read/write +strings from a stream. +
++GetItem reads a null-terminated string from the stream S +and returns a pointer to it. It doesn't insert the string in the +collection. +
++This method is primarily introduced to be able to load and store the +collection from and to a stream. +
++TStrCollection overrides the Compare function so it compares +the two keys as if they were pointers to strings. The compare is done case +sensitive. It returns +
++PutItem writes the string pointed to by Item to the stream +S. +
++This method is primarily used in the Load and Store methods, +and should not be used directly. +
++The TUnSortedStrCollection object manages an unsorted list of strings. +To this end, it overrides the method to add +strings at the end of the collection, rather than in the alphabetically +correct position. +
++Take care, the Search and +IndexOf methods will not work on an unsorted +string collection. +
++A TResourceCollection manages a collection of resource names. +It stores the position and the size of a resource, as well as the name of +the resource. It stores these items in records that look like this: +
+
+TYPE
+ TResourceItem = packed RECORD
+ Posn: LongInt;
+ Size: LongInt;
+ Key : String;
+ End;
+ PResourceItem = ^TResourceItem;
+
++It overrides some methods of TStringCollection in order to accomplish +this. +
++GetItem reads a resource item from the stream S. It reads the +position, size and name from the stream, in that order. It DOES NOT read the +resource itself from the stream. +
++The resulting item is not inserted in the collection. This call is manly for +internal use by the method. +
++FreeItem releases the memory occupied by Item. It de-allocates +the name, and then the resourceitem record. +
++It does NOT remove the item from the collection. +
++PutItem writes Item to the stream S. It does this by +writing the position and size and name of the resource item to the stream. +
++This method is used primarily by the Store +method. +
++Init instantiates a new instance of a TResourceFile object. +If AStream is not nil then it is considered as a stream describing an +executable image on disk. +
++Init will try to position the stream on the start of the resources section, +and read all resources from the stream. +
++SwitchTo switches to a new stream to hold the resources in. +AStream will be the new stream after the call to SwitchTo. +
++If Pack is true, then all the known resources will be copied from +the current stream to the new stream (AStream). If Pack is +False, then only the current resource is copied. +
++The return value is the value of the original stream: Stream. +
++The Modified flag is set as a consequence of this call. +
++A TStringList object can be used to read a collection of strings +stored in a stream. If you register this object with the +function, you cannot register the TStrListMaker object. +
++The TStrListMaker object can be used to generate a stream with +strings, which can be read with the TStringList object. +If you register this object with the +function, you cannot register the TStringList object. +
++The Init constructor creates a new instance of the TstrListMaker +object. It allocates AStrSize bytes on the heap to hold all the +strings you wish to store. It also allocates enough room for +AIndexSize key description entries (of the type TStrIndexrec). +
++AStrSize must be large enough to contain all the strings you wish to +store. If not enough memory is allocated, other memory will be overwritten. +The same is true for AIndexSize : maximally AIndexSize strings +can be written to the stream. +
++FPAccept accepts a connection from a socket Sock, which was +listening for a connection. If a connection is accepted, a file descriptor +is returned. On error -1 is returned. The returned socket may NOT +be used to accept more connections. The original socket remains open. +
++The Accept call fills the address of the connecting entity in +Addr, and sets its length in Addrlen. Addr should +be pointing to enough space, and Addrlen should be set to the +amount of space available, prior to the call. +
++The alternate forms of the command, with the +Text or File parameters are equivalent +to subsequently calling the regular function and the + or functions. +These functions return True if successful, False otherwise. +
++On error, -1 is returned, and errors are reported in +SocketError, and include the following: +
++Bind binds the socket Sock to address Addr. Addr +has length Addrlen. +The function returns True if the call was succesful, False if +not. +
++The form of the Bind command with the +is equivalent to subsequently calling and the +regular Bind function. +The function returns True if successfull, False otherwise. +
++Errors are returned in SocketError and include the following: +
++More arrors can be found in the Unix man pages. +
++Connect opens a connection to a peer, whose address is described by +Addr. AddrLen contains the length of the address. +The type of Addr depends on the kind of connection you're trying to +make, but is generally one of TSockAddr or TUnixSockAddr. +
++The forms of the command with the Text or +File arguments are equivalent to subsequently calling the regular Connect +function and the or functions. +These functions return True if successfull, False otherwise. +
++The Connect function returns a file descriptor if the call +was successfull, -1 in case of error. +
++GetPeerName returns the name of the entity connected to the +specified socket Sock. The Socket must be connected for this call to +work. +
++Addr should point to enough space to store the name, the +amount of space pointed to should be set in Addrlen. +When the function returns succesfully, Addr will be filled with the +name, and Addrlen will be set to the length of Addr. +
++Errors are reported in SocketError, and include the following: +
++Errors are reported in SocketError, and include the following: +
++GetSocketOptions gets the connection options for socket Sock. +The socket may be obtained from different levels, indicated by Level, +which can be one of the following: +
++For more information on this call, refer to the unix manual page \seem{getsockopt}{2}. +
++Errors are reported in SocketError, and include the following: +
++Listen listens for up to MaxConnect connections from socket +Sock. The socket Sock must be of type SOCK_STREAM or +Sock_SEQPACKET. +
++The function returns True if a connection was accepted, False +if an error occurred. +
++Errors are reported in SocketError, and include the following: +
++Recv reads at most Addrlen bytes from socket Sock into +address Addr. The socket must be in a connected state. +Flags can be one of the following: +
++The functions returns the number of bytes actually read from the socket, or +-1 if a detectable error occurred. +
++Errors are reported in SocketError, and include the following: +
++Send sends AddrLen bytes starting from address Addr +to socket Sock. Sock must be in a connected state. +The function returns the number of bytes sent, or -1 if a detectable +error occurred. +
++Flags can be one of the following: +
++Errors are reported in SocketError, and include the following: +
++SetSocketOptions sets the connection options for socket Sock. +The socket may be manipulated at different levels, indicated by Level, +which can be one of the following: +
+
+For more information on this call, refer to the unix manual page
+
+Errors are reported in SocketError, and include the following: +
++ShutDown closes one end of a full duplex socket connection, described +by Sock. The parameter How determines how the connection +will be shut down, and can be one of the following: +
++On succes, the function returns 0, on error -1 is returned. +
++SocketError is used to report errors, and includes the following: +
++Socket creates a new socket in domain Domain, from type +SocketType using protocol Protocol. +The Domain, Socket type and Protocol can be specified using predefined +constants (see the section on constants for available constants) +If succesfull, the function returns a socket descriptor, which can be passed +to a subsequent call. If unsuccesfull, the function returns -1. +
++for an example, see . +
++Errors are returned in SocketError, and include the follwing: +
+
+The
+The working of the
+To write to the 'screen', the text to be written should be written to the +VideoBuf array. Calling will then cp the text to +the screen in the most optimal way. (an example can be found further on). +
++The color attribute is a combination of the foreground and background color, +plus the blink bit. The bits describe the various color combinations: +
++Each possible color has a constant associated with it, see the constants +section for a list of constants. +
++The foreground and background color can be combined to a color attribute +with the following code: +
+
+Attr:=ForeGroundColor + (BackGroundColor shl 4);
+
++The color attribute can be logically or-ed with the blink attribute to +produce a blinking character: +
+
+ Atrr:=Attr or blink;
+
++But not all drivers may support this. +
++The contents of the VideoBuf array may be modified: This is 'writing' +to the screen. As soon as everything that needs to be written in the array +is in the VideoBuf array, calling UpdateScreen will copy the +contents of the array screen to the screen, in a manner that is as efficient +as possible. +
++The updating of the screen can be prohibited to optimize performance; To +this end, the function can be used: This will +increment an internal counter. As long as the counter differs from zero, +calling will not do anything. The counter can be +lowered with . When it reaches zero, the next call +to will actually update the screen. This is useful when +having nested procedures that do a lot of screen writing. +
++The video unit also presents an interface for custom screen drivers, thus +it is possible to override the default screen driver with a custom screen +driver, see the call. The current video driver can +be retrieved using the call. +
++The TErrorHandler function is used to register an own error +handling function. It should be used when installing a custom error +handling function, and must return one of the above values. +
++Code should contain the error code for the error condition, +and the Info parameter may contain any data type specific to +the error code passed to the function. +
++TVideoDriver record can be used to install a custom video +driver, with the call. +
++An explanation of all fields can be found there. +
++The OldVideoBuf contains the state of the video screen after the last +screen update. The function uses this array to decide +which characters on screen should be updated, and which not. +
++Note that the OldVideoBuf array may be ignored by some drivers, so +it should not be used. The Array is in the interface section of the video +unit mainly so drivers that need it can make use of it. +
++DoneVideo disables the Video driver if the video driver is active. If +the videodriver was already disabled or not yet initialized, it does +nothing. Disabling the driver means it will clean up any allocated +resources, possibly restore the screen in the state it was before +InitVideo was called. Particularly, the VideoBuf and +OldVideoBuf arrays are no longer valid after a call to +DoneVideo. +
++The DoneVideo should always be called if InitVideo was called. +Failing to do so may leave the screen in an unusable state after the program +exits. +
++For an example, see most other functions. +
++GetCapabilities returns the capabilities of the current driver. +It is an or-ed combination of the following constants: +
++Note that the video driver should not yet be initialized to use this +function. It is a property of the driver. +
++GetCursorType returns the current cursor type. It is one of the +following values: +
++Note that not all drivers support all types of cursors. +
++GetVideoModeCount returns the number of video modes that the current +driver supports. If the driver does not support switching of modes, then 1 +is returned. +
++This function can be used in conjunction with the +function to retrieve data for the supported video modes. +
++GetVideoModeData returns the characteristics of the Index-th +video mode in Data. Index is zero based, and has a maximum value of +GetVideoModeCount-1. If the current driver does not support setting of +modes (GetVideoModeCount=1) and Index is zero, the current mode +is returned. +
++The function returns True if the mode data was retrieved succesfully, +False otherwise. +
++For an example, see . +
++InitVideo Initializes the video subsystem. If the video system was +already initialized, it does nothing. +After the driver has been initialized, the VideoBuf and OldVideoBuf +pointers are initialized, based on the ScreenWidth and +ScreenHeight variables. When this is done, the screen is cleared. +
++For an example, see most other functions. +
++LockScreenUpdate increments the screen update lock count with one. +As long as the screen update lock count is not zero, +will not actually update the screen. +
++This function can be used to optimize screen updating: If a lot of writing +on the screen needs to be done (by possibly unknown functions), calling +LockScreenUpdate before the drawing, and +after the drawing, followed by a call, all writing will +be shown on screen at once. +
++For an example, see . +
++SetCursorPos positions the cursor on the given position: Column +NewCursorX and row NewCursorY. The origin of the screen is the +upper left corner, and has coordinates (0,0). +
++The current position is stored in the CursorX and CursorY +variables. +
++SetCursorType sets the cursor to the type specified in NewType. +
++SetVideoDriver sets the videodriver to be used to Driver. If +the current videodriver is initialized (after a call to InitVideo) +then it does nothing and returns False. +
++A new driver can only be installed if the previous driver was not yet +activated (i.e. before a call to ) or after it was +deactivated (i.e after a call to DoneVideo). +
++For more information about installing a videodriver, see . +
++For an example, see the section on writing a custom video driver. +
++SetVideoMode sets the video mode to the mode specified in Mode: +
++If the call was succesful, then the screen will have Col columns and +Row rows, and will be displaying in color if Color is +True. +
++The function returns True if the mode was set succesfully, False +otherwise. +
++Note that the video mode may not always be set. E.g. a console on Linux +or a telnet session cannot always set the mode. It is important to check +the error value returned by this function if it was not succesful. +
++The mode can be set when the video driver has not yet been initialized +(i.e. before was called) In that case, the video mode will +be stored, and after the driver was initialized, an attempt will be made to +set the requested mode. Changing the video driver before the call to +InitVideo will clear the stored video mode. +
++To know which modes are valid, use the and + functions. To retrieve the current video mode, +use the procedure. +
++UnlockScreenUpdate decrements the screen update lock count with one if +it is larger than zero. When the lock count reaches zero, the + will actually update the screen. No screen update will +be performed as long as the screen update lock count is nonzero. This +mechanism can be used to increase screen performance in case a lot of +writing is done. +
++It is important to make sure that each call to is +matched by exactly one call to UnlockScreenUpdate +
++For an example, see . +
++UpdateScreen synchronizes the actual screen with the contents +of the VideoBuf internal buffer. The parameter Force +specifies whether the whole screen has to be redrawn (Force=True) +or only parts that have changed since the last update of the screen. +
++The Video unit keeps an internal copy of the screen as it last +wrote it to the screen (in the OldVideoBuf array). The current +contents of VideoBuf are examined to see what locations on the +screen need to be updated. On slow terminals (e.g. a linux telnet +session) this mechanism can speed up the screen redraw considerably. +
++For an example, see most other functions. +
++Writing a custom video driver is not difficult, and generally means +implementing a couple of functions, which whould be registered with +the function. The various functions that can be +implemented are located in the record: +
+
+TVideoDriver = Record
+ InitDriver : Procedure;
+ DoneDriver : Procedure;
+ UpdateScreen : Procedure(Force : Boolean);
+ ClearScreen : Procedure;
+ SetVideoMode : Function (Const Mode : TVideoMode) : Boolean;
+ GetVideoModeCount : Function : Word;
+ GetVideoModeData : Function(Index : Word; Var Data : TVideoMode) : Boolean;
+ SetCursorPos : procedure (NewCursorX, NewCursorY: Word);
+ GetCursorType : function : Word;
+ SetCursorType : procedure (NewType: Word);
+ GetCapabilities : Function : Word;
+end;
+
+
+Not all of these functions must be implemented. In fact, the only absolutely
+necessary function to write a functioning driver is the UpdateScreen
+function. The general calls in the
+The functionality of these calls is the same as the functionality of the +calls in the video unit, so the expected behaviour can be found in the +previous section. Some of the calls, however, need some additional remarks. +
++The following unit shows how to override a video driver, with a driver +that writes debug information to a file. The unit can be used in any of +the demonstration programs, by simply including it in the uses +clause. Setting DetailedVideoLogging to +True will create a more detailed log (but will also slow down +functioning) +
+