Before to read what follows, it is advised to read a tutorial about SWT (Java Standard Widget Toolkit).
More SWT books and documentation.
The main argument of the dialogue function is compound which is a specification of controls and layouts.
compound : layout | composite | ( {layout-component}*)
layout : (layout-type [options] ( {layout-component}* ))
composite : (composite-type [style-spec] [options] composite-components )
layout-component : control-or-composite | grid-row
composite-components : layout | ( {control-or-composite}* ) | {tab-items}*
control-or-composite : control | composite
grid-row : ( {control-or-composite}* )
tab-item : (title options {control-or-composite}* )
style-spec : :style ( {style}* )
style : :h-scroll | :v-scroll | :border | ... (see SWT documentation)
control : atomic-control | (options)
atomic-control : a slot name (symbol), a special variable (symbol),
an atomic value (including NIL)
options : {option}*
option : keyword and value
layout-type : :fill-h | :fill-v | :row | :column | :grid | :2c-grid | :form
composite-type: :composite | :group | :tabfolder | :sashform
A keyword of a layout option is made from a public field of the layout SWT class (configuration field). For example, :makeColumnsEqualWidth and :horizontalSpacing for the :grid layout
The layout of a shell (top-level layout) may be omitted, writing for example
(dialogue `((:sashform...
instead of
(dialogue `(:grid
(((:sashform...
Shell default layouts:
:2c-grid layout is a 2-column layout based on the :grid layout. The left column contains "prompts" for controls that lay in the right column. Prompts are label controls, see the :prompt option of a control specification below.
If the layout that should follow a :group and :composite composite is omitted, it defauls to :2c-grid.
After a :grid layout, layout-component instances must be grid-row instances. After any other layout-type, layout-components must be control-or-composite instances.
Usually the :numColumns option in a :grid layout is not necessary because this value is computed from the numbers of items in the grid-row instances. Using the :numColumns option is advised when controls span cells.
In addition to the SWT options (:setforeground, ...), a composite may take some of the options of a control, at the present time: :style, :prompt and :name.
Notice a composite here isn't a composite in the SWT meaning.
After a :tabfolder composite, composite-components must be tab-items. Usually each tab-item contains a composite instance.
After a :sashform composite, composite-components must be a list of control-or-composite items.
A widget specification can be nil. Produces a dummy label widget, usally unvisible.
(defun dialogue
(;; specification of the controls and layouts
;; see syntax in the documentation
compound
&key
;; make the shell visible and active
(open? t)
;; make the shell visible and in front of all other shells (not active)
(move-above? nil)
;; usually a shell (makes a dialog shell)
;; If a display, makes a top-level shell
(parent (or *default-swt-parent* *display*))
;; Dialog (shell) modality
;; one of : :parent, :application, :system , :none (or nil)
(modality :parent)
;; Dialog (shell) trimmings
;; an unordered list of keywords to choose in: :border, :close, :min, :max,
;; :resize, :title, :no-trim and the standard trimmings :shell-trim and :dialog-trim.
;; If nil, defaults to :shell-trim or :dialog-trim (to :shell-trim if the parent is
;; a display, see parent argument)
;; Note:
;; :dialog-trim : same as (:title :border :close)
;; :shell-trim : same sa (:title :close :min :max :resize)
(trimmings *dialogue-default-trimmings*)
;; see with-shell&dispatch
(main nil)
;; a string (shell.settext)
(title nil)
;; Dialog (shell) options: a list of keyword and value pairs.
;; see documentation about the composite options (syntax of a composite)
;; Note: instead of :setText you can use Title argument. Title argument has
;; precedence.
(options nil)
;; dialog name (must be a symbol and is usually unique, see reuse? and
;; dispose-existing-shell? below. Notice if name is not unique, a control can't
;; be found on the dialog name using find-control - use *dialog-data, etc. instead.
;; If the name is not provided will be a keyword made from the title, text options
;; or gensym
(name nil)
;; if reuse? is nil, dispose an existing shell with same name
(dispose-existing-shell? t)
;; If T, reuse and make visible the dialog if it exists. If doesn't exist, make and
;; open the dialog (open = visible and active)
(reuse? T)
;; one of: :minimized :maximized :previous :normal nil
(state-on-reuse :normal)
;; to open the shell (make it visible and active) or just make it visible
(on-reuse-open? nil)
;; a list of exit controls specifications or
;; T to get 2 ok and cancel default buttons (NIL: no buttons).
;; See cancel-control, ok-control and make-exit-controls-composite-spec functions.
(exit-controls T)
;; if there is a button named :ok, set it as the default button
(default-button-name :ok)
;; the name of the control that should have the focus at opening
;; time
focused-control-name
;; One of nil, :nice or a foreign reference to a SWT point (to set
;; the top-left corner of the shell).
;; If :nice, compute the location from the cursor location and the size
;; of the dialog, unless one of the left or top arguments is given
(location :nice)
left top
;; to center the dialog on the screen (not implemented)
(center NIL)
;; ~~~ Init and closing functions: ~~~
;; a 1 argument function to be called at creation time (argument: the shell)
(creation-init-function nil)
;; a 1 argument function to be called at opening time (argument: the shell), after
;; the call to shell.pack. If the shell is reused, called before the call
;; to shell.setvisible
(init-function nil)
;; a 2 arguments function to be called on the close event (arguments : shell and event)
;; If the function returns T, the shell is disposed as well (default). If it returns
;; NIL the shell is not disposed (possibly this is not working on all OS).
;; On the close event, the :close property of the property list returned
;; by dialogue are set to T (see result parameter below).
;; Note : the close event is sent when the UI session is ending, before
;; SWT runs the dispose method (and possibly the dispose event is sent).
(close-function nil)
;; a plist that can be accessed using (dd-plist (find-dialog-data ))
(plist nil)
;; ~~~ A property list returned by dialogue as second value.
;; :ok property value is set to T in the selection handler of the default OK button.
;; :cancel property value is set to T in the default Cancel button selection handler.
;; See close-function parameter above.
;; Note: first value returned by dialogue is the value of the :ok property.
(result (list :ok nil :cancel nil :close nil))
;; ~~~ Defaults for the control specifications: ~~~
(font *dialogue-default-font*)
;; the default edit-specifier which may be:
;; :CLOS , :sv (or :special-variable) , :plist, NIL , :structure (not implemented)
(edit *edit-specifier*)
;; the default object (CLOS instance, plist, structure) to possibly be accessed by
;; each widget via the
;; reader and the writer . NIL means ignore this argument.
(data nil))
A symbol for which two functions have been defined, a reader (name) and a writer whose name is (setf name). Used to set the :reader and :writer options if they are not specified.
If edit option is :plist, accessor-name can be a property name in the edited property list and has priority over the :name option.
Any Lisp object (a CLOS instance or something else) to be accessed by the reader
and the writer of the item.
If not specified, defaults to the corresponding argument in the call to dialogue.
edit-specifier : is one of :CLOS , :sv (or :special-variable) ,
:plist or NIL
The edit option defaults to what has been specified in the :edit argument
of the call to dialogue.
To disable the control (which is enabled by default). Instead of :enabled, you can use the converse :read-only.
equality-test should be a function that takes two arguments, the old
and new value (Lisp values).
Defaults to the value-equal function.
To test if the value in a control has changed.
event-handlers : ( {event-type handler}* )
event-type is a keyword that matches the SWT event type: :activate :close :collapse :deactivate :defaultselection :deiconify :dispose :expand :focusin :focusout :help :hide :iconify :keydown :keyup :modify :mousedoubleclick :mousedown :mouseenter :mouseexit :mousehover :mousemove :mouseup :move :paint :resize :selection :show :verify.
See +event-types+ constant.
handler should be a 2 arguments function (event and control-data). event is a foil-ref. control-data: see the control-data structure definition.
A SWT font.
To ignore a control specification.
The initial value (Lisp value) to be put the control. If not specified will be computed from the reader (if one has been specified directly or mplicitely). If no reader is available and :edit option is :special-variable, the initial value is taken form the :item option. See the examples.
simple-item-spec : atomic-control | (atomic-control [edit-specifier])
atomic-control : see the syntax of the compound argument of dialogue
edit-specifier : see the :edit option
To quickly specify a dialog (see the examples).
layout-data-options: list of keyword and value pairs.
A keyword is named from the public fields of the SWT layout data.
See SWT documentation.
Notice :
Method-name: a method name (keyword) applicable to the control
(:setImage, :setSize, :setFont, :setForeground,...)
Argument: a value, a list of values (to be applied) or a function object.
If a function object, it should take 2 arguments (control and
control-data) and
return one argument or a list of arguments to be passed to the method.
Use :shell and :control to refer to the current shell and control in the argument (probably useless).
:setLayoutData will be ignored (use the :layout option instead).
See SWT documentation.
Control-name should be a symbol and be unique (at least if you want to access the control from the event handlers of another control).
If edit option is :plist, control-name should be a be a property name in the edited property list, except if :accessor option is specified.
If :control is not specified, control-name will be a keyword made of one of the following: slot name, special variable name, accessor, reader, writer, prompt, control type and position of the control in the compound.
Only for the :2c-grid layout.
If nil, no prompt will be created.
If not specified, defaults to the string of the widget-name if the item is a
:CLOS, a :special-variable or has an :accessor option.
Note: can be specified in the options of a :composite layout too.
For combo and list controls. A range of lisp values.
The range of strings to put in the control is computed from this
range using the read-converter (see :read-converter below).
Note : to set the range dynamically (usually from an event method), use the set-range function. Because the default write-converter function use this range to compute the value(s) to be returned.
A 1 argument function (the widget data object, see the :data option).
To get the initial value and to reinitialize a widget.
If not specified, it can be generated by using the values of other options:
-
the accessor name
-
the symbol-value function if the :edit option value
is :special-variable
- the slot-value function if the :edit option value
is :CLOS.
For basic controls only.
A function to convert the Lisp value into the value to be stored in the control ("control value"). Takes 2 arguments, the
Lisp value and the control-data.
Defaults: see ensure-read-converter function.
If read-converter is nil, nothing is stored.
See :enabled
A control type keyword describing one of the basic controls (:label, :text, :button, :list, :combo) or a Foil SWT class name (label., text., tree., ...).
The style of the control.
If the :type option value is a
keyword describing one of the basic controls, it should be a keyword or a list of keywords like
:multi, :center, :separator, :single, :radio, :check,... (see SWT documentation).
Style should be an integer if the :type option value is not a keyword. For example :
type tree. :style (logior *SWT.MULTI* *SWT.BORDER*)
For basic controls only.
A function to be called when the control looses focus (:focusout event) and the value of the control has changed.
The function takes 2 arguments: the new lisp value and the
control-data. If the function returns true, the new value is accepted.
If it returns nil, the old value is automatically restored
to the control.
By default (if value-accepter is unspecified):
- a new value is always accepted if a read_only combo or a list control, a check box.
- for the other controls, the new value is accepted according to the value-type option (if no value-type, the new value is always accepted).
If value-accepter is nil, this mecanism is skipped (same thing
if the write-converter is specified nil, because the mecanism uses the write-converter).
A lisp type. May be taken from a CLOS slot specification or
from the intial value. May be used to choose the control type
if the control type has not been specified.
For basic controls only.
A function to convert the control value into a Lisp value to pass
to the writer (if a writer is available).
Takes 2 arguments, the control value and the control-data.
See ensure-write-converter function for the provided defaults.
Notice : by default, removes leading and trailing spaces of the value of text and editable combo controls.
For basic controls only.
A 2 arguments function. The 2 arguments are the lisp new value
and the data lisp object. If not specified, it may be generated.
If nil nothing will be written back (same thing if write-converter
is nil).
Notes
The term function means a function name or a function object.
Basic controls : label, text, button , list, combo.
Options related to the reading mecanism: :initial-value, :reader, :read-converter, :range (combo and list controls).
Options related to the writing mecanism: :write-converter, :equality-test, :writer, :range (list control) .
:form layout
