Expand/Shrink

IupFlatTree

Definition: include pGUI.e

Ihandle ih = IupFlatTree(string attributes="", dword_seq args={})
Description: Creates a tree containing nodes of branches or leaves. Both branches and leaves can have an associated text and image.

For more information on the attributes and args parameters see IupSetAttributes.

The branches can be expanded or collapsed. When a branch is expanded, its immediate children are visible, and when it is collapsed they are hidden.

The leaves can generate an "executed" or "renamed" actions, [?? branches can only generate a "renamed" action. ??]

The focus node is the node with the focus rectangle, marked nodes have their background inverted.

It behaves like IupTree but it does not depend on the native system.

It inherits from IupCanvas.

Returns: the identifier of the created element.
pwa/p2js: Not supported, see IupTreeView instead.
See Also: IupTree
Notes: IupFlatTree is almost identical to the IupTree with some additional attributes,
but it has a major difference: all the attributes work before map.
So you can add and remove nodes before the element is mapped to the native system.

Another important difference is that there is no ADDROOT attribute.
IupFlatTree behaves as ADDROOT=NO always, so there is never an initial root branch.
Note: I (PL) have found by experiment that an IupFlatTree must have at least one of these:
IupSetAttribute(tree, "ADDBRANCH-1", "text") or
IupSetAttribute(tree, "ADDLEAF-1", "text")

The SPACING attribute is simply the vertical space between each node, different from the IupTree.

The EMPTYTOGGLE attribute replaces EMPTYAS3STATE and it works in all systems.

Finally all features behave the same in all systems.

An example can be seen in demo\pGUI\IupFlatTree.exw, and there is also one in demo\pGUI\sample.exw
Hierarchy Branches can contain other branches or leaves.
The first node always has id=0 and depth=0.
The tree nodes have a sequential identification number (id), starting by the first, with id=0, and increases for each node independent from the node depth.
The following picture illustrates the numbering of the nodes in a tree.

Tree nodes and Ids Since you have to add each node the creation of this tree can be done in several ways because the action attributes ADD* and INSERT* use an existent node to position the new node.

The following pseudo code initializes the tree from top to bottom sequentially: 

(0)         TITLE0 = "Figures"
(1)           ADDLEAF0 = "Other"               // Use previous node as reference
(2)           ADDBRANCH1 = "triangle"
(3)             ADDLEAF2 = "equilateral"
(4)             ADDLEAF3 = "isoceles"
(5)             ADDLEAF4 = "scalenus"
(6)           INSERTBRANCH2 = "parallelogram"  // Use previous node at same depth as reference
(7)             ADDLEAF6 = "square"
(8)             ADDLEAF7 = "diamond"
(9)           INSERTBRANCH6 = "2D"
(10)          INSERTBRANCH9 = "3D"

The following pseudo code initializes the tree from bottom to top sequentially (except for branches), and also uses the focus node: 

            VALUE = 0  // Set the focus node at the first (default for a new element)
            TITLE = "Figures"
            ADDBRANCH = "3D"
            ADDBRANCH = "2D"
            ADDBRANCH = "parallelogram"
            ADDLEAF1 = "diamond"
            ADDLEAF1 = "square"
            ADDBRANCH = "triangle"
            ADDLEAF1 = "scalene"
            ADDLEAF1 = "isosceles"
            ADDLEAF1 = "equilateral"
            ADDLEAF = "Other"

Notice that in both cases the initialization of the tree is highly dependent on the order of the operations.

Scrollbars are automatically displayed if the tree is greater than its display area.

The first node added to an empty tree will always be the focus node.

Alternatively, and often much simpler, trees can be populated from a nested sequence, see IupTreeAddNodes().
Manipulation Node insertion or removal is done by means of attributes. It is allowed to remove nodes and branches inside callbacks associated to opening or closing branches.

