Getting Started
Introduction
Sample Programs
IDEs
History
Advice
Mini-Tutorial
Tutorials
Code Snippets

Resources
Web Sites
More Tutorials
Forums
Vendors/Tools
Books
Magazines
Newsletters
NewsGroups
User Groups
Talk Shows
Blogs

Controls
Overview
Button
Check3State
Checkbox
ComboBox
Frame
Graphic
Image
ImageX
ImgButton
ImgButtonX
Label
Line
ListBox
ListView
Option
Progress Bar
Scrollbar
StatusBar
TAB
TextBox
Toolbar
TreeView

GBIC >> PowerBASIC >> Tutorials >> Controls >> TreeView Control

PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC - the scope of the language as well as it's specific capabilities.

Introduction       Projects       Language           Messages       Functions           Advanced
  • Overview
  • Examples
  • IDE
  • Compilation
  • Distribution
  • Project Files
  • DDT Windows
  • Controls
  • Menus
  • Dialogs  
  • Help Files
  • Resources  
  • Templates  
  • Project Shell  
  • Syntax
  • Operators
  • Data Types
  • Variables
  • Scope
  • Declarations  
  • Procedures
  • Flow Control
  • Windows
  • Messages
  • Callbacks
  • Mouse
  • Keyboard
  • Dialogs
  • Controls
  • Subclassing
  • Arithmetic
  • Trig  
  • Strings
  • Arrays
  • Date/Time
  • Printing
  • Files
  • Folders
  • Keyboard
  • Mouse
  • Sound
  • System
  • Error Traps
  • Debugging
  • Objects
  • Graphics
  • Databases
  • API
  • DLLs
  • ASM
  • Threads
  • TreeView Control
    The treeview control displays information in a hierarchical form - showing parent-child relationships between data items. Parent structures can be closed or expanded to minimize the space needed to display and entire "tree", as the structure is called.

    • Syntax:
      Control Add TreeView, hDlg, id&, txt$, x, y, xx, yy, _
                                           style&, extsytle& CALL callback
      TreeView Insert Item hDlg, id&, hPrnt, hIafter, _
                                          image&, selimage&, txt$ TO hItem
      

      The Control Add TreeView statement simply creates an empty treeview control. The TreeView Insert Item statement must be used to add items (as root or as children items).

      An imagelist is required if images are to be included on the treeview. Imagelists are discussed further down the page.

    • Source Code Example:
      This short example creates a complete application with a single treeview, three levels of items. When an item is clicked, the treeview responds with a message. This tutorial page discusses most of the statements used, however the DDT, Controls, Messages, and Callback tutorials provide background information that may be helpful in understanding the example.

       #Compile Exe
       #Resource "pb-test.pbr"
       Global hDlg As Dword, hLst As Dword, hItem As Dword, hTmp As Dword
       Function PBMain() As Long
          Dialog New Pixels, 0, "TreeView",200,200,155,150, _
                                          %WS_SysMenu, 0 To hDlg
          'create control
          Control Add Treeview, hDlg, 100, "", 10,10,130,125
      
          'create imagelist  w,h,depth,size
          ImageList New Icon 16,16,32,3 To hLst
          ImageList Add Icon hLst, "x"
          ImageList Add Icon hLst, "y"
          ImageList Add Icon hLst, "z"
          ImageList Add Icon hLst, "check"
      
          'attach imagelist
          Treeview Set ImageList hdlg, 100, hLst
      
          'add items  hdlg,id&,hPrnt,hIAftr,image&,selimage&,txt$ To hItem
          Treeview Insert Item hDlg,100,0,%TVI_Last,1,1,"One" To hItem
          Treeview Insert Item hDlg,100,hItem,%TVI_Last,1,4,"One-1" To hTmp
          Treeview Insert Item hDlg,100,hItem,%TVI_Last,2,4,"One-2" To hTmp
      
          Treeview Insert Item hDlg,100,0,%TVI_Last,2,2,"Two" To hItem
          Treeview Insert Item hDlg,100,hItem,%TVI_Last,1,4,"Two-1" To hTmp
          Treeview Insert Item hDlg,100,hItem,%TVI_Last,2,4,"Two-2" To hTmp
      
          Treeview Insert Item hDlg,100,0,%TVI_Last,3,3,"Three" To hItem
          Treeview Insert Item hDlg,100,hItem,%TVI_Last,1,4,"Three-1" To hTmp
          Treeview Insert Item hDlg,100,hItem,%TVI_Last,2,4,"Three-2" To hTmp
      
          Treeview Set Bold hDlg, 100, hItem, -1
              
          Dialog Show Modal hDlg Call DlgProc
       End Function
      
       CallBack Function DlgProc() As Long
          If Cb.Msg = %WM_Notify And Cb.NmId = 100 And _
                            Cb.NmCode = %TVN_SelChanged Then
             MsgBox "Selected!"
          End If
       End Function
      

      In this example, the treeview images are stored in a resource file, available from here.

      An additional example of a callback function is provided further down this page.

    • Visual Examples:
      And here are a few examples of what you can do with the treeview control in PowerBASIC. Variations on the Control Add TreeView statement were used to create the examples. In some cases, other Control statements or TreeView-specific statements were used to modify the results.

         

      There are a wide variety of options - lines, edit-in-place, images, checkboxes, fonts, scrolling, and more.

    Arguments
    The Control Add statement is used to create all new controls. Here are the statement's arguments and any special significance to the treeview control.

    • hDlg
      The dialog handle to which the treeview control is to be added. The value was returned by the DIALOG NEW statement.

    • id&
      The id& argument is a control identifier assigned by the programmer. It must be a value of 1-65535. Values of 100+ are suggested, as PowerBASIC pre-assigns identifiers with special meaning. Numeric equates are suggested over the use of literal values.

    • txt$
      An ampersand can also be included in txt$, such as "&Stop", to specify a hot key Alt-S.

      The treeview control does not display the txt$ value, so it is usually set to "". However, any entered txt$ value can be accessed using the GET/SET TEXT statements. This provides the application with a control-specific property that can used for any purpose the programmer chooses.

    • x,y and xx,yy
      The integer x,y and xx,yy dimensions use the same units as the parent dialog. (x,y) is the upper/left coordinates of the control. (xx,yy) is the width/height of the control.

      When the control is aligned to an edge of the dialog using one of the style& options, the x,y and xx,yy values are ignored.

    • style& and extstyle&
      The style& and extstyle& arguments (listed below) are optional. If not supplied, default values are used (see the table below). If values are supplied, they completely replace default values (i.e., the entered values are not in addition to the default values).

    • CALL
      The "CALL callback" section is optional. If not supplied, the callback function of the parent dialog is used. An example callback function for treeview controls is provided further down this page. The #MESSAGE COMMAND compiler directive can be used to prevent sending %WS_NOTIFY messages to the callback function. By default, both %WS_NOTIFY and %WS_COMMAND messages are sent.

    Usage Notes
    Some of these comments refer to the TreeView-specific statement in the next section below.

    Indexing is starts at 1 for all Control and listview statements.

    TreeView-Specific PowerBASIC Statements
    PowerBASIC provides several statements specific to the treeview control. These allow the application to manage the content and display of the control.

    Here's a summary of the TreeView statements, categorized by the capability they provide.

      • Insert/Delete
       Delete, Insert Item, Reset, Select, Unselect 
      • Get Properties
       Bold, Check, Child, Count, Expanded, Next, 
       Parent, Previous, Root, Select, Text, User
      
      • Set Properties  
       Bold, Check, Expanded, ImageList, Text, User
      

    And here's a description and syntax for each of the TreeView statements, along with some additional usage information.

      TreeView Delete     Delete an item
      hDlg, id&, hItem
      TreeView Get Bold     Get bold attribute of an item
      hDlg, id&, hItem TO datav&
      TreeView Get Check     Get checkmark attribute of an item
      hDlg, id&, hItem TO datav&
      TreeView Get Child     Get handle of first child. 0 if none.
      hDlg, id&, hItem TO datav&
      TreeView Get Count     Get total number of items
      hDlg, id&, hItem TO datav&
      TreeView Get Expanded     Get expanded attribute of an item
      hDlg, id&, hItem TO datav&
      TreeView Get Next     Get handle of next sibling. 0 is none.
      hDlg, id&, hItem TO datav&
      TreeView Get Parent     Get handle of parent. 0 if none.
      hDlg, id&, hItem TO datav&
      TreeView Get Previous     Get handle of previous sibling
      hDlg, id&, hItem TO datav&
      TreeView Get Root     Get handle of topmost data item (root)
      hDlg, id&, hItem TO datav&
      TreeView Get Select     Get handle of currently selected item
      hDlg, id&, hItem TO datav&
      TreeView Get Text     Get text of specified item
      hDlg, id&, hItem TO datav&
      TreeView Get User     Get user value of specified item
      hDlg, id&, hItem TO datav&
      TreeView Insert Item     Add new item
      hDlg, id&, hPrnt, hIAftr, image&, selimage&, txt$ TO hItem
      TreeView Reset     Delete all items
      hDlg, id&
      TreeView Select     Select specified item
      hDlg, id&, hItem
      TreeView Set Bold     Set bold attribute of specified item
      hDlg, id&, hItem, flag& 0-false, non-zero=true
      TreeView Set Check     Set checkmark attribute of specified item
      hDlg, id&, hItem, flag& 0-false, non-zero=true
      TreeView Set Expanded     Set expanded attribute of specified item
      hDlg, id&, hItem, flag& 0-false, non-zero-true
      TreeView Set ImageList     Attach imagelist to treeview control
      hDlg, id&, hLst
      TreeView Set Text     Set text of specific item
      hDlg, id&, hItem, txt$
      TreeView Set User     Set user value of specified item
      hDlg, id&, hItem, NumExpr
      TreeView Unselect     Unselect all items
      hDlg, id&

    And here is a short description of the arguments used in the TREEVIEW statements.

      hDlgHandle of the dialog that owns the Treeview.
      id&The control identifier assigned with CONTROL ADD TREEVIEW.
      hItemHandle of a Treeview item, used to uniquely identify the item
      datav&A long integer variable to which result data is assigned.
      txtv$A string variable to which result data is assigned.
      hPrntHandle of the parent item to insert the new item under.
      hIAftrHandle of the item to insert the new item after.
      image&Image index of the new item
      selimage&Selected image index of the new item
      txt$Text to be displayed for the Treeview item
      flag&A long integer value to define specific attributes
      hLstHandle of the ImageList to be used for graphical items

    See the Usage section above for information on how to use the values made available by these statements.

    Messages, Notifications, Styles, and ExtSstyles
    There are four types of named constants in the following table. All are pulled from the MSDN web site.

    • Notifications - event notifications a control receives
    • Messages - controls may send these
    • Styles - affect the visual look of a control
    • ExtStyles - additional values that affect the visual look

    The first column contains control-specific named constants and the second column contains generic window named constants (treeview controls are windows).

    Also, if the PowerBASIC Help file has an entry on the value, it is highlighted in yellow. If the value was noted in PowerBASIC Help as a default value, it is also shown in bold text.

    In the values for notifications, descriptions starting with -n and -c refer to events received through the %wm_notify and %wm_command messages. By default, PowerBASIC controls can receive both of these messages.

       

    And here is a short description of many of the named constants corresponding to notifications, styles, and extstyle - particularly those discussed in the PowerBASIC Help topics.

    
    
    

    Callback Function
    A control can have its own callback function, or use the parent dialog callback function.

    A control callback function should return TRUE to indicate it has processed the message. This prevents unnecessarily calling the dialog callback function, which will process the message if no control callback function is available, or if the control callback function returns FALSE.

    By default, both %WM_COMMAND and %WM_NOTIFY messages are received. However, if the #MESSAGE COMMAND compiler directive is invoked, the %WM_NOTIFY messages will not be available.

    Here's a sample treeview control callback function.

       CallBack Function cbTreeView()
          Select Case CB.MSG
             Case %WM_COMMAND
                Select Case CB.CTLMSG
                   Case %nm_click
                   Case %nm_dblclk
                   Case %nm_killfocus
                   Case %nm_rclick
                   Case %nm_rdblclk
                   Case %nm_return
                   Case %nm_setfocus
                   Case %tvn_beginlabeledit
                   Case %tvn_deleteitem
                   Case %tvn_endlabeledit
                   Case %tvn_itemchanged
                   Case %tvn_itemchanging
                   Case %tvn_itemexpanded
                   Case %tvn_itemexpanding
                   Case %tvn_keydown
                   Case %tvn_selchanged
                   Case %tvn_selchanging
                   Case %tvn_singleexpand
             End Select
          End Select
       End Function
    

    In each Case section, add the statements the application needs to respond to the event. Also, be sure to add "Function=1" as appropriate to indicate that the event was handled by the callback function.

    Issues
    The TreeView Insert Item statement does not recognize the command to show no images (value 0 for image&).

    I'll update this page as more information becomes available.

    CONTROL Statement Syntax
    The following table lists the various Control statements (except the ADD statements). Most, but not all, can be used with the treeview control. A one-line description of the statement and then its syntax are presented.

      CONTROL DISABLEdisable
      hDlg, id&
      CONTROL ENABLEenable hDlg, id&
      CONTROL GET CHECKcheck state hDlg, id& TO iResult1&
      CONTROL GET CLIENTtop/left location hDlg, id& TO wide&, high&
      CONTROL GET LOCtop/left location hDlg, id& TO x&, y&
      CONTROL GET SIZEwidth/height hDlg, id& TO width&, height&
      CONTROL GET TEXTtext hDlg, id& TO txt$
      CONTROL GET USERget user data hDlg, id&, index& TO retvar&
      CONTROL HANDLE window handle for control id hDlg, id& TO hCtl&
      CONTROL KILLremove control hDlg, id&
      CONTROL POSTput message in queue (non-blocking) hDlg, id&, Msg&, wParam&, lParam&
      CONTROL REDRAWschedule redraw of control hDlg, id&
      CONTROL SENDsend message to control, wait for processing hDlg, id&, Msg&, wParam&, lParam& TO iResult2&
      CONTROL SET CHECKset check for 3state or checkbox hDlg, id&, checkstate&
      CONTROL SET CLIENTchange size to specific client area size hDlg, id&, wide&, high&
      CONTROL SET COLORset fg/bg color hDlg, id&, fgcolor&, bgcolor&
      CONTROL SET FOCUSset focus hDlg, id&
      CONTROL SET FONTselect font for a control hDlg, id&, fonthandle&
      CONTROL SET LOCrelocate control within dialog hDlg, id&, x&, y&
      CONTROL SET OPTIONset check state of option control hDlg, id&, minid&, maxid&
      CONTROL SET SIZEchange control size hDlg, id&, width&, height&
      CONTROL SET TEXTchange control text hDlg, id&, text$
      CONTROL SET USERset user data hDlg, id&, index&, uservalue&
      CONTROL SHOW STATE     toggle visibility hDlg, id&, showstate& TO iResult3&

    If you have any suggestions or corrections, please let me know.