PSC Code Manual

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.

Functions

Function signature Description
(dialog-add-action dac-key action) Adds an action to tile DAC-KEY
(dialog-add-default-action key) Automatically add the default action for KEY
(dialog-copy-value-if-disabled value key toggle) Set KEY to VALUE if TOGGLE is checked
(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
(dialog-get-data typed) Returns a list of keys and values from the current dialog
(dialog-init file name source) Runs a dialog and returns a data list of keys and values
(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
(dialog-popup-idx key value) Returns the index of VALUE in popup list for KEY
(dialog-popup-list-get key) Retusnr the list currently associated with popup tile KEY
(dialog-popup-list-get-def key) Returns the list associated with popup tile KEY
(dialog-popup-list-set key lst) Assigns the list property of popup list tile KEY to LST
(dialog-popup-list-update key) Updates the list associated with popup tile KEY
(dialog-popup-set key value) Sets the value of a popup list tile
(dialog-popup-val key) Returns the value of popup list tile KEY
(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
(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
(dialog-tile-val key) Returns the correctly-typed value of an arbitrary dialog tile
(dialog-toggle-enable value key) Enables or disables tile KEY based on toggle VALUE
(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

(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

(dialog-popup-idx key value)

Returns the index of VALUE in popup list for KEY

VARS:
(KEY STR)
(VALUE STR)

(dialog-popup-list-get key)

Retusnr the list currently associated with popup tile KEY

(dialog-popup-list-get-def key)

Returns the list associated with popup tile KEY

VARS:
(KEY STR)

(dialog-popup-list-set key lst)

Assigns the list property of popup list tile KEY to LST

VARS:
(KEY STR)

(dialog-popup-list-update key)

Updates the list associated with popup tile KEY

VARS:
(KEY STR)

(dialog-popup-set key value)

Sets the value of a popup list tile

VARS:
(KEY STR (MEMBER KEY POPUP-KEYS-STRINGS))

(dialog-popup-val key)

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)