This means that the user may insert nodes and branches only when necessary when the parent branch is opened, allowing the use of a larger IupTree without too much overhead.
Then when the parent branch is closed the subtree can be removed.
But the subtree must have at least 1 node so the branch can be opened and closed, empty branches can NOT be opened.
User Data The node id does not always correspond to the same node as the tree is modified.
For example, an id=2 will always refer to the third node in the tree, so if you add a node before the third node, the node with id=2 will now refer to the new node, and the old node will now have id=3.
For that reason, each node can store an user data pointer uniquely identifying the node.
To set or retrieve the user data of a node use the USERDATAid attribute, or the Extra Functions below to associate a user data to a node and to find a node given its user data.
Images IupFlatTree has three types of images: one associated to the leaf, one to the collapsed branch and the other to the expanded branch.
Each image can be changed, both globally and individually.

The predefined images used in IupFlatTree can be obtained by means of function IupGetHandle().
The names of the predefined images are: IMGLEAF, IMGCOLLAPSED, IMGEXPANDED, IMGBLANK (blank sheet of paper) and IMGPAPER (written sheet of paper).
By default:

"IMAGELEAF" uses "IMGLEAF"
"IMAGEBRANCHCOLLAPSED" uses "IMGCOLLAPSED"
"IMAGEBRANCHEXPANDED" uses "IMGEXPANDED"

"IMGBLANK" and "IMGPAPER" are designed for use as "IMAGELEAF"

The default images are 16x16 pixels on standard resolution and 24x24 pixels on high resolution (4k displays), but you can force the use of the high resolution images by defining the global attribute "TREEIMAGE24" to "Yes".

All imagens do NOT need to have the same size, but it is recommended that a pair of branch open and branch collapsed to have the same size.

IMGEMPTY can be used as branches or leafs to clear the image (a totally transparent image).
Simple Marking It is the default operation mode (MARKMODE=SINGLE). In this mode only one node can be selected.
Multiple Marking IupFlatTree allows marking several nodes simultaneously using the Shift and Control keys.
To use multiple marking set MARKMODE=MULTIPLE.
Multiple nodes can also be selected using mouse dragging if SHOWDRAGDROP=NO.

When a user keeps the Control key pressed, the individual marking mode is used.
This way, the focus node can be modified without changing the marked node.
To reverse a node marking, the user simply has to press the space bar.

When the user keeps the Shift key pressed, the block marking mode is used.
This way, all nodes between the focus node and the initial node are marked, and all others are unmarked.
The initial node is changed every time a node is marked without the Shift key being pressed.
This happens when any movement is done without Shift or Control keys being pressed, or when the space bar is pressed together with Control.
Extra Text Area (since 3.30) The extra text area is displayed when EXTRATEXTWIDTH is greater than 0.
It is located at right, and displays additional text associated with each node.
The split handler can be controlled by the user and directly sets the EXTRATEXTWIDTH attribute.
Navigation Using the keyboard:
  • Arrow Up/Down: Moves the focus node to the neighbor node, according to the arrow direction. If Shift is pressed and MARKMODE=MULTIPLE a continuous range of cells is selected.
  • Home/End: Moves the focus node to the first/last node.
  • Page Up/Page Down: Moves the focus node to the node one visible page above/below the focus node.
  • Enter: If the focus node is an expanded branch, it is collapsed; if it is a collapsed branch, it is expanded; if it is a leaf, it is executed.
  • Ctrl+Arrow Up/Down: Moves only the focus node.
  • Ctrl+Space: Marks or unmarks the node at focus.
  • F2: Calls the rename callback or invokes the in place rename.
  • Esc: cancels in place rename.
Using the left mouse button:
  • Clicking a node: Moves the focus node to the clicked node.
  • Clicking a (-/+) box: Makes the branch to the right of the (-/+) box collapse/expand.
  • Double-clicking a node: Moves the focus node to the clicked node. If the node is an expanded branch, it is collapsed; if it is a collapsed branch, it is expanded; if it is a leaf, it is executed.
  • Clicking twice a node: Calls the rename callback or invokes the in place rename.
  • Clicking and dragging a node: if SHOWDRAGDROP=Yes starts a drag. When mouse is released, the DRAGDROP_CB callback is called.
    If the callback does not exist or if it returns IUP_CONTINUE then the node is moved to the new position.
    If Ctrl is pressed then the node is copied instead of moved. In Motif drag is performed with the middle mouse button.
