texmacs
/
doc
mirror of https://github.com/texmacs/doc.git
1
0
Fork 0
Code

More documentation for widgets. There is much to do yet.

This commit is contained in:
Miguel de Benito 2012-08-10 21:29:34 +00:00
parent 7a387e15a7
commit 184dc83b25
7 changed files with 405 additions and 332 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
devel/scheme/gui/scheme-gui-advanced.en.tm
View File

@ -1,19 +1,20 @@
<TeXmacs|1.0.7.15>
<TeXmacs|1.0.7.16>
<style|tmdoc>
<\body>
<tmdoc-title|Containers, glue, refresh and cia.>
<section|Attribute widgets>
<subsection|Attribute widgets>
Setting attributes of widgets is achieved by enclosing them in the
following special widgets.
In what follows <scm-arg|widget> can be anything defined using
<scm|tm-widget>.
<\explain>
<scm|(centered wid)><explain-synopsis|centers the widget <scm|wid>>
<scm|(centered <scm-arg|widget>)><explain-synopsis|centers
<scm-arg|widget>>
<|explain>
This does just that: it centers the widget <scm|wid> with respect to the
This does just that: it centers <scm-arg|widget> with respect to the
enclosing widget. Although we are calling this an attribute, the effect
is achieved by using a vertical list and a horizontal one together with
four <scm|glue> widgets. This means that in the following example, the
@ -59,15 +60,18 @@
</explain>
<\explain>
<scm|(resize (w1 w2 w3) (h1 h2 h3) wid)>
<scm|(resize (<scm-arg|w1> <scm-arg|w2> <scm-arg|w3>) (<scm-arg|h1>
<scm-arg|h2> <scm-arg|h3>) <scm-arg|wid>)>
<scm|(resize w h wid)><explain-synopsis|resizes the widget <scm|wid>>
<scm|(resize <scm-arg|w> <scm-arg|h> <scm-arg|widget>)><explain-synopsis|resizes
<scm-arg|widget>>
<|explain>
These two variants resize the argument. The first one specifies a minimum
size of <scm|w1 x h1>, a default size of <scm|w2 x h2> and a maximum size
of <scm|w3 x h3>. The widget <scm|wid> will be set to the default size
and will be allowed to resize but not beyond the bounds specified. The
second alternative sets a fixed width and height.
size of <scm-arg|w1><math|\<times\>><scm-arg|h1>, a default size of
<scm-arg|w2><math|\<times\>><scm-arg|h2> and a maximum size of
<scm-arg|w3><math|\<times\>><scm-arg|h3>. <scm-arg|widget> will be set to
the default size and will be allowed to resize but not beyond the bounds
specified. The second alternative sets a fixed width and height.
Sizes are specified as strings with a unit suffix, like in <scm|"150px">.
@ -87,17 +91,17 @@
</explain>
<\explain>
<scm|(padded wid)><explain-synopsis|surrounds the widget <scm|wid> by
padding>
<scm|(padded <scm-arg|widget>)><explain-synopsis|surrounds
<scm-arg|widget> by padding>
<|explain>
This sets some fixed padding around <scm|wid>. As in the case of
This sets some fixed padding around <scm-arg|widget>. As in the case of
<scm|centered>, the effect is achieved by means of several widgets into
which this macro expands. These are actually the same as in the example
there, but the <scm|glue> widgets are all fixed (i.e. have all their
expansion paramenters set to <scm|#f>).
</explain>
<section|Container or layout widgets>
<subsection|Container or layout widgets>
You can arrange widgets horizontally or vertically, or in two column mode
as in forms. When running the QT version the latter will default to the OS
@ -106,63 +110,67 @@
macro is <scm|dynamic>, which allows you to embed one widget into another.
<\explain>
<scm|(aligned items-list)><explain-synopsis|arranges items in a two
column table>
<scm|(aligned <scm-arg|items-list>)><explain-synopsis|arranges items in a
two column table>
<|explain>
\;
</explain>
<\explain>
<scm|(hlist widgets)><explain-synopsis|arranges items horizontally>
<scm|(hlist <scm-arg|widgets>)> <explain-synopsis|arranges items
horizontally>
<|explain>
\;
</explain>
<\explain>
<scm|(vlist widgets)><explain-synopsis|arranges items vertically>
<scm|(vlist <scm-arg|widgets>)><explain-synopsis|arranges items
vertically>
<|explain>
\;
</explain>
<\explain>
<scm|(hsplit (item ) (item ) ...)><explain-synopsis|arranges two items in
a variable size split panel>
<scm|(hsplit (item (<scm-arg|widget>)) (item (<scm-arg|widget>))
...)><explain-synopsis|arranges two items in a split panel>
<|explain>
\;
</explain>
<\explain>
<scm|(tabs (tab ) (tab ) ...)><explain-synopsis|a tabbed widget>
<scm|(tabs (tab (<scm-arg|widget>)) (tab (<scm-arg|widget>))
...)><explain-synopsis|a tabbed widget>
<|explain>
\;
</explain>
<\explain>
<scm|(dynamic (wid))><explain-synopsis|embeds a tm-widget into another
one>
<scm|(dynamic (<scm-arg|widget>))><explain-synopsis|embeds a tm-widget
into another one>
<|explain>
<scm|wid> can be any widget defined using <scm|tm-define>.
\;
</explain>
<section|Glue widgets>
<subsection|Glue widgets>
Besides laying out widgets in containers, you will often want to specifiy
how they eat up space around them when the user resizes the window. By
default (most?) widgets take up as much space as they can (i.e. they always
expand) unless you used <scm|resize> with them. If you don't want this to
happen you can place invisible spacers around them which will (if you tell
them to) gobble up as much as they can, either vertically or horizontally
or in both directions.
expand) unless you used <scm|resize> with them or they can have their size
set with a parameter. If you don't want this to happen you can place
invisible spacers around them which will (if you tell them to) gobble up as
much as they can, either vertically or horizontally or in both directions.
<TeXmacs> provides one such basic building block:
<\explain>
<scm|(glue horiz vert width height)><explain-synopsis|possibly expanding
whitespace>
<scm|(glue <scm-arg|horiz> <scm-arg|vert> <scm-arg|width>
<scm-arg|height>)><explain-synopsis|possibly expanding whitespace>
<|explain>
The first two parameters are of type <scm|bool> and specify whether the
<scm|glue> widget will try to expand horizontally or vertically when its
surroundings do. The last two parameters either fix the size for
The first two parameters, <scm-arg|horiz> and <scm-arg|vert>, are of
boolean type and specify whether the <scm|glue> widget will try to expand
horizontally or vertically when its surroundings do. The last two
parameters, <scm-arg|width> <scm-arg|height>, either fix the size for
non-expanding <scm|glue> or set a minimum one.
<\session|scheme|default>
@ -171,7 +179,7 @@
\ \ (centered (text "I'm centered.")))
<|unfolded-io>
((guile-user) (guile-user))
\;
</unfolded-io>
<\unfolded-io|Scheme] >
@ -191,7 +199,7 @@
\ \ \ \ (glue #f #f 0 10)))
<|unfolded-io>
((guile-user) (guile-user) (guile-user) (guile-user))
\;
</unfolded-io>
<\input|Scheme] >
@ -201,10 +209,6 @@
<\input|Scheme] >
(show wid2)
</input>
<\input|Scheme] >
\;
</input>
</session>
</explain>
@ -263,14 +267,17 @@
a bug which hasn't yet been fixed)
</explain>
<section|Refresh widgets>
<subsection|Refresh widgets>
Refresh widgets reevaluate their contents every time a command is
executed...
<section|Composite widgets>
<tmdoc-copyright|2012|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>

