Method XbpTreeViewItem():addItem()

Adds a new item (leaf) to a tree node.

:addItem( <cCaption>, ;
          [<nNormalImage>  | <oNormalImage>], ;
          [<nMarkedImage>  | <oMarkedImage>], ;
          [<nExpandedImage>| <oExpandedImage>], ;
          [<cDllName>], [<xValue>] ) --> oItem | NIL
or
:addItem( <oItem>, [<xValue>] ) --> oItem | NIL

<cCaption> is a character string which is displayed as the caption.

An icon or bitmap image can optionally be assigned to this parameter. The image can be specified via a numeric resource ID in parameter <nNormalImage>, or the image can be defined by assigning an XbpBitmap or XbpIcon object to <oNormalImage>. In any case, the image signifies the normal state of an XbpTreeViewItem object (not marked and not expanded). :addItem() assigns the image to the :image instance variable of the new XbpTreeViewItem object.

Either the numeric resource ID of an image, or an instance of the XbpBitmap or XbpIcon classes can optionally be specified for <nMarkedImage>|<oMarkedImage>. The image signifies the marked state of an XbpTreeViewItem object. :addItem() assigns the image to the :markedImage instance variable of the new XbpTreeViewItem object.

Either the numeric resource ID of an image, or an instance of the XbpBitmap or XbpIcon classes can optionally be specified for <nExpandedImage>|<oExpandedImage>. The image signifies the expanded state of an XbpTreeViewItem object. :addItem() assigns the image to the :expandedImage of the new XbpTreeViewItem object.

A character string containing the name of a DLL file must be specified for <cDllName> if bitmaps or icons for the tree view item are linked as recources to a DLL. When the resources are linked to the EXE file, no file name needs to be specified.

Optionally, an arbitrary value can be specified with <xValue>. It is associated with the new XbpTreeViewItem object and can be retrieved with the :getData() method.

<oItem>

Instead of accepting configuration data for a new XbpTreeViewItem object, the :addItem() method accepts as first parameter a complete XbpTreeViewItem object whose :create() method has been executed.

This method returns the added XbpTreeViewItem object. If the object is not created or added, the return value is NIL.

The method :addItem() adds a new XbpTreeViewItem object to an existing one. As a result, a new level is created in the hierarchical tree structure and the existing XbpTreeViewItem object becomes a node branching to a sub-level in a tree view.

The parameter interface offers two possibilities for the addion of a sub-item. Either configuration data for a new XbpTreeViewItem object or a created object can be passed as parameters. The first possibility is more comfortable to use since both the methods :new() and :create() are implicitly executed and configuration data is assigned automatically to the appropriate instance variables of the new object.

If an XbpBitmap or XbpIcon object is passed in parameter <oNormalImage, <oMarkedImage or <oExpandedImage, one of the methods :load() or :loadFile() must have previously been called. For bitmaps constructed in memory, method :make() must have been used. Moreover, it is discouraged to use the bitmap or icon object to load or define a different image as long as it is assigned to the tree view item. Therefore, if the individual item states should be represented by different images, a new bitmap or icon object should be created for each image.

Windows uses the Windows Bitmap file format as the default image format. If a numeric resource id is assigned to <nNormalImage>, <nMarkedImage> or <nExpandedImage>, it must be the id of a BITMAP resource linked into the application. In order to use an image of another image file format, an XbpBitmap object must be used instead. Also see XbpBitmap:load() for further information.

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Method XbpTreeViewItem():addItem() Foundation