Removing a Node with "Del"
By default the Del key is not processed, but you can implement it using a simple K_ANY callback: 

    function k_any(Ihandle ih, integer c)
        if c == K_DEL then IupSetAttribute(ih,"DELNODE","MARKED") end if 
        return IUP_CONTINUE
    end function
Extra Functions IupFlatTree has functions that allow associating a pointer (or a user defined id) to a node.
In order to do that, you provide the id of the node and the pointer (userid); even if the node’s id changes later on (because of insertions/deletions above/below it), the userid will still be associated with the given node.
A positive integer index, to some other table, is recommended in Phix, whereas using raw pointers would most likely require additional/careful/tedious memory management.
These functions all use the USERDATAid attribute.

IupFlatTree shares the same functions with IupTree.

IupTreeSetUserId(Ihandle ih, integer id, atom userid)
ih: Identifier of the interface element.
id: Node identifier.
userid: User index or pointer to be associated with the node. Use NULL to remove the association.

Associates a userid with a given id. If the id of the node is changed, the userid remains the same. Terminates in error if the node cannot be found.

atom userid = IupTreeGetUserId(Ihandle ih, integer id)
ih: Identifier of the interface element.
id: Node identifier.

Returns the index or pointer associated to the node or NULL if none was associated.
IupTreeSetUserId must have been called for the node with the given id.

integer id = IupTreeGetId(Ihandle ih, atom userid)
ih: Identifier of the interface element.
userid: Index or pointer associated to the node.

Returns the id of the node that has the userid on success or -1 (nil) if not found. IupTreeSetUserId must have been called with the same userid.

The utility functions IupSetAttributeId, IupGetAttributeId, IupGetIntId, IupGetFloatId, IupSetIntId, and IupSetFloatId can also be used here, as well as IupTreeAddNodes.

They work just like the respective traditional set and get functions, but the attribute string is complemented with the id value. For example: 

IupSetAttributeId(ih, "KIND", 30, value) == IupSetAttribute(ih, "KIND30", value)
IupSetAttributeId(ih, "ADDLEAF", 10, value) == IupSetAttribute(ih, "ADDLEAF10", value)

These functions are faster than the traditional functions because they do not need to parse the attribute name string and the application does not need to concatenate the attribute name with the id, although you will probably only notice if you are processing a very large tree. Note that the C function IupSetfAttributeId is not wrapped by pGUI, however that functionality is covered by the optional parameters of IupSetStrAttributeId.
Attributes: Inherits all attributes and callbacks of the IupCanvas, but redefines a few attributes.

Different from the IupTree, all attributes are functional before map.
The attributes marked with (*) are exclusive to the IupFlatTree and are NOT support in the regular IupTree.
General
AUTOREDRAW (non inheritable) automatically redraws the tree when something has change.
Set to NO to add many items to the tree without updating the display. Default: "YES".
BGCOLOR Background color of the tree. Default: the global attribute TXTBGCOLOR.
BORDERCOLOR(*) color used for the internal border. Default: "50 150 255". This is for the internal border.
BORDERWIDTH(*) line width used for the internal border. Default: "0". The internal borders are hidden by simply setting this value to 0. It is drawn inside the canvas, so inside the scrollbars.
COUNT (read only, non inheritable) returns the total number of nodes in the tree.
EXPAND (non inheritable) The default value is "YES".
EXTRATEXTWIDTH(*) width of the extra text area at right. (since 3.30)
FGCOLOR default text foreground color.
Once each node is created it will not change its color when FGCOLOR is changed.
Default: the global attribute TXTFGCOLOR.
HLCOLOR(*) (non inheritable) color of a filled box drawn over the selected node. Default: TXTHLCOLOR global attribute.
HLCOLORALPHA(*) the transparency used to draw the selection. Default: 128. If set to 0 the selection box is not drawn.
PSCOLOR(*) background color of a selected node. If not defined BACKCOLORid will be used. (since 3.30)
TEXTPSCOLOR(*) foreground color of a selected node. If not defined FORECOLORid will be used. (since 3.30)
ICONSPACING(*) (non inheritable) spacing between the image and the text. Default: "2".
INDENTATION sets the indentation level in pixels.
Default: 16 for standard resolution, 24 for high resolution display.
RASTERSIZE (non inheritable) the initial size is "400x200". Set to NULL to allow the automatic layout use smaller values.
SPACING vertical space between nodes. Notice that this is not the same as the IupTree.
CSPACING same as SPACING but using the units of the vertical part of the SIZE attribute. It will actually set the SPACING attribute. (since 3.29)
TOPITEM (write-only) position the given node identifier at the top of the tree or near to make it visible.
If any parent node is collapsed then they are automatically expanded.
invalid The following are not used on IupFlatTree (unlike IupTree):
ADDROOT (behaves as if "NO"), EMPTYAS3STATE (replaced with EMPTYTOGGLE), INFOTIP (uses regular TIP behaviour instead)
Also: ACTIVE, EXPAND, FONT, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, SIZE, RASTERSIZE, ZORDER, VISIBLE, THEME: also accepted.

