Chapter 4. Syntactic Extensions

syntax: (make-menu (label item) (label item) ...)
returns: an instance of <menu>

This macro simplifies the construction of complex menus. The subforms are pairs of label and item, where label must evaluate to a string, and item is either a procedure of no arguments or a menu. If item is a procedure, the procedure is invoked whenever the corresponding label is chosen from the menu. If item is a menu, the menu is posted as a cascade whenever the corresponding label is chosen from the menu.

syntax: (create widget-class make-arg ... with (keyword value) ...)
returns: instance

Widgets are created using the create macro which initializes the widget instance and provides convenient keyword syntax for specifying initial widget attributes. The make-args are positional and must precede the optional keyword arguments. The auxiliary keyword with marks the end of the positional arguments and the start of the keyword arguments. The keyword arguments are optional and may appear in any order.

Every attribute that can be set with a method called set-attribute-name! can be initialized with a keyword of the form attribute-name:. For example, the title of a button called button1 can be set to "Done" by the method call (set-title! button1 "Done"). Alternatively the title of the button can be set to "Done" when it is first created by adding (title: "Done") to the list of keyword arguments in the call to create.

Note: The create macro extends the usual initialization sequence. Any class to be instantiated via create must supply (or inherit) a public init method that accepts the same arguments as the class. This method is called with the actual parameters (the values of the positional arguments) passed to the class just after the instance is created.

syntax: (pack widget (keyword value) ...)
returns: unspecified

The pack macro makes more complex widget layouts possible using a set of keyword arguments including anchor:, expand:, fill:, and side:. These keywords determine the placement of the given widget within the available area of its parent. A <frame> is often useful to group several widgets together. anchor: specifies where the widget to be packed is anchored. Legal values are n, s, e, w, ne, se, sw, nw, and center. expand: is a boolean indicating whether or not the widget should expand to fill its parent. fill: specifies how the widget should fill its parent: x means fill horizontally, y means fill vertically, both fills both horizontally and vertically, and none avoids filling. side: determines what side of the parent widget this widget is anchored at. Legal values are: top, bottom, left, and right.

To change the layout of a widget repack it using a different set of attributes. When a widget is hidden via the hide method it currently forgets its previous layout.

The whole process of geometry management will likely be revised soon.

syntax: (swl:file-dialog title kind (keyword value) ...)
returns: see below

The swl:file-dialog macro displays the native file selection dialog for the current platform. The title should evaluate to a string, kind should evaluate to one of the symbols save or open. The optional keyword arguments are: parent: which specifies the <toplevel> served by the dialog, default-file: which indicates the filename initially displayed in the text entry field of the dialog, default-dir: which names the directory to display initially if the current directory is not to be used, default-extension: which (under Windows) gives an extension to use if the filename entered by the user has none, and file-types: which allows the display to be restricted to files with particular extensions. If supplied, the file-types: keyword takes an association list of the form (("file type" ("extension-pattern" ...)) ...).

syntax: (get-option widget keyword ...)
returns: see below

The get-option macro returns the values for one or more widget attributes corresponding to the given keywords. Multiple values are returned when several keywords are given. The list of possible keywords is the same as for create and set-option!.

syntax: (set-option! widget (keyword value) ...)
returns: unspecified

The set-option! macro makes it possible to change several widget attributes at one time using the same keyword argument syntax provided by the create macro. The list of possible keywords is the same as for create and get-option.

syntax: (tab-stops (keyword value) ...)
returns: a list of <tab-stop> instances

This macro simplifies the construction of lists of <tab-stop> instances used when setting the tab stops of text widgets and markups.

Each keyword must be left:, for left-aligned tabs, right:, for right-aligned tabs, center: for centered tabs, or numeric: for tabs that are aligned on the decimal point.

Each value must be a non-negative integer.

syntax: (make-font base-font (keyword value) ...)
returns: an instance of <font>

This macro provides convenient syntax for overriding particular attributes of an existing <font> instance when constructing a new instance. The valid keywords are family:, size:, add:, and cancel:. The latter two are used to add or cancel sets of font style properties, such as bold, italic, etc. For example

(make-font template-font (size: 16) (add: '(bold)) (cancel: '(italic underline)))

requests a 16-point bold version of template-font that is not italic or underlined.

syntax: (event-case ((key= x) (modifier= y)) ((pattern ...) e0 e1 ...) ...)
returns: see below

This macro simplifies pattern matching of events. The key= and modifier= bindings indicate expressions that evaluate to the key and modifier information from the event. One or the other may be omitted.

pattern is a non-empty list of zero or more modifiers followed by an optional key specifier. Modifiers are keywords from the set shift, control, alt, caps_lock, num_lock, double, triple, left-button, middle-button, and right-button. The last three match mouse buttons that are pressed. double and triple are meaningful only for mouse button press and release. A key specifier is either a Scheme character, a range of characters such as #\a - #\z, or a symbol naming one of the special keys, such as escape, home, left, up, right, down, page_up, page_down, home end, etc. The program ./apps/common/ can be helpful in finding the symbolic name for a particular key. Note that alt is a modifier while alt_l and alt_r are keys.

Each clause (pattern e0 e1 ...) is scanned in order until a pattern is found that matches the event described by the key= and modifier= keyword bindings. If specified, the key must match exactly. A modifier matches if it contains at least the modifiers specified by the pattern. More specific patterns should precede less specific patterns. The else clause, if present, matches any event. (See 1.5.)

Note that key= must be bound to a character or a value returned by keysym->keycode, while modifier= must be bound to a value returned by add-modifiers or cancel-modifiers.

syntax: (cancel-modifiers keyword-or-modifier ...)
returns: a modifier set

This macro returns the set of modifiers that results when subsequent modifiers are removed from the first. For example, if x is bound to a set of modifiers, then (cancel-modifiers x shift control) cancels the shift and control modifiers from x. (See 4)

syntax: (add-modifiers keyword-or-modifier ...)
returns: a modifier set

This macro constructs a set of modifiers from keywords such as control and left-button, and from other modifiers. The resulting set of modifiers can be examined by event-case. (See 4)