Documents

NextGrid & NextDBGrid

NextGrid

NextDBGrid

NextInspector

NextSheet

NextCollection

Misc

Labs

NextGrid .NET

NextInspector Advanced tutorial

Related Articles:

Info
  • Skill:
  • Version: 1.0.1
  • Author: Bojan Nikolic
  • Created: 2008-04-25
  • Updated: 2008-05-05
NextInspector represents a control that displays a hierarchical list of items, where each item may have own child items. This create so-called "Tree-hierarchy" with parent nodes and child nodes. Each node may be edited (change it's value) and in this way control some part of application.

Every node in NextInspector is a object and therefore it include numerous properties and methods. It is joy to work with them.



Some properties are more important (such as Name, Caption, Value...), some less but may make your NextInspector look unique such as Font, EmptyValue (shows text when Value is empty string...

1. Small example



Here is one small example with few nodes (not a real screenshot):



2. AbsoluteIndex of item



As may be seen on diagram, 4th item having AbsoluteIndex = 3. Next one, "Child 1" will have AbsoluteIndex = 4 and a child of this item will have AbsoluteIndex = 5 and so on till end of a Items array. First category (first item in array) naturaly have AbsoluteIndex = 0.

To access single Item with using AbsoluteIndex write:

NextInspector1.Items[5].Caption := 'My Caption';



NextInspector1->Items[5]->Caption := "My Caption";


3. Level of item



Every item have own "Level" inside items hierarchy. This level tolds how many parents for this item are before (Root) item. For example, our categories have level 0 (top-level) items, but our last child have level 2. This all me be read by Level property of Item.



Picture above shows how level structure looks in our example.

One very important property of item is ParentItem which as name say point to the Parent item of item. For example, next code collapse parent of currently selected item.

if NextInspector1.SelectedItem.ParentItem <> nil then NextInspector1.SelectedItem.ParentItem.Expanded := False;


As may be seen in this example, we have need to check if ParentItem is maybe nil because top-level items categories naturaly don't have own parent items.

Items (nodes) with same level but with same parent are called "Siblings". Every node have GetLastSiblings and GetFirstSiblings function for retreiving last or first of them. It may be handy in some situations.

4. Relative Index of item



As we already know what AbsoluteIndex is (again, simply index of item in one list), if we know that some item is 3rd item of item we can get use relative index. Example:

NextInspector1.Items[4].Item[2].AsInteger := 4;



NextInspector1->Items[4]->Item[2]->AsInteger = 4;


Very easy. As we assume that Item with absolute index 4 will allways be there we may easily access to the 3rd item of Items[4].

5. More important properties of item



As you probably know, Value property may be called as Item.AsString property. Result is equal in both cases, but you may also call: AsBoolean which is good choice for TNxCheckBoxItem, AsInteger or AsFloat which may be use for TNxSpinItem... only need to remember that non-float value such as "seven" is not valid as "7" to be passed as AsFloat property.

Property ReadOnly if set to True disable item for editing. But, property Enable disable item even for selecting (clicking by mouse). Caption will be also drawn in gray to indicate that this ite is disabled.



Property Visible when set to False will hide item for being drawn. Item is still here, but it won't be drawn.

6. Suffixes



Every item may have own small combo-box with additional values we called them suffixes. There are many situations like this where first need to be value entered and then measure unit chosen. This is why suffixes are great.

First, Suffixes, TStringList property need to be filled. Example: px, pt, picas...

Then property ShowSuffix need to be set to True:



7. Managing items



New item may be added in various ways, to be added, deleted or moved.

7.1. Adding items



Easiest way to add new item in run-time is with using AddChild function of Items property. This method both create and add item into items array.

NextInspector1.Items.AddChild(nil, TNxTextItem, 'Sample caption');


First param (in our case nil) indicate that new item will be top-level (category) item. If we set some other item here like in next example, newly added item will become child item:

NextInspector1.Items.AddChild(NextInspector1.Items[2], TNxTextItem, 'Sample caption');


Second param TNxTextItem, indicate class for newly created item. It may be other item class such as TNxSpinItem, TNxToolbarItem...

AddChildFirst function works in similar way, but new item will be added as first child of specified item:

NextInspector1.Items.AddChildFirst(NextInspector1.Items[1], TNxDateItem, 'Date item');


Example:

NextInspector1.Items.AddChild(NextInspector1.Items[0], TNxTextItem, 'Text item');
NextInspector1.Items.AddChildFirst(NextInspector1.Items[0], TNxDateItem, 'Date item');


As we know that Items[0] is first item in array, result will be:



Both AddChild and AddChildFirst returns newly created item as result. Example:

procedure TForm1.Button1Click(Sender: TObject);
var
  AItem: TNxTextItem;
begin
  AItem := NextInspector1.Items.AddChild(nil, TNxTextItem, 'Parent item') as TNxTextItem;
  NextInspector1.Items.AddChild(AItem, TNxDateItem, 'Child item');
end;


Result:



If we want to manually create item, set properties and add it into items array we may use AddItem procedure.

procedure TForm1.Button1Click(Sender: TObject);
var
  NewItem: TNxSpinItem;
begin
  NewItem := TNxSpinItem.Create(Self);
  NewItem.Caption := 'Spin item';
  NewItem.AsInteger := 3; // Set Value to '3'
  NextInspector1.Items.AddItem(NextInspector1.Items[0], NewItem);
end;


Result:



And item also include own AddChild method whic may be called as first one:

// We assume that NxTextItem already exists
NxTextItem1.AddChild(TNxTrackBarItem, 'Trackbar Item');


In Delphi, since AddChild, AddChildFirst and Item.AddChild return reference of newly created and added item, command with may be used.

with NextInspector1.Items.AddChild(nil, TNxTextItem, 'Category') do
begin
  AddChild(TNxTextItem, 'TextItem').AsString := 'Test'; // AddChild of item, it also return a reference.
end;




7.2. Deleting items



Items may be deleted in 2 basic ways:

1. By calling Delete method of Items property
2. By destroying item.

Delete procedure include Index: Integer param and simply call Items[Index].Free. When item is destroyed by calling .Free it is automatically removed from items array too.

NextInspector1.Items.Delete(3);



NextInspector1->Items->Delete(3);


or

NextInspector1.Items[3].Free;


Item also include own Delete() procedure which delete item itself.

DeleteChildren of item will delete all child items belong to item.

Clear method of NextInspector delete and destroys all items inside items array. This method is actually called when NextInspector is destroyed (for example after Form is closed).

7.3. Moving items



Item may be moved by using own MoveTo method. This method moves the node to another location in the Next Inspector.

Table 1: MoveTo Params
Meaning Type Meaning
Destination TNxPropertyItem The Destination parameter specifies a node that will be this node's parent or sibling after the move.
Mode TNodeAttachMode The Mode parameter specifies the new relationship between this node and the destination node. More about TNodeAttachType in Delphi help


8. Full example



Here is a full example how to add few items in run-time using different techniques:

procedure TForm1.Button1Click(Sender: TObject);
var
  MySpinItem: TNxSpinItem;
  MyAnotherItem: TNxPropertyItem;
begin
  with NextInspector1.Items.AddChild(nil, TNxTextItem, 'Category 1') do
  begin
    MySpinItem := AddChild(TNxSpinItem, 'Number') as TNxSpinItem;
    MySpinItem.AsFloat := 2.5;
    MySpinItem.Max := 20;
  end;
  NextInspector1.Items.AddChildFirst(NextInspector1.Items[0], TNxTextItem, 'Sub-category');
  { MySpinItem will become child item of 'Sub-category' }
  MySpinItem.MoveTo(NextInspector1.Items[1], naAddChild); { ComCtrls in uses }
  { Creating one more item manualy }
  MyAnotherItem := TNxCheckBoxItem.Create(Self);
  MyAnotherItem.Caption := 'My Item';
  MyAnotherItem.AsBoolean := False;
  MyAnotherItem.Color := clRed;
  TNxCheckBoxItem(MyAnotherItem).FlatStyle := True;
  NextInspector1.Items.AddItem(NextInspector1.Items[0], MyAnotherItem);
end;

Was This Article Useful?

Comments

2009-05-15 04:57:44

Need example adding item for c++ builder

2009-05-15 13:51:30

Hi,

Here is small example:

TNxTextItem *ATopItem = new TNxTextItem(this);
// Set properties for item
ATopItem->Caption = "Root Item";
ATopItem->ReadOnly = true;

// Add Item into Items array as Top-level item (first parameter NULL)
NextInspector1->Items->AddItem(NULL, ATopItem);

I suggest opening Adding Items demo project in Demos\BCB\Next Inspector folder

I hope that this helps
Only constructive comments, code contributions... will be publishes. Questions, non-official discussion will not be published.