Expanders (non inheritable)
HIDEBUTTONS hide the expand and collapse buttons.
HIDELINES hide the lines that connect the nodes in the hierarchy.
LINECOLOR(*) the color of the dotted guidelines. Default: "110 110 110"
BUTTONBGCOLOR(*) background color of the expander buttons. Default: "240 240 240"
BUTTONFGCOLOR(*) sign color of the expander buttons ("+" or "-" signs). Default: "50 100 150"
BUTTONBRDCOLOR(*) border color of the expander buttons. Default: "150 150 150"
BUTTONSIZE(*) size of the expander button square. Default: 9 for standard resolution, 16 for high resolution display
BUTTONPLUSIMAGE(*) the image name that will be shown for all expander button when collapsed. By default the button is drawn.
The "IMGPLUS" pre-defined image is a 9x9 image that can be used.
BUTTONMINUSIMAGE(*) the image name that will be shown for all expander button when collapsed. By default the button is drawn.
The "IMGMINUS" pre-defined image is a 9x9 image that can be used.
Nodes (non inheritable) For these attributes "id" is the specified node identifier.
If "id" is empty or invalid, then the focus node is used as the specified node.
CHILDCOUNTid (read only) returns the immediate children count of the specified branch.
It does not count children of child that are branches.
TOTALCHILDCOUNTid (read only) returns the total children count of the specified branch. It counts all grandchildren too.
ROOTCOUNT (read only) returns the number of root nodes. (since 3.23)
COLORid foreground color of the title at the given id. If not defined FGCOLOR is used.
The value should be a string in the format "R G B" where R, G, B are numbers from 0 to 255.
BACKCOLOR(*) background color of the title at the given id. If not defined BGCOLOR is used.
ITEMTIP(*) tip of the node at the given id. If defined will be shown instead of the TIP attribute.
DEPTHid (read only) returns the depth of the specified node.
The first node has depth=0, its immediate children has depth=1, their children has depth=2 and so on.
KINDid (read only) returns the kind of the specified node.
Possible values:

"LEAF": The node is a leaf
"BRANCH": The node is a branch
PARENTid (read only) returns the identifier of the specified node.
NEXTid (read only) returns the next brother (same depth) of the specified node.
Returns NULLs if at last child node of the parent (at the same depth).
PREVIOUSid (read only) returns the previous brother (same depth) of the specified node.
Returns NULLs if at first child node of the parent (at the same depth).
LASTid (read only) returns the last brother (same depth) of the specified node.
FIRSTid (read only) returns the first brother (same depth) of the specified node.
This is the same as getting the first child of the parent of the given node.
If the specified node is the first child returns the specified node.
STATEid the state of the specified branch. Returns NULL for a LEAF.
Possible values:

