documentation/consoles.sgml

   1   <chapter id="consoles">
   2     <title>Consoles in Wine</title>
   3
   4     <sect1 id="wine-consoles">
   5       <title>Consoles</title>
   6
   7       <para>
   8         Written by &name-eric-pouech; <email>&email-eric-pouech</email>
   9       </para>
  10
  11       <para>
  12         As described in the Wine User Guide's CUI section, Wine
  13         manipulates three kinds of "consoles" in order to support
  14         properly the Win32 CUI API.
  15       </para>
  16       <para>
  17         The following table describes the main implementation
  18         differences between the three approaches.
  19
  20         <table>
  21           <title>Fonction consoles implementation comparison</title>
  22           <tgroup cols="4" align="left">
  23             <thead>
  24               <row>
  25                 <entry>Function</entry>
  26                 <entry>Bare streams</entry>
  27                 <entry>Wineconsole &amp; user backend</entry>
  28                 <entry>Wineconsole &amp; curses backend</entry>
  29               </row>
  30             </thead>
  31             <tbody>
  32               <row>
  33                 <entry>
  34                   Console as a Win32 Object (and associated
  35                   handles)
  36                 </entry>
  37                 <entry>
  38                   No specific Win32 object is used in this case. The
  39                   handles manipulated for the standard Win32 streams
  40                   are in fact "bare handles" to their corresponding
  41                   Unix streams. The mode manipulation functions
  42                   (<function>GetConsoleMode</function> /
  43                   <function>SetConsoleMode</function>) are not
  44                   supported.
  45                 </entry>
  46                 <entry>
  47                   Implemented in server, and a specific Winelib
  48                   program (wineconsole) is in charge of the
  49                   rendering and user input. The mode manipulation
  50                   functions behave as expected.
  51                 </entry>
  52                 <entry>
  53                   Implemented in server, and a specific Winelib
  54                   program (wineconsole) is in charge of the
  55                   rendering and user input. The mode manipulation
  56                   functions behave as expected.
  57                 </entry>
  58               </row>
  59               <row>
  60                 <entry>
  61                   Inheritance (including handling in
  62                   <function>CreateProcess</function> of
  63                   <constant>CREATE_DETACHED</constant>,
  64                   <constant>CREATE_NEW_CONSOLE</constant> flags).
  65                 </entry>
  66                 <entry>
  67                   Not supported. Every process child of a process
  68                   will inherit the Unix streams, so will also
  69                   inherit the Win32 standard streams.
  70                 </entry>
  71                 <entry>
  72                   Fully supported (each new console creation will be
  73                   handled by the creation of a new USER32 window)
  74                 </entry>
  75                 <entry>
  76                   Fully supported, except for the creation of a new
  77                   console, which will be rendered on the same Unix
  78                   terminal as the previous one, leading to
  79                   unpredictible results.
  80                 </entry>
  81               </row>
  82               <row>
  83                 <entry><function>ReadFile</function> / <function>WriteFile</function> operations</entry>
  84                 <entry>Fully supported</entry>
  85                 <entry>Fully supported</entry>
  86                 <entry>Fully supported</entry>
  87               </row>
  88               <row>
  89                 <entry>
  90                   Screen-buffer manipulation (creation, deletion, resizing...)
  91                 </entry>
  92                 <entry>Not supported</entry>
  93                 <entry>Fully supported</entry>
  94                 <entry>
  95                   Partly supported (this won't work too well as we
  96                   don't control (so far) the size of underlying Unix
  97                   terminal
  98                 </entry>
  99               </row>
 100               <row>
 101                 <entry>
 102                   APIs for reading/writing screen-buffer content,
 103                   cursor position
 104                 </entry>
 105                 <entry>Not supported</entry>
 106                 <entry>Fully supported</entry>
 107                 <entry>Fully supported</entry>
 108               </row>
 109               <row>
 110                 <entry>
 111                   APIs for manipulating the rendering window size
 112                 </entry>
 113                 <entry>Not supported</entry>
 114                 <entry>Fully supported</entry>
 115                 <entry>
 116                   Partly supported (this won't work too well as we
 117                   don't control (so far) the size of underlying Unix
 118                   terminal
 119                 </entry>
 120               </row>
 121               <row>
 122                 <entry>
 123                   Signaling (in particular, Ctrl-C handling)
 124                 </entry>
 125                 <entry>
 126                   Nothing is done, which means that Ctrl-C will
 127                   generate (as usual) a <constant>SIGINT</constant>
 128                   which will terminate the program.
 129                 </entry>
 130                 <entry>
 131                   Partly supported (Ctrl-C behaves as expected,
 132                   however the other Win32 CUI signaling isn't
 133                   properly implemented).
 134                 </entry>
 135                 <entry>
 136                   Partly supported (Ctrl-C behaves as expected,
 137                   however the other Win32 CUI signaling isn't
 138                   properly implemented).
 139                 </entry>
 140               </row>
 141             </tbody>
 142           </tgroup>
 143         </table>
 144       </para>
 145     </sect1>
 146
 147     <sect1>
 148       <title>Console creation</title>
 149
 150       <para>
 151         The Win32 objects behind a console can be created in several occasions:
 152         <itemizedlist>
 153           <listitem>
 154             <para>
 155               When the program is started from wineconsole, a new
 156               console object is created and will be used (inherited)
 157               by the process launched from wineconsole.
 158             </para>
 159           </listitem>
 160           <listitem>
 161             <para>
 162               When a program, which isn't attached to a console, calls
 163               <function>AllocConsole</function>, Wine then launches
 164               wineconsole, and attaches the current program to this
 165               console. In this mode, the USER32 mode is always
 166               selected as Wine cannot tell the current state of the
 167               Unix console.
 168             </para>
 169           </listitem>
 170         </itemizedlist>
 171       </para>
 172       <para>
 173         Please also note, that starting a child process with the
 174         <constant>CREATE_NEW_CONSOLE</constant> flag, will end-up
 175         calling <function>AllocConsole</function> in the child
 176         process, hence creating a wineconsole with the USER32 backend.
 177       </para>
 178     </sect1>
 179   </chapter>
 180
 181 <!-- Keep this comment at the end of the file
 182 Local variables:
 183 mode: sgml
 184 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
 185 End:
 186 -->