home *** CD-ROM | disk | FTP | other *** search
/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / windows / c / bsscdemo / bstree.h < prev    next >
Encoding:
Text File  |  1993-05-28  |  58.3 KB  |  1,674 lines
  1. /*
  2. Copyright (c) 1992, 1993 by Barking Spider Software, Inc.  All rights reserved.
  3.                                        
  4.    Filename...:  bstree.h
  5.    
  6.    Version....:  1.0
  7.    
  8.    Language...:  Microsoft C/C++ 7.0
  9.    
  10.    Model......:  Small
  11.    
  12.    Environment:  Microsoft Windows 3.1
  13.                                        
  14.    Description:  This header file describes the exported APIs supported by
  15.                  the tree control.  For a description of error codes, 
  16.                  notification messages, structures, etc. reference the header
  17.                  file BSCORE.H.
  18.    Notes......:  
  19.                                        
  20.    History....:
  21.                                           
  22.    Author.....:  Peter J. Kaufman
  23.                                           
  24. */
  25.  
  26. /****************************************************************************/
  27. /*                        TREE CONTROL EXPORTED APIs                        */
  28. /****************************************************************************/
  29. /* 
  30.  
  31.   BST_AddChildrenToParent ( )
  32.   BST_ChangeNodeText ( )
  33.   BST_ChangeUserData ( )
  34.   BST_ConvertPointToSelectNotif ( )
  35.   BST_CreateTree ( )
  36.   BST_DeleteChildrenOfParent ( )
  37.   BST_DeleteNode ( )
  38.   BST_DragAcceptFiles ( )
  39.   BST_EraseTree ( )
  40.   BST_GetActiveNode ( )
  41.   BST_GetFirstChildOfParent ( )
  42.   BST_GetNextSibling ( )
  43.   BST_GetParent ( )
  44.   BST_GetPreviousSibling ( )
  45.   BST_GetVersion ( )
  46.   BST_InsertSiblingNodes ( )
  47.   BST_SetActiveNode ( )
  48.   BST_SetBitmap ( )
  49.   BST_SetBitmapAndActiveBitmap ( )
  50.   BST_SetBitmapSpace ( )
  51.   BST_SetDeleteNodeCallBack ( )
  52.   BST_SetFont ( )
  53.   BST_SetIcon ( )
  54.   BST_SetLineColor ( )
  55.   BST_SetXSpaceBeforeText ( )
  56.   BST_ShowActiveNode ( )
  57.   BST_ShowLines ( )
  58.   
  59. */
  60.  
  61. /*---------------------------------------------------------------------------
  62.   short _export FAR PASCAL BST_AddChildrenToParent(
  63.                                               HWND hwndTree,
  64.                                               LP_TREE_NODE lpParentTreeNode,
  65.                                               WORD wNodeDefCount,
  66.                                               LP_TREE_NODE_DEF lpTreeNodeDef);
  67.  
  68.   Description:
  69.  
  70.     This API allows the application to add one or more nodes to the tree as
  71.     children of the given parent.
  72.   
  73.   Arguments:
  74.   
  75.     HWND hwndTree:
  76.   
  77.       This argument indicates which tree control will create the new
  78.       tree nodes.  This is the window handle that was returned to the
  79.       application after calling BST_CreateTree ( ).  BST_CreateTree ( )
  80.       creates an empty tree.
  81.   
  82.     LP_TREE_NODE lpParentTreeNode:
  83.   
  84.       This argument points to the parent tree node which will receive the
  85.       wNodeDefCount worth of new tree node children specified by
  86.       lpTreeNodeDef.
  87.     
  88.       If lpParentTreeNode is NULL then this tells the tree control that
  89.       lpTreeNodeDef describes the root of the tree.  The root has to 
  90.       be created before any other tree nodes can be added.  Only one root
  91.       node is allowed in a tree.  If lpParentTreeNode is NULL and
  92.       wNodeDefCount is greater than 1 then an error will be returned from
  93.       BST_AddChildrenToParent ( ).
  94.     
  95.       If lpParentTreeNode is NOT NULL then lpParentTreeNode must be a
  96.       valid pointer to a tree node created earlier.  This tree node will
  97.       be the parent tree node to the child tree nodes to be created.
  98.       The child tree nodes to be created are described by the
  99.       lpTreeNodeDef argument.  The number of child tree nodes to be created
  100.       is expressed by wNodeDefCount.
  101.     
  102.       Refer to the comment section of the API to understand the origins
  103.       of the LP_TREE_NODE pointer stored in lpParentTreeNode.
  104.      
  105.     WORD wNodeDefCount:
  106.  
  107.       wNodeDefCount contains the number of nodes to be added.  In other
  108.       words, wNodeDefCount is the number of TREE_NODE_DEF array elements in
  109.       the TREE_NODE_DEF array pointed to by lpTreeNodeDef.
  110.      
  111.     LP_TREE_NODE_DEF lpTreeNodeDef:
  112.   
  113.       lpTreeNodeDef is a pointer to an array of TREE_NODE_DEFs that describe
  114.       each of the nodes to be added.
  115.     
  116.       If the given parent already has children, then the new children are
  117.       appended to the last child of the parent.  In this way, the 
  118.       application uses very little memory describing the nodes and have the
  119.       capability for providing multitasking.
  120.     
  121.       Only one node may be the root node, therefore adding more than one
  122.       child node to the parent 0L is prohibited.
  123.                
  124.       While adding tree nodes to the tree control, the tree control could
  125.       receive either a memory allocation failure or realize that the total
  126.       number of tree nodes in the tree has exceeded the maximum number of
  127.       tree nodes allowed.  If either of these conditions occur then the
  128.       child tree nodes that were added to the tree control prior to the
  129.       problem, are NOT removed from the tree.  The application will receive
  130.       error messages if there is a memory allocation problem or the maximum
  131.       number of tree nodes is exceeded.  The application can determine what
  132.       child tree nodes did not make it into the tree by looking at the value
  133.       of the lpTreeNode member of each TREE_NODE_DEF array starting from the
  134.       beginning of the array.  When a TREE_NODE_DEF's lpTreeNode member is
  135.       found that has a value of zero, then that TREE_NODE_DEF and all 
  136.       subsequent TREE_NODE_DEFs in the TREE_NODE_DEF array were not used to
  137.       create new child tree nodes.
  138.     
  139.   Comments:
  140.  
  141.     Where do TREE_NODE pointers come from?  There are several ways to retrieve
  142.     TREE_NODE pointers.
  143.          
  144.     1) TREE_NODE pointers are supplied to the application by the tree control.
  145.     They are returned to the application via the lpTreeNode member of the
  146.     TREE_NODE_DEF structure, when the application successfully calls 
  147.     BST_InsertSiblingNodes ( ) or BST_AddChildrenToParent ( ), which add
  148.     tree nodes to the given tree.  The application can store these
  149.     TREE_NODE pointers for future references.
  150.     
  151.     2) The application will receive the pointer to the tree control owned
  152.     SELECT_NOTIF structure as the result of a notification of an event.
  153.     From the SELECT_NOTIF structure, the TREE_NODE pointer to the tree node
  154.     involved in the event is available.  Below is a list of notifications
  155.     with the associated events:
  156.   
  157.     Notification                       Event
  158.      
  159.     WM_BST_SELECT_NOTIF
  160.                             - Single click left mouse button while over
  161.                               tree node.
  162.                             - Select node with up or down arrow.
  163.                             - Select node with page up or page down key.
  164.                             - Select node with home or end key.
  165.                             - Select node with Ctrl Up or Ctrl Down.
  166.                  
  167.     WM_BST_SELECT_NOTIF_DBLCLK
  168.                             - Double click left mouse button while over
  169.                               tree node.  Sends WM_BST_SELECT_NOTIF on
  170.                               first click.
  171.                             - Hit carriage return while a node is selected.
  172.                             - '+' key if the currently selected node has no
  173.                               children.
  174.                             - '-' key if the currently selected node has
  175.                               children.
  176.                  
  177.     WM_BST_DODRAG
  178.                             - Depress the left mouse button over a tree
  179.                               node and while continuing to hold down the
  180.                               left button, move the mouse a predetermined
  181.                               distance.
  182.   
  183.      3) Calling BST_GetActiveNode ( ) will return a TREE_NODE pointer of the
  184.         currently highlighted node.
  185.  
  186.      4) Calling BST_ConvertPointToSelectNotif ( ) will return a pointer to
  187.         the tree node that lies under the coordinate supplied by the
  188.         application.
  189.     
  190.      5) BST_SetDeleteNodeCallBack ( ) allows the application to register a
  191.         callback with the given tree control.  The callback will be called
  192.         everytime a node is deleted from the tree.  Nodes can be deleted from
  193.         the tree with three tree control export APIs or with the Windows API
  194.         DestroyWindow ( ).  The three tree control exported APIs are:
  195.      
  196.         BST_DeleteChildrenOfParent ( )
  197.         BST_DeleteNode ( )
  198.         BST_EraseTree ( )
  199.          
  200.   Return Codes:
  201.   
  202.     BST_NO_ERROR
  203.     BST_ERR_MEMORY_ALLOC_FAILED
  204.     BST_ERR_LEVEL_LIMIT_EXCEEDED
  205.     BST_ERR_TOO_MANY_NODES
  206.     BST_ERR_ONLY_ONE_ROOT_ALLOWED
  207.     BST_ERR_INVALID_PARENT_FOR_INSERTION
  208. */
  209.  
  210. short _export FAR PASCAL BST_AddChildrenToParent(
  211.                           HWND hwndTree,
  212.                           LP_TREE_NODE lpParentTreeNode,
  213.                           WORD wNodeDefCount,
  214.                           LP_TREE_NODE_DEF lpTreeNodeDef);
  215.  
  216.  
  217.  
  218. /*---------------------------------------------------------------------------
  219.   short _export FAR PASCAL BST_ChangeNodeText( HWND hwndTree, 
  220.                            LP_TREE_NODE lpTreeNode,
  221.                            WORD wTextLength,
  222.                            LPSTR lpszText);
  223.  
  224.   Description:
  225.  
  226.      This API allows the application to change the text of the tree node
  227.      specified in lpTreeNode.
  228.   
  229.   Arguments:
  230.   
  231.      HWND hwndTree:
  232.   
  233.     This argument specifies the tree control that contains the tree node
  234.     that will have the text change.
  235.   
  236.      LP_TREE_NODE lpTreeNode:
  237.   
  238.     This argument points to the tree node that will have it's text 
  239.     changed.
  240.     
  241.     Refer to the Comments section of the documentation for the API
  242.     BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  243.     pointer is made available to the application.
  244.      
  245.      WORD wTextLength:
  246.   
  247.     This argument states the number of characters for the tree control
  248.     to display as text for the given tree node, lpTreeNode.  The source
  249.     of the node text is the lpszText argument described below.
  250.     Normally, the application does a lstrlen ( ) on lpszText and assigns
  251.     the result to wTextLength.  But there may be cases that the string 
  252.     pointed to by lpszText is just too long and fewer characters are
  253.     required.
  254.     
  255.     There is a special attribute of wTextLength in which the most
  256.     significant bit or the sign bit acts as a flag.  Depending on how
  257.     this bit is set there are two ways to handle text in a tree node.
  258.     In both cases, the application passes a long pointer to the text
  259.     via the lpszText argument. The two methods are,
  260.                 
  261.     1) If the sign bit of wTextLength is set to 1,  then the pointer
  262.     in lpszText points to memory owned by the application and is
  263.     guaranteed not to change (be deleted or moved).  This signals the
  264.     tree control to use the supplied string pointer to display the text and
  265.     not worry about allocating, copying, and freeing its memory.
  266.                 
  267.     2) If the sign bit of wTextLength is set to 0, then the tree control
  268.     allocates wTextLength + 1 worth of memory.  The tree control then
  269.     copies wTextLength worth of characters from the string pointed to by
  270.     the lpszText argument to the allocated memory.  This allocated memory
  271.     is owned by the tree control, therefore the application does not have
  272.     to manage it.  When the tree node pointed to by the argument lpTreeNode
  273.     is deleted, the tree control will free the memory pointed to by
  274.     lpszText in the TREE_NODE.
  275.                 
  276.     The 1) method is usually used with static databases and the 2)
  277.     method is used with real-time systems.  And of course, both methods
  278.     can be intermixed.
  279.                 
  280.     NOTE:  If the low 15 bits of wTextLength are set to 0 then lpszText is
  281.     set to NULL by the tree control.
  282.                 
  283.      LPSTR   lpszText:
  284.      
  285.     lpszText is a long pointer to a string that will be displayed
  286.     in the tree control for the given tree node.  The application must
  287.     specify the length of string to be displayed in wTextLength.
  288.     Please refer to the wTextLength documentation above for an
  289.     understanding of the different methods that can be applied to the
  290.     handling of lpszText.     
  291.     
  292.   Comments:
  293.  
  294.      If a memory allocation failure occurs, then the lpszText member of
  295.      TREE_NODE will be assigned a NULL and NO text will be displayed for the
  296.      given tree node.
  297.      
  298.      If the low 15 bits of wTextLength are set to 0 then lpszText is set to
  299.      NULL by the tree control.
  300.       
  301.   Return Codes:
  302.   
  303.      BST_NO_ERROR                  
  304.      BST_ERR_MEMORY_ALLOC_FAILED 
  305. */
  306.  
  307. short _export FAR PASCAL BST_ChangeNodeText( HWND hwndTree, 
  308.                          LP_TREE_NODE lpTreeNode,
  309.                          WORD wTextLength,
  310.                          LPSTR lpszText);
  311.  
  312.  
  313.  
  314. /*---------------------------------------------------------------------------
  315.  
  316. short _export FAR PASCAL BST_ChangeUserData( HWND hwndTree, 
  317.                                              LP_TREE_NODE lpTreeNode,
  318.                                              WORD wUserDataSize,
  319.                                              LPSTR lpUserData);
  320.  
  321.  
  322.   Description:
  323.  
  324.      This API allows the application to change the user-defined data stored
  325.      by the lpUserData member of the tree node pointed to by the argument
  326.      lpUserData.
  327.   
  328.   Arguments:
  329.   
  330.      HWND hwndTree:
  331.   
  332.     This argument specifies the tree control that contains the tree node that 
  333.    will be assigned the new user-defined data.
  334.   
  335.      LP_TREE_NODE lpTreeNode:
  336.   
  337.     This argument points to the tree node that will have user-defined data 
  338.    assigned to it.
  339.     
  340.     Refer to the Comments section of the documentation for the API
  341.    BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  342.    pointer is made available to the application.
  343.      
  344.      WORD wUserDataSize:
  345.   
  346.     If wUserDataSize is 0 then the given pointer, lpUserData, is assigned to
  347.    the given tree node pointed to by lpTreeNode.  It will then be the
  348.    responsibility of the application to free the memory pointed to by
  349.    lpUserData.
  350.    
  351.    If wUserDataSize is not zero, it then signals the tree control to allocate
  352.    wUserDataSize worth of memory.  The tree control will then copy 
  353.    wUserDataSize bytes from the location pointed to by the given argument,
  354.    lpUserData, in to the newly allocated memory.   The tree control will
  355.    free this allocated memory when the tree node is deleted.
  356.                 
  357.      LPSTR lpUserData:
  358.      
  359.     Points to the application defined memory that the application wishes 
  360.    stored with the tree node pointed to by the argument lpTreeNode.
  361.    
  362.    If the wUserDataSize argument is set to 0 then the lpUserData pointer will
  363.    be directly assigned to the lpUserData member of the tree node pointed to
  364.    by lpTreeNode.  It will be the responsibility of the application to 
  365.    free the memory pointed to by lpUserData.  
  366.    
  367.    If wUserDataSize is non-zero, then the tree control will allocate
  368.    wUserDataSize worth of memory, copy wUserDataSize worth of memory from the
  369.    location pointed to by the argument lpUserData to the newly allocated
  370.    memory, and then assign the pointer to the newly allocated memory to the
  371.    lpUserData member of the tree node pointed to by the given argument,
  372.    lpTreeNode.
  373.     
  374.   Comments:
  375.  
  376.    BST_SetDeleteNodeCallBack ( ) allows the application to register a
  377.     callback with the given tree control.  The callback will be called
  378.     everytime a node is deleted from the tree.  Nodes can be deleted from
  379.     the tree with three tree control export APIs or with the Windows API
  380.     DestroyWindow ( ).  The three tree control exported APIs are:
  381.      
  382.     BST_DeleteChildrenOfParent ( )
  383.     BST_DeleteNode ( )
  384.     BST_EraseTree ( )
  385.       
  386.   Return Codes:
  387.   
  388.      BST_NO_ERROR                  
  389.      BST_ERR_MEMORY_ALLOC_FAILED 
  390. */
  391.  
  392. short _export FAR PASCAL BST_ChangeUserData( HWND hwnd, 
  393.                                              LP_TREE_NODE lpTreeNode,
  394.                                              WORD wUserDataSize,
  395.                                              LPSTR lpUserData);
  396.  
  397.  
  398. /*---------------------------------------------------------------------------
  399.   LP_SELECT_NOTIF _export FAR PASCAL BST_ConvertPointToSelectNotif( 
  400.                                    HWND  hwndTree,
  401.                                    short x,
  402.                                    short y);
  403.    
  404.   Description:
  405.   
  406.      This API allows the application to request the given x, y coordinate 
  407.      to be converted into a pointer to the tree control's SELECT_NOTIF
  408.      structure.  The SELECT_NOTIF structure will contain a pointer to the
  409.      TREE_NODE that the coordinated landed on and a wFlags member that
  410.      describes where on the tree node the point landed.  The x, y coordinate
  411.      is relative to the client area of the tree control specified by the
  412.      hwndTree argument.
  413.   
  414.   Arguments:
  415.   
  416.      HWND hwndTree:
  417.      
  418.     This is the window handle of the tree control that will evaluate the
  419.     given x, y coordinate.  hwndTree is the result of calling the exported
  420.     API BST_CreateTree ( ).
  421.   
  422.      short x:
  423.   
  424.     X axis of the point to be converted to a pointer to the tree
  425.     control's SELECT_NOTIF structure.  The value is pixel based and
  426.     relative to the tree control's upper left corner of the client area.
  427.      
  428.      short y:
  429.  
  430.     Y axis of the point to be converted to a pointer to the tree
  431.     control's SELECT_NOTIF structure.  The value is pixel based and
  432.     relative to the tree control's upper left corner of the client area.
  433.      
  434.   Comments:
  435.      
  436.      Normally, this API will be used in drag and drop operations.  To process
  437.      the drop notification message from the File Manager, which is
  438.      WM_DROPFILES, the application will need BST_ConvertPointToSelectNotif ( )
  439.      to determine what tree node the files were dropped on.  Just as well,
  440.      if the application decides to allow the dragging of a tree node, the
  441.      application will need to determine what the mouse cursor shape should be
  442.      when the cursor is over other tree control nodes.  Since the application
  443.      captures the mouse and monitors the WM_MOUSEMOVE messages, it can get the
  444.      window handle of the window that the mouse is over, determine the x, y
  445.      point in the client area where the mouse is located, and call
  446.      BST_ConvertPointToSelectNotif ( ) to retrieve the TREE_NODE pointer via
  447.      the SELECT_NOTIF structure.  Of course, OLE 2.0 will require the
  448.      utilization of this API.
  449.   
  450.      REMEMBER: The memory pointed to by SELECT_NOTIF pointer belongs to the
  451.      tree control and is read only.  Do not write to it or free the memory
  452.      or the tree control's integrity will be violated.
  453.      
  454.   Return Codes:
  455.   
  456.      NULL will be returned if the coordinate is not over a tree node.
  457.      
  458.      If the x, y coordinate landed on a tree node, then the return value will
  459.      be the LP_SELECT_NOTIF pointer which will contain the hit flags and a
  460.      pointer to the tree node that the x, y coordinate landed on.
  461.                                 
  462. */
  463.  
  464. LP_SELECT_NOTIF _export FAR PASCAL BST_ConvertPointToSelectNotif ( 
  465.                                    HWND  hwndTree,
  466.                                    short x,
  467.                                    short y);
  468.  
  469.  
  470.                                 
  471. /*---------------------------------------------------------------------------                                             
  472.   HWND _export FAR PASCAL BST_CreateTree( HANDLE hInstance,
  473.                       HWND hwndApp,
  474.                       int x, int y,
  475.                       int nWidth, int nHeight,
  476.                       DWORD dwStyle,
  477.                       DWORD dwExStyle);
  478.  
  479.   Description:
  480.   
  481.      Creates an empty tree.  BST_CreateTree ( ) ORs the style bits specified
  482.      in dwStyle to the tree control's required styles and calls the Windows
  483.      API, CreateWindowEx ( ).  In effect, BST_CreateTree calls ( )
  484.      CreateWindowEx ( ) as:
  485.                       
  486.     CreateWindowEx ( dwExStyle,
  487.              "BST_Tree",
  488.              "",
  489.              dwStyle | dwTreeControlStyles,
  490.              x,
  491.              y,
  492.              nWidth,
  493.              nHeight,
  494.              hwndApp,
  495.              NULL,
  496.              hInstance,
  497.              NULL);
  498.  
  499.      Once the tree is created then nodes can be added by calling the exported
  500.      APIs:
  501.   
  502.     BST_AddChildrenToParent ( ) 
  503.     BST_InsertSiblingNodes ( ).
  504.   
  505.   Arguments:
  506.   
  507.      HANDLE hInstance:
  508.   
  509.     Instance associated with the creation of the tree control window.
  510.   
  511.      HWND hwndApp:
  512.   
  513.     Window handle of the parent window that is creating the tree control.
  514.   
  515.      int x:
  516.   
  517.     X location of the upper left corner of the tree control in client
  518.     area coordinates of the parent window.
  519.   
  520.      int y:
  521.   
  522.     Y location of the upper left corner of the tree control in client
  523.     area coordinates of the parent window.
  524.   
  525.      int nWidth:
  526.   
  527.     Width of the tree control in device (pixel) units.
  528.   
  529.      int nHeight:
  530.   
  531.     Height of the tree control in device (pixel) units.
  532.   
  533.      DWORD dwStyle:
  534.   
  535.     Application requested CreateWindowEx ( ) styles.
  536.   
  537.      DWORD dwExStyle:
  538.   
  539.     Application requested CreateWindowEx ( ) extended styles.
  540.   
  541.   Comments:
  542.   
  543.      The successful return value from this call, which is a window handle,
  544.      will be used as the tree control identifier for applying the 
  545.      tree control exported APIs.  Most of the tree control APIs require
  546.      the tree control window handle.
  547.      
  548.   Return Codes:
  549.   
  550.      If successful, BST_CreateTree ( ) will return the window handle of the
  551.      newly created tree control.  If failure, then a NULL will be returned.
  552. */
  553.  
  554. HWND _export FAR PASCAL BST_CreateTree( HANDLE hInstance,
  555.                     HWND hwndApp,
  556.                     int x, int y,
  557.                     int nWidth, int nHeight,
  558.                     DWORD dwStyle,
  559.                     DWORD dwExStyle);
  560.  
  561.  
  562.                     
  563. /*---------------------------------------------------------------------------
  564.   short _export FAR PASCAL BST_DeleteChildrenOfParent(
  565.                              HWND hwndTree,
  566.                              LP_TREE_NODE lpTreeNode);
  567.  
  568.   Description:
  569.  
  570.      Deletes all of the child tree nodes of the given parent tree node
  571.      specified in lpTreeNode.
  572.   
  573.   Arguments:
  574.  
  575.      HWND hwndTree:
  576.      
  577.     This argument specifies the tree control that will destroy the child
  578.     tree nodes of the given parent tree node.  This is the window handle
  579.     that was returned to the application after it called
  580.     BST_CreateTree ( ).  BST_CreateTree ( ) creates an empty tree.
  581.       
  582.      LP_TREE_NODE lpTreeNode:
  583.   
  584.     lpTreeNode points to a tree node in the given tree in which it's
  585.     children, if it has any, will be destroyed.
  586.     
  587.     After this call is made by the application, all tree node pointers
  588.     associated with the destroyed tree nodes will be invalid.
  589.     
  590.     Refer to the Comments section of the documentation for the API
  591.     BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  592.     pointer is made available to the application.
  593.         
  594.   Comments:
  595.      
  596.      When a tree node is deleted, it's pointer, is no longer
  597.      valid.  The tree control frees the deleted tree node's memory.  If a
  598.      notification of a tree node's deletion is desired, then the application
  599.      can use the tree control exported API, BST_SetDeleteNodeCallBack ( ), to
  600.      register a callback function that the tree control will call just before
  601.      deletion of the node.  If the application has assigned a pointer
  602.      in the lpUserData member of the tree node, and this pointer points to
  603.      dynamically allocated memory then it is the responsibility of the
  604.      application to free this memory.
  605.      
  606.   Return Codes:
  607.   
  608.      BST_NO_ERROR    
  609. */
  610.  
  611. short _export FAR PASCAL BST_DeleteChildrenOfParent (HWND hwndTree,
  612.                              LP_TREE_NODE lpTreeNode);
  613.                     
  614.  
  615.  
  616. /*---------------------------------------------------------------------------
  617.   short _export FAR PASCAL BST_DeleteNode( HWND hwndTree,
  618.                        LP_TREE_NODE lpTreeNode);
  619.        
  620.   Description:
  621.                      
  622.      Delete all of the child tree nodes of the parent specified in lpTreeNode
  623.      and then delete the parent (lpTreeNode) from the tree.
  624.   
  625.   Arguments:
  626.  
  627.      HWND hwndTree:
  628.      
  629.     This argument specifies the tree control that will destroy the child
  630.     tree nodes of the given parent tree node and then destroy the parent
  631.     tree node.  This is the window handle that was returned to the
  632.     application after calling BST_CreateTree ( ).  BST_CreateTree ( )
  633.     creates an empty tree.
  634.       
  635.      LP_TREE_NODE lpTreeNode:
  636.   
  637.     lpTreeNode points to a tree node in the given tree which will be
  638.     deleted.  If this tree node has any children, then these children
  639.     will be destroyed as well.  
  640.      
  641.     After this call is made by the application, all tree node pointers
  642.     associated with the destroyed tree nodes will be invalid.
  643.  
  644.     Refer to the Comments section of the documentation for the API
  645.     BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  646.     pointer is made available to the application.
  647.     
  648.   Comments:
  649.  
  650.      When a tree node is deleted, it's pointer, is no longer valid.  The tree
  651.      control frees the deleted tree node's memory.  If a notification of a
  652.      tree node's deletion is desired, then the application can use the tree
  653.      control exported API, BST_SetDeleteNodeCallBack ( ), to register a
  654.      callback function that the tree control will call just before deletion of
  655.      the node.  If the application has assigned a pointer to dynamically
  656.      allocated memory in the lpUserData member of the tree node, it is the
  657.      responsibility of the application to free this memory.
  658.       
  659.        
  660.   Return Codes:
  661.   
  662.      BST_NO_ERROR   
  663. */
  664.  
  665. short _export FAR PASCAL BST_DeleteNode( HWND hwndTree,
  666.                      LP_TREE_NODE lpTreeNode);
  667.  
  668.  
  669.                       
  670. /*---------------------------------------------------------------------------
  671.   void _export FAR PASCAL BST_DragAcceptFiles( HWND hwndTree, BOOL bAccept);
  672.   
  673.   Description:
  674.  
  675.      Registers the tree control to accept dropped files.
  676.   
  677.   Arguments:
  678.  
  679.      HWND hwndTree:
  680.      
  681.     This argument specifies the tree control that will accept the message,
  682.     WM_DROPFILES.
  683.       
  684.      BOOL bAccept:
  685.   
  686.     If set to TRUE then the given tree control will accept the
  687.     WM_DROPFILES message.
  688.     
  689.   Comments:
  690.      
  691.      The Windows File Manager (WINFILE.EXE) will send the WM_DROPFILES message
  692.      to the window that registers when files are dropped onto it.
  693.      
  694.   Return Codes:
  695.   
  696.      None
  697.  
  698. */
  699.  
  700. void _export FAR PASCAL BST_DragAcceptFiles ( HWND hwndTree, BOOL bAccept);
  701.  
  702.  
  703. /*---------------------------------------------------------------------------
  704.   short _export FAR PASCAL BST_EraseTree( HWND hwndTree);
  705.  
  706.   Description:
  707.   
  708.      Remove all of the tree nodes in the specified tree control but do not
  709.      destroy the tree control.
  710.   
  711.   Arguments:
  712.  
  713.      HWND hwndTree:
  714.      
  715.     This argument specifies the tree control that will destroy all of it's
  716.     children including the root node.  This tree control handle can still
  717.     be used in any of the APIs such as BST_AddChildrenToParent ( ).  It
  718.     does not invalidate the tree control window handle.  Remember, the
  719.     tree needs a root.
  720.       
  721.  Comments:
  722.  
  723.      When a tree node is deleted, it's pointer, is no longer valid.  The tree
  724.      control frees the deleted tree node's memory.  If a notification of a
  725.      tree node's deletion is desired, then the application can use the tree
  726.      control exported API, BST_SetDeleteNodeCallBack ( ), to register a
  727.      callback function that the tree control will call just before deletion of
  728.      the node.  If the application has assigned a pointer to dynamically
  729.      allocated memory in the lpUserData member of the tree node, it is the
  730.      responsibility of the application to free this memory.
  731.   
  732.   Return Codes:
  733.   
  734.      BST_NO_ERROR   
  735. */
  736.  
  737. short _export FAR PASCAL BST_EraseTree( HWND hwndTree);
  738.  
  739.  
  740.  
  741.  
  742. /*---------------------------------------------------------------------------
  743.  
  744.   LP_TREE_NODE _export FAR PASCAL BST_GetFirstChildOfParent (
  745.                                                     HWND hwndTree, 
  746.                                                     LP_TREE_NODE lpTreeNode);
  747.   Description:
  748.  
  749.      This API returns the pointer to the tree node that satisfies these two
  750.      conditions:
  751.       
  752.       1) The tree node must reside immediately after the given tree node
  753.          lpTreeNode.
  754.       2) The tree node must be the child of the given tree node lpTreeNode. 
  755.   
  756.   Arguments:
  757.   
  758.     HWND hwndTree:
  759.   
  760.       This argument specifies the tree control in which the first child of
  761.       the given tree node will be searched for.   
  762.   
  763.     LP_TREE_NODE lpTreeNode:
  764.   
  765.       This argument points to the tree node in which it's first child will be
  766.       searched for.
  767.     
  768.       Refer to the Comments section of the documentation for the API
  769.       BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  770.       pointer is made available to the application.
  771.     
  772.   Comments:
  773.  
  774.     If for any reason the tree node pointed to by the returned LP_TREE_NODE
  775.     is removed, the pointer to this tree node will be invalid.
  776.       
  777.   Return Codes:
  778.   
  779.     A NULL pointer will be returned if no child exists for the given node
  780.     else the LP_TREE_NODE pointer to the first child of the given node
  781.     will be returned.                
  782. */
  783.  
  784. LP_TREE_NODE _export FAR PASCAL BST_GetFirstChildOfParent (
  785.                                                     HWND hwndTree, 
  786.                                                     LP_TREE_NODE lpTreeNode);
  787.  
  788.  
  789. /*---------------------------------------------------------------------------
  790.   LP_TREE_NODE _export FAR PASCAL BST_GetActiveNode( HWND hwndTree);
  791.  
  792.   Description:
  793.   
  794.      Returns the pointer to the active/highlighted node of the given tree.
  795.      If there are no nodes in the tree, the return value will be NULL.
  796.   
  797.   Arguments:
  798.   
  799.      HWND hwndTree:
  800.   
  801.        This argument specifies the tree control that contains the active node.
  802.      
  803.   Comments:
  804.   
  805.      The active node is the currently highlighted node, visible or hidden.
  806.      If the deletion of a highlighted node occurs, then the next sibling
  807.      becomes the next active node.  If there is no next sibling, then the
  808.      previous node to the deleted node becomes the active/highlighted node.
  809.   
  810.   Return Codes:
  811.   
  812.      The pointer to the active/highlighted node is returned unless there
  813.      are no tree nodes in the tree.
  814. */
  815.  
  816. LP_TREE_NODE _export FAR PASCAL BST_GetActiveNode( HWND hwndTree);
  817.  
  818.  
  819.  
  820. /*---------------------------------------------------------------------------
  821.  
  822.   LP_TREE_NODE _export FAR PASCAL BST_GetNextSibling (
  823.                                                     HWND hwndTree, 
  824.                                                     LP_TREE_NODE lpTreeNode);
  825.   Description:
  826.  
  827.      This API returns the pointer to the tree node that satisfies these two
  828.      conditions:
  829.       
  830.       1) The tree node must reside immediately after the given tree node
  831.          lpTreeNode.
  832.       2) The tree node must have the same parent as the given tree node
  833.          lpTreeNode. 
  834.   
  835.   Arguments:
  836.   
  837.     HWND hwndTree:
  838.   
  839.       This argument specifies the tree control in which the next sibling
  840.       will be searched for.   
  841.   
  842.     LP_TREE_NODE lpTreeNode:
  843.   
  844.       This argument points to the tree node in which it's next sibling
  845.       will be searched for.
  846.     
  847.       Refer to the Comments section of the documentation for the API
  848.       BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  849.       pointer is made available to the application.
  850.     
  851.   Comments:
  852.  
  853.     If for any reason the tree node pointed to by the returned LP_TREE_NODE
  854.     is removed, the pointer to this tree node will be invalid.
  855.       
  856.   Return Codes:
  857.   
  858.     A NULL pointer will be returned if no next sibling exists for 
  859.     the given node else the LP_TREE_NODE pointer to the next sibling
  860.     will be returned.                
  861. */
  862.  
  863. LP_TREE_NODE _export FAR PASCAL BST_GetNextSibling (
  864.                                                     HWND hwndTree, 
  865.                                                     LP_TREE_NODE lpTreeNode);
  866.                                                     
  867.  
  868. /*---------------------------------------------------------------------------
  869.  
  870.   LP_TREE_NODE _export FAR PASCAL BST_GetParent( HWND hwndTree, 
  871.                                                  LP_TREE_NODE lpTreeNode);
  872.                                                  
  873.   Description:
  874.  
  875.     This API returns the pointer to the tree node that is the parent tree
  876.     node of the given tree node.
  877.   
  878.   Arguments:
  879.   
  880.     HWND hwndTree:
  881.   
  882.       This argument specifies the tree control in which the parent of the
  883.       given tree node will be returned.
  884.   
  885.     LP_TREE_NODE lpTreeNode:
  886.   
  887.       This argument points to the tree node in which it's parent will be
  888.       returned.
  889.     
  890.       Refer to the Comments section of the documentation for the API
  891.       BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  892.       pointer is made available to the application.
  893.     
  894.   Comments:
  895.  
  896.     If for any reason the tree node pointed to by the returned LP_TREE_NODE
  897.     is removed, the pointer to this tree node will be invalid.
  898.       
  899.   Return Codes:
  900.   
  901.     A NULL pointer will be returned if the given tree node is the root node,
  902.     else the LP_TREE_NODE pointer to the parent will be returned.                
  903. */
  904.  
  905.  
  906. LP_TREE_NODE _export FAR PASCAL BST_GetParent( HWND hwndTree, 
  907.                                                LP_TREE_NODE lpTreeNode);
  908.                                                
  909.                                                
  910. /*---------------------------------------------------------------------------
  911.   LP_TREE_NODE _export FAR PASCAL BST_GetPreviousSibling (
  912.                                                      HWND hwndTree, 
  913.                                                      LP_TREE_NODE lpTreeNode);
  914.   Description:
  915.  
  916.     This API returns the pointer to the tree node that satisfies these two
  917.     conditions:
  918.       
  919.       1) The tree node must reside immediately before the given tree node
  920.          lpTreeNode.
  921.       2) The tree node must have the same parent as the given tree node
  922.          lpTreeNode. 
  923.   
  924.   Arguments:
  925.   
  926.     HWND hwndTree:
  927.   
  928.       This argument specifies the tree control in which the previous sibling
  929.       will be searched for.   
  930.   
  931.     LP_TREE_NODE lpTreeNode:
  932.   
  933.       This argument points to the tree node in which it's previous sibling
  934.       will be searched for.
  935.     
  936.       Refer to the Comments section of the documentation for the API
  937.       BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  938.       pointer is made available to the application.
  939.     
  940.   Comments:
  941.  
  942.     If for any reason the tree node pointed to by the returned LP_TREE_NODE
  943.     is removed, the pointer to this tree node will be invalid.
  944.       
  945.   Return Codes:
  946.   
  947.     A NULL pointer will be returned if no previous sibling exists for 
  948.     the given node else the LP_TREE_NODE pointer to the previous sibling
  949.     will be returned.                
  950. */
  951.  
  952.  
  953. LP_TREE_NODE _export FAR PASCAL BST_GetPreviousSibling (
  954.                                                      HWND hwndTree, 
  955.                                                      LP_TREE_NODE lpTreeNode);
  956.  
  957. /*---------------------------------------------------------------------------
  958.   WORD _export FAR PASCAL BST_GetVersion( void );
  959.  
  960.   Description:
  961.   
  962.      Returns the version number of the tree control. The returned word
  963.      contains the the version number. The high order byte of the word
  964.      contains the minor version and the low order byte of the word
  965.      contains the major version number.
  966.   
  967.   Arguments:
  968.  
  969.      void:
  970.      
  971.     Only one tree control DLL can be loaded at a time so any instance
  972.     of the tree control can reflect the version.
  973.      
  974.   Comments:
  975.   
  976.      To decipher the returned WORD, use the following piece of code:
  977.      wMinorVersion = wVersion >> 8;
  978.      wMajorVersion = wVersion & 0x00FF;
  979.   
  980.   Return Codes:
  981.   
  982.      BST_NO_ERROR   
  983. */
  984.                        
  985. WORD _export FAR PASCAL BST_GetVersion ( void );
  986.  
  987.  
  988.                       
  989. /*---------------------------------------------------------------------------
  990.   short _export FAR PASCAL BST_InsertSiblingNodes(
  991.                           HWND hwndTree,
  992.                           LP_TREE_NODE lpSiblingTreeNode,
  993.                           BOOL bBeforeSibling,
  994.                           WORD wNodeDefCount,
  995.                           LP_TREE_NODE_DEF lpTreeNodeDef);
  996.  
  997.   Description:
  998.  
  999.      This API allows the application to insert one or more nodes into the
  1000.      tree as siblings to the given tree node.  
  1001.   
  1002.   Arguments:
  1003.   
  1004.      HWND hwndTree:
  1005.    
  1006.     This argument specifies the tree control that will create the new
  1007.     sibling tree nodes.  This is the window handle that was returned to
  1008.     the application by calling BST_CreateTree ( ).  BST_CreateTree ( )
  1009.     creates an empty tree.
  1010.   
  1011.      LP_TREE_NODE lpSiblingTreeNode:
  1012.   
  1013.     This argument points to the sibling tree node which will act as a
  1014.     reference point for the insertion of the new tree nodes described by
  1015.     the TREE_NODE_DEF array pointed to by lpTreeNodeDef. Sibling nodes will
  1016.     be inserted before or after the node pointed to by lpSiblingTreeNode
  1017.     depending on the value of the argument bBeforeSibling.
  1018.     
  1019.     Refer to the Comments section of the documentation for the API
  1020.     BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  1021.     pointer is made available to the application.
  1022.         
  1023.      BOOL bBeforeSibling:
  1024.       
  1025.     bBeforeSibling is a flag that signals the tree control to insert the 
  1026.     newly created nodes before or after the sibling tree node pointed to by
  1027.     lpSiblingTreeNode.  If bBeforeSibling is set to TRUE then the tree
  1028.     nodes will be inserted before the sibling tree node pointed to by
  1029.     lpSiblingTreeNode.  If bBeforeSibling is set to FALSE then the newly
  1030.     created nodes will be inserted after the sibling tree node pointed to
  1031.     by lpSiblingTreeNode.
  1032.      
  1033.      WORD wNodeDefCount:
  1034.   
  1035.     wNodeDefCount contains the number of nodes to be inserted.  In other
  1036.     words, wNodeDefCount is the number of TREE_NODE_DEF elements in the
  1037.     TREE_NODE_DEF array pointed to by lpTreeNodeDef.
  1038.      
  1039.      LP_TREE_NODE_DEF lpTreeNodeDef:
  1040.   
  1041.     This is a pointer to a list of TREE_NODE_DEFs that describe each of
  1042.     the nodes to be inserted. 
  1043.  
  1044.   Comments:
  1045.        
  1046.      When BST_InsertSiblingNodes is called, the tree control allocates
  1047.      room for wNodeDefCount worth of nodes in the tree before or after
  1048.      lpSiblingTreeNode.  Insertion before or after lpSiblingTreeNode is
  1049.      determined by the argument bBeforeSibling.  The tree control then
  1050.      creates wNodeDefCount worth of new tree nodes.  It then serially
  1051.      traverses the lpTreeNodeDef array, initializing the newly created tree
  1052.      nodes, placing the pointers to the newly created tree nodes into
  1053.      the lpTreeNode member of the TREE_NODE_DEF structure pointed to by
  1054.      lpTreeNodeDef.  Then the tree control returns to the application where
  1055.      the application can retrieve the tree node pointers stored in the
  1056.      lpTreeNode members of the TREE_NODE_DEF structs.  The application can
  1057.      use these tree node pointers in future references.
  1058.      
  1059.      Inserting nodes with a sibling of 0L is prohibited and the root node
  1060.      cannot have siblings since only one root node is allowed.
  1061.      
  1062.   Return Codes:
  1063.   
  1064.      BST_NO_ERROR
  1065.      BST_ERR_MEMORY_ALLOC_FAILED 
  1066.      BST_ERR_LEVEL_LIMIT_EXCEEDED
  1067.      BST_ERR_TOO_MANY_NODES
  1068.      BST_ERR_ONLY_ONE_ROOT_ALLOWED             
  1069.      BST_ERR_INVALID_PARENT_FOR_INSERTION     
  1070. */
  1071.  
  1072. short _export FAR PASCAL BST_InsertSiblingNodes (
  1073.                           HWND hwndTree,
  1074.                           LP_TREE_NODE lpSiblingTreeNode,
  1075.                           BOOL bBeforeSibling,
  1076.                           WORD wNodeDefCount,
  1077.                           LP_TREE_NODE_DEF lpTreeNodeDef);
  1078.  
  1079.  
  1080. /*---------------------------------------------------------------------------
  1081.  
  1082.   short _export FAR PASCAL BST_SetActiveNode( HWND hwndTree, 
  1083.                                               LP_TREE_NODE lpTreeNode);
  1084.   Description:
  1085.  
  1086.     This API makes the tree node pointed to by the given argument, lpTreeNode,
  1087.     the active node in the given tree.
  1088.     
  1089.   Arguments:
  1090.   
  1091.     HWND hwndTree:
  1092.   
  1093.       This argument specifies the tree control in which the given tree node
  1094.       will be made active.  Only one active node is allowed in each tree.
  1095.   
  1096.     LP_TREE_NODE lpTreeNode:
  1097.   
  1098.       This argument points to the tree node which will be made active.
  1099.     
  1100.       Refer to the Comments section of the documentation for the API
  1101.       BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  1102.       pointer is made available to the application.
  1103.     
  1104.   Comments:
  1105.  
  1106.       When the given tree node is made active, the previously active window
  1107.       becomes inactive.  Only one active node is allowed in each tree.
  1108.       
  1109.       If the active node is not visible, in the client area of the tree control,
  1110.       then the active tree node will be made visible.
  1111.      
  1112.   Return Codes:
  1113.  
  1114.     BST_NO_ERROR  
  1115. */
  1116.  
  1117. short _export FAR PASCAL BST_SetActiveNode( HWND hwndTree, 
  1118.                                             LP_TREE_NODE lpTreeNode);
  1119.  
  1120. /*---------------------------------------------------------------------------
  1121.   short _export FAR PASCAL BST_SetBitmap( HWND hwndTree,
  1122.                       short nBitmap,
  1123.                       LP_TREE_NODE lpTreeNode,
  1124.                       HBITMAP hBitmap);
  1125.   Description:
  1126.   
  1127.      Assigns a bitmap handle to a specified tree node for the specified
  1128.      bitmap space.  Erases, but not deletes, the old bitmap or icon if it 
  1129.      exists and then draws the new one.
  1130.   
  1131.   Arguments:
  1132.  
  1133.      HWND hwndTree:
  1134.      
  1135.     hwndTree is the tree control in which the tree node will receive the
  1136.     bitmap handle.
  1137.  
  1138.      short nBitmap:
  1139.   
  1140.     nBitmap is the index into the bitmap/icon array of the tree node in
  1141.     which the given bitmap handle will be stored.  This index is zero
  1142.     based and the maximum index is MAX_BITMAPS - 1.  
  1143.  
  1144.      LP_TREE_NODE lpTreeNode:
  1145.   
  1146.     lpTreeNode is the pointer to the tree node that will be assigned the
  1147.     given bitmap handle.
  1148.  
  1149.     Refer to the Comments section of the documentation for the API
  1150.     BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  1151.     pointer is made available to the application.
  1152.  
  1153.      HBITMAP hBitmap:
  1154.  
  1155.     hBitmap is the handle to the bitmap which will be drawn in the
  1156.     specified bitmap space for the given tree node.  It will be stored in
  1157.     the tree node's hBitmap[] array in the member indexed by nBitmap.
  1158.     
  1159.     Bitmap spaces are the regions before the tree node text where the
  1160.     bitmaps/icons are painted.  The left most bitmap space corresponds
  1161.     with the first array member of the tree node's hBitmap[] array.
  1162.     The second left most bitmap space corresponds with the second array
  1163.     member of the tree node's hBitmap[] array, and so on.
  1164.     The hBitmap[] array stores the tree node's bitmap/icon handles but the
  1165.     bitmap spaces are defined globally for all tree nodes.  This keeps
  1166.     column alignment which looks good and makes hit testing consistent.
  1167.     
  1168.     Reference the tree control exported API, BST_SetBitmapSapce ( ) to
  1169.     learn the process of defining a bitmap space.
  1170.      
  1171.   Comments:
  1172.   
  1173.      Bitmap/icon handles are NOT the property of the tree control.  The tree
  1174.      control treats the bitmap/icon handle as read only.  It will use the
  1175.      handle to draw the bitmap/icon associated with the tree node.  If the
  1176.      tree node already has a bitmap/icon handle stored in the specified bitmap
  1177.      position then the old handle is simply overwritten.  It is the
  1178.      responsibility of the application to manage creation and destruction of
  1179.      bitmaps/icons.  If the application deletes/destroys bitmaps/icons before
  1180.      the tree nodes are destroyed, then the tree control will possibly
  1181.       reference invalid bitmap/icon handles.
  1182.      
  1183.      For more information regarding bitmaps/icons and tree nodes, refer to the
  1184.      TREE_NODE structure documentation.
  1185.   
  1186.   Return Codes:
  1187.   
  1188.      BST_NO_ERROR   
  1189. */
  1190.  
  1191. short _export FAR PASCAL BST_SetBitmap ( HWND hwndTree,
  1192.                      short nBitmap,
  1193.                      LP_TREE_NODE lpTreeNode,
  1194.                      HBITMAP hBitmap);
  1195.  
  1196.  
  1197.  
  1198. /* ---------------------------------------------------------------------------
  1199.   short _export FAR PASCAL BST_SetBitmapAndActiveBitmap(
  1200.                               HWND  hwnd,
  1201.                               short nBitmap,
  1202.                               LP_TREE_NODE lpTreeNode,
  1203.                               HBITMAP hBitmap,
  1204.                               HBITMAP hActiveBitmap);
  1205.   Description:
  1206.   
  1207.      Assigns two bitmap handles to a specified tree node for the specified
  1208.      bitmap space.  Erases, but not deletes, the old bitmap if defined
  1209.      and draws the new bitmap.  The hBitmap handle will be used to draw the
  1210.      bitmap if the tree node is not active else the hActiveBitmap handle
  1211.      will be used to draw the bitmap if the tree node is active.
  1212.      
  1213.      This API provides a way to provide a background masked bitmap 
  1214.      to match the highlight color used in showing tree node selection.
  1215.   
  1216.   Arguments:
  1217.  
  1218.      HWND hwndTree:
  1219.      
  1220.     hwndTree is the tree control in which the tree node will receive the
  1221.     bitmaps.
  1222.  
  1223.      short nBitmap:
  1224.   
  1225.     nBitmap is the index into the hBitmap[] array and the hActiveBitmap[]
  1226.     array of the specified tree node, lpTreeNode, in which the new bitmaps
  1227.     will replace the old bitmaps if they are defined.  This index is zero
  1228.     based and the maximum index is MAX_BITMAPS - 1;
  1229.  
  1230.      LP_TREE_NODE lpTreeNode:
  1231.   
  1232.     This is the pointer to the tree node that will be assigned the bitmaps.
  1233.     
  1234.     Refer to the Comments section of the documentation for the API
  1235.     BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  1236.     pointer is made available to the application.
  1237.  
  1238.      HBITMAP hBitmap:
  1239.     
  1240.     hBitmap is the handle to the bitmap in which the above tree node
  1241.     will draw in the specified bitmap space when the node is not selected.
  1242.     This handle will be store in the tree node's hBitmap[] array.
  1243.     
  1244.      HBITMAP hActiveBitmap:
  1245.     
  1246.     hActiveBitmap is the handle to the bitmap in which the above
  1247.     tree node will draw in the specified bitmap space when the node is
  1248.     active.  This handle will be store in the tree node's
  1249.     hActiveBitmap[] array.
  1250.      
  1251.   Comments:
  1252.   
  1253.      Bitmap handles are NOT the property of the tree control.  The tree
  1254.      control treats the bitmap as read only.  It will use the handle to draw
  1255.      the bitmap of each tree node.  When a tree node is assigned a new bitmap
  1256.      handle, the old handle is simply overwritten.  It is the application's
  1257.      responsibility to manage creation and destruction of bitmaps.  If the
  1258.      application destroys the bitmaps before the tree control, then there 
  1259.      will be trouble in paradise.   
  1260.      
  1261.      For more information regarding bitmaps and tree nodes, refer to the
  1262.      TREE_NODE structure documentation.
  1263.    
  1264.   Return Codes:
  1265.   
  1266.      BST_NO_ERROR   
  1267. */
  1268.  
  1269. short _export FAR PASCAL BST_SetBitmapAndActiveBitmap( HWND  hwndTree,
  1270.                                short nBitmap,
  1271.                                LP_TREE_NODE lpTreeNode,
  1272.                                HBITMAP hBitmap,
  1273.                                HBITMAP hActiveBitmap);
  1274.  
  1275.  
  1276.  
  1277. /*---------------------------------------------------------------------------
  1278.   short _export FAR PASCAL BST_SetBitmapSpace( HWND  hwndTree,
  1279.                            short nBitmap,
  1280.                            short nWidth,
  1281.                            short nHeight,
  1282.                            BOOL  bCenterBitmap);
  1283.  
  1284.   Description:
  1285.                            
  1286.      Define the tree control's maximum width and height (in pixels) of the
  1287.      bitmap space, identified by the argument nBitmap, for all nodes in the
  1288.      tree.  This API will reserve space before the beginning of the node's
  1289.      text for the drawing of the bitmap identified by nBitmap.  If the
  1290.      bitmap/icon handle associated with bitmap space is NULL, the empty bitmap
  1291.      space will still be represented.  If the next item after the empty bitmap
  1292.      space is the tree node text, then the tree control shifts the text left
  1293.      until it is butted against a non empty bitmap space or the lines.
  1294.  
  1295.      Bitmap spaces offer the application the ability to fine tune each bitmap
  1296.      position and to define each bitmap hit test area.   Hit testing is not
  1297.      performed on the bitmap but on the bitmap space.
  1298.      
  1299.      The dimensions of a bitmap space are defined globally for all tree nodes.
  1300.      The reason for this is to keep column alignment of the bitmaps.  This
  1301.      is visually pleasing and offers consistency with hit testing.     
  1302.      
  1303.   Arguments:
  1304.  
  1305.      HWND hwndTree:
  1306.      
  1307.     This argument specifies the tree control in which to reserve the
  1308.     bitmap space.  This space will be used to draw a bitmap.  This space
  1309.     is before the start of the node's text, if it has text.
  1310.  
  1311.      short nBitmap:
  1312.   
  1313.     Identifies the bitmap space.  This is a zero based index into a
  1314.     MAX_BITMAPS size array where each member of the array is a structure.
  1315.     This structure has two members which hold the width and height of the
  1316.     bitmap space.  The width and height are defined in device coordinates
  1317.     (pixels).
  1318.       
  1319.      short nWidth:
  1320.   
  1321.     nWidth is the width, in pixels, of the reserved bitmap space.
  1322.      
  1323.      short nHeight:
  1324.   
  1325.     nHeight is the height, in pixels, of the reserved bitmap space.
  1326.  
  1327.      BOOL bCentered:
  1328.   
  1329.     If set to TRUE then center the bitmap/icon in the bitmap space.
  1330.  
  1331.   Comments:
  1332.     
  1333.      The bitmap/icon will be painted in the reserved space centered
  1334.      between the top and bottom boundaries.  If bCentered is set to TRUE then
  1335.      the bitmap/icon will be centered between the left and right boundaries.
  1336.      If bCentered is set to FALSE then the bitmap/icon will be left justified
  1337.      in the bitmap space.  If the bitmap is larger than the
  1338.      width and/or the height, then the bitmap will be clipped.  If the icon
  1339.      is larger than the bitmap space there will be no clipping since the
  1340.      Windows API, DrawIcon(), does not provide it.  Therefore, if an
  1341.      icon is going to be associated with a bitmap space, make the width and
  1342.      height of the bitmap space at least as wide and tall as the values
  1343.      returned from GetSystemMetrics (SM_CXICON) and 
  1344.      GetSystemMetrics (SM_CXICON).
  1345.      
  1346.      If either nHeight or nWidth is zero, then there is no bitmap space.
  1347.      
  1348.      Remember, that the bitmap space definitions, 0 thru MAX_BITMAPS-1, are
  1349.      global to all tree nodes in the given tree control.
  1350.   
  1351.   Return Codes:
  1352.   
  1353.      BST_NO_ERROR   
  1354. */
  1355.  
  1356. short _export FAR PASCAL BST_SetBitmapSpace ( HWND  hwndTree,
  1357.                           short nBitmap,
  1358.                           short nWidth,
  1359.                           short nHeight,
  1360.                           BOOL  bCenterBitmap);
  1361.  
  1362.  
  1363.  
  1364. /*---------------------------------------------------------------------------
  1365.   typedef BOOL (_export FAR PASCAL * FP_DELETE_TREE_NODE_CB) ( HWND,
  1366.                                    LP_TREE_NODE);
  1367.     
  1368.   short _export FAR PASCAL BST_SetDeleteNodeCallBack (
  1369.                        HWND hwndTree, 
  1370.                        FP_DELETE_TREE_NODE_CB fpDeleteNodeCB);
  1371.                     
  1372.   Description:
  1373.   
  1374.      This API allows the application to register a callback with the given
  1375.      tree control.  The callback will be called everytime a node is deleted 
  1376.      from the tree.  Nodes can be deleted from the tree with three tree
  1377.      control export APIs or with the Windows API DestroyWindow ( ).  The three
  1378.      tree control exported APIs are:
  1379.      
  1380.     BST_DeleteChildrenOfParent ( )
  1381.     BST_DeleteNode ( )
  1382.     BST_EraseTree ( )
  1383.                            
  1384.   Arguments:
  1385.  
  1386.      HWND hwndTree:
  1387.      
  1388.     hwndTree identifies the tree control in which to register the callback
  1389.     with.
  1390.      
  1391.      FP_DELETE_TREE_NODE_CB fpDeleteNodeCB:
  1392.      
  1393.     The address of the callback.  This will be called everytime a tree
  1394.     node deletion occurs.
  1395.  
  1396.   Comments:
  1397.   
  1398.      Know how to define callbacks before using this feature!
  1399.     
  1400.   Return Codes:
  1401.   
  1402.      BST_NO_ERROR
  1403. */
  1404.  
  1405. typedef BOOL (_export FAR PASCAL * FP_DELETE_TREE_NODE_CB) ( HWND,
  1406.                                  LP_TREE_NODE);
  1407.     
  1408. short _export FAR PASCAL BST_SetDeleteNodeCallBack (
  1409.                        HWND hwndTree, 
  1410.                        FP_DELETE_TREE_NODE_CB fpDeleteNodeCB);
  1411.  
  1412.  
  1413.  
  1414. /*---------------------------------------------------------------------------
  1415.   short _export FAR PASCAL BST_SetFont( HWND hwndTree, HFONT hFont);
  1416.  
  1417.   Description:
  1418.   
  1419.      Apply a given font to the drawing of the text for all the tree nodes of
  1420.      the given tree control.
  1421.   
  1422.   Arguments:
  1423.  
  1424.      HWND hwndTree:
  1425.      
  1426.     This argument specifies the tree control that will apply the given
  1427.     font to the text of every tree node.
  1428.       
  1429.      HFONT hFont:
  1430.   
  1431.     hFont is a handle to a font that was created by the application.
  1432.  
  1433.   Comments:
  1434.   
  1435.      Once the tree control receives the font handle, it becomes the property
  1436.      of the tree control and it is the responsibility of the tree control to
  1437.      delete the font.  The font will be deleted if a new font is sent to the
  1438.      tree control by the application or if the tree control receives a
  1439.      WM_DESTROY message.  The system font is the default font.
  1440.        
  1441.   Return Codes:
  1442.   
  1443.      BST_NO_ERROR   
  1444. */
  1445.  
  1446. short _export FAR PASCAL BST_SetFont ( HWND hwndTree, HFONT hFont);
  1447.  
  1448.  
  1449.  
  1450.  
  1451. /*---------------------------------------------------------------------------
  1452.   short _export FAR PASCAL BST_SetIcon ( HWND  hwndTree,
  1453.                      short nIcon,
  1454.                      LP_TREE_NODE lpTreeNode,
  1455.                      HICON hIcon);
  1456.                     
  1457.   Description:
  1458.   
  1459.      Assigns an icon handle to a specified tree node for the specified
  1460.      bitmap space.  Erases, but not deletes, the old icon or bitmap and draws
  1461.      the given icon.
  1462.   
  1463.   Arguments:
  1464.  
  1465.      HWND hwndTree:
  1466.      
  1467.     hwndTree is the tree control in which the tree node will
  1468.     receive the icon handle.
  1469.  
  1470.      short nIcon:
  1471.   
  1472.     nIcon is the index into the bitmap array of the node in which the
  1473.     new handle will replace the old handle if the old handle exists.  
  1474.     This index is zero based and  the maximum index is MAX_BITMAPS - 1;
  1475.  
  1476.      LP_TREE_NODE lpTreeNode:
  1477.   
  1478.     This is the pointer to the tree node that will be assigned the icon.
  1479.  
  1480.     Refer to the Comments section of the documentation for the API
  1481.     BST_AddChildrenToParent ( ) for an understanding how the TREE_NODE 
  1482.     pointer is made available to the application.
  1483.     
  1484.      HICON hIcon:
  1485.      
  1486.     hIcon is the handle to the icon which will be drawn in the specified
  1487.     bitmap space for the given tree node.  It will be stored in the tree
  1488.     node's hBitmap[] array in the member indexed by nIcon.
  1489.     
  1490.     Bitmap spaces are the regions before the tree node text where the
  1491.     bitmaps/icons are painted.  The left most bitmap space corresponds
  1492.     with the first array member of the tree node's hBitmap[] array.
  1493.     The second left most bitmap space corresponds with the second array
  1494.     member of the tree node's hBitmap[] array, and so on.
  1495.     The hBitmap[] array stores the tree node's bitmap/icon handles but the
  1496.     bitmap spaces are defined globally for all tree nodes.  This keeps
  1497.     column alignment which looks good and makes hit testing tolerable.
  1498.     
  1499.     Reference the tree control exported API, BST_SetBitmapSapce ( ) to
  1500.     learn the process of defining a bitmap space.
  1501.      
  1502.   Comments:
  1503.   
  1504.      Bitmap/icon handles are NOT the property of the tree control.  The tree
  1505.      control treats the bitmap/icon handle as read only.  It will use the
  1506.      handle to draw the bitmap/icon associated with the tree node.  If the
  1507.      tree node already has a bitmap/icon handle stored in the specified bitmap
  1508.      position then the old handle is simply overwritten.  It is the
  1509.      responsibility of the application to manage creation and destruction of
  1510.      bitmaps/icons.  If the application deletes/destroys bitmaps/icons before
  1511.      the tree nodes are destroyed, then the tree control will possibly
  1512.      reference invalid bitmap/icon handles.
  1513.      
  1514.      For more information regarding bitmaps/icons and tree nodes, refer to the
  1515.      TREE_NODE structure documentation.
  1516.   
  1517.   Return Codes:
  1518.   
  1519.      BST_NO_ERROR   
  1520. */
  1521.  
  1522.  
  1523. short _export FAR PASCAL BST_SetIcon( HWND  hwndTree,
  1524.                       short nIcon,
  1525.                       LP_TREE_NODE lpTreeNode,
  1526.                       HICON hIcon);
  1527.                       
  1528.                       
  1529.                       
  1530. /*---------------------------------------------------------------------------
  1531.   short _export FAR PASCAL BST_SetLineColor( HWND hwndTree,
  1532.                          WORD wLineNumber,
  1533.                          COLORREF clrref);
  1534.  
  1535.   Description:
  1536.                            
  1537.      Places a RGB color into the line color array which, in turn, is used to
  1538.      paint the lines that connect the tree nodes.  There are MAX_LINE_COLORS
  1539.      different colors.
  1540.   
  1541.   Arguments:
  1542.  
  1543.      HWND hwndTree:
  1544.      
  1545.     hwndTree is the tree control in which the line color will be assigned.
  1546.  
  1547.      WORD wLineNumber:
  1548.     
  1549.     wLineNumber is the line color index number which is 0 based and has
  1550.     an upper limit of MAX_LINE_COLORS - 1.  
  1551.  
  1552.      COLORREF clrref:
  1553.   
  1554.     RGB color of the line.
  1555.  
  1556.   Comments:
  1557.   
  1558.      Levels of the tree control start at 0 and have a maximum limit of 
  1559.      MAX_LEVELS - 1.  To determine what color a line is painted, the tree
  1560.      control divides the level by MAX_LINE_COLORS and uses the remainder as
  1561.      the index into the line color array.
  1562.      
  1563.      If any of the line colors match the window background color, then the
  1564.      tree control will automatically select another color to avoid the
  1565.      conflict.
  1566.   
  1567.   Return Codes:
  1568.   
  1569.      BST_NO_ERROR   
  1570. */
  1571.                        
  1572. short _export FAR PASCAL BST_SetLineColor ( HWND hwndTree,
  1573.                         WORD wLineNumber,
  1574.                         COLORREF clrref);
  1575.                         
  1576.  
  1577.                         
  1578. /*---------------------------------------------------------------------------
  1579.   short _export FAR PASCAL BST_SetXSpaceBeforeText( HWND  hwndTree,
  1580.                             short nWidth);
  1581.                             
  1582.   Description:
  1583.      
  1584.      Allows the application to adjust the space between the last bitmap
  1585.      (if any) and the first character of the text string.
  1586.   
  1587.   Arguments:
  1588.  
  1589.      HWND hwndTree:
  1590.      
  1591.     This argument specifies the tree control in which to reserve space
  1592.     before the first character of the node's text string.
  1593.  
  1594.      short nWidth:
  1595.   
  1596.     nWidth is the width of the reserved space before the text.  This is
  1597.     expressed in pixels.
  1598.       
  1599.   Comments:
  1600.  
  1601.      There is no default space between the rightmost bitmap space and the
  1602.      first character of the text.
  1603.    
  1604.   Return Codes:
  1605.   
  1606.      BST_NO_ERROR   
  1607. */
  1608.  
  1609. short _export FAR PASCAL BST_SetXSpaceBeforeText ( HWND  hwndTree,
  1610.                            short nWidth);
  1611.  
  1612.  
  1613.  
  1614. /*---------------------------------------------------------------------------
  1615.   short _export FAR PASCAL BST_ShowActiveNode( HWND hwndTree);
  1616.  
  1617.   Description:
  1618.   
  1619.      Place the active node and all its children (that will fit) into the
  1620.      client area of the tree control.
  1621.   
  1622.   Arguments:
  1623.  
  1624.      HWND hwndTree:
  1625.      
  1626.     hwndTree is the tree control in which to display the active node.
  1627.     
  1628.   Comments:
  1629.  
  1630.      This API allows the application to force a tree node into view.
  1631.  
  1632.   Return Codes:
  1633.   
  1634.      BST_NO_ERROR   
  1635. */
  1636.  
  1637. short _export FAR PASCAL BST_ShowActiveNode ( HWND hwndTree);
  1638.  
  1639.  
  1640.  
  1641. /*---------------------------------------------------------------------------
  1642.   short _export FAR PASCAL BST_ShowLines( HWND hwndTree, BOOL bShowLines);
  1643.  
  1644.   Description:
  1645.   
  1646.      By default, the line drawing is on, but the line drawing can be
  1647.      controlled by specifying TRUE to turn on the line drawing on or FALSE to
  1648.      to turn the line drawing off.
  1649.  
  1650.   Arguments:
  1651.  
  1652.      HWND hwndTree:
  1653.      
  1654.     hwndTree is the tree control in which the display of lines is on
  1655.     or off.
  1656.  
  1657.      BOOL bShowLines:
  1658.     
  1659.     TRUE to turn line drawing on, FALSE to turn line drawing off.
  1660.   
  1661.   Comments:
  1662.  
  1663.       BST_ShowLines may be called at any time during the life of the tree
  1664.       control.  A complete repaint of the tree window will be performed.
  1665.   
  1666.   Return Codes:
  1667.   
  1668.      BST_NO_ERROR   
  1669. */
  1670.  
  1671. short _export FAR PASCAL BST_ShowLines ( HWND hwndTree, BOOL bShowLines);
  1672.  
  1673. /*----------------------------------EOF-------------------------------------*/
  1674.