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