1Summary of commands 2=================== 3 4In term browser window: 5Single-click left mouse-button: select node clicked as current node. 6Double-click left mouse-button: toggle expansion or collapse of clicked node. 7Press and hold right 8mouse-button: options menu for the node. 9Arrow keys: move selected node relative to current node. 10 11Navigation panel arrows: move selected node relative to current node. 12 13 14Summary of function 15=================== 16 17This tool is used to examine terms in a browser-like fashion. A selected 18term is displayed hierarchically in a tree format. The user can browse 19and traverse the term in a similar fashion to a directory browser. 20 21The terms are displayed using the global output mode option, and it is this 22representation of the term that is inspected. As changing the output mode 23may change the way the term is represented, this is not allowed during the 24inspection. To view the terms under different output modes, quit from the 25inspector, change the global output modes, and inspect the term 26again. Print depth can be set from within the inspector, but if the global 27output mode is set to `full', then the terms would always be printed with 28full depth, and the inspector print depth setting is ignored. 29 30Note that when the inspector is active, the user cannot interact with other 31ECLiPSe windows. 32 33 34Layout 35====== 36 37The inspector consists of the following components: 38 39Navigation and settings panel: this panel across the top contains 40arrow buttons for movements, parameter input entries, and a close-button. 41 42Main term browser window: displays the selected term in the hierarchical 43tree format. 44 45Status line: shows messages from the inspector. 46 47Browser y-scroll control panel: this window needs to be launched from the 48inspector from the Windows menu. It allows the changing of parameters for 49controlling the behaviour of the y scrollbar in the term browser window. 50 51 52Functionality 53============= 54 55Main term browser window 56------------------------ 57 58The selected term can be browsed and examined in this window. The term is 59displayed in a tree-like fashion, with nodes of the tree representing 60sub-terms of the selected term. As with directories in a directory browser, 61nodes which contains its own sub-terms can be toggled between two states: 62expanded, in which its child sub-terms are shown; or collapsed, when its 63children are not shown. The user can toggle between these two states by 64double clicking the left mouse button over the node. Nodes which can be 65expanded are shown in a red bold font. 66 67A node can be selected by single clicking the mouse button on it. 68 69For convenience, the list elements of a list are displayed at the same 70level, rather than as the actual recursive tree structure of the head and 71the tail. The elements are displayed in the order they are in the list from 72the top. The number of elements displayed at one level is controlled by the 73structure threshold. The last child node of a list is the tail of the 74list, and if the list is longer than the threshold, then the rest of the 75list beyond the threshold is displayed as the tail, which can then be 76further expanded at the next level. The threshold can be changed from the 77Options menu. List elements are prefixed by labels: `[ :' for the first 78element, `, :' for the other elements, and `| :' for the tail. So a 79list [1,2,3,4] with a threshold of 2 will be displayed as: 80 81./2 82 | 83 |-- [ 1 84 | 85 |-- , 2 86 | 87 -- | [3,4] 88 89The threshold setting is applied when the list node is expanded. 90 91Press and hold the right mouse button over a term will bring up a menu 92related to the term: summary information on it is given (Name/Arity, type, 93and information on what sort of argument it is: position/field name in a 94structure, list element `position', attribute name); and the option to 95observe the term. This option is designed to be used in conjunction with 96the tracer for debugging: it will allow the term to be observed for any 97changes in a display matrix. 98 99The option to observe terms will only work when the inspector was launched 100when the user is at a tracer debug port and if forward execution continues. 101A display matrix with the terms selected for observation will be created 102immediately before ECLiPSe execution continues after the debug 103port (note: although terms can be selected for observation while the tracer is 104not active, they will not be displayed because there is no continuation of 105execution from a debug port). 106 107When a term is selected for observation, the user is prompted to give a 108label to the term by a dialogue box. This label will be placed next to the 109observed term in the display matrix to allow the user to identify it. If 110the `Cancel' button of the dialogue box is clicked, then the term will not 111be added for observation. Multiple terms can be selected, and each term 112will be given a row in the display matrix -- the matrix will be a column of 113label-term pairs of the observed terms. 114 115The observe terms facilities can be seen as a way for the user to create 116display matrices interactively. It is equivalent to the user adding the call 117to display_matrix/2 with the selected terms just after the goal at the 118debug port. See the documentation on display matrix for more information on 119how to use it. 120 121 122The sub-terms can be displayed in the browser window with icons that gives 123type information if the `Display term type symbols' option is ticked. 124 125In the browser window, attributes are prefixed with their attribute names. 126For structures with field names (declared using local struct or 127global struct), the arguments are prefixed with their field names. If a 128normal structure has more arguments than the structure threshold, then its 129elements will be prefixed with their argument number. 130 131The viewable area of the term browser window can be adjusted by using the 132scrollbars. The y scrollbars implements a `follow-node' mode. In this mode, 133when the y scrollbars is used to scroll the screen, the viewable x area is 134adjusted so that nodes are always visible. This means that unlike 135conventional scrollbars, when scrolling through the term means alternating 136between the x and y scrollbars, only the y scrollbar has to be 137manipulated. In this follow-node mode, a node, which is in the visible 138area, is defined as the `leading' node. It is this leading node that will 139always be visible -- if the normal y scrolling would place the leading node 140outside pre-defined left and right boundaries in the x direction, the 141viewable x area will be adjusted so that the node will be displayed in the 142centre of the viewable x area. Which node is regarded as the leading node 143depends on the direction of scrolling: if scrolling upwards, the node is 144located relative to the top edge of the visible area; if scrolling 145downwards, it is relative to the bottom edge. The actual node selected is 146at the node that is closest to some pre-defined distance from the 147appropriate edge. 148 149 150Navigation buttons 151------------------ 152 153Navigation through the term is also possible using the navigation buttons. 154They allow the user to move the selected node in relation to the current node: 155to one of its sibling, parent or child node. The number of times a 156particular move is to be repeated can be set by setting the `repeat' entry 157in the middle of the panel. For moving to a child node, the particular 158child argument to move to at each stage is set in the `child' entry to the 159right of the descendant arrow. This is particularly useful in moving down 160many levels of deeply nested structures. The default child position is 2. 161 162The keyboard arrow keys can be used in place of the arrow buttons. 163 164 165Settings 166-------- 167 168Next to the navigation buttons there are the following entries: 169 170Argument position for child move 171 this determines to which child the current selection moves 172 when the right-arrow is pressed. 173 174Repeat count for all movements 175 this determines how many steps are executed in the given direction, 176 when an arrow is pressed. If the move has to be terminated early, 177 a message is displayed in the status line. 178 179Print depth setting 180 the nesting depth at which the textual representation of a subterm in 181 a tree node is truncated. This has no effect on the tree structure. 182 183Structure threshold/List unfolding chunk size 184 Lists are unfolded and displayed in chunks of the given length. This 185 is usually more readable than the true structure of the list, which is 186 a deeply nested term of ./2 structures. 187 188 Also, in structures with an arity higher than this setting, all the 189 arguments will be displayed together with argument position numbers, 190 for better orientation. 191 192Display term type symbols option 193 When ticked, every subterm is marked with a symbold indicating its type. 194 Depending on the data, this may improve or diminish readability. 195 196 197Browser y-scroll control panel 198------------------------------ 199 200This window allows the parameters for controlling y-scroll in the term 201browser window to be modified. It consists of 3 subsections: 202 203Check button for `follow-node' mode: 204 205If selected, the y scrollbar has the `follow-node' behaviour. If not 206selected, then the y scrollbar has the conventional behaviour, 207i.e. manipulating it does not have an effect on the viewable x area. Note 208that the x scrollbars have the conventional behaviour in both modes, 209i.e. the viewable x area can be adjusted independently of the viewable y 210area through the x scrollbar. 211 212Sliders for adjusting the left and right boundaries: 213 214The left and right boundaries defines the limits within which the leading 215node must be displayed during y-scroll. The limits are measured against the 216left-edge of the text of the node: if this edge is outside either the left 217or right edge as a result of manipulating the y scrollbar, then the 218viewable y area will be adjusted so that the left-edge of the node is 219displayed in the centre of the viewable x area. Note that this adjustment 220would not place the viewable area beyond the edges of the whole term 221display canvas. 222 223The left and right boundaries (LB and RB respectively) are shown below, 224 225 W 226 <-----------------------------------------------------> 227 228 Left edge viewable x area Right edge 229 |-----------------------------------------------------| 230 <----->| |<----------> 231 A LB RB B 232 233 234with A and B defining how far LB and RB are from the left and right edges 235respectively. The sliders allows A and B to be adjusted, expressed as % of 236the width of the viewable X area (W). Both range from 0% (at the edge) to 23750% (at the centre). 238 239Sliders for adjusting distances to leading node: 240 241The leading node is selected from the nodes which are in the viewable y 242area (they may not be visible because they are not in the viewable x 243area). The node selected is the node that is closest to one of two 244boundaries in the viewable y area. The boundary used depends on the 245direction of y scrolling -- the upper boundary when scrolling upwards, the 246lower boundary when scrolling downwards. These two boundaries are defined 247in terms of their distance from the upper and lower edges of the viewable y 248area respectively, expressed as a % of the height of the viewable y 249area. The sliders allows these two boundaries to be adjusted between 0% (at 250their respective edges) and 50% (at the centre of the viewable y area). 251 252Update button: 253 254Adjusting the sliders and the check button would not cause any immediate 255changes in the y-scroll parameters. The changes are applied only when the 256update button is pressed. 257 258Close button: 259 260Closes the window when pressed. 261 262Menu Bar 263-------- 264 265 Windows - this launches sub-windows of the inspector: 266 267 Browser y-scroll control 268 this launches the browser y-scroll control panel 269 Show symbol key 270 this launches a window that shows what the type icons represents. 271 Close 272 quit the inspector tool. 273 274 Select - this allows the selection of the term that is to be inspected: 275 276 Current goal 277 selects the current goal - the goal that is being 278 executed or traced. 279 Invoked goal 280 selects an invoked goal by its invocation number. 281 282 Help 283 Balloon Help 284 toggles balloon help. 285 Inspector Help 286 this window. 287 288 289 290 291