Understanding Tree Node Events

[Teknojnky]

This is mostly to clarify in my own mind and help me understand these correctly, and hopefully anyone else as well.

http://www.mediamonkey.com/wiki/index.php/SDBTreeNode

Feel free to correct or add more detail. Perhaps later it can be added to the wiki.

• OnCanEditNode: If this Event is not registered, then it appears the node text can not be edited (f2 or mouse click). If for some reason you want to disable editing a particular node, you must have a Function that returns FALSE, otherwise to enable editing the node text this function must return TRUE.
  
  Bug? This event is fired on every single click, instead of only F2 or slow double click so it basically will fire every time the node is clicked (even if the node was already current/active).
  
  Bug? This event is also fired when the focus enters or leaves the node's tracklist (ie clicking from now playing track list, to node track list, or vice versa).
• OnExecMenuItem: This Function is executed when clicking a menu item (from OnShowMenuItem) of a custom node, this event lets you over-ride the properties and/or remove functions for the selected node.
• OnExecTrackMenuItem: This Function is similar to OnExecMenuItem, but applies to right clicking a track within a custom node.
• OnFillChildren: This Sub executes when you double click a node or click the "+" to expand it to show sub/child nodes.
• OnFillTracks: This Sub is executed whenever the node is selected to fill the track list. This event will clear the current tracklist, and then populate it based on the results (if any) of your function.
• OnNodeDragDrop: This Function requires Five parameters (Destination Node, Source Node, SongList, The Type of Copy/Move operation, and whether or not its a test).
  
  I don't yet fully understand how this function works.
• OnNodeEdited: This Sub is executed when a user completes editing the node text caption (ie presses enter after editing the text).
• OnNodeEditText: This Function allows you to supply the user a different text to edit than actually is shown in the current caption text.
• OnNodeFocused: This Function returns a LONG result when a node gets the focus. This function takes priority over OnFillTracks, if both are registered then OnFillTracks will never be called.
  
  This event does NOT clear the track list, whatever is in the main track window will remain there unless your function updates it.
  
  I don't yet fully understand what this is to be used for.
• OnShowMenuItem: This Function returns which items appear on the node context menu.
  
  Not quite sure how to use this one.
  
  Bug? this event executes once on LEFT click (no context menu) and TWICE on RIGHT click (context menu)
• OnShowTrackMenuItem: This Function returns which items appear on the Track context menu of a custom node.
  
  Not sure how to use this one either.

Event execution order (left clicking on node from different node):
1) OnCanEditNode
2) OnShowMenuItem
3) OnNodeFocused (blocks OnFillTracks)
4) OnFillChildren

Event execution (left clicking while already active node)
1)OnCanEditNode

Event execution order (right clicking on node from different node)
1) OnCanEdit
2) OnShowMenuItem
3) OnFillTracks
4) OnCanEdit
5) OnShowMenuItem
6) OnShowMenuItem

Event execution order (right clicking already active node)
1) OnCanEdit
2) OnShowMenuItem
3) OnShowMenuItem

Event execution order (F5/Refresh node)
1) OnCanEdit
2) OnShowMenuItem
3) OnNodeFocus (or) OnFilltracks


As show, some of these events are either fired multiple times and/or fired when logically they should not be (right click vs left click). I don't know if these are bugs or intended for some reasons.

[MoDementia]

Very nice summary.
I haven't exploited all of the the events so I can't add too much; Bex maybe able to add a little more info from his inconsistencies script.
Can't say I'm suprised by the extra firing though

The exection orders could be very useful for scripters, thanks

[ZvezdanD]

OnCanEditNode

As I said one year ago, I think this event handler is senseless. If I already registered OnNodeEdited and other events for some node, this means that I want to use those events for that node. If I don't want to use those events anymore, I could use UnRegisterEvents, right? If someone really need to disable only those editing events without unregistering all events, then one could use this OnCanEditNode event, but only in that case - default behavior should be enabled events, not disabled.

OnNodeDragDrop: This Function requires Five parameters (Destination Node, Source Node, SongList, The Type of Copy/Move operation, and whether or not its a test).

I don't yet fully understand how this function works.

