documentation/running.sgml

   1   <chapter id="running">
   2     <title>Running Wine</title>
   3
   4     <para>
   5       This chapter will describe all aspects of running Wine, like e.g.
   6       basic Wine invocation, command line parameters of various Wine
   7       support programs etc.
   8     </para>
   9
  10     <sect1 id="basic-usage">
  11       <title>Basic usage: applications and control panel applets</title>
  12       <para>
  13         Assuming you are using a fake Windows installation, you install
  14         applications into Wine in the same way you would in Windows: by
  15         running the installer. You can just accept the defaults for
  16         where to install, most installers will default to "C:\Program
  17         Files", which is fine. If the application installer requests it,
  18         you may find that Wine creates icons on your desktop and in your
  19         app menu. If that happens, you can start the app by clicking on
  20         them.
  21       </para>
  22
  23       <para>
  24         The standard way to uninstall things is for the application to
  25         provide an uninstaller, usually registered with the "Add/Remove
  26         Programs" control panel applet.
  27         To access the Wine equivalent, run the <command>uninstaller</command>
  28         program (it is located in the
  29         <filename>programs/uninstaller/</filename> directory in a Wine
  30         source directory) in a <glossterm>terminal</glossterm>:
  31       </para>
  32
  33       <screen>
  34         <prompt>$</prompt> <userinput>uninstaller</userinput>
  35       </screen>
  36
  37       <para>
  38         Some programs install associated control panel applets, examples
  39         of this would be Internet Explorer and QuickTime. You can access
  40         the Wine control panel by running in a
  41         <glossterm>terminal</glossterm>:
  42       </para>
  43
  44       <screen>
  45          <prompt>$</prompt> <userinput>wine control</userinput>
  46       </screen>
  47
  48       <para>
  49         which will open a window with the installed control panel
  50         applets in it, as in Windows.
  51       </para>
  52
  53       <para>
  54         If the application doesn't install menu or desktop items, you'll
  55         need to run the app from the command line. Remembering where you
  56         installed to, something like:
  57       </para>
  58
  59       <screen>
  60          <prompt>$</prompt> <userinput>wine "c:\program files\appname\appname.exe"</userinput>
  61       </screen>
  62
  63       <para>
  64         will probably do the trick. The path isn't case sensitive, but
  65         remember to include the double quotes.  Some programs don't
  66         always use obvious naming for their directories and EXE files,
  67         so you might have to look inside the program files directory to
  68         see what was put where.
  69       </para>
  70     </sect1>
  71
  72     <sect1 id="running-wine">
  73       <title>How to run Wine</title>
  74
  75       <para>
  76         You can simply invoke the <command>wine</command> command to
  77         get a small help message:
  78       </para>
  79       <para>
  80         <screen>
  81 Wine 20040405
  82 Usage: wine PROGRAM [ARGUMENTS...]   Run the specified program
  83        wine --help                   Display this help and exit
  84        wine --version                Output version information and exit
  85         </screen>
  86       </para>
  87
  88       <para>
  89         The first argument should be the name of the file you
  90         want <command>wine</command> to execute.  If the executable is
  91         in the <parameter>Path</parameter> environment variable, you can
  92         simply give the executable file name. However, if the executable
  93         is not in <parameter>Path</parameter>, you must give the full path to
  94         the executable (in Windows format, not UNIX format!).  For
  95         example, given a <parameter>Path</parameter> of the following:
  96       </para>
  97       <screen>
  98 Path="c:\windows;c:\windows\system;e:\;e:\test;f:\"
  99       </screen>
 100       <para>
 101         You could run the file
 102         <filename>c:\windows\system\foo.exe</filename> with:
 103       </para>
 104       <screen>
 105 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
 106       </screen>
 107       <para>
 108         However, you would have to run the file
 109         <filename>c:\myapps\foo.exe</filename> with this command:
 110       </para>
 111       <screen>
 112 <prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
 113       </screen>
 114       <para>
 115       (note the backslash-escaped "\" !)
 116       </para>
 117       <para>
 118         For details on running text mode (CUI) executables, read the
 119         <link linkend="CUI-programs">section</link> below.
 120       </para>
 121     </sect1>
 122
 123     <sect1 id="explorer-like-wine">
 124       <title>Explorer-like graphical Wine environments</title>
 125
 126       <para>
 127         If you prefer using a graphical interface to manage your
 128         files you might want to consider using Winefile.  This Winelib
 129         application comes with Wine and can be found with the other
 130         Wine programs.  It is a useful way to view your drive configuration
 131         and locate files, plus you can execute programs directly from
 132         Winefile.  Please note, many functions are not yet implemented.
 133       </para>
 134     </sect1>
 135
 136     <sect1 id="command-line-options">
 137       <title>Wine Command Line Options</title>
 138
 139       <sect2>
 140         <title>--help</title>
 141         <para>
 142           Shows a small command line help page.
 143         </para>
 144       </sect2>
 145
 146       <sect2>
 147         <title>--version</title>
 148         <para>
 149           Shows the Wine version string. Useful to verify your installation.
 150         </para>
 151       </sect2>
 152     </sect1>
 153
 154     <sect1>
 155       <title>Environment variables</title>
 156       <sect2>
 157         <title>WINEDEBUG=[channels]</title>
 158         <para>
 159           Wine isn't perfect, and many Windows applications still
 160           don't run without bugs under Wine (but then, a lot of programs
 161           don't run without bugs under native Windows either!).  To
 162           make it easier for people to track down the causes behind
 163           each bug, Wine provides a number of <firstterm>debug
 164           channels</firstterm> that you can tap into.
 165         </para>
 166         <para>
 167           Each debug channel, when activated, will trigger logging
 168           messages to be displayed to the console where you invoked
 169           <command>wine</command>.  From there you can redirect the
 170           messages to a file and examine it at your leisure.  But be
 171           forewarned!  Some debug channels can generate incredible
 172           volumes of log messages.  Among the most prolific offenders
 173           are <parameter>relay</parameter> which spits out a log
 174           message every time a win32 function is called,
 175           <parameter>win</parameter> which tracks windows message
 176           passing, and of course <parameter>all</parameter> which is
 177           an alias for every single debug channel that exists.  For a
 178           complex application, your debug logs can easily top 1 MB and
 179           higher.  A <parameter>relay</parameter> trace can often
 180           generate more than 10 MB of log messages, depending on how
 181           long you run the application.  (As described in the
 182           <link linkend = "config-debug-etc">Debug</link>
 183           section of configuring wine you can
 184           modify what the <parameter>relay</parameter> trace reports).
 185           Logging does slow down Wine
 186           quite a bit, so don't use <parameter>WINEDEBUG</parameter>
 187           unless you really do want log files.
 188         </para>
 189         <para>
 190           Within each debug channel, you can further specify a
 191           <firstterm>message class</firstterm>, to filter out the
 192           different severities of errors.  The four message classes
 193           are:
 194           <simplelist type="inline">
 195             <member><parameter>trace</parameter></member>
 196             <member><parameter>fixme</parameter></member>
 197             <member><parameter>warn</parameter></member>
 198             <member><parameter>err</parameter></member>
 199           </simplelist>.
 200         </para>
 201         <para>
 202           To turn on a debug channel, use the form
 203           <parameter>class+channel</parameter>.  To turn it off, use
 204           <parameter>class-channel</parameter>.  To list more than one
 205           channel in the same <parameter>WINEDEBUG</parameter>
 206           option, separate them with commas.  For example, to request
 207           <parameter>warn</parameter> class messages in the
 208           <parameter>heap</parameter> debug channel, you could invoke
 209           <command>wine</command> like this:
 210         </para>
 211         <screen>
 212 <prompt>$</prompt> <userinput>WINEDEBUG=warn+heap wine <replaceable>program_name</replaceable></userinput>
 213         </screen>
 214         <para>
 215           If you leave off the message class, <command>wine</command>
 216           will display messages from all four classes for that channel:
 217         </para>
 218         <screen>
 219 <prompt>$</prompt> <userinput>WINEDEBUG=heap wine <replaceable>program_name</replaceable></userinput>
 220         </screen>
 221         <para>
 222           If you wanted to see log messages for everything except the
 223           relay channel, you might do something like this:
 224         </para>
 225         <screen>
 226 <prompt>$</prompt> <userinput>WINEDEBUG=+all,-relay wine <replaceable>program_name</replaceable></userinput>
 227         </screen>
 228         <para>
 229           Here is a list of the debug channels and classes in Wine.
 230           More channels will be added to (or subtracted from) later
 231           versions.
 232         </para>
 233
 234                 <table frame="none"><title>Debug Channels</title>
 235                 <tgroup cols=5 align="left">
 236                 <tbody>
 237 <row> <entry>accel</entry>  <entry>adpcm</entry>  <entry>advapi</entry>  <entry>animate</entry>  <entry>aspi</entry> </row>
 238 <row> <entry>atom</entry>  <entry>avicap</entry>  <entry>avifile</entry>  <entry>bidi</entry>  <entry>bitblt</entry> </row>
 239 <row> <entry>bitmap</entry>  <entry>cabinet</entry>  <entry>capi</entry>  <entry>caret</entry>  <entry>cdrom</entry> </row>
 240 <row> <entry>cfgmgr32</entry>  <entry>class</entry>  <entry>clipboard</entry>  <entry>clipping</entry>  <entry>combo</entry> </row>
 241 <row> <entry>comboex</entry>  <entry>comm</entry>  <entry>commctrl</entry>  <entry>commdlg</entry>  <entry>computername</entry> </row>
 242 <row> <entry>console</entry>  <entry>crtdll</entry>  <entry>crypt</entry>  <entry>curses</entry>  <entry>cursor</entry> </row>
 243 <row> <entry>d3d</entry>  <entry>d3d_shader</entry>  <entry>d3d_surface</entry>  <entry>datetime</entry>  <entry>dc</entry> </row>
 244 <row> <entry>ddeml</entry>  <entry>ddraw</entry>  <entry>ddraw_fps</entry>  <entry>ddraw_geom</entry>  <entry>ddraw_tex</entry> </row>
 245 <row> <entry>debugstr</entry>  <entry>devenum</entry>  <entry>dialog</entry>  <entry>dinput</entry>  <entry>dll</entry> </row>
 246 <row> <entry>dma</entry>  <entry>dmband</entry>  <entry>dmcompos</entry>  <entry>dmfile</entry>  <entry>dmfiledat</entry> </row>
 247 <row> <entry>dmime</entry>  <entry>dmloader</entry>  <entry>dmscript</entry>  <entry>dmstyle</entry>  <entry>dmsynth</entry> </row>
 248 <row> <entry>dmusic</entry>  <entry>dosfs</entry>  <entry>dosmem</entry>  <entry>dplay</entry>  <entry>dplayx</entry> </row>
 249 <row> <entry>dpnhpast</entry>  <entry>driver</entry>  <entry>dsound</entry>  <entry>dsound3d</entry>  <entry>edit</entry> </row>
 250 <row> <entry>enhmetafile</entry>  <entry>environ</entry>  <entry>event</entry>  <entry>eventlog</entry>  <entry>exec</entry> </row>
 251 <row> <entry>file</entry>  <entry>fixup</entry>  <entry>font</entry>  <entry>fps</entry>  <entry>g711</entry> </row>
 252 <row> <entry>gdi</entry>  <entry>global</entry>  <entry>glu</entry>  <entry>graphics</entry>  <entry>header</entry> </row>
 253 <row> <entry>heap</entry>  <entry>hook</entry>  <entry>hotkey</entry>  <entry>icmp</entry>  <entry>icon</entry> </row>
 254 <row> <entry>imagehlp</entry>  <entry>imagelist</entry>  <entry>imm</entry>  <entry>int</entry>  <entry>int21</entry> </row>
 255 <row> <entry>int31</entry>  <entry>io</entry>  <entry>ipaddress</entry>  <entry>iphlpapi</entry>  <entry>jack</entry> </row>
 256 <row> <entry>joystick</entry>  <entry>key</entry>  <entry>keyboard</entry>  <entry>listbox</entry>  <entry>listview</entry> </row>
 257 <row> <entry>loaddll</entry>  <entry>local</entry>  <entry>mapi</entry>  <entry>mci</entry>  <entry>mcianim</entry> </row>
 258 <row> <entry>mciavi</entry>  <entry>mcicda</entry>  <entry>mcimidi</entry>  <entry>mciwave</entry>  <entry>mdi</entry> </row>
 259 <row> <entry>menu</entry>  <entry>menubuilder</entry>  <entry>message</entry>  <entry>metafile</entry>  <entry>midi</entry> </row>
 260 <row> <entry>mmaux</entry>  <entry>mmio</entry>  <entry>mmsys</entry>  <entry>mmtime</entry>  <entry>module</entry> </row>
 261 <row> <entry>monthcal</entry>  <entry>mpeg3</entry>  <entry>mpr</entry>  <entry>msacm</entry>  <entry>msdmo</entry> </row>
 262 <row> <entry>msg</entry>  <entry>mshtml</entry>  <entry>msi</entry>  <entry>msimg32</entry>  <entry>msisys</entry> </row>
 263 <row> <entry>msrle32</entry>  <entry>msvcrt</entry>  <entry>msvideo</entry>  <entry>mswsock</entry>  <entry>nativefont</entry> </row>
 264 <row> <entry>netapi32</entry>  <entry>netbios</entry>  <entry>nls</entry>  <entry>nonclient</entry>  <entry>ntdll</entry> </row>
 265 <row> <entry>odbc</entry>  <entry>ole</entry>  <entry>oledlg</entry>  <entry>olerelay</entry>  <entry>opengl</entry> </row>
 266 <row> <entry>pager</entry>  <entry>palette</entry>  <entry>pidl</entry>  <entry>powermgnt</entry>  <entry>print</entry> </row>
 267 <row> <entry>process</entry>  <entry>profile</entry>  <entry>progress</entry>  <entry>propsheet</entry>  <entry>psapi</entry> </row>
 268 <row> <entry>psdrv</entry>  <entry>qcap</entry>  <entry>quartz</entry>  <entry>ras</entry>  <entry>rebar</entry> </row>
 269 <row> <entry>reg</entry>  <entry>region</entry>  <entry>relay</entry>  <entry>resource</entry>  <entry>richedit</entry> </row>
 270 <row> <entry>rundll32</entry>  <entry>sblaster</entry>  <entry>scroll</entry>  <entry>seh</entry>  <entry>selector</entry> </row>
 271 <row> <entry>server</entry>  <entry>setupapi</entry>  <entry>shdocvw</entry>  <entry>shell</entry>  <entry>shlctrl</entry> </row>
 272 <row> <entry>snmpapi</entry>  <entry>snoop</entry>  <entry>sound</entry>  <entry>static</entry>  <entry>statusbar</entry> </row>
 273 <row> <entry>storage</entry>  <entry>stress</entry>  <entry>string</entry>  <entry>syscolor</entry>  <entry>system</entry> </row>
 274 <row> <entry>tab</entry>  <entry>tape</entry>  <entry>tapi</entry>  <entry>task</entry>  <entry>text</entry> </row>
 275 <row> <entry>thread</entry>  <entry>thunk</entry>  <entry>tid</entry>  <entry>timer</entry>  <entry>toolbar</entry> </row>
 276 <row> <entry>toolhelp</entry>  <entry>tooltips</entry>  <entry>trackbar</entry>  <entry>treeview</entry>  <entry>ttydrv</entry> </row>
 277 <row> <entry>twain</entry>  <entry>typelib</entry>  <entry>uninstaller</entry>  <entry>updown</entry>  <entry>urlmon</entry> </row>
 278 <row> <entry>uxtheme</entry>  <entry>ver</entry>  <entry>virtual</entry>  <entry>vxd</entry>  <entry>wave</entry> </row>
 279 <row> <entry>wc_font</entry>  <entry>win</entry>  <entry>win32</entry>  <entry>wineboot</entry>  <entry>winecfg</entry> </row>
 280 <row> <entry>wineconsole</entry>  <entry>wine_d3d</entry>  <entry>winevdm</entry>  <entry>wing</entry>  <entry>winhelp</entry> </row>
 281 <row> <entry>wininet</entry>  <entry>winmm</entry>  <entry>winsock</entry>  <entry>winspool</entry>  <entry>wintab</entry> </row>
 282 <row> <entry>wintab32</entry>  <entry>wnet</entry>  <entry>x11drv</entry>  <entry>x11settings</entry>  <entry>xdnd</entry> </row>
 283 <row> <entry>xrandr</entry>  <entry>xrender</entry>  <entry>xvidmode</entry> </row>
 284                 </tbody>
 285                 </tgroup>
 286                 </table>
 287
 288         <para>
 289           For more details about debug channels, check out the
 290           <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
 291             The Wine Developer's Guide</ulink>.
 292         </para>
 293       </sect2>
 294     </sect1>
 295
 296     <sect1 id="wineserver-command-line-options">
 297       <title>wineserver Command Line Options</title>
 298
 299       <para>
 300         wineserver usually gets started automatically by Wine whenever
 301         the first wine process gets started.
 302         However, wineserver has some useful command line options that
 303         you can add if you start it up manually, e.g. via a user login
 304         script or so.
 305       </para>
 306
 307       <sect2 id="wineserver-config-parameter">
 308         <title>-d&lt;n&gt;</title>
 309         <para>
 310           Sets the debug level for debug output in the terminal that
 311           wineserver got started in at level &lt;n&gt;.
 312           In other words: everything greater than 0 will enable
 313           wineserver specific debugging output.
 314         </para>
 315       </sect2>
 316
 317       <sect2>
 318         <title>-h</title>
 319         <para>
 320           Display wineserver command line options help message.
 321         </para>
 322       </sect2>
 323
 324       <sect2>
 325         <title>-k[n]</title>
 326         <para>
 327           Kill the current wineserver, optionally with signal n.
 328         </para>
 329       </sect2>
 330
 331       <sect2>
 332         <title>-p[n]</title>
 333         <para>
 334           This parameter makes wineserver persistent, optionally for n
 335           seconds. It will prevent wineserver from shutting down immediately.
 336         </para>
 337         <para>
 338           Usually, wineserver quits almost immediately after the last
 339           wine process using this wineserver terminated.
 340           However, since wineserver loads a lot of things on startup
 341           (such as the whole Windows registry data), its startup might
 342           be so slow that it's very useful to keep it from exiting after
 343           the end of all Wine sessions, by making it persistent.
 344         </para>
 345       </sect2>
 346
 347       <sect2>
 348         <title>-w</title>
 349         <para>
 350           This parameter makes a newly started wineserver wait until the
 351           currently active wineserver instance terminates.
 352         </para>
 353       </sect2>
 354     </sect1>
 355
 356     <sect1 id="environment-variables">
 357       <title>Setting Windows/DOS environment variables</title>
 358       <para>
 359         Your program might require some environment variable to be set
 360         properly in order to run successfully.
 361         In this case you need to set this environment variable in the
 362         Linux shell, since Wine will pass on the entire shell environment
 363         variable settings to the Windows environment variable space.
 364         Example for the bash shell (other shells may have a different syntax
 365         !):
 366         <screen>
 367           export MYENVIRONMENTVAR=myenvironmentvarsetting
 368         </screen>
 369         This will make sure your Windows program can access the
 370         MYENVIRONMENTVAR environment variable once you start your program
 371         using Wine.
 372         If you want to have MYENVIRONMENTVAR set permanently, then you can
 373         place the setting into /etc/profile, or also ~/.bashrc in the case of
 374         bash.
 375       </para>
 376       <para>Note however that there are some exceptions to the rule:
 377         If you want to change the PATH, SYSTEM or TEMP variables, the of course
 378         you can't modify it that way, since this will alter the Unix environment
 379         settings. Instead, you should set them into the registry. To set them
 380         you should launch <userinput>wine regedit</userinput> and then go to the
 381         <screen>HKEY_CURRENT_USER/Environment</screen> key. Now you can create
 382         or modify the values of the variables you need
 383       </para>
 384       <para>
 385         <programlisting>"System" = "c:\\windows\\system"</programlisting>
 386         This sets up where the windows system files are. The Windows
 387           system directory should reside below the directory used for the
 388         <literal>Windows</literal> setting.
 389           Thus when using /usr/local/wine_c_windows as Windows path,
 390           the system directory would be
 391           <filename>/usr/local/wine_c/windows/system</filename>.
 392         It must be set with no trailing slash, and you must be sure that
 393         you have write access to it.
 394       </para>
 395       <para>
 396         <programlisting>"Temp" = "c:\\temp"</programlisting> This should
 397         be the directory you want your temp files stored in,
 398           /usr/local/wine_c/temp in our previous example.
 399         Again, no trailing slash, and <emphasis>write
 400           access</emphasis>!!
 401       </para>
 402       <para>
 403         <programlisting>"Path" = "c:\\windows;c:\\windows\\system;c:\\blanco"</programlisting>
 404         Behaves like the <envar>PATH</envar> setting on UNIX
 405         boxes. When wine is run like <userinput>wine
 406           sol.exe</userinput>, if <filename>sol.exe</filename>
 407         resides in a directory specified in the
 408         <literal>Path</literal> setting, wine will run it (Of
 409         course, if <filename>sol.exe</filename> resides in the
 410         current directory, wine will run that one). Make sure it
 411         always has your <filename>windows</filename> directory and
 412         system directory (For this setup, it must have
 413         <filename>"c:\\windows;c:\\windows\\system"</filename>).
 414       </para>
 415     </sect1>
 416
 417     <sect1 id="CUI-programs">
 418       <title>Text mode programs (CUI: Console User Interface)</title>
 419       <para>Text mode programs are program which output is only made
 420         out of text (surprise!). In Windows terminology, they are
 421         called CUI (Console User Interface) executables, by opposition
 422         to GUI (Graphical User Interface) executables. Win32 API
 423         provide a complete set of APIs to handle this situation, which
 424         goes from basic features like text printing, up to high level
 425         functionalities (like full screen editing, color support,
 426         cursor motion, mouse support), going through features like
 427         line editing or raw/cooked input stream support
 428       </para>
 429       <para>
 430         Given the wide scope of features above, and the current usage
 431         in Un*x world, Wine comes out with three different ways for
 432         running a console program (aka a CUI executable):
 433         <itemizedlist>
 434           <listitem>
 435             <para>
 436               bare streams
 437             </para>
 438           </listitem>
 439           <listitem>
 440             <para>
 441               wineconsole with user backend
 442             </para>
 443           </listitem>
 444           <listitem>
 445             <para>
 446               wineconsole with curses backend
 447             </para>
 448           </listitem>
 449         </itemizedlist>
 450       </para>
 451       <para>The names here are a bit obscure. "bare streams" means
 452         that no extra support of wine is provide to map between the
 453         unix console access and Windows console access. The two other
 454         ways require the use of a specific Wine program (wineconsole)
 455         which provide extended facilities. The following table
 456         describes what you can do (and cannot do) with those three
 457         ways.
 458         <table>
 459           <title>Basic differences in consoles</title>
 460           <tgroup cols="4" align="left">
 461             <thead>
 462               <row>
 463                 <entry>Function</entry>
 464                 <entry>Bare streams</entry>
 465                 <entry>Wineconsole &amp; user backend</entry>
 466                 <entry>Wineconsole &amp; curses backend</entry>
 467                 </row>
 468             </thead>
 469             <tbody>
 470               <row>
 471                 <entry>How to run (assuming executable is called foo.exe)</entry>
 472                 <entry><msgtext>
 473 <screen><prompt>$</prompt> <userinput>wine foo.exe</userinput></screen>
 474                   </msgtext></entry>
 475                 <entry><msgtext>
 476 <screen><prompt>$</prompt> <userinput>wineconsole -- --backend=user foo.exe</userinput></screen>
 477                 </msgtext></entry>
 478                 <entry><msgtext>
 479 <screen><prompt>$</prompt> <userinput>wineconsole foo.exe</userinput></screen>
 480                 </msgtext>You can also use --backend=curses as an option</entry>
 481               </row>
 482               <row>
 483                 <entry>Good support for line oriented CUI applications
 484                   (which print information line after line)
 485                   </entry>
 486                 <entry>Yes</entry>
 487                 <entry>Yes</entry>
 488                 <entry>Yes</entry>
 489               </row>
 490               <row>
 491                 <entry>Good support for full screen CUI
 492                   applications (including but not limited to color
 493                   support, mouse support...)</entry>
 494                 <entry>No</entry>
 495                 <entry>Yes</entry>
 496                 <entry>Yes</entry>
 497               </row>
 498               <row>
 499                 <entry>Can be run even if X11 is not running</entry>
 500                 <entry>Yes</entry>
 501                 <entry>No</entry>
 502                 <entry>Yes</entry>
 503               </row>
 504               <row>
 505                 <entry>Implementation</entry>
 506                 <entry>Maps the standard Windows streams to the
 507                   standard Unix streams (stdin/stdout/stderr)
 508                 </entry>
 509                 <entry>
 510                   Wineconsole will create a new Window (hence
 511                   requiring the USER32 DLL is available) where all
 512                   information will be displayed
 513                 </entry>
 514                 <entry>
 515                   Wineconsole will use existing unix console
 516                   (from which the program is run) and with the help of
 517                   the (n)curses library take control of all the terminal
 518                   surface for interacting with the user
 519                 </entry>
 520               </row>
 521               <row>
 522                 <entry>Known limitations</entry>
 523                 <entry></entry>
 524                 <entry></entry>
 525                 <entry>
 526                   Will produce strange behavior if two (or more)
 527                   Windows consoles are used on the same Un*x terminal.
 528                 </entry>
 529               </row>
 530             </tbody>
 531           </tgroup>
 532         </table>
 533       </para>
 534       <sect2 id="CUI-programs-config">
 535         <title>Configuration of CUI executables</title>
 536         <para>
 537           When wineconsole is used, several configuration options are
 538           available. Wine (as Windows do) stores, on a per application
 539           basis, several options in the registry. This let a user, for
 540           example, define the default screen-buffer size he would like
 541           to have for a given application.
 542         </para>
 543         <para>
 544           As of today, only the USER backend allows you to edit those
 545           options (we don't recommend editing by hand the registry
 546           contents). This edition is fired when a user right click in
 547           the console (this popups a menu), where you can either
 548           choose from:
 549           <itemizedlist>
 550             <listitem>
 551               <para>
 552                 Default: this will edit the settings shared by all
 553                 applications which haven't been configured yet. So,
 554                 when an application is first run (on your machine,
 555                 under your account) in wineconsole, wineconsole will
 556                 inherit this default settings for the
 557                 application. Afterwards, the application will have its
 558                 own settings, that you'll be able to modify at your will.
 559               </para>
 560               <para>
 561                 Properties: this will edit the application's
 562                 settings. When you're done, with the edition, you'll
 563                 be prompted whether you want to:
 564                 <orderedlist>
 565                   <listitem>
 566                     <para>
 567                       Keep these modified settings only for this
 568                       session (next time you run the application, you
 569                       will not see the modification you've just made).
 570                     </para>
 571                   </listitem>
 572                   <listitem>
 573                     <para>
 574                       Use the settings for this session and save them
 575                       as well, so that next you run your application,
 576                       you'll use these new settings again.
 577                     </para>
 578                   </listitem>
 579                 </orderedlist>
 580               </para>
 581             </listitem>
 582           </itemizedlist>
 583         </para>
 584         <para>
 585           Here's the list of the items you can configure, and their
 586           meanings:
 587           <table>
 588             <title>Wineconsole configuration options</title>
 589             <tgroup cols="2" align="left">
 590               <thead>
 591                 <row>
 592                   <entry>Configuration option</entry>
 593                   <entry>Meaning</entry>
 594                 </row>
 595               </thead>
 596               <tbody>
 597                 <row>
 598                   <entry>Cursor's size</entry>
 599                   <entry>
 600                     Defines the size of the cursor. Three options are
 601                     available: small (33% of character height), medium
 602                     (66%) and large (100%)
 603                   </entry>
 604                 </row>
 605                 <row>
 606                   <entry>Popup menu</entry>
 607                   <entry>
 608                     It's been said earlier that wineconsole
 609                     configuration popup was triggered using a right
 610                     click in the console's window. However, this can
 611                     be an issue when the application you run inside
 612                     wineconsole expects the right click events to be
 613                     sent to it. By ticking control or shift you select
 614                     additional modifiers on the right click for
 615                     opening the popup. For example, ticking shift will
 616                     send events to the application when you right
 617                     click the window without shift being hold down,
 618                     and open the window when you right-click while
 619                     shift being hold down.
 620                   </entry>
 621                 </row>
 622                 <row>
 623                   <entry>Quick edit</entry>
 624                   <entry>
 625                     This tick box lets you decide whether left-click
 626                     mouse events shall be interpreted as events to be
 627                     sent to the underlying application (tick off) or
 628                     as a selection of rectangular part of the screen
 629                     to be later on copied onto the clipboard (tick on).
 630                   </entry>
 631                 </row>
 632                 <row>
 633                   <entry>History</entry>
 634                   <entry>
 635                     This lets you pick up how many commands you want
 636                     the console to recall. You can also drive whether
 637                     you want, when entering several times the same
 638                     command - potentially intertwined with others -
 639                     whether you want to store all of them (tick off)
 640                     or only the last one (tick on).
 641                   </entry>
 642                 </row>
 643                 <row>
 644                   <entry>Police</entry>
 645                   <entry>
 646                     The Police property sheet allows you to pick the
 647                     default font for the console (font file, size,
 648                     background and foreground color).
 649                   </entry>
 650                 </row>
 651                 <row>
 652                   <entry>Screenbuffer &amp; window size</entry>
 653                   <entry>
 654                     The console as you see it is made of two different
 655                     parts. On one hand there's the screenbuffer which
 656                     contains all the information your application puts
 657                     on the screen, and the window which displays a
 658                     given area of this screen buffer. Note that the
 659                     window is always smaller or of the same size than
 660                     the screen buffer. Having a strictly smaller window
 661                     size will put on scrollbars on the window so that
 662                     you can see the whole screenbuffer's content.
 663                   </entry>
 664                 </row>
 665                 <row>
 666                   <entry>Close on exit</entry>
 667                   <entry>
 668                     If it's ticked, then the wineconsole will exit
 669                     when the application within terminates. Otherwise,
 670                     it'll remain opened until the user manually closes
 671                     it: this allows seeing the latest information of a
 672                     program after it has terminated.
 673                   </entry>
 674                 </row>
 675                 <row>
 676                   <entry>Edition mode</entry>
 677                   <entry>
 678                     <msgtext>
 679                       <para>
 680                         When the user enter commands, he or she can
 681                         choose between several edition modes:
 682                         <itemizedlist>
 683                           <listitem>
 684                             <para>
 685                               Emacs: the same keybindings as under
 686                               emacs are available. For example, Ctrl-A
 687                               will bring the cursor to the beginning
 688                               of the edition line. See your emacs
 689                               manual for the details of the commands.
 690                             </para>
 691                           </listitem>
 692                           <listitem>
 693                             <para>
 694                               Win32: these are the standard Windows
 695                               console key-bindings (mainly using
 696                               arrows).
 697                             </para>
 698                           </listitem>
 699                         </itemizedlist>
 700                       </para>
 701                     </msgtext>
 702                   </entry>
 703                 </row>
 704               </tbody>
 705             </tgroup>
 706           </table>
 707         </para>
 708       </sect2>
 709     </sect1>
 710   </chapter>
 711
 712 <!-- Keep this comment at the end of the file
 713 Local variables:
 714 mode: sgml
 715 sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")
 716 End:
 717 -->