
                  COMMON CONTROLS
              their development status
    and their UNDOCUMENTED features and functions
-----------------------------------------------------


1. Introduction
---------------
  The information provided herein is based on the dll version 4.72 which
  is included in MS Internet Explorer 4.01.

  All information about common controls should be collected in this document.

  All Wine programmers are encouraged to add their knowledge to this document.


2. General Information
----------------------
  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.


2.1 Structure sizes of different common control versions
--------------------------------------------------------
  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 COMCTL32.DLL versions. The following list shows the
  structure size constants that are currently defined in the original
  COMCTL32.DLL.
  NOTE: Some stuctures are NOT defined in wine's COMCTL32 yet.

    HDITEM_V1_SIZE:
      The size of the HDITEM structure in version 4.00.

    LVCOLUMN_V1_SIZE:
      The size of the LVCOLUMN structure in version 4.00.

    LVHITTESTINFO_V1_SIZE:
      The size of the LVHITTESTINFO structure in version 4.00.

    LVITEM_V1_SIZE:
      The size of the LVITEM structure in version 4.00.

    NMLVCUSTOMDRAW_V3_SIZE:
      The size of the NMLVCUSTOMDRAW structure in version 4.70.

    NMTTDISPINFO_V1_SIZE:
      The size of the NMTTDISPINFO structure in version 4.00.

    NMTVCUSTOMDRAW_V3_SIZE:
      The size of the NMTVCUSTOMDRAW structure in version 4.70.

    PROPSHEETHEADER_V1_SIZE:
      The size of the PROPSHEETHEADER structure in version 4.00.

    PROPSHEETPAGE_V1_SIZE:
      The size of the PROPSHEETPAGE structure in version 4.00.

    REBARBANDINFO_V3_SIZE:
      The size of the REBARBANDINFO structure in version 4.70.

    TTTOOLINFO_V1_SIZE:
      The size of the TOOLINFO structure in version 4.00.

    TVINSERTSTRUCT_V1_SIZE:
      The size of the TVINSERTSTRUCT structure in version 4.00.


3. Controls
-----------
  This paragraph describes the development status of the common controls.


3.1 Animation Control
---------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>

  Status:
      Dummy control. No functionality.

  Notes:
      Author needed!! Any volunteers??


3.2 Combo Box Ex Control
------------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>

  Status:
      Dummy control. No functionality.

  Notes:
      Author needed!! Any volunteers??


3.3 Date and Time Picker Control
--------------------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>

  Status:
      Dummy control. No functionality.

  Notes:
      Author needed!! Any volunteers??


3.4 Drag List Box Control
-------------------------
  Status:
      Nothing done at all.

  Notes:
      Author needed!! Any volunteers??


3.5 Flat Scroll Bar Control
---------------------------
  Status:
      Nothing done at all.

  Notes:
      Author needed!! Any volunteers??


3.6 Header Control
------------------
  Author:
      Eric Kohl <ekohl@abo.rhein-zeitung.de>

  Status:
      Almost finished.
      Unicode notifications are not supported (WM_NOTIFYFORMAT).
      Order array not supported.


3.7 Hot Key Control
-------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>

  Status:
      Dummy control. No functionality.

  Notes:
      Author needed!! Any volunteers??


3.8 Image List (no control)
---------------------------
  Author:
      Eric Kohl <ekohl@abo.rhein-zeitung.de>

  Status:
      Almost finished.


3.9 IP Address Control
----------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
      Alex Priem <alexp@sci.kun.nl>

  Status:
      Under construction.

  Notes:
      Author needed!! Any volunteers??


3.10 List View Control
----------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>
      Ben Williams <biwillia@shrug.isdn.uiuc.edu>

  Status:
      Under construction.

  Notes:
      Author needed!! Any volunteers??


3.11 Month Calendar Control
---------------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>

  Status:
      Dummy control. No functionality.

  Notes:
      Author needed!! Any volunteers??


3.12 Native font control
------------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>

  Status:
      Dummy control. No functionality.

  Notes:
      Author needed!! Any volunteers??


3.13 Pager Control
------------------
  Author:
      Dummy written by Eric Kohl. <ekohl@abo.rhein-zeitung.de>

  Status:
      Under construction.
      Many missing features.

  Notes:
      Author needed!! Any volunteers??


