documentation/dlls.sgml

  <chapter id="dlls">
    <title>Wine Builtin DLLs Overview</title>
    <para>A more detailed look at Wine's builtin DLLs...</para>

    <sect1 id="common-controls">
      <title>Common Controls</title>

      <!-- FIXME: Huh? Subtitle element not available here?!? -->
      <bridgehead renderas="sect3">
        Their development status and their UNDOCUMENTED features and functions
      </bridgehead>

      <para>
        Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
      </para>
      <para>
        (Extracted from <filename>wine/documentation/common_controls</filename>)
      </para>


      <sect2>
        <title>1. Introduction</title>

        <para>
          The information provided herein is based on the dll version
          4.72 which is included in MS Internet Explorer 4.01.
        </para>
        <para>
          All information about common controls should be collected in this document.
        </para>
        <para>
          All Wine programmers are encouraged to add their knowledge to this document.
        </para>
      </sect2>

      <sect2>
        <title>2. General Information</title>

        <para>
          Further information about common controls can be found in
          the MS Platform SDK and the MS Internet Client SDK (most
          recent). Information from these SDK's will NOT be repeated
          here. Only information which can NOT be found in these SDK's
          will be collected here. Some information in the SDK's
          mentioned above is (intentionally???) WRONG. Corrections to
          wrong information will be collected here too.
        </para>

        <sect3>
          <title>2.1 Structure sizes of different common control versions</title>

          <para>
            The common controls have been continously improved in the
            past. Some of the orignal structures had to be extended
            and their size changed. Most of the common control
            structures include their size as the first parameter. If a
            control gets the wrong size in a message or function a
            failure is very likely to occur. To avoid this, MS defined
            new constants that reflect the structure size of older
            <filename>COMCTL32.DLL</filename> versions. The following
            list shows the structure size constants that are currently
            defined in the original <filename>COMCTL32.DLL</filename>.
          </para>
          <note>
            <para>
              Some stuctures are NOT defined in wine's COMCTL32 yet.
            </para>
          </note>

          <variablelist>
            <varlistentry>
              <term><varname>HDITEM_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the <structname>HDITEM</structname>
                  structure in version 4.00.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>LVCOLUMN_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>LVCOLUMN</structname> structure in
                  version 4.00.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>LVHITTESTINFO_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>LVHITTESTINFO</structname> structure in
                  version 4.00.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>LVITEM_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the <structname>LVITEM</structname>
                  structure in version 4.00.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>NMLVCUSTOMDRAW_V3_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>NMLVCUSTOMDRAW</structname> structure in
                  version 4.70.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>NMTTDISPINFO_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>NMTTDISPINFO</structname> structure in
                  version 4.00.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>NMTVCUSTOMDRAW_V3_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>NMTVCUSTOMDRAW</structname> structure in
                  version 4.70.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>PROPSHEETHEADER_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>PROPSHEETHEADER</structname> structure
                  in version 4.00.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>PROPSHEETPAGE_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>PROPSHEETPAGE</structname> structure in
                  version 4.00.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>REBARBANDINFO_V3_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>REBARBANDINFO</structname> structure in
                  version 4.70.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>TTTOOLINFO_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>TOOLINFO</structname> structure in
                  version 4.00.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term><varname>TVINSERTSTRUCT_V1_SIZE</varname>:</term>
              <listitem>
                <para>The size of the
                  <structname>TVINSERTSTRUCT</structname> structure in
                  version 4.00.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>
      </sect2>

      <sect2>
        <title>3. Controls</title>

        <para>
          This section describes the development status of the common controls.
        </para>

        <sect3>
          <title>3.1 Animation Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Dummy control. No functionality.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>  Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>  
          </variablelist>
        </sect3>

        <sect3>
          <title>3.2 Combo Box Ex Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Dummy control. No functionality.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.3 Date and Time Picker Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Dummy control. No functionality.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.4 Drag List Box Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Dummy control. No functionality.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.5 Flat Scroll Bar Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Dummy written by &name-alex-priem; <email>&email-alex-priem;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Dummy control. No functionality.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.6 Header Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <itemizedlist>
                  <listitem>
                    <para>Almost finished.</para>
                  </listitem>
                  <listitem>
                    <para>Unicode notifications are not supported (WM_NOTIFYFORMAT).</para>
                  </listitem>
                  <listitem>
                    <para>Order array not supported.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.7 Hot Key Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Dummy control. No functionality.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.8 Image List (no control)</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Almost finished.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.9 IP Address Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                 <para>
                  Dummy written by &name-eric-kohl; <email>&email-eric-kohl;</email>,
                  &name-alex-priem; <email>&email-alex-priem;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Under construction.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.10 List View Control</title>

          <variablelist>
            <varlistentry>
            <term>Author:</term>
              <listitem>
                <para>Dummy written by: </para>
                <itemizedlist>
                  <listitem>
                    <para>
                      Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                    </para>
                  </listitem>
                  <listitem>
                    <para>&name-luc-tourangeau; <email>&email-luc-tourangeau;</email></para>
                  </listitem>
                  <listitem>
                    <para>&name-koen-deforche; <email>&email-koen-deforche;</email></para>
                  </listitem>
                  <listitem>
                    <para>&name-francis-beaudet; <email>&email-francis-beaudet;</email>
                      and the "Corel Team"</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Under construction.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>
                  Basic data structure with related messages are
                  supported. No painting supported yet.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.11 Month Calendar Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Dummy control. No functionality.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.12 Native font control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Dummy control. No functionality.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.13 Pager Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>
                  Under construction. Many missing features.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.14 Progress Bar Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Original implementation by Dimitrie O. Paun. Fixes
                  and improvements by Eric Kohl.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Finished!</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.15 Property Sheet</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  &name-anders-carlsson; <email>&email-anders-carlsson;</email> and
                  &name-francis-beaudet; <email>&email-francis-beaudet;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Development in progress.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Tab control must be implemented first.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.16 Rebar Control (Cool Bar)</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Development in progress. Many bugs and missing features.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Author needed!! Any volunteers??</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.17 Status Bar Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Original implementation by Bruce Milner. Fixes and
                  improvements by Eric Kohl.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Almost finished.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Tooltip integration is almost complete.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.18 Tab Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  &name-anders-carlsson; <email>&email-anders-carlsson;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Development in progress.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.19 Toolbar Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>
                  Development in progress. Basic functionality is
                  almost done. (dll version 4.0)
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.20 Tooltip Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Almost finished.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Notes:</term>
              <listitem>
                <para>Unicode support is incomplete
                  (<constant>WM_NOTIFYFORMAT</constant>).</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.21 Trackbar Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email> and 
                  &name-alex-priem; <email>&email-alex-priem;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Under construction.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.22 Tree View Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Written by &name-eric-kohl; <email>&email-eric-kohl;</email> and 
                  &name-alex-priem; <email>&email-alex-priem;</email>, fixes by
                  &name-aric-stewart; <email>&email-aric-stewart;</email>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Quite usable already.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>3.23 Updown Control</title>

          <variablelist>
            <varlistentry>
              <term>Author:</term>
              <listitem>
                <para>
                  Original implementation by Dimitrie O. Paun.
                  Some minor changes by &name-eric-kohl; <email>&email-eric-kohl;</email>.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Status:</term>
              <listitem>
                <para>Unknown.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <note>
            <title>Notes</title>
            <para>
              Have a look at <filename>controls/updown.c</filename>
              for a list of bugs and missing features.
            </para>
            <para>
              The status is unknown, because I did not have a close
              look at this control. One test-program looked quite
              good, but in Win95's <filename>cdplayer.exe</filename>
              the control does not show at all.
            </para>
            <para>
              Any volunteers??
            </para>
          </note>
        </sect3>
      </sect2>

      <sect2>
        <title>4. Additional Information</title>

        <para>
          Has to be written...
        </para>
      </sect2>

      <sect2>
        <title>5. Undocumented features</title>

        <para>
          There are quite a lot of undocumented functions like:
        </para>
        <itemizedlist>
          <listitem>
            <para>DSA (Dynamic Storage Array) functions.</para>
          </listitem>
          <listitem>
            <para>DPA (Dynamic Pointer Array) functions.</para>
          </listitem>
          <listitem>
            <para>MRU ("Most Recently Used" List) functions.</para>
          </listitem>
          <listitem>
            <para>other unknown functions.</para>
          </listitem>
        </itemizedlist>

        <para>
          Have a look at <filename>relay32/comctl32.spec</filename>.
        </para>

        <sect3>
          <title>5.1 Dynamic Storage Array (DSA)</title>

          <para>
            The DSA functions are used to store and manage dynamic
            arrays of fixed size memory blocks. They are used by
            <filename>TASKMAN.EXE</filename>, Explorer, IE4 and other
            Programs and DLL's that are "parts of the Windows
            Operating System". The implementation should be complete.
          </para>
          <para>
            Have a look at the source code to get more information.
          </para>
        </sect3>

        <sect3>
          <title>5.2 Dynamic Pointer Array (DPA)</title>

          <para>
            Similar to the DSA functions, but they just store
            pointers. They are used by Explorer, IE4 and other
            Programs and DLL's that are "parts of the Windows
            Operating System". The implementation should be complete.
          </para>
          <para>
            Have a look at the source code to get more information.
          </para>
        </sect3>

        <sect3>
          <title>5.3 "Most Recently Used" - List (MRU)</title>

          <para>
            Only stubs are implemented to keep Explorer from bailing out.
          </para>
          <para>
            No more information available at this time!
          </para>
        </sect3>

        <sect3>
          <title>5.4 MenuHelp</title>

          <para>
            Has to be written...
          </para>
        </sect3>

        <sect3>
          <title>5.5 GetEffectiveClientRect</title>

          <para>
            Has to be written...
          </para>
        </sect3>

        <sect3>
          <title>5.6 ShowHideMenuCtl</title>

          <para>
            The official documentation provided by MS is incomplete.
          </para>

          <variablelist>
            <varlistentry>
              <term><varname>lpInfo</varname>:</term>
              <listitem>
                <blockquote>
                  <para>
                    Both values of the first pair must be the handle
                    to the applications main menu.
                  </para>
                </blockquote>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>

        <sect3>
          <title>5.7 Other undocumented functions</title>

          <para>
            Several other undocumented functions are used by IE4.
          </para>
          <para>
            String functions: (will be written...)
          </para>
        </sect3>
      </sect2>

      <sect2>
        <title>6. Epilogue</title>

        <para>
          You see, much work has still to be done. If you are
          interested in writing a control send me an e-mail. If you
          like to fix bugs or add some functionality send an e-mail to
          the author of the control.
        </para>
      </sect2>
    </sect1>
  </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
End:
-->