User Commands dtksh(1) NAME dtksh - shell command language interpreter with access to many X, Xt, Xm and CDE functions SYNOPSIS dtksh [-abCefimnuvx] [-o _o_p_t_i_o_n] [+abCefmnuvx] [+o _o_p_t_i_o_n] [_c_o_m_m_a_n_d__f_i_l_e [_a_r_g_u_m_e_n_t...]] dtksh [-abCefimnuvx] [-o _o_p_t_i_o_n] [+abCefmnuvx] [+o _o_p_t_i_o_n] _c_o_m_m_a_n_d__s_t_r_i_n_g [_c_o_m_m_a_n_d__n_a_m_e [_a_r_g_u_m_e_n_t...]] dtksh -s [-abCefimnuvx] [-o _o_p_t_i_o_n] [+abeCefmnuvx] [+o _o_p_t_i_o_n] [_a_r_g_u_m_e_n_t...]] DESCRIPTION The dtksh utility is a version of the KornShell extended to support: +o Access to many X, Xt and Motif facilities from within a shell script +o Fully localized shell scripts +o Access to the CDE application help system +o Customization of script-based GUI attributes (such as font and colors) using the CDE customization tool +o Response to session-management Save state directives +o Response to window-management Close directives +o Access to most of the CDE Desktop Services Message Set +o Access to many of the CDE Data Typing API functions +o Access to the CDE Action API functions OPTIONS See ksh93(1). OPERANDS See ksh93(1). RESOURCES The dtksh interpreter has no relevant resources outside of those that affect the various widgets that can be instan- tiated from within a dtksh script. Refer to the manual page of the relevant widget for information on the resources that apply to that widget. SunOS 5.10 Last change: 15 Jul 1994 1 User Commands dtksh(1) STDIN See ksh93(1). INPUT FILES See ksh93(1). ENVIRONMENT VARIABLES The following information describes the environment vari- ables that dtksh uses that are in addition to those docu- mented in the manual page for the sh command language inter- preter. Immediate Return Value (-) Many of the category 3 commands (as described in the Return Values From Built-in Commands section) return a single value using an environment variable specified as the first argu- ment to the command (in the synopses for these special com- mands, the first argument has the name _v_a_r_i_a_b_l_e). If this return value is immediately used in an expression, the spe- cial environment variable ``-'' can be used in place of a variable name. When dtksh encounters ``-'' as the name of the environment variable in which the return value is to be returned, it returns the result as the value of the command. This allows the shell script to embed the command call in another command call. (This feature works only for commands that return a single value; the value is the first argument and the argument has the name _v_a_r_i_a_b_l_e). For example: XtDisplay DISPLAY $FORM XSync $DISPLAY true can be replaced by the equivalent: XSync $(XtDisplay "-" $FORM) true The reference to $_D_I_S_P_L_A_Y is replaced with the value returned by the call to XtDisplay. This capability is available for all category 3 commands except those that create a widget, those that return more than a single value and those whose first argument is not named _v_a_r_i_a_b_l_e. Com- mands that do not accept ``-'' as the environment variable name include: XtInitialize, XtCreateApplicationShell, XtCreatePopupShell, XtCreateManagedWidget and XtCreateWidget; all commands of the form: XmCreate...() and most commands of the form: tt_...() SunOS 5.10 Last change: 15 Jul 1994 2 User Commands dtksh(1) Variables Set By XtInitialize The XtInitialize command sets the following variables: _D_T_K_S_H__A_P_P_N_A_M_E _D_T_K_S_H__A_R_G_V _D_T_K_S_H__T_O_P_L_E_V_E_L Callback Context Variables An application registers a callback with a widget to specify which condition it is interested in, and what action should occur when that condition occurs. The action can be any arbitrary dtksh command line. For example: XtAddCallback $WIDGET activateCallback "ActivateProc" XtAddCallback $WIDGET activateCallback "XtSetSensitive $BUTTON false" A callback needs to be passed some context so it can deter- mine what condition led to its call. For a C procedure, this information is typically passed in a _c_a_l_l__d_a_t_a struc- ture. For example, a Scale widget invoking a valueChanged- Callback passes in _c_a_l_l__d_a_t_a an instance of the following structure: typedef struct { int reason; XEvent *event; int value; } XmScaleCallbackStruct; The C application's callback does something like: if (scaleCallData->reason == XmCR_VALUE_CHANGED) { eventType = scaleCallData->event->type; display = scaleCallData->event->xany.display; } Similarly in dtksh, when a callback is invoked, the follow- ing special environment variables are set up before the callback command executes: _C_B__W_I_D_G_E_T Set to the widget handle for the widget invoking the callback. _C_B__C_A_L_L__D_A_T_A Set to the address of the _c_a_l_l__d_a_t_a structure passed by the widget to the callback, but its use- fulness lies in the nested sub-variables associated with it. The _C_B__C_A_L_L__D_A_T_A environment variable represents a pointer to a structure; access to its fields uses a syntax similar SunOS 5.10 Last change: 15 Jul 1994 3 User Commands dtksh(1) to the C code. Nested environment variables are defined, named the same as the fields of the structure (but folded to all upper case), and use a dot to indicate containment of an element in a structure. Thus, the preceding C code, to access the _c_a_l_l__d_a_t_a provided by the Scale widget, translates to: if [${CB_CALL_DATA.REASON} = "CR_VALUE_CHANGED"]; then eventType=${CB_CALL_DATA.EVENT.TYPE} display=${CB_CALL_DATA.EVENT.XANY.DISPLAY} fi The same is true of the event structure within the _c_a_l_l__d_a_t_a structure. For most callback structures, the shell script is able to reference any of the fields defined for the particular call- back structure, using the technique previously described in this manual page. In most cases, the shell script is not able to alter the values of the fields within these struc- tures. The exception to this is the _X_m_T_e_x_t_V_e_r_i_f_y_C_a_l_l_b_a_c_k_- _S_t_r_u_c_t, available during the _l_o_s_i_n_g_F_o_c_u_s_C_a_l_l_b_a_c_k, the _m_o_d_i_f_y_V_e_r_i_f_y_C_a_l_l_b_a_c_k and the _m_o_t_i_o_n_V_e_r_i_f_y_C_a_l_l_b_a_c_k for the text widget. The dtksh utility supports the modification of certain fields within this structure, to the extent that it is supported by Motif. The following fields within the callback structure can be modified: _C_B__C_A_L_L__D_A_T_A._D_O_I_T _C_B__C_A_L_L__D_A_T_A._S_T_A_R_T_P_O_S _C_B__C_A_L_L__D_A_T_A._E_N_D_P_O_S _C_B__C_A_L_L__D_A_T_A._T_E_X_T._P_T_R _C_B__C_A_L_L__D_A_T_A._T_E_X_T._L_E_N_G_T_H _C_B__C_A_L_L__D_A_T_A._T_E_X_T._F_O_R_M_A_T An example of how these fields can be modified: CB_CALL_DATA.DOIT="false" CB_CALL_DATA.TEXT.PTR="*" CB_CALL_DATA.TEXT.LENGTH=1 Event Handler Context Variables As with callbacks, an application registers event handlers with a widget to specify what action should occur when one of the specified events occurs. Again, the action can be any arbitrary dtksh command line. For example: XtAddEventHandler $W "Button2MotionMask" false "ActivateProc" XtAddEventHandler $W "ButtonPressMask|ButtonReleaseMask" \ false "echo action" SunOS 5.10 Last change: 15 Jul 1994 4 User Commands dtksh(1) Just as with callbacks, two environment variables are defined to provide context to the event handler: _E_H__W_I_D_G_E_T Set to the widget handle for the widget for which the event handler is registered. _E_H__E_V_E_N_T Set to the address of the XEvent that triggered the event handler. Access to the fields within the XEvent structure is the same as for the _C_B__C_A_L_L__D_A_T_A environment variable previously described in this manual page. For example: if [${EH_EVENT.TYPE} = "ButtonPress"]; then echo X = ${EH_EVENT.XBUTTON.X} echo Y = ${EH_EVENT.XBUTTON.Y} elif [${EH_EVENT.TYPE} = "KeyPress"]; then echo X = ${EH_EVENT.XKEY.X} echo Y = ${EH_EVENT.XKEY.Y} fi Translation Context Variables Xt provides for event translations to be registered for a widget; their context is provided in the same way as with event handlers. The two variables defined for translation commands are: _T_R_A_N_S_L_A_T_I_O_N__W_I_D_G_E_T Set to the widget handle for the widget for which the translation is registered. _T_R_A_N_S_L_A_T_I_O_N__E_V_E_N_T Set to the address of the XEvent that triggered the translation. Dot-notation provides access to the fields of the event: echo Event type = ${TRANSLATION_EVENT.TYPE} echo Display = ${TRANSLATION_EVENT.XANY.DISPLAY} Workspace Callback Context Variables An application can register a callback function that is invoked any time the user changes to a new workspace. When the callback is invoked, the following two special environ- ment variables are set, and can be accessed by the shell callback code: _C_B__W_I_D_G_E_T Set to the widget handle for the widget invoking the callback. SunOS 5.10 Last change: 15 Jul 1994 5 User Commands dtksh(1) _C_B__C_A_L_L__D_A_T_A Set to the X atom that uniquely identifies the new workspace. This can be converted to its string representation using the XmGetAtomName command. Accessing Event Subfields The XEvent structure has many different configurations based on the event's type. The dtksh utility provides access only to the most frequently used XEvents. Any of the other stan- dard XEvents are accessed using the event type XANY, fol- lowed by any of the subfields defined by the XANY event structure, which includes the following subfields: ${TRANSLATION_EVENT.XANY.TYPE} ${TRANSLATION_EVENT.XANY.SERIAL} ${TRANSLATION_EVENT.XANY.SEND_EVENT} ${TRANSLATION_EVENT.XANY.DISPLAY} ${TRANSLATION_EVENT.XANY.WINDOW} The dtksh utility supports full access to all of the event fields for the following event types: XANY XBUTTON XEXPOSE XNOEXPOSE XGRAPHICSEXPOSE XKEY XMOTION The following examples show how the subfields for the previ- ously listed event types are accessed: ${TRANSLATION_EVENT.XBUTTON.X} $(CB_CALL_DATA.EVENT.XKEY.STATE} ${EH_EVENT.XGRAPHICSEXPOSE.WIDTH} Input Context Variables Xt provides the XtAddInput(3X) facility that allows an application to register interest in activity on a particular file descriptor. This generally includes data available for reading, the file descriptor being ready for writing, and exceptions on the file descriptor. If programming in C, the application provides a handler function that is invoked when the activity occurs. When reading data from the file descriptor, it is up to the handler to read the data from the input source and handle character escaping and line con- tinuations. The dtksh utility also supports the XtAddInput(3X) facility, but has limited its functionality to reading data, and has taken the reading function a step further to make it easier SunOS 5.10 Last change: 15 Jul 1994 6 User Commands dtksh(1) for shell programmers to use. By default, when a shell script registers interest in a file descriptor, dtksh invokes the shell script's input handler only when a com- plete line of text has been received. A complete line of text is defined to be a line terminated either by an unes- caped character, or by end-of-file. The input handler is also called if no data is available and end-of- file is reached. This gives the handler the opportunity to use XtRemoveInput(3X) to remove the input source, and to close the file descriptor. The advantage of this default behavior is that input handlers do not need to do escape processing or handle line continuations. The disadvantage is that it assumes that all of the input is line-oriented and contains no binary infor- mation. If the input source does contain binary informa- tion, or if the input handler wants to read the data from the input source directly, dtksh also supports a raw input mode. In raw mode, dtksh does not read any of the data from the input source. Any time dtksh is notified that input is available on the input source, it invokes the shell script's input handler. It then becomes the handler's responsibility to read the incoming data, to perform any required buffering and escape processing, and to detect when end-of-file is reached (so that the input source can be removed and the file descriptor closed). Whether the input handler is configured to operate in the default mode or in raw mode, dtksh sets up several environ- ment variables before calling the shell script's input handler. These environment variables provide the input handler with everything needed to handle the incoming data: _I_N_P_U_T__L_I_N_E If operating in the default mode, this variable contains the next complete line of input available from the input source. If _I_N_P_U_T__E_O_F is set to True, there is no data in this buffer. If operat- ing in raw mode, this environment variable always contains an empty string. _I_N_P_U_T__E_O_F If operating in the default mode, this variable is set to False any time _I_N_P_U_T__L_I_N_E contains data, and is set to True when end-of-file is reached. When end-of-file is reached, the input handler for the shell script should unregister the input source and close the file descriptor. If operating in raw mode, _I_N_P_U_T__E_O_F is always set to False. _I_N_P_U_T__S_O_U_R_C_E Indicates the file descriptor for which input is SunOS 5.10 Last change: 15 Jul 1994 7 User Commands dtksh(1) available. If operating in raw mode, this file descriptor is used to obtain the pending input. The file descriptor is also used to close the input source when it is no longer needed. _I_N_P_U_T__I_D Indicates the ID returned by XtAddInput when the input source was originally registered. This information is needed in order to remove the input source using XtRemoveInput. ASYNCHRONOUS EVENTS Default. STDOUT See ksh93(1). STDERR See ksh93(1). OUTPUT FILES None. EXTENDED DESCRIPTION The capabilities described here are extensions to those of the sh command language interpreter. See ksh93(1). The following subsections give a synopsis of each of the built- in commands added by dtksh to sh. In general, argument ord- ering and types are the same as for corresponding C pro- cedures, with exceptions noted. For more detail on the functionality and arguments of a command, see the standard documentation for the corresponding X11, Xt, Motif or Desk- top Services procedure. In definitions listed in this document, arguments named _v_a_r_i_a_b_l_e, _v_a_r_i_a_b_l_e_2, _v_a_r_i_a_b_l_e_3 and so on, indicate that the shell script must supply the name of an environment vari- able, into which some value is returned. All of the Xt commands used to create a new widget require that the widget class for the new widget be specified. The widget (or gadget) class name is the standard class name provided by Motif. For example, the class name for a Motif pushbutton widget is _X_m_P_u_s_h_B_u_t_t_o_n, while the class name for the Motif label gadget is _X_m_L_a_b_e_l_G_a_d_g_e_t. Commands that use their exit status to return a Boolean value (which can be used directly as part of an _i_f statement) are noted as such. Arguments enclosed within [] are optional. Dtksh Built-in Xlib Commands XBell _d_i_s_p_l_a_y _v_o_l_u_m_e SunOS 5.10 Last change: 15 Jul 1994 8 User Commands dtksh(1) XClearArea _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x _y _w_i_d_t_h _h_e_i_g_h_t _e_x_p_o_s_u_r_e_s XClearWindow _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e XCopyArea _d_i_s_p_l_a_y _s_r_c _d_e_s_t _s_r_c_X _s_r_c_Y _w_i_d_t_h _h_e_i_g_h_t _d_e_s_t_X _d_e_s_t_Y [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] XDefineCursor _d_i_s_p_l_a_y _w_i_n_d_o_w _c_u_r_s_o_r XDrawArc _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x _y _w_i_d_t_h _h_e_i_g_h_t _a_n_g_l_e_1 _a_n_g_l_e_2 XDrawLine _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x_1 _y_1 _x_2 _y_2 XDrawLines _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [-_c_o_o_r_d_i_n_a_t_e_M_o_d_e] [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x_1 _y_1 _x_2 _y_2 [_x_3 _y_3 ...] The _c_o_o_r_d_i_n_a_t_e_M_o_d_e operand is either CoordModeOrigin or CoordModePrevious. XDrawPoint _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x _y XDrawPoints _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [-_c_o_o_r_d_i_n_a_t_e_M_o_d_e] [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x_1 _y_1 [_x_2 _y_2 _x_3 _y_3 ...] The _c_o_o_r_d_i_n_a_t_e_M_o_d_e operand is either CoordModeOrigin or CoordModePrevious. XDrawRectangle _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x _y _w_i_d_t_h _h_e_i_g_h_t XDrawSegments _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x_1 _y_1 _x_2 _y_2 [_x_3 _y_3 _x_4 _y_4 ...] XDrawString _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x _y _s_t_r_i_n_g XDrawImageString _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x _y _s_t_r_i_n_g XFillArc _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x _y _w_i_d_t_h _h_e_i_g_h_t _a_n_g_l_e_1 _a_n_g_l_e_2 XFillPolygon _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [-_s_h_a_p_e] [-_c_o_o_r_d_i_n_a_t_e_M_o_d_e] [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x_1 _y_1 _x_2 _y_2 ... The _s_h_a_p_e operand is one of Complex, Convex or Nonconvex, and where _c_o_o_r_d_i_n_a_t_e_M_o_d_e is either CoordModeOrigin or CoordModePrevious. SunOS 5.10 Last change: 15 Jul 1994 9 User Commands dtksh(1) XFillRectangle _d_i_s_p_l_a_y _d_r_a_w_a_b_l_e [_o_p_t_i_o_n_a_l _G_C _a_r_g_u_m_e_n_t_s] _x _y _w_i_d_t_h _h_e_i_g_h_t XFlush _d_i_s_p_l_a_y XHeightOfScreen _v_a_r_i_a_b_l_e _s_c_r_e_e_n XRaiseWindow _d_i_s_p_l_a_y _w_i_n_d_o_w XRootWindowOfScreen _v_a_r_i_a_b_l_e _s_c_r_e_e_n XSync _d_i_s_p_l_a_y _d_i_s_c_a_r_d The _d_i_s_c_a_r_d operand is either True or False. XTextWidth _v_a_r_i_a_b_l_e _f_o_n_t_N_a_m_e _s_t_r_i_n_g The XTextWidth command differs from the C procedure; it takes the name of a font instead of a pointer to a font structure. XUndefineCursor _d_i_s_p_l_a_y _w_i_n_d_o_w XWidthOfScreen _v_a_r_i_a_b_l_e _s_c_r_e_e_n Built-in XtIntrinsic Commands XtAddCallback _w_i_d_g_e_t_H_a_n_d_l_e _c_a_l_l_b_a_c_k_N_a_m_e _d_t_k_s_h-_c_o_m_m_a_n_d The _c_a_l_l_b_a_c_k_N_a_m_e operand is one of the standard Motif or Xt callback names, with the Xt or Xm prefix omitted; for example, _a_c_t_i_v_a_t_e_C_a_l_l_b_a_c_k. XtAddEventHandler _w_i_d_g_e_t_H_a_n_d_l_e _e_v_e_n_t_M_a_s_k _n_o_n_M_a_s_k_a_b_l_e_F_l_a_g _d_t_k_s_h-_c_o_m_m_a_n_d The _e_v_e_n_t_M_a_s_k operand is of the form _m_a_s_k|_m_a_s_k|_m_a_s_k and the _m_a_s_k component is any of the standard set of XEvent masks; for example, _B_u_t_t_o_n_P_r_e_s_s_M_a_s_k, where _n_o_n_M_a_s_k_a_- _b_l_e_F_l_a_g is either True or False. XtAddInput _v_a_r_i_a_b_l_e [-_r] _f_i_l_e_D_e_s_c_r_i_p_t_o_r _d_t_k_s_h-_c_o_m_m_a_n_d The XtAddInput command registers the indicated file descriptor with the X Toolkit as an alternative input source (that is, for reading). The input handler for the shell script is responsible for unregistering the input source when it is no longer needed, and also to close the file descriptor. If the -r option is specified (raw mode), dtksh does not automatically read any of the data available from the input source; it is up to the speci- fied dtksh command to read all data. If the -r option is not specified, the specified dtksh command is invoked SunOS 5.10 Last change: 15 Jul 1994 10 User Commands dtksh(1) only when a full line has been read (that is, a line ter- minated by either an unescaped character, or end-of-file) and when end-of-file is reached. The raw mode is useful for handlers expecting to process non- textual data, or for handlers not wanting dtksh to automatically read in a line of data. When end-of-file is detected, it is the responsibility of the input handler for the shell script to use XtRemoveInput to remove the input source, and to close the file descrip- tor, if necessary. In all cases, several environment variables are set up for the handler to use. These include the following: _I_N_P_U_T__L_I_N_E Empty if raw mode; otherwise, contains next line to be processed. _I_N_P_U_T__E_O_F Set to True if end-of-file reached; other- wise, set to False. _I_N_P_U_T__S_O_U_R_C_E File descriptor associated with this input source. _I_N_P_U_T__I_D ID associated with this input handler; returned by XtAddInput. XtAddTimeOut _v_a_r_i_a_b_l_e _i_n_t_e_r_v_a_l _d_t_k_s_h-_c_o_m_m_a_n_d XtAddWorkProc _v_a_r_i_a_b_l_e _d_t_k_s_h-_c_o_m_m_a_n_d In dtksh, the _d_t_k_s_h-_c_o_m_m_a_n_d is typically a dtksh function name. Like regular work procedures, this function is expected to return a value indicating whether the work procedure wants to be called again, or whether it has completed its work and can be automatically unregistered. If the dtksh function returns zero, the work procedure remains registered; any other value causes the work pro- cedure to be automatically unregistered. XtAugmentTranslations _w_i_d_g_e_t_H_a_n_d_l_e _t_r_a_n_s_l_a_t_i_o_n_s XtCreateApplicationShell _v_a_r_i_a_b_l_e _a_p_p_l_i_c_a_t_i_o_n_N_a_m_e _w_i_d_g_e_t_C_l_a_s_s [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XtCallCallbacks _w_i_d_g_e_t_H_a_n_d_l_e _c_a_l_l_b_a_c_k_N_a_m_e The _c_a_l_l_b_a_c_k_N_a_m_e operand is one of the standard Motif or Xt callback names, with the Xt or Xm prefix omitted; for example, _a_c_t_i_v_a_t_e_C_a_l_l_b_a_c_k. SunOS 5.10 Last change: 15 Jul 1994 11 User Commands dtksh(1) XtClass _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e The command returns the name of the widget class associ- ated with the passed-in widget handle. XtCreateManagedWidget _v_a_r_i_a_b_l_e _w_i_d_g_e_t_N_a_m_e _w_i_d_g_e_t_C_l_a_s_s _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XtCreatePopupShell _v_a_r_i_a_b_l_e _w_i_d_g_e_t_N_a_m_e _w_i_d_g_e_t_C_l_a_s_s _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XtCreateWidget _v_a_r_i_a_b_l_e _w_i_d_g_e_t_N_a_m_e _w_i_d_g_e_t_C_l_a_s_s _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XtDestroyWidget _w_i_d_g_e_t_H_a_n_d_l_e [_w_i_d_g_e_t_H_a_n_d_l_e ...] XtDisplay _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XtDisplayOfObject _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XtGetValues _w_i_d_g_e_t_H_a_n_d_l_e _r_e_s_o_u_r_c_e:_v_a_r_i_a_b_l_e_1 [_r_e_s_o_u_r_c_e:_v_a_r_i_a_b_l_e_2 ...] XtHasCallbacks _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _c_a_l_l_b_a_c_k_N_a_m_e The _c_a_l_l_b_a_c_k_N_a_m_e operand is one of the standard Motif or Xt callback names, with the Xt or Xm prefix omitted: for example, _a_c_t_i_v_a_t_e_C_a_l_l_b_a_c_k variable is set to one of the strings CallbackNoList, CallbackHasNone or CallbackHas- Some. XtInitialize _v_a_r_i_a_b_l_e _s_h_e_l_l_N_a_m_e _a_p_p_l_i_c_a_t_i_o_n_C_l_a_s_s_N_a_m_e _a_p_p_l_i_- _c_a_t_i_o_n_N_a_m_e _a_r_g_u_m_e_n_t_s Similar to a typical Motif-based program, the _a_r_g_u_m_e_n_t_s argument is used to reference any command-line arguments that might have been specified by the shell script user; these are typically referred using the shell syntax of $@. The _a_p_p_l_i_c_a_t_i_o_n_N_a_m_e argument is listed because $@ does not include $_0. The _a_p_p_l_i_c_a_t_i_o_n_N_a_m_e and _a_r_g_u_m_e_n_t_s are used to build the argument list passed to the XtIni- tialize command. Upon completion, the environment vari- able _D_T_K_S_H__A_R_G_V is set to the argument list as returned by the XtInitialize command; the _D_T_K_S_H__T_O_P_L_E_V_E_L environ- ment variable is set to the widget handle of the widget created by XtInitialize, and the _D_T_K_S_H__A_P_P_N_A_M_E environ- ment variable is set to the value of the _a_p_p_l_i_c_a_t_i_o_n_N_a_m_e argument. The command returns a value that can be used in a conditional. XtIsManaged _w_i_d_g_e_t_H_a_n_d_l_e SunOS 5.10 Last change: 15 Jul 1994 12 User Commands dtksh(1) The command returns a value that can be used in a condi- tional. XtIsSubclass _w_i_d_g_e_t_H_a_n_d_l_e _w_i_d_g_e_t_C_l_a_s_s The _w_i_d_g_e_t_C_l_a_s_s operand is the name of a widget class. The command returns a value that can be used in a condi- tional. XtNameToWidget _v_a_r_i_a_b_l_e _r_e_f_e_r_e_n_c_e_W_i_d_g_e_t _n_a_m_e XtIsRealized _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XtIsSensitive _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XtIsShell _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XtLastTimestampProcessed _v_a_r_i_a_b_l_e _d_i_s_p_l_a_y XtMainLoop XtManageChild _w_i_d_g_e_t_H_a_n_d_l_e XtManageChildren _w_i_d_g_e_t_H_a_n_d_l_e [_w_i_d_g_e_t_H_a_n_d_l_e ...] XtMapWidget _w_i_d_g_e_t_H_a_n_d_l_e XtOverrideTranslations _w_i_d_g_e_t_H_a_n_d_l_e _t_r_a_n_s_l_a_t_i_o_n_s XtParent _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XtPopdown _w_i_d_g_e_t_H_a_n_d_l_e XtPopup _w_i_d_g_e_t_H_a_n_d_l_e _g_r_a_b_T_y_p_e The _g_r_a_b_T_y_p_e operand is one of the strings GrabNone, GrabNonexclusive or GrabExclusive. XtRealizeWidget _w_i_d_g_e_t_H_a_n_d_l_e XtRemoveAllCallbacks _w_i_d_g_e_t_H_a_n_d_l_e _c_a_l_l_b_a_c_k_N_a_m_e SunOS 5.10 Last change: 15 Jul 1994 13 User Commands dtksh(1) The _c_a_l_l_b_a_c_k_N_a_m_e operand is one of the standard Motif or Xt callback names, with the Xt or Xm prefix omitted; for example, _a_c_t_i_v_a_t_e_C_a_l_l_b_a_c_k. XtRemoveCallback _w_i_d_g_e_t_H_a_n_d_l_e _c_a_l_l_b_a_c_k_N_a_m_e _d_t_k_s_h-_c_o_m_m_a_n_d The _c_a_l_l_b_a_c_k_N_a_m_e operand is one of the standard Motif or Xt callback names, with the Xt or Xm prefix omitted; for example, _a_c_t_i_v_a_t_e_C_a_l_l_b_a_c_k. As with traditional Xt call- backs, when a callback is removed, the same dtksh command string must be specified as was specified when the call- back was originally registered. XtRemoveEventHandler _w_i_d_g_e_t_H_a_n_d_l_e _e_v_e_n_t_M_a_s_k _n_o_n_M_a_s_k_a_b_l_e_F_l_a_g _d_t_k_s_h-_c_o_m_m_a_n_d The _e_v_e_n_t_M_a_s_k operand is of the form _m_a_s_k|_m_a_s_k|_m_a_s_k and the _m_a_s_k component is any of the standard set of XEvent masks; for example, _B_u_t_t_o_n_P_r_e_s_s_M_a_s_k, where _n_o_n_M_a_s_k_a_- _b_l_e_F_l_a_g is either True or False. As with traditional Xt event handlers, when an event handler is removed, the same _e_v_e_n_t_M_a_s_k, _n_o_n_M_a_s_k_a_b_l_e_F_l_a_g setting and dtksh command string must be specified as was specified when the event handler was originally registered. XtRemoveInput _i_n_p_u_t_I_d The _i_n_p_u_t_I_d operand is the handle returned in the speci- fied environment variable when the alternative input source was registered using the XtAddInput command. XtRemoveTimeOut _t_i_m_e_o_u_t_I_d The _t_i_m_e_o_u_t_I_d operand is the handle returned in the specified environment variable when the timeout was registered using the XtAddTimeOut command. XtRemoveWorkProc _w_o_r_k_p_r_o_c_I_d The _w_o_r_k_p_r_o_c_I_d operand is the handle returned in the specified environment variable when the work procedure was registered using the XtAddWorkProc command. XtScreen _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XtSetSensitive _w_i_d_g_e_t_H_a_n_d_l_e _s_t_a_t_e The _s_t_a_t_e operand is either True or False. XtSetValues _w_i_d_g_e_t_H_a_n_d_l_e _r_e_s_o_u_r_c_e:_v_a_l_u_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] SunOS 5.10 Last change: 15 Jul 1994 14 User Commands dtksh(1) XtUninstallTranslations _w_i_d_g_e_t_H_a_n_d_l_e XtUnmanageChild _w_i_d_g_e_t_H_a_n_d_l_e XtUnmanageChildren _w_i_d_g_e_t_H_a_n_d_l_e [_w_i_d_g_e_t_H_a_n_d_l_e ...] XtUnmapWidget _w_i_d_g_e_t_H_a_n_d_l_e XtUnrealizeWidget _w_i_d_g_e_t_H_a_n_d_l_e XtWindow _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e Built-in Motif Commands XmAddWMProtocolCallback _w_i_d_g_e_t_H_a_n_d_l_e _p_r_o_t_o_c_o_l_A_t_o_m _d_t_k_s_h- _c_o_m_m_a_n_d The _p_r_o_t_o_c_o_l_A_t_o_m operand is typically obtained using the XmInternAtom command. XmAddWMProtocols _w_i_d_g_e_t_H_a_n_d_l_e _p_r_o_t_o_c_o_l_A_t_o_m [_p_r_o_t_o_c_o_l_A_- _t_o_m ...] The _p_r_o_t_o_c_o_l_A_t_o_m operand is typically obtained using the XmInternAtom command. XmCommandAppendValue _w_i_d_g_e_t_H_a_n_d_l_e _s_t_r_i_n_g _X_m_C_o_m_m_a_n_d_E_r_r_o_r _w_i_d_g_e_t_H_a_n_d_l_e _e_r_r_o_r_S_t_r_i_n_g XmCommandGetChild _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _c_h_i_l_d_T_y_p_e The _c_h_i_l_d_T_y_p_e operand is one of the strings: DIALOG_COMMAND_TEXT DIALOG_PROMPT_LABEL DIALOG_HISTORY_LIST DIALOG_WORK_AREA XmCommandSetValue _w_i_d_g_e_t_H_a_n_d_l_e _c_o_m_m_a_n_d_S_t_r_i_n_g XmCreateArrowButton _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateArrowButtonGadget _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateBulletinBoard _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateBulletinBoardDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] SunOS 5.10 Last change: 15 Jul 1994 15 User Commands dtksh(1) XmCreateCascadeButton _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateCascadeButtonGadget _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateCommand _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateDialogShell _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateDrawingArea _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateDrawnButton _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateErrorDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateFileSelectionBox _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateFileSelectionDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateForm _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateFormDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateFrame _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateInformationDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateLabel _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateLabelGadget _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateList _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateMainWindow _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] SunOS 5.10 Last change: 15 Jul 1994 16 User Commands dtksh(1) XmCreateMenuBar _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateMenuShell _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateMessageBox _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateMessageDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateOptionMenu _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreatePanedWindow _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreatePopupMenu _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreatePromptDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreatePulldownMenu _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreatePushButton _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreatePushButtonGadget _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateQuestionDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateRadioBox _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateRowColumn _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateScale _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateScrollBar _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateScrolledList _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] SunOS 5.10 Last change: 15 Jul 1994 17 User Commands dtksh(1) XmCreateScrolledText _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateScrolledWindow _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateSelectionBox _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateSelectionDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateSeparator _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateSeparatorGadget _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateText _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateTextField _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateToggleButton _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateToggleButtonGadget _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateWarningDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateWorkArea _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmCreateWorkingDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] XmFileSelectionDoSearch _w_i_d_g_e_t_H_a_n_d_l_e _d_i_r_e_c_t_o_r_y_M_a_s_k XmFileSelectionBoxGetChild _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _c_h_i_l_d_T_y_p_e The _c_h_i_l_d_T_y_p_e operand is one of the strings: DIALOG_APPLY_BUTTON DIALOG_CANCEL_BUTTON DIALOG_DEFAULT_BUTTON DIALOG_DIR_LIST DIALOG_DIR_LIST_LABEL DIALOG_FILTER_LABEL DIALOG_FILTER_TEXT SunOS 5.10 Last change: 15 Jul 1994 18 User Commands dtksh(1) DIALOG_HELP_BUTTON DIALOG_LIST DIALOG_LIST_LABEL DIALOG_OK_BUTTON DIALOG_SEPARATOR DIALOG_SELECTION_LABEL DIALOG_TEXT DIALOG_WORK_AREA XmGetAtomName _v_a_r_i_a_b_l_e _d_i_s_p_l_a_y _a_t_o_m XmGetColors _w_i_d_g_e_t_H_a_n_d_l_e _b_a_c_k_g_r_o_u_n_d _v_a_r_i_a_b_l_e _v_a_r_i_a_b_l_e_2 _v_a_r_i_- _a_b_l_e_3 _v_a_r_i_a_b_l_e_4 The XmGetColors command differs from the C procedure in that it takes a _w_i_d_g_e_t_H_a_n_d_l_e instead of a screen pointer and a colormap. XmGetFocusWidget _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmGetPostedFromWidget _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmGetTabGroup _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmGetTearOffControl _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmGetVisibility _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmInternAtom _v_a_r_i_a_b_l_e _d_i_s_p_l_a_y _a_t_o_m_S_t_r_i_n_g _o_n_l_y_I_f_E_x_i_s_t_s_F_l_a_g The _o_n_l_y_I_f_E_x_i_s_t_s_F_l_a_g operand can be set to either True or False. XmIsTraversable _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XmListAddItem _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _i_t_e_m_S_t_r_i_n_g The ordering of the arguments to the XmListAddItem com- mand differs from the corresponding C function. XmListAddItems _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _i_t_e_m_S_t_r_i_n_g [_i_t_e_m_- _S_t_r_i_n_g ...] The ordering of the arguments to the XmListAddItems com- mand differs from the corresponding C function. XmListAddItemsUnselected _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _i_t_e_m_S_t_r_i_n_g [_i_t_e_m_S_t_r_i_n_g ...] SunOS 5.10 Last change: 15 Jul 1994 19 User Commands dtksh(1) The ordering of the arguments to the XmListAddItemsUn- selected command differs from the corresponding C func- tion. XmListAddItemUnselected _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _i_t_e_m_S_t_r_i_n_g The ordering of the arguments to the XmListAddItemUn- selected command differs from the corresponding C func- tion. XmListDeleteAllItems _w_i_d_g_e_t_H_a_n_d_l_e XmListDeleteItem _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g XmListDeleteItems _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g [_i_t_e_m_S_t_r_i_n_g ...] XmListDeleteItemsPos _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_C_o_u_n_t _p_o_s_i_t_i_o_n XmListDeletePos _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n XmListDeletePositions _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n [_p_o_s_i_t_i_o_n ...] XmListDeselectAllItems _w_i_d_g_e_t_H_a_n_d_l_e XmListDeselectItem _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g XmListDeselectPos _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n XmListGetSelectedPos _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e The command returns in _v_a_r_i_a_b_l_e a comma-separated list of indices. The command returns a value that can be used in a conditional. XmListGetKbdItemPos _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmListGetMatchPos _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g The command returns in _v_a_r_i_a_b_l_e a comma-separated list of indices. The command returns a value that can be used in a conditional. XmListItemExists _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g The command returns a value that can be used in a condi- tional. XmListItemPos _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g XmListPosSelected _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n SunOS 5.10 Last change: 15 Jul 1994 20 User Commands dtksh(1) The command returns a value that can be used in a condi- tional. XmListPosToBounds _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _v_a_r_i_a_b_l_e _v_a_r_i_a_b_l_e_2 _v_a_r_i_a_b_l_e_3 _v_a_r_i_a_b_l_e_4 The command returns a value that can be used in a condi- tional. XmListReplaceItemsPos _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _i_t_e_m_S_t_r_i_n_g [_i_t_e_m_S_t_r_i_n_g ...] The ordering of the arguments to the XmListReplaceItem- sPos command differs from the corresponding C function. XmListReplaceItemsPosUnselected _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _i_t_e_m_- _S_t_r_i_n_g [_i_t_e_m_S_t_r_i_n_g ...] The ordering of the arguments to the XmListReplaceItem- sPosUnselected command differs from the corresponding C function. XmListSelectItem _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g _n_o_t_i_f_y_F_l_a_g The _n_o_t_i_f_y_F_l_a_g operand can be set to either True or False. XmListSelectPos _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _n_o_t_i_f_y_F_l_a_g The _n_o_t_i_f_y_F_l_a_g operand can be set to either True or False. XmListSetAddMode _w_i_d_g_e_t_H_a_n_d_l_e _s_t_a_t_e The _s_t_a_t_e operand can be set to either True or False. XmListSetBottomItem _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g XmListSetBottomPos _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n XmListSetHorizPos _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n XmListSetItem _w_i_d_g_e_t_H_a_n_d_l_e _i_t_e_m_S_t_r_i_n_g XmListSetKbdItemPos _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n The command returns a value that can be used in a condi- tional. XmListSetPos _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n SunOS 5.10 Last change: 15 Jul 1994 21 User Commands dtksh(1) XmListUpdateSelectedList _w_i_d_g_e_t_H_a_n_d_l_e XmMainWindowSep1 _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmMainWindowSep2 _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmMainWindowSep3 _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmMainWindowSetAreas _w_i_d_g_e_t_H_a_n_d_l_e _m_e_n_u_W_i_d_g_e_t_H_a_n_d_l_e _c_o_m_- _m_a_n_d_W_i_d_g_e_t_H_a_n_d_l_e _h_o_r_i_z_o_n_t_a_l_S_c_r_o_l_l_b_a_r_W_i_d_g_e_t_H_a_n_d_l_e _v_e_r_t_i_c_a_l_- _S_c_r_o_l_l_b_a_r_W_i_d_g_e_t_H_a_n_d_l_e _w_o_r_k_R_e_g_i_o_n_W_i_d_g_e_t_H_a_n_d_l_e XmMenuPosition _w_i_d_g_e_t_H_a_n_d_l_e _e_v_e_n_t_H_a_n_d_l_e The _e_v_e_n_t_H_a_n_d_l_e operand refers to an XEvent that has typ- ically been obtained by accessing the _C_B__C_A_L_L__D_A_T_A._E_V_E_N_T, _E_H__E_V_E_N_T or _T_R_A_N_S_L_A_T_I_O_N__E_V_E_N_T environment variables. XmMessageBoxGetChild _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _c_h_i_l_d_T_y_p_e The _c_h_i_l_d_T_y_p_e operand is one of the strings: DIALOG_CANCEL_BUTTON DIALOG_DEFAULT_BUTTON DIALOG_HELP_BUTTON DIALOG_MESSAGE_LABEL DIALOG_OK_BUTTON DIALOG_SEPARATOR DIALOG_SYMBOL_LABEL XmOptionButtonGadget _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmOptionLabelGadget _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmProcessTraversal _w_i_d_g_e_t_H_a_n_d_l_e _d_i_r_e_c_t_i_o_n The _d_i_r_e_c_t_i_o_n operand is one of the strings: TRAVERSE_CURRENT TRAVERSE_DOWN TRAVERSE_HOME TRAVERSE_LEFT TRAVERSE_NEXT TRAVERSE_NEXT_TAB_GROUP TRAVERSE_PREV TRAVERSE_PREV_TAB_GROUP TRAVERSE_RIGHT TRAVERSE_UP The command returns a value that can be used in a condi- tional. SunOS 5.10 Last change: 15 Jul 1994 22 User Commands dtksh(1) XmRemoveWMProtocolCallback _w_i_d_g_e_t_H_a_n_d_l_e _p_r_o_t_o_c_o_l_A_t_o_m _d_t_k_s_h- _c_o_m_m_a_n_d The _p_r_o_t_o_c_o_l_A_t_o_m operand is typically obtained using the XmInternAtom command. As with traditional WM callbacks, when a callback is removed, the same dtksh command string must be specified as was specified when the callback was originally registered. XmRemoveWMProtocols _w_i_d_g_e_t_H_a_n_d_l_e _p_r_o_t_o_c_o_l_A_t_o_m [_p_r_o_t_o_c_o_l_A_- _t_o_m ...] The _p_r_o_t_o_c_o_l_A_t_o_m operand is typically obtained using the XmInternAtom command. XmScaleGetValue _w_i_d_g_e_t_H_a_n_d_l_e _v_a_r_i_a_b_l_e XmScaleSetValue _w_i_d_g_e_t_H_a_n_d_l_e _v_a_l_u_e XmScrollBarGetValues _w_i_d_g_e_t_H_a_n_d_l_e _v_a_r_i_a_b_l_e _v_a_r_i_a_b_l_e_2 _v_a_r_i_- _a_b_l_e_3 _v_a_r_i_a_b_l_e_4 XmScrollBarSetValues _w_i_d_g_e_t_H_a_n_d_l_e _v_a_l_u_e _s_l_i_d_e_r_S_i_z_e _i_n_c_r_e_m_e_n_t _p_a_g_e_I_n_c_r_e_m_e_n_t _n_o_t_i_f_y_F_l_a_g The _n_o_t_i_f_y_F_l_a_g operand can be set to either True or False. XmScrollVisible _w_i_d_g_e_t_H_a_n_d_l_e _w_i_d_g_e_t_H_a_n_d_l_e _l_e_f_t_R_i_g_h_t_M_a_r_g_i_n _t_o_p_B_o_t_t_o_m_M_a_r_g_i_n XmSelectionBoxGetChild _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _c_h_i_l_d_T_y_p_e The _c_h_i_l_d_T_y_p_e operand is one of the strings: DIALOG_CANCEL_BUTTON DIALOG_DEFAULT_BUTTON DIALOG_HELP_BUTTON DIALOG_APPLY_BUTTON DIALOG_LIST DIALOG_LIST_LABEL DIALOG_OK_BUTTON DIALOG_SELECTION_LABEL DIALOG_SEPARATOR DIALOG_TEXT DIALOG_WORK_AREA XmTextClearSelection _w_i_d_g_e_t_H_a_n_d_l_e _t_i_m_e The _t_i_m_e operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. SunOS 5.10 Last change: 15 Jul 1994 23 User Commands dtksh(1) XmTextCopy _w_i_d_g_e_t_H_a_n_d_l_e _t_i_m_e The _t_i_m_e operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. The command returns a value that can be used in a conditional. XmTextCut _w_i_d_g_e_t_H_a_n_d_l_e _t_i_m_e The _t_i_m_e operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. The command returns a value that can be used in a conditional. XmTextDisableRedisplay _w_i_d_g_e_t_H_a_n_d_l_e XmTextEnableDisplay _w_i_d_g_e_t_H_a_n_d_l_e XmTextFindString _w_i_d_g_e_t_H_a_n_d_l_e _s_t_a_r_t_P_o_s_i_t_i_o_n _s_t_r_i_n_g _d_i_r_e_c_t_i_o_n _v_a_r_i_a_b_l_e The _d_i_r_e_c_t_i_o_n operand is one of the strings TEXT_FORWARD or TEXT_BACKWARD. The command returns a value that can be used in a conditional. XmTextGetBaseline _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextGetEditable _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XmTextGetInsertionPosition _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextGetLastPosition _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextGetMaxLength _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextGetSelection _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextGetSelectionPosition _w_i_d_g_e_t_H_a_n_d_l_e _v_a_r_i_a_b_l_e _v_a_r_i_a_b_l_e_2 The command returns a value that can be used in a condi- tional. XmTextGetString _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextGetTopCharacter _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextInsert _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _s_t_r_i_n_g SunOS 5.10 Last change: 15 Jul 1994 24 User Commands dtksh(1) XmTextPaste _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XmTextPosToXY _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _v_a_r_i_a_b_l_e _v_a_r_i_a_b_l_e_2 The command returns a value that can be used in a condi- tional. XmTextRemove _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XmTextReplace _w_i_d_g_e_t_H_a_n_d_l_e _f_r_o_m_P_o_s_i_t_i_o_n _t_o_P_o_s_i_t_i_o_n _s_t_r_i_n_g XmTextScroll _w_i_d_g_e_t_H_a_n_d_l_e _l_i_n_e_s XmTextSetAddMode _w_i_d_g_e_t_H_a_n_d_l_e _s_t_a_t_e The _s_t_a_t_e operand can be set to either True or False. XmTextSetEditable _w_i_d_g_e_t_H_a_n_d_l_e _e_d_i_t_a_b_l_e_F_l_a_g The _e_d_i_t_a_b_l_e_F_l_a_g operand can be set to either True or False. XmTextSetHighlight _w_i_d_g_e_t_H_a_n_d_l_e _l_e_f_t_P_o_s_i_t_i_o_n _r_i_g_h_t_P_o_s_i_t_i_o_n _m_o_d_e The _m_o_d_e operand is one of the strings: HIGHLIGHT_NORMAL HIGHLIGHT_SELECTED HIGHLIGHT_SECONDARY_SELECTED XmTextSetInsertionPosition _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n XmTextSetMaxLength _w_i_d_g_e_t_H_a_n_d_l_e _m_a_x_L_e_n_g_t_h XmTextSetSelection _w_i_d_g_e_t_H_a_n_d_l_e _f_i_r_s_t_P_o_s_i_t_i_o_n _l_a_s_t_P_o_s_i_t_i_o_n _t_i_m_e The _t_i_m_e operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. XmTextSetString _w_i_d_g_e_t_H_a_n_d_l_e _s_t_r_i_n_g XmTextSetTopCharacter _w_i_d_g_e_t_H_a_n_d_l_e _t_o_p_C_h_a_r_a_c_t_e_r_P_o_s_i_t_i_o_n SunOS 5.10 Last change: 15 Jul 1994 25 User Commands dtksh(1) XmTextShowPosition _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n XmTextXYToPos _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _x _y XmTextFieldClearSelection _w_i_d_g_e_t_H_a_n_d_l_e _t_i_m_e The _t_i_m_e operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. XmTextFieldGetBaseline _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextFieldGetEditable _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XmTextFieldGetInsertionPosition _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextFieldGetLastPosition _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextFieldGetMaxLength _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextFieldGetSelection _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextFieldGetSelectionPosition _w_i_d_g_e_t_H_a_n_d_l_e _v_a_r_i_a_b_l_e _v_a_r_i_- _a_b_l_e_2 The command returns a value that can be used in a condi- tional. XmTextFieldGetString _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e XmTextFieldInsert _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _s_t_r_i_n_g XmTextFieldPosToXY _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n _v_a_r_i_a_b_l_e _v_a_r_i_a_b_l_e_2 The command returns a value that can be used in a condi- tional. XmTextFieldRemove _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XmTextFieldReplace _w_i_d_g_e_t_H_a_n_d_l_e _f_r_o_m_P_o_s_i_t_i_o_n _t_o_P_o_s_i_t_i_o_n _s_t_r_i_n_g XmTextFieldSetEditable _w_i_d_g_e_t_H_a_n_d_l_e _e_d_i_t_a_b_l_e_F_l_a_g The _e_d_i_t_a_b_l_e_F_l_a_g operand can be set to either True or False. SunOS 5.10 Last change: 15 Jul 1994 26 User Commands dtksh(1) XmTextFieldSetHighlight _w_i_d_g_e_t_H_a_n_d_l_e _l_e_f_t_P_o_s_i_t_i_o_n _r_i_g_h_t_P_o_s_i_- _t_i_o_n _m_o_d_e The _m_o_d_e operand is one of the strings: HIGHLIGHT_NORMAL HIGHLIGHT_SELECTED HIGHLIGHT_SECONDARY_SELECTED XmTextFieldSetInsertionPosition _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n XmTextFieldSetMaxLength _w_i_d_g_e_t_H_a_n_d_l_e _m_a_x_L_e_n_g_t_h XmTextFieldSetSelection _w_i_d_g_e_t_H_a_n_d_l_e _f_i_r_s_t_P_o_s_i_t_i_o_n _l_a_s_t_P_o_s_i_- _t_i_o_n _t_i_m_e The _t_i_m_e operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. XmTextFieldSetString _w_i_d_g_e_t_H_a_n_d_l_e _s_t_r_i_n_g XmTextFieldShowPosition _w_i_d_g_e_t_H_a_n_d_l_e _p_o_s_i_t_i_o_n XmTextFieldXYToPos _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _x _y XmTextFieldCopy _w_i_d_g_e_t_H_a_n_d_l_e _t_i_m_e The _t_i_m_e operand is typically either obtained from within an XEvent, or from a call to the XtLastTimestampProcessed command. The command returns a value that can be used in a conditional. XmTextFieldCut _w_i_d_g_e_t_H_a_n_d_l_e _t_i_m_e The _t_i_m_e operand is typically either obtained from within an XEvent or from a call to the XtLastTimestampProcessed command. The command returns a value that can be used in a conditional. XmTextFieldPaste _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XmTextFieldSetAddMode _w_i_d_g_e_t_H_a_n_d_l_e _s_t_a_t_e The _s_t_a_t_e operand can be set to either True or False. XmToggleButtonGadgetGetState _w_i_d_g_e_t_H_a_n_d_l_e SunOS 5.10 Last change: 15 Jul 1994 27 User Commands dtksh(1) The command returns a value that can be used in a condi- tional. XmToggleButtonGadgetSetState _w_i_d_g_e_t_H_a_n_d_l_e _s_t_a_t_e _n_o_t_i_f_y_F_l_a_g The _s_t_a_t_e operand can be set to either True or False. The _n_o_t_i_f_y_F_l_a_g operand can be set to either True or False. XmToggleButtonGetState _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. XmToggleButtonSetState _w_i_d_g_e_t_H_a_n_d_l_e _s_t_a_t_e _n_o_t_i_f_y_F_l_a_g The _s_t_a_t_e operand can be set to either True or False. The _n_o_t_i_f_y_F_l_a_g operand can be set to either True or False. XmUpdateDisplay _w_i_d_g_e_t_H_a_n_d_l_e Built-in CDE Application Help Commands DtCreateHelpQuickDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] DtCreateHelpDialog _v_a_r_i_a_b_l_e _p_a_r_e_n_t_W_i_d_g_e_t_H_a_n_d_l_e _n_a_m_e [_r_e_s_o_u_r_c_e:_v_a_l_u_e ...] DtHelpQuickDialogGetChild _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _c_h_i_l_d_T_y_p_e The _c_h_i_l_d_T_y_p_e operand is one of the strings: HELP_QUICK_OK_BUTTON HELP_QUICK_PRINT_BUTTON HELP_QUICK_HELP_BUTTON HELP_QUICK_SEPARATOR HELP_QUICK_MORE_BUTTON HELP_QUICK_BACK_BUTTON DtHelpReturnSelectedWidgetId _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _v_a_r_i_a_b_l_e_2 The _v_a_r_i_a_b_l_e operand is set to one of the strings: HELP_SELECT_VALID HELP_SELECT_INVALID HELP_SELECT_ABORT HELP_SELECT_ERROR and _v_a_r_i_a_b_l_e_2 is set to the _w_i_d_g_e_t_H_a_n_d_l_e for the selected widget. SunOS 5.10 Last change: 15 Jul 1994 28 User Commands dtksh(1) DtHelpSetCatalogName _c_a_t_a_l_o_g_N_a_m_e Built-in Localization Commands catopen _v_a_r_i_a_b_l_e _c_a_t_a_l_o_g_N_a_m_e Opens the indicated message catalog, and returns the catalog ID in the environment variable specified by _v_a_r_i_- _a_b_l_e. If a shell script needs to close the file descrip- tor associated with a message catalog, the catalog ID must be closed using the catclose command. catgets _v_a_r_i_a_b_l_e _c_a_t_a_l_o_g_I_d _s_e_t_N_u_m_b_e_r _m_e_s_s_a_g_e_N_u_m_b_e_r _d_e_f_a_u_l_t_- _M_e_s_s_a_g_e_S_t_r_i_n_g Attempts to extract the requested message string from the message catalog associated with the _c_a_t_a_l_o_g_I_d argument. If the message string cannot be located, the default mes- sage string is returned. In either case, the returned message string is placed into the environment variable indicated by _v_a_r_i_a_b_l_e. catclose _c_a_t_a_l_o_g_I_d Closes the message catalog associated with the indicated _c_a_t_a_l_o_g_I_d. Built-in Session Management Commands DtSessionRestorePath _w_i_d_g_e_t_H_a_n_d_l_e _v_a_r_i_a_b_l_e _s_e_s_s_i_o_n_F_i_l_e Given the filename for the session file (excluding any path information), this command returns the full pathname for the session file in the environment variable indi- cated by _v_a_r_i_a_b_l_e. The command returns a value that can be used in a conditional, indicating whether the command succeeded. DtSessionSavePath _w_i_d_g_e_t_H_a_n_d_l_e _v_a_r_i_a_b_l_e _v_a_r_i_a_b_l_e_2 The full pathname for the session file is returned in environment variable indicated by _v_a_r_i_a_b_l_e. The filename portion of the session file (excluding any path informa- tion) is returned in the environment variable indicated by _v_a_r_i_a_b_l_e_2. The command returns a value that can be used in a conditional, indicating whether the command succeeded. DtShellIsIconified _w_i_d_g_e_t_H_a_n_d_l_e The command returns a value that can be used in a condi- tional. SunOS 5.10 Last change: 15 Jul 1994 29 User Commands dtksh(1) DtSetStartupCommand _w_i_d_g_e_t_H_a_n_d_l_e _c_o_m_m_a_n_d_S_t_r_i_n_g Part of the session management process is telling the session manager how to restart the application the next time the user reopens the session. This command passes along the specified command string to the session manager. The widget handle should refer to an applica- tion shell. DtSetIconifyHint _w_i_d_g_e_t_H_a_n_d_l_e _i_c_o_n_i_f_y_H_i_n_t The _i_c_o_n_i_f_y_H_i_n_t operand can be set to either True or False. This command sets the initial iconified state for a shell window. This command only works if the window associated with the widget has not yet been realized. Built-in Workspace Management Commands DtWsmAddCurrentWorkspaceCallback _v_a_r_i_a_b_l_e _w_i_d_g_e_t_H_a_n_d_l_e _d_t_k_s_h-_c_o_m_m_a_n_d This command evaluates the specified dtksh command when- ever the user changes workspaces. The handle associated with this callback is returned in the environment vari- able indicated by _v_a_r_i_a_b_l_e. The widget indicated by _w_i_d_g_e_t_H_a_n_d_l_e should be a shell widget. DtWsmRemoveWorkspaceCallback _c_a_l_l_b_a_c_k-_h_a_n_d_l_e The _c_a_l_l_b_a_c_k-_h_a_n_d_l_e must be a handle that was returned by DtWsmAddCurrentWorkspaceCallback. DtWsmGetCurrentWorkspace _d_i_s_p_l_a_y _r_o_o_t_W_i_n_d_o_w _v_a_r_i_a_b_l_e This command returns the X atom representing the user's current workspace in the environment variable indicated by _v_a_r_i_a_b_l_e. The XmGetAtomName command maps the X atom into its string representation. DtWsmSetCurrentWorkspace _w_i_d_g_e_t_H_a_n_d_l_e _w_o_r_k_s_p_a_c_e_N_a_m_e_A_t_o_m This command changes the user's current workspace to the workspace indicated by _w_o_r_k_s_p_a_c_e_N_a_m_e_A_t_o_m. The command returns a value that can be used in a conditional, indi- cating whether the command succeeded. DtWsmGetWorkspaceList _d_i_s_p_l_a_y _r_o_o_t_W_i_n_d_o_w _v_a_r_i_a_b_l_e This command returns in _v_a_r_i_a_b_l_e a string of comma- separated X atoms, representing the current set of workspaces defined for the user. The command returns a value that can be used in a conditional, indicating whether the command succeeded. SunOS 5.10 Last change: 15 Jul 1994 30 User Commands dtksh(1) DtWsmGetWorkspacesOccupied _d_i_s_p_l_a_y _w_i_n_d_o_w _v_a_r_i_a_b_l_e This command returns a string of comma-separated X atoms, representing the current set of workspaces occupied by the indicated shell window in the environment variable indicated by _v_a_r_i_a_b_l_e. The command returns a value that can be used in a conditional, indicating whether the com- mand succeeded. DtWsmSetWorkspacesOccupied _d_i_s_p_l_a_y _w_i_n_d_o_w _w_o_r_k_s_p_a_c_e_L_i_s_t This command moves the indicated shell window to the set of workspaces indicated by the string _w_o_r_k_s_p_a_c_e_L_i_s_t, which must be a comma-separated list of X atoms. DtWsmAddWorkspaceFunctions _d_i_s_p_l_a_y _w_i_n_d_o_w DtWsmRemoveWorkspaceFunctions _d_i_s_p_l_a_y _w_i_n_d_o_w DtWsmOccupyAllWorkspaces _d_i_s_p_l_a_y _w_i_n_d_o_w DtWsmGetCurrentBackdropWindows _d_i_s_p_l_a_y _r_o_o_t_W_i_n_d_o_w _v_a_r_i_a_b_l_e This command returns in _v_a_r_i_a_b_l_e a string of comma- separated window IDs representing the set of root back- drop windows. Built-in Action Commands The set of commands in this section provides the programmer with the tools for loading the action databases, querying information about actions defined in the databases, and requesting that an action be initiated. DtDbLoad This command reads in the action and data types data- bases. It must be called before any of the other Action or Data Typing Commands. The shell script should also use the DtDbReloadNotify command so that the shell script can be notified if new databases must be loaded. DtDbReloadNotify _d_t_k_s_h-_c_o_m_m_a_n_d The specified dtksh command is executed when the notifi- cation is received. Typically, the dtksh command includes a call to the DtDbLoad command. DtActionExists _a_c_t_i_o_n_N_a_m_e The command returns a value that can be used in a condi- tional. SunOS 5.10 Last change: 15 Jul 1994 31 User Commands dtksh(1) DtActionLabel _v_a_r_i_a_b_l_e _a_c_t_i_o_n_N_a_m_e If the action does not exist, then an empty string is returned. DtActionDescription _v_a_r_i_a_b_l_e _a_c_t_i_o_n_N_a_m_e This command returns an empty string if the action is not defined, or if the DESCRIPTION attribute is not speci- fied. DtActionInvoke _w_i_d_g_e_t_H_a_n_d_l_e _a_c_t_i_o_n_N_a_m_e _t_e_r_m_O_p_t_s _e_x_e_c_H_o_s_t _c_o_n_t_e_x_t_D_i_r _u_s_e_I_n_d_i_c_a_t_o_r _d_t_k_s_h-_c_o_m_m_a_n_d [FILE _f_i_l_e_N_a_m_e] ... The [FILE _f_i_l_e_N_a_m_e] couplets can be used to specify file arguments to be used by DtActionInvoke when invoking the specified action. The _d_t_k_s_h-_c_o_m_m_a_n_d argument is not sup- ported in CDE 1.0, and should be specified as a null ("") value. Built-in Data Typing Commands DtDtsLoadDataTypes This command should be invoked before any of the other data typing commands. DtDtsFileToDataType _v_a_r_i_a_b_l_e _f_i_l_e_P_a_t_h This command returns the name of the data type associated with the file indicated by the _f_i_l_e_P_a_t_h argument in the _v_a_r_i_a_b_l_e argument. The _v_a_r_i_a_b_l_e argument is set to an empty string if the file cannot be typed. DtDtsFileToAttributeValue _v_a_r_i_a_b_l_e _f_i_l_e_P_a_t_h _a_t_t_r_N_a_m_e This command returns the string representing the value of the specified attribute for the data type associated with the indicated file in the _v_a_r_i_a_b_l_e argument. If the attribute is not defined, or if the file cannot be typed, the _v_a_r_i_a_b_l_e argument is set to an empty string. DtDtsFileToAttributeList _v_a_r_i_a_b_l_e _f_i_l_e_P_a_t_h This command returns the space-separated list of attri- bute names defined for the data type associated with the indicated file in the _v_a_r_i_a_b_l_e argument. A shell script queries the individual values for the attributes using the DtDtsFileToAttributeValue command. The _v_a_r_i_a_b_l_e argument is set to an empty string if the file cannot be typed. This command differs from the corresponding C function in that it only returns the names of the defined attributes and not their values. SunOS 5.10 Last change: 15 Jul 1994 32 User Commands dtksh(1) DtDtsDataTypeToAttributeValue _v_a_r_i_a_b_l_e _d_a_t_a_T_y_p_e _a_t_t_r_N_a_m_e _o_p_t_N_a_m_e This command returns the string representing the value of the specified attribute for the indicated data type in _v_a_r_i_a_b_l_e. If the attribute is not defined, or if the indicated data type does not exist, the _v_a_r_i_a_b_l_e argument is set to an empty string. DtDtsDataTypeToAttributeList _v_a_r_i_a_b_l_e _d_a_t_a_T_y_p_e _o_p_t_N_a_m_e This command returns the space-separated list of attri- bute names defined for the indicated data type in _v_a_r_i_- _a_b_l_e. A shell script queries the individual values for the attributes using the DtDtsDataTypeToAttributeValue command. The _v_a_r_i_a_b_l_e argument is set to an empty string if the data type is not defined. This command differs from the corresponding C function in that it only returns the names of the defined attributes, and not their values. DtDtsFindAttribute _v_a_r_i_a_b_l_e _n_a_m_e _v_a_l_u_e This command returns a space-separated list of data type names whose attribute, indicated by the _n_a_m_e argument, has the value indicated by the _v_a_l_u_e argument. If an error occurs, the _v_a_r_i_a_b_l_e argument is set to an empty string. DtDtsDataTypeNames _v_a_r_i_a_b_l_e This command returns a space-separated list representing all of the data types currently defined in the data types database. If an error occurs, the _v_a_r_i_a_b_l_e argument is set to an empty string. DtDtsSetDataType _v_a_r_i_a_b_l_e _f_i_l_e_P_a_t_h _d_a_t_a_T_y_p_e _o_v_e_r_r_i_d_e The _v_a_r_i_a_b_l_e argument is set to the resultant saved data type for the directory. DtDtsDataTypeIsAction _d_a_t_a_T_y_p_e The command returns a value that can be used in a condi- tional. Built-in CDE Desktop Services Message Set Commands The following set of commands implement a subset of the Desktop Services Message Set, allowing shell script partici- pation in the Desktop Services protocol. Many of the Tool- Talk commands differ slightly from their associated C pro- gramming call. For ToolTalk commands that typically return SunOS 5.10 Last change: 15 Jul 1994 33 User Commands dtksh(1) a pointer, a C application can validate that pointer by cal- ling the tt_ptr_error() function; this C function call returns a Tt_status value, which indicates whether the pointer was valid, and if not, why it was not. In dtksh, all of the Desktop Services Message Set Commands that return a pointer also return the associated Tt_status value for the pointer automatically; this saves the shell script from needing to make an additional call to check the validity of the original pointer. In the case of a pointer error occur- ring, dtksh returns an empty string for the pointer value, and sets the Tt_status code accordingly. The Tt_status value is returned in the _s_t_a_t_u_s argument. The Tt_status value is a string representing the error, and can assume any of the values shown in the manual page for . Some of the commands take a message scope as an argument. For these commands, the _s_c_o_p_e argument can be set to a string representing any of the constants documented for tt_message_scope(1), and in the manual pages for the indivi- dual ToolTalk functions. tt_file_netfile _v_a_r_i_a_b_l_e _s_t_a_t_u_s _f_i_l_e _n_a_m_e tt_netfile_file _v_a_r_i_a_b_l_e _s_t_a_t_u_s _n_e_t_f_i_l_e _n_a_m_e tt_host_file_netfile _v_a_r_i_a_b_l_e _s_t_a_t_u_s _h_o_s_t _f_i_l_e _n_a_m_e tt_host_netfile_file _v_a_r_i_a_b_l_e _s_t_a_t_u_s _h_o_s_t _n_e_t_f_i_l_e _n_a_m_e ttdt_open _v_a_r_i_a_b_l_e _s_t_a_t_u_s _v_a_r_i_a_b_l_e_2 _t_o_o_l_n_a_m_e _v_e_n_d_o_r _v_e_r_s_i_o_n _s_e_n_d_S_t_a_r_t_e_d This command returns in the _v_a_r_i_a_b_l_e argument the _p_r_o_c_I_d associated with the connection. It returns the file descriptor associated with the connection in _v_a_r_i_a_b_l_e_2; this file descriptor can be used in registering an alter- native Xt input handler via the XtAddInput command. The _s_e_n_d_S_t_a_r_t_e_d argument is True or False. Any _p_r_o_c_I_d_s returned by ttdt_open contain embedded spaces. To prevent dtksh from interpreting the _p_r_o_c_I_d as multiple arguments (versus a single argument with embedded spaces), references to the environment variable contain- ing the _p_r_o_c_I_d must be within double quotes, as shown: ttdt_close STATUS "$PROC_ID" "" True tttk_Xt_input_handler _p_r_o_c_I_d _s_o_u_r_c_e _i_d In order for the ToolTalk messages to be received and processed, the shell script must register an Xt input handler for the file descriptor returned by the call to ttdt_open. The Xt input handler is registered using the SunOS 5.10 Last change: 15 Jul 1994 34 User Commands dtksh(1) XtAddInput command, and the handler must be registered as a raw input handler. The input handler that the shell script registers should invoke tttk_Xt_input_handler to get the message received and processed. The following code block demonstrates how this is done: ttdt_open PROC_ID STATUS FID "Tool" "HP" "1.0" True XtAddInput INPUT_ID -r $FID "ProcessTTInput \"$PROC_ID\"" ProcessTTInput() { tttk_Xt_input_handler $1 $INPUT_SOURCE $INPUT_ID } Refer to the description of the XtAddInput command for more details about alternative Xt input handlers. This command can be specified as an alternative Xt input handler, using the XtAddInput command. The _p_r_o_c_I_d value should be that which was returned by the ttdt_open command. When register- ing tttk_Xt_input_handler as an alternative Xt input handler, it must be registered as a raw handler to prevent dtksh from automatically break- ing up the input into lines. This can be done as follows: XtAddInput returnId -r $tt_fd \ "tttk_Xt_input_handler \"$procId\"" The \" characters before and after the reference to the _p_r_o_c_I_d environment variable are necessary to protect the embedded spaces in the _p_r_o_c_I_d environ- ment variable. ttdt_close _s_t_a_t_u_s _p_r_o_c_I_d _n_e_w_P_r_o_c_I_d _s_e_n_d_S_t_o_p_p_e_d This command closes the indicated communications connec- tion, and optionally sends a _S_t_o_p_p_e_d notice, if the _s_e_n_d_S_t_o_p_p_e_d argument is set to True. Because the _p_r_o_c_I_d returned by the call to ttdt_open contains embedded spaces, it must be enclosed within double quotes, as shown: ttdt_close STATUS "$PROC_ID" "$NEW_PROC_ID" False ttdt_session_join _v_a_r_i_a_b_l_e _s_t_a_t_u_s _s_e_s_s_I_d _s_h_e_l_l_W_i_d_g_e_t_H_a_n_d_l_e _j_o_i_n This command joins the session indicated by the _s_e_s_s_I_d argument. If the _s_e_s_s_I_d argument does not specify a value (that is, it is an empty string), then the default session is joined. If the _s_h_e_l_l_W_i_d_g_e_t_H_a_n_d_l_e argument specifies a widget handle (that is, it is not an empty SunOS 5.10 Last change: 15 Jul 1994 35 User Commands dtksh(1) string), then it should refer to a mappedWhenManaged applicationShellWidget. The _j_o_i_n argument is True or False. This command returns an opaque pattern handle in the _v_a_r_i_a_b_l_e argument; this handle can be destroyed using the ttdt_session_quit command when it is no longer needed. ttdt_session_quit _s_t_a_t_u_s _s_e_s_s_I_d _s_e_s_s_P_a_t_t_e_r_n_s _q_u_i_t This command destroys the message patterns specified by the _s_e_s_s_P_a_t_t_e_r_n_s argument, and, if the _q_u_i_t argument is set to True, it quits the session indicated by the _s_e_s_s_I_d argument, or it quits the default session if _s_e_s_s_I_d is empty. ttdt_file_join _v_a_r_i_a_b_l_e _s_t_a_t_u_s _p_a_t_h_N_a_m_e _s_c_o_p_e _j_o_i_n _d_t_k_s_h- _c_o_m_m_a_n_d An opaque pattern handle is returned in the _v_a_r_i_a_b_l_e argument; this should be destroyed by calling ttdt_file_quit when there is no interest in monitoring messages for the indicated file. The requested _d_t_k_s_h- _c_o_m_m_a_n_d is evaluated any time a message is received for the indicated file. When this _d_t_k_s_h-_c_o_m_m_a_n_d is evaluated, the following environment variables are defined, and provide additional information about the received message: _D_T__T_T__M_S_G The opaque handle for the incoming mes- sage. _D_T__T_T__O_P The string representing the operation to be performed; that is, TTDT_DELETED, TTDT_MODIFIED, TTDT_REVERTED, TTDT_MOVED or TTDT_SAVED. _D_T__T_T__P_A_T_H_N_A_M_E The pathname for the file to which this message pertains. _D_T__T_T__S_A_M_E__E_U_I_D__E_G_I_D Set to True if the message was sent by an application operating with the same effec- tive user ID and effective group ID as this process. _D_T__T_T__S_A_M_E__P_R_O_C_I_D Set to True if the message was sent by an application with the same _p_r_o_c_I_d (as returned by ttdt_open). SunOS 5.10 Last change: 15 Jul 1994 36 User Commands dtksh(1) When the callback completes, it must indicate whether the passed-in message was consumed (replied-to, failed or rejected). If the callback returns the message (as passed in the _D_T__T_T__M_S_G environment variable), it is assumed that the mes- sage was not consumed. If the message was con- sumed, the callback should return zero, or one of the values returned by the tt_error_pointer com- mand. The callback can return its value in the following fashion: return $DT_TT_MSG (or) return 0 ttdt_file_quit _s_t_a_t_u_s _p_a_t_t_e_r_n_s _q_u_i_t This command destroys the message patterns specified by the _p_a_t_t_e_r_n_s argument, and also unregisters interest in the pathname that was passed to the ttdt_file_join com- mand if _q_u_i_t is set to True; the _p_a_t_t_e_r_n_s argument should be the value returned by a call to the ttdt_file_join command. ttdt_file_event _s_t_a_t_u_s _o_p _p_a_t_t_e_r_n_s _s_e_n_d This command creates, and optionally sends, a ToolTalk notice announcing an event pertaining to a file. The file is indicated by the pathname passed to the ttdt_file_join command when _p_a_t_t_e_r_n_s was created. The _o_p argument indicates what should be announced for the indi- cated file, and can be set to TTDT_MODIFIED, TTDT_SAVED or TTDT_REVERTED. If _o_p is set to TTDT_MODIFIED, this command registers to handle _G_e_t__M_o_d_i_f_i_e_d, _S_a_v_e and _R_e_v_e_r_t messages in the scope specified when the _p_a_t_t_e_r_n_s was created. If _o_p is set to TTDT_SAVED or TTDT_REVERTED, this command unregisters from handling _G_e_t__M_o_d_i_f_i_e_d, _S_a_v_e and _R_e_v_e_r_t messages for this file. If the _s_e_n_d argument is set to True, the indicated message is sent. ttdt_Get_Modified _p_a_t_h_N_a_m_e _s_c_o_p_e _t_i_m_e_o_u_t This commands sends a _G_e_t__M_o_d_i_f_i_e_d request in the indi- cated scope, and waits for a reply, or for the specified _t_i_m_e_o_u_t (in milliseconds) to elapse. It returns a value that can be used in a conditional. A value of True is returned if an affirmative reply is received within the specified _t_i_m_e_o_u_t; otherwise, False is returned. ttdt_Save _s_t_a_t_u_s _p_a_t_h_N_a_m_e _s_c_o_p_e _t_i_m_e_o_u_t This command sends a _S_a_v_e request in the indicated scope, and waits for a reply, or for the indicated _t_i_m_e_o_u_t (in milliseconds) to elapse. A status of TT_OK is returned SunOS 5.10 Last change: 15 Jul 1994 37 User Commands dtksh(1) if an affirmative reply is received before the _t_i_m_e_o_u_t elapses; otherwise, a Tt_status error value is returned. ttdt_Revert _s_t_a_t_u_s _p_a_t_h_N_a_m_e _s_c_o_p_e _t_i_m_e_o_u_t This command sends a _R_e_v_e_r_t request in the indicated scope, and waits for a reply, or for the indicated _t_i_m_e_o_u_t (in milliseconds) to elapse. A status of TT_OK is returned if an affirmative reply is received before the _t_i_m_e_o_u_t elapses; otherwise, a Tt_status error value is returned. The following commands are typically used by the callback registered with the ttdt_file_join command. They serve as the mechanism for consuming and destroying a message. A message is consumed by either rejecting, failing or replying to it. The _t_t__e_r_r_o_r__p_o_i_n_t_e_r is used by the callback to get a return pointer for indicating an error condition. tt_error_pointer _v_a_r_i_a_b_l_e _t_t_S_t_a_t_u_s This command returns a magic value, which is used by ToolTalk to represent an invalid pointer. The magic value returned depends on the _t_t_S_t_a_t_u_s value passed in. Any of the valid Tt_status values can be specified. tttk_message_destroy _s_t_a_t_u_s _m_s_g This command destroys any patterns that may have been stored on the message indicated by the _m_s_g argument, and then it destroys the message. tttk_message_reject _s_t_a_t_u_s _m_s_g _m_s_g_S_t_a_t_u_s _m_s_g_S_t_a_t_u_s_S_t_r_i_n_g _d_e_s_t_r_o_y This command sets the status and the status string for the indicated request message, and then rejects the mes- sage. It then destroys the passed-in message if the _d_e_s_- _t_r_o_y argument is set to True. This command is one way in which the callback specified with the ttdt_file_join com- mand consumes a message. After rejecting the message, it is typically safe to destroy the message using tttk_message_destroy. tttk_message_fail _s_t_a_t_u_s _m_s_g _m_s_g_S_t_a_t_u_s _m_s_g_S_t_a_t_u_s_S_t_r_i_n_g _d_e_s_- _t_r_o_y This command sets the status and the status string for the indicated request message, and then it fails the mes- sage. It destroys the passed-in message if the _d_e_s_t_r_o_y argument is set to True. This command is one way in which the callback specified with the ttdt_file_join SunOS 5.10 Last change: 15 Jul 1994 38 User Commands dtksh(1) command consumes a message. After failing the message, it is typically safe to destroy the message, using tttk_message_destroy. tt_message_reply _s_t_a_t_u_s _m_s_g This command informs the ToolTalk service that the shell script has handled the message specified by the _m_s_g argu- ment. After replying to a message, it is typically safe to destroy the message using the tttk_message_destroy command. Listing Widget Information The _D_t_W_i_d_g_e_t_I_n_f_o command provides the shell programmer a mechanism for obtaining information about the current set of instantiated widgets and their resources; the information is written to the standard output. This provides useful debug- ging information by including: +o The list of instantiated widgets, including: the name, class and parent of the widget; a handle for the widget; the name of the environment variable supplied when the widget was created; the state of the widget. +o The list of resources supported by a particular widget class. +o The list of constraint resources supported by a par- ticular widget class. _D_t_W_i_d_g_e_t_I_n_f_o is called by using any of the following syn- taxes; all of the arguments are optional: DtWidgetInfo [_w_i_d_g_e_t_H_a_n_d_l_e | _w_i_d_g_e_t_N_a_m_e] If no arguments are supplied, information about all existing widgets is written to standard output; the information includes the name, the handle, the environ- ment variable, the parent, the widget class and the state. If arguments are supplied, they should be either widget handles, or the names of existing widgets; in this case, the information is written only for the requested set of widgets. DtWidgetInfo -r [_w_i_d_g_e_t_H_a_n_d_l_e | _w_i_d_g_e_t_C_l_a_s_s] If no arguments are supplied, the list of supported resources is written to standard output for all available widget classes. If arguments are supplied, they should be either widget handles, or the widget class names; in this case, the information is written only for the requested set of widgets or widget classes. SunOS 5.10 Last change: 15 Jul 1994 39 User Commands dtksh(1) DtWidgetInfo -R [_w_i_d_g_e_t_H_a_n_d_l_e | _w_i_d_g_e_t_C_l_a_s_s] If no arguments are supplied, the list of supported con- straint resources, if any, is written to standard output for all available widget classes. If arguments are sup- plied, they should be either widget handles, or the widget class names; in this case, the information is written only for the requested set of widgets or widget classes. DtWidgetInfo -c [_w_i_d_g_e_t_C_l_a_s_s] If no arguments are supplied, the list of supported widget class names is written to standard output. If arguments are supplied, dtksh writes the widget class name (if it is defined); otherwise, it writes an error message to standard error. DtWidgetInfo -h [_w_i_d_g_e_t_H_a_n_d_l_e] If no arguments are supplied, the list of active widget handles is written to standard output. If arguments are supplied, they should represent widget handles, in which case the name of the associated widget is written to standard output. Convenience Functions The CDE system includes a file of dtksh convenience func- tions. This file is itself a shell script containing shell functions that may be useful to a shell programmer. The shell functions perform frequently used operations. These include functions for quickly creating certain kinds of dia- logs (help, error, warning and so on), and a function for easily creating a collection of buttons and functions that make it easier to configure the constraint resources for a child of a form widget. It is not a requirement that shell script writers use these convenience functions; they are supplied to make it easier for developers to write shorter and more readable shell scripts. Before a shell script can access these functions, the shell script must first include the file containing the conveni- ence functions. The convenience functions are located in the file /usr/dt/lib/dtksh/DtFuncs.dtsh, and are included in a shell script using the following notation: . /usr/dt/lib/dtksh/DtFuncs.dtsh DtkshAddButtons This convenience function adds one or more buttons of the same kind into a composite widget. Most frequently, it is used to add a collection of buttons into a menupane or SunOS 5.10 Last change: 15 Jul 1994 40 User Commands dtksh(1) menubar. DtkshAddButtons _p_a_r_e_n_t _w_i_d_g_e_t_C_l_a_s_s _l_a_b_e_l_1 _c_a_l_l_b_a_c_k_1 [_l_a_b_e_l_2 _c_a_l_l_b_a_c_k_2 ...] DtkshAddButtons [-_w] _p_a_r_e_n_t _w_i_d_g_e_t_C_l_a_s_s _v_a_r_i_a_b_l_e_1 _l_a_b_e_l_1 _c_a_l_l_b_a_c_k_1 [_v_a_r_i_a_b_l_e_2 _l_a_b_e_l_2 _c_a_l_l_b_a_c_k_2 ...] The -w option indicates that the convenience function should return the widget handle for each of the buttons it creates. The widget handle is returned in the specified environment variable. The _w_i_d_g_e_t_C_l_a_s_s argument can be set to any one of the following, and defaults to XmPushButtonGadget, if not specified: XmPushButton XmPushButtonGadget XmToggleButton XmToggleButtonGadget XmCascadeButton XmCascadeButtonGadget Examples: DtkshAddButtons $MENU XmPushButtonGadget Open do_Open Save \ do_Save Quit exit DtkshAddButtons -w $MENU XmPushButtonGadget B1 Open \ do_Open B2 Save do_Save DtkshSetReturnKeyControls This convenience function configures a text widget (within a form widget), so the key does not activate the default button within the form. Instead, the key moves the focus to the next text widget within the form. This is useful if a window, con- taining a series of text widgets and the default button, should not be activated until the user presses the key while the focus is in the last text widget. DtkshSetReturnKeyControls _t_e_x_t_W_i_d_g_e_t _n_e_x_t_T_e_x_t_W_i_d_g_e_t _f_o_r_m_W_i_d_g_e_t _d_e_f_a_u_l_t_B_u_t_t_o_n The _t_e_x_t_W_i_d_g_e_t argument specifies the widget to be config- ured so it catches the key, and forces the focus to move to the next text widget (as indicated by the _n_e_x_t_T_e_x_t_W_i_d_g_e_t argument). The _f_o_r_m_W_i_d_g_e_t argument specifies the form containing the default button, and must be the parent of the two text widgets. The _d_e_f_a_u_l_t_B_u_t_t_o_n argument indicates which component to treat as the default button within the form widget. SunOS 5.10 Last change: 15 Jul 1994 41 User Commands dtksh(1) Examples: DtkshSetReturnKeyControls $TEXT1 $TEXT2 $FORM $OK DtkshSetReturnKeyControls $TEXT2 $TEXT3 $FORM $OK DtkshUnder, DtkshOver, DtkshRightOf, DtkshLeftOf These convenience functions simplify the specification of certain classes of form constraints. They provide a con- venient way of attaching a component to one edge of another component. They are used when constructing the resource list for a widget. This behavior is accomplished using the ATTACH_WIDGET constraint. DtkshUnder _w_i_d_g_e_t_I_d [_o_f_f_s_e_t] DtkshOver _w_i_d_g_e_t_I_d [_o_f_f_s_e_t] DtkshRightOf _w_i_d_g_e_t_I_d [_o_f_f_s_e_t] DtkshLeftOf _w_i_d_g_e_t_I_d [_o_f_f_s_e_t] The _w_i_d_g_e_t_I_d argument specifies the widget to which the current component is to be attached. The _o_f_f_s_e_t value is optional, and defaults to zero, if not specified. Example: XtCreateManagedWidget BUTTON4 button4 pushButton $FORM \ labelString:"Exit" $(DtkshUnder $BUTTON2) \ $(DtkshRightOf $BUTTON3) DtkshFloatRight, DtkshFloatLeft, DtkshFloatTop, DtkshFloatBot- tom These convenience functions simplify the specification of certain classes of form constraints. They provide a con- venient way of positioning a component, independent of the other components within the form. As the form grows or shrinks, the component maintains its relative position within the form. The component may still grow or shrink, depending on the other form constraints specified for the component. This behavior is accomplished using the ATTACH_POSITION constraint. DtkshFloatRight [_p_o_s_i_t_i_o_n] DtkshFloatLeft [_p_o_s_i_t_i_o_n] DtkshFloatTop [_p_o_s_i_t_i_o_n] DtkshFloatBottom [_p_o_s_i_t_i_o_n] SunOS 5.10 Last change: 15 Jul 1994 42 User Commands dtksh(1) The optional _p_o_s_i_t_i_o_n argument specifies the relative posi- tion to which the indicated edge of the component is posi- tioned. A default position is used, if one is not speci- fied. Example: XtCreateManagedWidgetBUTTON1 button1 pushButton \ $FORM labelString:"Ok" $(DtkshUnder $SEPARATOR) \ $(DtkshFloatLeft 10) $(DtkshFloatRight 40) DtkshAnchorRight, DtkshAnchorLeft, DtkshAnchorTop, DtkshAnchor- Bottom These convenience functions simplify the specification of certain classes of form constraints. They provide a con- venient way of attaching a component to one of the edges of a form widget in such a fashion that, as the form grows or shrinks, the component's position does not change. However, depending on the other form constraints set on this com- ponent, the component may still grow or shrink in size. This behavior is accomplished using the ATTACH_FORM con- straint. DtkshAnchorRight [_o_f_f_s_e_t] DtkshAnchorLeft [_o_f_f_s_e_t] DtkshAnchorTop [_o_f_f_s_e_t] DtkshAnchorBottom [_o_f_f_s_e_t] The optional _o_f_f_s_e_t argument specifies how far from the edge of the form widget the component should be positioned. If an offset is not specified, zero is used. Example: XtCreateManagedWidget BUTTON1 button1 pushButton \ $FORM labelString:"Ok" $(DtkshUnder $SEPARATOR) \ $(DtkshAnchorLeft 10) $(DtkshAnchorBottom 10) DtkshSpanWidth, DtkshSpanHeight These convenience functions simplify the specification of certain classes of form constraints. They provide a con- venient way of configuring a component such that it spans either the full height or width of the form widget. This behavior is accomplished by attaching two edges of the com- ponent (top and bottom for DtkshSpanHeight, and left and right for DtkshSpanWidth) to the form widget. The component typically resizes whenever the form widget is resized. The ATTACH_FORM constraint is used for all attachments. SunOS 5.10 Last change: 15 Jul 1994 43 User Commands dtksh(1) DtkshSpanWidth [_l_e_f_t_O_f_f_s_e_t _r_i_g_h_t_O_f_f_s_e_t] DtkshSpanHeight [_t_o_p_O_f_f_s_e_t _b_o_t_t_o_m_O_f_f_s_e_t] The optional _o_f_f_s_e_t arguments specify how far from the edges of the form widget the component should be positioned. If an offset is not specified, zero is used. Example: XtCreateManagedWidget SEP sep separator $FORM $(DtkshSpanWidth 1 1) DtkshDisplayInformationDialog, DtkshDisplayQuestionDialog, DtkshDisplayWarningDialog, DtkshDisplayWorkingDialog, DtkshDisplayErrorDialog These convenience functions create a single instance of each of the Motif feedback dialogs. If an instance of the requested type of dialog already exists, it is reused. The parent of the dialog is obtained from the environment vari- able, _T_O_P_L_E_V_E_L, which should be set by the calling shell script, and then should not be changed. The handle for the requested dialog is returned in one of the following environment variables: _D_T_K_S_H__E_R_R_O_R__D_I_A_L_O_G__H_A_N_D_L_E _D_T_K_S_H__Q_U_E_S_T_I_O_N__D_I_A_L_O_G__H_A_N_D_L_E _D_T_K_S_H__W_O_R_K_I_N_G__D_I_A_L_O_G__H_A_N_D_L_E _D_T_K_S_H__W_A_R_N_I_N_G__D_I_A_L_O_G__H_A_N_D_L_E _D_T_K_S_H__I_N_F_O_R_M_A_T_I_O_N__D_I_A_L_O_G__H_A_N_D_L_E When attaching callbacks to the dialog buttons, the applica- tion should not destroy the dialog; it should simply unmanage the dialog so that it can be used again later. If it is necessary to destroy the dialog, the associated environment variable should also be cleared, so the conveni- ence function does not attempt to reuse the dialog. DtkshDisplay*Dialog title message [_o_k_C_a_l_l_b_a_c_k _c_l_o_s_e_C_a_l_l_b_a_c_k \ _h_e_l_p_C_a_l_l_b_a_c_k _d_i_a_l_o_g_S_t_y_l_e] The Ok button is always managed, and by default unmanages the dialog. The Cancel and Help buttons are only managed when a callback is supplied for them. The _d_i_a_l_o_g_S_t_y_l_e argu- ment accepts any of the standard resource settings supported by the associated bulletin board resource. Example: DtkshDisplayErrorDialog "Read Error" "Unable to read the file" \ "OkCallback" "CancelCallback" "" DIALOG_PRIMARY_APPLICATION_MODAL SunOS 5.10 Last change: 15 Jul 1994 44 User Commands dtksh(1) DtkshDisplayQuickHelpDialog, DtkshDisplayHelpDialog These convenience functions create a single instance of each of the help dialogs. If an instance of the requested type of help dialog already exists, it is reused. The parent of the dialog is obtained from the environment variable, _T_O_P_L_E_V_E_L, which should be set by the calling shell script, and then should not be changed. The handle for the requested dialog is returned in one of the following environment variables: _D_T_K_S_H__H_E_L_P__D_I_A_L_O_G__H_A_N_D_L_E _D_T_K_S_H__Q_U_I_C_K__H_E_L_P__D_I_A_L_O_G__H_A_N_D_L_E If it is necessary to destroy a help dialog, the application should also clear the associated environment variable, so that the convenience function does not attempt to reuse the dialog. DtkshDisplay*HelpDialog title helpType helpInformation [_l_o_c_a_t_i_o_n_I_d] The meaning of the arguments depends on the value specified for the _h_e_l_p_T_y_p_e argument. The meanings are explained in the following table: _h_e_l_p_T_y_p_e _h_e_l_p_I_n_f_o_r_m_a_t_i_o_n _l_o_c_a_t_i_o_n_I_d ____________________________________________________________________ HELP_TYPE_DYNAMIC_STRING help string HELP_TYPE_FILE help file name HELP_TYPE_MAN_PAGE manual page name HELP_TYPE_STRING help string HELP_TYPE_TOPIC help volume name help topic location ID Example: DtkshDisplayHelpDialog "Help On Dtksh" HELP_TYPE_FILE "helpFileName" Dtksh App-Defaults File The dtksh app-defaults file, named Dtksh, is in a location based on the following path description: /usr/dt/app-defaults/ The only information contained in this app-defaults file is the inclusion of the standard desktop base app-defaults file. The contents of the dtksh app-defaults file is as follows: #include "Dt" Non-String Values The C bindings of the interfaces to X, Xt and Motif include many non-string values defined in headers. For example, the SunOS 5.10 Last change: 15 Jul 1994 45 User Commands dtksh(1) constraint values for a child of a form widget are declared, such as XmATTACH_FORM, with an Xt or Xm prefix followed by a descriptive name. Equivalent values are specified in dtksh by omitting the prefix, just as in an app-defaults file. For example: XmDIALOG_COMMAND_TEXT becomes DIALOG_COMMAND_TEXT; XtATTACH_FORM becomes ATTACH_FORM. A Boolean value can be specified as an argument to a dtksh command using the words True or False; case is not signifi- cant. Return Values From Built-in Commands Graphical commands in dtksh fall into one of four categories, based on the definition of the corresponding C function in a windowing library: 1. The function returns no values. Example: XtMapWidget. 2. The function is void, but returns one or more values through reference arguments. Example: XmGetColors. 3. The function returns a non-Boolean value. Example: XtCreateManagedWidget. 4. The function returns a Boolean value. Example: XtIsSensitive. A category 1 command follows the calling sequence of its corresponding C function exactly; the number and order of arguments can be determined by looking at the standard docu- mentation for the function. Example: XtMapWidget $FORM A category 2 command also generally follows the calling sequence as its corresponding C function. Where a C caller would pass in a pointer to a variable in which a value is returned, the dtksh command returns a value in an environ- ment variable. Example: XmGetColors $FORM $BG FOREGROUND TOPSHADOW BOTTOMSHADOW SELECT echo "Foreground color = " $FOREGROUND A category 3 command differs slightly from its corresponding C function. Where the C function returns its value as the value of the procedure call, a dtksh command requires an additional argument, which is always the first argument, and is the name of an environment variable into which the return value is placed. Example: SunOS 5.10 Last change: 15 Jul 1994 46 User Commands dtksh(1) XmTextGetString TEXT_VALUE $TEXT_WIDGET echo "The value of the text field is "$TEXT_VALUE A category 4 command returns a Boolean value that can be used in a conditional expression, just as with the corresponding C function. If the C function also returns values through reference variables (as in category 2), the dtksh command also uses variable names for the corresponding arguments. Example: if XmIsTraversable $PUSH_BUTTON; then echo "The pushbutton is traversable" else echo "The pushbutton is not traversable" fi Generally, the order and type of arguments passed to a com- mand matches those passed to the corresponding C function, except as noted for category 3 commands. Other exceptions are described in the applicable command descriptions. Widget Handles Where a C function returns a widget handle, the correspond- ing dtksh commands set an environment variable equal to the widget handle. These are category 3 commands; they take as one of their arguments the name of an environment variable in which to return the widget handle. (This is an ASCII string used by dtksh to access the actual widget pointer.) For example, either of the following commands could be used to create a new form widget; in both cases, the widget han- dle for the new form widget is returned in the environment variable _F_O_R_M: XtCreateManagedWidget FORM name XmForm $PARENT XmCreateForm FORM $PARENT name After either of the above commands, $_F_O_R_M can be used to reference the form widget. For instance, to create a label widget within the form widget just created, the following command could be used: XmCreateLabel LABEL $FORM namelabelString:"Hi Mom" \ topAttachment:ATTACH_FORM leftAttachment:ATTACH_FORM There is a special widget handle called NULL, provided for cases where a shell script may need to specify a NULL widget. For example, the following disables the defaultBut- ton resource for a form widget: XtSetValues $FORM defaultButton:NULL SunOS 5.10 Last change: 15 Jul 1994 47 User Commands dtksh(1) Widget Resources Some of the Xt and Motif commands allow the shell script to pass in a variable number of arguments, representing resource and value pairs. This is similar to the _a_r_g_l_i_s_t passed in to the corresponding Xt or Motif C function. Examples of these commands include any of the commands used to create a widget, and the XtSetValues command. In dtksh, resources are specified by a string with the following syn- tax: _r_e_s_o_u_r_c_e:_v_a_l_u_e. The name of the resource is given in the resource portion of the string; it is constructed by taking the corresponding Xt or Motif resource name and omitting the Xt or Xm prefix. The value to be assigned to the resource is given in the value portion of the string. The dtksh utility automati- cally converts the value string to an appropriate internal representation. For example: XtSetValues $WIDGET height:100 width:200 resizePolicy:RESIZE_ANY XmCreateLabel LABEL $PARENT myLabel labelString:"Close Dialog" When widget resources are retrieved using XtGetValues, the return value has the same syntax. For example: XtGetValues $WIDGET height:HEIGHT resizePolicy:POLICY \ sensitive:SENSITIVE echo $HEIGHT echo $POLICY echo $SENSITIVE Certain types of resource values have special representa- tion. These include string tables and bit masks. For instance, the XmList widget allows a string table to be specified both for the items and the selectedItems resources. In dtksh, a string table is represented as a comma-separated list of strings, which is compatible with how Motif handles them from a resource file. When a resource that returns a string table is queried using XtGetValues(3X), the resulting value is again a comma- separated set of strings. A resource that expects a bit mask value to be passed in, expects the mask to be specified as a string composed of the various mask values separated by the ``|'' character. When a resource that returns a bit mask is queried, the return value also is a string representing the enabled bits, separated by the ``|'' char- acter. For example, the following sets the mwmFunctions resource for the _V_e_n_d_o_r_S_h_e_l_l widget class: XtSetValues mwmFunctions MWM_FUNC_ALL|MWM_FUNC_RESIZE Unsupported Resources The dtksh utility supports most of the resources provided by SunOS 5.10 Last change: 15 Jul 1994 48 User Commands dtksh(1) Motif; however, there are certain resources that dtksh does not support. The list of unsupported resources follows. Several of these resources can be specified at widget crea- tion time by using XtSetValues, but cannot be retrieved using XtGetValues; these are indicated by the asterisk (*) following the resource name. All Widget And Gadget Classes: Any font list resource (*) Any pixmap resource (*) _C_o_m_p_o_s_i_t_e: _i_n_s_e_r_t_P_o_s_i_t_i_o_n children _C_o_r_e: accelerators translations (*) colormap _X_m_T_e_x_t: _s_e_l_e_c_t_i_o_n_A_r_r_a_y _s_e_l_e_c_t_i_o_n_A_r_r_a_y_C_o_u_n_t _A_p_p_l_i_c_a_t_i_o_n_S_h_e_l_l: _a_r_g_v _W_M_S_h_e_l_l: _i_c_o_n_W_i_n_d_o_w _w_i_n_d_o_w_G_r_o_u_p _S_h_e_l_l: _c_r_e_a_t_e_P_o_p_u_p_C_h_i_l_d_r_e_n_P_r_o_c _X_m_S_e_l_e_c_t_i_o_n_B_o_x: _t_e_x_t_A_c_c_e_l_e_r_a_t_o_r_s _M_a_n_a_g_e_r, _P_r_i_m_i_t_i_v_e and _G_a_d_g_e_t _S_u_b_c_l_a_s_s_e_s: _u_s_e_r_D_a_t_a _X_m_F_i_l_e_S_e_l_e_c_t_i_o_n_B_o_x: _d_i_r_S_e_a_r_c_h_P_r_o_c _f_i_l_e_S_e_a_r_c_h_P_r_o_c _q_u_a_l_i_f_y_S_e_a_r_c_h_D_a_t_a_P_r_o_c EXIT STATUS See ksh93(1). CONSEQUENCES OF ERRORS See ksh93(1). SunOS 5.10 Last change: 15 Jul 1994 49 User Commands dtksh(1) APPLICATION USAGE Initializing The Toolkit Environment Before any of the Xlib, Xt or Motif commands can be invoked, the shell script must first initialize the Xt toolkit by invoking the XtInitialize command, which returns an applica- tion shell widget. XtInitialize, as with all of the com- mands that return a widget handle, returns the widget handle in the environment variable named in its first argument. For example: XtInitialize TOPLEVEL myShellName Dtksh $0$@ Shell script writers should invoke the XtInitialize command as one of the first commands within a dtksh shell script. This allows dtksh to locate its message catalog and the correct app-defaults file. If a shell error occurs before XtInitialize has been called, it is possible that unlocal- ized error messages may be displayed. The dtksh utility provides a default app-defaults file to use if the call to XtInitialize specifies an application class name of _D_t_k_s_h. This app-defaults file loads in the standard set of desktop application default values, so that these applications have a consistent look with other desktop applications. Responding to a Window Manager Close Notice When the user selects the Close item on the window manager menu for an application, the application is terminated unless it has arranged to catch the Close notification. Multiple windows managed by the application disappear, and application data may be left in an undesirable state. To avoid this, dtksh provides for catching and handling the Close notification. The application must: +o Define a procedure to handle the Close notification +o Request notification when Close is selected and over- ride the response, so the application is not shut down The following code illustrates this processing: # This is the `callback' invoked when the user selects # the `Close' menu item WMCallback() { echo "User has selected the Close menu item" } # Create the toplevel application shell XtInitialize TOPLEVEL test Dtksh "$@" XtDisplay DISPLAY $TOPLEVEL # Request notification when the user selects the `Close' # menu item XmInternAtom DELETE_ATOM $DISPLAY "WM_DELETE_WINDOW" false SunOS 5.10 Last change: 15 Jul 1994 50 User Commands dtksh(1) XmAddWMProtocolCallback $TOPLEVEL $DELETE_ATOM "WMCallback" # Ask Motif to not automatically close down your # application window XtSetValues $TOPLEVEL deleteResponse:DO_NOTHING Responding to a Session Management Save State Notice Session management facilities allow applications to save their current state when the user terminates the current session, so that when the user later restarts the session, an application returns to the state it was in. In dtksh this is accomplished by setting up a handler analogously to handling a Close notification. If no such handler is set up, the application has to be restarted manually in the new session, and does not retain any state. To set up a handler to save state, the application must do the following: +o Define functions to save state at end-of-session, and restore it on start-up. +o Register interest in the session management notifica- tion. +o Register the function to save state. +o Determine if saved state should be restored at start- up. The following code illustrates this process: #! /usr/dt/bin/dtksh # Function invoked when the session is being ended by the user SessionCallback() { # Get the name of the file into which we should save our # session information if DtSessionSavePath $TOPLEVEL PATH SAVEFILE; then exec 9>$PATH # Save off whether we are currently in an iconified state if DtShellIsIconified $TOPLEVEL ; then print -u9 `Iconified' else print -u9 `Deiconified' fi # Save off the list of workspaces we currently reside in if DtWsmGetWorkspacesOccupied $(XtDisplay "-" $TOPLEVEL) $(XtWindow "-" $TOPLEVEL) CURRENT_WS_LIST ; then # Map the comma-separated list of atoms into # their string representation oldIFS=$IFS IFS="," SunOS 5.10 Last change: 15 Jul 1994 51 User Commands dtksh(1) for item in $CURRENT_WS_LIST; do XmGetAtomName NAME $(XtDisplay "-" $TOPLEVEL) $item print -u9 $NAME done IFS=$oldIFS fi exec 9<&- # Let the session manager know how to invoke us when # the session is restored DtSetStartupCommand $TOPLEVEL "/usr/dt/contrib/dtksh/SessionTest $SAVEFILE" else echo "DtSessionSavePath FAILED!!" exit -3 fi } # Function invoked during a restore session; restores the # application to its previous state RestoreSession() { # Retrieve the path where our session file resides if DtSessionRestorePath $TOPLEVEL PATH $1; then exec 9<$PATH read -u9 ICONIFY # Extract and restore our iconified state case $ICONIFY in Iconified) DtSetIconifyHint $TOPLEVEL True;; *) DtSetIconifyHint $TOPLEVEL False; esac # Extract the list of workspaces we belong in, convert # them to atoms, and ask the workspace manager to relocate # us to those workspaces WS_LIST="" while read -u9 NAME do XmInternAtom ATOM $(XtDisplay "-" $TOPLEVEL) $NAME False if [ ${#WS_LIST} -gt 0 ]; then WS_LIST=$WS_LIST,$ATOM else WS_LIST=$ATOM fi done DtWsmSetWorkspacesOccupied $(XtDisplay "-" $TOPLEVEL) $(XtWindow "-" $TOPLEVEL) $WS_LIST exec 9<&- else echo "DtSessionRestorePath FAILED!!" exit -3 fi SunOS 5.10 Last change: 15 Jul 1994 52 User Commands dtksh(1) } ################## Create the Main UI ####################### XtInitialize TOPLEVEL wmProtTest Dtksh "$@" XtCreateManagedWidget DA da XmDrawingArea $TOPLEVEL XtSetValues $DA height:200 width:200 XmInternAtom SAVE_SESSION_ATOM $(XtDisplay "-" $TOPLEVEL) "WM_SAVE_YOURSELF" False # If a command-line argument was supplied, then treat it as the # name of the session file if (( $# > 0)) then # Restore to the state specified in the passed-in session file XtSetValues $TOPLEVEL mappedWhenManaged:False XtRealizeWidget $TOPLEVEL XSync $(XtDisplay "-" $TOPLEVEL) False RestoreSession $1 XtSetValues $TOPLEVEL mappedWhenManaged:True XtPopup $TOPLEVEL GrabNone else # This is not a session restore, so come up in the default state XtRealizeWidget $TOPLEVEL XSync $(XtDisplay "-" $TOPLEVEL) False fi # Register the fact that we are interested in participating in # session management XmAddWMProtocols $TOPLEVEL $SAVE_SESSION_ATOM XmAddWMProtocolCallback $TOPLEVEL $SAVE_SESSION_ATOM SessionCallback XtMainLoop Cooperating with WorkSpace Management The dtksh utility provides access to all of the major workspace management functions of the desktop libraries, including functions for: +o Querying and setting the set of workspaces with which an application is associated. +o Querying the list of all workspaces. +o Querying and setting the current workspace. +o Requesting that an application be notified any time the user changes to a different workspace. From a user's perspective, workspaces are identified by a set of names, but from the workspace manager's perspective, workspaces are identified by X atoms. Whenever the shell script asks for a list of workspace identifiers, a string of X atoms is returned; if more than one X atom is present, the list is comma-separated. SunOS 5.10 Last change: 15 Jul 1994 53 User Commands dtksh(1) The workspace manager expects that the shell script uses the same format when passing workspace identifiers back to it. During a given session, it is safe for the shell script to work with the X atoms since they remain constant over the lifetime of the session. However, as was shown in the Ses- sion Management shell script example, if the shell script is going to save and restore workspace identifiers, the workspace identifiers must be converted from their X atom representation to a string before they are saved. Then, when the session is restored, the shell script needs to remap the names into X atoms before passing the information on to the workspace manager. Mapping between X atoms and strings and between strings and X atoms uses the following two commands: XmInternAtom ATOM $DISPLAY $WORKSPACE_NAME false XmGetAtomName NAME $DISPLAY $ATOM Creating Localized Shell Scripts Scripts written for dtksh are internationalized, and then localized, in a process very similar to C applications. All strings that may be presented to the user are identified in the script; a post-processor extracts the strings from the script, and from them builds a catalog, which can then be translated to any desired locale. When the script executes, the current locale determines which message catalog is searched for strings to display. When a string is to be presented, it is identified by a message-set ID (correspond- ing to the catalog), and a message number within the set; these values determine what text the user sees. The follow- ing code illustrates the process: # Attempt to open our message catalog catopen MSG_CAT_ID "myCatalog.cat" # The localized button label is in set 1, and is message # 2 XtCreatePushButton OK $PARENT ok labelString:$(catgets $MSG_CAT_ID 1 2 "OK") # The localized button label is in set 1, and is message #3 XtCreatePushButton CANCEL $PARENT cancel labelString:$(catgets $MSG_CAT_ID 1 3 "Cancel") # Close the message catalog, when no longer needed catclose $MSG_CAT_ID The file descriptor returned by catopen must be closed using catclose, and not using the sh exec command. Using the dtksh Utility to Access X Drawing Functions The commands of the dtksh utility include standard Xlib drawing functions to draw lines, points, segments, rectan- gles, arcs and polygons. In the standard C programming environment, these functions take a graphics context, or GC as an argument, in addition to the drawing data. In dtksh SunOS 5.10 Last change: 15 Jul 1994 54 User Commands dtksh(1) drawing functions, a collection of GC options are specified in the argument list to the command. By default, the draw- ing commands create a GC that is used for that specific com- mand and then discarded. If the script specifies the -gc option, the name of the graphics context object can be passed to the command; this GC is used in interpreting the command, and the variable is updated with any modifications to the GC performed by the command. -gc _G_C _G_C is the name of an environment variable that has not yet been initialized, or which has been left holding a graphic context by a previous drawing command. If this option is specified, it must be the first _G_C option specified. -foreground _c_o_l_o_r Foreground color, which can be either the name of a color or a pixel number. -background _c_o_l_o_r Background color, which can be either the name of a color or a pixel number. -font _f_o_n_t _n_a_m_e Name of the font to be used. -line_width _n_u_m_b_e_r Line width to be used during drawing. -function _d_r_a_w_i_n_g _f_u_n_c_t_i_o_n Drawing function, which can be any of the follow- ing: xor, or, clear, and, copy, noop, nor, nand, set, invert, equiv, andReverse, orReverse or copy- Inverted. -line_style _s_t_y_l_e Line style, which can be any of the following: LineSolid, LineDoubleDash or LineOnOffDash. Setting Widget Translations: The dtksh utility provides mechanisms for augmenting, over- riding and removing widget translations, much as in the C programming environment. In C, an application installs a set of translation action procedures, which can then be attached to specific sequences of events (translations are composed of an event sequence and the associated action pro- cedure). Translations within dtksh are handled in a similar fashion, except only a single action procedure is available. This action procedure, named _k_s_h__e_v_a_l, interprets any argu- ments passed to it as dtksh commands, and evaluates them when the translation is triggered. The following shell SunOS 5.10 Last change: 15 Jul 1994 55 User Commands dtksh(1) script segment gives an example of how translations can be used: BtnDownProcedure() { echo "Button Down event occurred in button "$1 } XtCreateManagedWidget BUTTON1 button1 XmPushButton $PARENT labelString:"Button 1" translations:'#augment :ksh_eval("echo Button1 entered") :ksh_eval("BtnDownProcedure 1")' XtCreateManagedWidget BUTTON2 button2 XmPushButton $PARENT labelString:"Button 2" XtOverrideTranslations $BUTTON2 '#override :ksh_eval("BtnDownProcedure 2")' EXAMPLES None. SEE ALSO sh(1), ksh93(1). SunOS 5.10 Last change: 15 Jul 1994 56