![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Customizing Task Editor Actions using Dlisp Dlisp is an interpreted programming language used in Apex and Summit to define the behavior of dialogs in the graphical user interface. Dlisp syntax is similar to that of LISP. Dlisp supports the following constructs:
- %function - a global function shared by all dialogs.
- %prog - a program (procedure) belonging to a dialog.
- %dialog - a collection of %progs comprising a dialog.
- %popup - a popup menu definition.
The bodies of these constructs are expressions which are evaluated when the constructs are invoked. The expressions are written in the dlisp string language. Dlisp expressions return values and often have side effects as well.
This chapter defines the syntax and semantics of dlisp specifications for defining dialog behavior.
The following topics are covered in this chapter:
Note: An alternative to dlisp is the APEX_SHELL language, which is a super-set of the standard UNIX csh language. The shell language can be used in place of dlisp to write the body of any %function or %prog. See the Scripting Language Guide for details.
Functions (%function)A %function construct defines a global function which may be called by any dialog. A function has the following syntax:
%functionname
body
%end_function
The body is an expression written in the dlisp string language. A function can be called by its name using the primitive function call. Arguments may be passed in a call. For example, the string language expression
<call,display_count,5>
calls the function named display_count passing the argument value 5.
The string value that results from the evaluation of the body is the value returned by a call. A function can access its arguments in its body using the primitive function parm. For example:
<parm,2>
returns the value of the 3rd parameter (numbering starts at 0).
Dialog Programs (%prog)A %prog (or simply a prog) is a function which is local to a particular dialog. A prog has the following syntax:
%progname body
The body is written in the dlisp string language. Note that there is no %end_prog token. A prog is terminated by the next "%" in the input file.
A %prog behaves exactly like a %function. However, the name is local to the dialog in which it is defined. It can be called by its name from within that dialog using the primitive function call.
There are three categories of progs which are used in dialogs:
First, there are progs with the predefined names build, setup, init, and exec. These progs are called automatically when specific events occur related to the dialog's life cycle and when the standard buttons at the bottom of the dialog (OK, Apply, Reset, Cancel, and Help) are activated. These progs are described in the section "Dialogs" below.
The second category of progs have user-defined names and are called via the graphical user interface when some widget event occurs, for example when a push button is activated or the text in a widget is altered. Widget callbacks are linked to such progs through widget attributes in a widget definition or through the dlisp primitive function activation.
A third category of progs also have user-defined names and are called explicitly via the primitive function call. These progs are used as general-purpose functions that are local to the dialog in which they are defined.
Defining DialogsTo define a dialog's behavior, the syntax is:
%dialog name [parent
[%use_parent_gui]]
build-body (run once when widgets are first constructed)
setup-body (run once when dialog is started)
initialization-body (run when dialog is started and each time Reset is pressed)
execution-body (run when OK or Apply is pressed)
other-bodies (widget callbacks, sub-dialog invocations, local utility functions)
Each %prog is written in the string language described in The String Language. The dialog name is the dialog's identifier. The %progs can appear in any order.
The parent (if specified) identifies a parent dialog by name from which progs are inherited. The parent dialog must appear in the definitions file before the child.
If %use_parent_gui is present, the same dialog widget structure is used for this dialog as the parent dialog. This allows dialog construction functions to be shared.
The standard buttons of an Apex or Summit dialog are associated with specific %progs.
The OK and Apply buttons cause the exec program to be run. More specifically, OK causes the string language program
<call,exec><wait><cancel>
to be run and Apply causes the program
<call,exec><wait>
to be run. The wait primitive function is used to wait for the completion of an operation invoked by exec. The wait can be suppressed by using <return,nowait> to terminate the exec prog.
Reset causes the init program to be run.
Cancel normally causes no program to run but drops the dialog and all of its children. By executing the expression
<add_option,Cancel_Prog,my_cancel
>
you can cause the prog my_cancel to be run on Cancel before the dialog is dropped. The window manager Close button is equivalent to Cancel.
The Help button causes a help window to be brought up with the help topic named DL+name of dialog. Running
<add_option,help_topic,my_help
>
will cause my_help to be used (instead of the dialog name) in the help topic.
Dialog Arguments
Each dialog window is passed an argument vector when it is created. The arguments are accessed through the dlisp arg primitive function. The common arguments for all dialogs are:
<arg,1> Context (working directory)
The <arg,3> is usually (by convention) a series of names that the dialog is to operate on.
Popup MenusTo define a popup menu, the syntax is:
domain-body (series of values each terminated by a newline)
range-body (series of values each terminated by a newline, same number of lines as domain))
The identifier name is the name of the popup. The names history, navigate, and completion are reserved.
Each of the series of values is an expression in the string language described in The String Language,
%range and its body are optional. If absent, the domain values are used as the range. Each value in the %domain and %range must be terminated with a newline character.
When a popup menu is to be displayed, the domain is evaluated and each value is used as a label in the popup menu. The current limit is 128 items. When an entry is selected in a popup menu, the range is evaluated and the value that corresponds to the domain entry selected is used as the value selected.
The association of a popup menu with the button widget that triggers the popup and the text widget that receives the selected value is defined through the popup primitive function described in Popup Menu Set Up.
The String LanguageThe bodies of dialog progs, functions, and popups are programmed in the dlisp string language. This language is LISP-like over the domain of strings. A string language expression consists of a series of literal characters and/or primitive function calls.
The evaluation of a primitive function results in a string. Characters appearing outside of a primitive function are treated as literals and concatenated into the result so that the result of evaluating an expression is also a string.
Primitive functions invoked may have side-effects and often, the final result string is not of interest.
Lexical Rules
Tab and newline characters are ignored, The character "#" begins a comment which extends to the end of the line. Comments are ignored.
Multiple adjacent blanks (" ") are replaced with a single blank. Note that spaces are significant in many circumstances within a dlisp expression. However, to make the documentation below easier to read, spaces have been inserted after commas in the argument lists. These spaces should not be supplied in actual dlisp programs.
The representations "\n" for a new-line, "\t" for a tab, and "\ " for a blank are not ignored and are included in the result.
Syntax and Semantics
Each input character, except those noted above and the character "<", stands for itself. The character "<" begins a primitive function call which has the syntax
<function_name
,arg1
,arg2
, ... >
where function_name is an identifier (the name of the primitive function) and arg1, arg2, ... are argument expressions. With a few exceptions, arguments are always evaluated. Most primitive functions take a fixed, known number of arguments. If fewer than required arguments are supplied, the missing argument values are the null string (""). If more than required arguments are supplied, the extras are not evaluated. This is one exception to the rule that all arguments are evaluated; the other exceptions are the conditional primitive functions cond, while, and for, see Primitive Functions).
Execution Context
Each %prog, %function, %popup and primitive function is executed in the context of some specific dialog window called the current dialog. Associated with the current dialog are widgets, arguments, local variables, and children.
Widget Identification
The arguments of certain dlisp primitive functions (for example. setw) reference widgets in the current dialog. A widget is identified using the widget_name specified in the widget's definition. The children of a composite widget are identified using the syntax:
parent_name
*child_name
where parent_name is the name of the root widget of the composite widget and child_name is the name of the child to be accessed. When a child_name is unique within the dialog, qualification with the parent_name may be omitted.
Dialog Arguments
Each dialog has an argument vector and some dlisp primitive functions (e.g. arg) refer to that vector. The argument vector is initialized when the dialog window is created and persists until it is dropped.
Local Variables
Each dialog window has a list of local variables and associated values which are created and modified via the dlisp set primitive function. The names of local variables are identifiers and the values are arbitrary strings which persist as long as dialog window exists. However, all local variables are discarded when the dialog's Reset button is activated (before the init prog is invoked).
Child Dialogs
If a dialog is created by a dlisp action, it will be a child of the current dialog. When the current dialog is discarded, any existing children are also discarded.
Data Representation
All dlisp values are strings. Numeric values (integers) are represented in decimal notation.
The null string is the empty string (no characters). The term null is sometimes used in place of null string.
A string is interpreted as a boolean value as follows:
true: any non-null string (for example. true) except false.
false: the null string or the string false,
Primitive functions which return a boolean value return:
true: when the result is true, and
null string: when the result is false.
Primitive Functions
The following subsections describe the available dlisp primitive functions, organized by purpose. Spaces shown after commas (",") in the syntax descriptions below should generally not be included in actual invocations because they would be interpreted as part of the argument's string value.
Widget Manipulation
Return the value of widget W. For text, list or label widgets return the contents. Toggle buttons return true or the null string indicating false.
Return the part of the value of widget W that is selected. Applies mainly to text or list widgets.
Same as <qualify,expand_name,valw,W,arg,1>
Set the value of widget W to V. Special case: If W is a toggle button and V starts with a "–", the label is set rather than the value.
Replace the selection in the widget W with V. If selection is empty, then do nothing. Intended for text and list widgets.
Append the value V to W. Usually used with list widgets.
Select those items in the value of the list widget W that match values in V. Values in V must be separated by new-line characters. The prior selection is de-selected first.
Remove selected items in the list widget W.
Make B the default button of widget W.
Change to "watch" cursor in dialog.
Change to "normal" cursor in dialog.
Set the menu items in the options menu W to V. An item in V beginning with * is displayed gray and is insensitive (the * is not displayed). The current selection is set to the first item.
Move cursor of widget W to the end of the line.
Move cursor of widget W to the beginning of the line.
Map (make visible) widget W. If W is null, map the top level widget of the associated dialog.
Unmap (make invisible) widget W If W is null, unmap the top level widget of the associated dialog.
Set sensitivity of widget W to B (a boolean value). Insensitive widgets generate no callbacks in response to user actions and are displayed in gray tones.
Set keyboard input focus to widget W.
Setup a callback so that prog is called whenever widget W is activated.
Initialize widget W to a dialog option with the name K, if any. If none, use value of the environment variable $APEX_K (with K made uppercase). If not defined, use S. If S is omitted, leave W unchanged.
Harvest history information from the text widget W. Only has an effect if the dialog has defined a history popup with W as the associated text target widget. History information is gathered automatically when the Apply or Ok button is used.
<xres, W, S>
Variables
<val, Var>Return value of the variable Var. Return null string if Var is undefined.
<set, Var, Val>Set the value of a local variable Var to the value Val. Local variable lifetime is the life of the dialog or until Reset is pressed. Local variables are not shared between dialogs nor executions of the same dialog. They are local to a dialog window.
<setg, Var, Val>Set the value of a global variable Var to the value Val. Global variables are shared by all dialogs.
<defined, Var>Return True is Var is defined.
<assign, Var, op, value>Perform the C assignment op ++, --, +=, -=, *=, or /=. The value must be numeric.
<wordlist, args>Construct a wordlist from args.
<count, Var>Count the items in a wordlist Var.
<shift, Var> <element, Var, index>Return Var[index] where Var is a wordlist.
<element_assign, Var, index, value>Set Var[index] to value where Var is a wordlist.
String Manipulation
Return S enclosed in quotes and escape any internal quotes.
If As_Names is false, return S with lines joined and separated by blanks. If As_Names is true, return S with lines joined and separated by commas (,) and the whole string enclosed in braces ({}).
Return true if L = R. opt is unimplemented. Always uses a case-less compare.
Return true if L != R. Always uses a case-less compare.
Return S with leading/trailing blanks and newlines removed.
Return the nth token of S. The first token is 1. If n is 0, then return S. Tokens are sub-strings without blanks separated by blanks or commas. Return the null string if no nth token.
Return a string that is F with suffix S. Don't add if F already has suffix S, else do.
Return the 1st token of S. Deals with quoted tokens.
Return value of S with the 1st token removed. Deals with quoted tokens.
Character of S at index I (0-based).
Substring of S starting at I (0-based) for L chars.
Locate S within V (0-based) starting at 0 or I if given.
Locate S within V (0-based) starting at the end or at I if given, searching backwards. Locate any character of S within V (0-based) starting at 0 or I if given.<reverse_locate_any, S, V [,I]>
Locate any character of S within V (0-based) starting at the end or at I if given, searching backwards.
Return a list that is a subset of L1 formed by removing any elements present in L2. The value returned may be equal to L1 or null or in between. Each element is separated by a new-line character.
RC is a string consisting of zero or more lines each of which has zero or more tokens. find_row searches for a line with the token at col# (1-based) = key and returns it. Returns null string if not found.
RC is as in find_row. Return a string with an equal number of lines but with only token col# (1-based) from the corresponding line in RC on it.
<replace_column, RC, col#, token>
RC is as in find_row. Return a string with an equal number of lines but with token col# (1-based) replaced with the given token.
Arithmetic, Relational and Boolean Operations
Sum of the given numeric arguments.
Difference of the given numeric arguments
Product of the given numeric arguments
Quotient of the given numeric arguments
Mod the given numeric arguments
V1 <= V2. Arguments must be integers.
V1 < V2. Arguments must be integers.
V1 >= V2. Arguments must be integers.
V1 > V2. Arguments must be integers.
Boolean AND of the given arguments.
Boolean OR of the given arguments.
Boolean NOT of the given argument.
Control Flow and Parameter Passing
If V is true evaluate T else evaluate F. This is a special case where only one of T or F is evaluated.
While test is true evaluate stmt repeatedly.
Evaluate init once, then, while test is true, evaluate stmt repeatedly. last is evaluated at the end of each iteration before the test is checked.
Break out of the innermost containing loop.
Continue the innermost containing loop.
Return the dialog argument with index I, Return a null string if I out-of-range. <arg,0> returns the title.
Return the values of the dialog arguments with index I through J separated by blanks. Return null string if I out-of-range. If J is out of range, stop at the end of the physical argument list.
Return all arguments from argument I to the end of the list separated by blanks. Return null string if I out-of-range.
Call the %prog or %function named prog with the specified args.
Return the value of call parameter I (0-based) of a prog or function. Error if I >= number of parameters.
Return the number of parameters in the current call.
Return from a function or prog with an optional value.
Terminate program with success indication.
Terminate program with optional error indication S (default is " ", a non-empty error condition).
Sub-Dialogs and Dialog Control
Display a message dialog with the message S.
Start a child dialog. The key is for aliasing. The name and args form the child dialog's arguments.
<dialog_wait, key, name, args ...>
Start a child dialog. The key is for aliasing. The name and args form the dialog's arguments. Execution of this dialog is suspended until the child dialog returns a value. That value is returned from this operation when it continues.
Return the alias key for the current dialog.
Return the window handle for the current dialog.
Return the alias key for the parent dialog.
Return the name of a child dialog if it's a child.
<dialog_call, key, name, args ...>
The key is a dialog's window handle, name is a prog name within that dialog. Call that prog with the given args. The call executes in the context of the called dialog and returns the prog's return value.
Cancel the current dialog. The dialog and any children are popped down and the dialogs recycled. Execution terminates.
Suspend execution and wait for a message. Return the message when execution continues. Generally shows a busy cursor in the interim.
Send a message to the dialog with alias key dest. If the dialog is not waiting, the message is lost. If dest is null, send to parent.
Return true if opt (or <arg,2> when opt is null) contains –key or +key.
Return the value of the option with the name key. Use <arg,2> when opt is null. The option
–key returns true,
+key returns false, and
–key value returns value.
Otherwise, return the null string.Add an option called name to the current dialog with the given value. Replace any existing option with the same name. Resetting the dialog does not remove this option change.
Return the current context (working directory) of the current dialog.
Set the context of the current dialog to path. Also set the value of <arg,1> to path.
UNIX and Apex/Summit API
Execute command line S. If the command name is apex_display it will be interpreted (unless overridden).
If wait is given and a process is forked the variable status will be set to the exit status. If wait is not given and a process is forked, execute_pid will be the process id.
Execute the UNIX command S, wait for completion, and return the standard output as a result. The command S is run through a csh shell. Be very careful not to run long commands or commands that might hang: they will keep the entire server busy or hung while they run. Output sent to standard error will probably end up in the dialog server log file in /tmp.
<perform, operation, arguments, editor, context, window_to_notify>
Do the editor operation operation with arguments arguments in editor editor. The context is the directory context in which to do the operation, and window_to_notify is the window handle to which a completion message should be sent (usually <alias_key>).
<query, operation, arguments, editor, context, max_wait>
Return value of the switch name in the view context (from context/Policy/Switches).
Return the name of the containing subsystem of path F.
Return the name of the containing view of path F.
Return the list of histories of the named subsystem SS. One per line.
Return the field F of the current project.
Load the current project with the list of files P.
Return property of P of view V. P is one of imports, storage_location, export_sets, default_history, model, release_kind, or histories.
Return property P of file F. P is one of controlled, checked_in, private_check_out, version, latest_version, history, length, or permanent_name (which actually applies to a directory, and returns the nearest enclosing permanently-named directory).
Print message S to an output window.
True if and only if S is legal for kind where kind is one of number, file, view, subsystem, version, directory, subsystem_or_view, configuration, or history. The context is used only for kind history, in which case it names a subsystem in which the history must exist.
<check, value, kind, null_message, part_illegal_message, multiple_message>
Check that value is legal for kind. If not, display a message dialog with null_message if non-null and value is null, or part_illegal_message if some or all of value is not legal, or multiple_message if non-null and there are multiple values in value. Fail after displaying a message. If the kind is not one of those mentioned for the function legal above, it is assumed to be a boolean function or prog which returns true when applied to a legal item in value and false otherwise.
Note: Cannot be used with kind history because there is no context parameter.
Return S with wild-cards, "~", and environment variables expanded.
Return a fully qualified version of name using context if needed.
Return directory name of pathname
Return pathname without extension.
<exists, pathname>
<is_directory, pathname>
<is_executable, pathname>
<is_file, pathname>
<is_link, pathnamee>
<is_subsystem, pathname>
<is_view, pathname>
<is_writable, pathname>Return the boolean result of the indicated test on pathname.
Return current working directory.
Change current working directory to pathname.
Return canonical (full) path of pathname.
<tempname[, prefix[, context]]>
Generate a temporary filename and return it, using the given prefix and the directory context, if specified.
<directory, dir, pattern, qualify>
Return, one per line, file names in directory dir matching pattern, fully qualified, if qualify is true.
Set the contents of file F to value.
Return the value of environment variable V.
Set environment V to E. in the current server's environment.
Popup Menu Set Up
<popup, class, button, target, prg, history, locator_target>
<popup, class, button, target, additive>Register the given button widget as a button for a popup menu. The class must name a popup menu declared in a %popup declaration. The target is the widget to receive the selected value. If additive is true, selected values are appended to the value of target.
<popup, navigate, button, target, prg, , locator_target>
Special case with class = navigate. Register the navigator button button. The prg is run to invoke a locator dialog. locator_target is the widget to receive locator results (can set = target)
<popup, completion, button, target, context_function>
Special case with class = completion. Register the given file name completion button. The context_function returns the directory to be used. The dialog context is used if context_function is null.
<popup, history, button, target, history>
Special case with class = history. Register the given history button. The history parameter is the name of the history to be associated with the button and target is the text widget to receive selected values.
Miscellaneous
Do a special operation, op where op is one of the following:
Run filter. Only valid in file locator dialogs.
Return list of unsaved windows. Each line has the form alias_key editor_name server_instance
Turn trace mode on or off according to the boolean value of mode (true or false).
Turn test mode on or off according to the boolean value of mode (true or false).
Return a list of existing debuggers.
<action, get_session_list>
<action, get_user_session_list>Return a list of all, or just user-defined, sessions.
Return true if the Ada product is enabled.
Return true if the C++ product is enabled.
Return true if only the Ada product is enabled.
Return true if only the C++ product is enabled.
Return true if the Summit/TM product is enabled.
Debugging Dlisp Actions
Dialog actions written in dlisp can be debugged through Apex or Summit tracing features. Most bugs can be readily found by turning on tracing, sending the trace output to a file, and then examining that file with an editor. Alternatively, the trace output may be directed to an xterm window.
The command for controlling tracing is
apex_displaytrace_option
dialog [stdout]
where trace_option is one of the following:
trace trace dlisp execution.
trace_all trace dlisp execution and control flow.
trace_off turn tracing off.
The stdout option causes the dlisp trace output to be sent to the standard output of the Dialog Server. Otherwise, the trace output is sent to the Message Window. It is usually best to specify the stdout option since output to the Message Window may be slow.
Normally, the standard output of the Dialog Server is directed to a log file in the /tmp directory with the name
user
_Apex_Dialog_Server_log
where user is your user name. The standard output can be redirected to another destination using the command
apex_display -editor dialog create_logdest
where dest is one of the following:
For example, to trace the execution of a dialog, you can perform the following steps:
- 1 . Type the command
apex_display trace_all dialog stdout
to enable dlisp tracing and send the trace messages to standard output of the Dialog Server.
- 2 . Type the command
apex_display -editor dialog create_log ~/log
to direct trace output to the file called log in your home directory.
- 3 . Display and exercise the dialog being debugged.
- 4 . Examine the contents of ~/log with an editor.
Tracing can be turned off at any time (via the trace_off option) and then turned back on again later. It is not necessary to redirect the output each time tracing is turned on.
The information written to the log file traces the execution of the dlisp code in detail. Sending the trace output to a file is recommended because the trace output can be voluminous. Using a text editor, you can quickly locate the portions of the dlisp execution that are not working correctly.
The following are handy csh alias definitions for controlling dialog tracing:
alias tron 'apex_display trace_all dialog stdout'
alias troff 'apex_display trace_off dialog'
alias trlog 'apex_display -editor dialog\
create_log \!*'
The trace output includes warnings and sometimes error messages that are not normally output by Apex or Summit (except to the log file). Some warnings report harmless conditions. For example, a dialog which does not have a %prog build will produce a warning message when the dialog is first displayed because an attempt is made to invoke build. On the other hand, a dlisp call to a function that does not exist or whose name was incorrectly typed will produce that same sort of warning message in the trace output. When you are debugging a new or modified dialog, it is helpful to exercise the dialog with tracing turned on and then examine the trace for any errors that may have occurred.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |