Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / CLIPPER / CLIPWIND.ARC / CLIPWIND.DOC < prev next >

Wrap

Text File | 1988-08-09 | 87.0 KB | 2,021 lines

Windows For Clipper ------------------- Copyright (C) 1986-1988 By Jim Holley All Rights Reserved 1346 Woodington Cir. Lawrenceville Ga. 30245 (404)564-3647 Windows For Clipper Trademarks and Concessions -------------------------- Clipper is a Trademark of Nantucket Corp. Lattice is a Trademark of Lattice, Inc. Microsoft is a Trademark of Microsoft Corp. Desmet 'C'is a Trademark of C Ware Corp. Plink86 is a Trademark of Pheonix Software Associates LTD. IBM is a Trademark of International Business Machines. Windows For Clipper SHAREWARE / NOT FREE SOFTWARE ----------------------------- The Windows For Clipper Library is now being distributed under the Shareware Concept. IT IS NOT FREE SOFTWARE. A lot of hard work and long hours have been put into developing this library of window routines. If you find this library of some practical use in developing your applications, please REGISTER your copy. If you don't find it of use, First, I'd like to know why. Second, please do not use it in any applications that you develop. I will trust in your conscience as a fellow programmer and developer. In trying to stay with the true concept of shareware (try it before you buy it), a decision was made to release the Windows For Clipper Library. I hope this decision will prove to be a wise one. This is a full working version. Not a demo. The documentation included on disk is also the complete reference to the library. There are no gimmicks or tricks. The contents of this distribution, is the same as the ordered version. If you use these routines and don't register them, you deminish the concept of shareware, and the programmer/developer community as whole. Shame on you! A Registration Form May Be Found In The REGISTER.DOC File. To All Bulletin Board Sysops and Users Groups: You may freely copy or make available for distribution, the Windows For Clipper Library package for evaluation purposes. However, no one may modify any of the files that are part of the orignal package. You may not sell, or otherwise profit from this package. That is the exclusive right of the author. You may however, charge a copy fee not to exceed $7.00 to cover costs, such as diskettes etc. This is the only fee that is allowable. If you paid more than this allowable fee, please contact the author. This provision applies ony to the Bulletin Board and Users Group Community. All others organizations and distribution methods are excluded and prohibited. Windows For Clipper Copyright Notice. ----------------- Copyright (C) 1986, 1987, 1988, By Jim Holley All rights reserved. Limited License Agreement ------------------------- Non registered users are granted a limited use license for evaluation purposes on a private Non commercial basis, to determine if Windows For Clipper is suitable for your use. If you regulary use Windows For Clipper, you must register your copy. This license does not apply to commercial businesses, institutions, or government agencies. If the Windows For Clipper Library is used in this way, registration is required. Remember, if you use the functions in the Windows For Clipper Library, you must register your copy. Disclaimer ---------- The author(s) of this set of routines believe that they will perform their stated purpose. No warranty of any kind, expressed or implied, including without limitation, any warranties of merchantabillity and/or fitness for a particular purpose is made. The author shall not be held liable for any damages to data, property, lost profits, lost savings, or other incidental or consequential damages, whether direct, indirect, or special, arising out of your use or inability to use these routines. Windows For Clipper This version of Windows For Clipper is for the Summer '87 version of the Clipper Compiler. All code with the exception of the WN_DBF(), WNSAVE(), and WNRESTORE() functions are written in MicroSoft 'C' Ver. 5.0 and Microsoft's Macro Assembler Ver 5.0. They are all a combination of Clipper, 'C', and assembler code. Windows For Clipper Table Of Contents ----------------- Page 1. Introduction ____________________________ 1 2. Limitations _____________________________ 2 3. Installing the Library __________________ 3 4. Link Phase ______________________________ 4 5. Technical Information ___________________ 5 6. Reserved Words ___________________________6 7. Library Reference _______________________ 7 Control & Initialization _SINIT_WN()............................ 8 _SST_WNCL()............................ 11 _SST_WNBC()............................ 12 _SST_PTSL()............................ 13 _SST_PTCL()............................ 14 _SST_UBIOS()........................... 15 _SWNCHG().............................. 13 _SMOVE_WN()............................ 14 _SREM_WN()............................. 15 _SWN_ROW()............................. 16 _SWN_COL()............................. 17 Input & Output _SWNPUTCH()............................ 21 _SWNGETCH()............................ 22 _SDRW_ROW()............................ 23 _SDRW_WN()............................. 24 _SWTE_TXT()............................ 25 _SWTE_RECS()........................... 26 _SWTE_PTR()............................ 28 _SCLS_WN()............................. 30 _SCRL_VERT()........................... 31 _SCRL_HORZ()........................... 32 _SWNERASE()............................ 33 _WNSAVE().............................. 34 _WNRESTORE()........................... 35 _WNGETBUF()............................ 36 _WNPUTBUF()............................ 37 _WN_DBF().............................. 38 Other Functions _BIGSTR().............................. 43 _NEWCOLOR()............................ 45 Windows For Clipper Page 1 Introduction ------------ Welcome to Windows for Clipper, a comprehensive set of window routines written especially for the Clipper programmer and Clipper Compiler. These routines provide all the basics for creating and manipulating windows in the Clipper programming environment. Also included are other video functions you may find useful. Windows For Clipper has been in use for over a year now by such companies or organizations as The Library Of Congress University Of Utah Scientific Atlanta Southern Methodist University Dr. Jay Sprenger Micro Business Services dConsultant Systems and many more. It is a proven, solid library. A Remote Bulletin Board service has been set up so that Windows For Clipper users can get support for the library, leave examples of code that others may find useful, and to discuss the Clipper compiler in general. The bulletin board is a restricted access board. You will be provided the number to call when you register your copy of the library. The demo that comes with this package shows how easy it is to access the window functions. No special tricks or requirements are needed. You write code as you normally would for any of the Clipper internal functions or your own User Defined Functions. No memory resident program needs to be loaded so that your program functions properly. It is all built into the program during the link phase. The only thing you need to learn are the function names and what they do. Windows For Clipper Page 2 Limitations ----------- The window functions have the following limitations: 1. Minimum ram required.................................1.5k (or 1048 bytes) This requirement is set even if a window is never created. 2. Maximum ram required.................................????? This is totally dependent on the number and dimensions of the windows that are being created in a program. Due to this, it it can not be stated exactly. 3. Maximum number of windows allowed....................256 Naturally, depending on the dimensions of the window and the amount of ram installed on the computer, the maximum number may be less. 4. Maximum window size..................................Full Screen 5. Minimum window size.................................3 col. by 3 rows Minimum size is due to the requirement of a border for all windows. Note, a 3 by 3 window will leave no room for text to be written. Windows For Clipper Page 3 Installation ------------ The first step you should take is MAKE A BACKUP COPY. Place the backup in a safe place in case you need it again. Installation of the library is simple and straight forward. Depending on the system configuration, do one of the following: If you have a floppy based system: ---------------------------------- Locate the diskette that contains the CLIPPER.LIB file. Copy the CLIPWIND.LIB file to this diskette. If there is not enough room on the disk for all of your libraries, you may put the Windows For Clipper Library on a separate disk. Refer to your linker manual to determine how to do this. If you have a hard disk system: ------------------------------- Determine which directory contains the CLIPPER.LIB file. Copy the CLIPWIND.LIB file to the same directory. Windows For Clipper Page 4 Link Phase ---------- The link phase is that portion of development where you invoke a linker to create the executable version of your program. Before you start to worry, the Windows For Clipper system requires nothing special other than specifying the library on the link line. For example: Plink86 Example PLINK86 FILE WDEMO, CURSOR LIBRARY CLIPPER, CLIPWIND ^-----------------^ ^-----------------------^ | | Indicate the object files to link | | Indicate the libraries to be used during the link phase. Link.exe Example LINK WDEMO CURSOR,, CLIPPER CLIPWIND The link structure may be as simple or complex as required. The only thing required is the CLIPWIND library in the link command used to invoke your linker. Included with the CLIPPER compiler are 2 batch files. These batch files, CL.BAT and CLD.BAT, are used to help compile and link your applications. Also included with Windows For Clipper are 2 batch files, CLWIND.BAT and CLDWIND.BAT. These were created to replace the batch files included with the compiler. If you currently use the aforementioned batch files, you may want to use those included with Windows For Clipper instead. There is also a batch file named PL2.BAT. This example file illustrates how to create batch files for linking using the PLINK86 linkage editor. It is fully functional and can be used if you do not wish to compile and link under control of a single batch file. Windows For Clipper Page 5 Technical Information --------------------- The Windows For Clipper routines support PC/MS - DOS for the IBM PC/XT/AT and 100% compatible computers. Some clones may or may not function properly, depending on the compatibility of the clone. The Windows For Clipper functions use DMA, or the standard BIOS interrupt call 10 hex. Any machine that does not support the IBM video addressing scheme or interrupt 10 hex will not work properly. It stands to reason, any machine that will execute a Clipper application will also execute the Windows For Clipper routines without problems. Compatibility Notes The Windows For Clipper functions will run on any IBM PC/XT/AT or 100 % compatibles. Since the new IBM PS/2 was not available to me, I can not state that it is 100 % compatible with this machine. Compatibility with this machine should not be a problem. As soon as this information becomes available, it will be documented. Windows For Clipper has been tested on, and found compatible with the following: Novell Advanced Netware Ver. 2.0A Various LIM Standard extended memory cards including the Intel AboveBoard, and Talltree Systems Jram3 and Jram AT3. Various Expanded Memory cards including the Quadram Quadboard. Thanks are in order for Mr. Paul Leo and his staff at the University of Utah, for there exhaustive testing of the Windows For Clipper System. Windows For Clipper Page 6 Reserved Words -------------- The following is a list of reserved words in the Windows For Clipper package. Please refrain from using any of these names. If you encounter a type conflict error during a program run, check your field and variable names to be sure you are not using one of these reserved words. _SINIT_WN _SST_WNCL _SST_WNBC _SWNCHG _SST_PTCL _SST_PTSL _SST_UBIOS _BIGSTR _SMOVE_WN _SREM_WN _SWNPUTCH _SWNGETCH _SDRW_ROW _SDRW_WN _SWTE_TXT _SWTE_RECS _SCLS_WN _SCRL_VERT _SCRL_HORZ _SWNERASE _WN_DBF _VIDSUP _SWN_ROW _SWN_COL _WNSAVE _WNRESTORE _WNGETBUF _WNPUTBUF _NEWCOLOR WNZ WN_ZFLD1 WN_ZFLD2 WN_ZFLD3 WN_ZFLD4 WN_ZFLD5 WN_ZFLD6 WN_ZFLD7 WN_ZFLD8 WN_ZFLD9 WN_ZFLD10 WN_ZUP WN_ZDOWN WN_ZLEFT WN_ZRIGHT WN_ZESC WN_ZCR WN_ZNUMROW WN_ZKEY WN_ZOFFSET WN_ZSCRL WN_ZTREC WN_ZCNT WN_ZTRSH WN_ZLINDEX WN_ZREC WN_ZF1 WN_ZF2 WN_ZF3 WN_ZF4 WN_ZF5 WN_ZF6 WN_ZF7 WN_ZF8 WN_ZF9 WN_ZF10 WN_ZFLEN WN_ZHOME WN_ZEND WN_ZCHOME WN_ZCEND WN_ZPGUP WN_ZPGDN ZZNROWS ZZNCOLS ZZSAVBUF ZZSAVEWN ZZMEMNAM Windows For Clipper Page 7 Library Reference ----------------- List of function calling syntax, synopsis, and return values for the Clipper window routines. -------------------------------- ============================================================================== Notational Conventions NOTE: Conventions used in this reference are as follows: TRUE - Logical True (.T.) FALSE - Logical False (.F.) [] - Anything enclosed in brackets is optional. ... - Ellipses following an item indicate that more items having the form may appear. ^ - Is used to indicate points of interest in example code. Also may indicate the use of the control (CTRL) key. ============================================================================== Windows For Clipper Page 8 Initialization and Control Functions ----------------------------------------------------------------------------- _SINIT_WN(starting column, starting row, number of columns, number of rows) Synopsis This is the core of the window functions. It is responsible for setting up the requirements of the window system as well setting up and maintaining the request for window creation from the programmer. What follows is a technical description of what this function does, as well as descriptions of the windows created and functions provided, with the window system. If you are not technically oriented, inclined or just plain uninterested in the technical aspect, you should still skim over the information below. It provides some very important information about this window system. On the first, and only the first, call to this module, 3 arrays are initialized. An array of pointers, an array of of color values, and an array of color codes. The memory required to establish the arrays is allocated whether you call a window function or not. All of the arrays are accessible to any of the window functions that require the data stored in them. The array of pointers consists of 256 elements, effectively giving the programmer 256 windows to work with and manipulate. All elements in the array are initialized to 0. As stated, this is an array of pointers. I am stressing this point because the initialization that takes place points every element in the array to the interrupt vector table in the computer. This is an area that only the brave should play around with. Any element that is set to 0 should be avoided. In a Clipper application, the calls to the window functions should only use the number returned by this function. If you use a number that was not provided by this function, you take the chance of writing information into the interupt vector table. This will reek havoc in your application, causing all kinds of strange things to happen. This brings up a couple of questions. First, why is an array necessary? And second, why set the value to 0 if it may cause trouble? The answer lies in dynamic memory allocation and a pointer variables value. The window routines were designed from the beginning to allow multiple windows, and to use as little RAM as possible. It would be a very simple task to eliminate the array if one could pass pointer values back and forth from the window functions to the Clipper application. As far as I know, it can't be done. This brought on the need for the array. The array is now used to store the pointer value. The value returned to the Clipper application is the offset value into the array that stores the pointer value. Windows For Clipper Page 9 Second question. All memory required for any given window is allocated dynamically. Any arbitrary number could have been selected to initialize the array, but chances are, the number selected could have been the same as the number returned by the memory allocation routines. Obviously, this would not be acceptable. The memory allocation routines return a 0 if the requested memory could not be allocated. So if an element in the array has a value of 0, it is not a valid pointer to a window control block structure and should not be accessed. On the other hand, if the allocation was successful, the pointer value is placed in the array and the value returned to the Clipper application corresponds to it's position in the array. As stated, memory is allocated dynamically when needed. When the memory is no longer needed, it is released back into the free memory pool. Therefore, if a window does not exist, it does not require any RAM. Once a window is initialized, it does require RAM, and will keep the RAM allocated to it as long as the window exists. The RAM requirements for each window created are as follows: 1024 Bytes approximate for the array of pointers. 24 Bytes used store the color and color code tables. 38 Bytes for the window control block structure. buffer = (number of columns * number of rows) * 2. The first item above is overhead. The array is manditory, and is constant. Memory for the array is allocated whether the window routines are used or not. The 30 bytes and buffer space are allocated each time a window is created. The memory allocated is constant as long as the window exists. If a window is removed the 30 bytes, and the bytes allocated for the buffer space, are released back to the free memory pool and can be used again. The buffer space is needed to store the information currently on the screen in the area the window will occupy. Windows For Clipper Page 10 If the window move function is called, memory is allocated for another buffer of the same buffer size required by the window itself. The above memory requirements are provided for those programmers who insist on writing mammoth applications and must keep a careful watch on the applications memory usage. Arguments starting column - Column offset the upper left corner of the window should start at. Values range from 0 to 79. starting row - Row offset the upper left corner of the window should start at. Values range from 0 to 24. number of columns - The number of columns the window will occupy. Values range from 0 to 79. number of rows - The number of rows the window will occupy. Values range from 0 to 24. Returns Value > 0 - If memory allocation and window initialization were successful. This value corresponds to the window control blocks structure position in the array. 0 - If memory could not be allocated, or invalid parameters were passed to the function. Windows For Clipper Page 11 _SST_WNCL(window, color code string, where) Synopsis This function allows the setting of color in a window. A color value can be established for the window border or window contents. The default color value is a black background and white foreground. Arguments window - Window number returned by the _SINIT_WN() function. Color code string - Character variable containing a string representing the color code. The color code string takes the following form. <background/foreground/intensity/blinking> You may use any character to separate the color code string, but a slash is recommended. The following are the codes used for color selection. A == BLACK B == BLUE G == GREEN C == CYAN R == RED M == MAGENTA O == BROWN W == WHITE L == BLINKING H == HIGH INTENSITY You may use upper case or lower case or any combination of the 2. EXAMPLE 1 "b/o/h/l" | | | | Blue Background ---------| | | |-------- Blinking Brown Foreground ----------| |---------High Intensity EXAMPLE 2 "b/r//" | | High Intensity not Blue Background ---------| | specified. Red Foreground ------------| No Blinking specified where - Character indicating where to change the color. Two (2) areas are available. The border, and the contents. "Where" must be a single character that is equal to a (b) for border or (c) for contents and can be either upper and/or lower case. Returns TRUE - If the color was changed successfully. FALSE - If the color could not be set. If this occurs, it is usually because the function received invalid arguments. Windows For Clipper Page 12 _SST_WNBC(window, border character) Synopsis This function allows the setting of a border character for a window. This character can be any of the printable characters in the PC's character set. Four (4) characters are special to the window borders. They are the upper left corner single, upper left corner double, upper left corner single top/double side, and the upper left corner double top/single side line graphics characters. These can be visually display by entering the following command at the dot prompt: ? CHR(218) == ┌ or in basic ? CHR$(218) ? CHR(201) == ╔ ? CHR$(201) ? CHR(213) == ╒ ? CHR$(213) ? CHR(214) == ╓ ? CHR$(214) If one of these characters is detected, a single, double single side/double top, or double top/single sided graphic box will border the window. At the current time any other character is taken literally, and will be used for the corners, top, bottom, and sides of the window. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. border character - The ascii value of the character that is to be used as the border character. The CHR() function should not be used as in the example above. Simply provide the ascii number for the border character. The reason this method of character selection was chosen was because not all editors allow entry of all the characters in the PC's character set, even some of the very expensive, feature rich editors on the market. And (here's the important one), it is easier to deal with characters and associated attributes as numbers, and not characters. Cheating on my part. Please forgive! Example 1. _SST_WNBC(window,218) This will create a single line graphics border around the window. Example 2. _SST_WNBC(window,201) This will create a double line graphics border around the window. Returns TRUE - If function was successfully. FALSE - If the function was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 13 _SST_PTSL(window, pointer type) Synopsis This function will select the pointer type to be written by the _SWTE_PTR() and _WN_DBF() functions. Two pointer types are available, type 1 and type 2. Type 1 is an arrow that points to the right and is placed in first 2 columns of a window. Please refer to the _SWTE_PTR() reference for more information. Type 2 is a bounce bar type pointer and is the default. This pointer spans the entire length of the window. The pointer colors can be selected using the _SST_PTCL() function. If a type 2 pointer is used, you should select a contrasting color to that which you have specified in the window. Arguments window - Window number returned by the _SINIT_WN() function. pointer type - 1 or 2. This indicates the pointer type to use. This value will be used by the _SWTE_PTR() function. Returns TRUE - If pointer type selection is successful. FALSE - If pointer type selection is not successful. This will occur if an invalid argument is received by the function. Windows For Clipper Page 14 _SST_PTCL(window, color code string) Synopsis This function allows the setting of the pointer color written by the _SWTE_PTR() function. This color should contrast the color which is set in the window. Arguments window - Window number returned by the _SINIT_WN() function. color code string - Character variable containing a string representing the color code. The color code string takes the following form. <background/foreground/intensity/blinking> You may use any character to separate the color code string, but a slash is recommended. The following are the codes used for color selection. A == BLACK B == BLUE G == GREEN C == CYAN R == RED M == MAGENTA O == BROWN W == WHITE L == BLINKING H == HIGH INTENSITY Please refer to the _SST_WNCL() function for an example of specifying the color code string. Returns TRUE - If pointer color selection is successful. FALSE - If pointer color selection is not successful. This will occur if an invalid argument is received by the function. Windows For Clipper Page 15 _SST_UBIOS(window, logical true or false) Synopsis This function sets the video access method used for all read/write operations performed in a window. Each window is treated as a separate entity. This provides more control to the programmer as to the video access method used in each window. The video access methods available are BIOS and Direct Memory Access. Some computers may not function correctly if Direct Memory Access (DMA) is used. For this reason, the window read/write functions can use an alternate method. If the computer is not 100% IBM compatible, even the alternate method will fail. Please test these functions on the machine that runs the application to be sure they work correctly. Arguments window - Window number returned by the _SINIT_WN() function. logical value - TRUE, will select the BIOS method. FALSE, will select Direct Memory Access. This is the default method used. Return TRUE - If the video access method was selected successfully. FALSE - If the video access method was selected was unsuccessful. This usually occurs due to invalid arguments being passed to the function. Windows For Clipper Page 16 _SWNCHG(window, new width, new height) Synopsis This function changes the width and height of a window. If you specify a window of 30 columns, and 10 rows, you can change these dimensions with this function to 40 columns and 15 rows. The window that is being changed can not be on the screen. You must use the swnerase function to erase the window from the screen. The new dimensions will appear when the window is drawn on the screen. Please note that this does not change the starting column and row coordinates. Care must be taken to prevent specifying a window that will exceed the column and row coordinates of the screen because the new coordinates are not checked. Arguments window - Window number returned by the _SINIT_WN() function. new width - New number of columns occupied by the window. new height - New number of rows occupied by the window. Returns TRUE - If the window change was successful. FALSE - If the window change was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 17 _SMOVE_WN(window, new column, new row) Synopsis This function will restore the text that was originally on the screen and move the window to the new coordinates. To do this, the function attempts to create a buffer by allocating memory. The buffer will store the contents of the target window. If memory is not available for this buffer, the window will not be moved. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. new column - New column offset for the upper left corner of the window. new row - New row offset for the upper left corner of the window. Returns TRUE - If the window was moved successfully. FALSE - If the window move was unsuccessful. This occurs because the function received invalid arguments. Windows For Clipper Page 18 _SREM_WN(window) Synopsis This function removes a window from the screen, restores the text that was on the screen prior to placing the window on the screen, and releases memory allocated, back to the free memory pool. On return from this function, the window no longer exists. If stacked (tiled) windows are on the screen, the last window drawn must be the first window removed. All subsequent removes must be done in the same manner. This function will obey the video access method selected Arguments window - Window number returned by the _SINIT_WN() function. Returns TRUE - If succesful in releasing memory, and restoring orginal screen contents. FALSE - If window was not successfully removed. This occurs because the function received invalid arguments. Windows For Clipper Page 19 _SWN_ROW(window) Synopsis This function determines the number of rows available for writing in the specified window. Arguments window - Window number returned by the _SINIT_WN() function. Returns - The number of rows available for writing. Or 0, if an invalid argument is received. Windows For Clipper Page 20 _SWN_COL(window) Synopsis This function determines the number of columns available for writing in the specified window. Arguments window - Window number returned by the _SINIT_WN() function. Returns - The number of columns available for writing. Or 0, if an invalid argument is received. Windows For Clipper Page 21 Input & Output Functions ------------------------ _SWNPUTCH(window, column, row, character) Synopsis This function provides the means to directly write any character to a window. If color has been set in the window, the character will be written using the same color attribute. This function will obey the video access methdo selected. Arguments window - Window number returned by the _SINIT_WN() function. column - The column location a character is to be written to. The columns are relative to the window dimensions. Column 0 represents the first available column for writing within a window. row - The row location a character is to be written to. The rows are relative to the window dimensions. Row 0 represents the first available row for writing within a window. character - The character to be written in the specified column row coordinates. Returns TRUE - If the function was successful in writing the character. FALSE - If the function was unsuccessful in writing the character. Windows For Clipper Page 22 _SWNGETCH(window, column, row) Synopsis This functions provides the means to directly read any character in a window. If a variable is to receive the character read, it must be initialized to a single space prior to calling this function. This function cannot create variables that are to be used by a Clipper application. Failure to initialize the target variable will make the function appear to have failed. This function should not be confused with the READ command in Clipper. This function does not get input from a user. The function will read an existing character in the window only. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. column - The column location a character is to be read from. The columns are relative to the window dimensions. That is, column 0 represents the first writable column in a window. row - The row location a character is to be written to. The rows are relative to the window dimensions. That is, row 0 represents the first writable row in a window. Return - This function returns the character read at the specified coordinates. Windows For Clipper Page 23 _SDRW_ROW(column, row, number of times, character [, video access method]) Synopsis This function provides a quick and easy way to write a specified character a specified number of times to the screen. It is not restricted to a window. You may use this function to write to any location on the screen. It can be used to subdivide a window quickly and with little coding. It is functionally equivalent to the dBASE/Clipper command: @ row,col SAY REPLICATE(character, number of times) This function allows a video access method to be selected as one of the arguments. The VDM is not mandatory. Arguments column - The starting column where the character is to be written. row - The starting row where the character is to be written. number of times - The number of times the character is to be written. character - The character to write. Video Access Method - A character indicating the VDM to use. A "D" will result in Direct Memory Access (DMA), any other character will result in a BIOS call. If not specified, the result will be a BIOS call. Returns TRUE - If the functions was successful. FALSE - If the function was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 24 _SDRW_WN(window) Synopsis This function actually draws the window on the screen. You may create any number of windows in your application, but they do not appear on the screen until this function is called. The window drawn occupies the following area: starting column, starting row number of columns + 2, number of rows + 2 When a call is placed to the _SINIT_WN() function with the following parameters: _SINIT_WN(10,5,30,10) a window is drawn with the upper left corner starting at column 10, row 5, and the lower right corner ending at column 42, row 17. As can be seen, the actual window occupies an area slightly larger than what was specified. The inside portion of the window area is available for writing. This area has the number of columns and rows which were specified. You cannot write text on the border area of the window when using the window output functions. The area available for writing is cleared. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. Returns TRUE - If window was drawn successfully. FALSE - If the window could not be drawn. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 25 _SWTE_TXT(window, string) Synopsis This function writes a string of text to a window. If the length of the string exceeds the the width of the window, it will be truncated. Each window keeps track of the last row written to. Each time a string is written to a window, the row offset inside the window is advanced to the next line. This is true regardless of the string's length. When the text is written to the last row in a window, all subsequent lines will scroll the window up one row, then write the text. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. string - The string to be written. The string can be in a variable, or literal. Returns TRUE - If the write was successful. FALSE - If the write was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 26 _SWTE_RECS(window, arg1, [arg2, arg3,.....]) Synopsis This function is a specialized form of the write text function. This function takes database field names as it's arguments. All fields specified must be of character type or converted to character type using one of the functions provided by Clipper i.e. STR(), DTOC() etc. At least one field must be specified. After that, 9 others maybe specified. The fields are written in the order specified in the call. If the contents of a field exceeds the window boundaries, the text will be truncated, and all subsequent fields will not be written. This does not mean the field is truncated in the database itself, just as output into the window. As in the _SWTE_TXT() function each window keeps track of the last row written to. Each time a set of fields is written to a window, the row offset is advanced to the next line. This function is not limited to just fields. You may specify string constants, or character type memory variables if needed. You may also specify any function as an argument, so long as the function returns a character type result. Example : _SWTE_REC(wn, Company, IF(paid , "Yes", "No")) Window # ^ ^ Field ^ Function returning char. This will display the contents of the field company and Yes, or No, depending on the value of paid. This assumes that company is a character field or memory variable, and paid is a logical field or memory variable. NOTE: The function is limited to combined length of 512 characters. This means that the length of each argument added together can not exceed 512 characters. All fields and memory variables will be displayed until a length of 512 characters is reached. If the combined length exceeds this limitation, the function will fail. This function will obey the video access method selected. Windows For Clipper Page 27 Arguments window - Window number returned by the _SINIT_WN() function. arg1 - A database field name, memory variable, character constant, or function returning a character result. If a field is specified, the database in which the fields are accessed must be open. If the database is not in the current selected area, an ALIAS prefix must be used. Example: CUSTINFO->COMP_NAME ^Alias prefix. [arg2, arg3,....] - Optional arguments. The above applies here also. Returns TRUE - If write was successful. FALSE - If the write was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 28 _SWTE_PTR(window, target row, direction) Synopsis This function will write a pointer in the window specified. Two pointer types are available, please refer to the _SST_PTSL() function reference to determine what the pointer types are. The pointer color can also be set. This function will determine the current color and use it. Please refer to the _SST_PTCL() function reference to determine how to set the pointer colors. A pointer in a window can be used for several different reasons. Highlight text as it is being read is one example. The _WN_DBF() function use the pointer to indicate which record the user is currently resting on. If order to use this function here are a few things you must know. If pointer type 1 is selected, you must prefix all text written to the window with 2 spaces. Pointer type 1 is an arrow that points to the right. It occupies the first 2 character positions in a window. You will need to prefix all text written to the window with 2 spaces. This will provide the space required to accommodate the pointer. If pointer type 2 is selected, no extra space is needed. This pointer is a bounce bar and starts at the first column in the window and fills the entire length of the window. It will not disturb the text that occupies the window. When calling this function, you must indicate the direction in which the pointer is being moved. If this is the first call to the function and no direction has yet been established, you indicate "N" for none. If you have a pointer at the last row in a window, and wish to move to the pointer to the previous row, you indicate "U" as the direction. And of course, if you wish to move the pointer down in a window, you indicate "D". The direction of movement and the target row are used to determine what the function must do to erase the previous pointer written in a window. You should never move the pointer more than one row up or down at a time. If this occurs the function will not be able to remove the previous pointer. You should never select a different pointer type after calling this function for the first time. This will result in a very peculiar looking window. If a window is erased, or has no pointer in it, you can safely change the pointer type to suit your needs. If pointer type 2 is selected, the function will use DMA as the video access method. This is not selectable. If pointer type one is selected, the function will obey the video access method selected. Windows For Clipper Page 29 Arguments window - Window number returned by the _SINIT_WN() function. target row - the row the pointer will be written in. The row is relative to the window dimensions. That is, row 0 represents the first writable row in a window. direction - the direction in which the pointer will be moved. valid responses are: "U", "D", and "N". Returns TRUE - If pointer written succesfully. FALSE - If pointer not written successfully. If this occurs it is usually because the function received an invalid argument. Windows For Clipper Page 30 _SCLS_WN(window) Synopsis This function will clear the contents of a window. When the window is cleared, the row offset is reset to row 1. If a vertical scroll value has previously been set, it will not be changed. The vertical scroll value must be explicitly changed by making a call to the _SCRL_VERT() function. Please refer to the _SCRL_VERT() functions synopsis for an explanation of this function. If you changed the color by calling the _SST_WNCL() function prior to calling this function, the windows content color will be changed to that specified when this function is called. This will not affect the border color of the window. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. Returns TRUE - If the window was cleared successfully. FALSE - If the window clear was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 31 _SCRL_VERT(window, number of characters) Synopsis This function will cause any text written to a window to scroll left or right. The scroll vertical function will not affect any text written in the window, prior to calling the function. All text written to a window after this function is called will scroll in the appropriate direction. To reset vertical scrolling to "No Scroll", a value of 0 should be passed to the function. Arguments window - Window number returned by the _SINIT_WN() function. number of characters - The number of characters to scroll. If left scroll is desired, a negative value is supplied. If right scroll is desired a positive value is supplied. To reset for "No Scroll", a 0 is supplied. Example - _SCRL_VERT(window, -5) This will scroll text left 5 characters. Example - _SCRL_VERT(window, 5) This will scroll text right 5 characters. Returns TRUE - If the scroll was successful. FALSE - If the scroll was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 32 _SCRL_HORZ(window, number of lines) Synopsis This function will cause any text written to a window to scroll up or down. If a scroll up request is made, the top line in the window will be lost and all lines below it will move up. Likewise, if a scroll down request is made, the bottom row in the window will be lost and all lines above it will be moved down. When scrolling up, the cursor offset in the window is reset to the first row of the window. When scrolling down, the cursor offset in the window is reset to the last row of the window. Arguments window - Window number returned by the _SINIT_WN() function. number of lines - The number of lines to scroll. If an up scroll is desired, a positive value is supplied. If a down scroll is desired a negative value is suppplied. Example - _SCRL_HORZ(window, 5) This will scroll text up 5 lines. Example - _SCRL_HORZ(window, -5) This will scroll text down 5 lines. Returns TRUE - If the scroll was successful. FALSE - If the scroll was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 33 _SWNERASE(window) Synopsis This function erases a window from the screen. If stacked (tiled) windows are on the screen, the topmost window must be erased first. All subsequent erasures must be done in the same manner. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. Returns TRUE - If the erasure was successful. FALSE - If the erasure was unsuccessful. If this occurs, it is because the function received invalid arguments. Windows For Clipper Page 34 _WNSAVE(window, filename) Synopsis This is a special purpose function that allows the text stored in a window to be saved in a Clipper MEM file. The complete contents of a window are saved including the color of the window contents. If the MEM filename specified exists, the contents of the MEM file will be lost and the new information stored in it. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. filename - A valid DOS filename. If an extension is not specified, WFC will be used as the default. The filename argument must be delimited with quote marks. Example : _WNSAVE(wn, "TEST") Returns TRUE - If the function was successful in reading and saving the windows contents. FALSE - If the function was not successful in reading and saving the windows contents. This return usually occurs if the the target window is not on the screen. Windows For Clipper Page 35 _WNRESTORE(window, filename) Synopsis This is a special purpose function that restores the contents of a window that was previously saved by the _WNSAVE() function. The target window must be on the screen and the same size as the original window the _WNSAVE() function used to save the information. If the window size differs, unpredictable results may occur. Arguments window - Window number returned by the _SINIT_WN() function. filename - A valid DOS filename. If an extension is not specified, WFC will be used as the default. The filename argument must be delimited with quote marks. Example : _WNRESTORE(wn, "TEST") Returns TRUE - If the function was successful in writing the saved contents back to the window. FALSE - If the function was not successful in writing the contents back to the window. This usually occurs if the target window is not on the screen, or the indicated file can not be found. Windows For Clipper Page 36 _WNGETBUF(window, buffer) Synopsis This is a special purpose function that reads the contents of a window and stores it into a buffer. This is the low level function used by the _WNSAVE function. The buffer must be initialize to a size that will hold the contents of the window. The buffer format is as follows: 1st byte .... character in the first column and first row in the window. 2nd byte .... color attribute of the specified window. All subsequent bytes follow this same pattern. The size of window buffer required can be calculated as follows: buffer size = (number of rows * number of columns) * 2 Example of buffer initialization: buffer = SPACE((numrow * numcols) * 2) or buffer = SPACE((_SWN_ROW(window) * _SWN_COL(window)) * 2) If the buffer space is not large enough, unpredictable results will occur. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. buffer - A Clipper initialized memory variable that will be used to store the contents of the window. Returns TRUE - If the function was successful in storing the window contents in the buffer. FALSE - If the function was unsuccessful in store the window contents in the buffer. This will usually occur if the target window is not on the screen, or invalid arguments were received by the function. Windows For Clipper Page 37 _WNPUTBUF(window, buffer) Synopsis This is a special purpose function that writes the contents of a buffer created by the _WNGETBUF() function, to a window. The target window should be the same size as the target window that was used to create the buffer. A standard string can not be written to a window with this function. The function expects the buffer to have the same format as that created by the _WNGETBUF() function. Please refer to the _WNGETBUF() fucntion for further information on the buffer format. This function will obey the video access method selected. Arguments window - Window number returned by the _SINIT_WN() function. buffer - A Clipper initialized memory variable whose contents was placed there by the _WNGETBUF() function. Returns TRUE - If the function was successful in writing the contents of the buffer to a window. FALSE - If the function was unsuccessful in writing the buffer contents in the window. This will usually occur if the target window is not on the screen, or invalid arguments were received by the function. Windows For Clipper Page 38 _WN_DBF(window, "field" [,"field","field".....]) Synopsis This is a special purpose function that allows a database to be viewed through a window. The function takes control of the keyboard and provides maneuverability through the database. Record selection can be accomplished using this function. All an operator has to do is point to the record desired and press return. The function requires the following: 1. A valid window number that has been initialized and drawn by the _SINIT_WN(), and _SDRW_WN() functions respectively. 2. The database being windowed must be the selected database in use. Suppose you have two databases open and you wish to display field information from area 1. This section of code would be required for the function to operate properly: *** open files SELECT 1 USE DATA1 SELECT 2 USE DATA2 *** window view of DATA1 SELECT 1 _WN_DBF(window, "customer", "address", "city", "state", "zip") This will display fields from the current area with the above field names. In the above example, all field names specified are character type fields. The quotes around the field names are required. There are exceptions to this, which are documented below. The type of pointer used by this function is selectable. Two pointer types are available. Please refer to the _SST_PTSL() function for more information. Character and logical fields are directly supported by the function. Logical fields do not display as .T. or .F., instead they are displayed as 'Y' for true (.T.) and, 'N' for false (.F.). To indicate one of these fields simply enclose the field name in quotes. Expressions are allowed, as long as the result is a character or character string. Numeric and date fields can be accessed by this function only if a method/function of converting the field to a character or character string is provided. The technique to accomplish this is usually another function call. The _WN_DBF() function will implement the method/function specified through macro expansion. Windows For Clipper Page 39 Clarification as to a method/function. -------------------------------------- A method is an action that is not strictly categorized as a function but still results in a character or character string result. This can best be describe in the following line of code: IF field1 and field2 are character type fields: "field1 + field2" <--- This is called concatenation. As can be seen, this will still result in a character or character string. There may be other methods, but this should serve as a good example. Functions should not need clarification. For those that do not fully understand what a function is or does, most programming reference works that deal with the 'C' language can give you a complete description. It is beyond the scope of this reference to do so. The handling of data conversion from numeric to character and date to character is implemented in a fashion to allow more flexibility to the programmer. Clipper provides a good set of conversion routines but they are not the only routines available. The design of this function allows the programmer to specify the method/function to use. These methods/functions can be Clipper internal routines, routines of your own design, or routines acquired by you. Due to this flexibility, certain precautions must be taken. Precautions to be aware of: 1. If the method/function is not a Clipper internal routine, it is suggested that an 'EXTERNAL method/function name' declaration line be placed somewhere within your application to insure it is included during the link phase. EXAMPLE: EXTERNAL LOGTOCHR 2. The programmer should fully understand what the return result should be from any method/function used for data conversion. The method/function MUST return a character or character string value. 3. The method/function can not be a procedure. Procedures are not supported. Windows For Clipper Page 40 4. You must follow the section describing the syntactical requirements found below. The above describes the data conversion methods using numeric and date fields as a reference. Be aware that data conversion is not strickly limited to those field types. Although the above discussion does apply to the numeric and date field types, you may also provide a method/function for conversion of logical fields or special formating of character fields. For instance, if you require a more verbose display of logical fields than what is supplied by this function, you may create your own function for this purpose and specify it as the data conversion method/function to use. The bottom line is this; Any method/function that returns a character or character string result should work. Syntactical requirements for data conversion. --------------------------------------------- Two methods are available if data conversion is to be used. Please keep in mind that character and logical type fields are directly supported by this function. In the following descriptions, 'wn' refers to a valid window number returned by the '_SINIT_WN()' function, 'name' refers to a character field and 'number' refers to a numeric field. Method 1. --------- This is called the 'DIRECT' method. It is preferrable if you require readable code at the expense of flexibility. Example: rec = _WN_DBF(wn, "name", "STR(number)") ^^^^^^^^^^^^^ In this example, the STR() function will be used for data conversion. Note the quotes surrounding the parameter; these quotes are required. If the quotes are not present, the application will experience a type conflict error. This is the same method used for direct support of the character and logical field types. The difference being, a function is part of the quoted parameter. Windows For Clipper Page 41 Method 2 -------- This is called the 'INDIRECT' method. It is preferable if you require flexibility at the expense of readability. Example: memvar = "STR(number)" rec = _WN_DBF(wn, "name", memvar) In this example, the STR() function will be used for data conversion. Note that quotes do not surround the parameter containing the method/function string. If quotes are placed around the memory variable 'memvar', no error will occur, the function will simply display the contents of the memory variable in the window. Parameter checking is at a minimum in this function. The programmer must bear most of the responsibility to insure the proper parameter values are passed. The function does check the parameters passed to it, and these parameters must be passed in sequence. The following construct would be invalid: recs = _WN_DBF(wn1, "customer", ,"address", "city") (missing ^ parameter) If parameters were passed as above, unpredictable results may occur. This function will try to recover and provide function integrity. This is not guaranteed. As of this writing, you cannot specify a scope with this function. Meaning that this construct would be invalid: _WN_DBF(window, "field1", "field2") for city = "ATLANTA" You can set a filter, and the function will respect said filter, until such time as it is removed. If a filter is set, a delay may be detected when moving from one record to another. This delay is not caused by the _WN_DBF() function, but the filter command itself, as it moves through the database trying to decide if the record qualifies. It is quite possible that no records pass the filter, therefore no field information will be displayed in the window. It is not necessary that the window be the same width or wider than the field information that will be written. If the field information is wider than the window, it will be truncated to fit the window. The information in the database is not effected. The field information is truncated for writing to the screen only. The total combined length of all fields specified can not exceed 512 characters. This restriction is the same as the _SWTE_RECS() function. Windows For Clipper Page 42 Maneuvering through the database is accomplished through the use of the special keys on the numeric key pad. The "Up", and "Down" arrow keys allow moving from record to record. If the "Up" arrow key is pressed, the database record pointer will be moved to the previous record. If the "Down" arrow key is pressed, the database record pointer will be moved to the next record. Depending on the pointer position in the window, the field information may be scrolled up or down, whichever is appropriate. The "Left" and "Right" arrow keys allow panning left or right through the field information specified. If the "Left" arrow key is pressed, the field on the left side of the window will be scrolled off the screen and all other field information will be shifted to the left. Any field information on the right that was not visible, can now be seen. Pressing the "Right" arrow key has the opposite effect. The "Home" and "End" keys move the record pointer to the first and last record displayed in a window. The "^Home" and "^End" (^ = Control) keys will move the record pointer to the top or bottom of the database respectively. The "PgUp" and "PgDn" down keys allowing paging through the database. The page size is dependant on the size of the window. If you have a window consisting of 10 rows, then the page size will be 10. If a window consists of 5 rows, then the page size will be 5 etc. If a vertical scroll has occurred, it remains in effect. The movement through the database, regardless of the key pressed, will maintain the current scroll setting. Record selection can be accomplished by pressing the enter key after pointing to the desired record or, if no record is desired pressing the ESCape key will cause the function to return a 0. It is up to the calling process to take appropriate action depending on the return value of this function. Arguments window - Window number returned by the _SINIT_WN() function. "field" - Field or data conversion method/function name to display. Please refer to the above text for an explaination of data conversion techniques. [,"field","field"...] - Up to 9 more fields or data conversion methods/functions may be specified for a total of 10, whose combined length does not exceed 512 characters. Return Record number - The function will return the record number of the or 0 record currently being pointed to if the return key is pressed, or 0 if the escape key is pressed. Windows For Clipper Page 43 Other Functions --------------- _BIGSTR(String, col, row [, color code string, VAM]) Synopsis This function will write BIG strings to the screen. The size of each character is 8 columns wide and 8 rows long. This function can be used to create attractive startup screens etc. Maximum safe string size is 10 characters. This is due to the size of each character that is printed. The color control string and VAM are optional. If not specified, the default will be white characters as the color and, DMA as the video access. Arguments string - The string to be printed. col - starting column coordinates. Adjust the starting column coordinates or the string size to insure the character will not exceed the screen boundaries. row - starting row coordinates. You should not specify a row coordinate higher than 16. If you do, the characters will exceed the screen boundaries. color code string - Character variable containing a string representing the color code. The color code string takes the following form. <foreground/intensity/blinking> You may use any character to separate the color code string, but a slash is recommended. NOTE: Only the foreground color is specified as a parameter to this function. If you wish to set the background color to something other than White on Black, use the Clipper SET COLOR TO statement. The following are the codes used for color selection. A == BLACK B == BLUE G == GREEN C == CYAN R == RED M == MAGENTA O == BROWN W == WHITE L == BLINKING H == HIGH INTENSITY Refer to the _WN_DBF() function for examples of specifying a color code string. VAM - Video access method to use. Valid arguments are: 1. For direct memory access. 0. For BIOS access. Windows For Clipper Page 44 Returns TRUE - If the function was successful in writing the string. FALSE - If the function was unsuccessful in writing the string. This will occur if the function receives invalid arguments. Windows For Clipper Page 45 _NEWCOLOR(start col, start row, end col, end row, color code string) Synopsis This function will change the color in the specified area of the screen. It will not disturb any text that may occupy the target area of the screen. This function uses only DMA as the access method. Arguments start col - The column in which to start the color change. start row - The row in which to start the color change. end col - The column in which the color change will end. end row - The row in which the color change will end. color code string - Character variable containing a string representing the color code. The color code string takes the following form: <background/foreground/intensity/blinking> You may use any character to separate the color code string, but a slash is recommended. The following are the codes used for color selection. A == BLACK B == BLUE G == GREEN C == CYAN R == RED M == MAGENTA O == BROWN W == WHITE L == BLINKING H == HIGH INTENSITY Refer to the _WN_DBF() function for examples of specifying a color code string. Returns TRUE - If the function changed the area as specified. FALSE - If the function could not change the area as specified. This usually occurs if the function received invalid arguments.