dialog/dialog.lsp [src]
Dialog utilities
Symbols to define before calling dialog-init:
- defaults-file: call (dialog-update-defaults-file )
This only works when the DCL file's path is /.dcl and
the defaults file is /defaults.dat. For sub-dialogs and other
dialogs not requiring a defaults file, leave this symbol nil.
- Key lists (lists of key names as strings). Setting these makes the system aware of keys
to include in xdata and the dialog defaults subsystem.
- plain-string-keys: edit boxes which should be read directly with get_tile
- int-keys: edit boxes to be read with safe-atoi
- dist-keys: edit boxes to be read with distof
- toggle-keys: toggle tiles
- popup-keys: special key list for popup list tiles. For each entry,
the car is the string identifier and the cdr specifies the current
list attribute of the popup list tile. Its form is one of the
following:
1. a list of strings
2. a symbol pointing to a list of strings
3. a lambda which takes no arguments and returns a list of strings
4. a symbol pointing to a subr which takes no arguments and returns a list of strings
- Declare the following variables locally for dialog-init to use and
keep out of the global scope:
- tile-actions map of tiles to tile actions
- extra-keys keys read from defaults-file but not used in main dialog
- default-actions: a list of cons cells mapping a key name to a symbol
pointing to a SUBR representing the tile's default action.
NOTE: default actions need not be specified at all if there is a symbol called
-action pointing to a SUBR. These are picked up automatically. The only time to
declare actions here is when one function applies to two separate keys (e.g. top and
bottom). Thus, functions called -action are mapped to exactly one tile and
take only a value argument, while functions specified here take key and value
arguments. See stair.lsp for an example.
- dialog-ties: a list whose entries are the arguments to dialog-tie-via-toggle. These ties
are made automatically on init
- sub-dialogs: a list of nested dialogs and what buttons they are
attached to. If the sub-dialog name and button key are the same, the
item is the single string name, and if not, it is a list whose car
is the dialog name and cdr is a list of string button keys to attach
the dialog to.
e.g. from stair.lsp
(setq sub-dialogs '(tread_opts ;; single dialog attached to button with same name
;; single dialog attached to two separate buttons
(conn_opts top_conn_opts bot_conn_opts)))
- any sub-dialogs must have a function -sub-init defined in
scope, which is set as the default action for its associated
buttons
- for each sub-dialog, set the following three symbols as lists of
key names as strings (different from the main dialog
versions). This is to indicate to dialog-init which extra-keys are
relevant to which sub-dialogs. See stair.lsp for an example.
- -popup-keys
- -dist-keys
- -keys
- hooks: there are several places in dialog.lsp where the system will
run a user-defined hook function if it is non-nil, using attempt-apply
- dialog-after-load: called after all main tile values are set from
defaults file, before default actions are assigned, dialog-ties
are made, and sub-dialogs are hooked up. This is the main place to
run hooks that need to change tile values on initial run, like
running special actions the first time.
- dialog-before-start: called just before the dialog is actually run
via built-in start_dialog. This is a good place to overwrite
default actions after they are set or make even more complex
dialog-ties than the system provides by default.
- dialog-before-save: called after user has clicked Save but before
tiles have been gathered in data variable. This is mainly used to
remove enable_* keys from key lists in multi-edit dialogs so they
aren't gathered into the final data variable.
- dialog-before-done: called immediately after the call to
dialog-get-data. This function will have access to a variable
called data that contains the final list that will be
returned. Use it to manipulate that list before the user gets it.
To add more hooks, add a call to
(attempt-apply dialog-- nil)
where appropriate in dialog.lsp and then define the corresponding
function in your dialog definition.
- technique -- custom save action: sometimes, it's helpful to define a
custom action for the Save button, rather than using the built-in.
For instance, if you want tile values to be saved as plain strings
rather than types determined by the key list they appear on, you can
get the data with
(setq data (dialog-get-data nil))
instead of the default
(setq data (dialog-get-data T))
Do this by (locally!) redefining dialog-save-action. The only
requirement you must follow is to call (done_dialog 0) at the end,
or else the dialog will hang forever. Note that dialog-init will
return whatever value is in the data variable, so assign whatever
you want to get back from that call to it.
- dialog-dumpout-func: to create a button that will close the
dialog, run a custom function, and return to the dialog, assign an
action to the button that
- defines dialog-dumpout-func. This is the function that will be
run when the dialog exits.
- defines dialog-dumpout-args if the function takes any
arguments. This is a list for passing via apply.
- runs (setq source (dialog-get-data T))
- manually calls (done_dialog 2) to close the dialog with an intent
to reopen. This tells the framework to apply dialog-dumpout-func
to dialog-dumpout-args and then reinitialize the dialog when it
ends (successfully -- ending in an error will not bring the dialog
back).
The dumpout function can manipulate the source variable to change
the dialog state based on user input. See land/dialog.lsp for an
example.
(dialog-add-action dac-key action)
Adds an action to tile DAC-KEY
Keeps track of current actions and appends rather than clobbering existing actions.
VARS:
(DAC-KEY STR)
(ACTION (LIST STR))
(dialog-add-default-action key)
Automatically add the default action for KEY
VARS:
(KEY STR)
(dialog-copy-value-if-disabled value key toggle)
Set KEY to VALUE if TOGGLE is checked
VARS:
(VALUE STR)
(KEY STR)
(TOGGLE STR)
(dialog-dynamic-load files)
Dynamically loads a number of DCL files together into a single dcl-id
(dialog-edit-box-action key string)
Default action for edit box tiles
Sets box value to ERR if left blank
VARS:
(KEY STR)
(dialog-get-data typed)
Returns a list of keys and values from the current dialog
If TYPED is non-nil, return them as typed values. Otherwise, strings.
(dialog-init file name source)
Runs a dialog and returns a data list of keys and values
FILE is the path to a DCL file. NAME is the name of the dialog in the file to run. SOURCE
is either nil or a data list of keys and values to initialize the dialog with. SOURCE
being nil means to use defaults-file.
VARS:
(FILE STR)
(NAME STR)
(dialog-load-defaults source)
Populates the dialog with values from SOURCE, or the defaults file
(dialog-load-defaults-partial)
Loads keys from load-defaults-keys into dialog
Returns the index of VALUE in popup list for KEY
VARS:
(KEY STR)
(VALUE STR)
Retusnr the list currently associated with popup tile KEY
Returns the list associated with popup tile KEY
VARS:
(KEY STR)
Assigns the list property of popup list tile KEY to LST
VARS:
(KEY STR)
Updates the list associated with popup tile KEY
VARS:
(KEY STR)
Sets the value of a popup list tile
VARS:
(KEY STR (MEMBER KEY POPUP-KEYS-STRINGS))
Returns the value of popup list tile KEY
VARS:
(KEY STR)
(dialog-save-action)
Dialog default save action
(dialog-save-defaults file)
Writes current dialog state to the defaults file
(dialog-set-key-vars)
Sets key variables in dialog-init
(dialog-start)
Replacement for start_dialog and unload_dialog
Calls both and returns the value of start_dialog
(dialog-sub-update-from-def button def)
Updates the -val variable for a sub dialog BUTTON based on DEF
(dialog-tie-via-toggle alist toggle)
Connect the values of tiles when TOGGLE is unchecked
VARS:
(ALIST LIST)
(TOGGLE STR)
(dialog-tile-val key)
Returns the correctly-typed value of an arbitrary dialog tile
VARS:
(KEY STR)
(dialog-toggle-enable value key)
Enables or disables tile KEY based on toggle VALUE
VARS:
(VALUE STR (MEMBER VALUE '("0" "1")))
(KEY STR)
(dialog-update-defaults-file dialog-name)
Replaces defaults file if it is older than the current version
(edit-box-val key)
Returns the typed value of an arbitrary edit box tile
VARS:
(KEY STR)