You could take a look on the Magic Nodes script and its CustomDragDrop function. It enables same thing which you have with MM built-in nodes, i.e. to drag selected tracks from the tracklist and to drop them to some node - in such case your code should update data corresponding to that node in all selected tracks.

By the way, thanks for such detailed descriptions!

[Teknojnky]

OnCanEditNode

As I said one year ago, I think this event handler is senseless. If I already registered OnNodeEdited and other events for some node, this means that I want to use those events for that node. If I don't want to use those events anymore, I could use UnRegisterEvents, right? If someone really need to disable only those editing events without unregistering all events, then one could use this OnCanEditNode event, but only in that case - default behavior should be enabled events, not disabled.

I am not sure its useless, it appears to be used where you want some nodes able to be edited, and other nodes you don't. When the event fires, you check to see if the node you want is editable and return true/false as appropriate.

This event is different from OnNodeEdited, in that OnNodeEdited fires AFTER the user completes the edit instead of before as OnCanEdit.

It appears to be analogous to UI.Edit.Common.Enable = True/False

OnNodeDragDrop: This Function requires Five parameters (Destination Node, Source Node, SongList, The Type of Copy/Move operation, and whether or not its a test).

I don't yet fully understand how this function works.

You could take a look on the Magic Nodes script and its CustomDragDrop function. It enables same thing which you have with MM built-in nodes, i.e. to drag selected tracks from the tracklist and to drop them to some node - in such case your code should update data corresponding to that node in all selected tracks.

Cool, I will have to give it a study.

By the way, thanks for such detailed descriptions!

Welcome, it is nice to have all the descriptions on one page rather than having to click back and forth, easier for my brain.

[ZvezdanD]

If someone really need to disable only those editing events without unregistering all events, then one could use this OnCanEditNode event, but only in that case - default behavior should be enabled events, not disabled.

I am not sure its useless, it appears to be used where you want some nodes able to be edited, and other nodes you don't. When the event fires, you check to see if the node you want is editable and return true/false as appropriate.

This event is different from OnNodeEdited, in that OnNodeEdited fires AFTER the user completes the edit instead of before as OnCanEdit.

Yes, I know all what you are saying since I am using it already. I don't think it is useless, but in my opinion it is senseless that I need to register this event if I want to edit caption of some node. Like I said, its default behavior (if I don't register this event) should be enabled editing, not disabled. Such behavior (enabled editing) has old method of defining event handlers (e.g. Node.OnEdited). Please read a thread where I talked about that, which I referenced in the previous post. There you could find my observations about those event handlers - for example, you could not mix old way of defining event handlers with a new one defined by Script.RegisterEvent. Maybe you should mention that fact in wiki.

[Teknojnky]

I disagree that nodes should be editable by default.

All of the root nodes are read only, and most of them take a couple levels of child nodes before the nodes are editable, if they are at all. Some nodes like Files to Edit are not editable all (aside from maybe any custom user nodes).

Though, I am not sure I understand why there is not an 'editable' property instead of the event.

[ZvezdanD]

I disagree that nodes should be editable by default.

Maybe I am not clear or you didn't read thread which I referenced. I don't mean that ALL nodes should have editable captions, especially not built-in ones. I mean that nodes which are already registered for editing, e.g. with OnNodeEdited don't need to be further enabled with another event handler by default. As I said in the mentioned thread, "If I already registered OnNodeEdited and other events for some node, this means that I want to use those events for that node". I think that only if I want to disable editing for nodes already registered for editing I should use OnCanEditNode and return False.

If you haven't tried old method of defining event handlers for nodes, you should know that with it it was enough to define Node.OnEdited and node is editable by default.

Though, I am not sure I understand why there is not an 'editable' property instead of the event.

I suppose that in the OnCanEditNode event handler you could check the typed text and decide if it should be accepted or not. Just guessing...

[trixmoto]

Thanks for this clear summary.

[*]OnNodeFocused: This Function returns a LONG result when a node gets the focus. This function takes priority over OnFillTracks, if both are registered then OnFillTracks will never be called.

This event does NOT clear the track list, whatever is in the main track window will remain there unless your function updates it.

I don't yet fully understand what this is to be used for.

My "Browse By Art" script used to use this function to generate and display HTML in the web control when clicking on a node - probably not used if you are using the main tracks window.