mirror of https://github.com/texmacs/doc.git
361 lines
11 KiB
Tcl
361 lines
11 KiB
Tcl
<TeXmacs|2.1.2>
|
|
|
|
<style|<tuple|tmdoc|english>>
|
|
|
|
<\body>
|
|
<tmdoc-title|Displaying lists and trees>
|
|
|
|
<paragraph|Displaying lists with <scm|enum>, <scm|choice> and
|
|
<scm|choices>>
|
|
|
|
<\explain>
|
|
<scm|(enum <scm-arg|cmd> <scm-arg|items> <scm-arg|default>
|
|
<scm-arg|width>)><explain-synopsis|a combo box>
|
|
<|explain>
|
|
Builds a combo box which will execute <scm-arg|cmd> whenever the user
|
|
makes a choice. The <scm-arg|width> may be given in any <TeXmacs> length
|
|
unit.
|
|
|
|
<\session|scheme|default>
|
|
<\unfolded-io|Scheme] >
|
|
(tm-widget (test-enum)
|
|
|
|
\ \ (enum (display* "First " answer "\\n")
|
|
|
|
\ \ \ \ \ \ \ \ '("gnu" "gnat" "zebra")
|
|
|
|
\ \ \ \ \ \ \ \ "zebra" "10em")))
|
|
<|unfolded-io>
|
|
\;
|
|
</unfolded-io>
|
|
|
|
<\input|Scheme] >
|
|
(show test-enum)
|
|
</input>
|
|
</session>
|
|
</explain>
|
|
|
|
<\explain>
|
|
<scm|(choice <scm-arg|cmd> <scm-arg|items>
|
|
<scm-arg|default>)><explain-synopsis|a list of items allowing one to be
|
|
chosen>
|
|
<|explain>
|
|
Builds a list of items which will execute <scm-arg|cmd> whenever the user
|
|
makes a choice. <scm-arg|items> is a list, <scm-arg|default> a value.
|
|
Contrary to <scm|enum>, all items are displayed simultaneously. If one
|
|
desires scrollbars, the widget must be enclosed in a <scm|scrollable>
|
|
container. The width of the widget may be set using a <scm|resize>
|
|
widget.
|
|
|
|
<\session|scheme|default>
|
|
<\input|Scheme] >
|
|
(tm-widget (test-choice)
|
|
|
|
\ \ (resize "200px" "50px"
|
|
|
|
\ \ \ \ (scrollable
|
|
|
|
\ \ \ \ \ \ (choice (display* answer "\\n")
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ '("First" "Second" "Third" "Fourth"
|
|
"Fifth" "Sixth")
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ "Third"))))
|
|
</input>
|
|
|
|
<\input|Scheme] >
|
|
(show test-choice)
|
|
</input>
|
|
</session>
|
|
</explain>
|
|
|
|
<\explain>
|
|
<scm|(choices <scm-arg|cmd> <scm-arg|items>
|
|
<scm-arg|defaults>)><explain-synopsis|a list of items allowing several to
|
|
be chosen>
|
|
<|explain>
|
|
Builds a list of items which will execute <scm-arg|cmd> whenever the user
|
|
makes a choice. Several items may be selected at the same time. Both
|
|
<scm-arg|items> and <scm-arg|defaults> are hence lists. Contrary to
|
|
<scm|enum>, all items are displayed simultaneously. If one desires
|
|
scrollbars, the widget must be enclosed in a <scm|scrollable> container.
|
|
The width of the widget may be set using a <scm|resize> widget.
|
|
|
|
<\session|scheme|default>
|
|
<\input|Scheme] >
|
|
(tm-widget (test-choices)
|
|
|
|
\ \ (resize "200px" "100px"
|
|
|
|
\ \ \ \ (scrollable
|
|
|
|
\ \ \ \ \ \ (choices (display* answer "\\n")
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ '("A" "B" "C" "D" "E" "F" "G" "H" "I"
|
|
"J" "K" "L")
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ '("B" "D" "F" "H" "J" "L")))))
|
|
</input>
|
|
|
|
<\input|Scheme] >
|
|
(show test-choices)
|
|
</input>
|
|
</session>
|
|
</explain>
|
|
|
|
<paragraph|Displaying trees with <scm|tree-widget>>
|
|
|
|
<\explain>
|
|
<scm|(tree-widget cmd <scm-arg|data> <scm-arg|data-roles>)><explain-synopsis|a
|
|
tree view>
|
|
<|explain>
|
|
The <scm|tree-widget> provides a graphical representation of a <TeXmacs>
|
|
tree <scm-arg|data> (not a <scheme> tree!). This may be part of a
|
|
document or any other tree. The first node in <scm-arg|data> won't be
|
|
displayed. All other nodes may have attributes called <em|data roles>
|
|
which will determine the textual representation of the node, whether it
|
|
has some icon next to it and which one, etc. These attributes are simply
|
|
children of the nodes in <scm-arg|data> at predefined positions given by
|
|
the data roles specification in the argument <scm-arg|data-roles>. This
|
|
is a list of identifiers for each tree label present in the data. For
|
|
instance, with the following data roles specification:
|
|
|
|
<\scm-code>
|
|
(list
|
|
|
|
\ \ (library \ \ \ DisplayRole DecorationRole UserRole:1)
|
|
|
|
\ \ (collection DisplayRole UserRole:1))
|
|
</scm-code>
|
|
|
|
we use the data:
|
|
|
|
<\scm-code>
|
|
(root
|
|
|
|
\ \ (library "Library" "icon.png" 12345
|
|
|
|
\ \ \ \ (collection "Cool stuff" 001)
|
|
|
|
\ \ \ \ (collection "Things to read" 002)
|
|
|
|
\ \ \ \ (collection "Current work" 003
|
|
|
|
\ \ \ \ \ \ (collection "Forever current" 004)
|
|
|
|
\ \ \ \ \ \ (collection "Read me" 005))))
|
|
</scm-code>
|
|
|
|
Notice that the node <scm|root> won't be displayed by the
|
|
<scm|tree-widget> and needs no data roles. Here <scm|UserRole:1> is used
|
|
to store database ids but it can be anything else. The supported data
|
|
roles are:
|
|
|
|
<\verbatim-code>
|
|
<\code>
|
|
DisplayRole \ \ \ \ \ \ \ ; a string to be displayed
|
|
|
|
EditRole \ \ \ \ \ \ \ \ \ \ ; a string valid for an editable
|
|
representation
|
|
|
|
ToolTipRole \ \ \ \ \ \ \ ; a small tooltip to display when the mouse
|
|
hovers over
|
|
|
|
StatusTipRole \ \ \ \ \ ; for the status bar (if present and
|
|
supported)
|
|
|
|
DecorationRole \ \ \ \ ; file name of an icon to use
|
|
|
|
CommandRole \ \ \ \ \ \ \ ; sent to the command executed after
|
|
(double?) clicks
|
|
|
|
UserRole:\<less\>number\<gtr\> \ ; left to user definition (will be
|
|
returned as strings)
|
|
</code>
|
|
</verbatim-code>
|
|
|
|
<paragraph|Default data roles>It is possible to omit some or all of the
|
|
data role specification. By default the widget will use the tree label's
|
|
string representation for <scm|DisplayRole>, <scm|EditRole>,
|
|
<scm|ToolTipRole> and <scm|StatusTipRole>. For the <scm|DecorationRole>
|
|
it will try to load pixmaps named <shell|treelabel-\<less\>label\<gtr\>.xpm>
|
|
in <shell|$TEXMACS_PIXMAP_PATH>. This search
|
|
<with|font-series|bold|won't> happen if the <scm|DecorationRole> is
|
|
specified (i.e. a full path with or without environment variables and
|
|
wildcards must be given). The default <scm|CommandRole> is the subtree
|
|
itself (see below).
|
|
|
|
<paragraph|Using commands>The first argument of <scm|tree-widget>,
|
|
<scm-arg|cmd>, \ is a <scheme> lambda that will be called when items are
|
|
clicked. The procedure must have the following signature:
|
|
|
|
<\scm-code>
|
|
(lambda (Event CommandRole . UserRoles) (...))
|
|
</scm-code>
|
|
|
|
where:
|
|
|
|
<\itemize-dot>
|
|
<item><scm|Event> is an integer: either 1, 2 or 4 for a single, right
|
|
or middle click respectively. In the future, other events could be
|
|
supported (like double clicks, drag&drop, unfold, etc.)
|
|
|
|
<item><scm|CommandRole> is either the value of that role if given for
|
|
the data item, or the subtree itself otherwise.
|
|
|
|
<item><scm|UserRoles> is a (possibly empty) list with the data for
|
|
those roles given in the data role specification.
|
|
</itemize-dot>
|
|
|
|
If multiple selections are enabled and one is made, <scm|CommandRole> and
|
|
<scm|UserRole> will both be lists (not implemented yet). Keep in mind
|
|
that the data is a <TeXmacs> tree and thus not a copy but always a
|
|
pointer to the actual data (unless you copy or transform it into another
|
|
format with e.g. <scm|tree-\<gtr\>stree>)
|
|
|
|
<paragraph|Examples>See <scm|widget10> in
|
|
<hlink|<verbatim|menu-test.scm>|$TEXMACS_PATH/progs/kernel/gui/menu-test.scm>
|
|
and ``<hlink|Displaying lists and trees|$TEXMACS_PATH/doc/devel/scheme/gui/scheme-gui-lists-trees.en.tm>''.
|
|
</explain>
|
|
|
|
<paragraph|An example using data roles>
|
|
|
|
We build on the previous example, but now we add a command. Notice how the
|
|
way one adds commands to <scm|tree-view> departs from that of other
|
|
widgets, where instead of a procedure one must provide a list with code
|
|
expecting one or two arguments with fixed names (usually <scm|answer> and
|
|
<scm|filter>). <with|font-shape|italic|Note to self>: this is easily
|
|
changed in <scm|$tree-view>, but it seems easier to manage empty arguments
|
|
this way.
|
|
|
|
<\session|scheme|default>
|
|
<\input|Scheme] >
|
|
(define t
|
|
|
|
\ \ (stree-\<gtr\>tree
|
|
|
|
\ \ \ '(root
|
|
|
|
\ \ \ \ \ (library "Library" "$TEXMACS_PIXMAP_PATH/tm_german.xpm" 01
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ (collection "Cool stuff" 001)
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ (collection "Things to read" 002)
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ (collection "Current work" 003
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (collection
|
|
"Forever current" 004)
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ (collection "Read
|
|
me" 005))))))
|
|
</input>
|
|
|
|
<\input|Scheme] >
|
|
(define dd
|
|
|
|
\ \ (stree-\<gtr\>tree
|
|
|
|
\ \ \ '(list (library DisplayRole DecorationRole UserRole:1)
|
|
|
|
\ \ \ \ \ \ \ \ \ \ (collection DisplayRole UserRole:1))))
|
|
</input>
|
|
|
|
<\input|Scheme] >
|
|
(define (action clicked cmd-role . user-roles)
|
|
|
|
\ \ (display* "clicked= " clicked ", cmd-role= " cmd-role
|
|
|
|
\ \ \ \ \ \ \ \ \ \ \ \ ", user-roles= " user-roles "\\n")))
|
|
</input>
|
|
|
|
<\input|Scheme] >
|
|
(tm-widget (widget-library)
|
|
|
|
\ \ (resize ("150px" "400px" "9000px") ("300px" "600px" "9000px")
|
|
|
|
\ \ \ \ (vertical
|
|
|
|
\ \ \ \ \ \ (bold (text "Testing tree-view"))
|
|
|
|
\ \ \ \ \ \ ===
|
|
|
|
\ \ \ \ \ \ (tree-view action t dd))))
|
|
</input>
|
|
|
|
<\input|Scheme] >
|
|
(top-window widget-library "Tree View")
|
|
</input>
|
|
</session>
|
|
|
|
Notice how we must add <shell|$TEXMACS_PIXMAP_PATH> to the name of the
|
|
pixmap because we are not using the default <scm|DecorationRole>.\
|
|
|
|
<subparagraph|An example using the buffer tree>
|
|
|
|
We can even use the <scm|buffer-tree> as argument to <scm|tree-widget>.
|
|
Changes in the buffer will show up immediately in the widget. In this
|
|
example we use the default data role specification.
|
|
|
|
<\warning>
|
|
As of this writing (31 Dec. 2013) the <name|Qt> implementation is sloppy
|
|
and forces a full reloading of the data model for each <cpp|modification>
|
|
of the <cpp|tree>. The slowdown is already noticeable with documents of a
|
|
few pages like this one. Additionally, the current selection in the
|
|
widget is lost after each modification to the buffer (fixing this
|
|
requires writing a fully fledged <cpp|observer> and probably an
|
|
intermediate copy of the data).
|
|
</warning>
|
|
|
|
<\session|scheme|default>
|
|
<\input|Scheme] >
|
|
(tm-widget (widget-buffer)
|
|
|
|
\ \ (resize ("150px" "400px" "9000px") ("300px" "600px" "9000px")
|
|
|
|
\ \ \ \ (vertical
|
|
|
|
\ \ \ \ \ \ (bold (text "Testing tree-view"))
|
|
|
|
\ \ \ \ \ \ ===
|
|
|
|
\ \ \ \ \ \ (tree-view noop (buffer-tree) (stree-\<gtr\>tree
|
|
'(dummy))))))
|
|
</input>
|
|
|
|
<\input|Scheme] >
|
|
(top-window widget-buffer "Tree View")
|
|
</input>
|
|
</session>
|
|
|
|
<subparagraph|An example with the side tools>
|
|
|
|
If your <TeXmacs> has the side tools enabled, you can try this:
|
|
|
|
<\session|scheme|default>
|
|
<\input|Scheme] >
|
|
(tm-widget (texmacs-side-tools)
|
|
|
|
\ \ (vertical
|
|
|
|
\ \ \ \ (hlist (glue #t #f 15 0) (text "Document tree:") (glue #t #f 15
|
|
0))
|
|
|
|
\ \ \ \ ---
|
|
|
|
\ \ \ \ (tree-view noop (buffer-tree) (stree-\<gtr\>tree '(unused)))))
|
|
</input>
|
|
</session>
|
|
|
|
<tmdoc-copyright|2013|the <TeXmacs> team.>
|
|
|
|
<tmdoc-license|Permission is granted to copy, distribute and/or modify
|
|
this\ndocument under the terms of the GNU Free Documentation License,
|
|
Version 1.1 or\nany later version published by the Free Software
|
|
Foundation; with no Invariant\nSections, with no Front-Cover Texts, and
|
|
with no Back-Cover Texts. A copy of\nthe license is included in the section
|
|
entitled "GNU Free Documentation License".>
|
|
</body>
|
|
|
|
<initial|<\collection>
|
|
</collection>> |