Treeviewlib/treeviewlib.html at master · bohagan1/Treeviewlib · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
<!DOCTYPE html>
<html>
<head>
<style>
  .indented-block {
    /* Indents the entire block by 40 pixels */
    margin-left: 40px;
    /* Alternatively, use padding-left */
    /* padding-left: 40px; */
  }
</style>
</head>
<body>
<h1>Treeviewlib</h1>

<h2>Name</h2>
<b>Treeviewlib</b> - Library of common utility functions for the <b>ttk::treeview</b> widget.

<h2>Synopsis</h2>

<p><b>package require Tcl</b> ?<b>8.5-</b>?</p>
<p><b>package require treeviewlib</b> ?<b>1.03</b>?</p>
<p><b>::treeviewlib::create</b> <i>pathname id</i> ?<i>titles</i>? ?<i>ids</i>? ?<i>is_tree</i>?</p>

<h2>Dependencies</h2>

<ul>
<li><p><b>autoscroll</b> package from <a href="https://core.tcl-lang.org/tklib/doc/trunk/embedded/index.md">TkLib</a></p></li>
</ul>

<h2>Description</h2>

<p>This library provides the <b>::treeviewlib::create</b> command to create and
wrap the ttk::treeview widget with support for several common utility functions.
These functions include:
resize rows when the font size changes, move columns, auto size columns,
hide/unhide columns, sort tree items, copy selected items to clipboard, bulk
item inserts, bulk expand/collapse of items, get size, selection change,
add row stripes to tree, etc.</p>
<p>It is intended to easily view and manage database records. To aid in this,
it utilizes identifiers (or ids) for the table, columns, and items which can
map to the database table id, column id, and row or unique id of the record.


<h2>Commands</h2>

<p>The following are the public commands provided by this package:</p>

<dl>
<dt><b>::treeviewlib::create</b> <i>pathname id</i> ?<i>titles</i>? ?<i>ids</i>? ?<i>is_tree</i>?</dt>
<p>This command creates a new ttk::frame <i>pathname</i> widget containing the
ttk::treeview, vertical ttk::scrollbar, and horizontal ttk::scrollbar widgets
using an id <i>id</i> and returns the treeview widget pathname. The <i>id</i> can be
used as a shorthand method for identifying which treeview widget to use for the
following functions. The optional <i>titles</i> argument is a list of column
width (in characters), title, alignment (left, right, center), and sortmode
(ascii, dictionary, integer, real) pairs describing each column in display order.
The <i>ids</i> argument is a list of the ids for each of those columns.
The <i>is_tree</i> boolean argument specifies whether to use the tree column
for the first column (true) or not (false).</p>

<dt><b>::treeviewlib::reconfigure</b> <i>pathname</i> ?<i>titles</i>? ?<i>ids</i>? ?<i>is_tree</i></dt>
<dd><p>This command is used to update the titles or ids for an existing treeview
widget created with the <b>::treeviewlib::create</b> command.</p></dd>
<br>
<dt><b>::treeviewlib::handler</b> <i>id fn args</i></dt>
<dd><p>Same as <b>::treeviewlib::perform_fn</b>, but uses the id passed to
<b>::treeviewlib::create</b> instead of the widget pathname.</p></dd>

<dt><b>::treeviewlib::perform_fn</b> <i>pathname fn args</i></dt>
<dd><p>This command is used to perform functions on the treeview widget
<i>pathname</i>. The supported functions are:</p></dd>

<div class="indented-block">
<h3>Item Related Functions:</h3>
<dl>
  <dt><b>append</b> <i>list</i></dt>
  <dd>Append items to end of treeview widget. The argument <i>list</i> is a
  list of key-value pairs consisting of the item id and list of data values to
  insert into the treeview widget. The id is assigned to the treeview <b>-id</b>
  argument and the values are assign to the <b>-text</b> and/or <b>-values</b>
  arguments. The id can be used to identify the item for subsequent functions.</dd>

  <dt><b>clear</b></dt>
  <dd>Delete all items in the treeview widget.</dd>

  <dt><b>delete</b> <i>ids</i></dt>
  <dd>Delete all items in <i>ids</i> list.</dd>

  <dt><b>get</b> <i>ids</i></dt>
  <dd>Get data values for all items in <i>ids</i> list and return as a list of
  data values lists. If only one id is provided, then the result is just its
  list of data values.</dd>

  <dt><b>insert</b> <i>index list</i></dt>
  <dd>Insert items into the treeview widget at index <i>index</i>. The argument <i>list</i>
  is a list of key-value pairs consisting of the item id and list of data values to
  insert into the treeview widget. The id is assigned to the treeview <b>-id</b>
  argument and the values are assign to the <b>-text</b> and/or <b>-values</b>
  arguments. The id can be used to identify the item for subsequent functions.</dd>

  <dt><b>set</b> <i>list</i></dt>
  <dd>Set or update existing items to new data values. The argument <i>list</i>
  is a list of key-value pairs consisting of the item id and list of data values to
  insert into the treeview widget.</dd>

  <dt><b>size</b></dt>
  <dd>Return the number of visible items in treeview widget.</dd>

  <dt><b>update</b> <i>list</i></dt>
  <dd>Same as <b>set</b>.</dd>
</dl>

