proc

<proc>

This kind of xml node allows to define a Tcl scripting procedure that could be called in other field nodes, like values.

The parameters are as follows,
n - Name of the proc used in other xml nodes.
args - optional, it will be set as a list with all arguments provided in the uses of other xml nodes.

If the proc is defined in the xml then it has some tricky implicit arguments:

The local variable named domNode is 'magically' filled with the xml dom node of the caller, and there could be other optional variables that can be set with special options in the arguments

{ -tree tree "" }
{ -boundary_conds boundary_conds "" }
{ -item item "" }
{ -dict dict "" }
{ -dict_units dict_units "" }

the list with the rest of provided arguments will be in the variable args.

It is possible to collect all <proc> nodes inside a <procs> xml node, but nowadays it is recommended to do it in a Tcl file (it is easier to edit, debug,...), and pass the desired optional arguments with %W, %TREE, %ITEM, %BC, %DICT, %DICT_UNITS

The arguments are described as follows:

%W: It is the current domNode id in the XML TDOM data structure that store the tree data (it is serialized in the .spd file). It should be noted that %W is not the path name of a window.

%TREE: It is the path name to a tree widget of class "TreeCtrl" in the GUI (e.g: .gid.central.boundaryconds.gg.ft.t)

%ITEM: Is is an integer id of the tree widget item

%BC: It is the path name to a widget of class "Boundary_conds" parent of the tree widget in the GUI (e.g. .gid.central.boundaryconds.gg)

%DICT: It gives a dictionary ‘key-value’, with data of the current selected node (<value n=”material”…/>). It is created internally by CustomLib, and in principle the user do not have to do anything with this parameter.

%DICT_UNITS: similar to DICT but for the units, if any.

Example:

<procs>
    <proc n='GetMaterialsList' args='args'>
      Cmas2d::GetMaterialsList $domNode
    </proc>

    <proc n='EditDatabaseList' args='args'>
      Cmas2d::EditDatabaseList $domNode $dict $boundary_conds $args
    </proc>
</procs> 

And in a .tcl file can define the true procs (it is possible write the code in the spd <proc> but it is better for debug to separate in a Tcl file).

proc Cmas2d::GetMaterialsList { domNode args } {    
    set dom_materials [$domNode selectNodes {//container[@n="materials"]}]    
    set result [list]
    foreach dom_material [$dom_materials childNodes] {
        lappend result $[$dom_material @name
    }
    return [join $result ,]
}

proc Cmas2d::EditDatabaseList { domNode dict boundary_conds args } {
    ...
}

Example: 

It is also possible to use the arguments %W, %DICT and %BC in order to define the procedures directly in the Tcl file, instead of in the original <procs/> node of the .spd file. For instance, there are the procedures “Cmas2d::GetMaterialsList %W" and "Cmas2d::EditDatabaseListDirect %W %DICT %BC" defined in the .spd file in the problem type cmas2d_customLib.gid.

<value n="material" pn="Material" editable="0" help="Choose a material from the database" values="[Cmas2d::GetMaterialsList %W]" v="Air">
<edit_command n="Edit materials" pn="Edit materials" icon="darkorange-block1.png" proc="Cmas2d::EditDatabaseListDirect %W %DICT %BC"/>
</value>
</condition>

Return value: to update the widgets of the window that called the proc with an edit_command it is possible to return a list with two dictionaries: the first dictionary with the keys and values to be set, and the second dictionary to set units.

Example:

spd file (XML)

  <container n="Points_of_loads" pn="Points of loads">
    <value n="point1" pn="N. point 1" v="" string_is="integer_or_void" help="Number of the point in the geometry to attribute the value 1 of the load">
      <edit_command n="select_points" pn="Select Points" proc="MyProcSelectPoint %W" icon="point"/>
    </value>
  </container>

Tcl file

proc MyProcSelectPoint { dom_node } {
    set my_dict ""
    set id [GidUtils::PickEntities Points single [= "Pick a geometry point"]]
    if { $id != "" } {
        set question [$dom_node @n]
        #Note: in this case we knot that question is 'point1' but this show an use of the dom_node argument 
        set my_dict [dict set my_dict point1 $id]
    }
    return [list $my_dict ""]
}