diff --git a/devel/scheme/gui/scheme-gui-advanced.en.tm b/devel/scheme/gui/scheme-gui-advanced.en.tm index 618ad4a..0f72bdb 100644 --- a/devel/scheme/gui/scheme-gui-advanced.en.tm +++ b/devel/scheme/gui/scheme-gui-advanced.en.tm @@ -1,19 +1,20 @@ - + <\body> - + - Setting attributes of widgets is achieved by enclosing them in the - following special widgets. + In what follows can be anything defined using + . <\explain> - > + )>> <|explain> - This does just that: it centers the widget with respect to the + This does just that: it centers 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 widgets. This means that in the following example, the @@ -59,15 +60,18 @@ <\explain> - + ) ( + ) )> - > + )>> <|explain> These two variants resize the argument. The first one specifies a minimum - size of , a default size of and a maximum size - of . The 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. + size of >, a default size of + > and a maximum size of + >. 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 . @@ -87,17 +91,17 @@ <\explain> - by - padding> + )> by padding> <|explain> - This sets some fixed padding around . As in the case of + This sets some fixed padding around . As in the case of , 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 widgets are all fixed (i.e. have all their expansion paramenters set to ). - + 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 , which allows you to embed one widget into another. <\explain> - + )> <|explain> \; <\explain> - + )> <|explain> \; <\explain> - + )> <|explain> \; <\explain> - + )) (item ()) + ...)> <|explain> \; <\explain> - + )) (tab ()) + ...)> <|explain> \; <\explain> - + ))> <|explain> - can be any widget defined using . + \; - + 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 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 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. provides one such basic building block: <\explain> - + + )> <|explain> - The first two parameters are of type and specify whether the - 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, and , are of + boolean type and specify whether the widget will try to expand + horizontally or vertically when its surroundings do. The last two + parameters, , either fix the size for non-expanding 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|Scheme] > @@ -191,7 +199,7 @@ \ \ \ \ (glue #f #f 0 10))) <|unfolded-io> - ((guile-user) (guile-user) (guile-user) (guile-user)) + \; <\input|Scheme] > @@ -201,10 +209,6 @@ <\input|Scheme] > (show wid2) - - <\input|Scheme] > - \; - @@ -263,14 +267,17 @@ a bug which hasn't yet been fixed) - + Refresh widgets reevaluate their contents every time a command is executed... - + team.> - \; - - \; + \ No newline at end of file diff --git a/devel/scheme/gui/scheme-gui-dialogs.en.tm b/devel/scheme/gui/scheme-gui-dialogs.en.tm new file mode 100644 index 0000000..3aace68 --- /dev/null +++ b/devel/scheme/gui/scheme-gui-dialogs.en.tm @@ -0,0 +1,185 @@ + + + + +<\body> + + + 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 . + + In order to create more complex layouts than those we did before you'll + need a few containers. Among these are and , which + we explain below. A very useful macro which you'll be using often is + : 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 : + + <\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> + \; + + + + The keyword is clear, just center whatever it contains, but + not so much: it builds two column tables, with each row of + type . As you can see, each takes two arguments, which + can be of type. + + The is another example of a widget which triggers a + command whenever it's clicked, or toggled in this case. The second argument + stands for the default state of the . + + Again, in order to display this you create a and give it a + title. + + <\session|scheme|default> + <\input|Scheme] > + (top-window widget1 "Two toggle widgets") + + + + 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 + : + + <\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> + \; + + + <\input|Scheme] > + (top-window widget1 "A bigger window") + + + + is another of the several available container or + . 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:\ + + + + This sets to have a default square size of 200x200 + pixels. + + If you want to add the usual buttons you use like in + the following example. Notice that the widget now accepts one parameter + 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 \\ ("Ok" (cmd "Ok")))) + <|unfolded-io> + \; + + + + Since the widget now needs an argument, we must use another function to + display it, namely , 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") + + + + That special \> at the end of the widget inserts as + before whitespace, but it stretches and aligns the to + the right. This is just another example of a . + + + + Note that our second dialog, is just a copy of + 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 \\ ("Ok" (cmd "Ok")))) + <|unfolded-io> + \; + + + <\input|Scheme] > + (dialogue-window widget1-buttons-smarter (lambda (arg) (display* arg + "\\n")) "Two toggles") + + + \; + + + 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 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. + + team.> + + + \ No newline at end of file diff --git a/devel/scheme/gui/scheme-gui-forms.en.tm b/devel/scheme/gui/scheme-gui-forms.en.tm new file mode 100644 index 0000000..12f0df9 --- /dev/null +++ b/devel/scheme/gui/scheme-gui-forms.en.tm @@ -0,0 +1,99 @@ + + + + +<\body> + + + As explained in ``'' 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 + and . + + 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 + : + + <\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")) \\ + + \ \ \ \ \ \ \ \ \ \ ("Ok" + + \ \ \ \ \ \ \ \ \ \ \ (display* (form-fields) " -\ " + (form-values) "\\n") + + \ \ \ \ \ \ \ \ \ \ \ (cmd "ok"))))))) + <|folded-io> + \; + + + <\input|Scheme] > + (dialogue-window form3 (lambda (x) (display* x "\\n")) "Test of form3") + + + + A complete list of the widgets you can embed in a form is in the table + inside . + + team.> + + + + +<\initial> + <\collection> + + + \ No newline at end of file diff --git a/devel/scheme/gui/scheme-gui-intro.en.tm b/devel/scheme/gui/scheme-gui-intro.en.tm index 00ee868..ed862f1 100644 --- a/devel/scheme/gui/scheme-gui-intro.en.tm +++ b/devel/scheme/gui/scheme-gui-intro.en.tm @@ -1,11 +1,9 @@ - + <\body> - - - + In you create and extend the visual interface using . 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 - , some more examples are here and - here. + A complete reference with all the available widgets is the "", and you can find some + examples in the other subsections of "". If you'd rather see the sources, the whole + list of keywords is in the table inside + . - To create a widget, you'll want to use 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 inside , - but we'll start with some buttons.\ - - + To create a widget, you'll first need to use 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 keyword, as in , but in order - to have both widgets sit side by side, you'll need a , such as : + to have both widgets sit side by side, you'll need a container widget as + described in "", such as : <\session|scheme|default> <\unfolded-io|Scheme] > @@ -118,258 +117,8 @@ The special symbol \\> is just one of the - predefined . - - - - As we said before, menus are special collections of widgets: - - - - - - In order to create more complex layouts you'll need a few containers. Among - these are and . A very useful macro is - : 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 : - - <\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> - \; - - - - The keyword is clear, but not so much: it - builds two column tables, with each row of type . As you can see, - each takes two arguments, which can be of - type. - - The is another example of a widget which triggers a - command whenever it's clicked, or toggled in this case. The second argument - stands for the default state of the . - - Again, in order to display this you create a and give it a - title. - - <\session|scheme|default> - <\input|Scheme] > - (top-window widget1 "Two toggle widgets") - - - - 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 - : - - <\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> - \; - - - <\input|Scheme] > - (top-window widget1 "A bigger window") - - - - is one of the several available container or . 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:\ - - - - This sets to have a default square size of 200x200 - pixels. - - If you want to add the usual buttons you use like in - the following example. Notice that the widget now accepts one parameter - 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 \\ ("Ok" (cmd "Ok")))) - <|unfolded-io> - \; - - - - Since the widget now needs an argument, we must use another function to - display it, namely , 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") - - - - That special \> at the end of the widget inserts as - before whitespace, but it stretches and aligns the to - the right. This is just another example of a . - - - - Note that our second dialog, is just a copy of - 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 \\ ("Ok" (cmd "Ok")))) - <|unfolded-io> - \; - - - <\input|Scheme] > - (dialogue-window widget1-buttons-smarter (lambda (arg) (display* arg - "\\n")) "Two toggles") - - - \; - - - 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 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 - ). - - - - As explained in 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 and . - - 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 - : - - <\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")) \\ - - \ \ \ \ \ \ \ \ \ \ ("Ok" - - \ \ \ \ \ \ \ \ \ \ \ (display* (form-fields) " -\ " - (form-values) "\\n") - - \ \ \ \ \ \ \ \ \ \ \ (cmd "ok"))))))) - <|unfolded-io> - \; - - - <\input|Scheme] > - (dialogue-window form3 (lambda (x) (display* x "\\n")) "Test of form3") - - - - A complete list of the widgets you can embed in a form is in the table - inside . + predefined glue widgets described in "". team.> @@ -379,4 +128,10 @@ 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".> - \ No newline at end of file + + +<\initial> + <\collection> + + + \ No newline at end of file diff --git a/devel/scheme/gui/scheme-gui-menus.en.tm b/devel/scheme/gui/scheme-gui-menus.en.tm new file mode 100644 index 0000000..8b87187 --- /dev/null +++ b/devel/scheme/gui/scheme-gui-menus.en.tm @@ -0,0 +1,21 @@ + + + + +<\body> + + + As we said before, menus are special collections of widgets: + + + + team.> + + + \ No newline at end of file diff --git a/devel/scheme/gui/scheme-gui-reference.en.tm b/devel/scheme/gui/scheme-gui-reference.en.tm index dae207c..d60a14d 100644 --- a/devel/scheme/gui/scheme-gui-reference.en.tm +++ b/devel/scheme/gui/scheme-gui-reference.en.tm @@ -1,4 +1,4 @@ - + @@ -6,14 +6,18 @@ This should be a comprehensive list of all the widgets available to the - user. + user, following this schema: + + <\explain> + + <|explain> + Some explanation. + An excerpt from , 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)))) - - \; - \; - team.> + @@ -6,7 +6,7 @@ Most of the user interface to is dynamically created from within - the interpreted scheme code. New menus and buttons can be added, or the + the interpreted 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 , 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 - 'd function. See 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. + 'd function. See ``'' 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> - + + + + + + +