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

293
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> <style|tmdoc>
<\body> <\body>
<tmdoc-title|An introduction to widgets, menus, dialogs and forms> <tmdoc-title|An introduction to widgets>
<section|Widgets><label|sec:widgets>
In <TeXmacs> you create and extend the visual interface using <em|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, 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 complicated aggregations of widgets might be better placed in a separate
window or dialogue. window or dialogue.
A complete reference with all the available widgets is A complete reference with all the available widgets is the "<hlink|Widgets
<hlink|here|scheme-gui-reference.en.tm>, some more examples are here and reference guide|scheme-gui-reference.en.tm>", and you can find some
here. 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. To create a widget, you'll first need to use <scm|tm-widget> to define a
The call to this function uses its particular syntax, with many keywords new one. The call to this function uses its particular syntax, with many
for the creation of widgets. You can see the whole list of keywords in the keywords for the creation of widgets. But we'll start with some buttons and
table <scm|gui-make-table> inside <hlink|menu-define.scm|$TEXMACS_PATH/progs/kernel/gui/menu-define.scm>, labels.\
but we'll start with some buttons.\
<subsection|Buttons and labels>
Execute the following two lines to get the unavoidable example and leave Execute the following two lines to get the unavoidable example and leave
your mouse over the ``Hello'' button. 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 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 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 to have both widgets sit side by side, you'll need a container widget as
widget|scheme-gui-container.en.tm>, such as <scm|hlist>: described in "<hlink|Containers, glue, refresh and
cia.|scheme-gui-advanced.en.tm>", such as <scm|hlist>:
<\session|scheme|default> <\session|scheme|default>
<\unfolded-io|Scheme] > <\unfolded-io|Scheme] >
@ -118,258 +117,8 @@
</session> </session>
The special symbol <scm|\<gtr\>\<gtr\>\<gtr\>> is just one of the The special symbol <scm|\<gtr\>\<gtr\>\<gtr\>> is just one of the
predefined <hlink|glue widgets|scheme-gui-advanced.en.tm>. predefined glue widgets described in "<hlink|Containers, glue, refresh and
cia.|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>.
<tmdoc-copyright|2012|the <TeXmacs> team.> <tmdoc-copyright|2012|the <TeXmacs> team.>
@ -379,4 +128,10 @@
Foundation; with no Invariant\nSections, with no Front-Cover Texts, and 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 with no Back-Cover Texts. A copy of\nthe license is included in the section
entitled "GNU Free Documentation License".> entitled "GNU Free Documentation License".>
</body> </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> <style|tmdoc>
@ -6,14 +6,18 @@
<tmdoc-title|Widgets reference guide> <tmdoc-title|Widgets reference guide>
This should be a comprehensive list of all the widgets available to the 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 An excerpt from <verbatim|progs/kernel/gui/menu-define.scm>, as of SVN
revision 5238: revision 5238:
<\scm> <\scm>
\;
(define-table gui-make-table (define-table gui-make-table
\ \ (eval ,gui-make-eval) \ \ (eval ,gui-make-eval)
@ -191,12 +195,8 @@
\ \ \ \ \ \ \ \ \ \ (texmacs-error "gui-make" "invalid menu item ~S" \ \ \ \ \ \ \ \ \ \ (texmacs-error "gui-make" "invalid menu item ~S"
x)))) x))))
\;
</scm> </scm>
\;
<tmdoc-copyright|2012|the <TeXmacs> team.> <tmdoc-copyright|2012|the <TeXmacs> team.>
<tmdoc-license|Permission is granted to copy, distribute and/or modify <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> <style|tmdoc>
@ -6,7 +6,7 @@
<tmdoc-title|Extending the graphical user interface> <tmdoc-title|Extending the graphical user interface>
Most of the user interface to <TeXmacs> is dynamically created from within 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 existing ones reused and rearranged, even the main editor can be embedded
anywhere. anywhere.
@ -14,14 +14,20 @@
the user. One possible approach is to use the facility <scm|interactive>, 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 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 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 <scm|tm-define>'d function. See ``<hlink|Meta information and logical
topic. However, automatically generated stuff is not always the best programming|../overview/overview-meta.en.tm>'' for more on this topic.
approach, so you might want to explicitly design your interface placing it However, automatically generated content is not always the best approach,
inside a complicated dialog. The following sections should help with that. so you might want to explicitly design your interface placing it inside a
complicated dialog. The following sections should help you with this.
<\traverse> <\traverse>
<branch|An introduction to widgets, dialogs and <branch|An introduction to widgets.|scheme-gui-intro.en.tm>
forms.|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 <branch|Containers, glue and refresh widgets and other advanced
topics.|scheme-gui-advanced.en.tm> topics.|scheme-gui-advanced.en.tm>