DP Tool Club 19

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

/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / dos / prg / c / cwl30 / cwl3docs / manual.doc < prev

Wrap

Text File | 1994-10-16 | 738KB | 20,653 lines

@ME.FORMAT R THE C WINDOW LIBRARY (c) Copyright P. A. McKenzie 1990, 1991, 1992, 1993, 1994 All Rights Reserved Version 3.00a T A B L E O F C O N T E N T S PRELIMINARIES .......................................... i Microsoft C ......................................... i Turbo C/C++ / Borland C++ ........................... ii Global Variables .................................... iv INTRODUCTION ........................................... 1 Defining Windows .................................... 1 Properties of Windows ............................... 1 Writing to Overlapping Windows ...................... 2 Top-Level, Child, and Desktop Windows ............... 2 Window Ranks ........................................ 2 Detection of Video Hardware ......................... 3 Window Coordinates .................................. 3 Client Area ......................................... 4 Video Attributes .................................... 4 Direct Screen Writes and BIOS Screen Updates ........ 5 Video Paging ........................................ 6 Error Codes ......................................... 7 Window Manager ...................................... 7 MANDATORY FUNCTIONS AND HEADER FILES ................... 8 WindowInitializeSystem() ............................ 8 CREATING WINDOWS ....................................... 9 The CWLWINDOW structure and WPOINTER structure ...... 9 WindowInitDesktop() ................................. 9 WindowInitialize() .................................. 10 CREATE_VIDEO_ATTRIBUTE() macro ...................... 11 Box types ........................................... 12 DISPLAYING WINDOWS ..................................... 14 The WindowDisplay() function and Explosion Effects .. 14 Displaying Multiple Windows ......................... 17 CLOSING WINDOWS ........................................ 19 WindowClose() ....................................... 19 WindowCloseAll() .................................... 20 WindowUninitSystem() ................................ 21 CENTERING WINDOWS ON THE SCREEN ........................ 22 WindowCenter() ...................................... 22 The C Window Library CHANGING WINDOW CHARACTERISTICS ........................ 24 WindowChangeTextAttribute() ......................... 24 WindowChangeBorderAttribute() ....................... 25 WindowDrawBorder() .................................. 25 WindowRemoveBorder() ................................ 27 WindowResizeHeight() ................................ 27 WindowResizeWidth() ................................. 28 WRITING TEXT TO WINDOWS ................................ 30 Null Terminated Write Functions ..................... 30 WindowWriteString() .............................. 30 WindowWriteStringAttr() .......................... 31 WindowWriteCenterString() ........................ 32 WindowWriteCenterStringAttr() .................... 33 WindowWriteStringCC() ............................ 33 WindowWriteStringCCAttr() ........................ 34 WindowWriteStringRJ() ............................ 35 WindowWriteStringRJAttr() ........................ 36 Length Controlled Write Functions.................... 37 WindowWriteCharacters() .......................... 37 WindowWriteAttributes() .......................... 38 WindowWriteCharAndAttr() ......................... 39 WindowWriteCharactersAttr() ...................... 40 WindowWriteRepeatAttribute() ..................... 41 WindowWriteRepeatCharacter() ..................... 42 Formatted Write Functions ........................... 43 Where output is placed in the window ............. 43 WindowSetWrap() .................................. 43 WindowPrintf() ................................... 44 WindowPrintfAttr() ............................... 45 WRITING TITLES TO WINDOWS .............................. 47 WindowTitleTop() .................................... 48 WindowTitleBottom() ................................. 49 WindowTitleTopAttr() ................................ 50 WindowTitleBottomAttr() ............................. 51 READING CHARACTERS AND ATTRIBUTES FROM WINDOWS ......... 53 WindowReadCharacters() .............................. 53 WindowReadAttributes() .............................. 54 WindowReadCharAndAttr() ............................. 55 HIDING WINDOWS ......................................... 57 WindowHide() ........................................ 57 CREATING COPIES OF A WINDOW ............................ 59 WindowCopy() ........................................ 59 The C Window Library SCROLLING TEXT IN WINDOWS .............................. 61 WindowScroll() ...................................... 61 WindowScrollRegion() ................................ 62 WindowScrollAttr() .................................. 63 WindowScrollRegionAttr() ............................ 64 CLEARING WINDOWS ....................................... 66 WindowClear() ....................................... 66 WindowClearAttr() ................................... 67 WindowClearRegion() ................................. 67 WindowClearRegionAttr() ............................. 68 WRITING WINDOW CONTENTS TO A FILE ...................... 70 WindowWriteTextToFile() ............................. 70 SHADOWING WINDOWS ...................................... 72 WindowDrawShadow() .................................. 72 WindowRemoveShadow() ................................ 74 SEE-THRU WINDOWS ....................................... 75 WindowMakeSeeThru() ................................. 75 WindowMakeNormal() .................................. 76 MOVING AND SLIDING WINDOWS ............................. 77 WindowMove() ........................................ 77 WindowSlide() ....................................... 78 CURSOR POSITIONING IN WINDOWS .......................... 79 Cursor Maintenance in The C Window Library .......... 79 Creating Cursor Shapes .............................. 79 WindowChangeCursor() ................................ 79 WindowMoveCursor() .................................. 80 WindowGetCursorShape() .............................. 81 WindowGetCursorPosition() ........................... 82 GETTING WHICH WINDOW OCCUPIES A LOCATION ............... 84 WindowWhich() ....................................... 84 GETTING INPUT FROM WINDOWS ............................. 85 Input Manager ....................................... 85 Regular Expressions ................................. 85 Editing Input ....................................... 90 Last Key Value ...................................... 92 Default Cursor Types and Editing Mode ............... 92 Editing using a character mask ...................... 93 The C Window Library Editing Functions ................................... 94 WindowGetString() ................................ 94 WindowGetStringAttr() ............................ 97 WindowGetMaskString() ............................ 98 WindowGetMaskStringAttr() ........................ 99 Getting Passwords ................................ 100 WindowGetPassword() ........................... 101 WindowGetPasswordAttr() ....................... 102 WindowGetMaskPassword() ....................... 102 WindowGetMaskPasswordAttr() ....................103 Undefined Keystroke Processing ................... 104 The CWLundef_fkey_func and CWLundef_akey_func_ function pointers ................. 104 Specifying when to call an undefined key function in a Regular Expression ...... 106 Return Values To The Input Manager .......... 106 Input Options .................................... 109 CHECKREGEXP and the reg_exp_error_func function pointer ........................... 110 THE CWLchars_entered_func function pointer ....... 113 Other Input releated functions ................... 114 TranslateStringToMaskString() .................... 114 TranslateMaskStringToString() .................... 116 CHILD WINDOWS .......................................... 118 Creating Child Windows with WindowSetParent() ....... 119 Translation of Child Coordinates .................... 120 Enumerating Child Windows ........................... 123 Testing Window Relationships ........................ 125 Testing Window Ranks ................................ 126 VIRTUAL WINDOWS ........................................ 127 Using Windows as Viewports .......................... 127 Attributed and Non-Attributed Virtual Windows ....... 127 Virtual Window's Logical Cursor ..................... 128 CREATING VIRTUAL WINDOWS ............................ 129 VirtualInitialize() .............................. 129 ASSIGNING VIEWPORTS AND CLOSING VIEWPORTS ........... 131 WindowAssignToVirtual() .......................... 131 Out of bounds Coordinates ........................ 132 WindowCloseViewport() ............................ 133 WRITING TEXT TO VIRTUAL WINDOWS ..................... 135 Null Terminated String Functions ................. 135 VirtualWriteString() .......................... 135 VirtualWriteStringAttr() ...................... 136 VirtualWriteCenterString() .................... 137 VirtualWriteCenterStringAttr() ................ 138 VirtualWriteStringCC() ........................ 139 VirtualWriteStringCCAttr() .................... 140 VirtualWriteStringRJ() ........................ 141 VirtualWriteStringRJAttr() .................... 141 The C Window Library Length Controlled Functions ...................... 142 VirtualWriteCharacters() ...................... 142 VirtualWriteAttributes() ...................... 143 VirtualWriteCharAndAttr() ..................... 144 VirtualWriteRepeatAttribute() ................. 145 VirtualWriteRepeatCharacter() ................. 146 Formatted Write Functions ........................ 147 Format String ................................. 147 Where Output is Placed ........................ 148 VirtualSetWrap() .............................. 148 VirtualPrintf() ............................... 149 VirtualPrintfAttr() ........................... 149 READING CHARACTERS AND ATTRIBUTES FROM VIRTUAL WINDOWS .............. 151 VirtualReadCharacters() .......................... 151 VirtualReadAttributes() .......................... 152 VirtualReadCharAndAttr() ......................... 153 REPOSITIONING THE VIEWPORT .......................... 155 WindowPositionViewport() ......................... 155 SCROLLING THE VIEWPORTS ............................. 159 WindowScrollVirtual() ............................ 159 WRITING VIRTUAL WINDOW CONTENTS TO A FILE ........... 162 VirtualWriteTextToFile() ......................... 162 MOVING THE LOGICAL CURSOR ........................... 164 VirtualMoveCursor() .............................. 164 VirtualGetCursorPosition() ....................... 165 CLEARING VIRTUAL WINDOWS ............................ 166 VirtualClear() ................................... 166 VirtualClearAttr() ............................... 167 VirtualClearRegion() ............................. 168 VirtualClearRegionAttr() ......................... 169 FREEZING VIEWPORTS .................................. 170 WindowFreeze() ................................... 170 DISPOSING OF VIRTUAL WINDOWS ........................ 172 VirtualClose() ................................... 172 The C Window Library INTRODUCTION TO MENU SYSTEM ............................ 174 Menu Manager ........................................ 174 POP-UP MENUS ........................................ 175 Description ...................................... 175 CREATING POP-UP MENUS ............................... 176 The PopupCreateMenu() function ................... 176 Creating Popup Menu Entries ...................... 179 Inserting Multiple Entries ....................... 183 Inserting a Popup Menu Within a Popup Menu ....... 185 Deleting Menu Entries ............................ 187 Initializing the size of the Virtual Window and and Viewport Window ........................... 188 SELECTING FROM POPUP MENUS .......................... 191 PopupSelectMenu() function ....................... 191 Values passed to menu function ................ 193 Values returned to menu manager ............... 193 SETTING OPTIONS IN POPUP MENUS ...................... 194 The PopupSetOptions() function ................... 194 Setting Multiple Options ...................... 194 Getting Menu Options .......................... 195 DISABLING POPUP MENU ENTRIES ........................ 196 Disabling and Enabling Entries ................... 196 CHANGING THE MENU ENTRY STRINGS ..................... 197 PopupSetEntryString() function ................... 197 CHECKING POPUP MENU ENTRIES ......................... 198 PopupCheckEntry() ................................ 198 REDEFINING MENU KEYS ................................ 199 Setting Global Key Definitions and the popup_key_definition Array ............ 199 Setting Local Key Definitions .................... 200 PopupAssignKeys() function .................... 200 PROCESSING UNDEFINED KEYS ........................... 201 The CWLpopup_undef_key_func function pointer ..... 201 Values returned to menu manager ............... 201 PRE-INPUT FUNCTION .................................. 205 Setting the CWLglobal_popup_prefunc function pointer .............. 205 The C Window Library DISPOSING OF POPUP MENUS ............................ 207 PopupMenuClose() ................................. 207 BAR MENUS .............................................. 208 Description ......................................... 208 CREATING BAR MENUS .................................. 209 BarCreateMenu() ................................. 209 Creating Bar Menu Entries ....................... 212 Inserting Multiple Entries ...................... 215 Deleting Menu Entries ........................... 216 SELECTING FROM BAR MENUS ............................ 218 BarSelectMenu() function ......................... 218 Values passed to menu function ................ 220 Values returned to menu manager ............... 220 SETTING OPTIONS IN BAR MENUS ........................ 221 The BarSetOptions() function ..................... 221 Setting Multiple Options ...................... 221 Getting Menu Options .......................... 222 ENABLING AND DISABLING BAR MENU ENTRIES ............. 223 Disabling and Enabling Entries ................... 223 CHANGING THE MENU ENTRY STRINGS ..................... 224 BarSetEntryString() function ..................... 224 REDEFINING MENU KEYS ................................ 225 Setting Global Key Definitions and the CWLbar_key_def Array ................... 225 Setting Local Key Definitions .................... 225 BarAssignKeys() function ...................... 226 PROCESSING UNDEFINED KEYS ........................... 227 The CWLbar_undef_key_func function pointer ....... 227 Values returned to menu manager .................. 227 PRE-INPUT FUNCTION .................................. 230 Setting the CWLglobal_bar_prefunc function pointer ........ 230 DISPOSING OF BAR MENUS .............................. 232 BarMenuClose() function .......................... 232 The C Window Library PULLDOWN MENUS ......................................... 233 Description ......................................... 233 Bar Menu and Popup Menu levels ...................... 233 CREATING PULLDOWN MENUS ............................. 234 The PulldownCreateMenu() function ................ 234 Adding and Inserting menu entries ................ 235 Deleting Menu Entries ............................ 236 SELECTING MENU ENTRIES .............................. 237 The PulldownSelectMenu() function ................ 237 DISPOSING OF PULLDOWN MENUS ......................... 238 USING BAR MENU FUNCTIONS ............................ 238 USING POPUP MENU FUNCTIONS .......................... 239 EXAMPLE OF PULLDOWN MENU SYSTEM ..................... 239 Key Definitions for Pulldown Menus ............... 245 MISCELLANEOUS FUNCTIONS ................................ 247 SETTING AND CHECKING VIDEO PAGES .................... 248 CheckVideoPage() ................................. 248 SetActiveVideoPage() function .................... 248 SetVisibleVideoPage() function ................... 249 GENERAL STRING WRITING FUNCTIONS .................... 251 VideoWriteString() ............................... 251 VideoWriteStringAttr() ........................... 252 VideoWriteAttributes() ........................... 252 VideoWriteCenterString() ......................... 253 VideoWriteCenterStringAttr() ..................... 254 VideoWriteCharAndAttr() .......................... 254 VideoWriteStringCC() ............................. 255 VideoWriteStringCCAttr() ......................... 256 VideoWriteStringRJ() ............................. 256 VideoWriteStringRJAttr() ......................... 257 VideoPrintf() .................................... 258 VideoPrintfAttr() ................................ 258 READING CHARACTERS AND ATTRIBUTES FROM THE SCREEN ... 260 VideoReadCharacters() ............................ 260 VideoReadAttributes() ............................ 260 VideoReadCharAndAttr() ........................... 261 The C Window Library DRAWING BOXES ....................................... 262 VideoDrawBox() ................................... 262 VideoDrawBoxAttr() ............................... 262 SAVING AND RESTORING SCREEN IMAGES .................. 264 VideoSave() ...................................... 264 VideoMove() ...................................... 265 VideoRestore() ................................... 265 VideoFree() ...................................... 266 CLEARING SCREENS .................................... 267 ClearScreen() .................................... 267 ClearRegion() .................................... 267 SCROLLING SCREENS ................................... 269 ScrollScreenUp() ................................. 269 ScrollScreenDown() ................................269 CHANGING THE VIDEO MODE ............................. 271 SetVideoMode() ................................... 271 CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN .............. 272 Changing rows .................................... 272 AdjustScreenInfo() ............................ 272 AdjustGlobalData() ............................ 273 SetVideoRows() ................................ 273 Changing columns ................................. 276 40 column and 80 column modes ................. 276 Modes higher than 80 columns .................. 277 CURSOR MANIPULATION ................................. 279 MoveCursor() ..................................... 279 ChangeCursor() ................................... 279 GetCursorShape() ................................. 280 GetCursorPosition() .............................. 280 HideCursor() ..................................... 281 BlockCursor() .................................... 281 ThinCursor() ..................................... 281 GETTING VIDEO INFORMATION ........................... 283 VIDEO_CONFIG structure ........................... 283 GetVideoBiosInfo() ............................... 283 TIMED DELAYS ........................................ 285 delay() .......................................... 285 The C Window Library SOUND FUNCTIONS ..................................... 286 sound() and nosound() ............................ 286 MakeSound() ...................................... 286 ERROR HANDLING ...................................... 288 The CWLerror_func function pointer ............... 288 USING A MOUSE WITH THE C WINDOW LIBRARY ............. 291 Installing the Mouse Library ..................... 291 Include Files .................................... 291 Initializing the Mouse with MouseInitializeSystem().......... 291 Turning off the mouse with MouseRestoreSystem() .. 292 Using a mouse with popup menus ................... 293 Popup Menu's prefunction for mouse ........... 295 Using a mouse with bar menus ..................... 295 Using a mouse with pulldown menus ................ 295 Changing the mouse defaults ...................... 295 WINDOW AND VIRTUAL WINDOW MACROS .................... 297 MENU MACROS ......................................... 300 Popup Menu Macros ................................ 300 Bar Menu Macros .................................. 302 Pulldown Menu Macros ............................. 303 VIDEO MACROS ........................................ 304 KEYBOARD MACROS ..................................... 308 Keyboard Idle Function ............................ 309 Keyboard Intercept Function ....................... 310 Checking for mouse presses ........................ 311 ERROR CODES ......................................... 313 IMPORTANT GLOBAL VARIABLES ............................. 314 INDEX .................................................. 327 The C Window Library PRELIMINARIES ------------- Congratulations on using The C Window Library (CWL); an easy to use, powerful, inexpensive C user interface library! Before we start talking 'C', we will discuss briefly on how to compile and link programs using The C Window Library. The following introduction is very brief. For more in depth information on make files, project files, link options, etc. please consult the various documentation supplied with the compiler that you are working with. The default word/byte alignment scheme was used when compiling all the libraries. In other words, all modules used by The C Window Library were compiled without the use of the word/byte alignment switch being used. Please read the README!!.1 and README!!.2 files for any items changed/corrections that have been made to this manual. Microsoft / Quick C ------------------- When compiling your programs, you must make sure that the constant MSC is defined. An example of how you would do this as follows: cl -Ax -DMSC -Ihfiles prog1.c /link /SE:1000 mcwinx.lib the -Ax is the model used for compilation. The x stands for either S for small, M for medium, C for compact, or L for large. The -D option defines a constant, which in this case is MSC. You must use the -D switch with MSC as the constant. If not, you will get either syntax errors, link errors, or runtime errors. The -I option tells the compiler that the .h files are located in a directory on the default drive called hfiles. The /link option links the resulting object files (prog1.obj) with The C Window Library file mswinx.lib, where x stands for S, M, C, or L. The /SE segment switch is a mandatory switch when linking the CWL libraries. The value that is usually used is 1000, but you can experiment with different values. The other method is to create a make file. If you are using the integrated environment of Quick C or using the Programmers Work Bench (PWB) for Microsoft C 6.0+ or Visual C++, you can create your make files by selecting the files you want to compile, and the libraries you want to link with and letting these integrated environments create the make file automatically. If you are more advanced you can create your make files by yourself without the aid of these programs. Consult the documentation for more information on make files. i Turbo C/TurboC++/Borland C++ ---------------------------- The command to compile and link programs using the Turbo C 2.0, Turbo C++ 1.0 and higher, or Borland C++ 2.0 or higher, the following command is to be used for the specified compiler: Borland C++: bcc -mx -Ihfiles prog1.c bcwinx.lib Turbo C++, Turbo C: tcc -mx -Ihfiles prog1.c bcwinx.lib the -mx is the model used for compilation. The x stands for either S for small, M for medium, C for compact, or L for large. The -I option tells the compiler that the .h files are located in a directory on the default drive called hfiles. If you are using Turbo C or Turbo C++, replace bcc with tc or tcc. If you will use the integrated environment, you must create a project file. This project file specifies the source code modules, object code modules, and libraries that will be linked in to produce an executable file. If you use the Turbo C Version 2.0 integrated environment, you must/ edit this file yourself. If you use the Turbo C++ or Borland C++ integrated environment, use the automatic Project File creator. You can also use make files to link in your program. Make sure that the desired library from The C Window Library is specified. You can also use the TCC.EXE (or BCC if you are using Borland C++) command line compiler with the desired library specified on the command line. Consult the Turbo C/C++ documentation on using make files and using the integrated environment. The default structure alignment was used to compile the libraries, which is byte alignment. An example of using the TCC.EXE (BCC.EXE) command line is as follows: tcc -mm -G -r -ihfiles prog1.c bcwinm.lib The following command line uses -mm for the medium memory model, -G to optimize for speed, -r for usage of register variables, and -i to tell the compiler that the header files are located in a directory on the default drive called hfiles. iii GLOBAL VARIABLES ---------------- The global variables used by The C Window Library follow a consistent naming convention. All global variables start with the three letters 'CWL'. For instance, CWLscreen_rows is a global variable in The C Window Library to denote the number of rows visible on the screen. This naming convention is used so that there is virtually no chance that you will invent a variable name in your program that matches one used in the library. If you stay away from starting your user variable names with 'CWL', duplication is impossible. All global variables are stored in the CWLGLOB.H header file. If you are curious, you can peruse this file to see what the global variables are. iv INTRODUCTION ------------ Defining Windows ---------------- A window is an area of the screen that is separate and independent from the other areas of the screen. With windows, you can scroll, write text, delete text, etc. in a defined section of the screen. An example of windows in application programs are the resident memory utilities that pop up on the screen when invoked, and restore the text to its original state when the resident application is terminated. Sidekick is a good example of what you can do with windows. As a matter of fact, most professional programs use windows in some manner. Some applications use windows to make pulldown menus i.e. the integrated environment in the Borland compilers. Other applications such as text editors and word processors use windows to display and edit a files contents. With The C Window Library, you can create professional looking application program easily and without worrying about the tricky details of window management. At your disposal are tools that can help you create pull-down menus, popup menus, bar menus, and just fast output. Properties of Windows --------------------- Windows should have the following properties: - more than one window can be displayed on the screen simultaneously. - windows are allowed to overlap without disturbing the contents of the windows underneath. - a window that is under a pile of windows can be brought to the top. - a window that is under a pile of windows can be written to without interfering with other windows. - windows can be disposed of when not needed, and erased from the screen. When erased, the contents of the screen underneath the window is restored. - windows can be written to at any time. - the window application should automatically detect the type of video hardware used. - the window functions should return an error if something goes wrong. Page 1 The C Window Library Page 1 Writing to Overlapping Windows ------------------------------ With The C Window Library, if a window does overlap another window, this overlap will be displayed on the physical screen. The C Window Library allows you to direct output to any window at any time. When output is written to a window, the window contents are updated in memory, but only the visible portions of the window will be updated on the screen. Top-Level, Child, and Desktop Windows ------------------------------------- CWL 3.0 now supports child windows. Child windows are windows that are embedded in other windows. The window that the child is embedded in is called the parent window. The child window is completely dependent on the parent when it comes to position, hiding, and closing. For example, if the parent window is moved, the child is also moved. A child window can also have child windows. You can have up to 255 child windows for each window. The maximum number of windows in total cannot exceed 32,767. If a window is not a window that you defined as a child window, it is called a top-level window. The main window that all top-level windows are children of is called the desktop window. Top-level windows are children of the desktop window. A sibling window is a child window that has the same parent as another child window. Window Ranks ------------ The rank order of the windows on the screen will determine which window has priority of the screen. Windows with lower rank numbers overlap windows with higher rank numbers. The lowest rank number is 1, and the highest is 254 and 255 for top-level windows and child windows, respectively. If a new window is opened with the same rank number as another previously opened window, the new window takes over the rank position, and the previous window's rank is increased by 1. If there is a window with the same rank as the previous window's new rank, its rank is increased by 1 etc. When a window is closed, all windows with a higher rank number are decreased by 1. Page 2 The C Window Library Page 2 For child windows, the rank determines the priority of the window within the parent. For example, a child window with a rank of 1 will overlap another sibling window with a rank of 2 or higher. Therefore knowing the rank number of the window does NOT determine the priority, unless the windows are top-level windows, or the windows are siblings within the same parent window. CWL has rank testing functions that you should use instead of comparing ranks 'blindly'. Windows may be assigned different ranks if there is a shadowed window. If a window is shadowed, the shadow effect is actually a secondary window that is always ranked 1 higher than the actual window. More will be stated on this in a later section. Detection of Video Hardware --------------------------- With The C Window Library, automatic detection of the type of video hardware is necessary. Since The C Window Library can write directly to screen memory, the starting memory address of screen memory must be known. Depending on the video adapter, the starting address of screen memory is different. For monochrome systems, the starting address is different from a color system. If the window routines think that they are writing to a color system instead of a monochrome system, crazy things will probably happen. For most adapters, The C Window Library will detect them and assign the starting address of screen memory to a global variable, so there is no need to specify the starting address yourself. Window Coordinates ------------------ A position on the screen can be specified as a pair of numbers. These numbers will denote the row and column of the desired position. Rows and columns are numbered from 0 to the maximum row or column number. The upper left hand corner of the screen would be at row 0, column 0. For simplicity, row y, column x will be abbreviated as (y,x). The position (0,0) is called the home position. However, when specifying a position in a window, this position is numbered relative to the window itself. No matter where a window resides on the screen, the upper left position of the window is (0,0), the second row of the window is row 1, the fourth column is column 3, etc. The window coordinates are called window relative coordinates. There are some window functions that require you to enter physical screen (absolute) coordinates, but for most functions, a window relative position would be needed. For example: Page 3 The C Window Library Page 3 ┌─────────────────────────────────────────────────────────┐ │(0,0) (0,79)│ │ │ │ Valid Absolute Screen Coordinates │ │ For 80 x 25 Screen │ │ │ │ This window opened at absolute (12,15) │ │ │ │ │ │ │ │ V │ │ ┌─────────────────────┐ │ │ │(0,0) (0,29)│ │ │ │ │ │ │ │ │ │ │ │(14,0) (14,29)│ │ │ └─────────────────────┘ │ │(24,0) (24,79)│ └─────────────────────────────────────────────────────────┘ CWL also supports positioning a window partially or totally outside of the desktop by using negative coordinates or positive coordinates that exceed the desktop height or width. For child windows, the position is relative to the parent window, and not to the screen itself. The parent acts as a 'mini desktop window'. The child window can also be positioned partially outside of the parent window, however the only portion of the child window that will be visible will be the portion that is within the parent. Client Area ----------- The client area of window is where all text is displayed in the window. This does not include the borders. The concept of the client area is important for some child window functions. Video Attributes ---------------- With The C Window Library, a window can have an assortment of colors for text and background. Each character that is displayed on the screen has its corresponding attribute byte. The attribute byte is an 8-bit quantity that specifies a character's color, intensity, and blink status. The format of the attribute byte is as follows: 7 6 5 4 3 2 1 0 ┌──┬─────────┬─┬─────────┐ │B │ bground │I│fground │ └──┴─────────┴─┴─────────┘ Page 4 The C Window Library Page 4 The B is the blink bit and the I is the intensity bit. Bits 0 thru 2 is a color code for the foreground (text) color. Bits 4 thru 6 determine the color code for the background (screen) color. If the blink bit is 1, then the character will blink. If the intensity bit is on, the character will appear brighter than usual. Some monitors cannot display high intensity characters, so the intensity bit may not change the characters brightness at all. Here is a list of color values along with the color they represent: Value Color │ Value Color │ 0 Black │ 8 Gray 1 Blue │ 9 Light blue 2 Green │ 10 Light green 3 Cyan │ 11 Light cyan 4 Red │ 12 Light red 5 Magenta │ 13 Light magenta 6 Brown │ 14 Yellow 7 White │ 15 Intense white If the video system is a monochrome system, the color values specified above will give unpredictable results if not used carefully. Monochrome systems also have an underline mode, that color systems (unless if you program the EGA or VGA adapters) cannot display. Upcoming is a list of color values that should work on monochrome systems along with the type of display that will be produced: Display Background Foreground No display 0 0 Underline 0 1 Normal Video 0 7 Reverse Video 7 0 When programming a monochrome system, you can change the values of the colors not supported to black and white combinations supported on the monochrome system. For example, you can change the light green color's value from 10 to 7. Now if light green is selected as a foreground color and the background color is black, you will have a normal video display on a monochrome system. Direct Screen Writes and BIOS Screen Updates -------------------------------------------- By default, The C Window Library writes directly to screen memory. This results in very fast screen output. If you Page 5 The C Window Library Page 5 have ever wondered how commercial programs can display output so rapidly on the screen, direct screen writing is the major reason. The disadvantage of writing directly to the screen is that it is ill-behaved with programs like Microsoft Windows or Quarterdeck's DesQView (although DesQView 386 running on a 386 or higher machine is well behaved with direct screen writes). Also on some color systems, the screen output is so fast that the video display produces "snow" on the screen. However, The C Window Library will automatically detect whether "snow" should be checked when writing directly to the screen. The old IBM Color Graphics Adapters suffer from this problem, but most other adapters including monochrome, Hercules, EGA, VGA, and newer CGA's do not suffer from this problem. When checking for snow, the screen writes are not as fast as when there is no snow checking, but it is fast enough. The other method of updating the screen is by making a call to the video functions contained in the ROM BIOS. BIOS stands for Basic Input Output System. The BIOS provides routines that are needed for the operation of the computer. Some of these routines are video functions needed to write characters and attributes, move the cursor, and scroll portions of the screen. Using the BIOS instead of writing directly to screen memory results in much slower screen updates, but will be compatible with programs like Microsoft Windows and DesQView. With The C Window Library, you are allowed to use either method. Video Paging ------------ Since most video display adapters have enough memory to store more than one screen of characters, these video adapters will support multiple video pages. With multiple video pages, you can write to a hidden video page and then display the entire video page instantaneously. The only adapter that does not support video paging is the Monochrome Display Adapter (MDA). All CGA's, EGA's and VGA's support multiple video pages. The maximum number of pages a card will support is determined by the amount of RAM included in the video board, and the maximum number of characters that can be displayed on each page. A list of the maximum number of video pages in each mode for each card is as follows: BIOS Mode Max. # Mode Type Adapter of pages ---- ---- ------- -------- 0,1 Text CGA, EGA, VGA 8 2,3 Text CGA, 4 EGA, VGA 8 7 Text MDA, Hercules 1 EGA, VGA 8 Page 6 The C Window Library Page 6 With The C Window Library, the video page displayed on the screen is called the visible page. When creating a window, its page number is recorded. When updating windows, the video page number where the window resides is used to direct the output to the appropriate video page. There are also functions in The C Window Library that allow you to switch video pages. With these routines, you can create very sophisticated user interfaces. If you are using a clone Hercules Monochrome adapter, you may have access to more than one video page. The original Hercules card has only one page of text memory. The problem of accessing the other pages in the clone cards is that there is no universal way to determine how many pages that the card has. If you are writing an application that targets a specific Hercules clone card, and you want to take advantage of the multiple pages, you can modify a global variable that contains the maximum number of available video pages, as well as the array that contains the segment:offset of each video page. Make sure you have the full documentation for the card, or know off-hand the number of pages and their addresses. Error Codes ----------- With most of The C Window Library functions, CWLerror_code, which is a global integer variable, is set to an error number when a function cannot be completed. Throughout this documentation, you are to assume that CWLerror_code is set to any error condition that is documented for each function. The CWLerror_code variable IS NOT reset when a function has been completed successfully. Window Manager -------------- The window manager is the code in The C Window Library that handles window initialization, movement, coloring, and other functions that control window management. Page 7 The C Window Library Page 7 MANDATORY FUNCTIONS AND HEADER FILES ------------------------------------ The only mandatory function is WindowInitializeSystem(), explained below. The cwlwin.h header file must be included in any module that will call functions included in The C Window Library. This means that on the first line of any C file that will call any window functions, you must have the line: #include "cwlwin.h" WindowInitializeSystem() ------------------------ This function MUST be called before any other function defined in The C Window Library. This function also sets global variables, so it is also mandatory to call WindowInitializeSystem() before accessing any global variables defined by The C Window Library. WindowInitializeSystem() detects the type of video display used, the number of rows and columns that the screen currently displays, and initializes data structures and global variables. Example: #include "cwlwin.h" main() { WindowInitializeSystem(); /* Initialization function */ /* Now it is safe to use C Window Library functions and global variables */ } There is no return value for WindowInitializeSystem(). Page 8 The C Window Library Page 8 CREATING WINDOWS ---------------- We will now look how a window is created by defining a CWLWINDOW, WPOINTER, and using the WindowInitDesktop() and WindowInitialize() function. The CWLWINDOW structure and WPOINTER structure pointer --------------------------------------------------- When a window is created, the upper left hand column and row, the width, height, etc. must be recorded. It would be very tedious if for every function call that acts on these windows we have to specify width, height, upper left hand row, etc. as function parameters. The C Window Library conveniently has a structure called CWLWINDOW, and its corresponding pointer called a WPOINTER to alleviate these problems. When a window is created, its characteristics are stored in a CWLWINDOW structure, and most functions require that a pointer to this structure be passed. This pointer is called a WPOINTER. By only referring to the WPOINTER, argument lists to functions become much shorter. WindowInitDesktop() ------------------- The WindowInitDesktop() function saves the base screen as a desktop window. This MUST be called prior to creating any windows. Here is a prototype: int WindowInitDesktop(int page) The page argument is the video page of the base screen to save. If you are creating windows that will be manipulated on video page 0, you must call WindowInitDesktop() with 0 as the argument: #include "cwlwin.h" main() { WindowInitializeSystem(); /* Initialize global variables */ WindowInitDesktop(0); /* Save video page 0's base screen */ } Page 9 The C Window Library Page 9 In most applications, the initial screen page is page 0. However, it is safer to use the global variable CWLactive_page (explained in the IMPORTANT GLOBAL VARIABLES section) to determine the page. If you are changing video pages in an application, the new page has to be initialized with WindowInitDesktop() so that the window manager updates the screen properly when moving windows, hiding windows, etc. This function must be called only once in an application for each screen page desired. Return Values for WindowInitDesktop() are as follows: Return Value Definition ┌────────────────┬───────────────────────────────┐ │NO_ERROR │ No error occurred. │ ├────────────────┼───────────────────────────────┤ │NO_HEAP_MEM │ Not enough memory to allocate.│ ├────────────────┼───────────────────────────────┤ │MAX_WINDOW │ Too many windows defined. │ ├────────────────┼───────────────────────────────┤ │BAD_DISPLAY_PAGE│ Video page does not exist. │ └────────────────┴───────────────────────────────┘ WindowInitialize() ------------------ The next function is WindowInitialize(). This function sets up a window with the position on the screen or another window to place the window, width, height, colors, and box type. If successful, this function returns a new WPOINTER. Here is an example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,15,NORM, NORM,SINGLEBOX); ... } In the above example, we have defined a variable w as having a WPOINTER type. This variable will ultimately point to a valid CWLWINDOW structure. The first argument is the new window's parent window. If the window is a top-level window, the first argument is DESKTOP_WINDOW. If the window is a child, the first argument is the WPOINTER of the parent window. The second argument to WindowInitialize() is a constant called BORDER. This tells the window manager that Page 10 The C Window Library Page 10 the window desired is going to have a border. If no border was desired, the constant would be NOBORDER. The third and fourth arguments tells the window manager the row and column of the screen where the upper left corner of the window will be located. Since the upper left corner of the screen is row 0, column 0, the upper left hand corner of the window will be placed at the upper left corner of the video screen. The fifth and sixth arguments denote the width and the height of the window. DO NOT INCLUDE THE BORDERS (if any) TO DETERMINE THE WIDTH AND HEIGHT OF THE WINDOW. Our window will have a width of 30 characters and a height of 15 characters. The seventh and eighth arguments are the video attributes of the inside of the window and the border respectively. The last argument tells us what type of border the window will have. We use the constant SINGLEBOX to tell the window manager that we want a window with a border made up of single lines. If there is no error, WindowInitialize() returns a valid WPOINTER. If there is an error, WindowInitialize() returns a WIN_NULL_PTR (a null window pointer) and sets CWLerror_code to one of the following values: Return Value Definition ┌────────────────┬───────────────────────────────┐ │NO_HEAP_MEM │ Not enough memory to allocate.│ ├────────────────┼───────────────────────────────┤ │MAX_WINDOW │ Too many windows defined. │ ├────────────────┼───────────────────────────────┤ │BAD_WINDOW │ Parent Window does not exist. │ └────────────────┴───────────────────────────────┘ Even though there is a structure type called CWLWINDOW, you should always use the pointer to the structure (WPOINTER) rather than the CWLWINDOW structure itself. CREATE_VIDEO_ATTRIBUTE() macro ------------------------------ Please note the use of the macro CREATE_VIDEO_ATTRIBUTE() in the previous example to create an integer representing the foreground and background colors. This macro uses the first argument as the background color, and the second argument as the foreground color. In the above example we have a constant called NORM which uses CREATE_VIDEO_ATTRIBUTE() to create a black background and a white foreground color combination. Note that the colors are denoted by capitalized letters appended with an underscore character (_). Page 11 The C Window Library Page 11 Box types --------- For ease of use, There are predefined constants found that contains definitions of common border types. These constants are as follows: Box Type Visual Box Type Visual ┌─────────────────────────╥─────────────────────────┐ │ ╔════╗ ║ ▒▒▒▒▒▒ │ │ DOUBLEBOX ║ ║ ║ HATCHBOX2 ▒ ▒ │ │ ║ ║ ║ ▒ ▒ │ │ ╚════╝ ║ ▒▒▒▒▒▒ │ ├─────────────────────────╫─────────────────────────┤ │ ┌────┐ ║ ▓▓▓▓▓▓ │ │ SINGLEBOX │ │ ║ HATCHBOX3 ▓ ▓ │ │ │ │ ║ ▓ ▓ │ │ └────┘ ║ ▓▓▓▓▓▓ │ ├─────────────────────────╫─────────────────────────┤ │ ╒════╕ ║ █▀▀▀▀█ │ │ MIXEDBOX1 │ │ ║ SOLIDBOX1 █ █ │ │ │ │ ║ █ █ │ │ ╘════╛ ║ █▄▄▄▄█ │ ├─────────────────────────╫─────────────────────────┤ │ ╓────╖ ║ ██████ │ │ MIXEDBOX2 ║ ║ ║ SOLIDBOX2 █ █ │ │ ║ ║ ║ █ █ │ │ ╙────╜ ║ ██████ │ ├─────────────────────────╫─────────────────────────┤ │ ░░░░░░ ║ │ │ HATCHBOX1 ░ ░ ║ BLANKBOX │ │ ░ ░ ║ │ │ ░░░░░░ ║ │ ├─────────────────────────╫─────────────────────────┘ │ -------- ║ │ DOTTEDLINE | | ║ │ | | ║ │ | | ║ │ -------- ║ └─────────────────────────╜ Although there are predefined border types in The C Window Library, you can define your own types. The window border characters are represented by an 8 byte character string. Each character in this string refers to a border character to be used in drawing the window border. A list of what each position in the string stands for is as follows: position Representation -------- --------------------------- 0 Upper left corner character. 1 Top line character. 2 Upper right corner character. 3 Left side character. 4 Right side character. 5 Bottom left corner character. 6 Bottom line character. 7 Bottom right corner character. Page 12 The C Window Library Page 12 This character string is sent to the window functions that call for a string of box drawing characters. For example, you can create your own customized set of characters with something like this: #define MYBOXCHARS "+-+||+-+" MYBOXCHARS is a literal string of box drawing characters. Using the rules of box drawing characters defined above, the upper left hand corner of the box is the plus sign, the top line is the hyphen, the upper right and corner is the plus sign, the left side is a pipe character, as is the right side, and the bottom part of the box is defined the same as the upper part. Then you would use it in a call to any function that asks for a box drawing string like this: w = WindowInitialize(DESKTOP_WINDOW,BORDER, ... ,MYBOXCHARS); The '...' are the other arguments that you would normally put for the WindowInitialize() function. Page 13 The C Window Library Page 13 DISPLAYING WINDOWS ------------------ Now we will display the window we created in the previous example. The WindowDisplay() function and Explosion Effects -------------------------------------------------- The WindowDisplay() function displays a window. Here is the previous example with WindowDisplay() added to it: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,15,NORM, NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); ... } The first argument to WindowDisplay() is the window to display, in our case, w is the window. The second argument is the rank order of the window. Since the rank order we desire is 1, this window will lie on top of all windows, unless another window is opened with a rank of 1. Remember, any window with a rank number n will have sibling windows with rank n-1, n-2,...,1 to be displayed on top of it. Remember that top-level windows are siblings of each other. You can change the rank order of a window at any time by calling WindowDisplay() with a different rank number. The third argument to WindowDisplay() is the explosion effect of the window when it is displayed. There are currently 16 ways to explode a window on the screen, numbered from 0 thru 15. Here is an overview of each effect: Defined Constant Value Effect ┌───────────────┬───────┬───────────────┐ │ NOEFFECT │ 0 │ ┌───────────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └───────────┘ │ └───────────────┴───────┴───────────────┘ Page 14 The C Window Library Page 14 Defined Constant Value Effect ┌───────────────┬───────┬───────────────┐ │EXPLODE │ 1 │ ┌───────────┐ │ │ │ │ │ ^ │ │ │ │ │ │ | │ │ │ │ │ │<-- -->│ │ │ │ │ │ │ │ │ │ │ │ | │ │ │ │ │ │ v │ │ │ │ │ └───────────┘ │ ├───────────────┼───────┼───────────────┤ │CONTRACT │ 2 │ ┌───────────┐ │ │ │ │ │ | │ │ │ │ │ │ | │ │ │ │ │ │ v │ │ │ │ │ │--> <--│ │ │ │ │ │ ^ │ │ │ │ │ │ | │ │ │ │ │ │ | │ │ │ │ │ └───────────┘ │ ├───────────────┼───────┼───────────────┤ │BRICKS │ 3 │ ┌───────────┐ │ │ │ │ │█ █ │ │ │ │ │ │ █ │ │ │ │ │ │ █ │ │ │ │ │ │ █ │ │ │ │ │ │ █ █ │ │ │ │ │ │█ █ │ │ │ │ │ └───────────┘ │ ├───────────────┼───────┼───────────────┤ │ │ │ ^ │ │MIDDLEROWOUT │ 4 │ │ │ │ │ │ ┌──────────┐ │ │ │ │ └──────────┘ │ │ │ │ │ │ │ │ │ v │ ├───────────────┼───────┼───────────────┤ │TOPBOTTOMIN │ 5 │ ┌──────────┐ │ │ │ │ └──────────┘ │ │ │ │ │ │ │ │ │ v │ │ │ │ ^ │ │ │ │ │ │ │ │ │ ┌──────────┐ │ │ │ │ └──────────┘ │ ├───────────────┼───────┼───────────────┤ │TOPDOWN │ 6 │ ┌──────────┐ │ │ │ │ └──────────┘ │ │ │ │ | │ │ │ │ v │ ├───────────────┼───────┼───────────────┤ │ │ │ ^ │ │BOTTOMUP │ 7 │ | │ │ │ │ ┌──────────┐ │ │ │ │ └──────────┘ │ └───────────────┴───────┴───────────────┘ Page 15 The C Window Library Page 15 Defined Constant Value Effect ┌───────────────┬───────┬───────────────┐ │MIDDLECOLOUT │ 8 │ ┌┐ │ │ │ │ ││ │ │ │ │ ││ │ │ │ │ <-││-> │ │ │ │ ││ │ │ │ │ ││ │ │ │ │ └┘ │ ├───────────────┼───────┼───────────────┤ │LEFTRIGHTIN │ 9 │ ┌┐ ┌┐ │ │ │ │ ││ ││ │ │ │ │ ││ ││ │ │ │ │ ││-> <-││ │ │ │ │ ││ ││ │ │ │ │ ││ ││ │ │ │ │ └┘ └┘ │ ├───────────────┼───────┼───────────────┤ │LEFTTORIGHT │ 10 │ ┌┐ │ │ │ │ ││ │ │ │ │ ││ │ │ │ │ ││-> │ │ │ │ ││ │ │ │ │ ││ │ │ │ │ └┘ │ ├───────────────┼───────┼───────────────┤ │RIGHTTOLEFT │ 11 │ ┌┐ │ │ │ │ ││ │ │ │ │ ││ │ │ │ │ <-││ │ │ │ │ ││ │ │ │ │ ││ │ │ │ │ └┘ │ ├───────────────┼───────┼───────────────┤ │SLIDELEFT │ 12 │ ╔═════════╗ │ │ │ │ ║ ║ │ │ │ │ ║ ┌────╢ │ │ │ │ ║ │ ║ │ │ │ │ ║ │<───╢ │ │ │ │ ║ │ ║ │ │ │ │ ║ └────╢ │ │ │ │ ║ ║ │ │ │ │ ╚═════════╝ │ ├───────────────┼───────┼───────────────┤ │SLIDERIGHT │ 13 │ ╔═════════╗ │ │ │ │ ║ ║ │ │ │ │ ╟────┐ ║ │ │ │ │ ║ │ ║ │ │ │ │ ╟──> │ ║ │ │ │ │ ║ │ ║ │ │ │ │ ╟────┘ ║ │ │ │ │ ║ ║ │ │ │ │ ╚═════════╝ │ └───────────────┴───────┴───────────────┘ Page 16 The C Window Library Page 16 ┌───────────────┬───────┬───────────────┐ │SLIDEDOWN │ 14 │ ╔══╤═╤═╤══╗ │ │ │ │ ║ │ │ │ ║ │ │ │ │ ║ │ V │ ║ │ │ │ │ ║ └───┘ ║ │ │ │ │ ║ ║ │ │ │ │ ║ ║ │ │ │ │ ╚═════════╝ │ ├───────────────┼───────┼───────────────┤ │SLIDEUP │ 15 │ ╔═════════╗ │ │ │ │ ║ ║ │ │ │ │ ║ ┌───┐ ║ │ │ │ │ ║ │ │ ║ │ │ │ │ ║ │ ^ │ ║ │ │ │ │ ║ │ │ │ ║ │ │ │ │ ╚══╧═╧═╧══╝ │ └───────────────┴───────┴───────────────┘ The last four effects, SLIDELEFT, SLIDERIGHT, SLIDEUP, and SLIDEDOWN slide a window that is initially out of view of the desktop window or the parent window into view. Note that the illustrations above use boxes with single lines to denote the actual window, and the double box lines represent the desktop or parent window for the SLIDE... effects. Return Values for WindowDisplay(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ Displaying Multiple Windows --------------------------- If you are creating multiple windows you can change the rank of the window by calling WindowDisplay() with a different rank number. Here is an example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,BLUE_) #define REDONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,RED_) #define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,GREEN_) Page 17 The C Window Library Page 17 main() { int i; WPOINTER w1,w2,w3; /* pointers to a window structures */ WindowInitializeSystem(); WindowInitDesktop(0); w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,15, BLUEONBLACK,NORM,SINGLEBOX); /* define second window */ w2 = WindowInitialize(DESKTOP_WINDOW,BORDER,3,3,30,15, REDONBLACK,NORM,DOUBLEBOX); /* define third window */ w3 = WindowInitialize(DESKTOP_WINDOW,BORDER,6,6,30,15, GREENONBLACK,NORM,SINGLEBOX); WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); WindowDisplay(w3,3,NOEFFECT); GET_KEY(); WindowDisplay(w2,1,NOEFFECT); GET_KEY(); WindowDisplay(w3,1,NOEFFECT); GET_KEY(); WindowDisplay(w1,1,NOEFFECT); GET_KEY(); } In the above program, w1, w2, and w3 are displayed with rank numbers of 1, 2, and 3, respectively. The ordering means that w1 will overlay w2, and w2 will overlay w3. Note that after the windows w1, w2, and w3 are initially displayed, they are redisplayed by making another call to WindowDisplay(). You can redisplay a window and change its rank by calling the WindowDisplay() function again. For example, w2 is redisplayed with a rank of 1. This promotes w2 to the top of the stack of displayed windows within the parent window, and demotes w1 with a rank of 2. Each and every window has a unique rank number. The window manager keeps track of conflicts in rank numbers, and adjusts the data structures involved in maintaining the windows in working order. Therefore, there is really no need for you to remember whether a rank number is used or not. The macro GET_KEY() pauses the program until you press a key. Page 18 The C Window Library Page 18 CLOSING WINDOWS --------------- In this section, we will discuss closing windows. WindowClose() ------------- The WindowClose() function removes the window from the display (if it is displayed) and deallocates all memory used by the window. This effectively renders the WPOINTER useless unless it is assigned to another window, or a window is created again. int WindowClose(WPOINTER w, int effect) The first argument is the window. The second argument is the special effect to use when closing the window. This argument is only meaningful if the window is visible. For a list of effects refer back to the DISPLAYING WINDOWS section. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,BLUE_) #define REDONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,RED_) #define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,GREEN_) main() { int i; WPOINTER w1,w2,w3; WindowInitializeSystem(); WindowInitDesktop(0); w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,15, BLUEONBLACK,NORM,SINGLEBOX); /* define second window */ w2 = WindowInitialize(DESKTOP_WINDOW,BORDER,3,3,30,15, REDONBLACK,NORM,DOUBLEBOX); /* define third window */ w3 = WindowInitialize(DESKTOP_WINDOW,BORDER,6,6,30,15, GREENONBLACK,NORM,SINGLEBOX); WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); WindowDisplay(w3,3,NOEFFECT); Page 19 The C Window Library Page 19 GET_KEY(); WindowDisplay(w2,1,NOEFFECT); GET_KEY(); WindowDisplay(w3,1,NOEFFECT); GET_KEY(); WindowDisplay(w1,1,NOEFFECT); GET_KEY(); WindowClose(w2,NOEFFECT); GET_KEY(); WindowClose(w3,NOEFFECT); GET_KEY(); WindowClose(w1,NOEFFECT); } The example above calls WindowClose() on all three windows. Return Values for WindowClose(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ WindowCloseAll() ---------------- The WindowCloseAll() function acts just like WindowClose() function except that all windows are destroyed on a desired video page. Here is the prototype: int WindowCloseAll(int page, int effect) The page argument is the video page of where the windows are located. Remember that The C Window Library allows displaying windows on video pages other than page 0 (default page). The effect argument is the special effect to use when closing the window. Refer to DISPLAYING WINDOWS for the list of special effects. Page 20 The C Window Library Page 20 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,BLUE_) #define REDONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,RED_) #define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,GREEN_) main() { int i; WPOINTER w1,w2,w3; WindowInitializeSystem(); WindowInitDesktop(0); w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,15, BLUEONBLACK,NORM,SINGLEBOX); /* define second window */ w2 = WindowInitialize(DESKTOP_WINDOW,BORDER,3,3,30,15, REDONBLACK,NORM,DOUBLEBOX); /* define third window */ w3 = WindowInitialize(DESKTOP_WINDOW,BORDER,5,5,30,15, GREENONBLACK,NORM,SINGLEBOX); WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); WindowDisplay(w3,3,NOEFFECT); WindowCloseAll(0,NOEFFECT); /* close all the windows */ } The example above calls WindowCloseAll() to close all three windows. Refer to WindowClose() for return values. WindowUninitSystem() -------------------- The WindowUninitSystem() frees any memory that was allocated by The C Window Library functions. This includes memory used for windows, virtual windows, menus, and other memory areas used for temporary storage. This function should be called right before termination of a program. Even though the MSDOS operating system frees any allocated memory when a program terminates, it is still a good idea to call WindowUninitSystem(). A prototype of this function is as follows: void WindowUninitSystem(void) Page 21 The C Window Library Page 21 CENTERING WINDOWS ----------------- The C Window Library allows easy centering of windows on the parent or desktop window. WindowCenter() -------------- The WindowCenter() function centers a window on the parent or desktop window vertically, horizontally, or both. Here is the prototype: int WindowCenter(WPOINTER w, int option) The first argument is the window to center, and the second argument tells whether to center the window horizontally, vertically, or both. The options argument must be one of the following: Options Type of centering ┌─────────────────────────┬────────────────────┐ │VERTCENTER │ vertical │ ├─────────────────────────┼────────────────────┤ │HORIZCENTER │ horizontal │ ├─────────────────────────┼────────────────────┤ │VERTCENTER | HORIZCENTER │ both horizontal and│ │ │ vertical │ └─────────────────────────┴────────────────────┘ Note the bitwise OR (|) between the constants VERTCENTER and HORIZCENTER for both horizontal and vertical centering. This function can be used on hidden windows. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,10,10,NORM, NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); Page 22 The C Window Library Page 22 WindowCenter(w,VERTCENTER); /* center vertically */ GET_KEY(); WindowMove(w,0,0); GET_KEY(); WindowCenter(w,HORIZCENTER); /* center horizontally */ GET_KEY(); WindowMove(w,0,0); GET_KEY(); WindowCenter(w,VERTCENTER | HORIZCENTER); /* center both horizontal and vertical */ GET_KEY(); WindowClose(w,NOEFFECT); } Return Values for WindowCenter(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ Page 23 The C Window Library Page 23 CHANGING WINDOW CHARACTERISTICS ------------------------------- In this section, we will discuss changing the window attributes, border style, and the window's height and width. WindowChangeTextAttribute() --------------------------- This function changes the attribute of the text portion of the window. The text portion is the inside of the window. Here is a prototype: int WindowChangeTextAttribute(WPOINTER w, int color) where w is the WPOINTER to change the text attribute, and color is the new color. You can use the CREATE_VIDEO_ATTRIBUTE() macro to define the color. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,10,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowChangeTextAttribute(w,REVERSE); } Return Values for WindowChangeTextAttribute(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ Page 24 The C Window Library Page 24 WindowChangeBorderAttribute() ----------------------------- This function changes the video attribute of the border of the window. If the window does not have a border, nothing is changed. Here is a prototype: int WindowChangeBorderAttribute(WPOINTER w, int color) where w is the WPOINTER to change the border attribute, and color is the new color. You can use the CREATE_VIDEO_ATTRIBUTE() macro to define the color. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,10,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowChangeBorderAttribute(w,REVERSE); } Return values for WindowChangeBorderAttribute(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ WindowDrawBorder() ------------------ You can also change the border type, or draw a border on an unbordered window by calling the WindowDrawBorder() function. Page 25 The C Window Library Page 25 Here is a prototype: int WindowDrawBorder(WPOINTER w, char *box) The first argument is the window we want to change the border of. The second argument is a string of border characters. This string denotes the type of border that the window should now have. In the example given below, w is initialized with a SINGLEBOX border, but WindowDrawBorder() changes this to a DOUBLEBOX. The WindowDrawBorder() function is also used to draw borders on borderless windows. When drawing borders on a NOBORDER window, the window must not have any of its sides touching the edges of the physical screen. In other words, the window must "have room" for a border to be drawn. If there is no room to draw the border, there is no change to the window. Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,NOBORDER,2,2,10,10, REVERSE,REVERSE,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowDrawBorder(w,DOUBLEBOX); /* Draws a double box around NOBORDER window */ } Return values for WindowDrawBorder(): Return Value Definition ┌────────────────┬───────────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼───────────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼───────────────────────────────┤ │NO_HEAP_MEM │ Mot enough memory to allocate.│ └────────────────┴───────────────────────────────┘ Page 26 The C Window Library Page 26 WindowRemoveBorder() -------------------- This function removes a border from a bordered window. Here is the prototype: int WindowRemoveBorder(WPOINTER w) If the window does not have a border, nothing is changed. Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,10,10, REVERSE,REVERSE,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowRemoveBorder(w); /* Removes the double box around BORDERed window */ } Return values for WindowRemoveBorder(): Return Value Definition ┌────────────────┬───────────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼───────────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼───────────────────────────────┤ │NO_HEAP_MEM │ Mot enough memory to allocate.│ └────────────────┴───────────────────────────────┘ WindowResizeHeight() -------------------- This function changes the inside (text portion) height of the window. Here is a prototype: int WindowResizeHeight(WPOINTER w, int newheight, int anchor) The newheight argument is the new height of the window. The anchor argument determines which side to "hold down" while the window is being resized. Page 27 The C Window Library Page 27 If the anchor is ANCHORTOP, the top line of the window is held in its current position and the window is resized accordingly. If anchor is ANCHORBOTTOM, the bottom of the window is held and the window is resized accordingly. If there is text in the window, the text will be truncated if the window is made shorter (unless the window is a viewport to a virtual window. Virtual windows are discussed in the VIRTUAL WINDOWS section). Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,10,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowResizeHeight(w,15,ANCHORTOP); /* height now is 15 */ GET_KEY(); WindowResizeHeight(w,5,ANCHORBOTTOM);/* height is now 5 */ } Return values for WindowResizeHeight(): Return Value Definition ┌────────────────┬───────────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼───────────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼───────────────────────────────┤ │NO_HEAP_MEM │ Mot enough memory to allocate.│ └────────────────┴───────────────────────────────┘ WindowResizeWidth() ------------------- This function changes the inside (text portion) width of the window. Here is a prototype: int WindowResizeWidth(WPOINTER w, int newwidth, int anchor) The newwidth argument is the new width of the window. The anchor argument determines which side to "hold down" while the window is being resized. Page 28 The C Window Library Page 28 If the anchor is ANCHORLEFT, the left side of the window is held in its current position and the window is resized accordingly. If anchor is ANCHORRIGHT, the right side of the window is held and the window is resized accordingly. If there is text in the window, the text will be truncated if the window is made shorter (unless the window is a viewport to a virtual window. Virtual windows are discussed in the VIRTUAL WINDOWS section). main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,10,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowResizeWidth(w,15,ANCHORLEFT);/* width is now 15 */ GET_KEY(); WindowResizeWidth(w,5,ANCHORRIGHT);/* width is now 5 */ } Return values for WindowResizeWidth(): Return Value Definition ┌────────────────┬───────────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼───────────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼───────────────────────────────┤ │NO_HEAP_MEM │ Mot enough memory to allocate.│ └────────────────┴───────────────────────────────┘ Page 29 The C Window Library Page 29 WRITING TEXT TO WINDOWS ----------------------- There are various functions that will write text to a window. These functions are divided into two groups: Functions that specify a null terminated string, and functions that require the length of the string of characters to write to be an explicit argument. Null Terminated Write Functions ------------------------------- WindowWriteString() ------------------- The WindowWriteString() function writes a null terminated string of characters to a window at a specified row and column of the window. If the string is too long to fit in the boundaries of the window, the string is clipped (truncated) to fit in the boundaries of the window. Here is the prototype: int WindowWriteString(WPOINTER w, char *string, int row, int col) The first argument is the window to write the string to. The second argument is the null terminated string to write. The third and fourth arguments are the row and column of the window to place the string. The video attribute used when writing the string is the video attribute of the inside of the window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); for (i=0;i<=9;i++) WindowWriteString(w,"Hello World",i,0); } Page 30 The C Window Library Page 30 The above example writes the string "Hello World" to each line of the window w. Return values for WindowWriteString(): Return Value Definition ┌────────────────┬─────────────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼─────────────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼─────────────────────────────────┤ │WINDOW_BOUND │ Row or column are out of bounds.│ └────────────────┴─────────────────────────────────┘ WindowWriteStringAttr() ----------------------- The WindowWriteStringAttr() function works the same as the WindowWriteString() function except that an extra argument determines the color used to write the string. Here is the prototype: int WindowWriteStringAttr(WPOINTER w, char *string, int row, int col, int attr) The first argument is the window to write the string to. The second argument is the null terminated string to write. The third and fourth arguments are the row and column of the window to place the string. The last argument is the video attribute to use. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); for (i=0;i<=9;i++) WindowWriteStringAttr(w,"Hello World",i,0,REVERSE); } Page 31 The C Window Library Page 31 The above example writes the string "Hello World" to each line of the window w using the video attribute defined by the constant REVERSE. The return values to WindowWriteStringAttr() are the same as WindowWriteString(). WindowWriteCenterString() ------------------------- The WindowWriteCenterString() function centers a null terminated string in a window. Here is a prototype: int WindowWriteCenterString(WPOINTER w, char *string, int row) The first argument is the window. The second argument is the string to write. The third argument is the row that the string will be centered. The attribute used to write the string is the attribute of the inside of the window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); for (i=0;i<=9;i++) WindowWriteCenterString(w,"Hello World",i); } The above example writes and centers the string "Hello World" to each line of the window w. The return values for WindowWriteCenterString() are the same as WindowWriteString(). Page 32 The C Window Library Page 32 WindowWriteCenterStringAttr() ----------------------------- The WindowWriteCenterStringAttr() function works the same as the WindowWriteCenterString() function except that an extra argument determines the color used to write the string. Here is the prototype: int WindowWriteCenterStringAttr(WPOINTER w, char *string, int row, int attr) The first argument is the window. The second argument is the string to write. The third argument is the row that the string will be centered. The last argument is the video attribute to use to write the string. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); for (i=0;i<=9;i++) WindowWriteCenterStringAttr(w,"Hello World",i,REVERSE); } The above example writes and centers the string "Hello World" to each line of the window w using REVERSE as the video attribute. The return values for WindowWriteCenterStringAttr() are the same as WindowWriteString(). WindowWriteStringCC() --------------------- Centers and writes a string around a column of the window (the CC stands for Centered Column). If the string is longer than the width of the window, the string is placed on column 1 of the window and is clipped at the right edge of the window. Here is the prototype: Page 33 The C Window Library Page 33 The attribute used to write the string is the attribute of the inside of the window. int WindowWriteStringCC(WPOINTER w, char *string, int row) The first argument is the window. The second argument is the string. The third argument is the row to write the string, and the last argument is the column to center the string on. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteStringCC(w,"This",0,10); WindowWriteStringCC(w,"is",1,10); WindowWriteStringCC(w,"centered",2,10); WindowWriteStringCC(w,"around",3,10); WindowWriteStringCC(w,"column",4,10); WindowWriteStringCC(w,"10",5,10); } The example above writes the text centered around column 10 of the window w. The return values for WindowWriteStringCC() are the same as WindowWriteString(). WindowWriteStringCCAttr() ------------------------- The WindowWriteStringCCAttr() function works the same as the WindowWriteStringCC() function except that an extra argument determines the color used to write the string. Here is the prototype: int WindowWriteStringCCAttr(WPOINTER w, char *string, int row, int col, int attr) The first argument is the window. The second argument is the Page 34 The C Window Library Page 34 string to write. The third argument is the row that the string will be centered. The column argument is the column to center the string on. The last argument is the video attribute to use to write the string. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteStringCCAttr(w,"This",0,10,REVERSE); WindowWriteStringCCAttr(w,"is",1,10,REVERSE); WindowWriteStringCCAttr(w,"centered",2,10,REVERSE); WindowWriteStringCCAttr(w,"around",3,10,REVERSE); WindowWriteStringCCAttr(w,"column",4,10,REVERSE); WindowWriteStringCCAttr(w,"10",5,10,REVERSE); } The example above writes the text centered around column 10 of the window w using the video attribute REVERSE. The return values for WindowWriteStringCCAttr() are the same as WindowWriteString(). WindowWriteStringRJ() --------------------- The WindowWriteStringRJ() function writes a right justified string. Here is the prototype: int WindowWriteStringRJ(WPOINTER w, char *string, int row, int col) The first argument is the window. The second argument is the string. The third argument is the row to write the string, and the last argument is the column to place the right edge of the string. Page 35 The C Window Library Page 35 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteStringRJ(w,"This",0,10); WindowWriteStringRJ(w,"is",1,10); WindowWriteStringRJ(w,"right",2,10); WindowWriteStringRJ(w,"justified",3,10); WindowWriteStringRJ(w,"on ",4,10); WindowWriteStringRJ(w,"column",5,10); WindowWriteStringRJ(w,"10",6,10); } The example above writes the text right justified on column 10 of the window w. The attribute used to write the string is the attribute of the inside of the window. The return values for WindowWriteStringRJ() are the same as WindowWriteString(). WindowWriteStringRJAttr() ------------------------- The WindowWriteStringRJAttr() function works the same as the WindowWriteStringRJ() function except that an extra argument determines the color used to write the string. Here is the prototype: int WindowWriteStringRJAttr(WPOINTER w, char *string, int row, int col, int attr) The first argument is the window. The second argument is the string to write. The third argument is the row to write the string. The col is the column to right justify the string. The last argument is the video attribute to use to write the string. Page 36 The C Window Library Page 36 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteStringRJAttr(w,"This",0,10,REVERSE); WindowWriteStringRJAttr(w,"is",1,10,REVERSE); WindowWriteStringRJAttr(w,"right",2,10,REVERSE); WindowWriteStringRJAttr(w,"justified",3,10,REVERSE); WindowWriteStringRJAttr(w,"on ",4,10,REVERSE); WindowWriteStringRJAttr(w,"column",5,10,REVERSE); WindowWriteStringRJAttr(w,"10",7,6,REVERSE); } The example above writes the text right justified at column 10 of the window w using the video attribute REVERSE. The return values for WindowWriteStringRJAttr() are the same as WindowWriteString(). Length Controlled Write Functions --------------------------------- The upcoming functions must have the length explicitly stated as one of the arguments. These functions do not stop writing characters if the null character in the string to write is reached. WindowWriteCharacters() ----------------------- This function writes characters from a buffer to the window. Here is the prototype: int WindowWriteCharacters(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is a Page 37 The C Window Library Page 37 pointer to the buffer where the characters are stored. The third and fourth arguments are the (row,col) position in the window to write the string, and the last argument is the number of characters from buffer to write. The attribute used is the attribute of the inside of the window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; char buf[] = "Hello World!!"; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteCharacters(w,buf,0,0,11); WindowWriteCharacters(w,buf,1,0,13); } The return values for WindowWriteCharacters() are the same as WindowWriteString(). WindowWriteAttributes() ----------------------- This function writes attributes from a buffer to the window. Here is the prototype: int WindowWriteAttributes(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is a pointer to the buffer where the attributes are stored. The third and fourth arguments are the (row,col) position in the window to write the string, and the last argument is the number of attributes from buffer to write. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) Page 38 The C Window Library Page 38 #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; char buf[13]; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<13;i++) if (i % 2) buf[i] = NORM; else buf[i] = REVERSE; WindowWriteString(w,"Hello World!!",0,0); GET_KEY(); WindowWriteAttributes(w,buf,0,0,13); /* Writes alternating NORM and REVERSE attributes */ } The return values for WindowWriteAttributes() are the same as WindowWriteString(). WindowWriteCharAndAttr() ------------------------ The WindowWriteCharAndAttr() function writes a string of character/attribute pairs to a window. Use this function if you have created a string of character/attribute pairs, and want to output them easily. The string consists of character and attributes in the following manner: char-attr-char-attr... Each character is followed by its corresponding video attribute. Here is the prototype: int WindowWriteCharAndAttr(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second is the buffer Page 39 The C Window Library Page 39 where the character and attributes are stored. The third and fourth is the (row,col) position in the window to write, and the length argument is the number of character/attribute pairs from the buffer to write. Please note the difference in the meaning of the length argument in this function as opposed to its use in the preceding functions. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; char buf[26]; char *str = "Hello World!!"; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<26;i+=2,str++) { buf[i] = *str; buf[i+1] = NORM; } WindowWriteCharAndAttr(w,buf,0,0,13); } The return values for WindowWriteCharAndAttr() are the same as WindowWriteString(). WindowWriteCharactersAttr() --------------------------- The WindowWriteCharactersAttr() function writes characters from a buffer to a window. The difference between this function and WindowWriteCharacters() is that a video attribute is specified. Here is the prototype: int WindowWriteCharactersAttr(WPOINTER w, char *buffer, int row, int col, int attr, int length) Page 40 The C Window Library Page 40 The attr argument is the video attribute to use when writing the characters. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; char buf[] = "Hello World!!"; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowWriteCharactersAttr(w,buf,1,0,REVERSE,13); } The return values for WindowWriteCharactersAttr() are the same as WindowWriteString(). WindowWriteRepeatAttribute() ---------------------------- The WindowWriteRepeatAttribute() function writes an attribute a specified number of times to a window. Here is a prototype: int WindowWriteRepeatAttribute(WPOINTER w, int attr, int row, int col, int count) The attr argument is the attribute to use. The count argument specifies the number of times to write the attribute attr to the window starting at (row,col). Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; Page 41 The C Window Library Page 41 main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Hello World!!",0,0); GET_KEY(); WindowWriteRepeatAttribute(w,REVERSE,0,0,13); } The example above illustrates that the WindowWriteRepeatAttribute() writes the REVERSE attribute 13 times starting at row 0, column 0 of the window w. The return values for WindowWriteRepeatAttribute() are the same as WindowWriteString(). WindowWriteRepeatCharacter() ---------------------------- The WindowWriteRepeatCharacter() function writes a character a specified number of times to a window. Here is a prototype: int WindowWriteRepeatCharacter(WPOINTER w, int ch, int row, int col, int count) The count argument is the character to use. The count argument specifies the number of times to write the character ch to the window starting at (row,col). #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteRepeatCharacter(w,'a',0,0,5); WindowWriteRepeatCharacter(w,'b',1,0,5); WindowWriteRepeatCharacter(w,'c',2,0,5); } Page 42 The C Window Library Page 42 The example above illustrates that the WindowWriteRepeatCharacter() writes the letter 'a', 'b', and 'c' 5 times on rows 0, 1, and 2 respectively. The return values for WindowWriteRepeatCharacter() are the same as WindowWriteString(). Formatted Write Functions ------------------------- These functions write formatted output to windows just like the printf() function. There are two functions that do this, namely WindowPrintf() and WindowPrintfAttr(). These functions use a format string that is similar to the format string found in printf(). For example, %d, %s, %lf, etc. and most of the escape sequences are supported. The list of escape sequences supported are as follows: \n - newline \b - backspace \t - tab \a - bell \r - carriage return \x - hexadecimal Where output is placed in the window ------------------------------------ The row and column of where the string will be written is determined by the window's logical cursor. The logical cursor is advanced by both of these functions to one column position after the last character is printed. If you want to start at a particular row and column of the window, you must move the cursor yourself by calling the WindowMoveCursor() function. This function is explained later in the CURSOR POSITIONING IN WINDOWS section. If the window is displayed, the logical cursor of the window is equivalent to the screen cursor. If the output to the window will be obscured by other windows, the screen cursor will also be hidden. When the window is first created, the logical cursor is automatically moved to (0,0) of the window. WindowSetWrap() --------------- With these functions, any text that will exceed the boundaries of the window will be wrapped to the next line. If the output will exceed the last row of the window, the window is automatically scrolled up by one line. This is the Page 43 The C Window Library Page 43 default action that is taken when characters exceed the right edge of the window. If you want the output clipped instead of wrapped, you must set the window's wrap flag using the WindowSetWrap() function. The WindowSetWrap() function sets the window's wrap flag to either on or off. Here is the prototype: int WindowSetWrap(WPOINTER w, int option) The second argument will be 0 if you want to turn the wrap flag off, or 1 if you want to turn it on. If the wrap flag is off, the output generated by WindowPrintf() and WindowPrintfAttr() will be terminated when the right edge of the window is reached. If the wrap flag is on, the output is wrapped to the next line when the right edge is reached, and the window will be scrolled up by one line if the output will exceed the last row. You can set the wrap flag to a window at any time. WindowPrintf() -------------- The WindowPrintf() function writes formatted output to the window. Here is the prototype: int WindowPrintf(WPOINTER w, char *format [,arg1,...]) The first argument is the window. The second argument is a format string. The rest of the arguments are optional arguments that are written to the window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; char *s1 = "This string will wrap around to the next line\n"; char *s2 = "This escape code will ring the bell \a"; int i = 3; double j = 5.6; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowPrintf(w,"3+2 is equal to %d\n",3+2); GET_KEY(); WindowPrintf(w,"i is equal to %d\nj is equal to %lf\n", i,j); Page 44 The C Window Library Page 44 GET_KEY(); WindowPrintf(w,s1); GET_KEY(); WindowPrintf(w,s2); } The above example illustrates how WindowPrintf() is used to print formatted strings. The return values for WindowPrintf() are the same as WindowWriteString(). WindowPrintfAttr() ------------------ The WindowPrintfAttr() function writes formatted output to the window. The difference between WindowPrintf() and WindowPrintfAttr() is that WindowPrintfAttr() uses a video attribute specified as an argument. Here is the prototype: int WindowPrintfAttr(WPOINTER w, int attr, char *format [,arg1,...]) The first argument is the window. The second argument is the video attribute to use. The third argument is the format string. The rest of the arguments are optional arguments that are written to the window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; char *s1 = "This string will wrap around to the next line\n"; char *s2 = "This escape code will ring the bell \a"; int i = 3; double j = 5.6; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowPrintfAttr(w,REVERSE,"3+2 is equal to %d\n",3+2); GET_KEY(); WindowPrintfAttr(w,REVERSE, "i is equal to %d\nj is equal to %lf\n",i,j); GET_KEY(); WindowPrintfAttr(w,REVERSE,s1); WindowPrintfAttr(w,REVERSE,s2); } Page 45 The C Window Library Page 45 The above example illustrates how WindowPrintfAttr() is used to print formatted strings. The return values for WindowPrintfAttr() are the same as WindowWriteString(). Page 46 The C Window Library Page 46 WRITING TITLES TO WINDOWS ------------------------- This section only applies to bordered windows. There are two methods of writing text to the top or bottom border of a window. Each method has its advantages and disadvantages. The first method is to explicitly write to the border of the window. Except for the WindowPrintf...() functions, if you specify the row number to be -1, the text is written on the upper border of the window. If the row number is equal to the window height, the text is written on the lower border of the window. To access the window's height use the macro WINDOW_HEIGHT() described later in the WINDOW MACROS section. If you want to write a formatted string on the border of the window, use the standard library function sprintf() to create a string of formatted output, and then write this string with one of the WindowWrite...() functions. Any text that is written on the borders of a window are not retained if the window is resized using one of the WindowResize...() functions, or if the border is changed using WindowDrawBorder(). Therefore it is a good idea to maintain what is on the borders of the window in your own string variables. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); /* Specify row 0 to write on */ WindowWriteCenterString(w,"This is a title",-1); WindowWriteCenterString(w,"This is a title", WINDOW_HEIGHT(w)); } Page 47 The C Window Library Page 47 The second method is writing a string of text to either the top or bottom border by using the WindowTitle...() functions. The advantage of using these functions is that the strings are retained automatically if the window is resized or the border type is changed. Another advantage is that if the title does not fit in the boundaries of the window, the title is truncated, but the full title is retained in a buffer. If the window is later resized so that the title can fit, the full title will appear on the border. The disadvantage is that only one string of text is allowed for the top and bottom borders, and there are only three positions on each border to place the title. WindowTitleTop() ---------------- The WindowTitleTop() function writes a title to the top border of a window. Here is the prototype: int WindowTitleTop(WPOINTER w, char *title, int pos) The first argument is the window to write the title. The second argument is the title to write. The third argument is the position to place the title. Here is a list of valid constants to use for the position: Title Constant Description ┌───────────┬────────────────────────────────────────────┐ │TITLELEFT │Places the title starting at column 1 of the│ │ │window. │ ├───────────┼────────────────────────────────────────────┤ │TITLECENTER│Centers the title in the window. │ ├───────────┼────────────────────────────────────────────┤ │TITLERIGHT │Right justifies the title to the last column│ │ │of the window. │ └───────────┴────────────────────────────────────────────┘ Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); Page 48 The C Window Library Page 48 /* left justify title */ WindowTitleTop(w,"This is a title",TITLELEFT); GET_KEY(); /* center title */ WindowTitleTop(w,"This is a title",TITLECENTER); GET_KEY(); /* right justify title */ WindowTitleTop(w,"This is a title",TITLERIGHT); } Return Values for WindowTitleTop(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ WindowTitleBottom() ------------------- The WindowTitleBottom() function writes a title to the bottom border of a window. Here is the prototype: int WindowTitleBottom(WPOINTER w, char *title, int pos) The first argument is the window to write the title. The second argument is the title to write. The third argument is a constant that denotes the position to place the title. A list of valid constants can be found in the description of WindowTitleBottom() described above. #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); /* left justify title */ WindowTitleBottom(w,"This is a title",TITLELEFT); GET_KEY(); Page 49 The C Window Library Page 49 /* center title */ WindowTitleBottom(w,"This is a title",TITLECENTER); GET_KEY(); /* right justify title */ WindowTitleBottom(w,"This is a title",TITLERIGHT); } Return Values for WindowTitleBottom(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ WindowTitleTopAttr() -------------------- The WindowTitleTopAttr() function writes a title to the top border of a window with a specified color attribute. Here is the prototype: int WindowTitleTopAttr(WPOINTER w, char *title, int pos, int attr) The first argument is the window to write the title. The second argument is the title to write. The third argument is a constant that denotes the position to place the title. A list of valid constants can be found in the description of WindowTitleTopAttr() described above. The fourth argument is the color attribute to use. #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); /* left justify title */ WindowTitleTopAttr(w,"This is a title",TITLELEFT, REVERSE); Page 50 The C Window Library Page 50 GET_KEY(); /* center title */ WindowTitleTopAttr(w,"This is a title",TITLECENTER, REVERSE); GET_KEY(); /* right justify title */ WindowTitleTopAttr(w,"This is a title",TITLERIGHT, REVERSE); } Return Values for WindowTitleTopAttr(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ WindowTitleBottomAttr() ----------------------- The WindowTitleBottomAttr() function writes a title to the bottom border of a window with a specified color attribute. Here is the prototype: int WindowTitleBottomAttr(WPOINTER w, char *title, int pos, int attr) The first argument is the window to write the title. The second argument is the title to write. The third argument is a constant that denotes the position to place the title. A list of valid constants can be found in the description of WindowTitleBottomAttr() described above. The fourth argument is the color attribute to use. #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; int i; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); Page 51 The C Window Library Page 51 /* left justify title */ WindowTitleBottomAttr(w,"This is a title",TITLELEFT, REVERSE); GET_KEY(); /* center title */ WindowTitleBottomAttr(w,"This is a title",TITLECENTER, REVERSE); GET_KEY(); /* right justify title */ WindowTitleBottomAttr(w,"This is a title",TITLERIGHT, REVERSE); } Return Values for WindowTitleBottomAttr(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ Page 52 The C Window Library Page 52 READING CHARACTERS AND ATTRIBUTES FROM WINDOWS ---------------------------------------------- With The C Window Library, you can read the contents of a window into a character buffer. These functions provide the programmer with the contents of the window at any time. The functions to perform this are WindowReadAttributes(), WindowReadCharacters(), and WindowReadCharAndAttr(). WindowReadCharacters() ---------------------- The WindowReadCharacters() function reads the characters from a window into a buffer. Here is the prototype. int WindowReadCharacters(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is the buffer to store the characters in. The third and fourth arguments are the (row,col) position in the window to start reading from. The last argument is the number of characters to read. You must make sure that buffer has enough room to hold all of the characters read in. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; char buf[14] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Hello World!!",0,0);/* Write String */ WindowReadCharacters(w,buf,0,0,13); /* Read characters */ GET_KEY(); WindowWriteString(w,buf,1,0); /* Write what we have read */ } The example above illustrates the use of WindowReadCharacters(), which reads the window's contents Page 53 The C Window Library Page 53 starting at (0,0) of the window. This happens to be the string "Hello World!!". After GET_KEY() is called, the results of the buffer are written on line 1 of the window. If the length exceeds the right edge of the window, WindowReadCharacters() will read up to the right edge of the window. Return Values for WindowReadCharacters(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼────────────────────────┤ │WINDOW_BOUND │ Row or column specified│ │ │ is out of bounds. │ └────────────────┴────────────────────────┘ WindowReadAttributes() ---------------------- The WindowReadAttributes() function reads the attributes from a window into a buffer. Here is the prototype. int WindowReadAttributes(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is the buffer to store the attributes in. The third and fourth arguments are the (row,col) position in the window to start reading from. The last argument is the number of attributes to read. You must make sure that buffer has enough room to hold all of the attributes read in. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; char buf[14] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); Page 54 The C Window Library Page 54 WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Hello World!!",0,0);/* Write String */ WindowReadAttributes(w,buf,0,0,13); /* Read attributes */ GET_KEY(); WindowWriteString(w,buf,1,0); /* Write what we have read */ } The example above illustrates the use of WindowReadAttributes(), which reads the window's attribute contents starting at (0,0) of the window. This happens to be the attributes of the string "Hello World!!", which is the NORM attribute. After GET_KEY() is called, the results of the buffer are written on line 1 of the window. If the length exceeds the right edge of the window, WindowReadAttributes() will read up to the right edge of the window. Return Values for WindowReadAttributes(): Return Value Definition ┌────────────────┬───────────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼───────────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼───────────────────────────────┤ │WINDOW_BOUND │Row or Column is out of bounds.│ └────────────────┴───────────────────────────────┘ WindowReadCharAndAttr() ---------------------- The WindowReadCharAndAttr() function reads character/attribute pairs from a window into a buffer. Here is the prototype. int WindowReadCharAndAttr(WPOINTER w, char *buffer, int row, int col, int length) The first argument is the window. The second argument is the buffer to store the character/attribute pairs in. The third and fourth arguments are the (row,col) position in the window to start reading from. The last argument is the number of character/attribute pairs to read. You must make sure that buffer has enough room to hold all of the character/attribute pairs read in. Page 55 The C Window Library Page 55 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; char buf[27] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Hello World!!",0,0);/* Write String */ WindowReadCharAndAttr(w,buf,0,0,13); GET_KEY(); WindowWriteCharAndAttr(w,buf,1,0,13); /* Write what we have read */ } The example above illustrates the use of WindowReadCharAndAttr(), which reads the window's character/attribute contents starting at (0,0) of the window. This happens to be the characters/attributes of the string "Hello World!!". After GET_KEY() is called, the results of the buffer are written on line 1 of the window. If the length exceeds the right edge of the window, WindowReadCharAndAttr() will read up to the right edge of the window. Return Values for WindowReadCharAndAttr(): Return Value Definition ┌────────────────┬───────────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼───────────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼───────────────────────────────┤ │WINDOW_BOUND │Row or Column is out of bounds.│ └────────────────┴───────────────────────────────┘ Page 56 The C Window Library Page 56 HIDING WINDOWS -------------- With The C Window Library, you can hide windows at any time without disturbing the contents of other windows. WindowHide() ------------ The WindowHide() function hides a window on the screen from view. The window retains all text and shadows that may be present. Here is a prototype: int WindowHide(WPOINTER w, int effect) The first argument is the window, and the last argument is the special effect to use when hiding the window. For a list of special effects, refer to the DISPLAYING WINDOWS section. Example : #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_) #define BLACKONWHITE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w1,w2,w3; main() { WindowInitializeSystem(); WindowInitDesktop(0); /* Initialize all windows */ w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); w2 = WindowInitialize(DESKTOP_WINDOW,BORDER,1,1,20,10, REDONWHITE,NORM,DOUBLEBOX); w3 = WindowInitialize(DESKTOP_WINDOW,BORDER,2,2,20,10, BLACKONWHITE,NORM,SINGLEBOX); /* Display All windows */ WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); WindowDisplay(w3,3,NOEFFECT); WindowWriteString(w1,"This is window 1",0,0); WindowWriteString(w2,"This is window 2",1,0); WindowWriteString(w3,"This is window 3",2,0); GET_KEY(); WindowHide(w3,NOEFFECT); GET_KEY(); WindowHide(w2,BRICKS); GET_KEY(); WindowHide(w1,CONTRACT); } Page 57 The C Window Library Page 57 The example initializes, opens, and displays three windows. Note that you can hide windows regardless of the order in which they were displayed. This makes for very flexible window management. Return Values for WindowHide(): Return Value Definition ┌────────────────┬──────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼──────────────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴──────────────────────────────┘ Page 58 The C Window Library Page 58 CREATING COPIES OF A WINDOW --------------------------- You can create copies of a window without going using the WindowInitialize() function. WindowCopy() ------------ The WindowCopy() function makes a copy of a previous window. The copy will have the same colors, border type, shadow, parent window, and may have the same text as a previous window. If the original window is a viewport on a virtual window (virtual windows are discussed later in the VIRTUAL WINDOWS section), the copy can also be made a viewport on the same virtual window. The only thing that will not be copied is the (row,col) of the original window. You supply the position of the new window. Here is the prototype: WPOINTER WindowCopy(WPOINTER w, int row, int col, int options) Please note that WindowCopy() returns a new WPOINTER. You must assign the return value to a WPOINTER or you will not get easy access to the newly created window. The first argument is the original window to copy. This window must already exist. The second and third arguments are the coordinates of where to place the new window. The last argument are additional options that control whether the window will contain the same text as the previous window, and if the new window will be made a viewport if the original window is a viewport. The constants used for options is as follows: Options Action ┌────────────┬─────────────────────────────────────────┐ │MAKECHILD │ Makes new window a child of w's parent. │ ├────────────┼─────────────────────────────────────────┤ │COPYTEXT │ Makes a copy of the text area of the │ │ │ original window. │ ├────────────┼─────────────────────────────────────────┤ │MAKEVIEWPORT│ Turns the copy into a viewport if the │ │ │ original is a viewport. │ ├────────────┼─────────────────────────────────────────┤ │NO_OPTIONS │ No options desired. │ └────────────┴─────────────────────────────────────────┘ As was stated before, viewports are discussed in the VIRTUAL WINDOW section of the manual. If options is NO_OPTIONS, the windows size, border type, shadow (if there is a shadow) and colors are copied. Page 59 The C Window Library Page 59 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w,w2; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,45,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w, "This will be copied to the new window",0,0); GET_KEY(); w2 = WindowCopy(w,3,3,COPYTEXT); /* Make a copy of w */ WindowDisplay(w2,1,NOEFFECT); /* Display this copy */ GET_KEY(); WindowCloseAll(0,NOEFFECT); } Return Values for WindowCopy(): Return Value Definition ┌────────────────┬───────────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────────────────┤ │BAD_WINDOW │Window to copy from does not exist.│ ├────────────────┼───────────────────────────────────┤ │NO_HEAP_MEM │Not enough memory to allocate for │ │ │new window. │ ├────────────────┼───────────────────────────────────┤ │MAX_WINDOW │Maximimum number of windows defined│ └────────────────┴───────────────────────────────────┘ Page 60 The C Window Library Page 60 SCROLLING TEXT IN WINDOWS ------------------------- With The C Window Library, you can scroll text in a window up, or down, or scroll just particular regions of a window. The functions used to scroll windows are WindowScroll(), WindowScrollAttr(), WindowScrollRegion(), and WindowScrollRegionAttr(). When specifying a direction, use the constant UP to scroll up or DOWN to scroll down. These constants are defined in cwlwin.h. WindowScroll() -------------- If you want to scroll the entire window either up or down, you can use the WindowScroll() function. Here is a prototype: int WindowScroll(WPOINTER w, int numlines, int direction) The first argument is the window to scroll. The second argument is the number of lines to scroll. The last argument is the direction to scroll the window (either UP or DOWN). Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteRepeatCharacter(w,'A'+i,i,0,20); GET_KEY(); WindowScroll(w,1,UP); GET_KEY(); WindowScroll(w,3,DOWN); } The above example creates text using WindowWriteRepeatCharacter() function. The WindowScroll() Page 61 The C Window Library Page 61 calls will scroll the window up by one line, and then scroll the window down by 3 lines. Return Values for WindowScroll(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ WindowScrollRegion() -------------------- The WindowScrollRegion() functions scrolls a specified region of a window. To use the WindowScrollRegion() function, you must describe the rectangular region to scroll. Here is the prototype: int WindowScrollRegion(WPOINTER w, int numlines, int urow, int ucol, int lrow, int lcol, int direction) Arguments 3 thru 6 describe the rectangular region. They are in the order of upper left row, upper left column, lower right row, lower right column. All of these coordinates are window relative. The second argument is the number of lines to scroll. The last argument is the direction. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteRepeatCharacter(w,'A'+i,i,0,20); GET_KEY(); WindowScrollRegion(w,1,2,2,4,10,UP); GET_KEY(); WindowScrollRegion(w,3,7,2,9,8,DOWN); } Page 62 The C Window Library Page 62 The above example creates text using WindowWriteRepeatCharacter() function. The first WindowScrollRegion() call will scroll the region described by the rectangular coordinates (2,2) and (4,10). This region is scrolled up one line. The second call to WindowScrollRegion() scrolls the region defined by the rectangular region (7,2) and (9,8). This region is scrolled down by three lines. Return Values for WindowScrollRegion(): Return Value Definition ┌────────────────┬───────────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────────────────┤ │BAD_WINDOW │Window does not exist. │ ├────────────────┼───────────────────────────────────┤ │WINDOW_BOUND │The rectangular region defined │ │ │is out of bounds of the window. │ └────────────────┴───────────────────────────────────┘ WindowScrollAttr() ------------------ This function works the same way as the WindowScroll() function except that an attribute is defined for the blank lines that are created when the window is scrolled. Here is a prototype: int WindowScrollAttr(WPOINTER w, int numlines, int direction, int attr) The last argument is the attribute to use for the blank lines created. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); Page 63 The C Window Library Page 63 for (i=0;i<10;i++) WindowWriteRepeatCharacter(w,'A'+i,i,0,20); GET_KEY(); WindowScrollAttr(w,1,UP,REDONWHITE); GET_KEY(); WindowScrollAttr(w,3,DOWN,REDONWHITE); } The above example creates text using WindowWriteRepeatCharacter() function. The WindowScrollAttr() calls will scroll the window up by one line, and then scroll the window down by 3 lines with both scrolls using REDONWHITE as the video attribute. WindowScrollAttr() returns the same values as WindowScroll(). WindowScrollRegionAttr() ------------------------ This function works the same way as the WindowScrollRegion() function except that an attribute is defined for the blank lines that are created when the window is scrolled. Here is a prototype: int WindowScrollRegionAttr(WPOINTER w, int numlines, int int urow, int ucol, int lrow, int lcol, int direction, int attr) The last argument is the attribute to use for the blank lines created. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteRepeatCharacter(w,'A'+i,i,0,20); GET_KEY(); WindowScrollRegionAttr(w,1,3,5,6,15,UP,REDONWHITE); Page 64 The C Window Library Page 64 GET_KEY(); WindowScrollRegionAttr(w,3,8,4,10,12,DOWN,REDONWHITE); } The above example creates text using WindowWriteRepeatCharacter() function. The first WindowScrollRegionAttr() call will scroll the region described by the rectangular coordinates (3,5) and (6,15). This region is scrolled one line. The second call to WindowScrollRegionAttr() scrolls the region defined by the rectangular region (8,4) and (10,12). This region is scrolled down by three lines. All blank lines use the video attribute REDONWHITE. WindowScrollRegionAttr() returns the same values as WindowScrollRegion(). Page 65 The C Window Library Page 65 CLEARING WINDOWS ---------------- The C Window Library contains functions that clears the entire window, or clears defined rectangular regions of the window. WindowClear() ------------- The WindowClear() function clears an entire window to spaces. The attribute used is the current attribute of the text area of the window. Here is the prototype: int WindowClear(WPOINTER w) The only argument is the window to clear. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowClear(w); } Return Values for WindowClear(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ Page 66 The C Window Library Page 66 WindowClearAttr() ----------------- The WindowClearAttr() function works the same way as the WindowClear() function except that an attribute is specified. Here is the prototype: int WindowClearAttr(WPOINTER w, int attr) The second argument is the video attribute to use. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowClearAttr(w,REDONWHITE); } The return values for WindowClearAttr() are the same as WindowClear(). WindowClearRegion() ------------------- The WindowClearRegion() function clears a region of a window. To use the WindowClearRegion() function, you must describe the rectangular region to clear. Here is the prototype: int WindowClearRegion(WPOINTER w, int urow, int ucol, int lrow, int lcol) where (urow,ucol) describes the upper left of the rectangle and (lrow,lcol) is the lower right of the window. These coordinates are window relative. Page 67 The C Window Library Page 67 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowClearRegion(w,4,4,8,15); } The WindowClearRegion() call will clear the region described by the rectangular coordinates (4,4) and (8,15). Return Values for WindowClearRegion(): Return Value Definition ┌────────────────┬───────────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────────────────┤ │BAD_WINDOW │Window does not exist. │ ├────────────────┼───────────────────────────────────┤ │WINDOW_BOUND │The rectangular region defined │ │ │is out of bounds of the window. │ └────────────────┴───────────────────────────────────┘ WindowClearRegionAttr() ----------------------- The WindowClearRegionAttr() function works the same as the WindowClearRegion() function, except that a video attribute is specified. Here is the prototype: int WindowClearRegionAttr(WPOINTER w, int urow, int ucol, int lrow, int lcol, int attr) The attr argument is a video attribute to use to clear the region. Page 68 The C Window Library Page 68 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REDONWHITE CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_) WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowClearRegionAttr(w,4,4,8,15,REDONWHITE); } The WindowClearRegionAttr() call will clear the region described by the rectangular coordinates (4,4) and (8,15) using the video attribute defined by the constant REDONWHITE. The WindowClearRegionAttr() returns the same values as WindowClearRegion(). Page 69 The C Window Library Page 69 WRITING WINDOW CONTENTS TO A FILE --------------------------------- The C Window Library allows you to print the contents of a window using the WindowWriteTextToFile() function. WindowWriteTextToFile() ----------------------- The WindowWriteTextToFile() function allows you to print the contents of a window to a file. Here is the prototype: int WindowWriteTextToFile(WPOINTER w, char *filename, int mode) The first argument is the window. The second argument is the file name. This file can be any of the DOS filenames ("con", "prn", "aux", etc.). The file specified by filename must be closed before calling WindowWriteTextToFile(), and the file handle is automatically closed before exiting WindowWriteTextToFile(). The last argument is the mode switch. If mode is 1, a newline ('\n') is written to the file after each line of the window is written to the file. If mode is 0, no newline character is written. Example: #include "cwlwin.h" #include <stdio.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; FILE *outfile; char *filename = "wintext"; char *filename2 = "wintext2"; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); for (i=0;i<10;i++) WindowWriteString(w,"Hello World!!",i,1); GET_KEY(); WindowWriteTextToFile(w,filename,1); /* use newlines */ WindowWriteTextToFile(w,filename2,0); /* no newlines */ } Page 70 The C Window Library Page 70 The example above illustrates two calls to WindowWriteTextToFile(). The first call writes the contents of the window w to a file called "wintext". Note that the mode parameter for the first call is 1. This will cause '\n' to be written to the file for each line of the window. The second call writes the window text to a file call "wintest2", with the mode parameter being 0 (no '\n'). Please note that WindowWriteTextToFile() does not check if the file already exists, so be careful that you do not replace files that are important to you. Return Values for WindowWriteTextToFile(): Return Value Definition ┌────────────────┬────────────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼────────────────────────────────────┤ │BAD_WINDOW │Window to copy from does not exist. │ ├────────────────┼────────────────────────────────────┤ │WINDOW_BOUND │The rectangular region defined │ │ │is out of bounds of the window. │ ├────────────────┼────────────────────────────────────┤ │FILE_CANT_OPEN │The file specified cannot be opened.│ ├────────────────┼────────────────────────────────────┤ │FILE_CANT_CLOSE │The file specified cannot be closed.│ └────────────────┴────────────────────────────────────┘ Page 71 The C Window Library Page 71 SHADOWING WINDOWS ----------------- With The C Window Library, you can place shadows on the windows created. Shadows create a nice effect when displayed with the proper background color. There are four positions where you can place a shadow on a window: the upper left corner of the window, the upper right corner, the lower left corner or the lower right corner. The shadow consists of two components. One of these components is the part of the shadow that is drawn either on the left or right side of the window. You can control the width of this portion of the shadow. The other component that makes up the shadow is the portion that is drawn either on top of or underneath a window. You can control the height of this portion of the shadow. You can also control the shadows video attribute, as well as the character that makes up the shadow itself. My suggestion is to use ASCII character 219 for the shadow character. Other ones that work well are ASCII 176, 178, and 178. Transparent shadows are also supported. You can place a shadow on a window at any time or take it off at any time. The only restriction with the shadow is that the window's current position must have room to draw the shadow. When shadows are drawn, CWL uses a window to draw the shadow. The rank of a window's shadow is one higher than the window itself. Therefore, you should note that a window is being used by CWL and that the number of windows available is reduced for each shadowed window. WindowDrawShadow() ------------------ The WindowDrawShadow() function places a shadow on a window. Here is the prototype: int WindowDrawShadow(WPOINTER w, int shadowpos, int width, int height, int shadowchar, int shadowattr, int transflag) The first argument is the window that the shadow will be drawn. The second argument is the position of the shadow. There are four possible positions: Page 72 The C Window Library Page 72 Shadow Constant Function ┌──────────────┬────────────────────────────────────────────┐ │SHADOWUPRIGHT │Draws shadow on upper right corner of the │ │ │window. │ ├──────────────┼────────────────────────────────────────────┤ │SHADOWUPLEFT │Draws shadow on upper left corner of the │ │ │window. │ ├──────────────┼────────────────────────────────────────────┤ │SHADOWLOWRIGHT│Draws shadow on lower right corner of │ │ │window. │ ├──────────────┼────────────────────────────────────────────┤ │SHADOWLOWLEFT │Draws shadow on lower left corner of window.│ └──────────────┴────────────────────────────────────────────┘ The third argument is the width of the strip of the shadow that is drawn on the right or left side of the window. The fourth argument is the height of the strip of the shadow that is drawn on top or underneath the window. The fifth argument is the character to use for the shadow. The sixth argument is the attribute to use for the shadow. The last argument is a flag denoting whether the shadow should be a transparent shadow. If the flag is 0, the shadow is solid, otherwise the shadow is transparent. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,BLUE_) #define REDONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,RED_) #define GREENONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,GREEN_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) main() { WPOINTER w0,w1; WindowInitializeSystem(); WindowInitDesktop(0); w0 = WindowInitialize(DESKTOP_WINDOW,NOBORDER,0,0,80,25, REVERSE,REVERSE,0); WindowDisplay(w0,1,NOEFFECT); w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,5,5,40,15, BLUEONBLACK,REDONBLACK,SINGLEBOX); WindowDrawShadow(w1,SHADOWUPLEFT,2,1,219,REVERSE,0); WindowDisplay(w1,1,NOEFFECT); WindowWriteString(w1,"Press a key to move shadow",0,0); GET_KEY(); WindowDrawShadow(w1,SHADOWUPRIGHT,2,1,219,REVERSE,0); WindowWriteString(w1,"Press a key again",2,1); GET_KEY(); WindowDrawShadow(w1,SHADOWLOWLEFT,2,1,219,REVERSE,0); WindowWriteString(w1,"Press a key once more",3,1); GET_KEY(); Page 73 The C Window Library Page 73 WindowDrawShadow(w1,SHADOWLOWRIGHT,2,1,219,REVERSE,0); GET_KEY(); WindowClose(w1,NOEFFECT); WindowClose(w0,NOEFFECT); } The above example illustrates the use of WindowDrawShadow(). Return Values for WindowDrawShadow(): Return Value Definition ┌────────────────┬─────────────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼─────────────────────────────────────┤ │BAD_WINDOW │Window to copy from does not exist. │ ├────────────────┼─────────────────────────────────────┤ │WINDOW_BOUND │The rectangular region defined │ │ │is out of bounds of the window. │ ├────────────────┼─────────────────────────────────────┤ │MAX_WINDOW │Maximum number of windows defined. │ └────────────────┴─────────────────────────────────────┘ WindowRemoveShadow() -------------------- The WindowRemoveShadow() function removes a shadow from a window, and takes a single argument, namely the window pointer. Here is the prototype: int WindowRemoveShadow(WPOINTER w) Return Values for WindowRemoveShadow(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ Page 74 The C Window Library Page 74 SEE-THRU WINDOWS ---------------- You can create windows that have borders, but do not overwrite the screen underneath. These windows are called see-thru windows. When creating see-thru windows the WindowMakeSeeThru() function is used to make a defined window a see-thru window. You can turn a non-seethru window into a seethru window and vice-versa by calling the WindowMakeNormal() function. WindowMakeSeeThru() ------------------- The WindowMakeSeeThru() function turns a normal window into a see-thru window. Here is a prototype: int WindowMakeSeeThru(WPOINTER w) The only argument is the window pointer. You can make a window a see-thru window at any time, including if it is hidden. If there is text in the normal window before making it a see-thru window, the text is retained. If text is written to a see-thru window, the text is written to the window's internal write buffer, but is not displayed on the screen. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,5, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowMakeSeeThru(w); GET_KEY(); WindowClose(w,NOEFFECT); } Page 75 The C Window Library Page 75 The example above displays a normal window, and then turns the normal window into a see-thru window when a key is pressed. Return Values for WindowMakeSeeThru(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ WindowMakeNormal() ------------------ The WindowMakeNormal() function turns a see-thru window into a normal text window. Any text that may have been written to the window will be displayed. Here is the prototype: int WindowMakeNormal(WPOINTER w) Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,5, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowMakeSeeThru(w); GET_KEY(); WindowMakeNormal(w); } The example above demonstrates the WindowMakeNormal() function. Return Values for WindowMakeNormal(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ Page 76 The C Window Library Page 76 MOVING AND SLIDING WINDOWS -------------------------- With The C Window Library, you can move and slide windows on the parent window, or desktop window if the window is a top-level window. The functions that perform this are the WindowMove() and WindowSlide(). WindowMove() ------------ The WindowMove() function moves a window to a new location in the parent window. Here is the prototype: int WindowMove(WPOINTER w, int row, int col) The first argument is the window. The second and third arguments are the row and column on the parent to place the upper left hand corner of the window. Note that row and column are parent-relative coordinates, not window relative. This is one of the few functions where row and column denote a position in the window's parent (the DESKTOP_WINDOW is the parent of a top-level window). Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,BLUE_) main() { WPOINTER w; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,15, BLUEONBLACK,NORM,SINGLEBOX); WindowWriteString(w,"Press a key to move me",0,0); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowMove(w,12,14); } The example above moves the window from its original position (0,0) to (12,14). Return Values for WindowMove(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ Page 77 The C Window Library Page 77 WindowSlide() ------------- The WindowSlide() function "slides" a window from one position on the parent window to another. Here is the prototype: int WindowSlide(WPOINTER w, int direction, int units) The first argument is the window. The second argument tells in which direction to move the window, either up, down, left, or right. The constants to use for up, down, left, and right are UP, DOWN, LEFT, and RIGHT, respectively. The third argument tells how many rows or columns to move the window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define BLUEONBLACK CREATE_VIDEO_ATTRIBUTE(BLACK_,BLUE_) main() { WPOINTER w; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, BLUEONBLACK,NORM,SINGLEBOX); WindowWriteString(w,"Press a key to slide right",0,0); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowSlide(w,RIGHT,20); WindowWriteString(w,"Press a key to slide down",1,0); GET_KEY(); WindowSlide(w,DOWN,10); WindowWriteString(w,"Press a key to slide left",2,0); GET_KEY(); WindowSlide(w,LEFT,20); WindowWriteString(w,"Press a key to slide up",3,0); GET_KEY(); WindowSlide(w,UP,20); } The example above illustrates how to use the WindowSlide() function. The return values for WindowSlide() are the same as WindowMove(). Page 78 The C Window Library Page 78 CURSOR POSITIONING IN WINDOWS ----------------------------- You can change the position of the cursor and its shape in the windows you create with The C Window Library. Cursor Maintenance in The C Window Library ------------------------------------------ As was stated before, The C Window Library can write to any window at any time. This makes the question "which window owns the cursor?" a hard question to answer. One method is that the window being updated either by writing text, clearing, etc. should have immediate control of the cursor. The approach The C Window Library has taken is that the topmost window always has control of the cursor. The topmost window is the top-level window with the lowest rank number. Windows with low rank numbers overlay windows with higher rank numbers. Creating Cursor Shapes ---------------------- The C Window Library has four pre-defined cursor shapes; INVISIBLE, THIN, BLOCK, and HALFBLOCK. An INVISIBLE cursor hides the cursor, a BLOCK shape creates a "fat" cursor, and THIN creates a thin cursor. The HALFBLOCK cursor is between a BLOCK and a THIN cursor. If you want to define your own cursor shapes, use the CREATE_CURSOR_SHAPE() macro. This macro takes two arguments the first argument is the beginning scan line, and the second argument is the ending scan line. Scan lines determine the height of the cursor. For monochrome systems, the scan lines range from 0 to 13. In a color system, the scan lines range from 0 to 7. A THIN cursor has its starting scan line at 6 and its ending scan line at 7 for color systems, and for monochrome systems, the starting scan line is 11 and its ending scan line is at 12. If the starting scan line number is greater than the ending scan line number, the cursor takes on a 'double' cursor shape. Experiment with different starting and ending scan lines for the desired effect. WindowChangeCursor() -------------------- The WindowChangeCursor() function changes the shape of the cursor in a window. Here is the prototype: int WindowChangeCursor(WPOINTER w, int shape) Page 79 The C Window Library Page 79 The first argument is the window. The second argument is the desired cursor shape. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Press a key to change cursor",0,0); GET_KEY(); WindowChangeCursor(w,BLOCK); WindowWriteString(w,"Press a key to change cursor again", 1,0); GET_KEY(); WindowChangeCursor(w,INVISIBLE); WindowWriteString(w,"Press a key to change cursor again", 2,0); GET_KEY(); WindowChangeCursor(w,THIN); } Return Values for WindowChangeCursor(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ WindowMoveCursor() ------------------ The WindowMoveCursor() functions moves the cursor in a window to a new location in the window. Here is the prototype: int WindowMoveCursor(WPOINTER w, int row, int col) Page 80 The C Window Library Page 80 The first argument is the window, and the second and third arguments are the new (row,col) position in the window to place the cursor. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Press a key to move cursor",0,0); GET_KEY(); WindowMoveCursor(w,7,5); } Return Values for WindowMoveCursor(): Return Value Definition ┌────────────────┬────────────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼────────────────────────────────────┤ │BAD_WINDOW │Window does not exist. │ ├────────────────┼────────────────────────────────────┤ │WINDOW_BOUND │Row or column number is │ │ │out of the boundaries of the window │ └────────────────┴────────────────────────────────────┘ WindowGetCursorShape() ---------------------- The WindowGetCursorShape() function returns the starting and ending scan lines of the cursor defined in a window. Here is the prototype: int WindowGetCursorShape(WPOINTER w, int *startline, int *endline) The startline and endline arguments are pointers to integers that will contain the starting and ending scan lines of the cursor when WindowGetCursorShape() returns. Page 81 The C Window Library Page 81 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { int startline,endline; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowGetCursorShape(w,&startline,&endline); WindowPrintf(w, "The starting scan line is %d\nThe ending scan line is %d", startline,endline); } The example above calls WindowGetCursorShape() and uses WindowPrintf() to print what the starting and ending scan lines are. Return Values for WindowGetCursorShape(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ WindowGetCursorPosition() ------------------------- The WindowGetCursorPosition() function gives the current row and column of the cursor in a window. Here is the prototype: int WindowGetCursorPosition(WPOINTER w, int *row, int *col) The row and col arguments are pointers to integers that will contain the row and column of the cursor after WindowGetCursorPosition() is called. Page 82 The C Window Library Page 82 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { int row,col; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowMoveCursor(w,7,4); WindowGetCursorPosition(w,&row,&col); WindowPrintf(w, "The row of the cursor is %d\n" "The column of the cursor is %d", row,col); } Return Values for WindowGetCursorPosition(): Return Value Definition ┌────────────────┬───────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼───────────────────────┤ │BAD_WINDOW │Window does not exist. │ └────────────────┴───────────────────────┘ Page 83 The C Window Library Page 83 GETTING WHICH WINDOW OCCUPIES A LOCATION ---------------------------------------- You can determine the WPOINTER which occupies a location on the screen. If you have multiple windows displayed, this can be very useful if you have overlaps and want to know which window is visible in a given screen location. WindowWhich() ------------- The WindowWhich() function determines which window is visible on a given desktop window location. Here is the prototype: WPOINTER WindowWhich(int row, int col, int page) Note that WindowWhich() returns a WPOINTER. The arguments row and col are desktop (screen) coordinates. The last argument, page, is the video page to use when determining which window lies in position (row,col). The WPOINTER that is returned is the WPOINTER that occupies the specified screen location. #include "cwlwin.h" WPOINTER w1, w2, w3, w4, w5; main() { /* ... Assume everything including windows have been initialized and opened */ if (WindowWhich(4,7,0) == w1) { /* some part of w1 is visible on row 4 column 7 of the screen (video page 0) */ } } The above example calls WindowWhich to determine if w1 is visible on position (4,7) of video page 0. Refer to the INTRODUCTION on video pages. If there is no window visible for a given screen location, WIN_NULL_PTR is returned. The base screen will always return a WIN_NULL_PTR. To convert from local window coordinates to desktop coordinates and vice-versa, refer to the CHILD WINDOWS section in this manual. Page 84 The C Window Library Page 84 GETTING INPUT FROM WINDOWS -------------------------- With The C Window Library, you can read input from windows. The input can be simple string input, or inputting strings with a character mask. There is also support for scrolling input fields. Input Manager ------------- The input manager are functions internal in The C Window Library that control editing, checking for invalid characters, cursor movement, etc. Regular Expressions ------------------- With The C Window Library, you specify exactly what characters are to be expected for every input position by using a special string of characters called a regular expression (a pattern matching string). Note: For those who are familiar with regular expressions, there is a difference between the regular expressions you will see here, and the regular expressions you will find in certain text editors, or in computer language syntax definitions. One major difference is that there are no wild cards denoting an arbitrary number of repeated characters (which is usually denoted by a '*' or a '+'), and there are no 'match begin of string' and 'match end of string' functions. An example of a regular expression would be the string "[A-Z]" which means only those characters that are between A and Z, inclusive, are to be accepted as valid input characters. Of course, the ASCII collating sequence is used. The following characters have special meanings in regular expressions: Character Purpose ┌─────────────────────┬────────────────────────────────────┐ │ Forward Slash (/) │ Removes the special meaning of the│ │ │ next character in the regular │ │ │ expression. │ └─────────────────────┴────────────────────────────────────┘ Page 85 The C Window Library Page 85 Character Purpose ┌─────────────────────┬───────────────────────────────────────┐ │ Brackets ([]) │ Encloses a set of characters to be │ │ │ matched with the current character │ │ │ entered at the keyboard. There are │ │ │ other special symbols that can appear│ │ │ in brackets: │ └─────────────────────┼─────────────┬─────────────────────────┤ │ Carat (^) │ This symbol states that │ │ │ the character entered at│ │ │ the keyboard must not │ │ │ match any character in │ │ │ the brackets. The carat│ │ │ must be the first │ │ │ character after the left│ │ │ bracket ([), otherwise │ │ │ the carat is taken │ │ │ literally as just │ │ │ another character. │ ├─────────────┼─────────────────────────┤ │ Dash (-) │ Matches character │ │ │ entered at keyboard with│ │ │ characters in ASCII │ │ │ order between │ │ │ (inclusive) the │ │ │ characters on either │ │ │ side of the dash. │ ├─────────────┼─────────────────────────┤ │ Dot (.) │ Matches any displayable │ │ │ ASCII character. │ └─────────────┴─────────────────────────┘ There are two categories of regular expressions; namely simple and complex. Simple regular expressions only specify a single character to be entered from the keyboard, while complex regular expressions specify that more than a single character must be entered from the keyboard. Here are examples of simple regular expressions: Simple Regular Expression What will be accepted ┌────────┬───────────────────────────────┐ │[0-9] │ Accept any single digit │ │ │ character. │ ├────────┼───────────────────────────────┤ │[3-7] │ Accept single digit character│ │ │ between '3' and '7' │ │ │ inclusive. │ ├────────┼───────────────────────────────┤ │[A-Z] │ Accept a letter between 'A' │ │ │ and 'Z' inclusive. │ └────────┴───────────────────────────────┘ Page 86 The C Window Library Page 86 ┌───────────┬────────────────────────────────┐ │[A-Za-z] │ Accept a letter between 'A' │ │ │ and 'Z' or a letter between │ │ │ 'a' and 'z'. │ ├───────────┼────────────────────────────────┤ │[ABCD] │ Accept either 'A', 'B', 'C', │ │ │ or 'D'. │ ├───────────┼────────────────────────────────┤ │[A-Za-z0-9]│ Accept anything between 'A' │ │ │ and 'Z', or 'a' and 'z', or │ │ │ '0' and '9' │ ├───────────┼────────────────────────────────┤ │[0-9ABCD] │ Accept '0' thru '9', 'A', │ │ │ 'B', 'C', or 'D'. │ ├───────────┼────────────────────────────────┤ │[^A] │ Accept any character except │ │ │ 'A'. │ ├───────────┼────────────────────────────────┤ │[^A-Z] │ Accept any character except │ │ │ the characters between 'A' │ │ │ and 'Z' (inclusive). │ ├───────────┼────────────────────────────────┤ │[A-/[] │ Accept any character between │ │ │ 'A' and '[', inclusive. │ │ │ Please note the use of the │ │ │ forward slash to denote that │ │ │ the left bracket has no │ │ │ special meaning. │ ├───────────┼────────────────────────────────┤ │[A Z] │ Accept 'A', the space │ │ │ character, or 'Z'. │ ├───────────┼────────────────────────────────┤ │[A/-Z] │ Accept 'A', the minus (-), or │ │ │ 'Z'. │ ├───────────┼────────────────────────────────┤ │[/-///]] │ Accept the minus (-), the │ │ │ forward slash (/), or the │ │ │ right bracket (]). │ ├───────────┼────────────────────────────────┤ │[!-&] │ Accept the ASCII characters │ │ │ between '!' and '&', │ │ │ inclusive. │ ├───────────┼────────────────────────────────┤ │A │ Accept the letter 'A'. Note │ │ │ that this is equivalent to │ │ │ [A]. │ ├───────────┼────────────────────────────────┤ │[9] │ Accept the digit '9'. │ ├───────────┼────────────────────────────────┤ │. │ Accept any character. │ ├───────────┼────────────────────────────────┤ │[] │ Accept no key and call user │ │ │ defined function (explained │ │ │ later in the UNDEFINED │ │ │ KEYSTROKE PROCESSING │ │ │ section). │ └───────────┴────────────────────────────────┘ Page 87 The C Window Library Page 87 ┌───────────┬───────────────────────────────┐ │# │ Accept a numeric digit. This│ │ │ is shorthand for [0-9]. │ ├───────────┼───────────────────────────────┤ │@ │ Accept an alphabetic │ │ │ character. This is shorthand│ │ │ for [A-Za-z]. │ └───────────┴───────────────────────────────┘ Remember, all of the above expressions process only one character entered at the keyboard, even though some of the expressions can accept a variety of characters. As you can see there are many possibilities you can make up. However the above forms of a regular expressions only work for one character entered at the keyboard. What if you want to enter a persons name, address, social security number etc.? You can concatenate (glue together) the regular expressions above to form a chain of regular expressions. This resulting chain is called a complex regular expression. Here are a few examples of complex regular expressions: Regular Expression What will be accepted ┌──────────────────────────┬──────────────────────────────┐ │[A-Z][0-9] │ The first character entered │ │ │ must be between 'A' and 'Z'. │ │ │ The second character entered │ │ │ must be between '0' and '9'. │ ├──────────────────────────┼──────────────────────────────┤ │[A-Z][^A-Z][0-9] │ Enter three characters. The │ │ │ first must be between 'A' and│ │ │ 'Z'. The second can be any │ │ │ character except anything │ │ │ between 'A' and 'Z', and the │ │ │ third character must be │ │ │ between '0' and '9'. │ ├──────────────────────────┼──────────────────────────────┤ │[1-9][0-9][0-9][0-9][0-9] │ Enter five characters. The │ │ │ first must be between '1' and│ │ │ '9'. The other four │ │ │ characters must be between │ │ │ '0' and '9'. │ ├──────────────────────────┼──────────────────────────────┤ │[A-Z][][0-9] │ The first character must be │ │ │ between 'A' and 'Z', the │ │ │ second input position calls a│ │ │ user defined function │ │ │ (explained in UNDEFINED │ │ │ KEYSTROKE PROCESSING), and │ │ │ the third character must be │ │ │ between '0' and '9'. │ └──────────────────────────┴──────────────────────────────┘ As you can see again, the strings can get pretty long if you wanted to setup a thirty character input specification, for instance, a persons name. To save time typing, you can use a multiplying factor in the regular expression. A multiplying Page 88 The C Window Library Page 88 factor is a number that is placed before a simple regular expression to denote that the simple regular expression is repeated. Here are a few examples: Regular Expression What will be accepted ┌───────────────────┬───────────────────────────────────────┐ │25[A-Z] │Enter twenty-five characters. All the │ │ │characters must be between 'A' and 'Z'.│ ├───────────────────┼───────────────────────────────────────┤ │10[0-9] │Enter ten characters. All must be │ │ │between '0' and '9'. │ ├───────────────────┼───────────────────────────────────────┤ │5[A-C] 3[1-3] │Enter nine characters. The first five │ │ │must be between 'A' and 'C' the sixth │ │ │must be the space character, and the │ │ │last three must be between '1' and '3'.│ │ │Please note the space embedded in the │ │ │string just before the multiplying │ │ │factor 3. │ ├───────────────────┼───────────────────────────────────────┤ │[1-9]2X/[5[^A-Z]/1 │Enter nine characters. The first must │ │ │be between '1' and '9'. The second and│ │ │third must be 'X'. The fourth is the │ │ │left bracket ([). The next five │ │ │characters entered can be any character│ │ │except anything between 'A' and 'Z', │ │ │and the last character to accept is a │ │ │'1'. Please note the use of the │ │ │forward slash just before the second │ │ │left bracket and just before the last │ │ │character ('1'). The forward slash │ │ │before the '1' makes sure the '1' is │ │ │not to be confused with a multiplying │ │ │factor of 1. │ ├───────────────────┼───────────────────────────────────────┤ │[A-Z]/.. │Enter three characters. The first must│ │ │be between 'A' and 'Z'. The second is │ │ │the '.', and the third is any │ │ │character. │ ├───────────────────┼───────────────────────────────────────┤ │10[A-Z]3[] │Enter thirteen characters. The first │ │ │ten must be between 'A' and 'Z', and │ │ │the last three input positions will │ │ │call a user defined undefined key │ │ │function (explained later in the │ │ │UNDEFINED KEYSTROKE PROCESSING │ │ │section). │ └───────────────────┴───────────────────────────────────────┘ The only limitation to what you can do with regular expressions is that you cannot nest regular expressions. For example: [A-[A-Z]] or 20[20[a-z]] Page 89 The C Window Library Page 89 It is ok to say [9-0] instead of [0-9]. They are both equivalent and both accepted by The C Window Library, so there is no need to know your ASCII table by heart, although it is advantageous to learn it if you want to create sophisticated regular expression strings. You can even use the IBM extended character set (ASCII values above 127) in the regular expression string. Editing Input ------------- The C library function gets(x), gets a string from the keyboard and points the character pointer x to the string. This function has limited editing capabilities. The only keys recognized are the backspace, which serves as a destructive backspace (erases character immediately to the left) and the enter key when the user has typed in the desired string. With The C Window Library, you have much more editing capabilities. The editing functions have the following default key values: Mapped Function Key Position ┌───────────────────────────────────┬──────────────────┬───┐ │Move cursor left │Left Arrow │ 0 │ ├───────────────────────────────────┼──────────────────┼───┤ │Move cursor right │Right Arrow │ 1 │ ├───────────────────────────────────┼──────────────────┼───┤ │Delete character at cursor │Del (on keypad) │ 2 │ ├───────────────────────────────────┼──────────────────┼───┤ │Toggle Insert/Overwrite mode │Insert (on keypad)│ 3 │ ├───────────────────────────────────┼──────────────────┼───┤ │Erase Input and go to first column │^E │ 4 │ ├───────────────────────────────────┼──────────────────┼───┤ │Destructive backspace │Backspace │ 5 │ ├───────────────────────────────────┼──────────────────┼───┤ │Accept Input and return │Enter │ 6 │ ├───────────────────────────────────┼──────────────────┼───┤ │Accept default and return │Escape │ 7 │ ├───────────────────────────────────┼──────────────────┼───┤ │Go to first column │Home │ 8 │ ├───────────────────────────────────┼──────────────────┼───┤ │Move cursor to last char. entered │End │ 9 │ └───────────────────────────────────┴──────────────────┴───┘ Page 90 The C Window Library Page 90 Here is a list of what the key functions perform: ┌───────────────────┬──────────────────────────────────────┐ │Move cursor left │Moves the cursor left one character. │ │ │If the beginning of the input field is│ │ │encountered the cursor is not moved. │ ├───────────────────┼──────────────────────────────────────┤ │Move cursor right │Moves the cursor right one character. │ │ │If the end of the input field is │ │ │encountered, the cursor is not moved. │ ├───────────────────┼──────────────────────────────────────┤ │Delete character │Deletes the character at the position │ │at cursor │of the cursor. If in insert mode, │ │ │any input to the right of the cursor │ │ │is moved one character to the left. │ │ │If in overwrite mode, no characters │ │ │are moved. │ ├───────────────────┼──────────────────────────────────────┤ │Toggle │Toggles the input between insert and │ │Insert/Overwrite │overwrite mode. In insert mode, the │ │ │default cursor is an underline cursor.│ │ │If in overwrite mode, the default │ │ │cursor is a full block. │ ├───────────────────┼──────────────────────────────────────┤ │Erase Input │Deletes all characters inputted and │ │ │moves the cursor to the first input │ │ │position. │ ├───────────────────┼──────────────────────────────────────┤ │Destructive │Deletes the character immediately to │ │Backspace │the left of the cursor and moves the │ │ │cursor to the left one character. If │ │ │insert mode is on, the characters from│ │ │the current cursor position to the end│ │ │of the input field are also moved. │ ├───────────────────┼──────────────────────────────────────┤ │Accept string │Accepts the string that is inputted │ │ │and returns the string. │ ├───────────────────┼──────────────────────────────────────┤ │Accept default │Returns the default string given to │ │and return │the input routine. │ ├───────────────────┼──────────────────────────────────────┤ │Go to first column │Moves cursor to the first input │ │ │position. │ ├───────────────────┼──────────────────────────────────────┤ │Go to last │Moves cursor to the last character in │ │character │the current input string. │ └───────────────────┴──────────────────────────────────────┘ The keys used to perform these functions can be changed. The mapped position is the offset in a table of key functions. By changing the value there, you can change the key used to perform these functions. If you do want to change these keys, I recommend using the key definitions found in the cwlwin.h file. For example, if you wanted Control-B to be the destructive backspace you would do as follows: Page 91 The C Window Library Page 91 CWLedit_key[5] = CTRLB; The table of key functions is stored in the array CWLedit_key. The CTRLB stands for Control-B and its definition is found in the cwlwin.h file. To totally undefine a key definition, assign a 0 to the desired array position in CWLedit_key. For example: CWLedit_key[2] = 0; undefines the delete character at cursor definition. When changing keys, make sure that the definitions all have unique key combinations. If you desire more keystrokes for a particular key function, see Undefined Keystroke Processing below. Last Key Value -------------- On exit of any of the input functions, the global integer CWLlast_key contains the ascii code (scan code) of the key that was used to exit the input function. Default Cursor Types and Editing Mode ------------------------------------- By default, The C Window Library starts editing input in overstrike mode. This means that characters are overwritten when the cursor is placed on a character. The opposite of overstrike mode is insert mode, which pushes the characters to the right of the cursor over by one input position when a character is entered. Also, the default cursor type for overstrike mode is a block cursor, and the default cursor for insert mode is a thin cursor. You can change the startup mode, as well as the cursor types. The global variables CWLcursor_type and CWLcursor_mode store the values of the cursor shapes and the startup mode. The CWLcursor_type is an array of two integers. The OVERSTRIKEMODE constant is the position in the CWLcursor_type array of where the overstrike shape of the cursor is stored. The INSERTMODE constant is the position in CWLcursor_type of where the insert shape of the cursor is stored. Here is an example of how you would change the cursor types. Page 92 The C Window Library Page 92 #include "cwlwin.h" main() { WindowInitializeSystem(); /*...*/ /* Some code */ CWLcursor_type[OVERSTRIKEMODE] = CREATE_CURSOR_SHAPE(6,7); CWLcursor_type[INSERTMODE] = THIN; } The CREATE_CURSOR_SHAPE() macro creates a cursor shape by using the first argument as the starting scan line of the cursor, and the second argument as the ending scan line. Refer to VIDEO MACROS section for more information on CREATE_CURSOR_SHAPE(). The THIN constant is a predefined constant that stands for a thin cursor. The other predefined constants for cursor shapes are BLOCK and INVISIBLE. To change the startup mode when an input function is called, you must change the CWLcursor_mode global variable. Here is how you would change the default mode: #include "cwlwin.h" main() { WindowInitializeSystem(); /*...*/ /* Some code */ CWLcursor_mode = OVERSTRIKEMODE; } Use the constants OVERSTRIKEMODE and INSERTMODE for the desired mode. Editing using a character mask ------------------------------ The C Window Library also provides input functions that use character masks. For example to enter a date, you might want the user to enter a date in MM-DD-YY format. Instead of the user having to enter the hyphens, it would be advantageous if the input field already had hyphens, and the cursor will advance or back up to the next input position, jumping over any hyphens encountered. You can accomplish this by using a character mask. The mask is a character string which is made up of displayable characters, and a special character used to denote an input position. For example, a date mask would look like this: Page 93 The C Window Library Page 93 __-__-__ The hyphens are displayed in the window, but the underscores are not displayed. The underscores are used as a place holder, i.e. a place where input is expected. By default, the input position character is an underscore, but you can change this. Another example would be a social security mask: ___-__-____ a telephone mask: (___) ___-____ ext: ____ another date mask: __/__/__ If a character is deleted or inserted, the input manager is smart enough to move characters so that they do not clobber the characters that are not part of the input field. Editing Functions ----------------- The following are functions that can be used to edit input with The C Window Library. WindowGetString() ----------------- The WindowGetString() function gets a string from a window starting at a certain row and column of the window. Here is the prototype: int WindowGetString(WPOINTER w, int row, int col, char *buffer, int fillchar, int minchars, int maxwidth, int options, int startpos, char *regexp) The first argument is the window pointer. The second and third arguments are the row and column of where the input begins. The fourth argument is a pointer to a character buffer where the input characters will be stored. Whatever null terminated string is stored in the character buffer prior to calling WindowGetString() will be used as a default string. For example: strcpy(str,"ABC"); WindowGetString(w,2,1,str,' ',3,3,0,0,"3[A-Z]"); Page 94 The C Window Library Page 94 The default value of "ABC" will be displayed in the window when WindowGetString() is called. Therefore, make sure that your string buffer has a 0 in the 0th position if you want to make sure your input is empty when WindowGetString() is called. When inputting information, hitting the Escape key (or whatever the current key definition is for CWLedit_key[7]) will abort input and will return the original default string. The fifth argument is the fill character. This character is used to fill any unfilled input positions on the window. Instead of having spaces for unfilled positions, you can have any character. Try ASCII 177 or the underline character. You may like the effect. The sixth argument is the minimum number of characters to accept. If the number of characters entered is less than minchars, the input manager will not accept the input. However, you can change this by allowing the input manager to call a user defined routine when it detects that the minimum number of characters was not satisfied. More information on this later in this section. The seventh argument is the maximum width of the displayable input field. This argument allows for scrollable input fields. If the maximum width of the displayable field is less than the total number of characters in the input field, the field will scroll right and left depending on the input position. If the input cursor exceeds the right edge of the displayable field, the input is scrolled right until the next input position is visible. If the cursor is moved beyond the left edge of the displayable field, the input is scrolled left until the previous input position comes into view. Scrolling input fields allow for large input fields in small windows. The eighth argument is an integer representing the various options available for the input field. The various options available will be discussed later on. The ninth argument is the starting position in the input string of where the cursor will be placed. Position numbers start from 0 to the maximum number of input positions less one. For most applications, the starting position is usually 0. If the starting position is not within bounds of the input string, the starting position is assumed to be 0. The last argument is the regular expression to use for the input. Make sure that the input buffer you provide is large enough to hold the maximum number of characters plus one more character for the terminating null character. Page 95 The C Window Library Page 95 More Examples: WindowGetString(w,2,1,str,' ',1,1,NO_OPTIONS,0,"[YyNn]"); This will accept one character but only if the character is 'Y','y','N', or 'n'. Another example is this: WindowGetString(w,2,1,str,' ',5,5,NO_OPTIONS,0,"5[0-9]"); This will allow the user to enter five digit characters. To accept all characters, use this: WindowGetString(w,2,1,str,' ',3,3,NO_OPTIONS,0,"."); Example Program: #include "cwlwin.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is NULL */ WindowWriteString(w,"Enter Your first name :",0,0); WindowGetString(w,2,0,buffer,' ',0,40,NO_OPTIONS,0,"40."); WindowWriteString(w,"You entered the following:",3,0); WindowWriteString(w,buffer,4,1); GET_KEY(); WindowWriteString(w,"Now Enter your last name:",6,1); /* Note that the last string is now used as a default */ WindowGetString(w,7,0,buffer,' ',0,40,NO_OPTIONS,0,"40."); WindowWriteString(w,"You entered the following:",8,0); WindowWriteString(w,buffer,9,0); } Page 96 The C Window Library Page 96 Return Values for WindowGetString(): Return Value Definition ┌────────────────┬─────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼─────────────────────────────┤ │BAD_WINDOW │Window does not exist. │ ├────────────────┼─────────────────────────────┤ │NO_HEAP_MEM │Not enough memory to allocate│ │ │for internal buffers. │ ├────────────────┼─────────────────────────────┤ │NO_INPUT_CHARS │Regular Expression indicates │ │ │no characters to accept. │ └────────────────┴─────────────────────────────┘ WindowGetStringAttr() --------------------- The WindowGetStringAttr() function is the same as the WindowGetString() function described above except that a video attribute is used for the input entered. Here is the prototype: int WindowGetStringAttr(WPOINTER w, int row, int col, char *buffer, int fillchar, int minchars, int maxwidth, int options, int startpos, int attr, char *regexp) Note that attr is the tenth argument. This is the video attribute to use when receiving input. Example Program: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is NULL */ WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter Your first name :",1,0); WindowGetStringAttr(w,2,0,buffer,' ',0,40,NO_OPTIONS,0, REVERSE,"40."); WindowWriteString(w,"You entered the following:",3,0); WindowWriteString(w,buffer,4,0); Page 97 The C Window Library Page 97 GET_KEY(); WindowWriteString(w,"Now Enter your last name:",6,0); /* Note that the last string is now used as a default */ WindowGetStringAttr(w,7,0,buffer,' ',0,40,NO_OPTIONS,0, REVERSE,"40."); WindowWriteString(w,"You entered the following:",8,0); WindowWriteString(w,buffer,9,0); } The return values for WindowGetStringAttr() are the same as WindowGetString(). WindowGetMaskString() --------------------- The WindowGetMaskString() function is the same as the WindowGetString() except that a character mask is used when editing the input. Here is the prototype: int WindowGetMaskString(WPOINTER w, int row, int col, char *buffer, char *mask, int fillchar, int minchars, int maxwidth, int options, int startpos, char *regexp) The mask argument is an extra argument. This is the character mask to use when editing the input. The string returned in the buffer does not contain any characters that are used for the mask. For instance, if the mask is "__/__/__", and the string entered is "121589", WindowGetMaskString() will place "121589" into the buffer. If you want to create a string with the components separated according to a mask pattern, use the TranslateStringToMaskString() function described later in the manual. Default strings must be set up 'unmasked'. For instance, if you wanted the default date to be "12/15/89", and the character mask is "__/__/__", your string buffer should contain "121589" before calling WindowGetMaskString(). This same rule applies to any input functions that use a character mask. Example: #include "cwlwin.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define TELMASK "(___)___-____ ext:____" #define SSMASK "___-__-____" WPOINTER w; char buffer[80]; main() { Page 98 The C Window Library Page 98 int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter Your Telephone No.",0,0); WindowGetMaskString(w,2,1,buffer,TELMASK,' ',0,40, NO_OPTIONS,0,"40."); WindowWriteString(w,"You entered the following phone no:", 3,0); WindowWriteString(w,buffer,4,0); GET_KEY(); memset(buffer,0,sizeof(buffer)); WindowWriteString(w,"Now Enter your Soc. Sec. Number:", 6,0); WindowGetMaskString(w,7,0,buffer,SSMASK,' ',0,40, NO_OPTIONS,0,"40."); WindowWriteString(w,"You entered the following:",8,0); WindowWriteString(w,buffer,9,0); } Return Values for WindowGetMaskString(): Return Value Definition ┌────────────────┬─────────────────────────────┐ │NO_ERROR │No error occured. │ ├────────────────┼─────────────────────────────┤ │BAD_WINDOW │Window does not exist. │ ├────────────────┼─────────────────────────────┤ │NO_HEAP_MEM │Not enough memory to allocate│ │ │for internal buffers. │ ├────────────────┼─────────────────────────────┤ │NO_INPUT_CHARS │Regular Expression indicates │ │ │no characters to accept. │ └────────────────┴─────────────────────────────┘ WindowGetMaskStringAttr() ------------------------- The WindowGetMaskStringAttr() functions works the same way as WindowGetMaskString() except that WindowGetMaskStringAttr() allows you to specify a video attribute to use for the characters that are entered. Here is the prototype: int WindowGetMaskStringAttr(WPOINTER w, int row, int col, char *buffer, char *mask, int fillchar, int minchars, int maxwidth, int options, startpos, int attr, char *regexp) Page 99 The C Window Library Page 99 Example: #include "cwlwin.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) #define TELMASK "(___)___-____ ext:____" #define SSMASK "___-__-____" WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter Your Telephone No.",0,0); WindowGetMaskStringAttr(w,2,0,buffer,TELMASK,' ',0,40, NO_OPTIONS,0,REVERSE,"40."); WindowWriteString(w,"You entered the following phone no:", 3,0); WindowWriteString(w,buffer,4,0); GET_KEY(); memset(buffer,0,sizeof(buffer)); WindowWriteString(w,"Now Enter your Soc. Sec. Number:",6,0); WindowGetMaskStringAttr(w,7,1,buffer,SSMASK,' ',0,40, NO_OPTIONS,0,REVERSE,"40."); WindowWriteString(w,"You entered the following:",8,0); WindowWriteString(w,buffer,9,0); } The return values for WindowGetMaskStringAttr() are the same as WindowGetMaskString(). Getting Passwords ----------------- The C Window Library also allows you to receive hidden input. The functions to perform this are WindowGetPassword(), WindowGetMaskPassword(), WindowGetPasswordAttr() and WindowGetMaskPasswordAttr(). These functions are similar to the other WindowGetxx() functions. except that a character specified by you is displayed instead of the actual key pressed. Page 100 The C Window Library Page 100 WindowGetPassword() ------------------- The WindowGetPassword() function gets hidden input from a window. Here is the prototype: int WindowGetPassword(WPOINTER w, int row, int col, char *buffer, int fillchar, int passchar, int minchars, int maxwidth, int options, int startpos, char *regexp) The first argument is the window pointer. The second and third arguments are the (row,col) to start receiving input. The fourth argument is the buffer to store the inputted characters. The fifth argument is the character to use to fill empty input positions on the screen. The sixth argument is the character to display to the screen when a key is pressed. The last four arguments are the same as the WindowGetString()'s last four arguments. For example, if the user typed "ABCDEF", and the passchar is '*', the screen will display "******". Notice the asterisk is displayed instead of the actual characters inputted. Example Program: #include "cwlwin.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter A Password",0,0); WindowGetPassword(w,1,0,buffer,' ','*',0,40,NO_OPTIONS, 0,"40."); WindowWriteString(w,"You entered the following:",3,0); WindowWriteString(w,buffer,4,0); } The return values for WindowGetPassword() are the same as WindowGetMaskString(). Page 101 The C Window Library Page 101 WindowGetPasswordAttr() ----------------------- The WindowGetPasswordAttr() function is the same as WindowGetPassword() except that a video attribute is specified for the input characters. Here is the prototype: int WindowGetPasswordAttr(WPOINTER w, int row, int col, char *buffer, int fillchar, int passchar, int minchars, int maxwidth, int options, int startpos, int attr, char *regexp) Please note that the attribute argument is the next to last argument in the function. Example Program: #include "cwlwin.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter A Password",0,0); WindowGetPasswordAttr(w,2,0,buffer,' ','*',0,40, NO_OPTIONS,1,REVERSE,"40."); WindowWriteString(w,"You entered the following:",3,0); WindowWriteString(w,buffer,4,0); } The return values for WindowGetPasswordAttr() are the same as WindowGetMaskString(). WindowGetMaskPassword() ----------------------- The WindowGetMaskPassword() function works just like WindowGetPassword() except that a character mask is supplied. Here is the prototype: Page 102 The C Window Library Page 102 int WindowGetMaskPassword(WPOINTER w, int row, int col, char *buffer, char *mask, int fillchar, int passchar, int minchars, int maxwidth, int options, int startpos, char *regexp) Example: #include "cwlwin.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define CREDITCARDMASK "____-____-____-____" WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter A Credit Card #",0,0); WindowGetMaskPassword(w,2,0,buffer,CREDITCARDMASK,' ','*', 0,40,NO_OPTIONS,0,"40."); WindowWriteString(w,"You entered the following:",3,0); WindowWriteString(w,buffer,4,0); } The return values for WindowGetMaskPassword() are the same as WindowGetMaskString(). WindowGetMaskPasswordAttr() --------------------------- The WindowGetMaskPasswordAttr() function works just like WindowGetMaskPassword() except that a video attribute is supplied. Here is the prototype: int WindowGetMaskPasswordAttr(WPOINTER w, int row, int col, char *buffer, char *mask, int fillchar, int passchar, int minchars, int maxwidth, int options, int startpos, int attr, char *regexp) Page 103 The C Window Library Page 103 Example: #include "cwlwin.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) #define CREDITCARDMASK "____-____-____-____" WPOINTER w; char buffer[80]; main() { int i,row,col; buffer[0] = 0; /* Make sure first character is null */ WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); buffer[0] = 0; /* Make sure first character is null */ WindowWriteString(w,"Enter A Credit Card #",0,0); WindowGetMaskPasswordAttr(w,1,0,buffer,CREDITCARDMASK,' ', '*',0,40, NO_OPTIONS,0,REVERSE, "40."); WindowWriteString(w,"You entered the following:",3,0); WindowWriteString(w,buffer,4,0); } The return values for WindowGetMaskPasswordAttr() are the same as WindowGetMaskString(). Undefined Keystroke Processing ------------------------------ Another powerful feature of the input functions is that you can call a function for keys that are not in the current key definitions. For instance, say you want the Enter key AND Control-R to mean accept the input. Since there is only room for one definition for accept input, you can write a function that checks for the Control-R key, and return a number to the input manager as to what action to take. The CWLundef_fkey_func and CWLundef_akey_func function pointers --------------------------------------------------------------- There are two global variables, CWLundef_fkey_func and CWLundef_akey_func. Both of these function pointers are defined in the file key.h. These two variables are pointers to functions that return an integer. By setting these functions to point to your own functions, you can process undefined keystrokes yourself and return to the input manager what action to take. Page 104 The C Window Library Page 104 The CWLundef_fkey_func is used to define keys that are not normal ASCII keys. For instance, Control key and Alt key combinations, the F-keys, PgDn and PgUp, etc. The CWLundef_akey_func is used to define normal ASCII keys (keys with ASCII values between 32 and 255, inclusive). Whenever an undefined key is encountered, the input manager will pass the string that has been currently entered, the current key pressed, the current position number of the character being processed, and a pointer to a new position to place the input cursor. The prototype for this function is as follows: int (*CWLundef_fkey_func)(char *str,int key, int pos,int *newposptr) The prototype to the CWLundef_akey_func is similar to the one above. The str is a pointer to a null-terminated string of characters that has been currently entered. For instance, if the string currently entered is ABC123 str will point to "ABC123". The second argument is the last key that was pressed. You should use the values defined in the header file "cwlwin.h" if you want to check for non-ascii keys. This will ensure that you are properly checking the keystroke desired. For instance, if you want to check if the key pressed was the Page Up key, use the constant PGUP defined in cwlwin.h. The third argument is an integer representing the position number of the current character that the cursor is on. The first character is at position number 0, the second character in the input field is 1, etc. If there is an input mask (as in WindowGetMaskString() and WindowGetMaskStringAttr()) the position number does not include any characters that are used to create the non-input positions. For instance: "__/__/__ " 01 23 45 The numbers under the mask are the position numbers for each character. The fourth argument is a pointer to an integer representing a new position to move the cursor. Use of this pointer will be explained later. Page 105 The C Window Library Page 105 Specifying when to call an undefined key function in a Regular Expression ------------------------------- An empty bracketed simple regular expression tells the input manager to call the undefined keystroke function. An example of this type of regular expression is as follows: Regular Expression Definition ┌────────────────┬─────────────────────────────┐ │[A-Z][] │The first input position must│ │ │be between 'A' and 'Z', and │ │ │the second position will │ │ │automatically call the user │ │ │defined undefined keystroke │ │ │function. │ ├────────────────┼─────────────────────────────┤ │20[] │All twenty input positions │ │ │will call the undefined │ │ │keystroke function. │ ├────────────────┼─────────────────────────────┤ │3[0-9]2[]2[A-Z] │The first three input │ │ │positions must be between '0'│ │ │and '9', the next two input │ │ │positions automatically call │ │ │the undefined keystroke │ │ │function, and the last two │ │ │positions must be between │ │ │'A' and 'Z'. │ └────────────────┴─────────────────────────────┘ If you use this form of a regular expression, you MUST have defined an undefined keystroke function. If you did not define one, you will more than likely get into an infinite loop. Using this form of regular expression combined with the return values (defined below) that can be returned to the input manager, you will virtually have total control of the way the input is handled. Return Values To The Input Manager ---------------------------------- When writing your function you must return an integer to the input manager. This integer will inform the input manager as to what action to take. Here are a list of the return values and what they inform the input manager: Page 106 The C Window Library Page 106 Return Action to Value Take ┌──────────────────┬─────────────────────────────────────┐ │DONT_PROCESS │ Do not Process keystroke and │ │ │ continue getting input. │ ├──────────────────┼─────────────────────────────────────┤ │MOVE_CURSOR_LEFT │ Move cursor left. │ ├──────────────────┼─────────────────────────────────────┤ │MOVE_CURSOR_RIGHT │ Move cursor right. │ ├──────────────────┼─────────────────────────────────────┤ │DELETE_AT_CURSOR │ Delete character at cursor. │ ├──────────────────┼─────────────────────────────────────┤ │TOGGLE_INSERT │ Toggle Insert/Overwrite mode. │ ├──────────────────┼─────────────────────────────────────┤ │DESTRUCT_BACKSPACE│ Destructive Backspace. │ ├──────────────────┼─────────────────────────────────────┤ │ACCEPT_INPUT │ Accept Input and return string. │ ├──────────────────┼─────────────────────────────────────┤ │ACCEPT_DEFAULT │ Accept default string and return. │ ├──────────────────┼─────────────────────────────────────┤ │ERASE_INPUT │ Erase Input and go to first │ │ │ character in input field. │ ├──────────────────┼─────────────────────────────────────┤ │GOTO_FIRST │ Go to first input character in │ │ │ field. │ ├──────────────────┼─────────────────────────────────────┤ │GOTO_LAST │ Move cursor to last input character │ │ │ in field. │ ├──────────────────┼─────────────────────────────────────┤ │MOVE_TO_CHARACTER │ Move cursor to input position │ │ │ specified in the *pos argument. │ ├──────────────────┼─────────────────────────────────────┤ │INSERT_CHARACTER │ Accept character as valid and insert│ │ │ it at the current cursor position. │ │ │ │ └──────────────────┴─────────────────────────────────────┘ The MOVE_TO_CHARACTER return value moves the input cursor to the position in the input string specified in the fourth argument of CWLundef_akey_func or CWLundef_fkey_func. If you recall, the fourth argument was a pointer to an integer. The INSERT_CHARACTER return value only applies to the function pointed to by CWLundef_akey_func. These user-defined functions can do anything, not just process keystrokes. For instance, if you want F1 to be a help key, where the help function is in a function called do_help() you must make sure that: a) the F1 key is undefined (not defined in the CWLedit_key array) b) the CWLundef_fkey_func function pointer points to your function c) return an integer to the input manager from your function. Page 107 The C Window Library Page 107 Here is a typical way that this would be set up: #include "cwlwin.h" /* ... Other #includes and #defines */ int do_help(); /* define help function */ main() { WindowInitializeSystem(); /* ...Some code */ CWLundef_fkey_func = do_help; WindowGetString(/* ... Parameters */); /* ... Other code */ } int do_help(char *str, int ch, int pos, int *newpos) { if (ch == F1) /* check for F1 */ { /* help function goes here */ return DONT_PROCESS; /* make sure input manager does not process this or any other undefined keystroke */ } else { *newpos = 3; /* move input cursor to the fourth input position */ return MOVE_TO_CHARACTER /* let input manager know we want to move the input cursor */ } } With this flexibility in the input functions, you can totally control how input is handled. Page 108 The C Window Library Page 108 Input Options ------------- In the previous examples, the available options were discussed briefly. These options provide further control of the input functions. Here is a list of the options that are available: Option Definition ┌────────────┬────────────────────────────────┐ │UPPERCASE │Translates and displays lower │ │ │case to upper case. │ ├────────────┼────────────────────────────────┤ │LOWERCASE │Translates and displays upper │ │ │case to lower case. │ ├────────────┼────────────────────────────────┤ │CHECKSPACES │Spaces are counted when │ │ │determining whether the minimum │ │ │number of characters are │ │ │entered. │ ├────────────┼────────────────────────────────┤ │ENHANCEDKEY │Use the enhanced keyboard keys │ │ │and distinguish between keypad │ │ │keys and separate cursor pad │ │ │keys. Also detect F11 and F12 │ │ │keys. │ ├────────────┼────────────────────────────────┤ │CHECKREGEXP │Check to see if all characters │ │ │entered agree with the regular │ │ │expression provided. │ ├────────────┼────────────────────────────────┤ │AUTORETURN │Automatically accept the input │ │ │when a character in the last │ │ │input position is entered. │ ├────────────┼────────────────────────────────┤ │HOMECURSOR │Move scrolled input back to the │ │ │first character in the input │ │ │string when input is accepted. │ ├────────────┼────────────────────────────────┤ │CLEARFIELD │Clears the input field if the │ │ │first key pressed is recognized │ │ │by the regular expression as a │ │ │valid input key. If a cursor │ │ │movement key is pressed first, │ │ │the field is not cleared if any │ │ │subsequent input keys are │ │ │pressed. │ ├────────────┼────────────────────────────────┤ │USEMOUSE │Utilize the mouse to move the │ │ │cursor in the input field. │ ├────────────┼────────────────────────────────┤ │NO_OPTIONS │No options desired. │ └────────────┴────────────────────────────────┘ Page 109 The C Window Library Page 109 UPPERCASE --------- The UPPERCASE option converts and displays all lower case letters to upper case while the user is inputting characters. LOWERCASE --------- The LOWERCASE option converts and displays all upper case letters to lower case while the user is inputting characters. CHECKSPACES ----------- The CHECKSPACES option will cause the input manager to count any embedded spaces when determining whether the minimum number of characters are reached. Trailing spaces are counted only if the user explicitly put them there. ENHANCEDKEY ----------- The ENHANCEDKEY option will distinguish between the cursor keys on the keypad from the dedicated cursor keys on the enhanced keyboards as well as the Ins, Home, Del, PgUp and PgDn keys. Also the F11 and F12 keys will be detected. CHECKREGEXP and the CWLreg_exp_error_func function pointer ------------------------------------------------------- The CHECKREGEXP option will check to make sure that every character inputted is a valid character according to the regular expression. When inserting or deleting characters during input, characters may be moved left or right depending on whether the input is in insert or overwrite mode. When the characters are moved, the resulting pattern of characters may not match the regular expression desired. For instance, if the regular expression is "3[A-Z]2[0-9]", meaning 3 characters between A and Z followed by 2 characters between 0 and 9, and the current input entered is as follows : ABC34 If the cursor is currently under the 'C', the delete key is pressed, and the input is currently in insert mode, the '34' will be moved one character to the left. The resulting input would then look like this: AB34 As you can see, the input does not match the regular expression "3[A-Z]2[0-9]" because the '3' is in a position that should be occupied by a letter. When the CHECKREGEXP Page 110 The C Window Library Page 110 option is chosen, each position is checked when the user wants to accept the string, not while the user is entering characters. If the input is not OK, the input manager will not accept the string. You can override this by setting the CWLreg_exp_error_func function pointer. The global function pointer CWLreg_exp_error_func is prototyped as follows: int (*CWLreg_exp_error_func)(char *buf, int nomatch); where buf is the current string entered, and nomatch is the position of the first non-matching character that did not match the regular expression. The first character of the string is at position 0. Your function must return an integer back as to what to do. There are two valid return values, namely ACCEPT_INPUT and DONT_PROCESS. A return value of ACCEPT_INPUT will accept the input, even though all of the characters do not match the regular expression. DONT_PROCESS tells the input manager to keep getting input. Here is an example: int my_check_func(); main() { ... CWLreg_exp_error_func = my_check_func; WindowGetString(other parameters, CHECKREGEXP, "[A-Z][0-9]"); ... } int my_check_func(char *buf, int mistake_pos) { /* Assume w is initialized and open for writing */ WindowPrintf(w, "Illegal input for %s. Illegal character at position %d",buf, mistake_pos); GET_KEY(); WindowHide(w,NOEFFECT); return DONT_PROCESS; } The above example shows a function called my_check_func() which will be called when the input manager detects that all of the characters in the buffer buf do not match the regular expression. The function displays a message in a window and waits for a key to be pressed. Then the function returns DONT_PROCESS back to the input manager. Page 111 The C Window Library Page 111 AUTORETURN ---------- The AUTORETURN will automatically accept the input and return to the calling function if the cursor is on the last input position and the user types a valid character. Of course, if CHECKREGEXP is on, the input is checked for validity. HOMECURSOR ---------- The HOMECURSOR options will scroll an input field back to the first position when the input is accepted. CLEARFIELD ---------- The CLEARFIELD option will automatically clear the input field of any characters if the first key struck is a key recognized as a valid input key, and the character is displayed in the input position. If the first key struck is a cursor movement key or a delete character key (destructive backspace or delete character), any valid input key that is subsequently struck does not clear the field, but is recorded in the input field. USEMOUSE -------- This option can only be used if you have access to The C Window Library MouseLib functions, the system has a mouse installed, and the mouse has been activated. By positioning the mouse cursor to any valid input position in the input field and pressing the mouse button defined in the global integer variable field_button_press, the cursor is automatically moved to that input position. If the CLEARFIELD option is used in conjunction to USEMOUSE, any subsequent input will not clear the field if the mouse was used to move the cursor. NO_OPTIONS ---------- No field options desired. In other words, all of the options defined above are turned off. Page 112 The C Window Library Page 112 Examples of Input Options ------------------------- Examples: a) WindowGetString(w,0,0,str,' ',1,1,UPPERCASE,0,"[YyNn]"); b) WindowGetString(w,0,0,str,' ',1,1,LOWERCASE,0,"[YyNn]"); c) WindowGetStringAttr(w,1,0,str,' ', CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_),1, 1,UPPERCASE | AUTORETURN,0,"[YyNn]"); d) WindowGetString(w,0,0,str,' ',10,10, UPPERCASE | ENHANCEDKEY,1,"10."); e) WindowGetString(w,0,0,str,' ',20,10,CHECKREGEXP | HOMECURSOR,1,"10[A-Z]10[0-9]"); Example a) gets one character and will automatically set this character to upper case. b) same as a) except character is converted to lower case. c) converts one character to uppercase and automatically accepts the input because the input cursor was on the last input position. Note the use of the bitwise OR (|) to set multiple options. d) Converts the input to uppercase and treats extra keys on an enhanced keyboard as different than their "normal" keys. e) On accepting of the input field, the input is checked to see if every position on the input field is checked to see if it matches the regular expression. Once the input is accepted, the input is scrolled back to the first input position. The CWLchars_entered_func function pointer ------------------------------------------ If the number of characters entered is not enough to satisfy the minimum number of characters allowed, by default the input manager will not return until the required number of characters is entered. However, a global function pointer can be assigned to a user-written function that will be called when the input manager detects that the minimum number of characters was not reached. The function pointer CWLchars_entered_func is prototyped as follows: int (*CWLchars_entered_func)(char *buf, int minchars); Page 113 The C Window Library Page 113 where buf is the current string that is entered, and minchars is the minimum number of characters to expect. Your function must return an integer back as to what to do. There are two valid return values, namely ACCEPT_INPUT and DONT_PROCESS. A return value of ACCEPT_INPUT will accept the input, even though the minimum number of characters was not reached. DONT_PROCESS tells the input manager to keep getting input. Here is an example: int my_min_func(); main() { ... CWLchars_entered_func = my_min_func; ... } int my_min_func(char *buf, int m) { /* Assume w is initialized and open for writing */ WindowWriteString(w,"Not enough characters!",0,0); GET_KEY(); WindowHide(w,NOEFFECT); return DONT_PROCESS; } The above example shows a function called my_min_func() which will be called when the input manager detects that the number of characters in the buffer buf, does not meet the minimum requirements. The function displays a message in a window and waits for a key to be pressed. Then the function returns DONT_PROCESS back to the input manager. Other Input Related Functions ----------------------------- There are other input related functions that you can use to translate strings into their character mask equivalents and vice-versa. TranslateStringToMaskString() ----------------------------- This TranslateStringToMaskString() function takes a string and either places spaces, or the actual mask character between the characters in the string. A pointer to the translated string is returned. Here is the prototype: Page 114 The C Window Library Page 114 char *TranslateStringToMaskString(char *buffer, char *mask, char *buf2, int maskchar, int flag) The first argument is a pointer to the string to translate. The second argument is the mask string to use. The third argument is a pointer to the buffer that will store the translated string. The fourth argument is the mask character that is to be used. This character determines where the input positions are. The flag argument tells whether to include spaces between each component, or to use the character in the mask. You must make sure that buf2 is big enough to hold the translated string. The string length of the mask determines how far to translate the string. If the mask string is shorter than the string to translate, the string is truncated up to the last character in the mask. If the string to translate runs out of characters before the mask has been totally scanned, the extra characters in buf2 will either be spaces, or the characters in the mask (not the mask character specified in argument 4) will be copied over. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define DATEMASK "__/__/__" char buf1[] = "123456"; char buf2[9]; WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); TranslateStringToMaskString(buf1,DATEMASK,buf2,'_',0); WindowPrintf(w, "The original string is %s\nThe translated string is %s\n", buf1,buf2); TranslateStringToMaskString(buf1,DATEMASK,buf2,'_',1); WindowPrintf(w, "The original string is %s\nThe translated string is %s\n", buf1,buf2); } The example above takes the string "123456" with the mask of "__/__/__". The results of a translate with a flag of 0, and with a flag value of 1, is displayed in window w. Page 115 The C Window Library Page 115 The return value for TranslateStringToMaskString() is the pointer to the buffer that holds the translated string. This string is automatically null terminated. TranslateMaskStringToString() ----------------------------- This TranslateMaskStringToString() function does the opposite of TranslateStringToMaskString(). This function takes a string that has been translated with the TranslateStringToMaskString() or contains mask characters and returns the string without the extra characters. Here is the prototype: char *TranslateMaskStringToString(char *buffer, char *mask, char *buf2, int maskchar) The first argument is a pointer to the translated string. The second argument is the mask string to use. The third argument is a pointer to the buffer that will store the resulting string. The fourth argument is the mask character that is to be used. This character determines where the input positions are. You must make sure that buf2 is big enough to hold the new string. The translation stops when either the end of the buffer is reached, or the end of the mask string is reached. Example: #include "cwlwin.h" #include <string.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define DATEMASK "__/__/__" char buf1[] = "12/34/56"; char buf2[9]; WPOINTER w; main() { memset(buf2,0,sizeof(buf2)); WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); TranslateMaskStringToString(buf1,DATEMASK,buf2,'_'); WindowPrintf(w,"The original string is %s\n" "The untranslated string is %s\n", buf1,buf2); } Page 116 The C Window Library Page 116 The example above takes the string "12/34/56" with the mask of "__/__/__". The results of the translation is displayed in window w. The return value for TranslateMaskStringToString() is the pointer to the buffer that holds the translated string. This string is automatically null terminated. Page 117 The C Window Library Page 117 CHILD WINDOWS ------------- Child Windows are windows that are embedded in other windows. The window which the child is embedded is called the parent window. The child window is always visible within the parent window, and is positioned with coordinates relative to the parent. Child windows can also have child windows. A child window can only have one parent, but a parent window can have up to 255 children. What purpose would a child window serve? Let's say that you want to create a window that will hold a directory listing. You would like the layout of the window to be separated into two parts: a list of the names of the files, and a list of names of the directories and other available drives. It would be advantageous to embed two windows into the main window, one window for the file names, and the other for the directory and drive names. Here is an illustration of what the layout may look like: ╔════════════File Window═════════════╗ ║ ║ ║ ║ ║ File Names Directories ║ ║ ┌────────────┐ ┌───────────┐ ║ ║ │File 1 │ │<Dir 1> │ ║ ║ │File 2 │ │<Dir 2> │ ║ ║ │File 3 │ │.. │ ║ ║ │File 4 │ │. │ ║ ║ │File 5 │ │[a] │ ║ ║ │ │ │[b] │ ║ ║ │ │ │[c] │ ║ ║ └────────────┘ └───────────┘ ║ ║ ║ ║ ║ ╚════════════════════════════════════╝ There are three approaches to solving this problem. The first approach is to not use CWL and try to code this yourself. Let's throw out this 'solution'! The second approach is to create three top-level windows, the File Window, File Names window, and Directories window. The drawbacks in creating all three as top-level is that a) you have to position the File Names and Directories window inside of the File Window using desktop coordinates, and b) If you move or hide the File Window, the File Names and Directories window do not move or hide unless you explicitly call these functions yourself. The third and preferred method is to make File Names and Directories windows as child windows of the File Window. Whenever the File Window is hidden or moved, the File Names and Directories windows will automatically follow along and Page 118 The C Window Library Page 118 hide themselves or move. Also, the positioning of a child window is relative to the parent window, not the screen. This allows easier positioning of the child within the parent. Creating Child Windows with WindowSetParent() --------------------------------------------- There are two ways of creating a child window. The first method has already been discussed, namely using the WindowInitialize() function. You specify the new window's parent window as the first argument to WindowInitialize(). When a child window is created this way, the rank of the child window is always 1. The second method is to take a window that is not a child window or is a child window of another window, and to make it a child of the window desired. To do this, you would use the WindowSetParent() function. Here is the prototype: int WindowSetParent(WPOINTER parent, WPOINTER child, int rank, int row, int col) The parent argument is the WPOINTER of the parent window. The second argument is the WPOINTER of the window that you want to make a child of the parent. The rank argument is the window rank of the child. The row and col arguments denote the position of the child window within the parent window. If parent is DESKTOP_WINDOW, child is made into a top-level window. As was suggested above, you can take a window that is already a child of another window and reassign it to another parent. Example: #include "cwlwin.h" WPOINTER w, childw, childw2; main() { WindowInitializeSystem(); WindowInitDesktop(0); /* Create top-level window */ w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,10, NORM,NORM,DOUBLEBOX); /* Create a child window with parent window as w */ childw = WindowInitialize(w,BORDER,4,4,8,8,NORM,NORM,SINGLEBOX); Page 119 The C Window Library Page 119 /* Create another top-level window */ childw2 = WindowInitialize(DESKTOP_WINDOW,BORDER, 4,4,8,8,NORM,NORM,SINGLEBOX); /* Make childw2 a child of w by calling WindowSetParent() */ WindowSetParent(w,childw2,1,4,20); WindowDisplay(w,1,NOEFFECT); } Return Values for WindowSetParent(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Parent window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │MAX_WINDOW │ Maximum number of │ │ │ windows defined. │ ├────────────────┼────────────────────────┤ │NO_HEAP_MEM │ Not enough memory to │ │ │ allocate for window. │ └────────────────┴────────────────────────┘ Translation of Child Coordinates and the CWLPOINT structure ----------------------------------------------------------- As was stated above, the child windows are positioned relative to the parent window. CWL provides functions that allow you to translate from child window coordinates to any other window's coordinate system. For example, you may want to know what the desktop position of (1,1) of a child window is. This is very useful for positioning windows given that you only know the desktop, parent, or child window position. There are three functions that provide these translation functions: CWLClientToDesktop(), CWLDesktopToClient(), and CWLMapWindowPoints(). Before proceeding with definitions of these functions, the CWLPOINT structure must be explained. The CWLPOINT structure is a C structure that has the following definition: typedef struct tagCWLPOINT { int x; /* x - coordinate */ int y; /* y - coordinate */ } CWLPOINT; The CWLPOINT structure defines a point in a window. This structure is used extensively in the translation functions. The prototypes to the the translation functions are as follows: Page 120 The C Window Library Page 120 int CWLClientToDesktop(WPOINTER w, CWLPOINT *point) int CWLDesktopToClient(WPOINTER w, CWLPOINT *point) int CWLMapWindowPoints(WPOINTER w1, WPOINTER w2, CWLPOINT *point, int numpoints) The CWLClientToDesktop() function translates window coordinates to desktop (screen) coordinates. The first argument is the window from where the points are to be referenced, and the second argument is a pointer to a CWLPOINT structure variable. This structure must be filled in with the points to translate. When CWLClientToDesktop() returns, the CWLPOINT structure variable will be overwritten with the translated coordinates. The CWLDesktopToClient() function does the opposite of CWLClientToDesktop(). The CWLPOINT structure variable is translated from desktop coordinates to window coordinates on return. The CWLMapWindowPoints() function translates from one window's coordinate system to another window's coordinate system. It is actually a combination of CWLDesktopToClient() and CWLClientToDesktop() functions. The w1 arguement is the window where the coordinates are to be translated from. The w2 argument is the coordinate system that the points will be translated to. The point argument is an array of CWLPOINT structures, and the last argument is the number of CWLPOINT structures to translate. All of these functions do not skimp on the translation. If a point lies outside of the window's client area, the functions give a true indication of where the point lies. In some cases this may mean that the points translate to negative coordinates. Also, for CWLMapWindowPoints(), the two windows can be totally unrelated (no parent-child relationship) and will still return valid, translated points. Example: #include "cwlwin.h" WPOINTER w, childw; CWLPOINT point; main() { WindowInitializeSystem(); WindowInitDesktop(0); /* Create top-level window */ w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,20, NORM,NORM,DOUBLEBOX); Page 121 The C Window Library Page 121 /* Create a child window with parent window as w */ childw = WindowInitialize(w,BORDER,4,4,8,8,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); /* Translate (0,0) of childw to desktop coordinates */ point.x = 0; point.y = 0; CWLClientToDesktop(childw,&point); /* Write the results */ WindowMoveCursor(w,16,0); WindowPrintf(w, "(0,0) of childw is (%d,%d) of the desktop\n", point.y, point.x); /* Translate (7,12) of desktop to w's coordinates */ point.x = 12; point.y = 7; CWLDesktopToClient(w,&point); /* Write the results */ WindowPrintf(w, "(7,12) of desktop is (%d,%d) of w\n", point.y, point.x); /* Translate (0,0) of w to childw */ point.x = 0; poiny.y = 0; CWLMapWindowPoints(w,childw,&point,1); /* Write the results */ WindowPrintf(w, "(0,0) of w is (%d,%d) of childw\n", point.y, point.x); } Return Values for all translation functions: Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ Another method of translating coordinates is to use macros instead of the functions defined above. The macros are called DESKTOP_TO_CLIENT() and CLIENT_TO_DESKTOP(). The macros encapsulate creating a CWLPOINT variable, filling in the structure with numbers, calling the desired translation function, and getting the new values from the CWLPOINT variable and assigning them to other variables. These macros have the following prototype: Page 122 The C Window Library Page 122 DESKTOP_TO_CLIENT(WPOINTER w, int orow, int ocol, int nrow, int ncol) CLIENT_TO_DESKTOP(WPOINTER w, int orow, int ocol, int nrow, int ncol) The orow and ocol arguments are analogous to the y and x members of a CWLPOINT structure variable before you would call CWLDesktopToClient() or CWLClientToDesktop(). The nrow and ncol arguments will be filled in with the y and x members of the CWLPOINT structure variable on return of the translation function. These macros are useful in that a CWLPOINT structure variable is created inside of the macro, so you don't have to create one yourself. However you must remember that these are macros. The orow and ocol arguments can be any valid C expression, but the nrow and ncol arguments must be variable names or l-values. L-values are expressions that can be legally placed on the left side of an assignment statement (which is simply the equal sign). Enumerating Child Windows ------------------------- In some cases you may want to call a function that will act on all child windows and windows that are children of the child window. For example, you may want to move all of a parents descendant windows up by one row (A descendant window can be the child of a window, a child window's child, a child of a child of a child window, etc.). Another example, is that you just may want to count the number of child windows. Whatever you desire, CWL supports a function that enumerates and calls a user-defined function for all descendant windows of a parent. The WindowEnumChildren() function does this job. int WindowEnumChildren(WPOINTER root, CWLENUMPROC enumproc, long lParam) The first argument is the window where all descendants will be processed. The second argument is a pointer to a user-defined function defined as a CWLENUMPROC that will be called for all children. The last argument is a long parameter that can be used for any purpose that you desire. The user-defined function must have the following prototype: int enumproc(WPOINTER w, int lParam) The first argument is the child window being processed. The second argument is the lParam defined in the WindowEnumChildren(). If enumproc() returns 0, the enumeration stops. If enumproc() returns 1, the enumeration continues to the next window. This allows you to stop the enumeration whenever you want. Page 123 The C Window Library Page 123 The windows are processed in a depth-first search manner. In other words, if the first child window has children of its own, the child window, and then its children will be processed before going onto the next sibling. If child windows are created during the enumeration, these windows will not be processed. Also, if child windows are deleted during processing, they are not enumerated. If the first argument to WindowEnumChildren() is DESKTOP_WINDOW, all windows, including top-level windows will be enumerated. Example: #include "cwlwin.h" WPOINTER w, childw; int MyEnumProc(WPOINTER, long); main() { WindowInitializeSystem(); WindowInitDesktop(0); /* Create top-level window */ w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,40,20, NORM,NORM,DOUBLEBOX); /* Create a child window with parent window as w */ childw = WindowInitialize(w,BORDER,4,4,8,8,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); /* Call enumeration function */ WindowEnumChildren(w,MyEnumProc,0L); } /* Write a string to all descendant windows */ int MyEnumProc(WPOINTER w, long lParam) { WindowWriteString(w,"Window enumerated",0,0); return 1; /* Continue enumeration */ } Return Values for WindowEnumChildren(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ └────────────────┴────────────────────────┘ Page 124 The C Window Library Page 124 Testing Window Relationships ---------------------------- CWL allows testing for window relationships. These include parent to child, child to parent, testing if a window is a child window, and testing if two windows are related in any fashion. The functions that are to be used are WindowIsChild(), WindowIsDescendant(), WindowIsRelated(), WindowIsSibling(), WindowGetParent(), and WindowTestRelation(). Here is the prototype for these functions: int WindowIsChild(WPOINTER parent, WPOINTER child) int WindowIsDescendant(WPOINTER parent, WPOINTER desc) int WindowIsRelated(WPOINTER w1, WPOINTER w2) int WindowIsSibling(WPOINTER w1, WPOINTER w2) WPOINTER WindowGetParent(WPOINTER child) int WindowTestRelation(WPOINTER w1, WPOINTER w2) The WindowIsChild() function tests if the second argument (child)is a child of the first argument (parent). TRUE is returned if the relationship exists, FALSE otherwise. This function only will return TRUE if child is a direct child of the parent, not a descendant of the parent. For example if child has child windows, those 'grandchildren' are not children of parent. This function also returns FALSE if the window is a top-level window. The WindowIsDescendant() returns TRUE if desc is a descendant of parent. This includes child windows of parent and any children that any child may have. FALSE is returned if no relationship holds. WindowIsRelated() returns TRUE if w1 is related to w2 in any fashion, except if w1 and w2 are top-level windows or are descendants of two different top-level windows. TRUE is returned if both windows are related, FALSE otherwise. WindowIsSibling() returns TRUE if w2 and w1 are sibling windows, i.e. they have the same parent. FALSE is returned if this relationship does not exist. WindowGetParent() returns the WPOINTER of the parent window of child. If parent is a top-level window, the window pointer w is returned. If child does not exist, WIN_NULL_PTR is returned. WindowTestRelation() returns an integer denoting the type of relationship that two windows hold. Here are a list of the return values and their definitions: Page 125 The C Window Library Page 125 Constant Value Definition ┌──────────────────┬───┬───────────────────────────────────┐ │BAD_WINDOW │ │ One or both windows do not exist.│ ├──────────────────┼───┼───────────────────────────────────┤ │NO_RELATION │ 0 │ There is no relationship │ │ │ │ between the two windows. │ ├──────────────────┼───┼───────────────────────────────────┤ │PARENT_CHILD │ 1 │ w1 is a parent of w2. │ ├──────────────────┼───┼───────────────────────────────────┤ │CHILD_PARENT │ 2 │ w2 is a parent of w1. │ ├──────────────────┼───┼───────────────────────────────────┤ │PARENT_DESCENDANT │ 3 │ w2 is a descendant window of │ │ │ │ w1. │ ├──────────────────┼───┼───────────────────────────────────┤ │DESCENDANT_PARENT │ 4 │ w1 is a descendant window of │ │ │ │ w2. │ ├──────────────────┼───┼───────────────────────────────────┤ │SIBLING_WINDOWS │ 5 │ w1 and w2 are siblings. │ └──────────────────┴───┴───────────────────────────────────┘ Testing Window Ranks -------------------- One of the things that you may want to test is to see if when two windows share the same space, which window will have priority. In versions of CWL prior to this one (3.0), the test was as simple as comparing the ranks of both windows, and the window with the smaller rank number would get priority. However, with the introduction of child windows, this test is no longer safe to do. The reason is that windows have their own system of ranking windows that is independent of another window. For example, a child window with a rank of 1 does not necessarily have to lie on top of another child window with a rank of 100 if both child windows have different parents. The function to use to compare window ranks is the WindowCompareRank() function. This function compares two windows and returns an integer denoting which window really does have the priority if both windows shared the same screen space. Here is the prototype: int WindowCompareRank(WPOINTER w1, WPOINTER w2) w1 and w2 are the windows that you want to compare. If WindowCompareRank() returns -1, w1 will overlap w2. If the return value is 1, w2 will overlap w1. This function returns BAD_WINDOW if either w1 or w2 do not exist. Page 126 The C Window Library Page 126 VIRTUAL WINDOWS --------------- A virtual window can be thought of as a rectangular area filled with text. This rectangular region can be broken up into rows and columns, just as a normal window can be divided into rows and columns. The differences between a virtual window and a regular window is that a virtual window's dimensions can be larger than the physical screen, and a virtual window is not displayed on the screen. Then what good is it if you cannot display it? You use regular windows to display portions of the virtual window. If a regular window is used to view a virtual window, the regular window is called a viewport. With this method, you can use a viewport to display a virtual window, and then 'pan' around, viewing different sections of the virtual window. Text editors use this method to display files. Scrolling popup menus also use virtual windows. With The C Window Library, you can create virtual windows of any size, up to available user memory. Using Windows as Viewports -------------------------- If text is written to a virtual window, and there is a viewport that is displaying the portion of the virtual window that has changed, the viewport will show the change immediately. You do not have to "repaint" or "refresh" the viewport to show an updated change. That is handled internally in The C Window Library. However, there is an option that will "freeze" a viewport, i.e. will not update automatically, if there is a change in the virtual window. When the viewport is unfrozen, the changes to the virtual window are than displayed. Attributed and Non-Attributed Virtual Windows --------------------------------------------- There are two types of virtual windows. You can have either a virtual window with its own video attributes or a virtual window which gets its video attributes from the viewport that is displaying the virtual window. Virtual windows without attributes use half as much memory as a virtual window with attributes, but attributed virtual window's are more flexible. For instance, lets say you have highlighted some text in the virtual window. If the virtual window is not attributed, you must write the highlight attribute to the viewport window using one of the window functions Page 127 The C Window Library Page 127 (WindowWriteStringAttr() for example), since the virtual window does not have the capacity to store the video attribute. If you were to scroll the highlighted portion out of the viewport, you lose the highlight attribute, and must call the window function again to highlight the text, if the text is displayed again in the viewport. With an attributed virtual window, you write the attributes to the virtual window. Since the attributes are stored in the virtual window structure itself, the attributes are retained until you change them. From this point on, virtual windows without attributes are called NOATTRIBUTE virtual windows. Virtual windows with attributes will be called ATTRIBUTE virtual windows. Virtual Window's Logical Cursor ------------------------------- Each virtual window has its own logical cursor. This cursor is updated automatically when calling VirtualPrintf(), and VirtualWriteCharacter() functions, or can be updated manually by calling the VirtualMoveCursor() function. This cursor is independent of the screen cursor. Page 128 The C Window Library Page 128 CREATING VIRTUAL WINDOWS ------------------------ The section will discuss creating virtual windows using the VirtualInitialize() function. VirtualInitialize() ------------------- Virtual windows are created by calling the VirtualInitialize() function. Here is the prototype: VWPOINTER VirtualInitialize(int vwtype, unsigned nrows, unsigned ncols, int attr) The VirtualInitialize() function returns a pointer to a virtual window structure (a VWPOINTER). The first argument to VirtualInitialize() tells whether the virtual window will or will not have its own video attributes. If this argument is NOATTRIBUTE, the virtual window will not have attributes, otherwise if it is ATTRIBUTE, the virtual window will have its own attributes. The second argument is the number of rows of the virtual window. The third argument is the number of columns. The fourth argument is the attribute to use for the virtual window. This argument is ignored if the virtual window is NOATTRIBUTE. Example: #include "cwlwin.h" #include <stdio.h> #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw1, vw2; main() { WindowInitializeSystem(); /* set up a NOATTRIBUTE virtual window */ vw1 = VirtualInitialize(NOATTRIBUTE,/* virt. window type */ 30, /* Number of rows */ 80, /* Number of cols */ 0); /* Attribute */ /* set up an ATTRIBUTE virtual window */ vw2 = VirtualInitialize(ATTRIBUTE,/* virtual window type */ 30, /* Number of rows */ 100, /* Number of cols */ NORM); /* Attribute */ if (vw1 == (VWPOINTER)0 || vw2 == (VWPOINTER)0 ) /* Check if allocation worked */ printf( "Error in allocating virtual window." "The error number is %d"", CWLerror_code); } Page 129 The C Window Library Page 129 In the above program, the VirtualInitialize() function is called. This function allocates memory for the virtual window, and does other initializations. Once this function is called, you can write to and read characters from the virtual window. Notice that the first argument to VirtualInitialize() is either the constant NOATTRIBUTE or ATTRIBUTE. Also note that there is a check to see whether the virtual windows could be allocated. If there are no errors, VirtualInitialize() returns a valid VWPOINTER. If there are errors, VirtualInitialize() returns a null VWPOINTER and sets the global variable CWLerror_code to one of the following: NO_HEAP_MEM if there is not enough memory to allocate for the virtual window. Page 130 The C Window Library Page 130 ASSIGNING VIEWPORTS AND CLOSING VIEWPORTS ----------------------------------------- For a virtual window to have any useful purpose, it should be displayed on the screen. However the virtual window may be larger than the physical screen. The problem is solved by using normal windows to display parts of the virtual window. WindowAssignToVirtual() ----------------------- To turn a window into a viewport onto a virtual window, you use the WindowAssignToVirtual() function. Here is the prototype: int WindowAssignToVirtual(WPOINTER w, VWPOINTER vw, unsigned row, unsigned col) The first argument is the window that will be turned into a viewport. The second argument is the virtual window that w will be assigned to. The third and fourth arguments are the (row,col) of the virtual window. This position is where the upper left hand corner of the viewport's text area will be placed. To illustrate this, here is a sample call to WindowAssignToVirtual(): WindowAssignToVirtual(w,vw,5,10) The following description shows how this is to be interpreted: VIRTUAL WINDOW ┌───────────────────────────────────────────────────────────┐ │(0,0) (0,100)│ │ │ │ (5,10) of virtual window is equivalent to (0,0) of │ │ | the viewport. │ │ v │ │ ┌─────────────────────┐ │ │ │(0,0) of the viewport│ │ │ │ │ │ │ │ VIEWPORT WINDOW │ │ │ │(14,0) (14,30)│ │ │ └─────────────────────┘ │ │ │ │(100,0) (100,100)│ └───────────────────────────────────────────────────────────┘ The viewport relative position of (0,0) is located at (5,10) of the virtual window. Page 131 The C Window Library Page 131 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,20,12, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteString(vw,"This is a string",0,0); WindowAssignToVirtual(w,vw,0,0); /* Assign viewport to virtual window */ } The above program opens a virtual window, vw, and opens a normal window, w. In the above example, the VirtualWriteString() function is used to write strings to the virtual window. See the WRITING TEXT TO VIRTUAL WINDOWS section for more information on VirtualWriteString(). Once a window is turned into a viewport, nothing is stopping you from using the other window functions. You can still use WindowWriteString(), WindowMove(), WindowPrintf(), etc. Writing text to a viewport window via the normal window functions does not effect the virtual window in any way. Return Values for WindowAssignToVirtual(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ └────────────────┴────────────────────────┘ Out of bounds Coordinates ------------------------- The next question is "What do you do if the coordinates given in WindowAssignToVirtual() are out of bounds of the range of the virtual window?". For instance, if the virtual window Page 132 The C Window Library Page 132 has 100 rows, but the call to WindowAssignToVirtual() specifies row 97, and the viewport itself has a height of 10 rows. The window manager will fill the viewport with as much of the virtual window as possible, and will clear the contents of the viewport that are not inside the virtual window. Here is another view of what happens in this case: VIRTUAL WINDOW ┌─────────────────────────────────────────────────────────┐ │(0,0) (100,0)│ │ │ │ (97,10) of virtual window is same as (0,0) of │ │ | the viewport window. │ │ v │ │ ┌─────────────────────┐ │ │ │(0,0) of the viewport│ │ │ │ │ │ │(100,0) │ VIEWPORT WINDOW │ (100,100) │ └─────────┼─────────────────────┼─────────────────────────┘ │This portion of the │ │ window is cleared │ └─────────────────────┘ The above picture shows a viewport that is partially contained in the virtual window. The contents of the window above the last row of the virtual window is updated, while the portion of the viewport below the line is cleared. WindowCloseViewport() --------------------- To turn a viewport back to a normal window, WindowCloseViewport() is called. Here is the prototype: int WindowCloseViewport(WPOINTER w, int hide, int effect) where w is the viewport to be turned back into a regular window. When this function is called, the window w is cleared with its own video attribute. The second argument tells if the window is to be hidden. If hide is 1, the window is hidden. If it is 0, the window remains on the screen. The effect argument is a special effect to use when hiding the window. A list of special effects are defined in the DISPLAYING WINDOWS section. This function DOES NOT close the virtual window or does a WindowClose() to the viewport window. Page 133 The C Window Library Page 133 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,20,12,NORM, NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteString(vw,"This is a string",0,0); WindowAssignToVirtual(w,vw,0,0); GET_KEY(); WindowCloseViewport(w,1,NOEFFECT); GET_KEY(); } The example above opens a virtual windows and a normal. It then assigns the windows to the virtual window by calling WindowAssignToVirtual(). The program then unassigns the viewport by calling WindowCloseViewport(). Return Values for WindowCloseViewport(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ └────────────────┴────────────────────────┘ Page 134 The C Window Library Page 134 WRITING TEXT TO VIRTUAL WINDOWS ------------------------------- There are several functions that write strings to virtual windows. They are divided into two groups: functions that take null terminated strings as arguments, and functions that use character buffers and a length argument. When any of the text functions are called, any viewport that is displaying any portion of the virtual window that has been changed will display the update. Null Terminated String Functions -------------------------------- VirtualWriteString() -------------------- The VirtualWriteString() function writes a null terminated to a virtual window at a specific row and column of the virtual window. Here is the prototype: int VirtualWriteString(VWPOINTER vw, char *string, unsigned row, unsigned col) The first argument is the virtual window pointer. The second argument is the string to write. The third and fourth arguments are the row and column of the virtual window that the string is to be written to. If the string will exceed the boundaries of the virtual window, the string is truncated. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w1, w2; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,20,12, NORM,NORM,SINGLEBOX); w2 = WindowInitialize(DESKTOP_WINDOW,BORDER,13,0,20,10, NORM,NORM,DOUBLEBOX); WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); VirtualWriteString(vw,"This is a string",0,0); WindowAssignToVirtual(w1,vw,0,0); WindowAssignToVirtual(w2,vw,0,10); } Page 135 The C Window Library Page 135 The example above writes the string "This is a string" to the virtual window at row 0, column 0. The windows w1 and w2 are viewports on the virtual window vw. The window w1 is located at (0,0) of the virtual window, while w2 is located at (0,10) of the virtual window. The window w1 will display "This is a string", but w2 will only display "string" since it is situated at column 10 of the virtual window. Return Values for VirtualWriteString(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row or Column is out │ │ │ of bounds. │ └────────────────┴────────────────────────┘ VirtualWriteStringAttr() ------------------------ The VirtualWriteStringAttr() works the same way as the VirtualWriteString() except that a video attribute is used. Here is the prototype: int VirtualWriteStringAttr(VWPOINTER vw, char *string, unsigned row, unsigned col, int attr) The last argument is the video attribute to use. If the virtual window is NOATTRIBUTE, the attribute is ignored, and only the string is written. Any viewports that are assigned to NOATTRIBUTE virtual windows will not reflect the change in the attribute. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,20,12, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringAttr(vw,"This is a string",0,0,REVERSE); Page 136 The C Window Library Page 136 WindowAssignToVirtual(w,vw,0,0); } The example above writes the string "This is a string" in the virtual window with a video attribute defined by the constant REVERSE. Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row or Column is out │ │ │ of bounds. │ ├────────────────┼────────────────────────┤ │NO_ATTRIB │ Virtual Window is │ │ │ NOATTRIBUTE. If this │ │ │ error occurs, only the │ │ │ string is written. │ └────────────────┴────────────────────────┘ VirtualWriteCenterString() -------------------------- The VirtualWriteCenterString() writes a centered string in a virtual window. Here is the prototype: int VirtualWriteCenterString(VWPOINTER vw, char *string, unsigned row) The row argument is the row to center the string on. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,50,12,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteCenterString(vw,"This is a string",0); WindowAssignToVirtual(w,vw,0,0); } Page 137 The C Window Library Page 137 The above example illustrates the use of VirtualWriteCenterString(). The viewport window w is just used as a guide to display what has happened. Return Values for VirtualWriteCenterString(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row is out of bounds. │ └────────────────┴────────────────────────┘ VirtualWriteCenterStringAttr() ------------------------------ The VirtualWriteCenterStringAttr() function works the same way as VirtualWriteCenterString() except that a video attribute is specified. Here is the prototype: int VirtualWriteCenterStringAttr(VWPOINTER vw, char *string, unsigned row, int attr) The attr argument is the video attribute to use. If the virtual window is NOATTRIBUTE, the attribute is ignored and only the string is written to the virtual window. #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,50,12,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteCenterStringAttr(vw,"This is a string",0, REVERSE); WindowAssignToVirtual(w,vw,0,0); } Page 138 The C Window Library Page 138 Return Values for VirtualWriteString(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row or Column is out │ │ │ of bounds. │ ├────────────────┼────────────────────────┤ │NO_ATTRIB │The virtual window is │ │ │NOATTRIBUTE. If this │ │ │error occurs, only the │ │ │string is written. │ └────────────────┴────────────────────────┘ VirtualWriteStringCC() ---------------------- The VirtualWriteStringCC() function centers and writes a string around a column of the virtual window (the CC stands for Centered Column). If the string is longer than the width of the virtual window, the string is placed on column 1 is clipped at the right edge of the virtual window. Here is the prototype: int VirtualWriteStringCC(VWPOINTER vw, char *string, unsigned row, unsigned col) The first argument is the window. The second argument is the string. The third argument is the row to write the string, and the last argument is the column to center the string on. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,50,12,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringCC(vw,"This",0,10); VirtualWriteStringCC(vw,"is",1,10); VirtualWriteStringCC(vw,"centered",2,10); VirtualWriteStringCC(vw,"around",3,10); VirtualWriteStringCC(vw,"column",4,10); VirtualWriteStringCC(vw,"10",5,10); WindowAssignToVirtual(w,vw,0,0); } Page 139 The C Window Library Page 139 The example above writes the text centered around column 10 of the virtual window w. The return values for VirtualWriteStringCC() are the same as VirtualWriteString(). VirtualWriteStringCCAttr() -------------------------- The VirtualWriteStringCCAttr() works the same way as the VirtualWriteStringCC() function except that a video attribute is specified. Here is the prototype: int VirtualWriteStringCCAttr(VWPOINTER vw, char *string, unsigned row, unsigned col, int attr) The attribute to use is the last argument. If the virtual window is NOATTRIBUTE, the attr argument is ignored, and only the string is written to the virtual window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,50,12,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringCCAttr(vw,"This",0,10,REVERSE); VirtualWriteStringCCAttr(vw,"is",1,10,REVERSE); VirtualWriteStringCCAttr(vw,"centered",2,10,REVERSE); VirtualWriteStringCCAttr(vw,"around",3,10,REVERSE); VirtualWriteStringCCAttr(vw,"column",4,10,REVERSE); VirtualWriteStringCCAttr(vw,"10",5,10,REVERSE); WindowAssignToVirtual(w,vw,0,0); } The return values for VirtualWriteStringCCAttr() are the same as VirtualWriteStringAttr(). Page 140 The C Window Library Page 140 VirtualWriteStringRJ() ---------------------- The VirtualWriteStringRJ() function writes a right justified string in a virtual window. Here is the prototype: int VirtualWriteStringRJ(WPOINTER w, char *string, unsigned row, unsigned col) The first argument is the virtual window. The second argument is the string. The third argument is the row to write the string, and the last argument is the column to place the right edge of the string. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,50,12, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringRJ(vw,"This",0,10); VirtualWriteStringRJ(vw,"is",1,10); VirtualWriteStringRJ(vw,"right",2,10); VirtualWriteStringRJ(vw,"justified",3,10); VirtualWriteStringRJ(vw,"on ",4,10); VirtualWriteStringRJ(vw,"column",5,10); VirtualWriteStringRJ(vw,"10",6,10); WindowAssignToVirtual(w,vw,0,0); } The example above writes the text right justified on column 10 of the virtual window. The return values for VirtualWriteStringRJ() are the same as VirtualWriteString(). VirtualWriteStringRJAttr() -------------------------- The VirtualWriteStringRJAttr() writes a right justified string in a virtual window, and allows you to specify a video attribute. Here is the prototype: Page 141 The C Window Library Page 141 int VirtualWriteStringRJAttr(WPOINTER w, char *string, unsigned row, unsigned col, int attr) The last argument is the attribute to use. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) VWPOINTER vw; /* virtual window pointers */ WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,50,12,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); VirtualWriteStringRJAttr(vw,"This",0,10,REVERSE); VirtualWriteStringRJAttr(vw,"is",1,10,REVERSE); VirtualWriteStringRJAttr(vw,"right",2,10,REVERSE); VirtualWriteStringRJAttr(vw,"justified",3,10,REVERSE); VirtualWriteStringRJAttr(vw,"on ",4,10,REVERSE); VirtualWriteStringRJAttr(vw,"column",5,10,REVERSE); VirtualWriteStringRJAttr(vw,"10",6,10,REVERSE); WindowAssignToVirtual(w,vw,0,0); } The example above writes the text right justified on column 10 of the virtual window. If the virtual window is NOATTRIBUTE, only the string is written. The return values for VirtualWriteStringRJAttr() are the same as VirtualWriteStringAttr(). Length Controlled Functions --------------------------- VirtualWriteCharacters() ------------------------ The VirtualWriteCharacters() writes a specified number of characters from a buffer to the virtual window. Here is the prototype: int VirtualWriteCharacters(VWPOINTER vw, char *buffer, unsigned row, unsigned col, unsigned length) Page 142 The C Window Library Page 142 The first argument is the virtual window. The second argument is the buffer where the characters are stored. The third and fourth arguments are the (row,col) of where the characters will be placed in the virtual window. The last argument is the number of characters from buffer that will be written. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; VWPOINTER vw; char buf[] = "Hello World!!"; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); VirtualWriteCharacters(vw,buf,0,0,11); VirtualWriteCharacters(vw,buf,1,0,13); WindowAssignToVirtual(w,vw,0,0); } The return values for VirtualWriteCharacters() are the same as VirtualWriteString(). VirtualWriteAttributes() ------------------------ The VirtualWriteAttributes() writes a specified number of attributes from a buffer to the virtual window. Here is the prototype: int VirtualWriteAttributes(VWPOINTER vw, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer where the attributes are stored. The third and fourth arguments are the (row,col) of where the attributes will be placed in the virtual window. The last argument is the number of attributes from buffer that will be written. If the window is NOATTRIBUTE, this function does nothing. Page 143 The C Window Library Page 143 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; VWPOINTER vw; char buf[13]; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); for (i=0;i<13;i++) if (i % 2) buf[i] = NORM; else buf[i] = REVERSE; w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); VirtualWriteString(vw,"Hello World!!",0,0); VirtualWriteAttributes(vw,buf,0,0,13); WindowAssignToVirtual(w,vw,0,0); } The return values for VirtualWriteAttributes() are the same as VirtualWriteStringAttr(). VirtualWriteCharAndAttr() ------------------------- The VirtualWriteCharAndAttr() function writes a string of character/attribute pairs to a virtual window. Use this function if you have created a string of character/attribute pairs, and want to output them easily. The string consists of character and attributes in the following manner: char-attr-char-attr... Each character is followed by its corresponding video attribute. Here is the prototype: int VirtualWriteCharAndAttr(VWPOINTER vw, char *buffer, unsigned row, unsigned col, unsigned length) Page 144 The C Window Library Page 144 The first argument is the virtual window. The second is the buffer where the character and attributes are stored. The third and fourth is the (row,col) position in the virtual window to write, and the length argument is the number of character/attribute pairs from the buffer to write. Please note the difference in the meaning of the length argument in this function as opposed to its use in the preceding functions. If the virtual window is NOATTRIBUTE, nothing is written to the virtual window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; VWPOINTER vw; char buf[26]; char *str = "Hello World!!"; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); for (i=0;i<26;i+=2,str++) { buf[i] = *str; buf[i+1] = NORM; } VirtualWriteCharAndAttr(vw,buf,0,0,13); WindowAssignToVirtual(w,vw,0,0); } The return values for VirtualWriteCharAndAttr() are the same as VirtualWriteStringAttr(). VirtualWriteRepeatAttribute() ----------------------------- The VirtualWriteRepeatAttribute() function writes an attribute a specified number of times to a virtual window. Here is a prototype: int VirtualWriteRepeatAttribute(VWPOINTER vw, int attr, unsigned row, unsigned col, int count) Page 145 The C Window Library Page 145 The attr argument is the attribute to use. The count argument specifies the number of times to write the attribute attr to the virtual window starting at (row,col). If the virtual window is NOATTRIBUTE, this function returns an error. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; VWPOINTER vw; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); VirtualWriteString(vw,"Hello World!!",0,0); VirtualWriteRepeatAttribute(vw,REVERSE,0,0,13); WindowAssignToVirtual(w,vw,0,0); } The example above illustrates that the VirtualWriteRepeatAttribute() writes the REVERSE attribute 13 times starting at row 0, column 0 of the virtual window w. The return values for VirtualWriteRepeatAttribute() are the same as VirtualWriteStringAttr(). VirtualWriteRepeatCharacter() ----------------------------- The VirtualWriteRepeatCharacter() function writes a character a specified number of times to a virtual window. Here is a prototype: int VirtualWriteRepeatCharacter(WPOINTER w, int ch, int row, int col, int count) The count argument is the character to use. The count argument specifies the number of times to write the character ch to the virtual window starting at (row,col). Page 146 The C Window Library Page 146 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,20,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); WindowDisplay(w,1,NOEFFECT); VirtualWriteRepeatCharacter(vw,'a',0,0,5); VirtualWriteRepeatCharacter(vw,'b',1,0,5); VirtualWriteRepeatCharacter(vw,'c',2,0,5); WindowAssignToVirtual(w,vw,0,0); } The example above illustrates that the VirtualWriteRepeatCharacter() writes the letter 'a', 'b', and 'c' 5 times on rows 0, 1, and 2 respectively. The return values for VirtualWriteRepeatCharacter() are the same as VirtualWriteString(). Formatted Write Functions ------------------------- Format String ------------- These functions write formatted output to virtual windows just like the printf() function. There are two functions that do this, namely VirtualPrintf() and VirtualPrintfAttr(). These functions use a format string that is similar to the format string found in printf(). For example, %d, %s, %lf, etc. and most of the escape sequences are supported. The list of escape sequences supported are as follows: \n - newline \t - tab \r - carriage return \x - hexadecimal Page 147 The C Window Library Page 147 Where Output is Placed ---------------------- The row and column of where the string will be written is determined by the virtual window's logical cursor. The logical cursor is advanced by both of these functions to one column position after the last character is printed. If you want to start at a particular row and column of the window, you must move the cursor yourself by calling the VirtualMoveCursor() function. This function is explained in the MOVING THE LOGICAL CURSOR section. When the virtual window is first initialized using VirtualInitialize(), the logical cursor is automatically moved to (0,0) of the virtual window. VirtualSetWrap() ---------------- With these functions, any text that will exceed the boundaries of the window will be wrapped to the next line. If the output will exceed the last row of the window, the window is automatically scrolled up by one line. This is the default action to take when characters exceed the right edge of the virtual window. If you want the output clipped instead of wrapped, you must set the virtual window's wrap flag using the VirtualSetWrap() function. The VirtualSetWrap() function sets the virtual window's wrap flag to either on or off. Here is the prototype: int VirtualSetWrap(VWPOINTER vw, int option) The second argument will be 0 if you want to turn the wrap flag off, or 1 if you want to turn it on. If the wrap flag is off, the output generated by VirtualPrintf() and VirtualPrintfAttr() will be terminated when the right edge of the window is reached. If the wrap flag is on, the output is wrapped to the next line when the right edge is reached. Unlike regular windows, the output is not scrolled if the last line of the virtual window is reached. You can set the wrap flag to a virtual window at any time. Page 148 The C Window Library Page 148 VirtualPrintf() --------------- The VirtualPrintf() function writes formatted output to the virtual window. Here is the prototype: int VirtualPrintf(VWPOINTER vw, char *format [,arg1,...]) The first argument is the virtual window. The second argument is a format string. The rest of the arguments are optional arguments that are written to the virtual window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; VWPOINTER vw; int i = 3; double j = 5.6; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,0,0); VirtualPrintf(vw,"3+2 is equal to %d\n",3+2); GET_KEY(); VirtualPrintf(vw,"i is equal to %d\nj is equal to %lf\n", i,j); } The above example illustrates how VirtualPrintf() is used to print formatted strings to a virtual window. The return values for VirtualPrintf() are the same as VirtualWriteString(). VirtualPrintfAttr() ------------------- The VirtualPrintfAttr() function writes formatted output to the virtual window. The difference between VirtualPrintf() and VirtualPrintfAttr() is that VirtualPrintfAttr() uses a video attribute specified as an argument. Here is the prototype: int VirtualPrintfAttr(VWPOINTER vw, int attr, char *format [,arg1,...]) Page 149 The C Window Library Page 149 The first argument is the virtual window. The second argument is the video attribute to use. The third argument is the format string. The rest of the arguments are optional arguments that are written to the virtual window. If the virtual window is NOATTRIBUTE, only the string is written to the window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; VWPOINTER vw; int i = 3; double j = 5.6; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,0,0); VirtualPrintfAttr(vw,REVERSE,"3+2 is equal to %d\n",3+2); GET_KEY(); VirtualPrintfAttr(vw,REVERSE, "i is equal to %d\nj is equal to %lf\n",i,j); } The above example illustrates how VirtualPrintfAttr() is used to print formatted strings. The return values for VirtualPrintfAttr() are the same as VirtualWriteStringAttr(). Page 150 The C Window Library Page 150 READING CHARACTERS AND ATTRIBUTES FROM VIRTUAL WINDOWS ------------------------------------------------------ With The C Window Library, you can read the contents of a virtual window into a character buffer. These functions provide the programmer with the contents of the virtual window at any time. The functions to perform this are VirtualReadAttributes(), VirtualReadCharacters() and VirtualReadCharAndAttr(). VirtualReadCharacters() ----------------------- The VirtualReadCharacters() function reads the characters from a virtual window into a buffer. Here is the prototype. int VirtualReadCharacters(VWPOINTER vw, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer to store the characters in. The third and fourth arguments are the (row,col) position in the virtual window to start reading from. The last argument is the number of characters to read. You must make sure that buffer has enough room to hold all of the characters read in. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; char buf[14] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(NOATTRIBUTE,10,80,NORM); VirtualWriteString(vw,"Hello World!!",0,0); VirtualReadCharacters(vw,buf,0,0,13); } The example above illustrates the use of VirtualReadCharacters(), which reads the virtual window's contents starting at (0,0). This happens to be the string "Hello World!!". Page 151 The C Window Library Page 151 If the length exceeds the right edge of the virtual window, VirtualReadCharacters() will read up to the right edge of the virtual window. Return Values for VirtualReadCharacters(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row or Column is out │ │ │ of bounds. │ └────────────────┴────────────────────────┘ VirtualReadAttributes() ---------------------- The VirtualReadAttributes() function reads the attributes from a virtual window into a buffer. Here is the prototype. int VirtualReadAttributes(VWPOINTER w, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer to store the attributes in. The third and fourth arguments are the (row,col) position in the virtual window to start reading from. The last argument is the number of attributes to read. If the virtual window is NOATTRIBUTE, nothing is read. You must make sure that buffer has enough room to hold all of the attributes read in. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; char buf[14] = {0}; /* Null all elements of buf */ main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(ATTRIBUTE,10,80,NORM); VirtualReadAttributes(vw,buf,0,0,13); /* Read attributes */ } Page 152 The C Window Library Page 152 The example above illustrates the use of VirtualReadAttributes(), which reads the virtual window's attribute contents starting at (0,0) of the virtual window. If the length exceeds the right edge of the virtual window, VirtualReadAttributes() will read up to the right edge of the virtual window. Return Values for VirtualReadAttributes(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row or Column is out │ │ │ of bounds. │ ├────────────────┼────────────────────────┤ │NO_ATTRIB │ The virtual window is │ │ │ NOATTRIBUTE. │ └────────────────┴────────────────────────┘ VirtualReadCharAndAttr() ------------------------ The VirtualReadCharAndAttr() function reads character/attribute pairs from a virtual window into a buffer. Here is the prototype. int VirtualReadCharAndAttr(VWPOINTER w, char *buffer, unsigned row, unsigned col, unsigned length) The first argument is the virtual window. The second argument is the buffer to store the character/attribute pairs in. The third and fourth arguments are the (row,col) position in the virtual window to start reading from. The last argument is the number of character/attribute pairs to read. If the window is NOATTRIBUTE, nothing is read. You must make sure that buffer has enough room to hold all of the character/attribute pairs read in. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; char buf[27] = {0}; /* Null all elements of buf */ Page 153 The C Window Library Page 153 main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(ATTRIBUTE,10,80,NORM); VirtualWriteString(vw,"Hello World!!",0,0); VirtualReadCharAndAttr(vw,buf,0,0,13); } The example above illustrates the use of VirtualReadCharAndAttr(), which reads the virtual window's character/attribute contents starting at (0,0) of the virtual window. This happens to be the characters/attributes of the string "Hello World!!". If the length exceeds the right edge of the virtual window, VirtualReadCharAndAttr() will read up to the right edge of the virtual window. Return Values for VirtualReadCharAndAttr(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row or Column is out │ │ │ of bounds. │ ├────────────────┼────────────────────────┤ │NO_ATTRIB │ The virtual window is │ │ │ NOATTRIBUTE. │ └────────────────┴────────────────────────┘ Page 154 The C Window Library Page 154 REPOSITIONING THE VIEWPORT -------------------------- A viewport can be repositioned anywhere on the virtual window. This allows to view different parts of the virtual window. WindowPositionViewport() ------------------------ The WindowPositionViewport() function positions the viewport to a new location on the virtual window it is associated with. Here is the prototype: int WindowPositionViewport(WPOINTER w, unsigned row, unsigned col) The first argument is the viewport window. The second argument and third arguments are is the (row,col) position of the virtual window associated with w. This position will be where the upper left hand corner of the viewport's text area will be placed. Example: #include <stdio.h> #include <string.h> #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define FILENAMECHARS \ "25[A-Za-z0-9!@#$%/^&()+=_/-{}/[/]`~/.\\:]" VWPOINTER vw; /* virtual window pointer */ WPOINTER w; /* Window pointer */ char filename[26]; FILE *infile; /* input file handle */ main() { unsigned int i,j,row,col; WindowInitializeSystem(); WindowInitDesktop(0); /* set up a Type 0 virtual window */ vw = VirtualInitialize(NOATTRIBUTE,200,80,0); /* set up viewport window */ w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,78, 12,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); Page 155 The C Window Library Page 155 /* read a file name */ read_file(); /* display file in viewport */ WindowAssignToVirtual(w,vw,0,0); row = col = 1; CWLflush_kbd = TRUE; /* Set keyboard flush to TRUE */ while (1) { switch (GET_KEY()) /* Keep getting keys until ESCAPE key is hit */ { case UARROW: /* Move viewport up 1 line */ if (row > 0) WindowPositionViewport(w,--row,col); break; case DARROW: /* Move viewport down 1 line */ if (row < 188) WindowPositionViewport(w,++row,col); break; case LARROW: /* Move viewport left 1 line */ if (col > 0) WindowPositionViewport(w,row,--col); break; case RARROW: /* Move viewport right 1 line */ if (col < 68) WindowPositionViewport(w,row,++col); break; case ESC: /* End program */ close_all(); break; } } } read_file() /* Gets a filename and displays it in the window */ { int ch; unsigned r = 0, c = 0; filename[0] = 0; WindowWriteString(w,"Please enter a file name: ",0,0); WindowGetString(w,0,26,filename,'_',0,40,0,0,FILENAMECHARS); if ((infile = fopen(filename,"r")) == NULL) { WindowMoveCursor(w,2,0); WindowPrintf(w,"File name %s does not exist\n" "Press a key to continue", filename); GET_KEY(); close_all(); } else Page 156 The C Window Library Page 156 while(1) /* Read characters into virtual window */ { ch = fgetc(infile); if (feof(infile)) break; if (ch != '\n') VirtualWriteRepeatCharacter(vw,ch,r,c++,1); else { r++; c=0; } } fclose(infile); } close_all() { WindowClose(w,NOEFFECT); exit(0); } The above example reads in a text file and uses WindowPositionViewport() to move left, right, up, or down. There is no checking to see if you have scrolled past the end of the file. The read_file() function reads a file and copies each character in the file to the virtual window called vw. In the main program, the global variable CWLflush_kbd, defined in the IMPORTANT GLOBAL VARIABLES section, is set to TRUE. When flush_keyboard is TRUE, the keyboard buffer is flushed before any incoming keystrokes are accepted. Otherwise the keyboard buffer is not flushed. In the while(1) loop of the main program, the constants UARROW, DARROW, LARROW, and RARROW, stands for the up, down, left, and the right arrow keys on the keypad, respectively. The constants UARROW, DARROW, LARROW, and RARROW are defined in cwlwin.h. Depending on the key that is hit, the viewport is repositioned to point to a new row or column. The call to WindowPositionViewport() has three arguments. The first is the pointer to the viewport window, the second and the third are the row and the column of the virtual window to place the upper left hand corner of the viewport. There is minimal bounds checking in the above example, however you can enhance it by putting in more bounds checking and by implementing a page down, or page up function. Page 157 The C Window Library Page 157 Return Values for WindowPositionViewport(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row or Column is out │ │ │ of bounds. │ └────────────────┴────────────────────────┘ Page 158 The C Window Library Page 158 SCROLLING THE VIEWPORTS ----------------------- Viewports can have its display scrolled left, right, up, or down using the WindowScrollViewport() function described below. WindowScrollViewport() --------------------- This functions scrolls the viewport specific number of characters. Here is the prototype: int WindowScrollViewport(WPOINTER w, unsigned num, int direction) The first argument is the viewport and the second argument is the number of characters to scroll. The last argument is the direction to scroll. This direction can be UP, DOWN, LEFT, or RIGHT. Example: #include <stdio.h> #include <string.h> #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define FILENAMECHARS \ "25[A-Za-z0-9!@#$%/^&()+=_/-{}/[/]`~/.\\:]" VWPOINTER vw; /* virtual window pointer */ WPOINTER w; /* Window pointer */ char filename[26]; FILE *infile; /* input file handle */ main() { unsigned int i,j,row,col; WindowInitializeSystem(); WindowInitDesktop(0); /* set up a Type 0 virtual window */ vw = VirtualInitialize(NOATTRIBUTE,200,80,0); /* set up viewport window */ w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,78,12, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); /* read a file name */ read_file(); Page 159 The C Window Library Page 159 /* display file in viewport */ WindowAssignToVirtual(w,vw,0,0); CWLflush_kbd = TRUE; while (1) { switch (GET_KEY()) { /* Keep getting keys until ESCAPE key is hit */ case UARROW: /* Move viewport up 1 line */ WindowScrollViewport(w,1,UP); break; case DARROW: /* Move viewport down 1 line */ WindowScrollViewport(w,1,DOWN); break; case LARROW: /* Move viewport left 1 line */ WindowScrollViewport(w,1,LEFT); break; case RARROW: /* Move viewport right 1 line */ WindowScrollViewport(w,1,RIGHT); break; case ESC: /* End program */ close_all(); break; } } } read_file() { /* Gets a filename and displays it in the window */ int ch; unsigned r = 0, c = 0; filename[0]=0; WindowWriteString(w,"Please enter a file name: ",0,0); WindowGetString(w,0,26,filename,'_',0,40,0,0,FILENAMECHARS); if ((infile = fopen(filename,"r")) == NULL) { WindowMoveCursor(w,2,0); WindowPrintf(w,"File name %s does not exist\n" "Press a key to continue", filename); GET_KEY(); close_all(); } else while(1) { /* Read characters into virtual window */ ch = fgetc(infile); if (feof(infile)) break; if (ch != '\n') VirtualWriteRepeatCharacter(vw,ch,r,c++,1); else r++; c = 0; } } fclose(infile); } Page 160 The C Window Library Page 160 close_all() { WindowClose(w,NOEFFECT); WindowUninitializeSystem(); exit(0); } The example above is the same as the example for the WindowPositionViewport() function, except that the call to WindowPositionViewport() is replaced with the appropriate WindowScrollViewport() call. For WindowScrollViewport(), the window is never scrolled if the scroll will result in the upper left hand corner of the viewport being out of bounds of the virtual window. For example, you cannot scroll left 1 character if the viewport is located at (0,0) of the virtual window, similarly you cannot scroll right if the virtual window has a maximum of 80 characters and the upper left hand corner of the viewport is situated at (0,79). The same restrictions apply for scrolling up and down. Return Values for WindowScrollViewport(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_WINDOW │ Window does not exist. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ └────────────────┴────────────────────────┘ Page 161 The C Window Library Page 161 WRITING VIRTUAL WINDOW CONTENTS TO A FILE ----------------------------------------- The C Window Library allows you to print the contents of a virtual window using the VirtualWriteTextToFile() function. VirtualWriteTextToFile() ------------------------ The VirtualWriteTextToFile() function allows you to print the contents of a virtual window to a file. Here is the prototype: int VirtualWriteTextToFile(VWPOINTER vw, char *filename, int mode) The first argument is the virtual window. The second argument is the file name. This file can be any of the DOS filenames ("con", "prn", "aux", etc.). The file specified by filename must be closed before calling VirtualWriteTextToFile(), and the file handle is automatically closed before exiting VirtualWriteTextToFile(). The last argument is the mode switch. If mode is 1, a newline ('\n') is written to the file after each line of the virtual window written to the file. If mode is 0, no newline character is written. When mode 0 is chosen, the file is open in binary mode, else it is open in text mode. Example: #include "cwlwin.h" VWPOINTER vw; char *filename = "wintext"; char *filename2 = "wintext2"; main() { int i; WindowInitializeSystem(); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); for (i=0;i<10;i++) VirtualWriteString(vw,"Hello World!!",i,0); VirtualWriteTextToFile(vw,filename,1); /* use newlines */ VirtualWriteTextToFile(vw,filename2,0); /* no newlines */ } The example above illustrates two calls to VirtualWriteTextToFile(). The first call writes the contents of the virtual window vw to a file called "wintext". Note that the mode parameter for the first call is 1. This will cause '\n' to be written to the file for each line of the Page 162 The C Window Library Page 162 virtual window. The second call writes the virtual window text to a file call "wintest2", with the mode parameter being 0 (no '\n'). Please note that VirtualWriteTextToFile() does not check if the file already exists, so be careful that you do not replace files that are important to you. If there are no errors, VirtualWriteTextToFile() returns NO_ERROR. If there are errors, VirtualWriteTextToFile() will return one of the following: Return Values for VirtualWriteTextToFile(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │FILE_CANT_OPEN │ File cannot be opened. │ ├────────────────┼────────────────────────┤ │FILE_CANT_CLOSE │ File cannot be closed. │ └────────────────┴────────────────────────┘ Page 163 The C Window Library Page 163 MOVING THE LOGICAL CURSOR ------------------------- You can move and get the position of the logical cursor in a virtual window. VirtualMoveCursor() ------------------- The VirtualMoveCursor() function moves a virtual window's logical cursor to a new location. Here is the prototype: int VirtualMoveCursor(VWPOINTER vw, unsigned row, unsigned col) The first argument is the virtual window, and the second and third arguments denote the new (row,col) position of the logical cursor. Example: #include "cwlwin.h" VWPOINTER vw; main() { int i; WindowInitializeSystem(); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); VirtualMoveCursor(vw,10,10) /* Moves the logical cursor to row 10, column 10 of the virtual window */ } Return Values for VirtualMoveCursor(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │V_WINDOW_BOUND │ Row or Column is out │ │ │ of bounds. │ └────────────────┴────────────────────────┘ Page 164 The C Window Library Page 164 VirtualGetCursorPosition() -------------------------- The VirtualGetCursorPosition() function gives the current row and column of the cursor in a virtual window. Here is the prototype: int VirtualGetCursorPosition(VWPOINTER vw, unsigned *row, unsigned *col) The row and col arguments are pointers to unsigned integers that will contain the row and column of the cursor after VirtualGetCursorPosition() is called. Example: #include "cwlwin.h" VWPOINTER vw; main() { unsigned row,col; WindowInitializeSystem(); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); VirtualMoveCursor(vw,7,4); VirtualGetCursorPosition(vw,&row,&col); } Return Values for VirtualGetCursorPosition(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ └────────────────┴────────────────────────┘ Page 165 The C Window Library Page 165 CLEARING VIRTUAL WINDOWS ------------------------ The C Window Library contains functions that clears the entire virtual window, or clears defined rectangular regions of the virtual window. VirtualClear() -------------- The VirtualClear() function clears an entire virtual window to spaces. Here is the prototype: int VirtualClear(VWPOINTER vw) The only argument is the virtual window to clear. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0, 20,10,NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,0,0); for (i=0;i<10;i++) VirtualWriteString(vw,"Hello World!!",i,0); GET_KEY(); VirtualClear(vw); } Return Values for VirtualClear(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ └────────────────┴────────────────────────┘ Page 166 The C Window Library Page 166 VirtualClearAttr() ------------------ The VirtualClearAttr() function works the same way as the VirtualClear() function except that an attribute is specified. Here is the prototype: int VirtualClearAttr(VWPOINTER vw, int attr) The second argument is the video attribute to use. If the virtual window is NOATTRIBUTE, this function only clears the text. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; VWPOINTER vw; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,0,0); for (i=0;i<10;i++) VirtualWriteString(vw,"Hello World!!",i,0); GET_KEY(); VirtualClearAttr(vw,REVERSE); } Return Values for VirtualClearAttr(): Return Value Definition ┌────────────────┬────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼────────────────────────┤ │NO_ATTRIB │ The virtual window is │ │ │ NOATTRIBUTE. │ └────────────────┴────────────────────────┘ Page 167 The C Window Library Page 167 VirtualClearRegion() ------------------- The VirtualClearRegion() function clears a region of a virtual window. To use the VirtualClearRegion() function, you must describe the rectangular region to clear. Here is the prototype: int VirtualClearRegion(VWPOINTER vw, unsigned urow, unsigned ucol, unsigned lrow, unsigned lcol) where (urow,ucol) describes the upper left of the rectangle and (lrow,lcol) is the lower right of the virtual window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; VWPOINTER vw; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,0,0); for (i=0;i<10;i++) VirtualWriteString(vw,"Hello World!!",i,0); GET_KEY(); VirtualClearRegion(vw,4,4,8,15); } The VirtualClearRegion() call will clear the region described by the rectangular coordinates (4,4) and (8,15). Return Values for VirtualClearRegion(): Return Value Definition ┌────────────────┬─────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼─────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼─────────────────────────┤ │V_WINDOW_BOUND │ Invalid region specified│ └────────────────┴─────────────────────────┘ Page 168 The C Window Library Page 168 VirtualClearRegionAttr() ------------------------ The VirtualClearRegionAttr() function works the same as the VirtualClearRegion() function, except that a video attribute is specified. Here is the prototype: int VirtualClearRegionAttr(VWPOINTER vw, unsigned urow, unsigned ucol, unsigned lrow, unsigned lcol, int attr) The attr argument is a video attribute to use to clear the region. If the virtual window is NOATTRIBUTE, the attribute argument is ignored. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) WPOINTER w; VWPOINTER vw; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(ATTRIBUTE,30,80,NORM); WindowDisplay(w,1,NOEFFECT); WindowAssignToVirtual(w,vw,0,0); for (i=0;i<10;i++) VirtualWriteString(vw,"Hello World!!",i,0); GET_KEY(); VirtualClearRegionAttr(vw,4,4,8,15,REVERSE); } The VirtualClearRegionAttr() call will clear the region described by the rectangular coordinates (4,4) and (8,15) using the video attribute defined by the constant REVERSE. Return Values for VirtualClearRegionAttr(): Return Value Definition ┌────────────────┬─────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼─────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼─────────────────────────┤ │NO_ATTRIB │ The virtual window is │ │ │ NOATTRIBUTE. │ ├────────────────┼─────────────────────────┤ │V_WINDOW_BOUND │ Invalid region specified│ └────────────────┴─────────────────────────┘ Page 169 The C Window Library Page 169 FREEZING VIEWPORTS ------------------ You can temporarily suspend or 'freeze' a viewport window from displaying updates to the virtual window. This is good if there is data being written to the virtual window which takes a long time to generate. The viewport can be frozen when the information is being written, and unfrozen when the writing of the data is terminated. WindowFreeze() -------------- The WindowFreeze() function suspends or resumes displaying of virtual window updates on a viewport window. Here is the prototype: int WindowFreeze(WPOINTER w, int option) The first argument is the viewport window, and the second argument is the option flag. If this flag is 0, the window is unfrozen, i.e. the window will display virtual window updates. If it is 1, the window will suspend virtual window updates from being displayed. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; WPOINTER w; main() { int i; WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); vw = VirtualInitialize(NOATTRIBUTE,10,80,NORM); WindowAssignToVirtual(w,vw,0,0); WindowDisplay(w,1,NOEFFECT); /* Freeze Viewport */ WindowFreeze(w,1); for (i=0;i<10;i++) { delay(1000); VirtualPrintf(vw,"Line %d\n",i); } /* Unfreeze window */ WindowFreeze(w,0); Page 170 The C Window Library Page 170 GET_KEY(); /* Now try with window always displaying data */ VirtualClear(vw); for (i=0;i<10;i++) { delay(1000); VirtualPrintf(vw,"Line %d\n",i); } } The above program first freezes the viewport w with the first call to WindowFreeze(). Then text is written slowly to the virtual window vw. This text is not displayed until the window is unfrozen again with the second call to WindowFreeze(). Everything is reset and the writing of the text to the virtual window is done again, but this time the viewport is always displaying virtual window updates, even when the text is being written to the virtual window. The delay() function is discussed in the TIMED DELAYS section. Return Values for WindowFreeze(): Return Value Definition ┌────────────────┬─────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼─────────────────────────┤ │BAD_WINDOW │ The viewport window does│ │ │ not exist. │ ├────────────────┼─────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ ├────────────────┼─────────────────────────┤ │NO_ATTRIB │ The virtual window is │ │ │ NOATTRIBUTE. │ └────────────────┴─────────────────────────┘ Page 171 The C Window Library Page 171 DISPOSING OF VIRTUAL WINDOWS ---------------------------- The last step is to dispose of the virtual window. The function to do this is the VirtualClose() function. VirtualClose() ------------- The VirtualClose() function frees all the memory allocated to the virtual window and destroys the virtual window pointer. Here is the prototype: int VirtualClose(VWPOINTER vw, int hideflag, int effect) The first argument is the virtual window. The second argument is a flag that determines whether any viewports displaying the virtual window should be hidden. If this argument is 1, all viewports displaying the virtual window is hidden. If the argument is 0, all viewports are cleared, but not hidden. The third argument is the special effect to use when hiding the viewports. This argument is ignored if hideflag is 0. For a list of special effects, refer to the DISPLAYING WINDOWS section. Once VirtualClose() is called you must not use the VWPOINTER again unless you assign it to another virtual window, or create a new virtual window. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) VWPOINTER vw; /* virtual window pointer */ WPOINTER w1, w2; main() { WindowInitializeSystem(); WindowInitDesktop(0); vw = VirtualInitialize(NOATTRIBUTE,30,80,0); w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,0, 0,20,12,NORM,NORM,SINGLEBOX); w2 = WindowInitialize(DESKTOP_WINDOW,BORDER, 13,0,20,10,NORM,NORM,DOUBLEBOX); WindowDisplay(w1,1,NOEFFECT); WindowDisplay(w2,2,NOEFFECT); VirtualWriteString(vw,"This is a string",0,0); WindowAssignToVirtual(w1,vw,0,0); WindowAssignToVirtual(w2,vw,0,0); GET_KEY(); VirtualClose(vw,1,NOEFFECT); } Page 172 The C Window Library Page 172 Return Values for VirtualClose(): Return Value Definition ┌────────────────┬─────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────┼─────────────────────────┤ │BAD_V_WINDOW │ Virtual window does │ │ │ not exist. │ └────────────────┴─────────────────────────┘ Page 173 The C Window Library Page 173 INTRODUCTION TO MENU SYSTEM --------------------------- Menu systems are important entities in any program. The C Window Library has functions that create popup, pull-down, and bar menus. The popup menus are scrollable menus with a limit of 32,767 selections. The bar menus can have any number of entries. As of this version, the bar menus are not scrollable, although there will be an implementation of scrolling bar menus in a future version. The pull-down menus are a combination of popup and bar menus. You can change entries, hide entries, use hotkeys to invoke a menu entry, and many more things. Menu Manager ------------ The menu manager is the code in The C Window Library that handles moving the highlight bar in the menu, calling the menu functions when they are selected, keeps tracks of available entries, and other functions that keep track of the menu when selections are made. Page 174 The C Window Library Page 174 POP-UP MENUS ------------ Description ----------- A popup menu is a vertical menu with a list of entries that are selected by placing a highlight bar on the entry and pressing return, releasing the left mouse button, or pressing a key that will automatically move the highlight bar to the desired entry and invoking the entry. Popup menus are scrollable, in other words, if there are more entries than can be displayed in the window, the menu will scroll through the rest of the selections. You can have up to 32,767 entries in a popup menu. A popup menu consists of a window and a virtual window. The virtual window allows you to scroll through the entries, and the window is used as a viewport on the virtual window. Here is a partial list of the various options you can have with popup menus: * Highlight bar wrapping - wrap highlight bar to first or last option when there are no more selections. * Static Menus - menu remains on the screen when entry is selected. * Perpetual Menus - menu remain on the screen regardless of whether the PopupSelectMenu() function (explained later) is called or not. * Hidden (Unavailable) entries - You can make an entry in the popup menu unavailable or available at any time. * Color scheme of the menu - You can customize the color of the highlight bar, the hotkey letters, hidden entries, etc. * Change entry names - You can safely change the names displayed in the menu at any time. * Delete or Add Entries at any time. * Use a mouse to select menu entries. Page 175 The C Window Library Page 175 CREATING POP-UP MENUS --------------------- The PopupCreateMenu() function ------------------------------ To initialize a popup menu, the PopupCreateMenu() function is used. This function creates an empty popup menu. Adding entries to the menu will be discussed in the next section. Here is the prototype: POPUP_MENU_PTR PopupCreateMenu(WPOINTER parent, unsigned options, unsigned pcolor, int row, int col) The parent argument is a pointer to the window that will be the parent of the popup menu window. If the menu is to have no parent, this argument should be DESKTOP_WINDOW. The options argument denotes options that are used to turn on various aspect of a popup menu. The options are as follows: Option Definition ┌──────────────────┬───────────────────────────────────────────┐ │POPUPCREATWIN │Allows PopupCreateMenu() to create a │ │ │window. Once this window is created, it │ │ │is attached to the menu and will be used │ │ │for displaying the menu entries. The menu │ │ │window is defaulted to have a border │ │ │consisting of single lines. This option │ │ │should always be used unless you have a │ │ │window that you have created that you │ │ │would like to use. Any user-defined │ │ │windows must be attached to the menu by │ │ │calling PopupAttachWindow() before any │ │ │entries can be added. However, you can │ │ │change the characteristics of the default │ │ │window by getting the window pointer and │ │ │applying any of the Window...() functions │ │ │to it. │ ├──────────────────┼───────────────────────────────────────────┤ │POPUPRESIZEWIDTH │Automatically adjusts the width of the │ │ │menu window to fit the longest menu entry. │ ├──────────────────┼───────────────────────────────────────────┤ │POPUPRESIZEHEIGHT │Automatically adjusts the height of the │ │ │menu whenever menu entries are added or │ │ │deleted. │ ├──────────────────┼───────────────────────────────────────────┤ │POPUPRESIZEALL │Combination of POPUPRESIZEWIDTH and │ │ │POPUPRESIZEHEIGHT options. │ └──────────────────┴───────────────────────────────────────────┘ Page 176 The C Window Library Page 176 Option Definition ┌──────────────────┬───────────────────────────────────────────┐ │POPUPWRAP │Allows the menu highlight bar to wrap to │ │ │the first entry if the user moves the menu │ │ │highlight bar past the last entry, and │ │ │will wrap to the last entry if the │ │ │highlight bar is moved before the first │ │ │entry. │ ├──────────────────┼───────────────────────────────────────────┤ │POPUPSTATIC │Allows the menu to be displayed while the │ │ │user-defined menu function is invoked. │ ├──────────────────┼───────────────────────────────────────────┤ │POPUPSCROLLBAR │Draws a vertical scroll bar on the right │ │ │side of a popup menu window if the number │ │ │of menu entries exceed the height of the │ │ │window. This scroll bar will consist of │ │ │up and down arows, and a moveable scroll │ │ │box. The scroll box is a highlighted │ │ │character inside of the scroll bar that │ │ │indicates approximately where the menu │ │ │highlight bar is positioned in relation to │ │ │all of the entries. For example, if there │ │ │are 500 entries in the popup menu, and the │ │ │highlight bar is on entry 250, the scroll │ │ │box will appear in the center of the │ │ │scroll bar. This scroll bar can also be │ │ │controlled with a mouse. This is │ │ │discussed in the section Using A Mouse in │ │ │CWL. │ ├──────────────────┼───────────────────────────────────────────┤ │POPUPDISPLAY │Allows the menu to be displayed after │ │ │processing the entries for a menu. │ │ │Normally, when the PopupSelectMenu() │ │ │function is called to start the selection │ │ │process of the menu, (this will be │ │ │discussed later), the menu is invoked, and │ │ │selections can be made from the menu. │ │ │When the PopupSelectMenu() function exits, │ │ │the menu is hidden from the screen. If the │ │ │POPUPDISPLAY option is on, the menu will │ │ │still be displayed on exit, but no │ │ │selections can be made from it. │ ├──────────────────┼───────────────────────────────────────────┤ │POPUPENHANCEDKEY │Allows the processing of enhanced keys in │ │ │a menu. The enhanced keys are the F11 and │ │ │F12 keys, as well as grey keys used on │ │ │enhanced keyboards. │ └──────────────────┴───────────────────────────────────────────┘ The options described above can be combined with a bitwise OR operator. For example, if scroll bars, an automatic adjustable window, and the menu creates the window, the options would be: POPUPSCROLLBAR | POPUPRESIZEALL | POPUPCREATWIN Page 177 The C Window Library Page 177 The pcolor argument is an array of menu colors used to color different parts of the menu. An array of type unsigned int is used to define the colors used in a popup menu. Each element in the array denote a certain area of the popup menu. A list of the constants used to define these areas as well as their definitions is as follows: Menu Color Constant Definition ┌───────────────┬───┬───────────────────────────────────┐ │ENTRYCOLOR │ 0 │ Color of the text area of the │ │ │ │ popup menu's window. │ ├───────────────┼───┼───────────────────────────────────┤ │BORDERCOLOR │ 1 │ Color of the border of the popup │ │ │ │ menu's window. │ ├───────────────┼───┼───────────────────────────────────┤ │HOTKEYCOLOR │ 2 │ Color of each menu entry's hotkey │ │ │ │ character. │ ├───────────────┼───┼───────────────────────────────────┤ │HIGHLIGHTCOLOR │ 3 │ Color of a highlighted entry. │ │ │ │ This is effectively the color of │ │ │ │ an entry when the highlight bar is│ │ │ │ over the entry. │ ├───────────────┼───┼───────────────────────────────────┤ │UNAVAILCOLOR │ 4 │ Color of the unavailable entries. │ │ │ │ In CWL, you can make entries │ │ │ │ unavailable (the highlight bar │ │ │ │ skips over these entries). │ └───────────────┴───┴───────────────────────────────────┘ Colors can be created using the CREATE_VIDEO_ATTRIBUTE() macro. The row and col arguments denote where the popup menu window will be placed within the parent. The return value is a pointer to a structure called a POPUP_MENU_PTR. This pointer is used to identify the popup menu and is used in any subsequent functions that manipulate the popup menu. If the POPUP_MENU_PTR is POPUP_NULL_PTR the menu could not be created and CWLerror_code is set to NO_HEAP_MEM. Page 178 The C Window Library Page 178 Example: #include "cwlwin.h" unsigned int menu_colors[NUMPOPUPCOLORS]; POPUP_MENU_PTR p; main() { /* ... */ ... menu_color[ENTRYCOLOR] = CREATE_VIDEO_ATTTRIBUTE(BLACK_WHITE_); menu_color[BORDERCOLOR]= CREATE_VIDEO_ATTTRIBUTE(BLACK_WHITE_); menu_color[HOTKEYCOLOR] = CREATE_VIDEO_ATTTRIBUTE(BLUE_WHITE_); menu_color[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTTRIBUTE(BLACK_WHITE_); menu_color[UNAVAILCOLOR]= CREATE_VIDEO_ATTTRIBUTE(BLACK_WHITE_); p = PopupCreateMenu(DESKTOP_WINDOW, POPUPCREATEWIN | POPUPRESIZEALL, menu_color,0,0); if (p == POPUP_NULL_PTR) { /* popup window could not be created */ } ... } The example above shows an array of menu colors called menu_colors initialized with the color scheme that the menu will use. The constant NUMPOPUPCOLORS is defined in cwlwin.h and should be used to determine the size of the color array. Next, the POPUP_MENU_PTR p is initialized in the PopupCreateMenu() function. If the menu could not be created, p will be a NULL pointer, which is denoted by POPUP_NULL_PTR. Creating Popup Menu Entries --------------------------- Now that the menu has been created with PopupCreateMenu(), it is now necessary to fill in our menu entries in the menu. Here are a list of the functions that allow the creation and deletion of menu entries. Here is the prototype: int PopupInsertEntry(POPUP_MENU_PTR p, int type, int where, char *entry_string, int menuid, POPUPSELECTPROC popproc) int PopupAppendEntry(POPUP_MENU_PTR p, int type, char *entry_string, int menuid, POPUPSELECTPROC popproc) Page 179 The C Window Library Page 179 The p argument is the POPUP_MENU_PTR to the popup menu. The type argument denotes the menu entry type. The different types are as follows: Menu Type Definition ┌───────────────┬──────────────────────────────────────────┐ │CWL_MSTRING │ Denotes that the entry is a character │ │ │ string. │ ├───────────────┼──────────────────────────────────────────┤ │CWL_MSEPARATOR │ Entry is a menu separator. The │ │ │ separator is a horizontal line that is │ │ │ drawn in the menu. This entry is always │ │ │ skipped over by the highlight bar and │ │ │ cannot be chosen. If this type is used, │ │ │ entry_string must be the constant │ │ │ SEPARATOR, which is defined in cwlwin.h. │ ├───────────────┼──────────────────────────────────────────┤ │CWL_MDISABLED │ The entry is initially disabled. This │ │ │ option only works with CWL_MSTRING types.│ ├───────────────┼──────────────────────────────────────────┤ │CWL_MENABLED │ The entry is initially enabled. This │ │ │ option can be omitted when creating │ │ │ entries since this is the default if │ │ │ CWL_MDISABLED is not set. │ ├───────────────┼──────────────────────────────────────────┤ │CWL_MCHECKED │ The menu item has a check mark that is │ │ │ displayed as the first character of the │ │ │ menu string. │ ├───────────────┼──────────────────────────────────────────┤ │CWL_MUNCHECKED │ The menu item is initially unchecked. │ │ │ This option may be omitted when creating │ │ │ menu entries since CWL_MUNCHECKED is the │ │ │ default. │ ├───────────────┼──────────────────────────────────────────┤ │CWL_MGRAYED │ The menu item is initially grayed and │ │ │ disabled. This differs from │ │ │ CWL_MDISABLED in that the entry is also │ │ │ 'grayed' using this option. It is │ │ │ advantageous to use this option rather │ │ │ than CWL_MDISABLED since it is more than │ │ │ likely that disabled entries are also │ │ │ grayed. The actual disabling color may │ │ │ not really be gray, but whatever the │ │ │ UNAVAILCOLOR color was when the popup │ │ │ menu was created with PopupCreateMenu(). │ └───────────────┴──────────────────────────────────────────┘ The where argument for the PopupInsertEntry() function denotes the place in the menu where the entry will be inserted. The entry is inserted before the entry denoted by the where argument. Entries are numbered starting from 0. Page 180 The C Window Library Page 180 The entry_string argument is the menu string that is displayed in the menu. The ampersand character (&) in the menu string denotes that the next character is to be used as a hotkey. A hotkey will invoke a menu entry just be typing a key instead of moving the highlight to the entry and pressing enter. For example, if the entry string is " &Load ", the 'L' is considered as the hotkey. If you desire an ampersand character in the entry string, use two consecutive ampersand characters. If there are duplicate hotkeys in a menu, the menu entry that is closest to the first entry in the list is invoked. If the entry string is to be checked, the first character should be a blank or space character, since this position is where the check mark will be placed. The menuid argument is an optional integer that the programmer can use for any purpose. This value will be used in a future version of CWL when full event-driven menus will be implemented. The popproc argument is a user-defined function that is invoked when a menu entry is selected. The popproc function must have the following prototype: int popproc(POPUP_MENU_PTR pCurrent, int selection) The pCurrent argument is a pointer to the menu that invoked the function. The selection argument is the entry that was selected. For instance, if the first menu entry was selected, selection is 0. PopupAppendEntry() always places menu entries at the end of the list of defined menu entries. Return Values for PopupAppendEntry() and PopupInsertEntry(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ ├────────────────────┼───────────────────────────┤ │NO_HEAP_MEM │ Not enough memory to │ │ │ allocate for new entry. │ ├────────────────────┼───────────────────────────┤ │WINDOW_NOT_ATTACHED │ No attached window. │ └────────────────────┴───────────────────────────┘ Example: #include "cwlwin.h" unsigned int menu_colors[NUMPOPUPCOLORS]; POPUP_MENU_PTR p; int myproc(POPUP_MENU_PTR, int); /* Call back function */ Page 181 The C Window Library Page 181 main() { /* ... */ ... menu_color[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(BLACK_WHITE_); menu_color[BORDERCOLOR]= CREATE_VIDEO_ATTRIBUTE(BLACK_WHITE_); menu_color[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(BLUE_WHITE_); menu_color[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(BLACK_WHITE_); menu_color[UNAVAILCOLOR]= CREATE_VIDEO_ATTRIBUTE(BLACK_WHITE_); p = PopupCreateMenu(DESKTOP_WINDOW, POPUPCREATEWIN | POPUPRESIZEALL, menu_color,0,0); if (p == POPUP_NULL_PTR) { /* popup window could not be created */ exit(0); } /* Append a entry item to the menu */ PopupAppendEntry(p, CWL_MSTRING,"Menu Item 2",0,myproc); /* Insert an entry before the first entry. This entry is also grayed and disabled */ PopupInsertEntry(p,CWL_MSTRING | CWL_MGRAYED,0, "Menu Item 1",0,myproc); /* Append a separator */ PopupAppendEntry(p,CWL_MSEPARATOR, SEPARATOR,0, (POPUPSELECTPROC)0); /* Append a entry item to the menu */ PopupAppendEntry(p, CWL_MSTRING,"Menu Item 3",0,myproc); /* Insert an entry before the separator. */ PopupInsertEntry(p,CWL_MSTRING | CWL_MGRAYED,0, "Menu Item 1",2,myproc); ... } The example above creates a popup menu called p. Five entries are placed on the menu. The first entry is placed inside the menu with the PopupAppendEntry() function. The second entry is placed using the PopupInsertEntry(), and is inserted before the first entry. The third entry is a SEPARATOR entry. The fourth entry is appended using PopupAppendEntry(). The last entry is inserted before the separator by inserting it at position 2 of the menu. Page 182 The C Window Library Page 182 Inserting Multiple Entries -------------------------- You can insert multiple entries by calling the PopupInsertMultEntries() and PopupAppendMultEntries() functions. These function require that an array of structures called POPUP_MENU_ENTRY's are filled in with the desired values. The layout of this structure is defined as follows: typedef struct tagPOPUPENTRY { char *entry_name; unsigned int menuid; unsigned int type; POPUPSELECTPROC popproc; } POPUP_MENU_ENTRY; The entry_name, menuid, type and popproc members are the same as the corresponding names used in the PopupInsertEntry() and PopupAppendEntry(). The prototypes for PopupInsertMultEntries() and PopupAppendMultEntries() are as follows: int PopupInsertMultEntries(POPUP_MENU_PTR p, int where, POPUP_MENU_ENTRY *pentry, int numentries) int PopupAppendMultEntries(POPUP_MENU_PTR p, POPUP_MENU_ENTRY *pentry, int numentries) The p argument is the pointer to the popup menu. The where argument is analogous to the where argument for the PopupInsertEntry() function defined in the previous section. The where argument denotes the position in the menu where the entries will be inserted. This argument is pertinent only to the PopupInsertMultEntries() function. The pentry argument is the array of POPUP_MENU_ENTRY's to be inserted. The numentries argument is the number of POPUP_MENU_ENTRY's to insert. The PopupAppendMultEntries() always places the menu entries at the end of the popup menu. Page 183 The C Window Library Page 183 Return Values for PopupAppendMultEntries() and PopupInsertMultEntries(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ ├────────────────────┼───────────────────────────┤ │NO_HEAP_MEM │ Not enough memory to │ │ │ allocate for new entries. │ ├────────────────────┼───────────────────────────┤ │WINDOW_NOT_ATTACHED │ No attached window. │ └────────────────────┴───────────────────────────┘ Example: #include "cwlwin.h" /* Define menu function */ int menu_func(POPUP_MENU_PTR, int); /* Set up array of POPUP_MENU_ENTRY's */ POPUP_MENU_ENTRY menu_items[] = { {" &Load " ,0,CWL_MSTRING,menu_func}, {" &Pick " ,0,CWL_MSTRING,menu_func}, {" &New " ,0,CWL_MSTRING,menu_func}, {SEPARATOR ,0,CWL_MSEPARATOR ,(POPUPPROC)0}, {" &Save " ,0,CWL_MSTRING,menu_func}, {" &Write to ",0,CWL_MSTRING,menu_func}, {" &Directory ",0,CWL_MSTRING,menu_func}, {" &Change Dir",0,CWL_MSTRING,menu_func}, {" &OS Shell ",0,CWL_MSTRING,menu_func}, {" E&xit " ,0,CWL_MSTRING,menu_func} }; main() { ... /* Assume initialization has been done */ p = PopupCreateMenu( /* Arguments */); /* Insert the entries (there are 10 of them) */ PopupInsertMultEntries(p,0,menu_items,10); /* ... */ } The example above sets up an array of POPUP_MENU_ENTRY called menu_items, with each element filled in with the information desired. The PopupInsertMultEntries() function inserts all ten entries into the popup menu. Page 184 The C Window Library Page 184 Inserting a Popup Menu Within a Popup Menu ------------------------------------------ There may be situations where a popup menu scheme would make sense if one of the entries opened another popup menu when selected. These type of popup menus are called cascading menus. With CWL, you can insert a popup menu within a popup menu by using the PopupInsertPopup() function. Here is the prototype: int PopupInsertPopup(POPUP_MENU_PTR pOwner, POPUP_MENU_PTR pInsert, int type, int where, char *entry_string, int menuid) int PopupAppendPopup(POPUP_MENU_PTR pOwner, POPUP_MENU_PTR pInsert, int type, char *entry_string, int menuid) The pOwner argument is a pointer to the popup menu that will hold the inserted popup. The pInsert argument is the popup menu to insert. The type argument are the menu entry types that were defined for PopupInsertEntry(). This means that the entry can be initially grayed, checked, etc. The where argument denotes the position in pOwner to place the embedded popup entry. The entry_string argument is the actual name that will appear in pOwner for this menu entry. The menuid is an optional integer that the programmer can use for any purpose. For the PopupAppendPopup() function, the entries are attached to the end of the menu. When a menu is attached to another menu, the entry_name has a character appended to the name to denote that there is another menu associated with the entry. By default, this character is the ASCII 16, which is a triangular character that points right. The global character variable CWLpopup_char holds the current character that is used for the popup menu indicator. You can change this variable to any character desired by doing something like the following: CWLpopup_char = '*' The above uses the asterisk (*) as the embedded popup indicator. If no character is desired, this character can be a space. Popup menus can be cascaded to any level i.e. menus that are inserted can also have cascading menus. Page 185 The C Window Library Page 185 Return Values for PopupInsertPopup() and PopupAppendPopup(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ │ │ (either the parent or the │ │ │ menu that is to be │ │ │ embedded) │ ├────────────────────┼───────────────────────────┤ │NO_HEAP_MEM │ Not enough memory to │ │ │ allocate for new entry. │ ├────────────────────┼───────────────────────────┤ │WINDOW_NOT_ATTACHED │ No attached window. │ └────────────────────┴───────────────────────────┘ Example: #include "cwlwin.h" /* Define menu function */ int menu_func(POPUP_MENU_PTR, int); /* Set up array of POPUP_MENU_ENTRY's */ POPUP_MENU_ENTRY menu_items[] = { {" &Load ",0,CWL_MSTRING,menu_func}, {" &Pick ",0,CWL_MSTRING,menu_func}, {SEPARATOR ,0,CWL_MSEPARATOR ,(POPUPPROC)0}, {" &Save ",0,CWL_MSTRING,menu_func}, {" &Write to ",0,CWL_MSTRING,menu_func}, {" &Directory ",0,CWL_MSTRING,menu_func}, {" &Change Dir " ,0,CWL_MSTRING,menu_func}, {" &OS Shell ",0,CWL_MSTRING,menu_func}, {" E&xit ",0,CWL_MSTRING,menu_func} }; /* Set up array of POPUP_MENU_ENTRY's for second menu*/ POPUP_MENU_ENTRY menu_items2[] = { {" New Sub-Item1",0,CWL_MSTRING,menu_func}, {" New Sub-Item2",1,CWL_MSTRING,menu_func}, }; main() { POPUP_MENU_PTR p, p2; ... /* Assume initialization has been done */ p = PopupCreateMenu( /* Arguments */); p2 = PopupCreateMenu(/* Arguments */); /* Insert the entries */ PopupInsertMultEntries(p,0,menu_items,9); PopupInsertMultEntries(p2,0,menu_items2,2); /* Insert the popup menu as item 2 */ PopupInsertPopup(p,p2,"&Name",CWL_MSTRING,2,0) /* ... */ } Page 186 The C Window Library Page 186 The p2 menu is embedded into the p menu at menu entry 1. Here is an example of what these menus will look like on the screen: ┌────────────┐ │ Load ├──────────────┐ │ Pick │New Sub-Item 1│ │────────────│New Sub-Item 2│ │ Save ├──────────────┘ │ Write to │ │ Directory │ │ Change Dir │ │ OS Shell │ │ Exit │ └────────────┘ Note that the embedded menu appears if 'Pick' is selected. Deleting Menu Entries --------------------- Deleting many entries is easily accomplished by calling the PopupDeleteEntry() and PopupDeleteMultEntries() functions. The entries can be separator entries, string entries, or embedded popup menus. Here are the prototypes to these functions: int PopupDeleteEntry(POPUP_MENU_PTR p, int where) int PopupDeleteMultEntries(POPUP_MENU_PTR p, int where, int num) The argument p is the pointer to the popup menu. The where argument denotes the position of the menu entry to delete. For the PopupDeleteMultEntries() function, this position denotes the first menu item to delete. If where is -1, the last entry is deleted. The num argument in the PopupDeleteMultEntries() function is the number of entries to delete starting from position where. If an embedded popup menu is deleted, the embedded menu is still available for use as either a stand-alone popup menu, or can be embedded in another window. Return Values for PopupDeleteEntry() and PopupDeleteMultEntries(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ ├────────────────────┼───────────────────────────┤ │WINDOW_NOT_ATTACHED │ No attached window. │ └────────────────────┴───────────────────────────┘ Page 187 The C Window Library Page 187 Example: #include "cwlwin.h" POPUP_MENU_ENTRIES menu_items[] = { /* Fill in entries */ }; main() { POPUP_MENU_PTR p; ... /* Assume initialization has been done and entries were created*/ p = PopupCreateMenu( /* Arguments */); /* Insert the entries */ PopupInsertMultEntries(p,0,menu_items,3); /* Delete the first entry */ PopupDeleteEntry(p,0) /* ... */ } Initializing the size of the Virtual Window and Window ------------------------------------------------------ Normally when entries are added or deleted, the popup menu's virtual window and viewport window will grow or shrink accordingly. Sometimes this may be time consuming for a large number of entries. The PopupSetDimensions() function sets up the dimensions of the popup menu's virtual window to a specific size so that the virtual window does not have to be resized every time an entry is added. It also makes the virtual window unshrinkable, so this function should be used judiciously when determining the maximum size of the virtual window. The PopupSetWinDimensions() function sizes the viewport window to a fixed size. This is useful if you want the popup menu's window to not grow larger or smaller than a certain height or width when entries are added or deleted. Here are the prototypes for these two functions: int PopupSetDimensions(POPUP_MENU_PTR p, int width, int height, int options) int PopupSetWinDimensions(POPUP_MENU_PTR p, int width, int height, int options) The p argument is the pointer to the popup menu. The width and height arguments are the width and height desired. Page 188 The C Window Library Page 188 The options argument denote whether the width, height or both arguments are to be used when resizing the window. The various options are as follows: POPUP_SETWIDTH sets the width of the virtual window using the width argument. The height argument is ignored. POPUP_SETHEIGHT sets the heigth of the virtual window using the height argument. The width argument is ignored. POPUP_SETALL sets both the width and the height using the width and height arguments, respectively. If the width or height argument is less than the current virtual window's width or height, the argument is ignored. This function can only be used to enlarge a virtual window, not to shrink it. The viewport window is also sized to the dimensions specified, but can be made no smaller than width or height. You can manually resize the width and height by using WindowResize...() or VirtualResize() functions on the popup window or popup virtual window, respectively. When PopupSetWinDimensions() is called, the popup menu's viewport window is automatically resized, and will not grow beyond the sizes given in width and height. This differs from the PopupSetDimensions() function in that the virtual window is always resized if the number of entries exceeds the height of the window or the length of a new entry is wider than the virtual window. It is recommended that this function is used on the viewport window if a lot of entries are to be added. The viewport window can be retrieved using the POPUP_WINDOW() macro. The virtual window of the popup menu can be retrieved using the POPUP_VIRTUAL_WINDOW() macro. Both of these macros are described in Macros section of this manual. Return Values for PopupSetDimensions and PopupSetWinDimensions(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ ├────────────────────┼───────────────────────────┤ │NO_HEAP_MEM │ Not enough memory to │ │ │ allocate for new entries. │ ├────────────────────┼───────────────────────────┤ │WINDOW_NOT_ATTACHED │ No attached window. │ └────────────────────┴───────────────────────────┘ Page 189 The C Window Library Page 189 Example: #include "cwlwin.h" main() { POPUP_MENU_PTR p; ... /* Assume initialization has been done and entries were created*/ p = PopupCreateMenu( /* Arguments */); /* Reset the dimensions of the virtual window */ PopupSetDimensions(p,30,100,POPUP_SETALL); PopupSetWinDimensions(p,12,6,POPUP_SETALL); /* ... */ } Page 190 The C Window Library Page 190 SELECTING FROM POPUP MENUS -------------------------- We have now created the popup menu. Now how do we get the menu manager to act on our popup window? The answer is the PopupSelectMenu() function. PopupSelectMenu() function -------------------------- The PopupSelectMenu() function displays the popup window, and allows the user to move the highlight bar until he/she has placed the bar on the desired option, or the user presses a hotkey to invoke one of the entries. Before the call to the PopupSelectMenu(), nothing has been displayed (unless you called WindowDisplay() on the popup menu's window). This means that you can resize the popup window, change borders, write strings to the popup menus virtual window, insert and delete entries etc. while everything is hidden away from view. The only time when the popup menu is displayed is when the call to PopupSelectMenu() is made (or unless you have displayed the popup window yourself using WindowDisplay()). The prototype of the call to PopupSelectMenu() is as follows: int PopupSelectMenu(POPUP_MENU_PTR p, int rank, int start) The first argument is the POPUP_MENU_PTR. The second argument is the rank of the popup window. As with other windows, the rank determines how the window will be situated on the screen with respect to the other windows. The last argument is the number of the menu entry of where the highlight bar should be situated. Usually this is 0, but this will give you the option to start on any one of the menu entries. If the start value is out of bounds (say you have specified start to be 5 while there are only 5 menu entries) the menu manager will default to the first menu option. Now let's put everything together: /* Define menu function */ int menu_func(POPUP_MENU_PTR, int); /* Set up array of POPUP_MENU_ENTRY's */ POPUP_MENU_ENTRY menu_items[] = { {" &Load ",0,CWL_MSTRING,menu_func}, {" &Pick ",0,CWL_MSTRING,menu_func}, {" &New " ,0,CWL_MSTRING,menu_func}, {SEPARATOR ,0,CWL_MSEPARATOR ,(POPUPPROC)0}, {" &Save ",0,CWL_MSTRING,menu_func}, {" &Write to ",0,CWL_MSTRING,menu_func}, {" &Directory ",0,CWL_MSTRING,menu_func}, {" &Change Dir " ,0,CWL_MSTRING,menu_func}, {" &OS Shell ",0,CWL_MSTRING,menu_func}, {" E&xit " ,0,CWL_MSTRING,menu_func} }; Page 191 The C Window Library Page 191 unsigned int menu_colors[5]; POPUP_MENU_PTR p; main() { WindowInitializeSystem(); WindowInitDesktop(0); /* define colors */ menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLUE_); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(CYAN_,BLACK_); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_); /* create a POPUP_MENU_PTR */ p = PopupCreateMenu(DESKTOP_WINDOW, POPUPCREATEWIN | POPUPRESIZEALL, menu_color,0,0); /* insert the entries */ PopupInsertMultEntries(p,0,menu_items,10); /* get menu selections */ PopupSelectMenu(p, /* POPUP_MENU_PTR */ 1, /* rank of popup window */ 0 /* menu entry to start on */ ); } int menu_func(POPUP_MENU_PTR p, int which) { WPOINTER w; w = WindowInitialize(DESKTOP_WINDOW, BORDER,15,15,40,4, CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_), CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_), SINGLEBOX); WindowClear(w); WindowPrintf(w,"You have selected %s", POPUP_ENTRY_STRING(p,which)); WindowWriteCenterString(w,"Press a key to continue",3); WindowDisplay(w,1,NOEFFECT); GET_KEY(); WindowClose(w,NOEFFECT); if (which == 9) return POPUP_EXIT; else return POPUP_CONTINUE; } Page 192 The C Window Library Page 192 The above example has a call to PopupSelectMenu(). The arguments passed are p as the POPUP_MENU_PTR, a window rank of 1, and a starting position of 0. The POPUP_ENTRY_STRING() macro in the menu_func() function returns the entry string for the particualr menu entry. The first argument is the POPUP_MENU_PTR and the second argument is the entry number. Values passed to menu function ------------------------------ When a selection is made, the menu manager will call the function defined for the selection, and pass two arguments to this function. The first argument passed is the POPUP_MENU_PTR of the current popup menu and the second argument is the number of the entry selected. Entry numbers are numbered from 0 to the highest entry in the menu, less one. For example, if the " Load " entry is selected, the menu manager will pass the POPUP_MENU_PTR p, and a 0 to func(). If " Pick " is chosen, the menu manager passes a 1 as the second argument to func() etc. Values returned to menu manager ------------------------------- The user function must return an integer back to the menu manager. If the value returned to the menu manager is POPUP_EXIT, the menu manager will exit from the current menu and will return control back to the function that called it. If the return value is POPUP_CONTINUE, the menu continues to process selections. The menu_func() function defined above creates a window, displays the entry you have chosen, and returns a value back to the menu manager. If the value is POPUP_EXIT, the menu manager returns control back to the function that called it. In this case, main() called PopupSelectMenu(). A return value of POPUP_CONTINUE will cause the menu manager to let the user make another selection. The menu_func() function is a simple implementation. However your function can do much more sophisticated things, including opening other popup menus. If another popup menu is called while in another popup menu, the new popup menu gets its own menu manager and will not interfere with the original menu manager. This is good if a menu function will call another menu function. Return Values for PopupSelectMenu(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ └────────────────────┴───────────────────────────┘ Page 193 The C Window Library Page 193 SETTING OPTIONS IN POPUP MENUS ------------------------------ In addition to setting options using the PopupCreateMenu() function, you can turn on and off options at any time using the PopupSetOptions() function. The PopupSetOptions() function ------------------------------ The PopupSetOptions() function turns either one or more of the above options on or off. The prototype to the call is as follows: int PopupSetOptions(POPUP_MENU_PTR p, int option, int switch) The first argument is the POPUP_MENU_PTR. The second argument are the options that you wish to change. The constants that describe the options are exactly the same as the ones described in PopupCreateMenu(). The third argument is whether you want to switch the options on or off. Here are some sample calls to PopupSetOptions(): a) PopupSetOptions(p,POPUPWRAP,1) b) PopupSetOptions(p,POPUPSTATIC,1) c) PopupSetOptions(p,POPUPSTATIC,0) d) PopupSetOptions(p,POPUPDISPLAY,1) e) PopupSetOptions(p,POPUPENHANCEDKEY,1) The third argument is 1 for "turn option on", 0 for "turn option off". Setting Multiple Options ------------------------ You can also set multiple options with a single call by using a bitwise OR (|). For example: PopupSetOptions(p,POPUPWRAP | POPUPSTATIC 1) will set options POPUPWRAP and POPUPSTATIC. Return Values for PopupSetOptions(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ └────────────────────┴───────────────────────────┘ Page 194 The C Window Library Page 194 Getting Menu Options -------------------- You can retrieve the options in a popup menu by calling the PopupGetOptions() function. The prototype is as follows: int PopupGetOptions(POPUP_MENU_PTR p, int *options) The first argument is the popup menu that you want to retieve the options from. The second argument is a pointer to an integer that will hold the options when PopupGetOptions() returns. You can see if an option is set by using the bitwise AND. Example: int options; POPUP_MENU_PTR p; ... PopupGetOptions(p,&options); if (options & POPUPWRAP) { /* wrap option is on */ } ... Return Values for PopupGetOptions(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ └────────────────────┴───────────────────────────┘ Page 195 The C Window Library Page 195 DISABLING POPUP MENU ENTRIES ---------------------------- There may be cases when a menu entry should be disabled. The entry shows up in the menu, but it is a different color than the other entries and cannot be selected. Disabling and Enabling Entries ------------------------------ With The C Window Library, you can disable and enable menu entries at any time. The PopupEnableEntry() function performs this task. Here is the prototype to this function. int PopupEnableEntry(POPUP_MENU_PTR p, int where, int option) The first argument is the POPUP_MENU_PTR. The second argument is the number of the entry that you wish to change. Entry numbers range from 0 to the highest entry in the menu less one. The option argument is either CWL_MDISABLED to disable a menu, or CWL_MENABLED to enable an entry. You can combine CWL_MGRAYED with CWL_MDISABLED by using the bitwise OR operator (|) to gray the entry. Return Values for PopupEnableEntry(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ ├────────────────────┼───────────────────────────┤ │MENU_ENTRY_INVALID │ Entry number is invalid. │ └────────────────────┴───────────────────────────┘ Page 196 The C Window Library Page 196 CHANGING THE MENU ENTRY STRINGS ------------------------------- There may be times when you want to change a POPUP_MENU_ENTRY entry_name string. For instance, you may have a menu entry with the following entry_name: "Default File Name ABC.DAT" If the user selects this choice, the file name should change to another file name the user wants. From there the menu should reflect the new choice the user has made. Let's say the user has changed the default file name to DEF.DAT. The menu then should say: "Default File Name DEF.DAT" PopupSetEntryString() function ------------------------------ How do you change the entry string? One way is to fool around with the POPUP_MENU_PTR's structure members, and change the string yourself. This is not recommended for the novice to average C programmer, since it is not a good idea to change the structure members directly without a full understanding of the structure. A safer way is to call the PopupSetEntryString() function. A prototype of this function is as follows: PopupSetEntryString(POPUP_MENU_PTR p, int entry, char *newstring) The first argument is the POPUP_MENU_PTR. The second argument is the number of the entry that you wish to change. Entry numbers range from 0 to the highest entry in the menu less one. The third argument is a pointer to the new character string. The newstring cannot be longer than the current POPUP_MENU_ENTRY entry_name string. The return values are the same as the PopupEnableEntry() function defined above. Page 197 The C Window Library Page 197 CHECKING MENU ENTRIES --------------------- Menu entries can be checked or unchecked at any time. You usually check menu entries if one of the entries serves as an indicator to whether an option in your program is turned on or off. PopupCheckEntry() ----------------- PopupCheckEntry() places or erases a check mark in the first character position of the menu. You should define your menu strings so that the check mark can be placed properly without erasing any characters. Here is the prototype: PopupCheckEntry(POPUP_MENU_PTR p, int entry, int flag) The first argument is the POPUP_MENU_PTR. The second argument is the number of the entry that you wish to check or uncheck. Entry numbers range from 0 to the highest entry in the menu less one. The flag argument is TRUE if the entry is to be checked, or FALSE if the entry is to be unchecked. The return values are the same as the PopupEnableEntry() function defined above. Page 198 The C Window Library Page 198 REDEFINING MENU KEYS -------------------- Setting Global Key Definitions and the popup_key_definition Array ---------------------------------- You can redefine the keys used to control moving the highlight bar, accepting the menu choice, and exiting from the menu. Here is a list of the default key mapping: Function Key Constant ┌────────────────────────────┬──────────┬──────────────────────┐ │ Move highlight bar up │Up Arrow │POPUP_UPKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │ Move highlight bar down │Down Arrow│POPUP_DOWNKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │ Accept Menu Choice │Enter │POPUP_ACCEPTKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │ Escape Pop-up menu │Escape │POPUP_QUITKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │ Move To First Menu Item │Home │POPUP_HOMEKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │ Move to Last Menu Item │End │POPUP_ENDKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │ Scroll entries up by one │ │ │ │ page │PgUp │POPUP_PAGEUPKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │ Scroll entries down by one │ │ │ │ page │PgDn │POPUP_PAGEDOWNKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │*Move To Next Popup Menu │Unassigned│POPUP_RIGHTKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │*Move to Previous Popup Menu│Unassigned│POPUP_LEFTKEY │ ├────────────────────────────┼──────────┼──────────────────────┤ │*Escape Pulldown Menu │Unassigned│POPUP_PULLDOWN_QUITKEY│ └────────────────────────────┴──────────┴──────────────────────┘ The global array popup_key_definition contains the values of the default popup menu key definitions. The names under the Constant heading are the offsets in the popup_key_definition array of where the key value for the function is defined. For instance, the value for the "Move highlight bar up" function is located at popup_key_definition[POPUP_UPKEY]. You can change the values in popup_key_definition at any time, but make sure that a definition for "Escape Pop-up menu" always exists, and that there are no duplicate definitions (i.e. the "Move highlight bar up" key definition is the same as the "Move highlight bar down" key definition). When defining new key values, you should use the values defined in the cwlwin.h header file for non-ascii keys. * The POPUP_RIGHTKEY, POPUP_LEFTKEY, and the POPUP_PULLDOWN_QUITKEY definitions only apply to popup menus that are incorporated in a pulldown menu. See the section on pulldown menus for more information. Page 199 The C Window Library Page 199 Setting Local Key Definitions ----------------------------- Another way of redefining menu keys is to load your own array of key definitions with your desired values, and then calling the PopupAssignKeys() function. With this method, each menu can have different key definitions. PopupAssignKeys() function -------------------------- Here is a prototype of the PopupAssignKeys() function: int PopupAssignKeys(POPUP_MENU_PTR p, unsigned *keys) where p is the POPUP_MENU_PTR, and keys is an array of key definitions. Here is a small code example: #include "cwlwin.h" unsigned mykeys[NUMPOPUPKEYS] = {CTRLU,CTRLD,RETURN, ESC,HOME,END,0,0,0,0}; POPUP_MENU_PTR p; /* Other stuff...*/ main() { /* Assume p is initialized */ /* Assigns my key definitions to popup menu p */ PopupAssignKeys(p,mykeys); } The constant NUMPOPUPKEYS should be used to make sure that your array of key definitions is large enough to hold all the definitions. The above example uses the constants defined in cwlwin.h to assign to the array mykeys. Each position in the mykeys array uses the default key mapping explained above. In other words, mykeys[POPUP_UPKEY] is CTRLU, etc. Return Values for PopupAssignKeys(): Return Value Definition ┌────────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├────────────────────┼───────────────────────────┤ │POPUP_MENU_INVALID │ Popup Menu does not exist.│ └────────────────────┴───────────────────────────┘ Page 200 The C Window Library Page 200 PROCESSING UNDEFINED KEYS ------------------------- If you are an advanced programmer and/or have experience in using other window/menu libraries, you may be wondering "how do I define a function that supplies context-sensitive help for each POPUP_MENU_ENTRY? There is no structure member in POPUP_MENU_ENTRY that supplies this". With The C Window Library, any key that is not recognized by the menu manager (i.e. the key struck does not invoke a menu option, move the highlight bar up or down, or ends processing of the menu) can be processed by calling a user written function. The WindowGet...() family of functions allowed us to define a function that will be called if a key that has no current definition is pressed. For popup menus, we can do the same thing. The CWLpopup_undef_key_func function pointer -------------------------------------------- The global function pointer, CWLpopup_undef_key_func, can point to a user written function that will be called when the menu manager encounters a key that is not defined. The declaration for CWLpopup_undef_key_func is as follows: unsigned int (*CWLpopup_undef_key_func)(POPUP_MENU_PTR p, int sel, int *choice) The user written function takes three arguments. The first argument is a pointer to the popup menu that the menu manager is currently processing. The second argument is an integer that contains the value of the key that was pressed. The third argument is a pointer to an integer that will contain the number of the menu choice to execute. Initially, choice points to an integer that contains the current menu choice that the menu highlight bar is situated. For instance, if the highlight bar is on the first menu choice when an undefined key is pressed, *choice will be equal to 0. If CWLpopup_undef_key_func is equal to a Null Function pointer (NULLFN), no user defined function is called. By default, CWLpopup_undef_key_func is assigned to NULLFN. Values returned to menu manager ------------------------------- If CWLpopup_undef_key_func is assigned to a function, the function must return an integer back to the menu manager. This integer value will tell the menu manager how to proceed. Here is a list of the valid return values that the user written function can return: Page 201 The C Window Library Page 201 Return Action to Value Take ┌─────────────────────┬────────────────────────────────────┐ │ POPUP_CONTINUE │No Action. Continue processing the │ │ │popup menu. │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_MOVE_UP │Move the highlight bar up. │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_MOVE_DOWN │Move the highlight bar down. │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_DO_CHOICE │Accept and invoke menu entry │ │ │assigned to *choice. │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_MOVE_CONTINUE │Move the highlight bar to menu entry│ │ │assigned to *choice and continue │ │ │processing menu. │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_ESCAPE │Escape the popup menu. │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_MOVE_HOME │Move highlight to first available │ │ │menu entry. │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_MOVE_END │Move highlight to last available │ │ │menu entry. │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_MOVE_PAGEUP │Scroll the entries in the popup │ │ │window up by one "page" (a page is │ │ │the current height of the popup │ │ │window). │ ├─────────────────────┼────────────────────────────────────┤ │ POPUP_MOVE_PAGEDOWN │Scroll the entries in the popup │ │ │window down by one "page" (a page is│ │ │the current height of the popup │ │ │window). │ ├─────────────────────┼────────────────────────────────────┤ │*POPUP_MOVE_LEFT │Move to next popup menu. │ ├─────────────────────┼────────────────────────────────────┤ │*POPUP_MOVE_RIGHT │Move to previous popup menu. │ ├─────────────────────┼────────────────────────────────────┤ │*POPUP_PULLDOWN_QUIT │Escape pulldown menu │ └─────────────────────┴────────────────────────────────────┘ A return value of POPUP_CONTINUE is a "do nothing" command to the menu manager. If POPUP_DO_CHOICE is returned to the menu manager, the integer assigned to the parameter *choice is used as the menu entry to invoke. The highlight bar will automatically be moved to the menu choice specified, and the menu function will be called. If POPUP_MOVE_CONTINUE is returned to the menu manager, the highlight bar will be moved to the entry specified by the value of *choice, but no function is called. Return values of POPUP_DO_CHOICE and POPUP_MOVE_CONTINUE only work when the menu entry specified by *choice is an available Page 202 The C Window Library Page 202 entry or the POPUPVERRIDE option is on , otherwise the menu manager just continues processing the popup menu. * The POPUP_MOVE_RIGHT, POPUP_MOVE_LEFT, and POPUP_PULLDOWN_QUIT only apply to popup menus that are incorporated in a pulldown menu system. See the section on pulldown menus for more information. Here is an example of using a user defined function for the undefined keys: #include "cwlwin.h" /* Other includes */ int user_func(); main() { CWLpopup_undef_key_func = user_func; /* Other code */ } unsigned int user_func(POPUP_MENU_PTR p, int sel, int *choice) { switch(sel) { case F1: help(*choice); /* call help function */ return POPUP_CONTINUE; /* return "do nothing" */ case F2: *choice = 6; /* let menu manager know to do choice 7 on the menu */ return POPUP_DO_CHOICE; /* Also let menu manager know we are returning the "do the function assigned to *choice" command */ default: return POPUP_CONTINUE; /* let menu manager know not to do anything */ } } int help(int choice) { /* help function */ switch (choice) { case 0: /* do context-sensitive help for entry 0 */ break; Page 203 The C Window Library Page 203 case 1: /* do context-sensitive help for entry 1 */ break; /* do more entries */ /* ... */ } } In the above example, if the user hits F1, a help function is called. If you wanted to know how to incorporate a help function in the popup menus, here is the way to do it. If the user hits F2, the integer pointed to by choice is assigned a 6, and user_func() returns POPUP_DO_CHOICE to the menu manager. This tells the menu manager to invoke the function assigned to menu entry 7. Page 204 The C Window Library Page 204 PRE-INPUT FUNCTION ------------------ With The C Window Library, you can define a function that will be performed just before the menu manager waits for the user to enter a keystroke. This function can perform just about anything. Setting the CWLglobal_popup_prefunc function pointer ------------------------------------------------- The CWLglobal_popup_prefunc function pointer points to this user written function. Here is the prototype: int (*CWLglobal_popup_prefunc)(POPUP_MENU_PTR p, int *sel) The arguments that will be passed to your function are the following: a) The POPUP_MENU_PTR of the popup menu that called your function, and b) A pointer to the number of the selection that the highlight bar is currently on. The selection number ranges from 1 to the highest entry number of the menu. The pre-input function MUST return a value back to the menu manager. The return values that can be returned are the same as the CWLpopup_undef_key_func function described above. If you are using a version of The C Window Library prior to version 1.5, you must declare your pre-input function as returning an int, and you must return a value back to the menu manager. Versions prior to 1.5 declared the pre-input function as void. The POPUP_DO_CHOICE and POPUP_MOVE_CONTINUE return values will move the highlight bar to the entry number that is assigned to the *sel argument when the pre-input function has returned. By default, CWLglobal_popup_prefunc points to a NULLFN, and therefore will not be performed. However, you can implement pre-input functions depending on the current selection. For instance, you can write a function that displays extra information for each entry like so: #include "cwlwin.h" char *mess[] = { " This option saves and loads files", " This brings you in edit mode", " This compiles and/or links the current program", /* ... More stuff */ }; Page 205 The C Window Library Page 205 WPOINTER message_window; int disp_info(); main() { /* ... */ CWLglobal_popup_prefunc = disp_info; /* ... */ } int disp_info(POPUP_MENU_PTR p, int *sel) { /* Assume message_window already created and opened */ WindowClear(message_window, CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); WindowWriteString(message_window,mess[*sel],0,0); return POPUP_CONTINUE; } For simplicity, the menu definitions are left out of the preceding code sample. The disp_info displays the appropriate description in the window message_window. POPUP_CONTINUE is returned to the menu manager. This informs the menu manager to continue looking for a keystroke. Page 206 The C Window Library Page 206 DISPOSING OF POPUP MENUS ------------------------ PopupMenuClose() ---------------- If the popup menu is no longer needed, the PopupMenuClose() function will dispose of the popup menu and return any memory allocated to the popup menu, window, and virtual window memory back to the heap. The call to the function is very simple: PopupMenuClose(POPUP_MENU_PTR p) where p is the POPUP_MENU_PTR to dispose of. Since this function destroys the POPUP_MENU_PTR p, p must not be used for any popup menu functions, unless p is pointing to a valid POPUP_MENU_PTR. For any menus that may be embedded in p, they are destroyed as well. The return values and the reasons for failure are the same as PopupSelectMenu(). Page 207 The C Window Library Page 207 BAR MENUS --------- Description ----------- A bar menu is a horizontal menu with a list of entries that are selected by placing a highlight bar on the entry and pressing return, releasing the left mouse button, or pressing a key that will automatically move the highlight bar to the desired entry and invoking the entry. You can have up to 32,767 entries in a bar menu. A bar menu consists of only a window, unlike popup menus which use virtual windows. Page 208 The C Window Library Page 208 CREATING BAR MENUS ------------------ The BarCreateMenu() function ---------------------------- To initialize a bar menu, the BarCreateMenu() function is used. This function creates an empty bar menu. Adding entries to the menu will be discussed in the next section. Here is the prototype: BAR_MENU_PTR BarCreateMenu(WPOINTER parent, unsigned options, unsigned bcolor, int row, int col, int width) The parent argument is a pointer to the window that will be the parent of the bar menu window. If the menu is to have no parent, this argument should be DESKTOP_WINDOW. The options argument denotes options that are used to turn on various aspect of a bar menu. The options are as follows: Option Definition ┌────────────┬────────────────────────────────────────────┐ │BARCREATWIN │Allows BarCreateMenu() to create a window. │ │ │Once this window is created, it is attached │ │ │to the menu and will be used for displaying │ │ │the menu entries. The menu window is │ │ │defaulted to have a border consisting of │ │ │single lines. This option should always be │ │ │used unless you have a window that you have │ │ │created that you would like to use. Any │ │ │user-defined windows must be attached to │ │ │the menu by calling BarAttachWindow() │ │ │before any entries can be added. However, │ │ │you can change the characteristics of the │ │ │default window by getting the window │ │ │pointer and applying any of the Window...() │ │ │functions to it. │ ├────────────┼────────────────────────────────────────────┤ │BARWRAP │Allows the menu highlight bar to wrap to │ │ │the first entry if the user moves the menu │ │ │highlight bar past the last entry, and will │ │ │wrap to the last entry if the highlight bar │ │ │is moved before the first entry. │ ├────────────┼────────────────────────────────────────────┤ │BARSTATIC │Allows the menu to be displayed while the │ │ │user-defined menu function is invoked. │ └────────────┴────────────────────────────────────────────┘ Page 209 The C Window Library Page 209 Option Definition ┌──────────────┬────────────────────────────────────────────┐ │BARDISPLAY │Allows the menu to be displayed after │ │ │processing the entries for a menu. │ │ │Normally, when the BarSelectMenu() function │ │ │is called to start the selection process of │ │ │the menu, (this will be discussed later), │ │ │the menu is invoked, and selections can be │ │ │made from the menu. When the │ │ │BarSelectMenu() function exits, the menu is │ │ │hidden from the screen. If the BARDISPLAY │ │ │option is on, the menu will still be │ │ │displayed on exit, but no selections can be │ │ │made from it. │ ├──────────────┼────────────────────────────────────────────┤ │BARENHANCEDKEY│Allows the processing of enhanced keys in a │ │ │menu. The enhanced keys are the F11 and │ │ │F12 keys, as well as grey keys used on │ │ │enhanced keyboards. │ └──────────────┴────────────────────────────────────────────┘ The options described above can be combined with a bitwise OR operator. The bcolor argument is an array of menu colors used to color different parts of the menu. An array of type unsigned int is used to define the colors used in a bar menu. Each element in the array denote a certain area of the bar menu. A list of the constants used to define these areas as well as their definitions is as follows: Menu Color Constant Definition ┌──────────────┬───┬───────────────────────────────────┐ │ENTRYCOLOR │ 0 │Color of the text area of the │ │ │ │bar menu's window. │ ├──────────────┼───┼───────────────────────────────────┤ │BORDERCOLOR │ 1 │Color of the border of the bar │ │ │ │menu's window. │ ├──────────────┼───┼───────────────────────────────────┤ │HOTKEYCOLOR │ 2 │Color of each menu entry's hotkey │ │ │ │character. │ ├──────────────┼───┼───────────────────────────────────┤ │HIGHLIGHTCOLOR│ 3 │Color of a highlighted entry. │ │ │ │This is effectively the color of │ │ │ │an entry when the highlight bar is │ │ │ │over the entry. │ ├──────────────┼───┼───────────────────────────────────┤ │UNAVAILCOLOR │ 4 │Color of the unavailable entries. │ │ │ │In CWL, you can make entries │ │ │ │unavailable (the highlight bar │ │ │ │skips over these entries). │ └──────────────┴───┴───────────────────────────────────┘ Colors can be created using the CREATE_VIDEO_ATTRIBUTE() macro. Page 210 The C Window Library Page 210 The row and col arguments denote where the bar menu window will be placed within the parent. The width argument is the width of the bar menu window if BARCREATEWIN option is used. The return value is a pointer to a structure called a BAR_MENU_PTR. This pointer is used to identify the bar menu and is used in any subsequent functions that manipulate the bar menu. If the BAR_MENU_PTR is NULL the menu could not be created and CWLerror_code is set to NO_HEAP_MEM. Example: #include "cwlwin.h" unsigned int menu_colors[NUMBARCOLORS]; BAR_MENU_PTR b; main() { /* ... */ ... menu_color[ENTRYCOLOR] = CREATE_VIDEO_ATTTRIBUTE(BLACK_WHITE_); menu_color[BORDERCOLOR]= CREATE_VIDEO_ATTTRIBUTE(BLACK_WHITE_); menu_color[HOTKEYCOLOR] = CREATE_VIDEO_ATTTRIBUTE(BLUE_WHITE_); menu_color[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTTRIBUTE(BLACK_WHITE_); menu_color[UNAVAILCOLOR]= CREATE_VIDEO_ATTTRIBUTE(BLACK_WHITE_); b = BarCreateMenu(DESKTOP_WINDOW,BARCREATEWIN, menu_color,0,0,50); if (b == BAR_NULL_PTR) { /* bar window could not be created */ } ... } The example above shows an array of menu colors called menu_colors initialized with the color scheme that the menu will use. The constant NUMBARCOLORS is defined in cwlwin.h and should be used to determine the size of the color array. Next, the BAR_MENU_PTR b is initialized in the BarCreateMenu() function. If the menu could not be created, b will be a NULL pointer, which is denoted by BAR_NULL_PTR. Page 211 The C Window Library Page 211 Creating Bar Menu Entries ------------------------- Now that the menu has been created with BarCreateMenu(), it is now necessary to fill in our menu entries in the menu. Here are a list of the functions that allow the creation and deletion of menu entries. Here is the prototype: int BarInsertEntry(BAR_MENU_PTR b, int type, int where, char *entry_string, int menuid, BARSELECTPROC barproc) int BarAppendEntry(BAR_MENU_PTR b, int type, char *entry_string, int menuid, BARSELECTPROC barproc) The b argument is the BAR_MENU_PTR to the bar menu. The where argument for the BarInsertEntry() function denotes the place in the menu where the entry will be inserted. The entry is inserted before the entry denoted by the where argument the entry where. Entries are numbered starting from 0. The type argument denotes the menu entry type. The different types are as follows: Menu Type Definition ┌─────────────┬─────────────────────────────────────────┐ │CWL_MSTRING │Denotes that the entry is a character │ │ │string. │ ├─────────────┼─────────────────────────────────────────┤ │CWL_MDISABLED│The entry is initially disabled. This │ │ │option only works with CWL_MSTRING types.│ ├─────────────┼─────────────────────────────────────────┤ │CWL_MENABLED │The entry is initially enabled. This │ │ │option can be omitted when creating │ │ │entries since this is the default if │ │ │CWL_MDISABLED is not set. │ ├─────────────┼─────────────────────────────────────────┤ │CWL_MGRAYED │ The menu item is initially grayed and │ │ │disabled. This differs from │ │ │CWL_MDISABLED in that the entry is only │ │ │disabled in this option. It is │ │ │advantageous to use this option rather │ │ │than CWL_MDISABLED since it is more than │ │ │likely that disabled entries are also │ │ │grayed. The actual disabling color may │ │ │not really be gray, but whatever the │ │ │UNAVAILCOLOR color was when the bar │ │ │menu was created with BarCreateMenu(). │ └─────────────┴─────────────────────────────────────────┘ Page 212 The C Window Library Page 212 The entry_string argument is the menu string that is displayed in the menu. The ampersand character (&) in the menu string denotes that the next character is to be used as a hotkey. A hotkey will invoke a menu entry just be typing a key instead of moving the highlight to the entry and pressing enter. For example, if the entry string is " &Load ", the 'L' is considered as the hotkey. If you desire an ampersand character in the entry string, use two consecutive ampersand characters. If there are duplicate hotkeys in a menu, the menu entry that is closest to the first entry in the list is invoked. If the entry string is to be checked, the first character should be a blank or space character, since this position is where the check mark will be placed. The menuid argument is an optional integer that the programmer can use for any purpose. This value will be used in a future version of CWL when full event-driven menus will be implemented. The barproc argument is a user-defined function that is invoked when a menu entry is selected. The barproc function must have the following prototype: int barproc(BAR_MENU_PTR bCurrent, int selection) The bCurrent argument is a pointer to the menu that invoked the function. The selection argument is the entry that was selected. For instance, if the first menu entry was selected, selection is 0. BarAppendEntry() always places menu entries at the end of the list of defined menu entries. Return Values for BarAppendEntry() and BarInsertEntry(): Return Value Definition ┌───────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├───────────────────┼───────────────────────────┤ │BAR_MENU_INVALID │ Bar Menu does not exist. │ ├───────────────────┼───────────────────────────┤ │NO_HEAP_MEM │ Not enough memory to │ │ │ allocate for the entry. │ ├───────────────────┼───────────────────────────┤ │WINDOW_NOT_ATTACHED│ returned if the menu does │ │ │ not have an attached │ │ │ window. │ └───────────────────┴───────────────────────────┘ Example: #include "cwlwin.h" unsigned int menu_colors[NUMBARCOLORS]; BAR_MENU_PTR b; int myproc(BAR_MENU_PTR, int); /* Call back function */ Page 213 The C Window Library Page 213 main() { /* ... */ ... menu_color[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(BLACK_WHITE_); menu_color[BORDERCOLOR]= CREATE_VIDEO_ATTRIBUTE(BLACK_WHITE_); menu_color[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(BLUE_WHITE_); menu_color[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(BLACK_WHITE_); menu_color[UNAVAILCOLOR]= CREATE_VIDEO_ATTRIBUTE(BLACK_WHITE_); b = BarCreateMenu(DESKTOP_WINDOW, BARCREATEWIN, menu_color,0,0, 50); if (b == BAR_NULL_PTR) { /* bar window could not be created */ exit(0); } /* Append a entry item to the menu */ BarAppendEntry(b, CWL_MSTRING,"Menu Item 2",0,myproc); /* Insert an entry before the first entry. This entry is also grayed and disabled */ BarInsertEntry(b,CWL_MSTRING | CWL_MGRAYED,0, "Menu Item 1",0,myproc); /* Append a entry item to the menu */ BarAppendEntry(b, CWL_MSTRING,"Menu Item 3",0,myproc); /* Insert an entry before the separator. */ BarInsertEntry(b,CWL_MSTRING | CWL_MGRAYED,0, "Menu Item 1",2,myproc); ... } The example above creates a bar menu called b. Five entries are placed on the menu. The first entry is placed inside the menu with the BarAppendEntry() function. The second entry is placed using the BarInsertEntry(), and is inserted before the first entry. Page 214 The C Window Library Page 214 Inserting Multiple Entries -------------------------- You can insert multiple entries by calling the BarInsertMultEntries() and BarAppendMultEntries() functions. These function require that an array of structures called BAR_MENU_ENTRY's are filled in with the desired values. The layout of this structure is defined as follows: typedef struct tagBARENTRY { char *entry_name; unsigned int menuid; unsigned int type; BARSELECTPROC barproc; } BAR_MENU_ENTRY; The entry_name, menuid, type and barproc members are the same as the corresponding names used in the BarInsertEntry() and BarAppendEntry(). The prototypes for BarInsertMultEntries() and BarAppendMultEntries() are as follows: int BarInsertMultEntries(BAR_MENU_PTR b, int where, BAR_MENU_ENTRY *bentry, int numentries) int BarAppendMultEntries(BAR_MENU_PTR b, BAR_MENU_ENTRY *bentry, int numentries) The b argument is the pointer to the bar menu. The where argument is analogous to the where argument for the BarInsertEntry() function defined in the previous section. The where argument denotes the position in the menu where the entries will be inserted. This argument is pertinent only to the BarInsertMultEntries() function. The bentry argument is the array of BAR_MENU_ENTRY's to be inserted. The numentries argument is the number of BAR_MENU_ENTRY's to insert. The BarAppendMultEntries() always places the menu entries at the end of the bar menu. The return values for BarAppendMultEntries() and BarInsertMultEntries() is the same as BarInsertEntry() defined above. Page 215 The C Window Library Page 215 Example: #include "cwlwin.h" /* Define menu function */ int menu_func(BAR_MENU_PTR, int); /* Set up array of BAR_MENU_ENTRY's */ main() { ... /* Assume initialization has been done */ b = BarCreateMenu( /* Arguments */); /* Insert the entries (there are 8 of them) */ BarInsertMultEntries(b,0,menu_items,8); /* ... */ } The example above sets up an array of BAR_MENU_ENTRY called menu_items, with each element filled in with the information desired. The BarInsertMultEntries() function inserts all ten entries into the bar menu. Deleting Menu Entries --------------------- Deleting many entries is easily accomplished by calling the BarDeleteEntry() and BarDeleteMultEntries() functions. The entries can be separator entries, string entries, or embedded bar menus. Here are the prototypes to these functions: int BarDeleteEntry(BAR_MENU_PTR b, int where) int BarDeleteMultEntries(BAR_MENU_PTR b, int where, int num) The argument b is the pointer to the bar menu. The where argument denotes the position of the menu entry to delete. For the BarDeleteMultEntries() function, this position denotes the first menu item to delete. If where is -1, the last entry is deleted. The num argument in the BarDeleteMultEntries() function is the number of entries to delete starting from position where. If an embedded bar menu is deleted, the embedded menu is still available for use as either a stand-alone bar menu, or can be embedded in another window. Page 216 The C Window Library Page 216 Return Values for BarDeleteEntry() and BarDeleteMultEntries(): Return Value Definition ┌───────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├───────────────────┼───────────────────────────┤ │BAR_MENU_INVALID │ Bar Menu does not exist. │ ├───────────────────┼───────────────────────────┤ │MENU_ENTRY_INVALID │ Entry number is invalid. │ └───────────────────┴───────────────────────────┘ Example: #include "cwlwin.h" BAR_MENU_ENTRIES menu_items[] = { /* Fill in entries */ }; main() { BAR_MENU_PTR b; ... /* Assume initialization has been done and entries were created*/ b = BarCreateMenu( /* Arguments */); /* Insert the entries */ BarInsertMultEntries(b,0,menu_items,3); /* Delete the first entry */ BarDeleteEntry(b,0) /* ... */ } Page 217 The C Window Library Page 217 SELECTING FROM BAR MENUS ------------------------ We have now created the bar menu. Now how do we get the menu manager to act on our bar window? The answer is the BarSelectMenu() function. BarSelectMenu() function ------------------------ The BarSelectMenu() function displays the bar window, and allows the user to move the highlight bar until he/she has placed the bar on the desired option, or the user presses a hotkey to invoke one of the entries. Before the call to the BarSelectMenu(), nothing has been displayed. This means that you can resize the bar window, change borders, write strings to the bar menus virtual window, insert and delete entries etc. while everything is hidden away from view. The only time when the bar menu is displayed is when the call to BarSelectMenu() is made (or unless you have displayed the bar window yourself using WindowDisplay()). The prototype of the call to BarSelectMenu() is as follows: int BarSelectMenu(BAR_MENU_PTR b, int rank, int start) The first argument is the BAR_MENU_PTR. The second argument is the rank of the bar window. As with other windows, the rank determines how the window will be situated on the screen with respect to the other windows. The last argument is the number of the menu entry of where the highlight bar should be situated. Usually this is 0, but this will give you the option to start on any one of the menu entries. If the start value is out of bounds (say you have specified start to be 5 while there are only 5 menu entries) the menu manager will default to the first menu option. Now let's put everything together: /* Define menu function */ int menu_func(BAR_MENU_PTR, int); /* Set up array of BAR_MENU_ENTRY's */ BAR_MENU_ENTRY bar_items[] = { {"&File",0,CWL_MSTRING,menu_func}, {"&Edit",0,CWL_MSTRING,menu_func}, {"&Run", 0,CWL_MSTRING,menu_func}, {"&Compile",0,CWL_MSTRING,menu_func}, {"&Project",0,CWL_MSTRING,menu_func}, {"&Options", 0,CWL_MSTRING,menu_func}, {"&Debug",0,CWL_MSTRING,menu_func}, {"&Break/watch",0,CWL_MSTRING,menu_func} }; Page 218 The C Window Library Page 218 unsigned int menu_colors[5]; BAR_MENU_PTR b; main() { WindowInitializeSystem(); WindowInitDesktop(0); /* define colors */ menu_colors[ENTRYCOLOR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_); menu_colors[BORDERCOLOR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_); menu_colors[HOTKEYCOLOR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLUE_); menu_colors[HIGHLIGHTCOLOR] = CREATE_VIDEO_ATTRIBUTE(CYAN_,BLACK_); menu_colors[UNAVAILCOLOR] = CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_); /* create a BAR_MENU_PTR */ b = BarCreateMenu(DESKTOP_WINDOW, BARCREATEWIN, BARRESIZEALL, menu_color,0,0); /* insert the entries */ BarInsertMultEntries(b,0,menu_items,8); /* get menu selections */ BarSelectMenu(b, /* BAR_MENU_PTR */ 1, /* rank of bar window */ 0 /* menu entry to start on */ ); } int menu_func(BAR_MENU_PTR b, int which) { WPOINTER w; w = WindowInitialize(DESKTOP_WINDOW, BORDER,15,15,40,4, CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_), CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_), SINGLEBOX); WindowClear(w); WindowPrintf(w,"You have selected %s", BAR_ENTRY_STRING(b,which)); WindowWriteCenterString(w,"Press a key to continue",3); WindowDisplay(w,1,NOEFFECT); GET_KEY(); return BAR_CONTINUE; } The above example has a call to BarSelectMenu(). The arguments passed are b as the BAR_MENU_PTR, a window rank of 1, and a starting position of 0. The BAR_ENTRY_STRING() macro in the menu_func() function returns the entry string for the particualr menu entry. The first argument is the BAR_MENU_PTR and the second argument is the entry number. Page 219 The C Window Library Page 219 Values passed to menu function ------------------------------ When a selection is made, the menu manager will call the function defined for the selection, and pass two arguments to this function. The first argument passed is the BAR_MENU_PTR of the current bar menu and the second argument is the number of the entry selected. Entry numbers are numbered from 0 to the highest entry in the menu, less one. For example, if the " Load " entry is selected, the menu manager will pass the BAR_MENU_PTR b, and a 1 to func(). If " Pick " is chosen, the menu manager passes a 2 as the second argument to func() etc. Values returned to menu manager ------------------------------- The user function must return an integer back to the menu manager. If the value returned to the menu manager is BAR_EXIT, the menu manager will exit from the current menu and will return control back to the function that called it. If the return value is BAR_CONTINUE, the menu continues to process selections. The menu_func() function defined above creates a window, displays the entry you have chosen, and returns a value back to the menu manager. If the value is BAR_EXIT, the menu manager returns control back to the function that called it. In this case, main() called BarSelectMenu(). A return value of BAR_CONTINUE will cause the menu manager to let the user make another selection. The menu_func() function is a simple implementation. However your function can do much more sophisticated things, including opening other bar menus. If another bar menu is called while in another bar menu, the new bar menu gets its own menu manager and will not interfere with the original menu manager. This is good if a menu function will call another menu function. Return Values for BarSelectMenu(); Return Value Definition ┌───────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├───────────────────┼───────────────────────────┤ │BAR_MENU_INVALID │ Bar Menu does not exist. │ └───────────────────┴───────────────────────────┘ Page 220 The C Window Library Page 220 SETTING OPTIONS IN BAR MENUS ---------------------------- In addition to setting options using the BarCreateMenu() function, you can turn on and off options at any time using the BarSetOptions() function. The BarSetOptions() function ---------------------------- The BarSetOptions() function turns either one or more of the above options on or off. The prototype to the call is as follows: int BarSetOptions(BAR_MENU_PTR b, int option, int switch) The first argument is the BAR_MENU_PTR. The second argument are the options that you wish to change. The constants that describe the options are exactly the same as the ones described in BarCreateMenu(). The third argument is whether you want to switch the options on or off. Here are some sample calls to BarSetOptions(): a) BarSetOptions(b,BARWRAP,1) b) BarSetOptions(b,BARSTATIC,1) c) BarSetOptions(b,BARSTATIC,0) d) BarSetOptions(b,BARDISPLAY,1) e) BarSetOptions(b,BARENHANCEDKEY,1) The third argument is 1 for "turn option on", 0 for "turn option off". Setting Multiple Options ------------------------ You can also set multiple options with a single call by using a bitwise OR (|). For example: BarSetOptions(b,BARWRAP | BARSTATIC,1) will set options BARWRAP and BARSTATIC defined above. Return Values for BarSetOptions(): Return Value Definition ┌───────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├───────────────────┼───────────────────────────┤ │BAR_MENU_INVALID │ Bar Menu does not exist. │ └───────────────────┴───────────────────────────┘ Page 221 The C Window Library Page 221 Getting Menu Options -------------------- You can retrieve the options in a popup menu by calling the BarGetOptions() function. The prototype is as follows: int BarGetOptions(BAR_MENU_PTR b, int *options) The first argument is the bar menu that you want to retieve the options from. The second argument is a pointer to an integer that will hold the options when BarGetOptions() returns. You can see if an option is set by using the bitwise AND. Example: int options; BAR_MENU_PTR b; ... BarGetOptions(b,&options); if (options & BARWRAP) { /* wrap option is on */ } ... Return Values for BarGetOptions(): Return Value Definition ┌───────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├───────────────────┼───────────────────────────┤ │BAR_MENU_INVALID │ Bar Menu does not exist. │ └───────────────────┴───────────────────────────┘ Page 222 The C Window Library Page 222 ENABLING AND DISABLING MENU ENTRIES ----------------------------------- There may be cases when a menu entry should be made unavailable. The entry shows up in the menu, but it is a different color than the other entries, and the highlight bar will just skip over this unavailable entry. Disabling and Enabling Entries ------------------------------ With The C Window Library, you can disable and enable menu entries at any time. The BarEnableEntry() function performs this task. Here is the prototype to this function. int BarEnableEntry(BAR_MENU_PTR b, int where, int option) The first argument is the BAR_MENU_PTR. The second argument is the number of the entry that you wish to change. Entry numbers range from 0 to the highest entry in the menu less one. The option argument is either CWL_MDISABLED to disable a menu, or CWL_MENABLED to enable an entry. You can combine CWL_MGRAYED with CWL_MDISABLED by using the bitwise OR operator (|) to gray the entry. Page 223 The C Window Library Page 223 SETTING THE MENU ENTRY STRINGS ------------------------------ There may be times when you want to change a BAR_MENU_ENTRY entry_name string. For instance, you may have a menu entry with the following entry_name: "Default File Name ABC.DAT" If the user selects this choice, the file name should change to another file name the user wants. From there the menu should reflect the new choice the user has made. Let's say the user has changed the default file name to DEF.DAT. The menu then should say: "Default File Name DEF.DAT" BarSetEntryString() function ---------------------------- How do you change the entry string? One way is to fool around with the BAR_MENU_PTR's structure members, and change the string yourself. This is not recommended for the novice to average C programmer, since it is not a good idea to change the structure members directly without a full understanding of the structure. A safer way is to call the BarSetEntryString() function. A prototype of this function is as follows: BarSetEntryString(BAR_MENU_PTR b, int entry, char *newstring) The first argument is the BAR_MENU_PTR. The second argument is the number of the entry that you wish to change. Entry numbers range from 0 to the highest entry in the menu less one. The third argument is a pointer to the new character string. The newstring cannot be longer than the current BAR_MENU_ENTRY entry_name string. Return Values for BarSetEntryString(): Return Value Definition ┌───────────────────┬───────────────────────────┐ │NO_ERROR │ No error occured. │ ├───────────────────┼───────────────────────────┤ │BAR_MENU_INVALID │ Bar Menu does not exist. │ ├───────────────────┼───────────────────────────┤ │MENU_ENTRY_INVALID │ Entry number is invalid. │ └───────────────────┴───────────────────────────┘ Page 224 The C Window Library Page 224 REDEFINING MENU KEYS -------------------- Setting Global Key Definitions and the CWLbar_key_def Array ------------------------ You can redefine the keys used to control moving the highlight bar, accepting the menu choice, and exiting from the menu. Here is a list of the default key mapping: Function Key Constant ┌────────────────────────┬───────────┬─────────────┐ │Move highlight bar right│Right Arrow│BAR_RIGHTKEY │ ├────────────────────────┼───────────┼─────────────┤ │Move highlight bar left │Down Arrow │BAR_LEFTKEY │ ├────────────────────────┼───────────┼─────────────┤ │Accept Menu Choice │Enter │BAR_ACCEPTKEY│ ├────────────────────────┼───────────┼─────────────┤ │Escape Bar menu │Escape │BAR_QUITKEY │ ├────────────────────────┼───────────┼─────────────┤ │Move To First Menu Item │Home │BAR_HOMEKEY │ ├────────────────────────┼───────────┼─────────────┤ │Move to Last Menu Item │End │BAR_ENDKEY │ └────────────────────────┴───────────┴─────────────┘ The global array CWLbar_key_def contains the values of the default bar menu key definitions. The names under the Constant heading are the offsets in the CWLbar_key_def array of where the key value for the function is defined. For instance, the value for the "Move highlight bar up" function is located at CWLbar_key_def[BAR_UPKEY]. You can change the values in CWLbar_key_def at any time, but make sure that a definition for "Escape Pop-up menu" always exists, and that there are no duplicate definitions (i.e. the "Move highlight bar up" key definition is the same as the "Move highlight bar down" key definition). When defining new key values, you should use the values defined in the cwlwin.h header file for non-ascii keys. Setting Local Key Definitions ----------------------------- Another way of redefining menu keys is to load your own array of key definitions with your desired values, and then calling the BarAssignKeys() function. With this method, each menu can have different key definitions. Page 225 The C Window Library Page 225 BarAssignKeys() function ------------------------ Here is a prototype of the BarAssignKeys() function: int BarAssignKeys(BAR_MENU_PTR b, unsigned *keys) where b is the BAR_MENU_PTR, and keys is an array of key definitions. Here is a small code example: #include "cwlwin.h" unsigned mykeys[NUMBARKEYS] = {CTRLU,CTRLD,RETURN, ESC,HOME,END,0,0,0,0}; BAR_MENU_PTR b; /* Other stuff...*/ main() { /* Assume b is initialized */ /* Assigns my key definitions to bar menu b */ BarAssignKeys(b,mykeys); } The constant NUMBARKEYS should be used to make sure that your array of key definitions is large enough to hold all the definitions. The above example uses the constants defined in cwlwin.h to assign to the array mykeys. Each position in the mykeys array uses the default key mapping explained above. In other words, mykeys[BAR_UPKEY] is CTRLU, etc. If there is no error, then NO_ERROR is returned. If there is an error, the error conditions and reasons are the same as the BarSelectMenu() function defined above. Page 226 The C Window Library Page 226 PROCESSING UNDEFINED KEYS ------------------------- If you are an advanced programmer and/or have experience in using other window/menu libraries, you may be wondering "how do I define a function that supplies context-sensitive help for each BAR_MENU_ENTRY? There is no structure member in BAR_MENU_ENTRY that supplies this". With The C Window Library, any key that is not recognized by the menu manager (i.e. the key struck does not invoke a menu option, move the highlight bar up or down, or ends processing of the menu) can be processed by calling a user written function. The WindowGet...() family of functions allowed us to define a function that will be called if a key that has no current definition is pressed. For bar menus, we can do the same thing. The CWLbar_undef_key_func function pointer ------------------------------------------ The global function pointer, CWLbar_undef_key_func, can point to a user written function that will be called when the menu manager encounters a key that is not defined. The declaration for CWLbar_undef_key_func is as follows: unsigned int (*CWLbar_undef_key_func)(BAR_MENU_PTR b, int sel, int *choice) The user written function takes three arguments. The first argument is a pointer to the bar menu that the menu manager is currently processing. The second argument is an integer that contains the value of the key that was pressed. The third argument is a pointer to an integer that will contain the number of the menu choice to execute. Initially, choice points to an integer that contains the current menu choice that the menu highlight bar is situated. For instance, if the highlight bar is on the first menu choice when an undefined key is pressed, *choice will be equal to 0. If CWLbar_undef_key_func is equal to a Null Function pointer (NULLFN), no user defined function is called. By default, CWLbar_undef_key_func is assigned to NULLFN. Values returned to menu manager ------------------------------- If CWLbar_undef_key_func is assigned to a function, the function must return an integer back to the menu manager. This integer value will tell the menu manager how to proceed. Here is a list of the valid return values that the user written function can return: Page 227 The C Window Library Page 227 Return Action to Value Take ┌─────────────────┬───────────────────────────────────────┐ │BAR_CONTINUE │ No Action. Continue processing the bar│ │ │ menu. │ ├─────────────────┼───────────────────────────────────────┤ │BAR_DO_CHOICE │ Accept and invoke menu entry assigned │ │ │ to *choice. │ ├─────────────────┼───────────────────────────────────────┤ │BAR_MOVE_CONTINUE│ Move the highlight bar to menu entry │ │ │ assigned to *choice and continue │ │ │ processing menu. │ ├─────────────────┼───────────────────────────────────────┤ │BAR_ESCAPE │ Escape the bar menu. │ ├─────────────────┼───────────────────────────────────────┤ │BAR_MOVE_LEFT │ Move to next bar menu. │ ├─────────────────┼───────────────────────────────────────┤ │BAR_MOVE_RIGHT │ Move to previous bar menu. │ ├─────────────────┼───────────────────────────────────────┤ │BAR_MOVE_HOME │ Move highlight to first entry. │ ├─────────────────┼───────────────────────────────────────┤ │BAR_MOVE_END │ Move highlight to last entry. │ └─────────────────┴───────────────────────────────────────┘ A return value of BAR_CONTINUE is a "do nothing" command to the menu manager. If BAR_DO_CHOICE is returned to the menu manager, the integer assigned to the parameter *choice is used as the menu entry to invoke. The highlight bar will automatically be moved to the menu choice specified, and the menu function will be called. If BAR_MOVE_CONTINUE is returned to the menu manager, the highlight bar will be moved to the entry specified by the value of *choice, but no function is called. Here is an example of using a user defined function for the undefined keys: #include "cwlwin.h" /* Other includes */ int user_func(); main() { CWLbar_undef_key_func = user_func; /* Other code */ } Page 228 The C Window Library Page 228 unsigned int user_func(BAR_MENU_PTR b, int sel, int *choice) { switch(sel) { case F1: help(*choice); /* call help function */ return BAR_CONTINUE; /* return "do nothing" */ case F2: *choice = 6; /* let menu manager know to do choice 7 on the menu */ return BAR_DO_CHOICE; /* Also let menu manager know we are returning the "do the function assigned to *choice" command */ default: return BAR_CONTINUE; /* let menu manager know not to do anything */ } } int help(int choice) { /* help function */ switch (choice) { case 0: /* do context-sensitive help for entry 0 */ break; case 1: /* do context-sensitive help for entry 1 */ break; /* do more entries */ /* ... */ } } In the above example, if the user hits F1, a help function is called. If you wanted to know how to incorporate a help function in the bar menus, here is the way to do it. If the user hits F2, the integer pointed to by choice is assigned a 6, and user_func() returns BAR_DO_CHOICE to the menu manager. This tells the menu manager to invoke the function assigned to menu entry 7. Page 229 The C Window Library Page 229 PRE-INPUT FUNCTION ------------------ With The C Window Library, you can define a function that will be performed just before the menu manager waits for the user to enter a keystroke. This function can perform just about anything. Setting the CWLglobal_bar_prefunc function pointer ------------------------------------------------- The CWLglobal_bar_prefunc function pointer points to this user written function. Here is the prototype: int (*CWLglobal_bar_prefunc)(BAR_MENU_PTR b, int *sel) The arguments that will be passed to your function are the following: a) The BAR_MENU_PTR of the bar menu that called your function, and b) A pointer to the number of the selection that the highlight bar is currently on. The selection number ranges from 1 to the highest entry number of the menu. The pre-input function MUST return a value back to the menu manager. The return values that can be returned are the same as the CWLbar_undef_key_func function described above. If you are using a version of The C Window Library prior to version 1.5, you must declare your pre-input function as returning an int, and you must return a value back to the menu manager. Versions prior to 1.5 declared the pre-input function as void. The BAR_DO_CHOICE and BAR_MOVE_CONTINUE return values will move the highlight bar to the entry number that is assigned to the *sel argument when the pre-input function has returned. By default, CWLglobal_bar_prefunc points to a NULLFN, and therefore will not be performed. However, you can implement pre-input functions depending on the current selection. For instance, you can write a function that displays extra information for each entry like so: #include "cwlwin.h" char *mess[] = { " This option saves and loads files", " This brings you in edit mode", " This compiles and/or links the current program", /* ... More stuff */ }; Page 230 The C Window Library Page 230 WPOINTER message_window; int disp_info(); main() { /* ... */ CWLglobal_bar_prefunc = disp_info; /* ... */ } int disp_info(BAR_MENU_PTR b, int *sel) { /* Assume message_window already created and opened */ WindowClear(message_window, CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); WindowWriteString(message_window,mess[*sel],0,0); return BAR_CONTINUE; } For simplicity, the menu definitions are left out of the preceding code sample. The disp_info displays the appropriate description in the window message_window. BAR_CONTINUE is returned to the menu manager. This informs the menu manager to continue looking for a keystroke. Page 231 The C Window Library Page 231 DISPOSING OF BAR MENUS ---------------------- BarMenuClose() ------------- If the bar menu is no longer needed, the BarMenuClose() function will dispose of the bar menu and return any memory allocated to the bar menu, window, and virtual window memory back to the heap. The call to the function is very simple: BarMenuClose(BAR_MENU_PTR b) where b is the BAR_MENU_PTR to dispose of. Since this function destroys the BAR_MENU_PTR b, b must not be used for any bar menu functions, unless b is pointing to a valid BAR_MENU_PTR. The return values and the reasons for failure are the same as BarSelectMenu(). Page 232 The C Window Library Page 232 PULLDOWN MENUS -------------- Description ----------- A pulldown menu is a combination of popup menus and a bar menu. The bar menu portion of the pulldown menu acts the same way as a normal bar menu. However when a choice is made from the bar menu, a popup menu appears with more options to choose. An example of a pulldown menu is the integrated environments of most PC based C compilers. Most of what was discussed previously will apply to pulldown menus. Make sure that you have read the sections on popup menus and bar menus before preceding. Bar Menu and Bar Menu levels ---------------------------- With pulldown menus there are two levels; the bar menu level and the popup menu level. When in the bar menu level, no popup menu's are displayed, and the move right and move left keys move the highlight bar to the next or previous selection in the bar menu. When in the popup menu level, the move right and move left keys not only move the highlight in the bar menu, but will also display the popup menu associated with the bar menu option. Page 233 The C Window Library Page 233 CREATING PULLDOWN MENUS ----------------------- There are 4 steps that must be done when creating pulldown menus. They are as follows: Step 1) Call PulldownCreateMenu() to create an empty pulldown menu. Step 2) Create each popup menu to be displayed underneath the bar. Step 3) Call PulldownInsertEntry() or PulldownAppendEntry() to insert or add the entries on the pulldown menu. For Step 1) the bar menu is created automatically. There is no need for the programmer to create a bar menu. Step 2) is as described in the Popup windows section. Step 3) is a function that inserts the popup menus defined in step 2 into the pulldown menus. The PulldownCreateMenu() function --------------------------------- To create an empty pulldown menu template, the PulldownCreateMenu() function is used. Here is the prototype: PULLDOWN_MENU_PTR PulldownCreateMenu(WPOINTER wParent, int options, unsigned *bcolor, int row, int col, int width) The wParent argument is the pointer to the window that will be the parent to the pulldown menu. If no parent window is desired, use the DESKTOP_WINDOW constant. The options argument follow the same options as for bar menus, such as BARSTATIC or BARWRAP. See the BAR MENU section for these bar menu options. The bcolor is an array of menu colors which is exactly the same argument for the BarCreateMenu() function. The row and col arguments is the position to place the pulldown menu. The width is the width of the bar portion of the menu window. Page 234 The C Window Library Page 234 Note that the return value is a pointer to a pulldown menu, namely, a PULLDOWN_MENU_PTR. This is the handle that has to be used when referencing the pulldown menu. If there are errors, PulldownCreateMenu() returns NULL, and CWLerror_code is set to the error that occurred. Adding and Inserting menu entries --------------------------------- Each entry on the bar portion of the pulldown menu has to be added to the menu. The way to do this is to use either the PulldownInsertEntry() or PulldownAppendEntry() functions. Here are the prototypes to these functions: int PulldownInsertEntry(PULLDOWN_MENU_PTR pd, int type, int where, char *entry_string, int menuid, BARSELECTPROC func, POPUP_MENU_PTR p) int PulldownAppendEntry(PULLDOWN_MENU_PTR pd, int type, char *entry_string, int menuid, BARSELECTPROC func, POPUP_MENU_PTR pop) The pd argument is the PULLDOWN_MENU_PTR. This is the value that was returned when PulldownCreateMenu() was called. The type argument is the menu type. The available types are the same as the types available to bar and popup menus. These include CWL_MSTRING, CWL_MDISABLED, CWL_MGRAYED, etc. The only type that is not allowed is CWL_MSEPERATOR, since pulldowns do not have separators. The where argument denotes the position to place the menu item. (PulldownInsertEntry() only). The entry_string argument is a pointer to the string that will be displayed in the menu. The menuid argument is an optional integer argument that can be used for any purpose. The last two arguments, func and pop, should be explained in tandem, since one depends on the other. The func argument can take on one of two types of values: If func is BAR_NULL_FUNC (a NULL function), the popup menu defined in the pop argument (the last argument) is displayed. If the func argument is not BAR_NULL_FUNC, the user-defined function func is called when a selection is made. This allows entries in the pulldown menu to have no popup menu associated with them, and still have functions invoked if they are selected. Page 235 The C Window Library Page 235 If func is BAR_NULL_FUNC, pop MUST point to a valid POPUP_MENU_PTR. The popup menus are placed underneath the bar menu in a 'pleasing' manner, so you do not have to do the hard work and place them yourself. This means that using a POPUP_MENU_PTR as part of a pulldown menu will render the popup menu's previous location moot, but most programmers usually find the position of the popup menus acceptable. However, you can move a popup menu anywhere on the screen after PulldownAppendEntry() or PulldownInsertEntry() is called. Return Values for PulldownInsertEntry() and PulldownAppendEntry(): Return Value Definition ┌──────────────────────┬────────────────────────────────┐ │NO_ERROR │ No error occured. │ ├──────────────────────┼────────────────────────────────┤ │PULLDOWN_MENU_INVALID │ Pulldown Menu does not exist. │ └──────────────────────┴────────────────────────────────┘ Deleting menu entries --------------------- You can delete entries from the pulldown menu. The PulldownDeleteEntry() function deletes an entry, including the entries popup if it exists. Here is the prototype: int PulldownDeleteEntry(PULLDOWN_MENU_PTR pd, int where) The where argument is the entry to delete. Entries are numbered starting from 0. If a popup menu is associated with the entry, the POPUP_MENU_PTR of the entry is not destroyed, only its reference in the pulldown menu is removed. Return Values for PulldownInsertEntry() and PulldownAppendEntry(): Return Value Definition ┌──────────────────────┬────────────────────────────────┐ │NO_ERROR │ No error occured. │ ├──────────────────────┼────────────────────────────────┤ │PULLDOWN_MENU_INVALID │ Pulldown Menu does not exist. │ ├──────────────────────┼────────────────────────────────┤ │MENU_ENTRY_INVALID │ Entry number invalid. │ └──────────────────────┴────────────────────────────────┘ Page 236 The C Window Library Page 236 SELECTING MENU ENTRIES ---------------------- To start the selection process in a pulldown menu, the PulldownSelectMenu() function is called. Here is the prototype: int PulldownSelectMenu(PULLDOWN_MENU_PTR pd, int rank, int start, int immediate) The rank argument is the rank of the bar menu of the pulldown menu. The start argument determines the starting entry to place the highlight bar. The immediate argument is a flag that denotes whether the popup menu of the desired bar entry is to be displayed when the PulldownSelectMenu() function is called. If immediate is TRUE, the popup menu is displayed. If FALSE, the popup menu is not displayed, and only the bar menu portion of the pulldown menu is displayed. When a selection is made in a pulldown menu, the user-defined function that is associated with the popup menu is called if a popup menu exists for the entry, or the user-defined function defined for the bar menu is called if the entry does not have a popup menu associated with it. The user-defined function must return a value back to the menu manager. There are two possible return values, PULLDOWN_EXIT and PULLDOWN_CONTINUE. The PULLDOWN_EXIT return value will cause the menu manager to close both the popup menu window (if one was displayed), and the bar menu. Then control is returned back to the function that called PulldownSelectMenu(). The PULLDOWN_CONTINUE return value will cause the menu manager to continue processing the pulldown menu without closing the popup window (if one was displayed). If the return value is not one of the ones mentioned above, PULLDOWN_CONTINUE is assumed. Selections made on a bar menu item that has a popup menu associated with it will display the popup menu. Return Values for PulldownSelectMenu(): Return Value Definition ┌──────────────────────┬────────────────────────────────┐ │NO_ERROR │ No error occured. │ ├──────────────────────┼────────────────────────────────┤ │PULLDOWN_MENU_INVALID │ Pulldown Menu does not exist. │ ├──────────────────────┼────────────────────────────────┤ │MENU_ENTRY_INVALID │ Entry number invalid. │ └──────────────────────┴────────────────────────────────┘ Page 237 The C Window Library Page 237 DISPOSING OF PULLDOWN MENUS --------------------------- To dispose of a pulldown menu, use the PulldownMenuClose() or PulldownMenuCloseAll() functions. Here are the prototyes for these functions: int PulldownMenuCloseAll(PULLDOWN_MENU_PTR pd) int PulldownMenuClose(PULLDOWN_MENU_PTR pd) The difference between these functions is that PulldownMenuCloseAll() destroys all popup menus associated with the pulldown menu, while PulldownMenuClose() only deletes the bar portion but leaves the popup menus alone. Return Values for PulldownMenuClose() and PulldownMenuCloseAll(): Return Value Definition ┌──────────────────────┬────────────────────────────────┐ │NO_ERROR │ No error occured. │ ├──────────────────────┼────────────────────────────────┤ │PULLDOWN_MENU_INVALID │ Pulldown Menu does not exist. │ └──────────────────────┴────────────────────────────────┘ USING BAR MENU FUNCTIONS ------------------------ Any thing that was mentioned in the BAR MENUS chapter can be applied to the bar menu portion of the pulldown menu. To get a BAR_MENU_PTR from a pulldown menu, use the PulldownGetBar() function. The prototype is as follows: BAR_MENU_PTR PulldownGetBar(PULLDOWN_MENU_PTR pd) Note that a BAR_MENU_PTR is returned. You can then apply of the techniques and functions mentioned previously to the bar menu. This includes enabling and disabling entries, setting options, etc. The menu manager can determine whether the bar menu is really part of a pulldown menu system and will act accordingly. For example, disabling a bar menu entry will disable the popup menu window from being displayed. The only thing that is not recommended is to call BarMenuClose() on the bar menu, since PulldownMenuFree() or PulldownMenuFreeAll() destroys the bar menu. All global user-defined functions for bar menus (CWLglobal_bar_prefunc and CWLbar_undef_key_func) are active for the pulldown menu pointers bar menu. Page 238 The C Window Library Page 238 USING POPUP MENU FUNCTIONS -------------------------- Just as with the bar menu, the individual popup menus can also be manipulated using the methods described in POPUP MENUS. To get the POPUP_MENU_PTR for a particular entry in the pulldown menu, use the PulldownGetPopup() function. Here is the prototype: POPUP_MENU_PTR PulldownGetPopup(PULLDOWN_MENU_PTR pd, int entry) The entry argument is the entry in the pulldown menu of the desired popup menu. If the entry does not have a popup associated with it, POPUP_NULL_PTR is returned. Just as the menu manager can determine whether a bar menu is part of a pulldown menu, it also determines that a popup menu is part of a pulldown menu system. Do not call PopupMenuFree() on the popup menu, since the pulldown menu always assumes that the popup menu is available. All global user-defined functions for popup menus (CWLglobal_popup_prefunc and CWLpopup_undef_key_func) are active for the pulldown menu's popup menus. Example of a Pulldown Menu -------------------------- Here is an example of a CWL program that sets up a pulldown menu and makes selections from it: #include "cwlwin.h" #include <string.h> /* define colors */ #define YELLOWONRED CREATE_VIDEO_ATTRIBUTE(RED_, YELLOW_) #define WHITEONBLUE CREATE_VIDEO_ATTRIBUTE(BLUE_, WHITE_) #define BLUEONWHITE CREATE_VIDEO_ATTRIBUTE(WHITE_, BLUE_) #define BLACKONCYAN CREATE_VIDEO_ATTRIBUTE(CYAN_, BLACK_) #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_, WHITE_) #define BLACKONWHITE \ CREATE_VIDEO_ATTRIBUTE(WHITE_, BLACK_) #define WHITEONRED \ CREATE_VIDEO_ATTRIBUTE(RED_,LIGHTWHITE_) #define GRAYONWHITE \ CREATE_VIDEO_ATTRIBUTE(WHITE_,GRAY_) Page 239 The C Window Library Page 239 unsigned menu_colors[NUMMENUCOLORS]; /* Menu colors */ void pulldown_demo (); int rt1 _PROTO_((POPUP_MENU_PTR, int)); int rt2 _PROTO_((BAR_MENU_PTR, int)); WPOINTER pw; void main() { int b; WindowInitializeSystem(); ClearScreen(NORM); /* Save Base Screen as a window */ WindowInitDesktop(CWLactive_page); /* define colors */ menu_colors[ENTRYCOLOR] = menu_colors[BORDERCOLOR] = BLACKONWHITE; menu_colors[UNAVAILCOLOR] = GRAYONWHITE; menu_colors[HOTKEYCOLOR] = menu_colors[HIGHLIGHTCOLOR] = WHITEONBLACK /* create status window */ pw = WindowInitialize(DESKTOP_WINDOW,BORDER, 15,0,40,5,NORM,NORM,SINGLEBOX); WindowCenter(pw,HORIZCENTER); /* Call Pulldown demo function */ pulldown_demo(); /* uninitialize CWL */ WindowUninitSystem(); } /* create pulldown menu here */ void pulldown_demo() { int i; PULLDOWN_MENU_PTR pull; POPUP_MENU_PTR pmenu[8]; /* Create a PULLDOWN_MENU_PTR */ pull = PulldownCreateMenu(DESKTOP_WINDOW, /* Parent */ BARWRAP, /* options for bar */ menu_colors, /* color scheme */ 0, /* row */ 0, /* column */ 75); /* width */ Page 240 The C Window Library Page 240 /********************************* * Create all of the popup menus * *********************************/ /* Create first popup */ PopupAppendEntry(pmenu[0],CWL_MSTRING , " &Load ",0,rt1); PopupAppendEntry(pmenu[0],CWL_MSTRING , " &Pick ",0,rt1); PopupAppendEntry(pmenu[0],CWL_MSTRING , " &New ",0,rt1); PopupAppendEntry(pmenu[0],CWL_MSTRING , " &Save ",0,rt1); PopupAppendEntry(pmenu[0],CWL_MSTRING , " &Write to ",0,rt1); PopupAppendEntry(pmenu[0],CWL_MSTRING , " &Directory ",0,rt1); PopupAppendEntry(pmenu[0],CWL_MSTRING , " &Change Dir ",0,rt1); PopupAppendEntry(pmenu[0],CWL_MSTRING , " &Quit ",0,rt1); /* create second popup */ pmenu[1] = PopupCreateMenu(DESKTOP_WINDOW, POPUPSTATIC | POPUPMOUSE | POPUPRESIZEALL | POPUPWRAP | POPUPMOUSE | POPUPCREATEWIN, menu_colors,0,0); PopupAppendEntry(pmenu[1],CWL_MSTRING , " &Run ",0,rt1); PopupAppendEntry(pmenu[1],CWL_MSTRING , " &Program Reset",0,rt1); PopupAppendEntry(pmenu[1],CWL_MSTRING , " &Go to Cursor",0,rt1); PopupAppendEntry(pmenu[1],CWL_MSTRING , " &Trace Into ",0,rt1); PopupAppendEntry(pmenu[1],CWL_MSTRING , " &Step Over ",0,rt1); PopupAppendEntry(pmenu[1],CWL_MSTRING , " &User Screen ",0,rt1); /* create third popup */ pmenu[2] = PopupCreateMenu(DESKTOP_WINDOW, POPUPSTATIC | POPUPMOUSE | POPUPRESIZEALL | POPUPWRAP | POPUPMOUSE | POPUPCREATEWIN, menu_colors,0,0); PopupAppendEntry(pmenu[2],CWL_MSTRING , " &Compile to OBJ",0,rt1); PopupAppendEntry(pmenu[2],CWL_MSTRING , " &Make EXE file",0,rt1); Page 241 The C Window Library Page 241 PopupAppendEntry(pmenu[2],CWL_MSTRING , " &Link EXE file",0,rt1); PopupAppendEntry(pmenu[2],CWL_MSTRING , " &Build all ",0,rt1); PopupAppendEntry(pmenu[2],CWL_MSTRING , " &Primary C File",0,rt1); PopupAppendEntry(pmenu[2],CWL_MSTRING , " &Get Info ",0,rt1); /* create fourth popup */ pmenu[3] = PopupCreateMenu(DESKTOP_WINDOW, POPUPSTATIC | POPUPMOUSE | POPUPRESIZEALL | POPUPWRAP | POPUPMOUSE | POPUPCREATEWIN, menu_colors,0,0); PopupAppendEntry(pmenu[3],CWL_MSTRING , " &Compiler ",0,rt1); PopupAppendEntry(pmenu[3],CWL_MSTRING , " &Linker ",0,rt1); PopupAppendEntry(pmenu[3],CWL_MSTRING , " &Environment ",0,rt1); PopupAppendEntry(pmenu[3],CWL_MSTRING , " &Directories ",0,rt1); PopupAppendEntry(pmenu[3],CWL_MSTRING , " &Save Options ",0,rt1); PopupAppendEntry(pmenu[3],CWL_MSTRING , " &Retrieve options ",0,rt1); /* create fifth popup */ pmenu[4] = PopupCreateMenu(DESKTOP_WINDOW, POPUPSTATIC | POPUPMOUSE | POPUPRESIZEALL | POPUPWRAP | POPUPMOUSE | POPUPCREATEWIN, menu_colors,0,0); PopupAppendEntry(pmenu[4],CWL_MSTRING , " &Evaluate ",0,rt1); PopupAppendEntry(pmenu[4],CWL_MSTRING , " &Call Stack ",0,rt1); PopupAppendEntry(pmenu[4],CWL_MSTRING , " &Find Function",0,rt1); PopupAppendEntry(pmenu[4],CWL_MSTRING , " &Refresh display ",0,rt1); PopupAppendEntry(pmenu[4],CWL_MSTRING , " &Display Swapping Smart",0,rt1); PopupAppendEntry(pmenu[4],CWL_MSTRING , " &Source Debugging ",0,rt1); Page 242 The C Window Library Page 242 /* create sixth popup */ pmenu[5] = PopupCreateMenu(DESKTOP_WINDOW, POPUPSTATIC | POPUPMOUSE | POPUPRESIZEALL | POPUPWRAP | POPUPMOUSE | POPUPCREATEWIN, menu_colors,0,0); PopupAppendEntry(pmenu[5],CWL_MSTRING , " &Add watch Ctrl-F7",0,rt1); PopupAppendEntry(pmenu[5],CWL_MSTRING , " &Delete watch Ctrl-F3",0,rt1); PopupAppendEntry(pmenu[5],CWL_MSTRING , " &Edit Watch ",0,rt1); PopupAppendEntry(pmenu[5],CWL_MSTRING , " &Remove All Watches",0,rt1); PopupAppendEntry(pmenu[5],CWL_MSEPARATOR,"",0,rt1); PopupAppendEntry(pmenu[5],CWL_MSTRING , " &Toggle breakpoint ",0,rt1); PopupAppendEntry(pmenu[5],CWL_MSTRING , " &Clear all breakpoints",0,rt1); PopupAppendEntry(pmenu[5],CWL_MSTRING , " &View Next breakpoint",0,rt1); /************************************* * insert entries into pulldown menu * *************************************/ PulldownInsertEntry(pull, CWL_MSTRING , 0,"&File", 0,BAR_NULL_PTR, pmenu[0]); /* Note that this entry does not have a pulldown associated with it */ PulldownInsertEntry(pull, CWL_MSTRING , 1,"&Edit", 0,rt2, POPUP_NULL_PTR); PulldownInsertEntry(pull, CWL_MSTRING , 2,"&Run", 0,BAR_NULL_PTR, pmenu[1]); PulldownInsertEntry(pull, CWL_MSTRING , 3,"&Compile", 0,BAR_NULL_PTR, pmenu[2]); PulldownInsertEntry(pull, CWL_MSTRING , 4,"&Project", 0,BAR_NULL_PTR, pmenu[3]); Page 243 The C Window Library Page 243 PulldownInsertEntry(pull, CWL_MSTRING , 5,"&Options", 0,BAR_NULL_PTR, pmenu[4]); PulldownInsertEntry(pull, CWL_MSTRING , 6,"&Miscellaneous", 0,BAR_NULL_PTR, pmenu[5]); /* Test disabling by turning off the last entry */ BarEnableEntry(PulldownGetBar(pull),6,CWL_MGRAYED); /* Go! */ PulldownSelectMenu(pull,1,0,0); /* Dispose of pulldown menu and all other menus used to build it */ PulldownMenuFreeAll(pull); } /* Routine that is called when popup function is invoked */ int rt1(POPUP_MENU_PTR p, int which) { int dummy; WindowClear(pw); /* Display the entry name that was chosen */ WindowPrintf(pw, "You have selected %s", PopupGetEntryString(p,which)); WindowWriteCenterString(pw, "Press a key to continue", 4); /* Display the window with all the info */ WindowDisplay(pw, 1, NOEFFECT); GET_MPRESS_KEY(&dummy); /* Hide the info window */ WindowHide(pw, NOEFFECT); /* Keep getting popup selections */ return POPUP_CONTINUE; } /* routine called when bar menu function is selected */ int rt2(BAR_MENU_PTR b, int which) { WindowClear(pw); /* Display the entry name that was chosen */ WindowPrintf(pw, "You have selected %s", BarGetEntryString(b, which)); Page 244 The C Window Library Page 244 WindowWriteCenterString(pw, "Press a key to continue", 4); WindowDisplay(pw, 1, NOEFFECT); GET_MPRESS_KEY(&which); /* Hide window */ WindowHide(pw, NOEFFECT); /* Keep getting selections */ return BAR_CONTINUE; } The GET_MPRESS_KEY() macro waits for a key to be struck, or a mouse button on the mouse to be pressed. It may be advantageous to always create a pulldown menu instead of just a bar menu since pulldowns are more flexible in that popups can be added underneath, and the pulldown menu inherits all of the properties of a bar menu, i.e. you can call bar menu functions on the pulldown menu by specifying the bar menu portion of the pulldown menu. Key definitions for pulldown menus ---------------------------------- In the POPUP MENU section, there were three key definitions that pertain to pulldown menus: Action Key Constant ┌───────────────────────────┬──────────┬──────────────────────┐ │Move To Next Popup Menu │Rt. Arrow │POPUP_RIGHTKEY │ ├───────────────────────────┼──────────┼──────────────────────┤ │Move to Previous Popup Menu│Left Arrow│POPUP_LEFTKEY │ ├───────────────────────────┼──────────┼──────────────────────┤ │Escape Pulldown Menu │Unassigned│POPUP_PULLDOWN_QUITKEY│ └───────────────────────────┴──────────┴──────────────────────┘ By default, the right arrow key moves to the next popup menu defined on the bar menu. If the next bar entry does not have a popup menu defined, the bar entry is highlighted instead. The left arrow key moves to the previous popup menu defined on the bar menu. POPUP_PULLDOWN_QUITKEY constant closes the pulldown menu. These definitions can be assigned to each popup menu in the pulldown menu system by using the PulldownGetPopup() function combined with PopupSetKeys() function i.e. PopupSetKeys(PulldownGetPopup(pull,0),keys) where pull is the PULLDOWN_MENU_PTR, 0 is the desired popup, and keys is an array of popup menu keys. You can also change the key definitions by setting values in the CWLglobal_popup array. Page 245 The C Window Library Page 245 Page 246 The C Window Library Page 246 MISCELLANEOUS FUNCTIONS ----------------------- There are other functions in The C Window Library that you can use without defining windows. These functions include writing strings directly to the display, dynamically changing the number of displayable rows and columns on the screen, timed delays, sound functions, and other video related functions. Page 247 The C Window Library Page 247 SETTING AND CHECKING VIDEO PAGES -------------------------------- The following functions sets and checks video pages. Your video setup must support multiple video pages for the examples given in this section to work. Please refer to page 5 for a discussion of video adapters and the number of pages each will support. CheckVideoPage() ---------------- This function checks to see if the video page is valid. Here is the prototype: int CheckVideoPage(int page) If page is valid, CheckVideoPage() returns NO_ERROR. If it is not, the return value is INVALID_PAGE. Example: #include "cwlwin.h" main() { int i; WindowInitializeSystem(); for (i=0;i<8;i++) { if (CheckVideoPage(i) == NO_ERROR) printf("\nValid video page #%d",i); else printf("\nInvalid video page #%d",i); } } SetActiveVideoPage() function ----------------------------- The SetActiveVideoPage() function sets the active video page. Here is a prototype: int SetActiveVideoPage(int page) Any windows initialized with WindowInitialize() will have its output directed to the current active video page on initialization. This function DOES NOT change the visible display page. Page 248 The C Window Library Page 248 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w1, w2; main() { WindowInitializeSystem(); /* Save Base Screen for video pages 0 and 1 */ WindowInitDesktop(0); WindowInitDesktop(1); /* Set the active video page */ SetActiveVideoPage(0); w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,10,10, NORM,NORM,SINGLEBOX); SetActiveVideoPage(1); w2 = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,10,10, NORM,NORM,SINGLEBOX); } The above example shows two windows, w1 and w2, being open on different video pages. Please note the two calls to WindowInitDesktop(). The first saves the base screen on video page 0, and the second call saves the initial screen on page 1. The first call to SetActiveVideoPage() sets the active video page to page 0. This is usually the active video page on startup. Since the active page is 0, w1 is opened with page 0 as its video page. The second call to SetActiveVideoPage() makes page 1 the active page, therefore w2 is initialized to send its output to video page 1. Return Values for SetActiveVideoPage(): Return Value Definition ┌──────────────┬───────────────────────┐ │NO_ERROR │ No error occured. │ ├──────────────┼───────────────────────┤ │INVALID_PAGE │ Video Page is invalid.│ └──────────────┴───────────────────────┘ SetVisibleVideoPage() function ------------------------------ The SetVisibleVideoPage() function sets the visible video page. Here is a prototype: int SetVisibleVideoPage(int page) The visible video page is the page displayed on the screen. Page 249 The C Window Library Page 249 Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w1,w2; main() { WindowInitializeSystem(); /* Make sure video page is 0 */ SetVisibleVideoPage(0); SetActiveVideoPage(0); /*Save Base screen for video pages 0 and 1 */ WindowInitDesktop(0); WindowInitDesktop(1); /* Initialize Windows */ w1 = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); SetActiveVideoPage(1); w2 = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); WindowWriteString(w1,"This is window 1 on page 0",0,0); WindowWriteString(w2,"This is window 2 on page 1",0,0); /* Display video page 0 */ WindowDisplay(w1,1,NOEFFECT); GET_KEY(); /* Change to video page 1 and display */ SetVisibleVideoPage(1); WindowDisplay(w2,1,NOEFFECT); GET_KEY(); /* Reset to page 0 */ SetVisibleVideoPage(0); } The example above initializes two windows. w1 is initialized on page 0 and w2 is initialized on page 1. Also note that there are two calls to WindowInitDesktop(), one for page 0 and another for page 1. The first window displayed is w1. Once a key is pressed the visible page is switched to page 1 by calling SetVisibleVideoPage(). The last line of the program sets the visible page back to page 0. You should do this on exit of any program that changes video pages. Return Values for SetVisibleVideoPage(): Return Value Definition ┌──────────────┬───────────────────────┐ │NO_ERROR │ No error occured. │ ├──────────────┼───────────────────────┤ │INVALID_PAGE │ Video Page is invalid.│ └──────────────┴───────────────────────┘ Page 250 The C Window Library Page 250 GENERAL STRING WRITING FUNCTIONS -------------------------------- The following functions write strings to the active video page. These functions are not window functions, therefore you should use these functions when you are not using windows created with The C Window Library unless you are careful in using them. The advantage of using these functions instead of the normal string writing functions found in most C compiler libraries (i.e. printf(), puts(), etc.) is that the output is written directly to screen memory, which results in fast output. If the BIOS option is selected, BIOS functions are used to write the strings. Refer to page 4 for a discussion of direct screen writing and BIOS functions. VideoWriteString() ------------------ This function writes a null terminated string to the active video page. Here is the prototype: void VideoWriteString(char *string, int row, int col) The first argument is the string, and the second and third arguments are the (row,col) position of the active video page to place the string. There is no check to see if (row,col) is out of bounds. The attribute that is used is determined by the current video attribute at each character position on the screen. Example: #include "cwlwin.h" main() { int i; WindowInitializeSystem(); for (i=0;i<10;i++) VideoWriteString("Hello, World",i,0); } There is no return value for VideoWriteString(). Page 251 The C Window Library Page 251 VideoWriteStringAttr() ---------------------- This function writes a null terminated string to the active video page using a video attribute. Here is the prototype: void VideoWriteStringAttr(char *string, int row, int col, int attr) The first argument is the string, the second and third arguments are the (row,col) position of the active video page to place the string, and the last argument is the video attribute to use. There is no check to see if (row,col) is out of bounds. The last argument is the video attribute to use. Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) main() { int i; WindowInitializeSystem(); for (i=0;i<10;i++) VideoWriteStringAttr("Hello, World",i,0,REVERSE); } There is no return value for VideoWriteStringAttr(). VideoWriteAttributes() ---------------------- This function writes a string of attributes to the active video page. Here is the prototype: void VideoWriteAttributes(char *buffer, int row, int col, int num) The first argument is the buffer that contains the video attributes. The second and third arguments are the (row,col) position of the active video page to place the attributes, and the last arguments is the number of attributes to write from the buffer. There is no check to see if (row,col) is out of bounds, or if num attributes will exceed the right edge of the screen. Page 252 The C Window Library Page 252 Example: #include "cwlwin.h" #include <string.h> #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) char buf[12]; main() { WindowInitializeSystem(); VideoWriteString("Hello, World",0,0); GET_KEY(); memset(buf,REVERSE,sizeof(buf)); VideoWriteAttributes(buf,0,0,sizeof(buf)); } The example above writes a string using the VideoWriteString() function and then changes the attribute of the string by setting a buffer to the REVERSE attribute and using the VideoWriteAttributes() function with this buffer. There is no return value for VideoWriteAttributes(). VideoWriteCenterString() ------------------------ The VideoWriteCenterString() function centers a string at a certain row of the active video page. Here is the prototype: void VideoWriteCenterString(char *string, int row) The first argument is the string and the second argument is the row to write on the active video page to write the string. There is no check to see if row is out of bounds. Example: #include "cwlwin.h" main() { int i; WindowInitializeSystem(); for (i=0;i<10;i++) VideoWriteCenterString("Hello, World",i); } There is no return value for VideoWriteCenterString(). Page 253 The C Window Library Page 253 VideoWriteCenterStringAttr() ---------------------------- The VideoWriteCenterStringAttr() function centers a string at a certain row of the active video page with a specified video attribute. Here is the prototype: void VideoWriteCenterStringAttr(char *string, int row, int attr) The first argument is the string and the second argument is the row to write on the active video page to write the string. The third argument is the video attribute to use. There is no check to see if row is out of bounds. Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) main() { int i; WindowInitializeSystem(); for (i=0;i<10;i++) VideoWriteCenterStringAttr("Hello, World",i,REVERSE); } There is no return value for VideoWriteCenterStringAttr(). VideoWriteCharAndAttr() ----------------------- The VideoWriteCharAndAttr() function writes a string of character-attribute pairs to the active video page. Here is the prototype: void VideoWriteCharAndAttr(char *buffer, int row, int col, int num) The first argument is the buffer that holds the character attribute pairs. This buffer should be in the following form: ┌──────┬───────┬───────┬───────┬───────┬──────┐ │char1 │ attr1 │ char2 │ attr2 │ char3 │ attr3│ ... └──────┴───────┴───────┴───────┴───────┴──────┘ The second and third arguments are the (row,col) position of the active video page to write the string. The last argument is the number of character-attribute pairs to write. Page 254 The C Window Library Page 254 Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) char buf[24]; main() { int i,j; WindowInitializeSystem(); for (i=0,j='A'; i<24; i+=2,j++) { buf[i] = j; buf[i+1] = REVERSE; } for (i=0;i<10;i++) VideoWriteCharAndAttr(buf,i,012); } The example above creates a string of character attribute pairs and then writes this string using the VideoWriteCharAndAttr() function. There is no return value for VideoWriteCharAndAttr(). VideoWriteStringCC() -------------------- This function writes a string centered around a column on the active video page. Here is the prototype: void VideoWriteStringCC(char *string, int row, int col) The first argument is the string. The second argument is the row, and the third argument is the column to center the string around. Example: #include "cwlwin.h" main() { int i; WindowInitializeSystem(); VideoWriteStringCC("This",0,10); VideoWriteStringCC("is",1,10); VideoWriteStringCC("centered",2,10); VideoWriteStringCC("around",3,10); VideoWriteStringCC("column",4,10); VideoWriteStringCC("10",5,10); } There is no return value for VideoWriteStringCC(). Page 255 The C Window Library Page 255 VideoWriteStringCCAttr() ------------------------ This function writes a string centered around a column on the active video page with a specified video attribute. Here is the prototype: void VideoWriteStringCCAttr(char *string, int row, int col, int attr) The first argument is the string. The second argument is the row. The third argument is the column to center the string around, and the fourth argument is the attribute to use. Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) main() { int i; WindowInitializeSystem(); VideoWriteStringCCAttr("This",0,10,REVERSE); VideoWriteStringCCAttr("is",1,10,REVERSE); VideoWriteStringCCAttr("centered",2,10,REVERSE); VideoWriteStringCCAttr("around",3,10,REVERSE); VideoWriteStringCCAttr("column",4,10,REVERSE); VideoWriteStringCCAttr("10",5,10,REVERSE); } There is no return value for VideoWriteStringCCAttr(). VideoWriteStringRJ() -------------------- The VideoWriteStringRJ() function writes a string to the screen that is right justified at column col. If the string will not fit within column 0, the string is still right justified, but excess characters to the left of column 1 are clipped. This function writes a string column on the active video page. Here is the prototype: void VideoWriteStringRJ(char *string, int row, int col) The first argument is the string. The second argument is the row, and the third argument is the column to right justify the string on. Page 256 The C Window Library Page 256 Example: #include "cwlwin.h" main() { int i; WindowInitializeSystem(); VideoWriteStringRJ("This",0,10); VideoWriteStringRJ("is",1,10); VideoWriteStringRJ("right",2,10); VideoWriteStringRJ("justified",3,10); VideoWriteStringRJ("on ",4,10); VideoWriteStringRJ("column",5,10); VideoWriteStringRJ("10",6,10); } There is no return value for VideoWriteStringRJ(). VideoWriteStringRJAttr() ------------------------ The VideoWriteStringRJAttr() function writes a string to the screen that is right justified at column col with a specified video attribute. If the string will not fit within column 1, the string is still right justified, but excess characters to the left of column 0 are clipped. This function writes a string column on the active video page. Here is the prototype: void VideoWriteStringRJAttr(char *string, int row, int col, int attr) The first argument is the string. The second argument is the row. The third argument is the column to right justify the string on, and the last argument is the video attribute to use. Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) main() { int i; WindowInitializeSystem(); VideoWriteStringRJAttr("This",0,10,REVERSE); VideoWriteStringRJAttr("is",1,10,REVERSE); VideoWriteStringRJAttr("right",2,10,REVERSE); VideoWriteStringRJAttr("justified",3,10,REVERSE); VideoWriteStringRJAttr("on ",4,10,REVERSE); VideoWriteStringRJAttr("column",5,10,REVERSE); VideoWriteStringRJAttr("10",6,10,REVERSE); } There is no return value for VideoWriteStringRJAttr(). Page 257 The C Window Library Page 257 VideoPrintf() ------------- The VideoPrintf() function writes formatted strings to the active video page. This function works exactly the same as printf() except that output is written directly to the screen. Here is the prototype: void VideoPrintf(char *format [,arg1,arg2...]) The location of the output is placed at the current cursor position. The cursor is advanced to one character beyond the last character of output. Example: #include "cwlwin.h" int i = 3; double j = 5.6; main() { WindowInitializeSystem(); VideoPrintf("3+2 is equal to %d\n",3+2); VideoPrintf("i is equal to %d\nj is equal to %lf\n",i,j); } Unlike printf(), there is no return value with VideoPrintf(). VideoPrintfAttr() ----------------- The VideoPrintfAttr() function works the same as VideoPrintf() except that a video attribute is specified. Here is the prototype: void VideoPrintfAttr(int attr, char *format [,arg1,arg2...]) The first argument is the attribute to use. The second argument is the format string, and the other arguments are optional arguments. Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(WHITE_,BLACK_) int i = 3; double j = 5.6; main() { WindowInitializeSystem(); VideoPrintfAttr(REVERSE,"3+2 is equal to %d\n",3+2); VideoPrintfAttr(REVERSE, "i is equal to %d\nj is equal to %lf\n",i,j); } Page 258 The C Window Library Page 258 Unlike printf(), there is no return value with VideoPrintfAttr(). Page 259 The C Window Library Page 259 READING CHARACTERS AND ATTRIBUTES FROM THE SCREEN ------------------------------------------------- These functions read characters and/or attributes from the active video page. VideoReadCharacters() --------------------- This function reads characters from the active video page into a buffer. Here is the prototype: void VideoReadCharacters(char *buffer, int row, int col, int num) The first argument is the buffer to store the characters. The second and third arguments are the (row,col) position on the active video page. The last argument is the number of characters to read in. There is no check to see if the row, col, or the num arguments are in bounds of the screen. Example: #include "cwlwin.h" char buf[25]; main() { WindowInitializeSystem(); VideoReadCharacters(buf,0,0,25); } The example above reads the characters on the screen starting at position (0,0). There is no return value for VideoReadCharacters(). VideoReadAttributes() --------------------- This function reads attributes from the active video page into a buffer. Here is the prototype: void VideoReadAttributes(char *buffer, int row, int col, int num) Page 260 The C Window Library Page 260 The first argument is the buffer to store the attributes. The second and third arguments are the (row,col) position on the active video page. The last argument is the number of attributes to read in. There is no check to see if the row, col, or the num arguments are in bounds of the screen. Example: #include "cwlwin.h" char buf[25]; main() { WindowInitializeSystem(); VideoReadAttributes(buf,0,0,25); } The example above reads the attributes on the screen starting at position (0,0). There is no return value for VideoReadAttributes(). VideoReadCharAndAttr() ---------------------- This function reads character-attribute pairs from the active video page into a buffer. Here is the prototype: void VideoReadCharAndAttr(char *buffer, int row, int col, int num) The first argument is the buffer to store the character-attribute pairs. The second and third arguments are the (row,col) position on the active video page. The last argument is the number of character-attribute pairs to read in. There is no check to see if the row, col, or the num arguments are in bounds of the screen. Example: #include "cwlwin.h" char buf[26]; main() { WindowInitializeSystem(); VideoReadCharAndAttr(buf,0,0,13); } The example above reads the character-attribute pairs on the screen starting at position (0,0). There is no return value for VideoReadCharAndAttr(). Page 261 The C Window Library Page 261 DRAWING BOXES ------------- The following functions draw boxes on the screen. VideoDrawBox() -------------- The VideoDrawBox() function draws a box on the screen. Here is the prototype: void VideoDrawBox(int urow, int ucol, int lrow, int lcol, char *boxchars) The box is defined by a rectangular region. The urow and ucol arguments are the coordinates of the upper left hand corner of the box. The lrow and lcol arguments are the coordinates of the lower right hand corner of the box. The last argument is a string of box drawing characters to use. You can use the predefined box types in the header file cwlwin.h, or you can make your own. Refer to page 11 for more information on box types. There is no check to see if the coordinates are in bounds. Example: #include "cwlwin.h" main() { WindowInitializeSystem(); ClearScreen(CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); /* Draw two boxes */ VideoDrawBox(1,1,10,10,SINGLEBOX); VideoDrawBox(1,11,10,21,DOUBLEBOX); } There is no return value for VideoDrawBox(). VideoDrawBoxAttr() ------------------ The VideoDrawBoxAttr() function draws a box on the screen with a specified video attribute. Here is the prototype: void VideoDrawBoxAttr(int urow, int ucol, int lrow, int lcol, char *boxchars, int attr) This function works the same way as the VideoDrawBox() function. Note that the last argument is the video attribute to use. There is no check to see if the coordinates are in bounds. Page 262 The C Window Library Page 262 Example: #include "cwlwin.h" #define REVERSE CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) main() { WindowInitializeSystem(); ClearScreen(CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); /* Draw two boxes */ VideoDrawBoxAttr(1,1,10,10,SINGLEBOX,REVERSE); VideoDrawBoxAttr(1,11,10,21,DOUBLEBOX,REVERSE); } There is no return value for VideoDrawBoxAttr(). Page 263 The C Window Library Page 263 SAVING AND RESTORING SCREEN IMAGES ---------------------------------- The following functions save rectangular regions of the screen in a buffer, and restore rectangular portions of the screen. These routines exist in The C Window Library so that advanced C programmers can have general screen saving/restoring routines handy. As always, you should be careful in using these functions at the same time you are using windows created with The C Window Library. VideoSave() ----------- The VideoSave() function saves a rectangular portion of the screen into a structure called a VBLOCK. A pointer to this structure is called a VBLOCKPTR. Here is the prototype: VBLOCKPTR VideoSave(int urow, int ucol, int lrow, int lcol) This function returns a VBLOCKPTR. The VBLOCKPTR will be used to move or restore this saved region. The first two arguments are the coordinates of the upper left hand corner of the rectangle to save (urow,ucol). The last two arguments are the coordinates of the lower right hand corner of the rectangle (lrow,lcol). There is no check to see if the coordinates are out of bounds. You can use this function to save the base screen, and then use VideoRestore() to restore the base screen on exit. Example: #include "cwlwin.h" VBLOCKPTR v; main() { WindowInitializeSystem(); v = VideoSave(0,0,24,79); /* Save Rectangular region */ /* Check if NULL */ if (v == (VBLOCKPTR)0) VideoWriteString("Trouble saving video"); } If there are no errors, VideoSave() returns a valid VBLOCKPTR. If there are errors VideoSave() returns a null VBLOCKPTR and sets the global integer CWLerror_code to the following value: NO_HEAP_MEM if there is not enough memory for the save buffer of the VBLOCKPTR. Page 264 The C Window Library Page 264 VideoMove() ----------- The VideoMove() function moves a region saved by VideoSave() to a different location of the screen. This location will be the new upper left hand corner of the rectangular region that was saved. The move is not displayed until you call VideoRestore(), which is defined later. Here is the prototype: void VideoMove(VBLOCKPTR v, int row, int col) The first argument is the VBLOCKPTR. The second and third arguments are the new upper left hand position of the saved area. There is NO check to see if the VBLOCKPTR exists, or the row or column are valid. Example: #include "cwlwin.h" VBLOCKPTR v; main() { WindowInitializeSystem(); v = VideoSave(0,0,9,9); /* Save Rectangular region defined by (0,0) (9,9) */ VideoMove(v,0,9); } There is no return value for VideoMove(). VideoRestore() -------------- The VideoRestore() function takes a rectangular area of the screen saved with VideoSave() and redisplays the area. Here is the prototype: void VideoRestore(VBLOCKPTR v) The only argument is the VBLOCKPTR. There is no check to see if the VBLOCKPTR is valid. Example: #include "cwlwin.h" VBLOCKPTR v; Page 265 The C Window Library Page 265 main() { WindowInitializeSystem(); v = VideoSave(0,0,9,9); for (i=0;i<10;i++) VideoWriteString("This is the save area. " "Press a key to restore.",i,0); GET_KEY(); VideoRestore(v); } There is no return value for VideoRestore(). VideoFree() ----------- The VideoFree() function frees a previously defined VBLOCKPTR. Here is the prototype: void VideoFree(VBLOCKPTR v) The only argument is the VBLOCKPTR. There is NO check to see if the VBLOCKPTR is valid, therefore you must be very careful to call this function on a valid VBLOCKPTR. If not, the heap will become corrupted. Example: #include "cwlwin.h" VBLOCKPTR v; main() { WindowInitializeSystem(); v = VideoSave(0,0,9,9); for (i=0;i<10;i++) VideoWriteString("This is the save area. " "Press a key to restore.",i,0); GET_KEY(); VideoRestore(v); VideoFree(v); } There is no return value for VideoFree(). Page 266 The C Window Library Page 266 CLEARING SCREENS ---------------- The following functions clears the visible video page, and clears regions of the visible screen. ClearScreen() ------------- The ClearScreen() function clears the visible video page with a specified attribute and moves the screen cursor to position (0,0). Here is the prototype: void ClearScreen(int attr) The only argument is the video attribute to use. Example: #include "cwlwin.h" main() { WindowInitializeSystem(); /* Clear the entire screen */ ClearScreen(CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); } There is no return value for ClearScreen(). ClearRegion() ------------- This function clears a rectangular region of the screen. Here is the prototype: void ClearRegion(int urow, int ucol, int lrow, int lcol, int attr) The first two arguments represent the coordinate of the upper left hand coordinates of the rectangular region to clear. The third and fourth arguments represent the coordinate of the lower right hand corner of the rectangular region. The last argument is the attribute to use. There is no check to see if the coordinates are in bounds. Page 267 The C Window Library Page 267 Example: #include "cwlwin.h" main() { WindowInitializeSystem(); /* Clear Region defined by (0,0) as the upper right hand corner and (9,9) as the lower right hand corner */ ClearRegion(0,0,9,9,CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); } There is no return value for ClearRegion(). Page 268 The C Window Library Page 268 SCROLLING SCREENS ----------------- These functions scroll portions of the screen up or down. ScrollScreenUp() ---------------- The ScrollScreenUp() function scrolls a rectangular portion of the screen up a specified number of lines. Here is the prototype: void ScrollScreenUp(int numlines, int urow, int ucol, int lrow, int lcol, int attr) The first argument is the number of lines to scroll the region. The second and third arguments are the (row,col) coordinates of the upper left hand corner of the rectangular region to scroll. The fourth and fifth arguments are the (row,col) of the lower right hand corner of the rectangular region. The last argument is the attribute to use for blank lines created when the region is scrolled. Example: #include "cwlwin.h" main() { WindowInitializeSystem(); ScrollScreenUp(1,0,2,4,9, CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); } There is no return value for ScrollScreenUp(). ScrollScreenDown() ------------------ The ScrollScreenDown() function scrolls a rectangular portion of the screen down a specified number of lines. Here is the prototype: void ScrollScreenDown(int numlines, int urow, int ucol, int lrow, int lcol, int attr) The first argument is the number of lines to scroll the region. The second and third arguments are the (row,col) coordinates of the upper left hand corner of the rectangular region to scroll. The fourth and fifth arguments are the Page 269 The C Window Library Page 269 (row,col) of the lower right hand corner of the rectangular region. The last argument is the attribute to use for blank lines created when the region is scrolled. Example: #include "cwlwin.h" main() { WindowInitializeSystem(); ScrollScreenDown(1,0,2,4,9, CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); } There is no return value for ScrollScreenDown(). Page 270 The C Window Library Page 270 CHANGING THE VIDEO MODE ----------------------- With The C Window Library, you can change the video mode at any time. The video mode determines the width of the screen, and whether the screen is in text or graphics mode. SetVideoMode() -------------- The SetVideoMode() function changes the video mode. Here is a prototype: void SetVideoMode(int modenum) The only argument is the mode number. Refer to the Video Paging section on page 5 for more information on mode numbers and what they display. When the video mode is changed, the screen is cleared. This cannot be prevented. You must redisplay any windows that were on the screen. If the change of video mode results in a change in screen dimensions, then you must read the following sections on CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN. Even though The C Window Library does not support graphics mode, you can change to graphics mode in The C Window Library, Example: #include "cwlwin.h" main() { WindowInitializeSystem(); SetVideoMode(3); /* Change to video mode 3 */ } There is no return value for SetVideoMode(). Page 271 The C Window Library Page 271 CHANGING THE NUMBER OF ROWS AND COLUMNS ON THE SCREEN ----------------------------------------------------- Changing rows ------------- With The C Window Library, you can change the number of rows on the video screen. However, there are some things to watch out for when changing the number of rows, especially if you have windows displayed on the screen. If you are not using any window related functions, you can change the number of displayable rows safely by doing two things: a) Call the SetVideoRows() function to change the number of rows. b) Call AdjustGlobalData() to adjust the global variables used by The C Window Library that keep track of the screen dimensions. If you are going to create or have created windows you should do the following: a) Call the SetVideoRows() function. b) Call the AdjustScreenInfo() function. This function adjusts all global variables defined in The C Window Library to reflect the new number of rows. Whether there are or are not windows defined, the visible video page MUST be page 0 before changing the number of screen rows. AdjustScreenInfo() ------------------ This function must be called after SetVideoRows() is called if you are going to, or have initialized and/or displayed windows. Here is the prototype: int AdjustScreenInfo(int page) The only argument is the video page to adjust to the new screen height. Because of the new dimension of the screen, there has to be a reshuffling of a few global arrays, constants, variables, etc. The AdjustScreenInfo() function does just this. If you do not call AdjustScreenInfo(), you may see problems if you try to manipulate windows on the new screen. Page 272 The C Window Library Page 272 See SetVideoRows() for an example of AdjustScreenInfo(). Return Values for AdjustScreenInfo(): Return Value Definition ┌─────────────┬────────────────────────────────┐ │NO_ERROR │ No error occured. │ ├─────────────┼────────────────────────────────┤ │NO_HEAP_MEM │ Not enough memory to allocate. │ └─────────────┴────────────────────────────────┘ AdjustGlobalData() ------------------ The AdjustGlobalData() function should be called after you have changed the number of video rows using SetVideoRows() (defined below). This resets the global variables necessary for non-window functions to execute properly. Here is the prototype: void AdjustGlobalData(void) There are no arguments and no return value for AdjustGlobalData(). If you have called AdjustScreenInfo(), you do not have to call AdjustGlobalData(). See below for an example of AdjustGlobalData(). SetVideoRows() -------------- The SetVideoRows() function changes the number of video rows on the screen. Here is a list of video adapters and there row number capabilities: Video Type Number of Rows Possible ---------- -------------- CGA, MDA, Hercules 25 EGA 25, 43 MCGA 25, 50 VGA 12, 14, 21, 25, 28, 43, 50 or more Page 273 The C Window Library Page 273 The list above are the values SetVideoRows() uses, depending on the adapter that The C Window Library has detected. If your video card supports a row configuration that is not supported by the SetVideoRows() function, consult the 'Changing columns' section and proceed as if you are changing the number of columns. Here is the prototype for SetVideoRows(): int SetVideoRows(int numrows, int modeflag) The first argument is the number of screen rows. The modeflag tells whether the video mode should be reset. If modeflag is 0, the video mode is not reset. Any other value for modeflag will cause a video mode reset. This reset may or may not be necessary, so experiment with both values for modeflag. Example: #include "cwlwin.h" main() { WindowInitializeSystem(); ClearScreen(CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); VideoWriteString( "Press a key to change to a new video mode",0,0); GET_KEY(); if (VGA_MODE_ON || MCGA_MODE_ON) SetVideoRows(50,0); else if (EGA_MODE_ON) SetVideoRows(43,0); else { VideoWriteString( "Hardware does not support changing video rows",1,0); exit(0); } AdjustGlobalData(); VideoWriteString( "Press a key again to change to 25 lines",1,0); GET_KEY(); SetVideoRows(25,0); AdjustGlobalData(); } The example above uses the constants VGA_MODE_ON, MCGA_MODE_ON, and EGA_MODE_ON. These constants are discussed in the VIDEO MACROS section. Page 274 The C Window Library Page 274 Here is another example, but now we have a window on the screen. Example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30, 10,NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Press a key to change rows",0,0); GET_KEY(); if (VGA_MODE_ON || MCGA_MODE_ON) SetVideoRows(50,0); else if (EGA_MODE_ON) SetVideoRows(43,0); else { WindowWriteString(w,"Cannot change rows",0,0); exit(0); } /* Adjust the screen information */ AdjustScreenInfo(0); /* OK to adjust to new height */ WindowResizeHeight(w,40,ANCHORTOP); WindowWriteString(w,"Now press a key to change back",1,0); GET_KEY(); /* First we must resize window */ WindowResizeHeight(w,10,ANCHORTOP); SetVideoRows(25,0); AdjustScreenInfo(0); } Note the use of AdjustScreenInfo() after a reset is made. Return Values for SetVideoRows(); Return Value Definition ┌───────────────────┬────────────────────────────────┐ │NO_ERROR │ No error occured. │ ├───────────────────┼────────────────────────────────┤ │INVALID_ROWS │ number of rows not supported. │ └───────────────────┴────────────────────────────────┘ Page 275 The C Window Library Page 275 Changing columns ---------------- The number of columns can be changed, but there are two things to watch out for. First, to change from 40 column mode to 80 column mode or vice-versa, is a matter of changing the video mode. Changing the video mode from 40 to 80 column mode or from 80 to 40 requires a BIOS function that is present on all systems that support 40 column mode. 40 column and 80 column modes ----------------------------- To change to 40 column mode do the following: SetVideoMode(0); /* this changes to 40 column Black and White mode */ or SetVideoMode(1); /* this changes to 40 column color mode */ The example above only works if you have a CGA, EGA, MCGA, or VGA card. To change to 80 column mode do the following: SetVideoMode(2); /* this changes to Black and White 80 column mode */ or SetVideoMode(3); /* use this for color 80 column mode */ or SetVideoMode(7); /* use this for mono cards */ SetVideoMode(7) works for all adapters, while SetVideoMode(2) and SetVideoMode(3) works only for CGA, EGA, MCGA, or VGA cards. Modes higher than 80 columns ---------------------------- There are video systems that support video modes greater than 80 columns. The problem is that for each different brand of video adapter, there is a unique way of changing to a higher column mode. Most of these adapters support an additional BIOS function that must be called to change to any screen Page 276 The C Window Library Page 276 column mode higher than 80. Therefore, it is up to you (the programmer) to find out how to change the video system from 80 columns to a higher column mode. Once you are familiar with how to do this, changing the number of columns is almost the same as changing the number of rows. If you are using any window related functions, you can change the number of displayable columns safely by doing two things: a) Call the appropriate routine to change the number of columns. If this is a call to SetVideoMode(), the screen will be cleared. b) Call AdjustScreenInfo() to adjust the global variables used by The C Window Library that keep track of the screen dimensions. If you are not using any windows in your application, replace the call to AdjustScreenInfo() in step b) with a call to AdjustGlobalData(). This example works for the ATI VGA card. This changes the mode to 132 columns: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) WPOINTER w; main() { WindowInitializeSystem(); WindowInitDesktop(0); w = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,30,10, NORM,NORM,SINGLEBOX); WindowDisplay(w,1,NOEFFECT); WindowWriteString(w,"Press a key to change columns",0,0); GET_KEY(); /* Set Video Mode to 132 columns x 25 rows (Works for ATI VGA card) */ SetVideoMode(0x23); /* Adjust the screen information and redisplay window */ AdjustScreenInfo(0); WindowDisplay(w,1,NOEFFECT); /* OK to adjust to new height */ WindowResizeWidth(w,100,ANCHORLEFT); WindowWriteString(w,"Now press a key to change back",1,0); GET_KEY(); /* First we must resize window */ WindowResizeWidth(w,30,ANCHORLEFT); Page 277 The C Window Library Page 277 /* Set back to 80 column mode */ SetVideoMode(3); AdjustScreenInfo(0); WindowDisplay(w,1,NOEFFECT); } Page 278 The C Window Library Page 278 CURSOR MANIPULATION ------------------- The functions defined in this section manipulate the cursor. The following functions can be called without calling WindowInitializeSystem(). MoveCursor() ------------ This function moves the cursor to a different location. Here is the prototype: void MoveCursor(int row, int col, int page) The first two arguments are the row and column positions of where to move the cursor. The last argument is the video page of the cursor you want to move. Example: #include "cwlwin.h" main() { MoveCursor(0,4,0); /* Move cursor to row 0 column 4 on video page 0 */ } There is no return value for MoveCursor(). ChangeCursor() -------------- The ChangeCursor() function changes the shape of the cursor. The shape of the cursor is determined by its starting and ending scan lines. Here is a prototype: void ChangeCursor(unsigned startline, unsigned endline) The first argument is the starting scan line and the second argument is the ending scan line. For monochrome systems, there are 12 scan lines numbered 0 thru 11, while on color systems there are 8 scan lines numbered 0 thru 7. The starting scan line is the top line of the cursor, and the ending scan line is the last line of the cursor. There is no check to see if the starting scan line and the ending scan lines are valid. Page 279 The C Window Library Page 279 Example: #include "cwlwin.h" main() { WindowInitializeSystem(); ChangeCursor(6,7); /* This is an underline cursor */ GET_KEY(); ChangeCursor(0,7); /* This is a thick cursor */ } There is no return for ChangeCursor(). GetCursorShape() ---------------- This function returns the shape of the cursor in scan lines. Here is the prototype: void GetCursorShape(unsigned *startline, unsigned *endline) When this function returns, the staring scan line is placed in the integer pointed to by scanline, and the ending scan line is placed in the integer pointed to by endline. Example: #include "cwlwin.h" main() { int start, end; WindowInitializeSystem(); GetCursorShape(&start, &end); VideoPrintf("\nThe starting scan line is %d\n" "The ending scan line is %d", start,end); } There is no return value for GetCursorShape(). GetCursorPosition() ------------------- This function gets the current cursor position. Here is the prototype: void GetCursorPosition(int *row, int *col, int page) The first argument is a pointer to an integer that will be set to the current row. The second argument is a pointer to an integer that will be set to the current column. The last argument is the video page of the cursor. Page 280 The C Window Library Page 280 Example: #include "cwlwin.h" main() { int row,col; MoveCursor(10,15); GetCursorPosition(&row,&col,0); WindowInitializeSystem(); VideoPrintf("\nThe row of the cursor is %d\n" "The column is %d", row,col); } There is no return value for GetCursorPosition(). The following functions serve as shortcuts in changing the cursor shape. HideCursor() ------------ Hides the cursor on the screen. Here is the prototype: void HideCursor(void) BlockCursor() ------------- Displays the cursor as a thick block. void BlockCursor(void) ThinCursor() ------------ Displays the cursor as an underline cursor. void ThinCursor(void) Example: #include "cwlwin.h" main() { WindowInitializeSystem(); MoveCursor(0,0,0); VideoWriterString("Press a key to hide the cursor",0,0); Page 281 The C Window Library Page 281 GET_KEY(); HideCursor(); VideoWriterString( "Press a key to change cursor to a block",1,0); GET_KEY(); BlockCursor(); VideoWriterString( "Press a key to change cursor to a thin cursor",2,0); GET_KEY(); ThinCursor(); } There are no return values for HideCursor(), BlockCursor(), or ThinCursor(). Page 282 The C Window Library Page 282 GETTING VIDEO INFORMATION ------------------------- You can get information about the video configuration by calling the GetVideoBiosInfo() function. VIDEO_CONFIG structure ---------------------- To get information about the video configuration, you must pass a pointer to a VIDEO_CONFIG structure. This structure is defined as follows: typedef struct tagVIDEOSTRUCT { unsigned int video_mode; /* Current video mode */ unsigned int cursor_startline; /* Starting scan line of cursor */ unsigned int cursor_endline; /* Ending scan line of cursor */ unsigned int cursor_row; /* Screen row of cursor */ unsigned int cursor_col; /* Column of cursor */ unsigned int video_page; /* Current visible video page */ unsigned int video_pagesize; /* Size in bytes of the video page */ unsigned int video_rows; /* Number of displayable rows */ unsigned int video_cols; /* Number of displayable columns * / unsigned int char_height; /* Height (in scan lines) of a character */ unsigned int crt_port_address; /* Address of CRT status port */ unsigned int crt_mode_setting; /* Current CRT Mode Setting */ unsigned int crt_color_setting; /* Current CRT color settings */ } VIDEO_CONFIG; GetVideoBiosInfo() ------------------ This function returns information about the current video configuration. Here is the prototype: void GetVideoBiosInfo(VIDEO_CONFIG *v) The only argument is a pointer to a VIDEO_CONFIG structure. This structure is filled in with the appropriate values. Page 283 The C Window Library Page 283 Example: #include "cwlwin.h" VIDEO_CONFIG v; main() { WindowInitializeSystem(); /* Get video information */ ClearScreen(CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_)); GetVideoBiosInfo(&v); VideoPrintf("The video mode is %d\n" "The starting scan line of the cursor is %d\n" "The ending scan line of the cursor is %d \n" "The row of the cursor is %d \n" "The column of the cursor is %d\n" "The video page is %d\n" "The size of the video page is %d\n" "The number of rows is %d\n" "The number of columns is %d\n" "The height of the characters is %d\n", v.video_mode, v.cursor_startline, v.cursor_endline, v.cursor_row,v.cursor_col, v.video_page, v.video_pagesize, v.video_rows, v.video_cols, v.char_height); } There is no return value for GetVideoBiosInfo(). Page 284 The C Window Library Page 284 TIMED DELAYS ------------ One of the problems that has been addressed in The C Window Library is the lack of a delay() function in most C compiler packages. The delay() function delays program execution for a certain number of milliseconds. Borland's Turbo C compiler is one of the few that has a delay() function. The other compilers may have a sleep() function, but usually these functions do not have millisecond accuracy. One of the problems was to write a delay() function that would work for all the major C compilers, work with millisecond accuracy, work for any speed PC, and last but not least, without using floating point arithmetic. This function was written in assembly language for accuracy. The use of the delay() is used extensively in displaying and hiding windows with certain special effects. delay() ------- The delay() function delays the program for a certain number of milliseconds. Here is the prototype: void delay(unsigned millisecs) The only argument is the number of milliseconds to delay. If you are using the Turbo C version of The C Window Library, this function is already included in the Turbo C library. However, if you are using another compiler you now have a delay() function! Example: main() { WindowInitializeSystem(); delay(50); /* Delay for 50 milliseconds */ } You must call WindowInitializeSystem() before using delay(). There is no return value for delay(). Page 285 The C Window Library Page 285 SOUND FUNCTIONS --------------- The C Window Library also supports sound functions for compilers that are lacking these functions. sound() and nosound() --------------------- The sound() function sounds a tone with a specified frequency in Hertz (cycles per second). Here is a prototype: void sound(unsigned frequency) The nosound() function turns off the tone generated by the sound() function. Example: #include "cwlwin.h" main() { unsigned i; WindowInitializeSystem(); for (i=100;i<=1000;i++) sound(i); for(i=1000;i>=100;i--) sound(i); nosound(); } Note for Turbo users: You should include "dos.h" in your files that contain sound() and nosound(). All other compilers should include "cwlwin.h". Note for Power C users: If you are using the Power C compiler, you must include "cwlwin.h" or any file that includes cwlwin.h after bios.h. This is to ensure that the linker does not get confused with the Power C function called sound(), which works differently than the sound() function defined above. MakeSound() ----------- The MakeSound() function sounds a tone for a duration of time. Here is the prototype: void MakeSound(unsigned freq, unsigned millisec) Page 286 The C Window Library Page 286 where freq is the frequency of the tone (in Hertz) and millisec is the number of milliseconds to sound the tone. Example: -------- #include "cwlwin.h" main() { WindowInitializeSystem(); /* Produce a 440 Hertz tone for 3 seconds */ MakeSound(440,3000); } There is no error return for this function. Page 287 The C Window Library Page 287 ERROR HANDLING -------------- Whenever an error has occurred in The C Window Library, a user defined error function can be called. The CWLerror_func function pointer ---------------------------------- The CWLerror_func function pointer can point to an error function that is performed whenever there is an error encountered in one of The C Window Library functions. If the global variable CWLcheck_existence_flag is set to 1 and there is an error, The C Window Library will automatically call CWLerror_func. Here is the prototype: void (*CWLerror_func)(int errcode, char *sourcefile, int sourceline, char *funcname) The errcode is one of the defined error codes included in The C Window Library. Refer to page 6 of the main documentation for more information of the error codes and their definitions. The second argument is the name of the file where the error occurred. Only users with the source code to The C Window Library will have access to this file. The third argument is the offending line in the source file of where the error occurred. The last argument is the name of the function of where the error occurred. By default CWLerror_func points to a void null function (VOIDNULLFN), therefore no error function is called. Here is an example of how to implement automatic error checking: #include "cwlwin.h" #define WHITEONRED CREATE_VIDEO_ATTRIBUTE(RED_,WHITE_) void custom_error_func(int, char *, int, char *); WPOINTER w, error_window; void initialize_error(); main() { WindowInitializeSystem(); WindowInitDesktop(0); CWLerror_func = custom_error_func; /* Assign error function */ initialize_error(); WindowDisplay(w,1,NOEFFECT); /* This line will be flagged for an error */ } void initialize_error() /* Initialize error window and error handler */ Page 288 The C Window Library Page 288 { error_window = WindowInitialize(DESKTOP_WINDOW,BORDER,0,0,60,5, WHITEONRED, WHITEONRED,SINGLEBOX); } void custom_error_func(int errcode, char *sourcefile, int sourceline, char *funcname) { int ch; MakeSound(100,500); /* Produce an error beep */ if (errcode == NO_HEAP_MEM) /* Always check for the heap memory error separately */ { VideoWriteString("You have ran out of Heap Memory",0,0); VideoWriteString( "Press 'Q' to quit program, Any other key to Continue...", 1,0); } else /* Display error window */ { WindowClear(error_window); WindowDisplay(error_window,1,EXPLODE); WindowPrintf(error_window, "Error Code: %d\nSource File: %s\nSource Line %d\n" "Error Occurred in %s", errcode,sourcefile,sourceline,funcname); WindowWriteString(error_window, "Press 'Q' to quit program, Any other key to Continue...", 4,0); } ch = GET_KEY(); if (ch == 'Q' || ch == 'q') exit(0); else if (errcode != NO_HEAP_MEM) WindowHide(error_window,CONTRACT); } The above example initializes an error window and sets the CWLerror_func function pointer to point to the function custom_error_func(). Whenever an error occurs in The C Window Library, custom_error_func() will be called. Please note the check to see if the NO_HEAP_MEM error has occurred. It is important that you check for this error condition separately. The reason for this is that if there is not enough heap memory, you may inadvertently call a function in your error handler that calls on malloc() or any of the other memory allocation related functions. This will Page 289 The C Window Library Page 289 either freeze your system, or more peculiarly, cause your error handler to be called in an infinite loop because of the repeated failing calls to malloc() or its related functions. In the latter case, you will run out of stack space. If you want to unassign the CWLerror_code function pointer, use the following line in your code: CWLerror_func = VOIDNULLFN; Page 290 The C Window Library Page 290 USING A MOUSE WITH THE C WINDOW LIBRARY --------------------------------------- With The C Window Library, you can create applications that use a Microsoft compatible mouse to select from popup, pulldown, and bar menus as well as getting mouse presses. Using the mouse for menus will be discussed in this section, while getting and testing for button presses will be discussed in the KEYBOARD MACROS section below. Installing the Mouse Library ---------------------------- Before using the mouse library, make sure that you read the README file concerning installing the mouse library. Initializing the Mouse with MouseInitializeSystem() --------------------------------------------------- Before you can use a mouse, you must initialize it by calling MouseInitializeSystem(). This function tests for a Microsoft compatible mouse and returns a value denoting whether a mouse is found. Here is the prototype: int MouseInitializeSystem(int intype, int *button, int hpos, int vpos) The first argument informs MouseInitializeSystem() to whether you just want to test to see if a mouse is installed and not to activate the mouse, or to not only test for the mouse, but to activate it. If the first argument is MOUSE_TEST, MouseInitializeSystem() will just return an integer denoting whether a mouse is found. If the first argument is MOUSE_FULL_INSTALL, not only is a status returned, but the mouse will be activated. The second argument is a pointer to an integer that will contain the number of buttons that the mouse has. This number will usually be 2 or 3. The third and fourth arguments are the screen coordinates of where to place the mouse cursor on the screen. The third argument is the row, and the fourth argument is the column to place the mouse cursor. MouseInitializeSystem() returns NOMOUSE if a mouse is not installed, or MOUSEFOUND if a mouse is installed. MouseInitializeSystem() must be called after calling WindowInitializeSystem() for it to work properly. Page 291 The C Window Library Page 291 Turning off the mouse with MouseRestoreSystem() ----------------------------------------------- Before terminating a program that has called MouseInitializeSystem() you should call MouseRestoreSystem(). If you do not call MouseRestoreSystem(), the mouse will still be 'alive', even though the application has terminated. Here is the prototype: int MouseRestoreSystem(void) If the mouse was not initialized previously with MouseInitializeSystem(), MouseRestoreSystem() returns NOMOUSE, otherwise the return value is NO_ERROR. Example: main() { /* initialize mouse */ MouseInitializeSystem(); /* ... */ /* turn off mouse */ MouseRestoreSystem(); } If you want to turn the mouse back on after calling MouseRestoreSystem(), you must call MouseInitializeSystem() again. Example: #include "cwlmouse.h" main() { int button; int ismouse; WindowInitializeSystem(); ismouse = (MouseInitializeSystem(MOUSE_FULL_INSTALL, &button,0,0) == MOUSEFOUND)); MoveCursor(0,0,0); if (ismouse) VideoPrintf( "Mouse was found. Number of buttons is %d\n",button); else VideoPrintf("Mouse not found"); } Page 292 The C Window Library Page 292 Using a mouse with popup menus ------------------------------ Once the mouse is initialized, you can use the mouse to make selections with popup menus. To move the highlight bar with the mouse, position the mouse cursor over any menu entry in the window, and hold the left mouse button down. If the mouse is moved while holding the left button down, the highlight is moved along with the mouse cursor. A selection is made by releasing the left mouse button while the mouse cursor is on an active menu entry. Scroll bars are placed on a popup window when the POPUPMOUSESCROLL option is used in a popup menu. The scroll bars consist of a moveable scroll box, as well as up and down arrows. By default, scroll bars are not drawn on popup windows that have entries that can fit in the popup window. In other words, if your popup window can hold all of your entries without scrolling, no scroll bar is drawn on the window. If you change the size of the popup window, scroll bars are drawn automatically if the entries cannot fit in the window. The popup window's text area must be at least 4 rows tall for the scroll bars to serve any useful purpose. Popup Menu's pre-function for mouse ----------------------------------- When the POPUPMOUSESCROLL option is used for popup menus, the menu can be scrolled automatically by placing the mouse on either the up or down scroll characters on the popup window, and pressing the left mouse button. The normal pre-function for the popup menu, namely the function pointed to by CWLglobal_popup_prefunc, is disabled if you use the mouse to scroll through the entries in the manner described above. If you want to perform a function when the menu bar is moved automatically from choice to choice, you should use the CWLpopup_mouse_func function pointer. Here is the prototype: void (*CWLpopup_mouse_func)(POPUP_MENU_PTR p, unsigned current) p is the current popup menu, and current is the current selection that the highlight bar is on. Note the difference in the second argument. The CWLglobal_popup_prefunc function pointer has a pointer to an integer as the second argument, while the Page 293 The C Window Library Page 293 CWLpopup_mouse_func has an integer as the second argument. Also note that the CWLpopup_mouse_func returns nothing, while the CWLglobal_popup_prefunc returns a value back to the menu manager. If you use the mouse the 'normal' way (pointing the mouse to the actual menu entry and moving the mouse up or down while holding the left mouse button down), the normal pre-function is not disabled. The reason for having the CWLpopup_mouse_func function pointer is that there may be a description displayed for each menu entry, where the displaying of the menu entry is done by the function pointed to by CWLglobal_popup_prefunc. Here is a small example: #include "cwlwin.h" int display_choice(); void do_display_choice(); POPUP_MENU_PTR p; /* other initializations */ main() { WindowInitializeSystem(); WindowInitDesktop(); MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,0,0); p = PopupCreateMenu(/* arguments */); PopupSetOptions(p,POPUPMOUSE|POPUPMOUSESCROLL,1); CWLglobal_popup_prefunc = display_choice; popup_move_mouse_func = do_display_choice; /* ... */ } display_choice(POPUP_MENU_PTR p, int *choice) { /* display info for entry in a window */ return POPUP_CONTINUE; } void do_display_choice(POPUP_MENU_PTR p, int choice) { display_choice(p,&choice); } Page 294 The C Window Library Page 294 Using a mouse with bar menus ---------------------------- To move the highlight bar with the mouse, position the mouse cursor over any menu entry in the window, and hold the left mouse button down. If the mouse is moved while holding the left button down, the highlight is moved along with the mouse cursor. A selection is made by releasing the left mouse button while the mouse cursor is on an active menu entry. To activate the mouse so that it can be used for bar menus, you must set the bar menu option BARMOUSE on. Using a mouse with pulldown menus --------------------------------- If the menu options for the mouse are turned on for all popup menus and the bar menu, and these menus are used as part of a pulldown menu system, the mouse behaves exactly the same except for the following differences: a) Holding the left mouse button down and positioning the mouse cursor over a bar menu entry will bring up the popup menu that is associated with the bar entry. If there is no popup menu defined for a particular bar entry, releasing the mouse button will invoke the entry's function. b) Releasing the mouse button when it is positioned over a bar entry, and the bar entry has a popup associated with it, does nothing. A general rule is that a menu function is only executed when the highlight bar is positioned on a menu entry that has a function associated with it. Changing the mouse defaults --------------------------- By default, the left mouse button is held down when moving the highlight bar. If you prefer a different button to be used to move the highlight bar, you can change the button by changing the following global variables: int CWLpopup_press - holds the current button to be used to move the highlight bar in popup menus. int CWLbar_press - holds the current button to be used to move the highlight bar in bar menus. The following constants can be assigned to these two global variables: Page 295 The C Window Library Page 295 Constant Definition -------- ---------- MOUSELEFT_PRESS Left button. MOUSERIGHT_PRESS Right button. MOUSEMIDDLE_PRESS Middle button. By default, CWLpopup_press and CWLbar_press are assigned MOUSELEFT_PRESS. Here is an example of changing these variables: #include "cwlwin.h" main() { ... MouseInitializeSystem( /* arguments */ ); /* change mouse menu buttons */ CWLpopup_press = MOUSERIGHT_PRESS; CWLbar_press = MOUSERIGHT_PRESS; ... } The CWLpopup_press and CWLbar_press variables are assigned their default values when MouseInitializeSystem() is called. If you want to change these variables, make sure that the change is made after calling MouseInitializeSystem(). Page 296 The C Window Library Page 296 WINDOW AND VIRTUAL WINDOW MACROS -------------------------------- Note : These macros should be used after making a call to WindowInitializeSystem() or else unpredictable values will be returned. The following macros are defined in the cwlwin.h file. The window w is NOT CHECKED for validity. Macro Definition ┌────────────────┬───────────────────────────────────────────┐ │ISBORDER(w) │Returns TRUE if window has a border, FALSE │ │ │otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │ISFROZEN(w) │Returns TRUE if window is frozen from │ │ │doing screen updates when the virtual │ │ │window has changed, FALSE otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │ISSEETHRU(w) │Returns TRUE if window is in seethru │ │ │mode, FALSE otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │ISSHADOW(w) │Returns TRUE if the window has a shadow, │ │ │FALSE otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │ISSHADOWTRANS(w)│Returns TRUE if the shadow is transparent, │ │ │FALSE otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │ISVISIBLE(w) │Returns TRUE if window is visible, FALSE │ │ │otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │ISVIEWPORT(w) │Returns TRUE if window is a viewport, FALSE│ │ │otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │ISWINDOW(vw) │Returns TRUE if virtual window has any │ │ │viewports, FALSE otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │ISWRAP(w) │Returns TRUE if window wrap is on, FALSE │ │ │otherwise. │ ├────────────────┼───────────────────────────────────────────┤ │SHADOW_ATTR(w) │Returns the current video attribute used to│ │ │draw the window's shadow. Return value is │ │ │undefined if the window has no shadow │ ├────────────────┼───────────────────────────────────────────┤ │SHADOW_CHAR(w) │Returns the current character used to draw │ │ │the window's shadow. Return value is │ │ │undefined if the window has no shadow. │ ├────────────────┼───────────────────────────────────────────┤ │SHADOW_HEIGHT(w)│Returns the height of the window's shadow. │ │ │Return value is undefined if the window │ │ │has no shadow. │ └────────────────┴───────────────────────────────────────────┘ Page 297 The C Window Library Page 297 Macro Definition ┌─────────────────────────┬───────────────────────────────────┐ │SHADOW_POS(w) │Returns the position of the │ │ │shadow as an integer. The valid │ │ │positions are as follows: │ │ │ Return │ │ │Shadow Position Value │ │ ├─────────────── ────── │ │ │SHADOWUPLEFT 1 │ │ │SHADOWUPRIGHT 2 │ │ │SHADOWLOWLEFT 3 │ │ │SHADOWLOWRIGHT 4 │ │ │ │ │ │If there is no shadow, FALSE is │ │ │returned. │ ├─────────────────────────┼───────────────────────────────────┤ │SHADOW_WIDTH(w) │Returns the width of the │ │ │window's shadow. Return value is │ │ │undefined if the window has no │ │ │shadow. │ ├─────────────────────────┼───────────────────────────────────┤ │VIEWPORT_COLUMN(w) │Returns the upper left column of │ │ │where the viewport w is positioned │ │ │on the virtual window. │ ├─────────────────────────┼───────────────────────────────────┤ │VIEWPORT_ROW(w) │Returns the upper left row of where│ │ │the viewport w is positioned on the│ │ │virtual window. │ ├─────────────────────────┼───────────────────────────────────┤ │VIRTUAL_ATTRIBUTE_ON(vw) │Returns TRUE if the virtual window │ │ │vw is attributed, FALSE otherwise. │ ├─────────────────────────┼───────────────────────────────────┤ │VIRTUAL_HEIGHT(vw) │Returns the number of rows in a │ │ │virtual window vw. │ ├─────────────────────────┼───────────────────────────────────┤ │VIRTUAL_WIDTH(vw) │Returns the number of columns │ │ │in a virtual window. │ ├─────────────────────────┼───────────────────────────────────┤ │VIRTUAL_WINDOW(w) │Returns the virtual window that the│ │ │viewport w is currently viewing. │ ├─────────────────────────┼───────────────────────────────────┤ │VIRTUAL_COORD_IN_VIEWPORT│Returns TRUE if the virtual window │ │(w,row,col) │coordinates (row,col) are inside │ │ │the viewport w, FALSE otherwise. │ │ │The virtual window must have w as a│ │ │viewport. │ ├─────────────────────────┼───────────────────────────────────┤ │VIRTUAL_WINDOW_EXIST(vw) │Returns TRUE if virtual window was │ │ │initialized, FALSE otherwise. │ ├─────────────────────────┼───────────────────────────────────┤ │WINDOW_BORDER_CHARS(w) │Returns the current border of a │ │ │window as a string. │ ├─────────────────────────┼───────────────────────────────────┤ │WINDOW_BORDER_COLOR(w) │Returns the border color of the │ │ │window w. │ └─────────────────────────┴───────────────────────────────────┘ Page 298 The C Window Library Page 298 Macro Definition ┌─────────────────────────┬───────────────────────────────────┐ │WINDOW_COLUMN(w) │Returns the absolute column of the │ │ │upper left hand corner of the │ │ │window. │ ├─────────────────────────┼───────────────────────────────────┤ │WINDOW_EXIST(w) │Returns TRUE if window was │ │ │initialized, FALSE otherwise. │ ├─────────────────────────┼───────────────────────────────────┤ │WINDOW_HEIGHT(w) │Returns the height of the text area│ │ │of the window w. │ ├─────────────────────────┼───────────────────────────────────┤ │WINDOW_PAGENUM(w) │Returns the video page of where the│ │ │window will be displayed. │ ├─────────────────────────┼───────────────────────────────────┤ │WINDOW_RANK(w) │Returns the rank of the window w. │ ├─────────────────────────┼───────────────────────────────────┤ │WINDOW_ROW(w) │Returns the absolute row coordinate│ │ │of the upper left hand corner of │ │ │the window w. │ └─────────────────────────┴───────────────────────────────────┘ Page 299 The C Window Library Page 299 MENU MACROS ----------- The following macros are defined in the header file cwlwin.h. Popup Menu Macros Definition ┌──────────────────────────┬──────────────────────────────────┐ │POPUP_CASCADE(p) │Returns TRUE if the menu is a │ │ │menu that has been embedded in │ │ │a cascading menu, FALSE otherwise.│ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_CASCADE_ENTRY │Returns TRUE if the entry is a │ │(p,entry) │cascading menu, FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_DISPLAY_ON(p) │Returns TRUE if the POPUP_MENU_PTR│ │ │p's window is to be displayed │ │ │regardless if the menu manager has│ │ │returned to the calling function, │ │ │FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_ENHANCED_ON(p) │Returns TRUE if the popup menu │ │ │will recognize enhanced keys, │ │ │FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_ENTRY_CHECKED │Returns TRUE if entry is checked, │ │(p,entry) │FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_ENTRY_DISABLED │Returns TRUE if entry is disabled,│ │(p,entry) │FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_ENTRY_GRAYED │Returns TRUE if entry is grayed, │ │(p,entry) │FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_ENTRY_ID(p,entry) │Returns the menu ID number of the │ │ │entry. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_ENTRY_HIGHLIGHTED │Returns TRUE if the entry is high-│ │(p,entry) │lighted, FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_ENTRY_RAWSTRING(p) │Returns the string including the │ │ │ampersand that was used in the │ │ │original menu entry. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_ENTRY_STRING │Returns the entry string of │ │(p,entry) │POPUP_MENU_ENTRY entry. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_EXPLODE(p) │Returns the special effect │ │ │constant of the POPUP_MENU_PTR p. │ │ │This special effect is used to │ │ │hide, close, and open the popup │ │ │menu's window. │ ├──────────────────────────┼──────────────────────────────────┤ │POPUP_MENU_FROM_CASCADE │Returns a POPUP_MENU_PTR that is │ │(p,entry) │the cascading menu located at │ │ │entry. │ └──────────────────────────┴──────────────────────────────────┘ Page 300 The C Window Library Page 300 Popup Menu Macros Definition ┌──────────────────────────┬───────────────────────────────────┐ │POPUP_MOUSE_ON(p) │Returns TRUE if a mouse can be │ │ │used to make selections, FALSE │ │ │otherwise. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_MOUSE_SCROLL_ON(p) │Returns TRUE if a mouse can be used│ │ │to scroll through the entries if │ │ │the entries cannot fit in the │ │ │popup window, FALSE otherwise. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_NUMBER_OF_ENTRIES(p)│Returns the total number of entries│ │ │defined in the POPUP_MENU_PTR p. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_OVERRIDE_ON(p) │Returns TRUE if POPUP_MENU_PTR p │ │ │will have unavailable options │ │ │processed, FALSE otherwise. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_PARENT(p) │Returns the POPUP_MENU_PTR that is │ │ │the parent of the embedded menu p. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_PARENT_ENTRY(p) │Returns the entry number in p's │ │ │parent menu that matches p. -1 if │ │ │there is no such entry. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_PULLDOWN_ON(p) │Returns TRUE if the POPUP_MENU_PTR │ │ │p is incorporated in a pulldown │ │ │menu system, FALSE otherwise. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_STATIC_ON(p) │Returns TRUE if the POPUP_MENU_PTR │ │ │p will remain on the screen when │ │ │an entry is selected, FALSE │ │ │otherwise. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_STRING_IN_WINDOW │Returns TRUE if the POPUP_MENU_PTR │ │(p,entry) │p has entry number entry displayed │ │ │in the popup menu's window, FALSE │ │ │otherwise. │ │ │ │ │ │This macro is useful if you have a │ │ │scrolling popup menu and want to │ │ │know if a particular entry is │ │ │displayed in the window. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_VIRTUAL_WINDOW(p) │Returns the VWPOINTER of the popup │ │ │menu. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_WINDOW(p) │Returns the WPOINTER of the popup │ │ │menu. │ ├──────────────────────────┼───────────────────────────────────┤ │POPUP_WRAP_ON(p) │Returns TRUE if the highlight wrap │ │ │of POPUP_MENU_PTR p is on, │ │ │otherwise 0. │ └──────────────────────────┴───────────────────────────────────┘ Page 301 The C Window Library Page 301 Bar Menu Macros Definition ┌──────────────────────────┬──────────────────────────────────┐ │BAR_DISPLAY_ON(b) │Returns TRUE if the BAR_MENU_PTR │ │ │b's window is to be displayed │ │ │regardless if the menu manager has│ │ │returned to the calling function, │ │ │FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_ENHANCED_ON(b) │Returns TRUE if the bar menu will │ │ │recognize enhanced keys, FALSE │ │ │otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_ENTRY_DISABLED │Returns TRUE if entry is disabled,│ │(b,entry) │FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_ENTRY_GRAYED │Returns TRUE if entry is grayed, │ │(b,entry) │FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_ENTRY_ID(b,entry) │Returns the menu ID number of the │ │ │entry. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_ENTRY_HIGHLIGHTED │Returns TRUE if the entry is high-│ │(b,entry) │lighted, FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_ENTRY_RAWSTRING(b) │Returns the string including the │ │ │ampersand that was used in the │ │ │original menu entry. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_ENTRY_STRING(b,entry) │Returns the entry string of │ │ │BAR_MENU_ENTRY entry. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_EXPLODE(b) │Returns the special effect │ │ │constant of the BAR_MENU_PTR b. │ │ │This special effect is used to │ │ │hide, close, and open the bar │ │ │menu's window. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_NUMBER_OF_ENTRIES(b) │Returns the total number of │ │ │entries defined in the │ │ │BAR_MENU_PTR b. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_PULLDOWN_ON(b) │Returns TRUE if the BAR_MENU_PTR b│ │ │is incorporated in a pulldown menu│ │ │system, FALSE otherwise. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_STATIC_ON(b) │Returns TRUE if the BAR_MENU_PTR b│ │ │will remain on the screen when an │ │ │entry is selected, FALSE otherwise│ ├──────────────────────────┼──────────────────────────────────┤ │BAR_WINDOW(b) │Returns the WPOINTER of the bar │ │ │menu. │ ├──────────────────────────┼──────────────────────────────────┤ │BAR_WRAP_ON(b) │Returns TRUE if the highlight wrap│ │ │of BAR_MENU_PTR b is on, otherwise│ │ │FALSE is returned. │ └──────────────────────────┴──────────────────────────────────┘ Page 302 The C Window Library Page 302 Pulldown Menu Macros Definition ┌─────────────────────────────┬──────────────────────────────┐ │BAR_MENU_PTR_FROM_POPUP(pop) │Returns the BAR_MENU_PTR │ │ │associated with the │ │ │POPUP_MENU_PTR pop, which must│ │ │be part of a pulldown menu │ │ │system. │ ├─────────────────────────────┼──────────────────────────────┤ │BAR_MENU_PTR_FROM_PULLDOWN │Returns the BAR_MENU_PTR │ │(pull) │assocated with the │ │ │PULLDOWN_MENU_PTR pull. │ ├─────────────────────────────┼──────────────────────────────┤ │POPUP_MENU_PTR_FROM_BAR │Returns the POPUP_MENU_PTR │ │(b,entry) │associated with the │ │ │BAR_MENU_PTR b. │ │ │ │ │ │The entry argument is the │ │ │number of the POPUP_MENU_PTR │ │ │desired in the pulldown menu │ │ │system. For example, if you │ │ │want to know the first │ │ │POPUP_MENU_PTR given only a │ │ │BAR_MENU_PTR, the call to this│ │ │macro would be │ │ │POPUP_MENU_PTR_FROM_BAR(b,1). │ ├─────────────────────────────┼──────────────────────────────┤ │POPUP_MENU_PTR_FROM_PULLDOWN │Returns the POPUP_MENU_PTR │ │(pull,entry) │associated with the │ │ │PULLDOWN_MENU_PTR pull. The │ │ │entry is the number of the │ │ │desired POPUP_MENU_PTR desired│ │ │in the pulldown menu system. │ ├─────────────────────────────┼──────────────────────────────┤ │PULLDOWN_MENU_PTR_FROM_BAR │Returns the PULLDOWN_MENU_PTR │ │(b) │associated with the bar │ │ │menu b. │ ├─────────────────────────────┼──────────────────────────────┤ │PULLDOWN_MENU_PTR_FROM_POPUP │Returns the PULLDOWN_MENU_PTR │ │(pop) │associated with the │ │ │POPUP_MENU_PTR pop. │ └─────────────────────────────┴──────────────────────────────┘ Page 303 The C Window Library Page 303 VIDEO MACROS ------------ Macro Definition ┌──────────────────────┬──────────────────────────────────────┐ │CHECK_SNOW │Returns TRUE if during direct screen │ │ │writes that video "snow" is │ │ │eliminated. You can also assign │ │ │values to this macro. This macro is a│ │ │pseudonym for the variable CWLchksnow.│ │ │ │ │ │Example: │ │ │ #include "cwlwin.h" │ │ │ int a; │ │ │ a = CHECK_SNOW; │ │ │ CHECK_SNOW = FALSE; /* Turn off snow│ │ │ checking */ │ ├──────────────────────┼──────────────────────────────────────┤ │CREATE_VIDEO_ATTRIBUTE│Creates a video attribute using bg as │ │(bg,fg) │the background color, and fg as the │ │ │foreground color. The following │ │ │variables can be used: │ ╞══════════════════════╧══════════════════════════════════════╡ │ Variable │ │ Name Color Value │ │ ┌───────────────┬──────────────┬──┐ │ │ │CWLblack │ Black │ 0│ │ │ │CWLblue │ Blue │ 1│ │ │ │CWLgreen │ Green │ 2│ │ │ │CWLcyan │ Cyan │ 3│ │ │ │CWLred │ Red │ 4│ │ │ │CWLmagenta │ Magenta │ 5│ │ │ │CWLbrown │ Brown │ 6│ │ │ │CWLwhite │ White │ 7│ │ │ │CWLgray │ Gray │ 8│ │ │ │CWLlightblue │ Light Blue │ 9│ │ │ │CWLlightgreen │ Light green │10│ │ │ │CWLlightcyan │ Light cyan │11│ │ │ │CWLlightred │ Light red │12│ │ │ │CWLlightmagenta│ Light magenta│13│ │ │ │CWLyellow │ Yellow │14│ │ │ │CWLlightwhite │ Intense white│15│ │ │ └───────────────┴──────────────┴──┘ │ │ │ │The variables above are initialized when │ │WindowInitializeSystem() is called. If you want to use a │ │color value before WindowInitializeSystem() is called, you │ │can use the uppercase equivalent of the above variables, with│ │a trailing underscore character attached to the name. For │ │example BLACK_ would be used instead of CWLblack, WHITE_ │ │would be used instead of white, etc. │ │ │ │For monochrome systems, the only colors that are available │ │are CWLblack, CWLwhite, and CWLwhite. An attribute of │ │CWLblue creates an underline attribute, and CWLlightblue │ │creates an intense underlined attribute. Any other │ │combination on a monochrome system is undefined. │ ╘═════════════════════════════════════════════════════════════╛ Page 304 The C Window Library Page 304 Macro Definition ┌──────────────────────┬───────────────────────────────────┐ │GET_BGROUND_COLOR(c) │Returns the background color of the│ │ │video attribute c. │ ├──────────────────────┼───────────────────────────────────┤ │GET_FGROUND_COLOR(c) │Returns the foreground color of the│ │ │video attribute c. │ ├──────────────────────┼───────────────────────────────────┤ │GET_OFFSET(x) │Returns the offset of a pointer x. │ │ │The pointer can be either near or │ │ │far. │ ├──────────────────────┼───────────────────────────────────┤ │GET_SEGMENT(x) │Returns the segment address of a │ │ │pointer x. The pointer can be │ │ │either near or far. │ ├──────────────────────┼───────────────────────────────────┤ │MAKE_FAR_POINTER(a,b) │Creates a far pointer made up of │ │ │segment address a, and offset │ │ │address b. │ ├──────────────────────┼───────────────────────────────────┤ │SCREEN_OFFSET(r,c,a) │Returns the screen offset of the │ │ │address of a character located at │ │ │row r and column c of the video │ │ │page a. The screen segment is │ │ │defined in the macro │ │ │SCREEN_SEGMENT. both r and c │ │ │should be >= 0. │ │ │ │ │ │Example: char far *p; p = │ │ │MAKE_FAR_POINTER(SCREEN_SEGMENT, │ │ │ SCREEN_OFFSET(0,0,0)); │ │ │ │ │ │The above example has created a far│ │ │pointer p that points to the screen│ │ │buffer memory at row 0, column 0, │ │ │on video page 0. │ ├──────────────────────┼───────────────────────────────────┤ │SCREEN_OFFSET_ATTR │Returns the screen offset of the │ │(r,c,a) │address of a attribute located at │ │ │row r and column c of the video │ │ │page a. The screen segment is │ │ │defined in the macro │ │ │SCREEN_SEGMENT. Both r and c │ │ │should be >= 0. │ ├──────────────────────┼───────────────────────────────────┤ │SCREEN_SEGMENT │Returns the screen segment of video│ │ │page 0. This macro is a pseudo- │ │ │nym for the variable CWLscrnseg. │ └──────────────────────┴───────────────────────────────────┘ Page 305 The C Window Library Page 305 Macro Definition ┌──────────────────────┬───────────────────────────────────┐ │SCREEN_WRITE_METHOD │Returns 1 if writing directly to │ │ │the screen, 0 if using the BIOS. │ │ │You can also use this macro to │ │ │assign the particular writing │ │ │method. This macro controls the │ │ │way The C Window Library will do │ │ │screen updates. The default is 1 │ │ │(write directly to screen). │ │ │ │ │ │Example: │ │ │#include "cwlwin.h" │ │ │int a,b; │ │ │a = SCREEN_WRITE_METHOD; │ │ │SCREEN_WRITE_METHOD = 1; │ ├──────────────────────┼───────────────────────────────────┤ │VIDEO_PAGESIZE │Returns the size (in bytes) of a │ │ │video page. You can also assign │ │ │values to VIDEO_PAGESIZE, but the │ │ │best thing to do is to leave it │ │ │alone unless you are familiar with │ │ │the video system you are using. │ │ │This macro is a pseudonym for the │ │ │variable CWLpagesize. │ └──────────────────────┴───────────────────────────────────┘ The following macros are used to identify the monitor type and video card being used in the system. Macro Definition ┌────────────────────┬───────────────────────────────────┐ │CGA_ACTIVE │Returns TRUE if Color Graphics │ │ │Adapter is active, FALSE otherwise.│ ├────────────────────┼───────────────────────────────────┤ │EGA_ACTIVE │Returns TRUE if EGA is active, │ │ │FALSE otherwise. │ ├────────────────────┼───────────────────────────────────┤ │EGA_COLOR_ATTACHED │Returns TRUE if monitor hooked up │ │ │to EGA is a high resolution color │ │ │monitor, FALSE otherwise. │ ├────────────────────┼───────────────────────────────────┤ │EGA_COLOR_ON │Returns TRUE if EGA is in color │ │ │mode, FALSE otherwise. │ ├────────────────────┼───────────────────────────────────┤ │EGA_INSTALLED │Returns TRUE if EGA is installed, │ │ │FALSE otherwise. │ ├────────────────────┼───────────────────────────────────┤ │HERCULES_ACTIVE │Returns TRUE if Hercules adapter is│ │ │active, FALSE otherwise. │ ├────────────────────┼───────────────────────────────────┤ │MCGA_ACTIVE │Returns TRUE if the MCGA is the │ │ │active video card. │ ├────────────────────┼───────────────────────────────────┤ │MCGA_COLOR_ON │Returns TRUE if MCGA is in color │ │ │mode, FALSE otherwise. │ └────────────────────┴───────────────────────────────────┘ Page 306 The C Window Library Page 306 ┌────────────────────┬───────────────────────────────────┐ │MCGA_INSTALLED │Returns TRUE if MCGA is installed │ │ │(IBM PS/2 Model 30), FALSE │ │ │otherwise. │ ├────────────────────┼───────────────────────────────────┤ │MDA_ACTIVE │Returns TRUE if MDA (Monochrome) │ │ │adapter is active, FALSE otherwise.│ ├────────────────────┼───────────────────────────────────┤ │MONO_MODE_ON │Returns TRUE if Monochrome mode is │ │ │on regardless of the adapter, FALSE│ │ │otherwise. │ ├────────────────────┼───────────────────────────────────┤ │VGA_ACTIVE │Returns TRUE if VGA is active │ │ │adapter, FALSE otherwise. │ ├────────────────────┼───────────────────────────────────┤ │VGA_COLOR_ATTACHED │Returns TRUE if monitor is hooked │ │ │up to VGA analog color, FALSE │ │ │otherwise. │ ├────────────────────┼───────────────────────────────────┤ │VGA_COLOR_ON │Returns TRUE if VGA is in color │ │ │mode, FALSE otherwise. │ ├────────────────────┼───────────────────────────────────┤ │VGA_INSTALLED │Returns TRUE if VGA Adapter is │ │ │installed, FALSE otherwise. │ └────────────────────┴───────────────────────────────────┘ You should always check the ..._ACTIVE constants before checking for other aspects of the video system. For example, make sure that VGA_ACTIVE returns 1 before checking any other VGA_... macro. If VGA_ACTIVE is 1, then all VGA_... macros are valid. The same thing goes for EGA. MONO_MODE_ON is the only macro that can be tested regardless of the video adapter. Macro Definition ┌────────────┬──────────────────────────────────┐ │LINEMODE25 │Returns TRUE if screen displays 25│ │ │lines, FALSE otherwise. │ ├────────────┼──────────────────────────────────┤ │LINEMODE43 │Returns TRUE if screen displays 43│ │ │lines (EGA and VGA), FALSE │ │ │otherwise. │ ├────────────┼──────────────────────────────────┤ │LINEMODE50 │Returns TRUE if screen displays 50│ │ │lines (VGA), FALSE otherwise. │ └────────────┴──────────────────────────────────┘ Page 307 The C Window Library Page 307 KEYBOARD MACROS --------------- Macro Definition ┌─────────────────────┬────────────────────────────────────────┐ │ENHANCED_KEYBOARD() │Returns TRUE if there is an enhanced │ │ │keyboard attached, FALSE otherwise. │ ├─────────────────────┼────────────────────────────────────────┤ │FLUSH_KEYBOARD() │Flushes the keyboard buffer. │ ├─────────────────────┼────────────────────────────────────────┤ │GET_KEY() │Returns what key was pressed either as a│ │ │character, or as a scan code if a │ │ │non-ascii key is pressed. A list of │ │ │scan codes are found in the file │ │ │cwlwin.h. │ ├─────────────────────┼────────────────────────────────────────┤ │GET_ENHANCED_KEY() │Same as GET_KEY() except that keys on │ │ │the enhanced keyboards are │ │ │distinguishable. For instance, the │ │ │key on the keypad will return a │ │ │different scan code than the Home key │ │ │on the separate cursor movement pad. │ ├─────────────────────┼────────────────────────────────────────┤ │GET_SHIFT_STATE() │Returns the shift state of the keyboard.│ │ │The shift state tells whether the Alt, │ │ │Ctrl or Shift key was pressed, or if the│ │ │Num Lock, Scroll Lock, or Caps Lock keys│ │ │are on or off. The shift state is │ │ │updated after each call to GET_KEY() or │ │ │GET_ENHANCED_KEY(). Use a bitwise AND │ │ │(&) when testing for these keys. │ │ │The #defined constants that are used to │ │ │test for the various keys is found in │ │ │cwlwin.h. │ │ │ │ │ │Example: │ │ │ │ │ │#include "cwlwin.h" │ │ │#include <stdio.h> │ │ │main() │ │ │{ │ │ │ int CurrentShift; │ │ │ GET_KEY(); │ │ │ /* both ALT and CTRL │ │ │ must be pressed */ │ │ │ CurrentShift = │ │ │ (GET_SHIFT_STATE() & ALT) && │ │ │ (GET_SHIFT_STATE() & CTRL); │ │ │ │ │ │ printf("The Ctrl and Alt key" │ │ │ "was %s pressed", │ │ │ CurrentShift?"":"not"); │ │ │} │ ├─────────────────────┼────────────────────────────────────────┤ │ISKEYREADY() │Returns TRUE if there is a key ready in │ │ │the keyboard buffer, FALSE otherwise. │ └─────────────────────┴────────────────────────────────────────┘ Page 308 The C Window Library Page 308 Keyboard Idle function ---------------------- When calling the GET_KEY() or GET_ENHANCED_KEY() macros, you can call a function while the program is waiting for a key to be pressed. The global variable CWLkey_idle_func is a function pointer that points to this function. Here is the prototype: void (*CWLkey_idle_func)(void) There are no arguments and no return value to this function. You must initialize this function pointer after you have called WindowInitializeSystem(). If not, the function you assigned will not be executed. Here is an example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) void count_numbers(void); int num = 0; main() { WindowInitializeSystem(); CWLkey_idle_func = count_numbers; ClearScreen(NORM); GET_KEY(); MoveCursor(2,1,0); VideoPrintf("You stopped the count at %d",num); } void count_numbers() { num++; MoveCursor(0,0,0); VideoPrintf("%d",num); delay(1000); } The program above keeps a counter going in the upper left hand corner of the screen until a key is pressed. If you want to unassign the CWLkey_idle_func function pointer, do the following: CWLkey_idle_func = VOIDNULLFN; This function can perform just about anything. One major use would be to update an on-screen clock while the keyboard is not being used. Page 309 The C Window Library Page 309 Keyboard Intercept function --------------------------- Before GET_KEY() and GET_ENHANCED_KEY() return a value, you can intercept the pending return value, examine it, and change the value to whatever you wish. This is good if you want to reassign keys easily. The function pointer to assign is CWLkey_intercept_func. Here is the prototype: unsigned (*CWLkey_intercept_func)(int which, unsigned keyval) The first argument is an integer that denotes whether a mouse button was pressed, or a key from the keyboard was pressed. If a keyboard key was pressed, the value of which is equal to KEYPRESSED, otherwise it is MOUSEPRESSED. If you do not have a mouse, or the mouse is not activated, this value will always be KEYPRESSED. More information on the mouse in the USING THE MOUSE section in the manual. The return value will be the new key value that GET_KEY() and GET_ENHANCED_KEY() will return. It is advisable to use the key codes described in "cwlwin.h" if you are returning a non-ascii key. Here is an example: #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) unsigned switch_to_quotes(int,unsigned); unsigned oldchar; main() { int ch; WindowInitializeSystem(); CWLkey_intercept_func = switch_to_quotes; ClearScreen(NORM); ch = GET_KEY(); MoveCursor(0,0,0); VideoPrintf( "The old key was %c. The new code is %c",oldchar,ch); } unsigned switch_to_quotes(int which, unsigned keyval) { if (which == KEYPRESSED) { oldchar = keyval; return (unsigned)'"'; /* return a double quote */ } } The program above intercepts the return value of GET_KEY() and assigns the double quote character. The character is then printed out on the screen along with the character that was assigned. If you want to unassign the CWLkey_intercept_func function pointer, do the following: CWLkey_intercept_func = NULLFN; Page 310 The C Window Library Page 310 Checking for mouse button presses --------------------------------- The GET_MPRESS_KEY() and GET_MPRESS_ENHANCED_KEY() macros work the same as the GET_KEY() and GET_ENHANCED_KEY() macros, which are described below and used in some previous examples, except that GET_MPRESS_KEY() and GET_MPRESS_ENHANCED_KEY() also test to see if one or more mouse buttons has been pressed. When GET_MPRESS_KEY() or GET_MPRESS_ENHANCED_KEY() is called, the program is suspended until a key on the keyboard is pressed, or one or more mouse buttons has been pressed. The difference between these two macros is that GET_MPRESS_ENHANCED_KEY() recognizes keys on an enhanced (101 key) keyboard. Here is a prototype for both of these macros: unsigned int GET_MPRESS_KEY(int *which) unsigned int GET_MPRESS_ENHANCED_KEY(int *which) The only argument is a pointer to an integer which will contain either MOUSEPRESSED if the mouse was pressed, or KEYBOARDPRESSED if a key on the keyboard was pressed. The CWLkey_idle_func and CWLkey_intercept_func function pointers are fully implemented when either of these macros are called. Both of these macros return either the key that was struck, or the mouse button(s) that was(were) pressed. The values for these mouse buttons are as follows: ┌──────────────────────────┬───────────────────────────────┐ │MOUSELEFT_PRESS │Left button was pressed. │ ├──────────────────────────┼───────────────────────────────┤ │MOUSERIGHT_PRESS │Right button was pressed. │ ├──────────────────────────┼───────────────────────────────┤ │MOUSEMIDDLE_PRESS │Middle button was pressed. │ ├──────────────────────────┼───────────────────────────────┤ │MOUSELEFTRIGHT_PRESS │Left and Right was pressed │ │ │simultaneously. │ ├──────────────────────────┼───────────────────────────────┤ │MOUSEMIDDLERIGHT_PRESS │Middle and Right buttons were │ │ │pressed simultaneously. │ ├──────────────────────────┼───────────────────────────────┤ │MOUSEMIDDLELEFT_PRESS │Middle and Left buttons pressed│ │ │simultaneously. │ ├──────────────────────────┼───────────────────────────────┤ │MOUSEMIDDLERIGHTLEFT_PRESS│Middle, right, and left buttons│ │ │pressed simultaneously. │ └──────────────────────────┴───────────────────────────────┘ If a keyboard key is hit, the return values are the same as for GET_KEY() or GET_ENHANCED_KEY(). Page 311 The C Window Library Page 311 Example: #include "cwlmouse.h" #include "cwlwin.h" #define NORM CREATE_VIDEO_ATTRIBUTE(BLACK_,WHITE_) void print_nums(); main() { int w,b; unsigned ch; WindowInitializeSystem(); ClearScreen(NORM); MouseInitializeSystem(MOUSE_FULL_INSTALL,&b,10,10); CWLkey_idle_func = print_nums; ch = GET_MPRESS_KEY(&w); VideoPrintf("\nThe %s was pressed. Value is %d", (w==MOUSEPRESSED?"Mouse":"Keyboard"),ch); MouseRestoreSystem(); } void print_nums() { static int count = 0; MoveCursor(0,0,0); VideoPrintf("%d",count++); } Page 312 The C Window Library Page 312 ERROR CODES ----------- The following table is a list of error codes defined in CWL. Error Code Value Definition ┌───────────────────────┬─────┬──────────────────────────────┐ │NO_ERROR │ 0 │No error. │ ├───────────────────────┼─────┼──────────────────────────────┤ │NO_HEAP_MEM │ -1 │Memory Allocation Failed. │ ├───────────────────────┼─────┼──────────────────────────────┤ │BAD_DISPLAY_PAGE │ -2 │Video page does not exist. │ ├───────────────────────┼─────┼──────────────────────────────┤ │INVALID_VIDEO_MODE │ -3 │Video mode is invalid. │ ├───────────────────────┼─────┼──────────────────────────────┤ │INVALID_ROWS │ -4 │Invalid number of screen rows.│ ├───────────────────────┼─────┼──────────────────────────────┤ │NOT_SUPPORTED │ -5 │Feature is not supported in │ │ │ │this version of CWL. │ ├───────────────────────┼─────┼──────────────────────────────┤ │BAD_WINDOW │-100 │WPOINTER does not exist. │ ├───────────────────────┼─────┼──────────────────────────────┤ │BAD_WINDOW_SIZE │-101 │Window size is invalid. │ ├───────────────────────┼─────┼──────────────────────────────┤ │MAX_WINDOW │-104 │Maximum number of windows │ │ │ │already defined. │ ├───────────────────────┼─────┼──────────────────────────────┤ │NO_INPUT_CHARS │-106 │Number of characters defined │ │ │ │in input mask is 0. │ ├───────────────────────┼─────┼──────────────────────────────┤ │BAD_V_WINDOW │-200 │VWPOINTER does not exist. │ ├───────────────────────┼─────┼──────────────────────────────┤ │NO_ATTRIB │-204 │Virtual window has no │ │ │ │attributes. │ ├───────────────────────┼─────┼──────────────────────────────┤ │FILE_NO_EXIST │-300 │File does not exist. │ ├───────────────────────┼─────┼──────────────────────────────┤ │FILE_CANT_CLOSE │-301 │Cannot close output file. │ ├───────────────────────┼─────┼──────────────────────────────┤ │FILE_CANT_OPEN │-302 │Cannot open file for output. │ ├───────────────────────┼─────┼──────────────────────────────┤ │MENU_ENTRY_INVALID │-400 │Invalid menu entry. │ ├───────────────────────┼─────┼──────────────────────────────┤ │POPUP_NOT_ATTACHED │-405 │Popup Menu does not have a │ │ │ │window attached. │ ├───────────────────────┼─────┼──────────────────────────────┤ │BAR_NOT_ATTACHED │-406 │Bar Menu does not have a │ │ │ │window attached. │ ├───────────────────────┼─────┼──────────────────────────────┤ │PULL_NO_BARMENU │-407 │Pulldown menu does not have a │ │ │ │bar menu defined. │ ├───────────────────────┼─────┼──────────────────────────────┤ │POPUP_MENU_INVALID │-408 │POPUP_MENU_PTR is invalid. │ ├───────────────────────┼─────┼──────────────────────────────┤ │BAR_MENU_INVALID │-409 │BAR_MENU_PTR is invalid. │ └───────────────────────┴─────┴──────────────────────────────┘ Page 313 The C Window Library Page 313 IMPORTANT GLOBAL VARIABLES -------------------------- There are global variables that you should be aware of in The C Window Library. Most of these variables can be changed, while others should be left alone. You must call WindowInitializeSystem() before modifying any of these variables. The list does not cover all of the global variables in CWL. To refer to all of the global variables, the file CWLGLOB.H and INTERNAL.H has definitions for all global variables and internal functions used in CWL. When describing the global variable, the following scheme is used: Variable variable name Defined in XXXXXX.h (file where variable is declared) Initialized in function call (function where variable gets its initial value) Purpose Description of variable's purpose. Default Value default value for variable. Modify Info Tells if variable should be modified. These variables are described in alphabetical order. Variable int CWLactive_page Initialized in WindowInitializeSystem() Purpose Current active video page. Modify Info Should be modified only by calling the SetActiveVideoPage() function. Page 314 The C Window Library Page 314 Variable int CWLbar_press Initialized in MouseInitializeSystem() Purpose Holds the current button mouse button to press to move the highlight bar on bar menus. Default Value MOUSELEFT_PRESS. Modify Info Can be modified at any time. Variable int CWLcaldelay Initialized in WindowInitializeSystem() Purpose This is a calibration count for the delay() function. Modify Info Should only be modified if the delay() function is giving inaccurate delay times. If the delay is too long, then caldelay_ should be decreased. If it is too short, then CWLcaldelay should be increased. Variable int CWLcheck_exist Initialized in WindowInitializeSystem() Purpose Informs The C Window Library to check for window, virtual window, and for non-open window errors. If this variable is 1, the library routines will check for these conditions. If 0, these conditions are not checked. Default Value 1. Modify Info Can be modified at any time, but is recommended that this flag be left on for development work. Make sure that your application program is stable if you plan to turn off checking. Page 315 The C Window Library Page 315 Variable int CWLchksnow Initialized in WindowInitializeSystem() Purpose This variable controls whether the display should be checked for snow when writing directly to the screen. A value of 1 will check for snow, while a value of 0 will turn off snow checking. Default Value 0 (no snow checking). Modify Info Can be modified at any time. Variable int CWLcrt_port Initialized in WindowInitializeSystem() Purpose This variable holds the value of the CRT status port. This port is used to test when it is safe to read or write characters to the screen without producing snow. Modify Info Should not be modified. Variable int CWLcursor_mode Initialized in WindowInitializeSystem() Purpose Holds the mode that the WindowGet...() functions will operate in when called. The modes are either OVERSTRIKEMODE or INSERTMODE. Default Value OVERSTRIKEMODE. Modify Info Can be modified at any time. Example: CWLcursor_mode = INSERTMODE; Page 316 The C Window Library Page 316 Variable int CWLcursor_type[2] Initialized in WindowInitializeSystem() Purpose Holds the cursor shapes for OVERSTRIKEMODE and INSERTMODE input modes. Default Value CWLcursor_type[OVERSTRIKEMODE] is set to a block cursor. CWLcursor_type[INSERTMODE] is set to an underline cursor. Modify Info Can be modified at any time. Example: CWLcursor_type[INSERTMODE] = CREATE_CURSOR_SHAPE(5,7); Variable int CWLdef_attr Initialized in WindowInitializeSystem() Purpose Default video attribute used when any Video...() functions are called to write to the screen. Default Value 7 (black background, white foreground). Modify Info Can be modified at any time. Variable int CWLenhanced_keyboard Initialized in WindowInitializeSystem() Purpose Tells if an enhanced keyboard is attached. If CWLenhanced_keyboard is 1, an enhanced keyboard is active, otherwise if 0, the keyboard is not an enhanced keyboard. Modify Info Can be modified safely. Page 317 The C Window Library Page 317 Variable int CWLeffect_speed[16] Initialized in WindowInitializeSystem() Purpose This array holds the number of milliseconds of delay for each of the special effects supported in The C Window Library. Default Value 10 (10 ms.), except for CWLeffect_speed[BRICKS], which is 1 ms. Modify Info Can be modified safely at anytime. The way you would modify the values is to use the special effects constants. For example: CWLeffect_speed[CONTRACT] = 5; The above example changes the explosion delay for the CONTRACT special effect to 5 ms. Variable int CWLflush_kbd Initialized in WindowInitializeSystem(). Purpose Tells if the keyboard buffer should be flushed whenever the GET_KEY() or GET_ENHANCED_KEY() macros are called. A value of 1 means the buffer will be flushed. Default Value 0 (no flush). Modify Info Can be modified at any time. Variable VIDEO_CONFIG CWLinit_video Initialized in WindowInitializeSystem() Purpose Structure that holds the video configuration when WindowInitializeSystem() is called. Modify info Should not be modified if the initial video startup is desired when exiting an application. Page 318 The C Window Library Page 318 Variable char CWLmask_char Initialized in WindowInitializeSystem() Purpose Holds the mask character that is used for input routines. The character defined in input_mask_char is used in input masks to specify an input position in the edit field. Refer to the functions WindowGet..() functions for more information concerning character masks. Default Value '_' (0x5F). Modify Info Can be modified safely at any time, except when in the middle of a user defined function that was called by The C Window Library's input routines. Variable void (*CWLkey_idle_func)(void) Initialized in WindowInitializeSystem() Purpose pointer that points to a function that is performed whenever the GET_KEY() and GET_ENHANCED_KEY() macros do not have a key ready to be processed. Modify Info Can be modified at any time. Variable unsigned (*CWLkey_intercept_func)(int which, unsigned keyval) Initialized in WindowInitializeSystem() Purpose pointer that points to a function which traps any keystrokes that the GET_KEY() and GET_ENHANCED_KEY() macros will return. Modify Info Can be modified at any time. Page 319 The C Window Library Page 319 Variable int CWLmax_pages Initialized in WindowInitializeSystem() Purpose Total number of video pages detected by The C Window Library. Modify Info Should not be modified unless a modification to the screen_page_offset array was done. Variable int (*CWLchars_entered_func)(char *string, int minchars) Arguments string - string that was entered. minchars - minimum number of characters expected. Initialized in WindowInitializeSystem() Purpose Pointer to user-defined function that will be executed when the input manager detects that there were not enough characters entered. Default Value NULLFN. Variable int CWLwindow_trans[16] Initialized in WindowInitializeSystem() Purpose Array of the number of transparent shadows that are currently displayed for each display page. Default Value 0 for each array element. Modify Info Do not modify. Page 320 The C Window Library Page 320 Variable WPOINTER CWLorig_screen[16] Initialized in WindowInitDesktop() Purpose Array of windows created when WindowInitDesktop() is called. The original screen for video page 0 is CWLorig_screen[0], page 1 is CWLorig_screen[1], etc. Modify Info You can use any window function on the original screen, except for ones that resize, move, hide, display, or close. If you write strings to the original screen, you will permanently destroy the contents of the original screen at the positions that have been modified. Example: WindowWriteString(CWLorig_screen[0],"123",0,0); The above example writes "123" to the upper left hand corner of the original screen of video page 0. Variable int CWLpagesize Initialized in WindowInitializeSystem() Purpose Holds the size of a display page in bytes. Modify Info Should not be modified unless The C Window Library did not detect the correct video page size. Page 321 The C Window Library Page 321 Variable int CWLpopup_press Initialized in MouseInitializeSystem() Purpose Holds the current button mouse button to press to move the highlight bar on popup menus. Default Value MOUSELEFT_PRESS. Modify Info Can be modified at any time. Variable int (*CWLreg_exp_error_func)(char *string, int nomatch) Arguments string - string that was entered. nomatch - position of the first non-matching character. Initialized in WindowInitializeSystem() Purpose Pointer to user-defined function that will be executed when the input manager detects that there are illegal characters in the string when it is compared to the regular expression. This function is only called when it is not equal to NULLFN, and the CHECKREGEXP option is on. Default Value NULLFN. Modify info Can be modified at any time. Return Values Must return DONT_PROCESS or ACCEPT_INPUT. Variable int CWLscreen_cols Initialized in WindowInitializeSystem() Purpose Number of columns visible on the screen. Modify Info Do not modify this variable Page 322 The C Window Library Page 322 Variable unsigned int *CWLscreen_image[16] Initialized in WindowInitializeSystem() Purpose Used for internal window management. Each pointer in the CWLscreen_image array points to an image of the current window organization of the screen. For example CWLscreen_image[0] is a pointer to the current window "layout" for video page 0. Modify Info DO NOT modify this. This array is VERY important when window updates are done. Variable unsigned char far *CWLpage_offset[16] Initialized in WindowInitializeSystem() Purpose Array of starting addresses of each video page. Modify Info You can modify if The C Window Library fails to detect video pages that your video card may have. Invalid video pages will set CWLpage_offset[page] to a far NULL pointer, where page is the invalid video page. If there is a failure to detect video pages that your card may have, you can use the MAKE_FAR_POINTER macro to initialize. Example: CWLpage_offset[page] = MAKE_FAR_POINTER(0xB000,0x2000); where page is the page to initialize. You should have the documentation of the video card on hand so that you are sure of the starting address of the video page. You must also adjust the global variable CWLmax_pages to reflect the new number of pages, and the CWLpagesize variable to reflect the size of each video page. Page 323 The C Window Library Page 323 Variable int CWLscreen_rows Initialized in WindowInitializeSystem() Purpose Number of rows visible on the screen. Modify Info Don't modify this variable Variable int (*CWLundef_akey_func)(char *string, unsigned key, int pos, int *newpos) Arguments string - string currently entered. key - key that was hit. pos - position where cursor is in the input string. Purpose Pointer to a function that is executed when a key that is not defined in an input routines regular expression is pressed. Default Value NULLFN. Modify Info Can be modified at any time. Return Values Refer to the manual for more information. Variable int (*CWLundef_fkey_func)(char *string, unsigned key, int pos, int *newpos) Defined in key.h Arguments string - string currently entered. key - key that was hit. pos - position where cursor is in the input string. Purpose Pointer to a function that is executed when a key that is not defined in an input routines regular expression is pressed. Page 324 The C Window Library Page 324 Default Value NULLFN. Modify Info Can be modified at any time. Return Values Refer to to the main documentation for more information. Variable int CWLvisible_page Initialized in WindowInitializeSystem() Purpose Current visible video page. Modify Info Should be modified only by calling the SetVisibleVideoPage() function. Variable unsigned CWLedit_key[12] Defined in cwlwin.h Initialized in WindowInitializeSystem() Purpose Array of edit key definitions. This array is used in the window input routines. Modify Info You can modify values in the array, provided that there are no duplicate definitions, and there is a definition for a key that terminates user input. Refer to the GETTING INPUT FROM WINDOWS section. Page 325 The C Window Library Page 325 Variable int CWLerror_code Initialized in WindowInitializeSystem() Purpose Holds the last error that occurred as an integer. You should always check the value of CWLerror_code to determine what has happened if a function fails. All of the window and virtual window functions return an error status when things go wrong. However, only selected functions from the Video... family of functions set CWLerror_code. CWLerror_code does not reset itself if there are no errors. Default Value 0. Modify Info Safe to modify, but will always reset itself to an error condition if a function fails. Page 326 The C Window Library Page 326 INDEX ───── A Adding Menu Entries (see Bar Menus-Creating Entries, Popup Menus-Creating Entries, Pulldown Menus-Creating Entries) Adjusting Screen Dimensions (see Screen Handling-Changing Number of Rows/ Changing Number of Cols) B Bar Menus ................................ 208 - 232 Changing Entry String ................ 224 Creating ............................. 209 - 212 Creating Entries ..................... 212 - 216 Deleting Entries ..................... 216 Disabling Entries .................... 223 Disposing of ......................... 232 Enabling Entries ..................... 223 Inserting Entries .................... 212, 215 Macros ............................... 302 Pre-Selection Function ............... 230 Redefining Menu Keys ................. 225 Retrieving Options ................... 222 Selecting ............................ 218 Setting Local Key Definitions ........ 225 Setting Options ...................... 221 Undefined Keys ....................... 227 Values passed to menu function ....... 220 Values returned to menu manager ...... 220 Boxes Types ................................ 12 Drawing (see Screen Handling-Drawing Boxes) C Child Windows ............................ 118 Centering ........................... 22 Creating ............................. 119 Enumerating .......................... 123 - 124 Testing Ranks ........................ 126 Testing Relationships ................ 125 - 126 Translating Coordinates .............. 120 - 123 Uses ................................. 118 Closing Windows (see Windows-Closing) Page 327 The C Window Library Page 327 Colors (see Screen Handling-Attributes) Cursor ................................... 79 Changing Shape ....................... 79, 279 Hiding ............................... 79, 281 Maintenance .......................... 79 Moving ............................... 80, 164, 279 Retrieving Position .................. 82, 165, 280 Retrieving Shape ..................... 81, 280 CWL ...................................... 1 Introduction ......................... 1 Compiler Support ..................... i Global Variables ..................... iv Initializing ......................... 8 Uninitializing ....................... 21 D Delay function ........................... 285 Direct Screen Writing .................... 5 E Error Codes .............................. 7, 313 Error Handling ........................... 288 I Initializing CWL (see CWL-Initializing) Mouse (see Mouse-Initializing) Input (see Window-Editing Input) M Menus (see Bar Menus, Popup Menus, Pulldown Menus) Mouse .................................... 291 Initializing ......................... 291 Turning Off .......................... 292 Using with Menus ..................... 293, 295 Page 328 The C Window Library Page 328 P Popup Menus .............................. 175 - 207 Cascading Menus ...................... 185 - 187 Changing Entry String ................ 197 Creating ............................. 176 - 179 Creating Entries ..................... 179 - 182 Deleting Entries ..................... 187 - 188 Disabling Entries .................... 196 Disposing of ......................... 207 Enabling Entries ..................... 196 Inserting Entries .................... 179 - 187 Macros ............................... 300 - 301 Pre-Selection Function ............... 205 - 206 Redefining Menu Keys ................. 199 - 200 Retrieving Options ................... 195 Sizing Popup Window .................. 188 - 190 Selecting ............................ 191 - 193 Setting Local Key Definitions ........ 200 Setting Options ...................... 194 Undefined Keys ....................... 201 - 204 Values passed to menu function ....... 193 Values returned to menu manager ...... 193 Pulldown Menus ........................... 233 - 246 Bar Menu Functions ................... 238 Creating ............................. 234 - 236 Creating Entries ..................... 235 - 236 Deleting Entries ..................... 236 Disposing of ......................... 238 Macros ............................... 303 Popup Menu Functions ................. 239 Values passed to menu function ....... 237 Values returned to menu manager ...... 237 R Regular Expressions (see Window - Regular Expressions) S Screen Handling .......................... Attributes ........................... 4 BIOS ................................. 5 Setting Video Mode ................... 271 Getiing Video Information ............ 283 - 284 Changing Number of Rows .............. 272 - 275 Changing Number of Columns ........... 276 - 278 Writing Strings ..................... 251 - 259 Writing Attributes ................... 251 - 259 Reading Strings ...................... 259 - 261 Reading Attributes ................... 259 - 261 Page 329 The C Window Library Page 329 Scrolling ............................ 269 - 270 Saving Areas ......................... 264 Restoring Areas ...................... 265 Drawing Boxes ........................ 262 - 263 Video Pages .......................... 6, 248 - 250 Starting CWL (see CWL-Initializing) V Virtual Windows .......................... 127 - 173 Attributes ........................... 127 - 128 Clearing ............................. 166 - 169 Closing .............................. 133 - 134, 172 - 173 Freezing Viewport .................... 170 - 171 Initializing ......................... 129 - 130 Initializing Viewports ............... 131 - 133 Introduction ......................... 127 Logical Cursor ....................... 128, 164 - 165 Positioning Viewport ................. 155 - 158 Reading Attributes ................... 151 - 154 Reading Strings ...................... 151 - 154 Size ................................. 127 Writing Attributes ................... 135 - 150 Writing Contents to File ............. 162 - 163 Writing Strings ...................... 135 - 150 Video Modes (see Screen Handling-Video Mode) Video Pages (see Screen Handling-Video Pages) Video Functions (see Screen Handling) W Window ................................... Borders .............................. 10, 12, 25 - 27 Centering ............................ 22 - 23 Changing Window Size ................. 27 - 29 Child (see Child Windows) Clearing ............................. 66 - 69 Client Area .......................... 4 Closing .............................. 19 - 21 Colors/Attributes .................... 4 - 5, 11, 304 Coordinates .......................... 4 Creating ............................. 9 Creating copies ...................... 59 - 60 Cursor Maintenance ................... 79 - 83 Defining ............................. 1 Desktop .............................. 2, 9 Determining point ownership .......... 84 Display Effects ...................... 14 - 18 Page 330 The C Window Library Page 330 Displaying ........................... 14 - 18 Editing Input ........................ 85 - 117 Header Files ......................... 8 Hiding ............................... 57 - 58 Moving ............................... 77 printf() for windows ................. 43 - 46 Properties ........................... 1 Ranks ................................ 2 Reading Attributes ................... 53 - 58 Reading Strings ...................... 53 - 58 Regular Expressions .................. 85 - 89 Scrolling Text ....................... 61 - 65 See-thru Windows ..................... 75 - 76 Shadowing ............................ 72 - 74 Sliding .............................. 78 Titles ............................... 47 - 52 Top-Level ............................ 2 Viewport (see Virtual Window) Virtual (see Virtual Window) Window Manager ....................... 7 Writing Attributes ................... 38 - 41 Writing Strings to ................... 30 - 46 Writing to File ...................... 70 - 71 Page 331 The C Window Library Page 331