mirror of https://github.com/texmacs/doc.git
A bit more documentation about widgets.
This commit is contained in:
Miguel de Benito
parent
f75134534c
commit
7a387e15a7
|
|
@ -8,49 +8,267 @@
|
|||
<section|Attribute widgets>
|
||||
|
||||
Setting attributes of widgets is achieved by enclosing them in the
|
||||
following special widgets:
|
||||
following special widgets.
|
||||
|
||||
<scm|centered>, <scm|resize>, <scm|padded>, ...\
|
||||
<\explain>
|
||||
<scm|(centered wid)><explain-synopsis|centers the widget <scm|wid>>
|
||||
<|explain>
|
||||
This does just that: it centers the widget <scm|wid> 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
|
||||
first widget is actually expanded to something like the second one.
|
||||
|
||||
<section|Container widgets>
|
||||
<\session|scheme|default>
|
||||
<\unfolded-io|Scheme] >
|
||||
(tm-widget (wid1)
|
||||
|
||||
\ \ (centered (text "I'm centered.")))
|
||||
<|unfolded-io>
|
||||
((guile-user) (guile-user))
|
||||
</unfolded-io>
|
||||
|
||||
<\folded-io|Scheme] >
|
||||
(tm-widget (wid2)
|
||||
|
||||
\ \ (vlist
|
||||
|
||||
\ \ \ \ (glue #f #f 0 10)
|
||||
|
||||
\ \ \ \ (hlist
|
||||
|
||||
\ \ \ \ \ \ (glue #t #f 25 0)
|
||||
|
||||
\ \ \ \ \ \ (text "I'm centered.")
|
||||
|
||||
\ \ \ \ \ \ (glue #t #f 25 0))
|
||||
|
||||
\ \ \ \ (glue #f #f 0 10)))
|
||||
<|folded-io>
|
||||
((guile-user) (guile-user))
|
||||
</folded-io>
|
||||
|
||||
<\input|Scheme] >
|
||||
(show wid1)
|
||||
</input>
|
||||
|
||||
<\input|Scheme] >
|
||||
(show wid2)
|
||||
</input>
|
||||
</session>
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|(resize (w1 w2 w3) (h1 h2 h3) wid)>
|
||||
|
||||
<scm|(resize w h wid)><explain-synopsis|resizes the widget <scm|wid>>
|
||||
<|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.
|
||||
|
||||
Sizes are specified as strings with a unit suffix, like in <scm|"150px">.
|
||||
|
||||
<\session|scheme|default>
|
||||
<\unfolded-io|Scheme] >
|
||||
(tm-widget (wid)
|
||||
|
||||
\ \ (resize "200px" "70px" (text "I'm stuck!")))
|
||||
<|unfolded-io>
|
||||
\;
|
||||
</unfolded-io>
|
||||
|
||||
<\input|Scheme] >
|
||||
(show wid)
|
||||
</input>
|
||||
</session>
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|(padded wid)><explain-synopsis|surrounds the widget <scm|wid> by
|
||||
padding>
|
||||
<|explain>
|
||||
This sets some fixed padding around <scm|wid>. 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>
|
||||
|
||||
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
|
||||
standard for arranging labels and their associated input widgets in
|
||||
dialogs.
|
||||
dialogs. Other possibilites are splitters and tabbed widgets. A very useful
|
||||
macro is <scm|dynamic>, which allows you to embed one widget into another.
|
||||
|
||||
<scm|aligned>, <scm|hlist>, <scm|vlist>, <scm|hsplit>, ...
|
||||
<\explain>
|
||||
<scm|(aligned items-list)><explain-synopsis|arranges items in a two
|
||||
column table>
|
||||
<|explain>
|
||||
\;
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|(hlist widgets)><explain-synopsis|arranges items horizontally>
|
||||
<|explain>
|
||||
\;
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|(vlist widgets)><explain-synopsis|arranges items vertically>
|
||||
<|explain>
|
||||
\;
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|(hsplit (item ) (item ) ...)><explain-synopsis|arranges two items in
|
||||
a variable size split panel>
|
||||
<|explain>
|
||||
\;
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|(tabs (tab ) (tab ) ...)><explain-synopsis|a tabbed widget>
|
||||
<|explain>
|
||||
\;
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|(dynamic (wid))><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>
|
||||
|
||||
Shifting of widgets... From the definitions:
|
||||
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.
|
||||
|
||||
<\verbatim>
|
||||
((== x '---) '$---)
|
||||
<TeXmacs> provides one such basic building block:
|
||||
|
||||
((== x '===) (gui-make '(glue #f #f 0 5)))
|
||||
<\explain>
|
||||
<scm|(glue horiz vert width 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
|
||||
non-expanding <scm|glue> or set a minimum one.
|
||||
|
||||
((== x '======) (gui-make '(glue #f #f 0 15)))
|
||||
<\session|scheme|default>
|
||||
<\unfolded-io|Scheme] >
|
||||
(tm-widget (wid1)
|
||||
|
||||
((== x '/) '$/)
|
||||
\ \ (centered (text "I'm centered.")))
|
||||
<|unfolded-io>
|
||||
((guile-user) (guile-user))
|
||||
</unfolded-io>
|
||||
|
||||
((== x '//) (gui-make '(glue #f #f 5 0)))
|
||||
<\unfolded-io|Scheme] >
|
||||
(tm-widget (wid2)
|
||||
|
||||
((== x '///) (gui-make '(glue #f #f 15 0)))
|
||||
\ \ (vlist
|
||||
|
||||
((== x '\<gtr\>\<gtr\>) (gui-make '(glue #t #f 5 0)))
|
||||
\ \ \ \ ===
|
||||
|
||||
((== x '\<gtr\>\<gtr\>\<gtr\>) (gui-make '(glue #t #f 15 0)))
|
||||
\ \ \ \ (hlist
|
||||
|
||||
((== x (string-\<gtr\>symbol "\|")) '$/)
|
||||
</verbatim>
|
||||
\ \ \ \ \ \ (glue #t #f 25 0)
|
||||
|
||||
\ \ \ \ \ \ (text "I'm centered.")
|
||||
|
||||
\ \ \ \ \ \ (glue #t #f 25 0))
|
||||
|
||||
\ \ \ \ (glue #f #f 0 10)))
|
||||
<|unfolded-io>
|
||||
((guile-user) (guile-user) (guile-user) (guile-user))
|
||||
</unfolded-io>
|
||||
|
||||
<\input|Scheme] >
|
||||
(show wid1)
|
||||
</input>
|
||||
|
||||
<\input|Scheme] >
|
||||
(show wid2)
|
||||
</input>
|
||||
|
||||
<\input|Scheme] >
|
||||
\;
|
||||
</input>
|
||||
</session>
|
||||
</explain>
|
||||
|
||||
In addition to the basic <scm|glue> widget, there are several convenience
|
||||
macros.
|
||||
|
||||
<\explain>
|
||||
<scm|===><explain-synopsis|vertical separator>
|
||||
<|explain>
|
||||
Expands to <scm|(glue #f #f 0 5)>.
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|======><explain-synopsis|big vertical separator>
|
||||
<|explain>
|
||||
Expands to <scm|(glue #f #f 0 15)>.
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|//><explain-synopsis|horizontal separator>
|
||||
<|explain>
|
||||
Expands to <scm|(glue #f #f 5 0)>.
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|///><explain-synopsis|big horizontal separator>
|
||||
<|explain>
|
||||
Expands to <scm|(glue #f #f 15 0)>.
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|\<gtr\>\<gtr\>><explain-synopsis|expanding horizontal separator>
|
||||
<|explain>
|
||||
Expands to <scm|(glue #t #f 5 0)>.
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|\<gtr\>\<gtr\>\<gtr\>><explain-synopsis|big expanding horizontal
|
||||
separator>
|
||||
<|explain>
|
||||
Expands to <scm|(glue #t #f 15 0)>.
|
||||
</explain>
|
||||
|
||||
For the specific use in menus the following two macros are defined:
|
||||
|
||||
<\explain>
|
||||
<scm|\|><explain-synopsis|horizontal separator>
|
||||
<|explain>
|
||||
(That's a vertical bar: <scm|\|>)
|
||||
</explain>
|
||||
|
||||
<\explain>
|
||||
<scm|---><explain-synopsis|vertical separator>
|
||||
<|explain>
|
||||
(That's <with|font-series|bold|three> dashes. If you see only two, that's
|
||||
a bug which hasn't yet been fixed)
|
||||
</explain>
|
||||
|
||||
<section|Refresh widgets>
|
||||
|
||||
Refresh widgets reevaluate their contents every time a command is
|
||||
executed...
|
||||
|
||||
<section|Other topics>
|
||||
<section|Composite widgets>
|
||||
|
||||
\;
|
||||
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@
|
|||
</session>
|
||||
|
||||
The special symbol <scm|\<gtr\>\<gtr\>\<gtr\>> is just one of the
|
||||
predefined <hlink|glue widgets|scheme-gui-glue.en.tm>.\
|
||||
predefined <hlink|glue widgets|scheme-gui-advanced.en.tm>.
|
||||
|
||||
<section|Menus>
|
||||
|
||||
|
|
@ -127,7 +127,13 @@
|
|||
<with|color|red|Problems with toolbars, system menus, context menus... Menu
|
||||
containers: horizontal menu, vertical menu. Separators.>
|
||||
|
||||
<section|User dialogs><label|sec:dialogs>
|
||||
<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>:
|
||||
|
|
@ -250,11 +256,35 @@
|
|||
</input>
|
||||
</session>
|
||||
|
||||
That special at the bottom <scm|\<gtr\>\<gtr\>> inserts as before
|
||||
whitespace, but it stretches and aligns the <scm|bottom-buttons> to the
|
||||
right (<with|color|red|right?>). This is just another example of a
|
||||
<with|font-shape|italic|glue widget>, of which there are more described
|
||||
<hlink|here|scheme-gui-glue.en.tm>.
|
||||
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
|
||||
|
|
@ -278,7 +308,7 @@
|
|||
<scm|form-> :
|
||||
|
||||
<\session|scheme|default>
|
||||
<\folded-io|Scheme] >
|
||||
<\unfolded-io|Scheme] >
|
||||
(tm-widget (form3 cmd)
|
||||
|
||||
\ \ (resize "500px" "500px"
|
||||
|
|
@ -329,9 +359,9 @@
|
|||
(form-values) "\\n")
|
||||
|
||||
\ \ \ \ \ \ \ \ \ \ \ (cmd "ok")))))))
|
||||
<|folded-io>
|
||||
((guile-user) (guile-user))
|
||||
</folded-io>
|
||||
<|unfolded-io>
|
||||
\;
|
||||
</unfolded-io>
|
||||
|
||||
<\input|Scheme] >
|
||||
(dialogue-window form3 (lambda (x) (display* x "\\n")) "Test of form3")
|
||||
|
|
|
|||
Loading…
Reference in New Issue