psc/dialog

Symbols to define before calling dialog-init:



- defaults-file: call (dialog-update-defaults-file <dialog-name>)



  This only works when the DCL file's path is <name>/<name>.dcl and

  the defaults file is <name>/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

  <keyname>-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 <key-name>-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 <name>-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.



    - <name>-popup-keys

    - <name>-dist-keys

    - <name>-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-<before/after>-<event> 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.