3.14 Progress Bar Control
-------------------------
  Author:
      Original implementation by Dimitrie O. Paun.
      Fixes and improvements by Eric Kohl.

  Status:
      Almost finished (should behave like the original).

  Notes:
      WM_GETFONT and WM_SETFONT are not implemented yet. They seem to be
      useless because progress bars usually don't display any textual
      information. But if M$ implemented an undocumented flag to display
      textual information (e.g. percentage) these messages would make sense.


3.15 Property Sheet
-------------------
  Author:
      Anders Carlsson <anders.carlsson@linux.nu>

  Status:
      - Development in progress.
      - Not yet published.

  Notes:
      Tab control must be implemented first.


3.16 Rebar Control (Cool Bar)
-----------------------------
  Author:
      Eric Kohl <ekohl@abo.rhein-zeitung.de>

  Status:
      Development in progress.
      Many bugs and missing features.

  Notes:
      Author needed!! Any volunteers??


3.17 Status Bar Control
-----------------------
  Author:
      Original implementation by Bruce Milner.
      Fixes and improvements by Eric Kohl.

  Status:
      Almost finished.

  Notes:
      - Tooltip integration is almost complete.


3.18 Tab Control
----------------
  Author:
      Anders Carlsson <anders.carlsson@linux.nu>

  Status:
      - Development in progress.


3.19 Toolbar Control
--------------------
  Author:
      Eric Kohl <ekohl@abo.rhein-zeitung.de>

  Status:
      - Development in progress.
      - Basic functionality is almost done. (dll version 4.0)

  Notes:
      - Bitmaps are not correctly displayed.


3.20 Tooltip Control
--------------------
  Author:
      Eric Kohl <ekohl@abo.rhein-zeitung.de>

  Status:
      - Almost finished.

  Notes:
      - Unicode support is still missing.


3.21 Trackbar Control
---------------------
  Author:
      Dummy written by Eric Kohl <ekohl@abo.rhein-zeitung.de>
      Alex Priem <alexp@sci.kun.nl>

  Status:
      Under construction.


3.22 Tree View Control
----------------------
  Author:
      Dummy written by Eric Kohl.
      Alex Priem <alexp@sci.kun.nl>

  Status:
      Under construction.


3.23 Updown Control
-------------------
  Author:
      Original implementation by Dimitrie O. Paun.
      Some minor changes by Eric Kohl <ekohl@abo.rhein-zeitung.de>.

  Status:
      - Unknown.

  Notes:
      - Have a look at controls/updown.c for a list of bugs and missing
        features.

      - 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
        cdplayer.exe the control does not show at all.
      
      Any volunteers??


4. Additional Information
-------------------------

  Has to be written...


5. Undocumented features
------------------------

  There are quite a lot of undocumented functions like:
     - DSA (Dynnamic Storage Array) functions.
     - DPA (Dymnamic Pointer Array) functions.
     - MRU ("Most Recently Used" List) functions.
     - other unknown functions.

  Have a look at relay32/comctl32.spec.


5.1 Dymnamic Storage Array (DSA)
---------------------------------
  The DSA functions are used to store and manage dynamic arrays of fixed size
  memory blocks. They are used by TASKMAN.EXE, Explorer, IE4 and other
  Programs and DLL's that are "parts of the Windows Operating System".
  The implementation should be complete.

  Have a look at the source code to get more information.


5.2 Dynamic Pointer Array (DPA)
------------------------------------
  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.

  Have a look at the source code to get more information.


5.3 "Most Recently Used" - List (MRU)
-------------------------------------
  The function 'COMCTL32_157()' could be called 'CreateMRUListEx32A()'.
  Only stubs are implemented to keep Explorer from bailing out.

  No more information available at this time!


5.4 MenuHelp
------------
  Has to be written...


5.5 GetEffectiveClientRect
--------------------------
  Has to be written...


5.6 ShowHideMenuCtl
-------------------
  The official documentation provided by MS is incomplete.

  lpInfo:
  ...
  Both values of the first pair must be the handle to the applications main
  menu.
  ...


5.7 Other undocumented functions
--------------------------------
  Several other undocumented functions are used by IE4.

  COMCTL32_11, COMCTL_385, COMCTL32_386 and COMCTL32_388.
  Their stubs are implemented to keep IE4 from bailing out.


6. Epilogue
-----------
  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.


Eric Kohl <ekohl@abo.rhein-zeitung.de>