From 66f1725428e5c9c27ea651fbe0ef9028f13adc48 Mon Sep 17 00:00:00 2001 From: "Dimitrie O. Paun" Date: Fri, 30 Jan 2004 22:58:26 +0000 Subject: [PATCH] Move keyboard programming instructions to the Devel Guide. Cleanup up a bunch of bits that don't belong in a book. --- documentation/configuring.sgml | 239 ++---------------------------- documentation/fonts.sgml | 3 - documentation/implementation.sgml | 171 +++++++++++++++++++++ documentation/printing.sgml | 55 ------- documentation/registry.sgml | 6 +- documentation/running.sgml | 21 +-- 6 files changed, 183 insertions(+), 312 deletions(-) diff --git a/documentation/configuring.sgml b/documentation/configuring.sgml index dfc3ed73919..3713a4da057 100644 --- a/documentation/configuring.sgml +++ b/documentation/configuring.sgml @@ -169,12 +169,8 @@ script called winecheck, to be found in Wine's tools/ directory. It tries to check your configuration's correctness by checking for some popular - problems. - - The latest version can always be found at - http://home.arcor.de/andi.mohr/download/winecheck. - - To run it, run in a terminal in the Wine source tree directory: + problems. To run it, run in a terminal + in the Wine source tree directory: $ cd tools @@ -182,9 +178,8 @@ The winecheck output will be a percentage score indicating Wine - configuration correctness. - Note that winecheck is only alpha, so it's not very complete or - 100% accurate. + configuration correctness. Please note that winecheck is not + 100% accurate. @@ -2830,196 +2825,12 @@ release! These entries/sections are: - -Keyboard - - -Wine now needs to know about your keyboard layout. This -requirement comes from a need from many apps to have the -correct scancodes available, since they read these directly, -instead of just taking the characters returned by the X -server. This means that Wine now needs to have a mapping from -X keys to the scancodes these programs expect. - - -On startup, Wine will try to recognize the active X layout by -seeing if it matches any of the defined tables. If it does, -everything is alright. If not, you need to define it. - - -To do this, open the file -dlls/x11drv/keyboard.c and take a look -at the existing tables. Make a backup copy of it, especially -if you don't use CVS. - - -What you really would need to do, is find out which scancode -each key needs to generate. Find it in the -main_key_scan table, which looks like -this: - - -static const int main_key_scan[MAIN_LEN] = -{ -/* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */ -0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D, -0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B, -0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B, -0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35, -0x56 /* the 102nd key (actually to the right of l-shift) */ -}; - - -Next, assign each scancode the characters imprinted on the -keycaps. This was done (sort of) for the US 101-key keyboard, -which you can find near the top in -keyboard.c. It also shows that if there -is no 102nd key, you can skip that. - - -However, for most international 102-key keyboards, we have -done it easy for you. The scancode layout for these already -pretty much matches the physical layout in the -main_key_scan, so all you need to do is -to go through all the keys that generate characters on your -main keyboard (except spacebar), and stuff those into an -appropriate table. The only exception is that the 102nd key, -which is usually to the left of the first key of the last line -(usually Z), must be placed on a separate -line after the last line. - - -For example, my Norwegian keyboard looks like this - - -§ ! " # ¤ % & / ( ) = ? ` Back- -| 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space - -Tab Q W E R T Y U I O P Å ^ - ¨~ - Enter -Caps A S D F G H J K L Ø Æ * -Lock ' - -Sh- > Z X C V B N M ; : _ Shift -ift < , . - - -Ctrl Alt Spacebar AltGr Ctrl - - -Note the 102nd key, which is the <> key, to -the left of Z. The character to the right of -the main character is the character generated by -AltGr. - - -This keyboard is defined as follows: - - -static const char main_key_NO[MAIN_LEN][4] = -{ -"|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´", -"qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~", -"aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*", -"zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_", -"<>" -}; - - -Except that " and \ needs to be quoted with a backslash, and -that the 102nd key is on a separate line, it's pretty -straightforward. - - -After you have written such a table, you need to add it to the -main_key_tab[] layout index table. This -will look like this: - - -static struct { -WORD lang, ansi_codepage, oem_codepage; -const char (*key)[MAIN_LEN][4]; -} main_key_tab[]={ -... -... -{MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO}, -... - - -After you have added your table, recompile Wine and test that -it works. If it fails to detect your table, try running - - -wine --debugmsg +key,+keyboard >& key.log - - - and look in the resulting key.log file to - find the error messages it gives for your layout. - - - Note that the LANG_* and - SUBLANG_* definitions are in - include/winnls.h, which you might need to - know to find out which numbers your language is assigned, and - find it in the debugmsg output. The numbers will be - (SUBLANG * 0x400 + LANG), so, for example - the combination LANG_NORWEGIAN (0x14) and - SUBLANG_DEFAULT (0x1) will be (in hex) - 14 + 1*400 = 414, so since I'm Norwegian, I - could look for 0414 in the debugmsg output - to find out why my keyboard won't detect. - - - Once it works, submit it to the Wine project. If you use CVS, - you will just have to do - - -cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff - - - from your main Wine directory, then submit - layout.diff to - wine-patches@winehq.org along with a brief note - of what it is. - - - If you don't use CVS, you need to do - - -diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff - - - and submit it as explained above. - - - If you did it right, it will be included in the next Wine - release, and all the troublesome programs (especially - remote-control programs) and games that use scancodes will - be happily using your keyboard layout, and you won't get those - annoying fixme messages either. - - - Good luck. - - - SCSI Support This file describes setting up the Windows ASPI interface. - - - - Warning/Warning/Warning!!!!!! - This may trash your system if used incorrectly. It may - even trash your system when used correctly! - - - - - - Now that I have said that. ASPI is a direct link to SCSI devices from - windows programs. ASPI just forwards the SCSI commands that programs send + ASPI is a direct link to SCSI devices from windows programs. + ASPI just forwards the SCSI commands that programs send to it to the SCSI bus. @@ -3033,22 +2844,17 @@ diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff have their permissions set as restricted as possible! - - Cookbook for setting up scanner: (At least how mine is to work) - (well, for other devices such as CD burners, MO drives, ..., too) - - Windows requirements - The scanner software needs to use the "Adaptec" + The software needs to use the "Adaptec" compatible drivers (ASPI). At least with Mustek, they allow you the choice of using the built-in card or the "Adaptec (AHA)" compatible drivers. This will not work any other way. Software that accesses the scanner via a - DOS ASPI driver (e.g. ASPI2DOS) is supported, too. [AM] + DOS ASPI driver (e.g. ASPI2DOS) is supported, too. @@ -3136,28 +2942,9 @@ diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff - General Information - - The mustek scanner I have was shipped with a package - "ipplus". This program uses the TWAIN driver specification - to access scanners. - - - (TWAIN MANAGER) - - - -ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> WINASPI - - - - - - NOTES/BUGS + Notes The biggest drawback is that it only works under Linux at the moment. - - The ASPI code has only been tested with: @@ -3181,19 +2968,13 @@ ipplus.exe <-> (TWAIN INTERFACE) <-> (TWAIN DATA SOURCE.ASPI) -> - - I make no warranty to the ASPI code. It makes my scanner - work. Your devices may explode. I have no way of determining - this. I take zero responsibility! - Using ODBC - This section describes how ODBC works within Wine and how to configure - it to do what you want (if it can do what you want). + This section describes how ODBC works within Wine and how to configure it. The ODBC system within Wine, as with the printing system, is designed diff --git a/documentation/fonts.sgml b/documentation/fonts.sgml index a1e2000e3be..ac3b1c57c02 100644 --- a/documentation/fonts.sgml +++ b/documentation/fonts.sgml @@ -489,9 +489,6 @@ FontPath "tcp/localhost:7100" - - Hope this helps... - diff --git a/documentation/implementation.sgml b/documentation/implementation.sgml index 4ace0181b2d..2a1d0da8098 100644 --- a/documentation/implementation.sgml +++ b/documentation/implementation.sgml @@ -2,6 +2,177 @@ Low-level Implementation Details of Wine's Low-level Implementation... + +Keyboard + + +Wine now needs to know about your keyboard layout. This +requirement comes from a need from many apps to have the +correct scancodes available, since they read these directly, +instead of just taking the characters returned by the X +server. This means that Wine now needs to have a mapping from +X keys to the scancodes these programs expect. + + +On startup, Wine will try to recognize the active X layout by +seeing if it matches any of the defined tables. If it does, +everything is alright. If not, you need to define it. + + +To do this, open the file +dlls/x11drv/keyboard.c and take a look +at the existing tables. Make a backup copy of it, especially +if you don't use CVS. + + +What you really would need to do, is find out which scancode +each key needs to generate. Find it in the +main_key_scan table, which looks like +this: + + +static const int main_key_scan[MAIN_LEN] = +{ +/* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */ +0x29,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0A,0x0B,0x0C,0x0D, +0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0x1A,0x1B, +0x1E,0x1F,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,0x2B, +0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35, +0x56 /* the 102nd key (actually to the right of l-shift) */ +}; + + +Next, assign each scancode the characters imprinted on the +keycaps. This was done (sort of) for the US 101-key keyboard, +which you can find near the top in +keyboard.c. It also shows that if there +is no 102nd key, you can skip that. + + +However, for most international 102-key keyboards, we have +done it easy for you. The scancode layout for these already +pretty much matches the physical layout in the +main_key_scan, so all you need to do is +to go through all the keys that generate characters on your +main keyboard (except spacebar), and stuff those into an +appropriate table. The only exception is that the 102nd key, +which is usually to the left of the first key of the last line +(usually Z), must be placed on a separate +line after the last line. + + +For example, my Norwegian keyboard looks like this + + +§ ! " # ¤ % & / ( ) = ? ` Back- +| 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space + +Tab Q W E R T Y U I O P Å ^ + ¨~ + Enter +Caps A S D F G H J K L Ø Æ * +Lock ' + +Sh- > Z X C V B N M ; : _ Shift +ift < , . - + +Ctrl Alt Spacebar AltGr Ctrl + + +Note the 102nd key, which is the <> key, to +the left of Z. The character to the right of +the main character is the character generated by +AltGr. + + +This keyboard is defined as follows: + + +static const char main_key_NO[MAIN_LEN][4] = +{ +"|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´", +"qQ","wW","eE","rR","tT","yY","uU","iI","oO","pP","åÅ","¨^~", +"aA","sS","dD","fF","gG","hH","jJ","kK","lL","øØ","æÆ","'*", +"zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_", +"<>" +}; + + +Except that " and \ needs to be quoted with a backslash, and +that the 102nd key is on a separate line, it's pretty +straightforward. + + +After you have written such a table, you need to add it to the +main_key_tab[] layout index table. This +will look like this: + + +static struct { +WORD lang, ansi_codepage, oem_codepage; +const char (*key)[MAIN_LEN][4]; +} main_key_tab[]={ +... +... +{MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO}, +... + + +After you have added your table, recompile Wine and test that +it works. If it fails to detect your table, try running + + +wine --debugmsg +key,+keyboard >& key.log + + + and look in the resulting key.log file to + find the error messages it gives for your layout. + + + Note that the LANG_* and + SUBLANG_* definitions are in + include/winnls.h, which you might need to + know to find out which numbers your language is assigned, and + find it in the debugmsg output. The numbers will be + (SUBLANG * 0x400 + LANG), so, for example + the combination LANG_NORWEGIAN (0x14) and + SUBLANG_DEFAULT (0x1) will be (in hex) + 14 + 1*400 = 414, so since I'm Norwegian, I + could look for 0414 in the debugmsg output + to find out why my keyboard won't detect. + + + Once it works, submit it to the Wine project. If you use CVS, + you will just have to do + + +cvs -z3 diff -u dlls/x11drv/keyboard.c > layout.diff + + + from your main Wine directory, then submit + layout.diff to + wine-patches@winehq.org along with a brief note + of what it is. + + + If you don't use CVS, you need to do + + +diff -u the_backup_file_you_made dlls/x11drv/keyboard.c > layout.diff + + + and submit it as explained above. + + + If you did it right, it will be included in the next Wine + release, and all the troublesome programs (especially + remote-control programs) and games that use scancodes will + be happily using your keyboard layout, and you won't get those + annoying fixme messages either. + + + + Undocumented APIs diff --git a/documentation/printing.sgml b/documentation/printing.sgml index 441a57a197b..65a9cf6fd19 100644 --- a/documentation/printing.sgml +++ b/documentation/printing.sgml @@ -208,61 +208,6 @@ - - TODO / Bugs - - - - - Driver does read PPD files, but ignores all constraints - and doesn't let you specify whether you have optional - extras such as envelope feeders. You will therefore find - a larger than normal selection of input bins in the - print setup dialog box. I've only really tested ppd - parsing on the hp4m6_v1.ppd file. - - - - - No TrueType download. - - - - - StretchDIBits uses level 2 PostScript. - - - - - AdvancedSetup dialog box. - - - - - Many partially implemented functions. - - - - - ps.c is becoming messy. - - - - - Notepad often starts text too far to the left depending - on the margin settings. However the win3.1 - pscript.drv (under wine) also does - this. - - - - - Probably many more... - - - - - diff --git a/documentation/registry.sgml b/documentation/registry.sgml index 1b786898ca2..871b961e0de 100644 --- a/documentation/registry.sgml +++ b/documentation/registry.sgml @@ -1,14 +1,10 @@ The Registry - - Originally written by Ove Kåven - - After Win3.x, the registry became a fundamental part of Windows. It is the place where both Windows itself, and all - Win95/98/NT/2000/whatever-compliant applications, store + Win95/98/NT/2000/XP/etc.-compliant applications, store configuration and state data. While most sane system administrators (and Wine developers) curse badly at the twisted nature of the Windows registry, it is still necessary for Wine diff --git a/documentation/running.sgml b/documentation/running.sgml index 27626f3e980..dfabad2fd7f 100644 --- a/documentation/running.sgml +++ b/documentation/running.sgml @@ -7,16 +7,6 @@ support programs etc. - - This chapter will describe all aspects of running Wine, like e.g. - basic Wine invocation, command line parameters of various Wine - support programs etc. - - - - - - Basic usage: applications and control panel applets @@ -75,21 +65,12 @@ remember to include the double quotes. Some programs don't always use obvious naming for their directories and EXE files, so you might have to look inside the program files directory to - see what it put where. + see what was put where. How to run Wine - - Wine is a very complicated piece of software with many ways to - adjust how it runs. With very few exceptions, you can - activate the same set of features through the configuration file as you can - with command-line parameters. In this chapter, we'll briefly - discuss these parameters, and match them up with their - corresponding configuration variables. - You can invoke the wine --help command to