"EXPANDED": Expanded branch state (shows its children)
"COLLAPSED": Collapsed branch state (hides its children)
TITLEid the text label of the specified node.
TITLEFONTid the text font of the specified node. The format is the same as the FONT attribute.
TITLEFONTSTYLEid changes the font style of the specified node. Actually changes the TITLEFONTid attribute.
TITLEFONTSIZEid changes the font size of the specified node. Actually changes the TITLEFONTid attribute.
USERDATAid the user data associated with the specified node.
EXTRATEXTid(*) text displayed at the extra text area at right. (since 3.30)
Toggle (non inheritable)
SHOWTOGGLE enables the use of toggles for all nodes of the tree.
Can be "YES", "3STATE" or "NO". Default: "NO".
EMPTYTOGGLE(*) when SHOWTOGGLE=Yes, the empty space left in nodes that TOGGLEVISIBLEid=NO is filled with a blank space. Can be Yes or NO. Default: No.
TOGGLEVALUEid defines the toggle state. Values can be "ON" or "OFF".
If SHOW3STATE=YES then can also be "NOTDEF". Default: "OFF".
TOGGLEVISIBLEid defines the toggle visible state. Values can be "Yes" or "No". Default: "Yes".
TOGGLEBGCOLOR(*) background color of the toggle. Default: "TXTBGCOLOR"
TOGGLEFGCOLOR(*) foreground color of the toggle, use to draw the frame and the check mark. Default: "TXTFGCOLOR"
TOGGLESIZE(*) size of the toggle square. Default: 16 for standard resolution, 24 for high resolution display
Images (non inheritable)
IMAGEid (write only) image name to be used in the specified node, where id is the specified node identifier.
Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage.
If node is a branch it is used when collapsed.
All images do NOT need to have the same size, but it is recommended that a branch expanded and collapse images to have the same size.
IMAGEEXPANDEDid (write only) same as the IMAGE attribute but used for expanded branches.
IMAGELEAF the image name that will be shown for all leaves. Default: "IMGLEAF" (a bullet).
Internal values "IMGBLANK" (blank sheet of paper) and "IMGPAPER" (written sheet of paper) are also available.
If BGCOLOR is set the image is automatically updated. This image defines the available space for the image in all nodes.
"IMGEMPTY" can be used as a totally transparent image .
IMAGEBRANCHCOLLAPSED the image name that will be shown for all collapsed branches. Default: "IMGCOLLAPSED" (a closed folder).
IMAGEBRANCHEXPANDED the image name that will be shown for all expanded branches. Default: "IMGEXPANDED" (an open folder).
BACKIMAGE(*) image name to be used as background.
Use IupSetHandle or IupSetAttributeHandle to associate an image to a name. See also IupImage.
BACKIMAGEZOOM(*) if set the back image will be zoomed to occupy the full background. Aspect ratio is NOT preserved. Can be Yes or No. Default: No.
Focus (non inheritable)
VALUE The focus node identifier.
When retrieved but there isn’t a node with focus it returns 0 if there are any nodes, and returns -1 if there are no nodes.
When changed and MARKMODE=SINGLE the node is also selected. The tree is always scrolled so the node becomes visible.
Additionally accepts the values:

"ROOT" or "FIRST": the first node (which is always expanded)
"LAST": the last expanded node
"NEXT": the next expanded node, one node after the focus node. If at the last does nothing
"PREVIOUS": the previous expanded node, one node before the focus node. If at the first does nothing
"PGDN": the next expanded node, ten nodes node after the focus node. If at the last does nothing
"PGUP": the previous expanded node, ten nodes before the focus node. If at the first does nothing
"CLEAR": clears the selection of the focus node.
CANFOCUS (creation only) enables the focus traversal of the control. Default: YES.
PROPAGATEFOCUS enables the focus callback forwarding to the next native parent with FOCUS_CB defined. Default: NO.
FOCUSFEEDBACK(*) (non inheritable) draw the focus feedback. Can be Yes or No. Default: Yes.
HASFOCUS(*) (read-only) returns the button state if has focus. Can be Yes or No.
Marks (non inheritable)
MARK (write only) Selects a range of nodes in the format "start-end" (%d-%d).
Allowed only when MARKMODE=MULTIPLE. Also accepts the values:

"INVERTid": Inverts the specified node selected state, where id is the specified node identifier. If id is empty or invalid, then the focus node is used as reference node.
"BLOCK": Selects all nodes between the focus node and the initial block-marking node defined by MARKSTART
"CLEARALL": Clear the selection of all nodes
"MARKALL": Selects all nodes
"INVERTALL": Inverts the selection of all nodes
MARKEDid The selection state of the specified node, where id is the specified node identifier.
If id is empty or invalid, then the focus node is used as reference node. Can be: YES or NO. Default: NO
MARKEDNODES The selection state of all nodes.
It is/accepts a sequence of '+' and '-' symbols indicating the state of each item ('+'=selected, '-'=unselected).
When setting this value, if the number of specified symbols is smaller than the total count then the remaining nodes will not be changed.
Can be set only when MARKMODE=MULTIPLE, can also be get when MARKMODE=SINGLE.
MARKMODE defines how the nodes can be selected. Can be: SINGLE or MULTIPLE. Default: SINGLE.
MARKSTART Defines the initial node for the block marking, used when MARK=BLOCK.
The value must be the node identifier. Default: 0 (first node).
MARKWHENTOGGLE selects or clears the selection of a node when its toggle is changed.
Works only if the node has a toggle. Default: No.
Hierarchy (non inheritable) For these attributes "id" is the specified node identifier.
If "id" is empty or invalid, then the focus node is used as the specified node.
ADDEXPANDED (non inheritable) Defines if branches will be expanded when created.
The branch will be actually expanded when it receives the first child.
Possible values: "YES" = The branches will be created expanded; "NO" = The branches will be created collapsed. Default: "YES".
ADDLEAFid (write only) Adds a new leaf after the reference node, where id is the reference node identifier.
Use id=-1 to add before the first node. The value is used as the text label of the new node.
The id of the new node will be the id of the reference node + 1.
The attribute LASTADDNODE is set to the new id.
The reference node is marked and all others unmarked.
The reference node position remains the same.
If the reference node does not exist, nothing happens.
If the reference node is a branch then the depth of the new node is one depth increment from the depth of the reference node,
if the reference node is a leaf then the new node has the same depth.
If you need to add a node after a specified node but at a different depth use INSERTLEAF.
ADDBRANCHid (write only) Same as ADDLEAF for branches. Branches can be created expanded or collapsed depending on ADDEXPANDED.

Initial layout After calling IupSetAttribute(ADDBRANCH9, "new branch"):
COPYNODEid (write only) Copies a node and its children, where id is the specified node identifier.
The value is the destination node identifier.
If the destination node is a branch and it is expanded, then the specified node is inserted as the first child of the destination node.
If the branch is not expanded or the destination node is a leaf, then it is inserted as the next brother of the leaf.
The specified node is not changed. All node attributes are copied, except user data.
DELNODEid (write only) Removes a node and/or its children, where id is the specified node identifier.
Possible values:

"ALL": deletes all nodes, id is ignored.
"SELECTED": deletes the specified node and its children
"CHILDREN": deletes only the children of the specified node
"MARKED": deletes all the selected nodes (and all their children), id is ignored
EXPANDALL (write only) expand or contracts all nodes. Can be YES (expand all), or NO (contract all).
INSERTLEAFid,
INSERTBRANCHid 		(write only) Same as ADDLEAF and ADDBRANCH but the depth of the new node is always the same of the reference node.
If the reference node is a leaf, then the id of the new node will be the id of the reference node + 1.
If the reference node is a branch the id of the new node will be the id of the reference node + 1 + the total number of child nodes of the reference node.