<h3>Column Related Functions:</h3>
<dl>
  <dt><b>autosizecolumns</b></dt>
  <dd>Auto size all treeview widget columns to their max entry sizes.</dd>

  <dt><b>hide</b> <i>ids</i></dt>
  <dd>Hide all columns in <i>ids</i> list.</dd>

  <dt><b>movecolumn</b> <i>sourceColumn targetColumn</i></dt>
  <dd>Move column <i>sourceColumn</i> before column <i>targetColumn</i>.</dd>

  <dt><b>show</b> <i>ids</i></dt>
  <dd>Same as <b>unhide</b>.</dd>

  <dt><b>unhide</b> <i>ids</i></dt>
  <dd>Show or unhide all columns in <i>ids</i> list. Columns are restored to their original order.</dd>
</dl>

<h3>Copy and Paste Related Functions:</h3>
<dl>
  <dt><b>attach</b> <i>ids</i></dt>
  <dd>Reattach all items in <i>ids</i> at current focus item, or if none the first selected item, or if none at the end. Used as part of a cut and paste operation.</dd>

  <dt><b>copy</b> <i>ids</i></dt>
  <dd>Copy all items in <i>ids</i> list to clipboard.</dd>

  <dt><b>cut</b> <i>ids</i></dt>
  <dd>Same as <b>detach</b>.</dd>

  <dt><b>detach</b> <i>ids</i></dt>
  <dd>Detach all items in <i>ids</i>. Used as part of a cut and paste operation.</dd>

  <dt><b>paste</b> <i>ids</i></dt>
  <dd>Same as <b>attach</b>.</dd>
</dl>

<h3>Move Related Functions:</h3>
<dl>
  <dt><b>raise</b> <i>ids</i></dt>
  <dd>Raise each item in list <i>ids</i> up 1 row in the treeview widget.</dd>

  <dt><b>lower</b></dt>
  <dd>Lower each item in list <i>ids</i> down 1 row in the treeview widget.</dd>

  <dt><b>move</b> <i>index ids</i></dt>
  <dd>Move all items in list <i>ids</i> to index <i>index</i> in the treeview widget.</dd>
</dl>

<h3>View Related Functions:</h3>
<dl>
  <dt><b>collapse</b> <i>ids</i></dt>
  <dd>Collapse all items in <i>ids</i> list.</dd>

  <dt><b>collapse_all</b></dt>
  <dd>Collapse all items in treeview widget.</dd>

  <dt><b>expand</b> <i>ids</i></dt>
  <dd>Expand all items in <i>ids</i> list.</dd>

  <dt><b>expand_all</b></dt>
  <dd>Expand all items in treeview widget.</dd>
</dl>

<h3>Sort Related Functions:</h3>
<dl>
  <dt><b>sort</b></dt>
  <dd>Sort treeview widget items using current sort column and order.</dd>

  <dt><b>sortbycolumn</b> ?<i>column</i>? ?<i>order</i>? ?<i>mode</i>?</dt>
  <dd>Sort treeview widget items using the specified sort column <i>column</i>, order
    <i>order</i>, and mode <i>mode</i>. If not specified, column defaults to
    <b>#0</b>, order defaults to <b>increasing</b>, and mode defaults to <b>ascii</b>.
    See <b>lsort</b> command for valid order and mode values.</dd>

  <dt><b>sortcolumn</b></dt>
  <dd>Return the current sort column.</dd>

  <dt><b>sortinfo</b></dt>
  <dd>Return a list with the current sort column, order, and mode.</dd>

  <dt><b>sortorder</b></dt>
  <dd>Return the current sort order.</dd>
</dl>
</div>
<br>
<dt><b>::treeviewlib::select_handler</b> <i>id fn args</i></dt>
<dd><p>Same as <b>::treeviewlib::select</b>, but uses the id passed to
<b>::treeviewlib::create</b> instead of the widget pathname.</p></dd>

<dt><b>::treeviewlib::select</b> <i>pathname fn args</i></dt>
<dd><p>This command is used to perform selection related functions on the
treeview widget <i>pathname</i>. The supported functions are:</p></dd>

<div class="indented-block">
<dl>
  <dt><b>all</b></dt>
  <dd>Select all items in the treeview widget.</dd>

  <dt><b>clear</b></dt>
  <dd>Unselect all items in the treeview widget.</dd>

  <dt><b>invert</b></dt>
  <dd>Invert the selection state of all items in the treeview widget.</dd>

  <dt><b>see</b> ?<i>id</i>?</dt>
  <dd>See item <i>id</i> in the treeview widget, or if not specified the first item in the selection.</dd>

  <dt><b>select</b> ?<i>ids</i>?</dt>
  <dd>Select all of the items in <i>ids</i> list, or if not specified the focus item.</dd>

  <dt><b>size</b></dt>
  <dd>Return the number of selected items in the treeview widget.</dd>

  <dt><b>toggle</b> ?<i>ids</i>?</dt>
  <dd>Toggle the selection state of all of the items in <i>ids</i> list, or if not specified the focus item.</dd>

  <dt><b>unselect</b> ?<i>ids</i>?</dt>
  <dd>Unselect all of the items in <i>ids</i> list, or if not specified the focus item.</dd>
</dl>
</div>
</dl>
<br>
</body>
</html>