185
devel/scheme/gui/scheme-gui-dialogs.en.tm Normal file
View File

@ -0,0 +1,185 @@
<TeXmacs|1.0.7.16>
<style|tmdoc>
<\body>
<tmdoc-title|Dialogs and composite widgets>
<with|font-shape|italic|Dialogs> are collections of widgets arranged in a
window in order to perform a common task. You might want to create one of
this in order to configure or interact with a plugin: add some
configuration options as well as some common actions and have the window
always open besides your document. A good example whose code might help is
the preferences dialog <scm|(open-preferences)>.
In order to create more complex layouts than those we did before you'll
need a few containers. Among these are <scm|aligned> and <scm|tabs>, which
we explain below. A very useful macro which you'll be using often is
<scm|dynamic>: it allows you to embed one widget into another.
Let's see how you create a dialog. To get started here is one little
example taken from <hlink|menu-test.scm|$TEXMACS_PATH/progs/kernel/gui/menu-test.scm>:
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (widget1)
\ \ (centered
\ \ \ \ (aligned
\ \ \ \ \ \ (item (text "First:")
\ \ \ \ \ \ \ \ (toggle (display* "First " answer "\\n") #f))
\ \ \ \ \ \ (item (text "Second:")
\ \ \ \ \ \ \ \ (toggle (display* "Second " answer "\\n") #f)))))
<|unfolded-io>
\;
</unfolded-io>
</session>
The keyword <scm|centered> is clear, just center whatever it contains, but
<scm|aligned> not so much: it builds two column tables, with each row of
type <scm|item>. As you can see, each <scm|item> takes two arguments, which
can be of <with|font-shape|italic|any> type.
The <scm|toggle> is another example of a widget which triggers a <scheme>
command whenever it's clicked, or toggled in this case. The second argument
stands for the default state of the <scm|toggle>.
Again, in order to display this you create a <scm|top-window> and give it a
title.
<\session|scheme|default>
<\input|Scheme] >
(top-window widget1 "Two toggle widgets")
</input>
</session>
You'll notice that the created window is too small and the title is not
wholly displayed. You can force it to be of a certain size using
<scm|resize>:
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (widget1)
\ \ (centered
\ \ \ \ (resize "500px" "200px"
\ \ \ \ \ \ (aligned
\ \ \ \ \ \ \ \ (item (text "First:")
\ \ \ \ \ \ \ \ \ \ (toggle (display* "First " answer "\\n") #f))
\ \ \ \ \ \ \ \ (item (text "Second:")
\ \ \ \ \ \ \ \ \ \ (toggle (display* "Second " answer "\\n") #f))))))
<|unfolded-io>
\;
</unfolded-io>
<\input|Scheme] >
(top-window widget1 "A bigger window")
</input>
</session>
<scm|resize> is another of the several available container or
<hlink|content management widgets|scheme-gui-container.en.tm>. It accepts
two sorts of arguments. Either one sets a fixed size for the widget with
two strings, as in the example above, or one passes two lists, the first
for widths, the second for heights, with the minimum, default and maximum
values in that order, like this:\
<scm|(resize ("100px" "200px" "400px") ("100px" "200px" "400px")
(some-widget-here))>
This sets <scm|some-widget-here> to have a default square size of 200x200
pixels.
If you want to add the usual buttons you use <scm|bottom-buttons> like in
the following example. Notice that the widget now accepts one parameter
<scm|cmd> which will be called when the user clicks the ``Ok'' button.
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (widget1-buttons cmd)
\ \ (centered
\ \ \ \ (aligned
\ \ \ \ \ \ (item (text "First:")
\ \ \ \ \ \ \ \ (toggle (display* "First " answer "\\n") #f))
\ \ \ \ \ \ (item (text "Second:")
\ \ \ \ \ \ \ \ (toggle (display* "Second " answer "\\n") #f))))
\ \ (bottom-buttons \<gtr\>\<gtr\> ("Ok" (cmd "Ok"))))
<|unfolded-io>
\;
</unfolded-io>
</session>
Since the widget now needs an argument, we must use another function to
display it, namely <scm|dialogue-window>, which will also close the window
after the button has been clicked.
<\session|scheme|default>
<\input|Scheme] >
(dialogue-window widget1-buttons (lambda (arg) (display* arg "\\n"))
"Two toggles")
</input>
</session>
That special <scm|\<gtr\>\<gtr\>> at the end of the widget inserts as
before whitespace, but it stretches and aligns the <scm|bottom-buttons> to
the right. This is just another example of a <hlink|glue
widget|scheme-gui-advanced.en.tm>.
<subsection|Composite widgets>
Note that our second dialog, <scm|widget1-buttons> is just a copy of
<scm|widget1> with an extra line at the end. We could have spared us the
keytrokes in this way:
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (widget1-buttons-smarter cmd)
\ \ (dynamic (widget1))
\ \ (bottom-buttons \<gtr\>\<gtr\> ("Ok" (cmd "Ok"))))
<|unfolded-io>
\;
</unfolded-io>
<\input|Scheme] >
(dialogue-window widget1-buttons-smarter (lambda (arg) (display* arg
"\\n")) "Two toggles")
</input>
\;
</session>
As you can see, the approach we've shown has a shortcoming: there's no way
to access all the values of the different widgets in your dialog at the
same time. Of course you can use the function <scm|cmd> passed to your
widget to perform some computations, but in case you need to retrieve or
store complicated data, what you need is a form.
<tmdoc-copyright|2012|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>

99
devel/scheme/gui/scheme-gui-forms.en.tm Normal file
View File

@ -0,0 +1,99 @@
<TeXmacs|1.0.7.16>
<style|tmdoc>
<\body>
<tmdoc-title|Forms>
As explained in ``<hlink|Dialogs and composite
widgets|scheme-gui-dialogs.en.tm>'' the available widgets can be used to
compose dialog windows which perform one simple task. But sometimes one
needs to read complex input from the user and forms provide one mechanism
to do this. They allow you to define multiple named fields of several
types, whose values are stored in a hash table. The contents of this hash
can be retrieved when the user clicks a button using the functions
<scm|form-fields> and <scm|form-values>.
In the following example you can see that the syntax is pretty much the
same as for regular widgets, but you must prefix the keywords with
<scm|form-> :
<\session|scheme|default>
<\folded-io|Scheme] >
(tm-widget (form3 cmd)
\ \ (resize "500px" "500px"
\ \ \ \ (padded
\ \ \ \ \ \ (form "Test"
\ \ \ \ \ \ \ \ (aligned
\ \ \ \ \ \ \ \ \ \ (item (text "Input:")
\ \ \ \ \ \ \ \ \ \ \ \ (form-input "fieldname1" "string" '("one")
"1w"))
\ \ \ \ \ \ \ \ \ \ (item === ===)
\ \ \ \ \ \ \ \ \ \ (item (text "Enum:")
\ \ \ \ \ \ \ \ \ \ \ \ (form-enum "fieldname2" '("one" "two" "three")
"two" "1w"))
\ \ \ \ \ \ \ \ \ \ (item === ===)
\ \ \ \ \ \ \ \ \ \ (item (text "Choice:")
\ \ \ \ \ \ \ \ \ \ \ \ (form-choice "fieldname3" '("one" "two"
"three") "one"))
\ \ \ \ \ \ \ \ \ \ (item === ===)
\ \ \ \ \ \ \ \ \ \ (item (text "Choices:")
\ \ \ \ \ \ \ \ \ \ \ \ (form-choices "fieldname4"\
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ '("one" "two"
"three")\
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ '("one" "two"))))
\ \ \ \ \ \ \ \ (bottom-buttons
\ \ \ \ \ \ \ \ \ \ ("Cancel" (cmd "cancel")) \<gtr\>\<gtr\>
\ \ \ \ \ \ \ \ \ \ ("Ok"
\ \ \ \ \ \ \ \ \ \ \ (display* (form-fields) " -\<gtr\> "
(form-values) "\\n")
\ \ \ \ \ \ \ \ \ \ \ (cmd "ok")))))))
<|folded-io>
\;
</folded-io>
<\input|Scheme] >
(dialogue-window form3 (lambda (x) (display* x "\\n")) "Test of form3")
</input>
</session>
A complete list of the widgets you can embed in a form is in the table
<scm|gui-make-table> inside <hlink|menu-define.scm|$TEXMACS_PATH/progs/kernel/gui/menu-define.scm>.
<tmdoc-copyright|2012|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>
<associate|preamble|false>
</collection>
</initial>

291
devel/scheme/gui/scheme-gui-intro.en.tm
View File

@ -1,11 +1,9 @@
<TeXmacs|1.0.7.15>
<TeXmacs|1.0.7.16>
<style|tmdoc>
<\body>
<tmdoc-title|An introduction to widgets, menus, dialogs and forms>
<section|Widgets><label|sec:widgets>
<tmdoc-title|An introduction to widgets>
In <TeXmacs> you create and extend the visual interface using <em|widgets>.
This word means either the basic building blocks you have at your disposal,
@ -25,17 +23,17 @@
complicated aggregations of widgets might be better placed in a separate
window or dialogue.
A complete reference with all the available widgets is
<hlink|here|scheme-gui-reference.en.tm>, some more examples are here and
here.
A complete reference with all the available widgets is the "<hlink|Widgets
reference guide|scheme-gui-reference.en.tm>", and you can find some
examples in the other subsections of "<hlink|Extending the graphical user
interface|scheme-gui.en.tm>". If you'd rather see the sources, the whole
list of keywords is in the table <scm|gui-make-table> inside
<hlink|menu-define.scm|$TEXMACS_PATH/progs/kernel/gui/menu-define.scm>.
To create a widget, you'll want to use <scm|tm-widget> to define a new one.
The call to this function uses its particular syntax, with many keywords
for the creation of widgets. You can see the whole list of keywords in the
table <scm|gui-make-table> inside <hlink|menu-define.scm|$TEXMACS_PATH/progs/kernel/gui/menu-define.scm>,
but we'll start with some buttons.\
<subsection|Buttons and labels>
To create a widget, you'll first need to use <scm|tm-widget> to define a
new one. The call to this function uses its particular syntax, with many
keywords for the creation of widgets. But we'll start with some buttons and
labels.\
Execute the following two lines to get the unavoidable example and leave
your mouse over the ``Hello'' button.
@ -72,8 +70,9 @@
The next step is to add some text next to the button, i.e. a label. This is
done with the <scm|text> keyword, as in <scm|(text "Hello")>, but in order
to have both widgets sit side by side, you'll need a <hlink|container
widget|scheme-gui-container.en.tm>, such as <scm|hlist>:
to have both widgets sit side by side, you'll need a container widget as
described in "<hlink|Containers, glue, refresh and
cia.|scheme-gui-advanced.en.tm>", such as <scm|hlist>:
<\session|scheme|default>
<\unfolded-io|Scheme] >
@ -118,258 +117,8 @@
</session>
The special symbol <scm|\<gtr\>\<gtr\>\<gtr\>> is just one of the
predefined <hlink|glue widgets|scheme-gui-advanced.en.tm>.
<section|Menus>
As we said before, menus are special collections of widgets:
<with|color|red|Problems with toolbars, system menus, context menus... Menu
containers: horizontal menu, vertical menu. Separators.>
<section|More complex widgets>
In order to create more complex layouts you'll need a few containers. Among
these are <scm|aligned> and <scm|tabs>. A very useful macro is
<scm|dynamic>: it allows you to embed one widget into another.
<subsection|User dialogs><label|sec:dialogs>
Let's see how you create a dialog. To get started here is one little
example taken from <hlink|menu-test.scm|$TEXMACS_PATH/progs/kernel/gui/menu-test.scm>:
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (widget1)
\ \ (centered
\ \ \ \ (aligned
\ \ \ \ \ \ (item (text "First:")
\ \ \ \ \ \ \ \ (toggle (display* "First " answer "\\n") #f))
\ \ \ \ \ \ (item (text "Second:")
\ \ \ \ \ \ \ \ (toggle (display* "Second " answer "\\n") #f)))))
<|unfolded-io>
\;
</unfolded-io>
</session>
The keyword <scm|centered> is clear, but <scm|aligned> not so much: it
builds two column tables, with each row of type <scm|item>. As you can see,
each <scm|item> takes two arguments, which can be of
<with|font-shape|italic|any> type.
The <scm|toggle> is another example of a widget which triggers a <scheme>
command whenever it's clicked, or toggled in this case. The second argument
stands for the default state of the <scm|toggle>.
Again, in order to display this you create a <scm|top-window> and give it a
title.
<\session|scheme|default>
<\input|Scheme] >
(top-window widget1 "Two toggle widgets")
</input>
</session>
You'll notice that the created window is too small and the title is not
wholly displayed. You can force it to be of a certain size using
<scm|resize>:
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (widget1)
\ \ (centered
\ \ \ \ (resize "500px" "200px"
\ \ \ \ \ \ (aligned
\ \ \ \ \ \ \ \ (item (text "First:")
\ \ \ \ \ \ \ \ \ \ (toggle (display* "First " answer "\\n") #f))
\ \ \ \ \ \ \ \ (item (text "Second:")
\ \ \ \ \ \ \ \ \ \ (toggle (display* "Second " answer "\\n") #f))))))
<|unfolded-io>
\;
</unfolded-io>
<\input|Scheme] >
(top-window widget1 "A bigger window")
</input>
</session>
<scm|resize> is one of the several available container or <hlink|content
management widgets|scheme-gui-container.en.tm>. It accepts two sorts of
arguments. Either one sets a fixed size for the widget with two strings, as
in the example above, or one passes two lists, the first for widths, the
second for heights, with the minimum, default and maximum values in that
order, like this:\
<scm|(resize ("100px" "200px" "400px") ("100px" "200px" "400px")
(some-widget-here))>
This sets <scm|some-widget-here> to have a default square size of 200x200
pixels.
If you want to add the usual buttons you use <scm|bottom-buttons> like in
the following example. Notice that the widget now accepts one parameter
<scm|cmd> which will be called when the user clicks the ``Ok'' button.
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (widget1-buttons cmd)
\ \ (centered
\ \ \ \ (aligned
\ \ \ \ \ \ (item (text "First:")
\ \ \ \ \ \ \ \ (toggle (display* "First " answer "\\n") #f))
\ \ \ \ \ \ (item (text "Second:")
\ \ \ \ \ \ \ \ (toggle (display* "Second " answer "\\n") #f))))
\ \ (bottom-buttons \<gtr\>\<gtr\> ("Ok" (cmd "Ok"))))
<|unfolded-io>
\;
</unfolded-io>
</session>
Since the widget now needs an argument, we must use another function to
display it, namely <scm|dialogue-window>, which will also close the window
after the button has been clicked.
<\session|scheme|default>
<\input|Scheme] >
(dialogue-window widget1-buttons (lambda (arg) (display* arg "\\n"))
"Two toggles")
</input>
</session>
That special <scm|\<gtr\>\<gtr\>> at the end of the widget inserts as
before whitespace, but it stretches and aligns the <scm|bottom-buttons> to
the right. This is just another example of a <hlink|glue
widget|scheme-gui-advanced.en.tm>.
<subsection|Composite widgets>
Note that our second dialog, <scm|widget1-buttons> is just a copy of
<scm|widget1> with an extra line at the end. We could have spared us the
keytrokes in this way:
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (widget1-buttons-smarter cmd)
\ \ (dynamic (widget1))
\ \ (bottom-buttons \<gtr\>\<gtr\> ("Ok" (cmd "Ok"))))
<|unfolded-io>
\;
</unfolded-io>
<\input|Scheme] >
(dialogue-window widget1-buttons-smarter (lambda (arg) (display* arg
"\\n")) "Two toggles")
</input>
\;
</session>
As you can see, the approach we've shown has a shortcoming: there's no way
to access all the values of the different widgets in your dialog at the
same time. Of course you can use the function <scm|cmd> passed to your
widget to perform some computations, but in case you need to retrieve or
store complicated data, what you need is a form (See
<reference|sec:forms>).
<section|Forms><label|sec:forms>
As explained in <reference|interface:dialogs> the available widgets can be
used to create menu items and dialog windows, but you may want to create
more complex dialogs to perform more complicated tasks. Forms provide one
mechanism to do this. They allow you to define multiple named fields of
several types, whose values are stored in a hash table You can retrieve and
return the values of this hash when the user clicks a button using the
functions <scm|form-fields> and <scm|form-values>.
In the following example you can see that the syntax is pretty much the
same as for regular widgets, but you must prefix the keywords with
<scm|form-> :
<\session|scheme|default>
<\unfolded-io|Scheme] >
(tm-widget (form3 cmd)
\ \ (resize "500px" "500px"
\ \ \ \ (padded
\ \ \ \ \ \ (form "Test"
\ \ \ \ \ \ \ \ (aligned
\ \ \ \ \ \ \ \ \ \ (item (text "Input:")
\ \ \ \ \ \ \ \ \ \ \ \ (form-input "fieldname1" "string" '("one")
"1w"))
\ \ \ \ \ \ \ \ \ \ (item === ===)
\ \ \ \ \ \ \ \ \ \ (item (text "Enum:")
\ \ \ \ \ \ \ \ \ \ \ \ (form-enum "fieldname2" '("one" "two" "three")
"two" "1w"))
\ \ \ \ \ \ \ \ \ \ (item === ===)
\ \ \ \ \ \ \ \ \ \ (item (text "Choice:")
\ \ \ \ \ \ \ \ \ \ \ \ (form-choice "fieldname3" '("one" "two"
"three") "one"))
\ \ \ \ \ \ \ \ \ \ (item === ===)
\ \ \ \ \ \ \ \ \ \ (item (text "Choices:")
\ \ \ \ \ \ \ \ \ \ \ \ (form-choices "fieldname4"\
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ '("one" "two"
"three")\
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ '("one" "two"))))
\ \ \ \ \ \ \ \ (bottom-buttons
\ \ \ \ \ \ \ \ \ \ ("Cancel" (cmd "cancel")) \<gtr\>\<gtr\>
\ \ \ \ \ \ \ \ \ \ ("Ok"
\ \ \ \ \ \ \ \ \ \ \ (display* (form-fields) " -\<gtr\> "
(form-values) "\\n")
\ \ \ \ \ \ \ \ \ \ \ (cmd "ok")))))))
<|unfolded-io>
\;
</unfolded-io>
<\input|Scheme] >
(dialogue-window form3 (lambda (x) (display* x "\\n")) "Test of form3")
</input>
</session>
A complete list of the widgets you can embed in a form is in the table
<scm|gui-make-table> inside <hlink|menu-define.scm|$TEXMACS_PATH/progs/kernel/gui/menu-define.scm>.
predefined glue widgets described in "<hlink|Containers, glue, refresh and
cia.|scheme-gui-advanced.en.tm>".
<tmdoc-copyright|2012|the <TeXmacs> team.>
@ -380,3 +129,9 @@
with no Back-Cover Texts. A copy of\nthe license is included in the section
entitled "GNU Free Documentation License".>
</body>
<\initial>
<\collection>
<associate|preamble|false>
</collection>
</initial>

21
devel/scheme/gui/scheme-gui-menus.en.tm Normal file
View File

@ -0,0 +1,21 @@
<TeXmacs|1.0.7.16>
<style|tmdoc>
<\body>
<tmdoc-title|Menus and toolbars>
As we said before, menus are special collections of widgets:
<with|color|red|Problems with toolbars, system menus, context menus... Menu
containers: horizontal menu, vertical menu. Separators.>
<tmdoc-copyright|2012|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>

16
devel/scheme/gui/scheme-gui-reference.en.tm
View File

@ -1,4 +1,4 @@
<TeXmacs|1.0.7.15>
<TeXmacs|1.0.7.16>
<style|tmdoc>
@ -6,14 +6,18 @@
<tmdoc-title|Widgets reference guide>
This should be a comprehensive list of all the widgets available to the
user.
user, following this schema:
<\explain>
<scm|some-symbol><explain-synopsis|Some synopsis>
<|explain>
Some explanation.
</explain>
An excerpt from <verbatim|progs/kernel/gui/menu-define.scm>, as of SVN
revision 5238:
<\scm>
\;
(define-table gui-make-table
\ \ (eval ,gui-make-eval)
@ -191,12 +195,8 @@
\ \ \ \ \ \ \ \ \ \ (texmacs-error "gui-make" "invalid menu item ~S"
x))))
\;
</scm>
\;
<tmdoc-copyright|2012|the <TeXmacs> team.>
<tmdoc-license|Permission is granted to copy, distribute and/or modify

22
devel/scheme/gui/scheme-gui.en.tm
View File

@ -1,4 +1,4 @@
<TeXmacs|1.0.7.15>
<TeXmacs|1.0.7.16>
<style|tmdoc>
@ -6,7 +6,7 @@
<tmdoc-title|Extending the graphical user interface>
Most of the user interface to <TeXmacs> is dynamically created from within
the interpreted scheme code. New menus and buttons can be added, or the
the interpreted <scheme> code. New menus and buttons can be added, or the
existing ones reused and rearranged, even the main editor can be embedded
anywhere.
@ -14,14 +14,20 @@
the user. One possible approach is to use the facility <scm|interactive>,
which according to the user's preferences will either popoup a dialog or
ask in the footer bar, based in metadata you provide inside your
<scm|tm-define>'d function. See <with|color|red|here> for more on this
topic. However, automatically generated stuff is not always the best
approach, so you might want to explicitly design your interface placing it
inside a complicated dialog. The following sections should help with that.
<scm|tm-define>'d function. See ``<hlink|Meta information and logical
programming|../overview/overview-meta.en.tm>'' for more on this topic.
However, automatically generated content is not always the best approach,
so you might want to explicitly design your interface placing it inside a
complicated dialog. The following sections should help you with this.
<\traverse>
<branch|An introduction to widgets, dialogs and
forms.|scheme-gui-intro.en.tm>
<branch|An introduction to widgets.|scheme-gui-intro.en.tm>
<branch|Menus and toolbars.|scheme-gui-menus.en.tm>
<branch|Dialogs and composite widgets.|scheme-gui-dialogs.en.tm>
<branch|Forms.|scheme-gui-forms.en.tm>
<branch|Containers, glue and refresh widgets and other advanced
topics.|scheme-gui-advanced.en.tm>