Initial layout After calling IupSetAttribute(INSERTBRANCH9, "new branch"):
MOVENODEid (write only): Moves a node and its children, where id is the specified node identifier.
The value is the destination node identifier.
If the destination node is a branch and it is expanded, then the specified node is inserted as the first child of the destination node.
If the branch is not expanded or the destination node is a leaf, then it is inserted as the next brother of the leaf.
The specified node is removed. User data and all node attributes are preserved.
Editing
RENAME (write only) Forces a rename action to take place. Valid only when SHOWRENAME=YES.
RENAMECARET (write only) the caret’s position of the text box when in-place renaming.
Same as the CARET attribute for IupText, but here is used only once after SHOWRENAME_CB is called and before the text box is shown.
RENAMESELECTION (write only) the selection interval of the text box when in-place renaming.
Same as the SELECTION attribute for IupText, but here is used only once after SHOWRENAME_CB is called and before the text box is shown.
SHOWRENAME (non inheritable) Allows the in place rename of a node. Default: "NO".
F2 and clicking twice only starts to rename a node if SHOWRENAME=Yes.
Drag&Drop Drag & Drop attributes are supported, but SHOWDRAGDROP must be set no No.
DRAGDROPTREE (non inheritable) prepare the Drag & Drop callbacks to support drag and drop of nodes between trees (IupFlatTree only), in the same IUP application.
Drag & Drop attributes still need to be set in order to activate the drag & drop support, so the application can control if this tree will be source and/or target.
Default: NO.
DROPFILESTARGET (non inheritable) Enable or disable the drop of files.
Default: NO, but if DROPFILES_CB is defined when the element is mapped then it will be automatically enabled.
This is NOT related to the drag&drop of nodes inside the tree.
DROPEQUALDRAG (non inheritable) if enabled will allow a drop node to be equal to the drag node.
Used only if SHOWDRAGDROP =Yes.
In the case the nodes are equal the callback return value is ignored and nothing is done after.
SHOWDRAGDROP (non inheritable) Enables the internal drag and drop of nodes, and enables the DRAGDROP_CB callback. Default: "NO".
Works only if MARKMODE=SINGLE. Drag & Drop attributes are NOT used.
Callbacks: Inherits all callbacks of the IupCanvas, but redefines a few of them.
Including BUTTON_CB, LEAVEWINDOW_CB, FOCUS_CB, and MOTION_CB. To allow the application to use those callbacks the same callbacks are exported with the "FLAT_" prefix using the same parameters.
They are all called before the internal callbacks and if they return IUP_IGNORE the internal callbacks are not processed.

Drag & Drop attributes and callbacks are supported, but SHOWDRAGDROP must be set to NO.
SELECTION_CB Action generated when a node is selected or deselected.

This action occurs when the user clicks with the mouse or uses the keyboard with the appropriate combination of keys.
It may be called more than once for the same node with the same status.

function selection_cb(Ihandle ih, integer id, status)
ih: identifier of the element that activated the event.
id: Node identifier.
status: 1=node selected, 0=node unselected.
MULTISELECTION_CB Action generated after a continuous range of nodes is selected in one single operation.
If not defined the SELECTION_CB with status=1 will be called for all nodes in the range.
The range is always completely included, independent if some nodes were already marked.
That single operation also guaranties that all other nodes outside the range are already not selected.
Called only if MARKMODE=MULTIPLE.

function multiselection_cb(Ihandle ih, atom pIds, integer n)
ih: identifier of the element that activated the event.
pIds: Pointer to an array of node identifiers.
This array is kept for backward compatibility, the range is simply defined by ids[0] to ids[n-1], where ids[i+1]=ids[i]+1.
n: Number of nodes in the array.
MULTIUNSELECTION_CB Action generated before multiple nodes are unselected in one single operation.
If not defined the SELECTION_CB with status=0 will be called for all nodes in the range.
The range is not necessarily continuous. Called only if MARKMODE=MULTIPLE. (Since 3.1)

function multiunselection_cb(Ihandle ih, atom pIds, integer n)
ih: identifier of the element that activated the event.
pIds: Pointer to an array of node identifiers.
n: Number of nodes in the array.
BRANCHOPEN_CB Action generated when a branch is expanded.
This action occurs when the user clicks the "+" sign on the left of the branch, or when double clicks the branch, or hits Enter on a collapsed branch.

function branchopen_cb(Ihandle ih, integer id)
ih: identifier of the element that activated the event.
id: node identifier.

Returns: IUP_IGNORE for the branch not to be opened, or IUP_DEFAULT for the branch to be opened.
BRANCHCLOSE_CB Action generated when a branch is collapsed.
This action occurs when the user clicks the "-" sign on the left of the branch, or when double clicks the branch, or hits Enter on an expanded branch.

function branchclose_cb(Ihandle ih, integer id)
ih: identifier of the element that activated the event.
id: node identifier.

Returns: IUP_IGNORE for the branch not to be closed, or IUP_DEFAULT for the branch to be closed.
EXECUTELEAF_CB Action generated when a leaf is to be executed.
This action occurs when the user double clicks a leaf, or hits Enter on a leaf.

function executeleaf_cb(Ihandle ih, integer id)
ih: identifier of the element that activated the event.
id: node identifier.
EXECUTEBRANCH_CB Action generated when a branch is executed.
This action occurs when the user double clicks a branch, or hits Enter on a branch.
Is is called before the BRANCH*_CB callbacks.

function executebranch_cb(Ihandle ih, integer id)
ih: identifier of the element that activated the event.
id: node identifier.
SHOWRENAME_CB Action generated when a node is about to be renamed.
It occurs when the user clicks twice the node or press F2. Called only if SHOWRENAME=YES.

function showrename_cb(Ihandle ih, integer id)
ih: identifier of the element that activated the event.
id: node identifier.

Returns: if IUP_IGNORE is returned, the rename is canceled.
RENAME_CB Action generated after a node was renamed in place.
It occurs when the user press Enter after editing the name, or when the text box looses it focus. Called only if SHOWRENAME=YES.

function rename_cb(Ihandle ih, integer id, atom pTitle)
ih: identifier of the element that activated the event.
id: node identifier.
pTitle: new node title (a char*).

Returns: The new title is accepted only if the callback returns IUP_DEFAULT.
If the callback does not exist the new title is always accepted.
If the user pressed Enter and the callback returns IUP_IGNORE the editing continues.
If the text box looses its focus the editing stops always.
DRAGDROP_CB Action generated when an internal drag & drop is executed. Only active if SHOWDRAGDROP=YES.

function dragdrop_cb(Ihandle ih, integer drag_id, drop_id, isshift, iscontrol)

ih: identifier of the element that activated the event.
drag_id: Identifier of the clicked node where the drag start.
drop_id: Identifier of the clicked node where the drop were executed. -1 indicates a drop in a blank area.
isshift: flag indicating the shift key state.
iscontrol: flag indicating the control key state.

Returns: if returns IUP_CONTINUE, or if the callback is not defined and SHOWDRAGDROP=YES, then the node is moved to the new position.
If Ctrl is pressed then the node is copied instead of moved.
If the drop node is a branch and it is expanded, then the drag node is inserted as the first child of the node.
If the branch is not expanded or the node is a leaf, then the drag node is inserted as the next brother of the drop node.
NODEREMOVED_CB Action generated when a node is about to be removed.
It is only a notification, the action can not be aborted.
No node dependent attribute can be consulted during the callback.
It is useful to remove memory allocated for the userdata.

function noderemoved_cb(Ihandle ih, atom pUserdata)
ih: identifier of the element that activated the event.
pUserdata: pointer to userdata.
RIGHTCLICK_CB Action generated when the right mouse button is pressed over a node.

function rightclick_cb(Ihandle ih, integer id)
ih: identifier of the element that activated the event.
id: node identifier.
TOGGLEVALUE_CB Action generated when the toggle’s state was changed.
The callback also receives the new toggle’s state.

function togglevalue_cb(Ihandle ih, integer id, state)
ih: identifier of the element that activated the event.
id: node identifier.
state: 1 if the toggle’s state was shifted to ON; 0 if it was shifted to OFF. If SHOW3STATE=YES, -1 if it was shifted to NOTDEF.
FLAT_BUTTON_CB Action generated when any mouse button is pressed or released inside the element.
Use IupConvertXYToPos() to convert (x,y) coordinates in the node identifier.
FLAT_MOTION_CB Action generated when the mouse is moved over the element.
Use IupConvertXYToPos() to convert (x,y) coordinates in item the node identifier.
DROPFILES_CB [Windows and GTK Only] Action generated when one or more files are dropped in the element.
also MAP_CB, UNMAP_CB, DESTROY_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB: All common callbacks are supported.
Example: See demo\pGUI\IupFlatTree.exw