1 03/19/85  ft_menu_
  2 
  3 
  4 The ft_menu_ subroutine allows a FORTRAN program to use the Multics
  5 menu facility (menu_).  Through ft_menu_ a FORTRAN program may create a
  6 menu object, display the menu, and get a user-entered selection from a
  7 menu.  Once a menu object has been created, the FORTRAN program can use
  8 this menu object by referencing it via a menu-id returned to the caller
  9 when the menu object was created or when a stored menu object was
 10 retrieved.
 11 
 12 The functionality available is provided through the various entry
 13 points defined below.
 14 
 15 
 16 Entry points in ft_menu_:
 17    (List is generated by the help command)
 18 
 19 
 20 :Entry:  create:  03/19/85 ft_menu_$create
 21 
 22 
 23 Function:  Utilized to create a menu object.  It returns a menu
 24 identifier (menu_id) which is subsequently used to reference the menu
 25 object.
 26 
 27 
 28 Syntax:
 29    declarations:
 30      character*n1  choices(m1)
 31      character*n2  headers(m2)
 32      character*n3  trailers(m3)
 33      character*1   keys(m4)
 34      character*1   pad_char
 35      integer       menu_format(6)
 36      integer       menu_needs(3)
 37      integer       menu_id
 38      integer       code
 39 call ft_menu_$create (choices, headers, trailers, pad_char,
 40      menu_format, key, menu_needs, menu_id, code)
 41 
 42 
 43 Arguments:
 44 choices
 45    is an array of character variables which are the text of the options
 46    that  the user  wishes to  display in the  menu.  (Input)  n1 is the
 47    length,  in characters,  of the longest  character string comprising
 48    the text  of an option.   m1 is the  extent of the  array, i.e., the
 49    number of options  in the menu being described.   This array must be
 50    at least of extent 1.
 51 headers
 52    is an array of character variables to be displayed at the top of the
 53    menu.   (Input)  n2 is  the  length, in  characters, of  the longest
 54    header specified.  m2  is the extent of the  array, i.e., the number
 55    of headers (lines)  desired.  At least one header  must be specified
 56    (if the first variable is set to blanks, no headers will be used).
 57 
 58 
 59 trailers
 60    is  an  array of  trailers (displayed  immediately below  the menu).
 61    (Input) n3, m3, are analogous to n2, m2 respectively.
 62 menu_format
 63    is an array,  which specifies the format of  the menu being created.
 64    (Input) Prior to calling this entry point, the FORTRAN programmer is
 65    responsible for setting the following variables:
 66       menu_format(menu_version) = version number of menu_
 67               (currently, only version 1 is defined).
 68       menu_format(max_width) = maximum width of the window
 69                on which the menu will be displayed.
 70       menu_format(max_heigth) = maximum height of window
 71                 on which menu is to be displayed.
 72       menu_format(no_of_columns) = number of columns to be used
 73                 by the menu manager to display the options.
 74       menu_format(center_headers) = 0 or 1;  0 = no, 1 = yes.
 75       menu_format(center_trailers) = 0 or 1;  0 = no, 1 = yes.
 76 
 77 
 78 pad_char
 79    is the  character that the  menu facility will display  at the right
 80    and  left of  a centered  header or  trailer to  fill out  the line.
 81    (Input)
 82 keys
 83    is  an  array  (maximum  value  of m4  is  61)  that  identifies the
 84    keystroke  to be  associated with  each choice.   (Input) This array
 85    must be at least as long as the number of choices in the menu.  Each
 86    element in the array must be unique.
 87 menu_needs
 88    an  array  that  contains  menu  related  information  on successful
 89    execution of call.  (Output)
 90 
 91 
 92       Returned information:
 93 
 94       menu_needs(lines_needed)  the number of lines required
 95                                 to display the menu.
 96       menu_needs(width_needed)  the number of columns required
 97                                 to display the menu.
 98       menu_needs(no_of_options) the number of options defined
 99                                 in the menu.
100 
101 
102 menu_id
103    the menu identifier (i.e.,  the menu object "identifier").  (Output)
104    It must not be altered in any way by the application program.
105 code
106    return code.  (Output)
107 
108 
109 :Entry:  delete:  03/19/85 ft_menu_$delete
110 
111 
112 Function:   Deletes a  menu object  from a  given value  segment.  (See
113 ft_menu_$store.)
114 
115 
116 Syntax:
117    declarations:
118      character*168  dir_name
119      character*32   entry_name
120      character*32   menu_name
121      integer        code
122    call ft_menu_$delete (dir_name, entry_name, menu_name, code)
123 
124 
125 Arguments:
126 dir_name
127    pathname of the directory containing the menu object.  (Input)
128 entry_name
129    entry name of value segment containing the menu object.  (Input) The
130    suffix "value" need not be specified.
131 menu_name
132    name  used  to identify  the menu  object when  the menu  object was
133    stored.  (Input)
134 code
135    return code.  (Output)
136 
137 
138 :Entry:  describe:  03/19/85 ft_menu_$describe
139 
140 
141 Function:   Returns information  about a  menu object.   It returns the
142 number  of  options in  the menu,  the  number of  lines and  number of
143 columns  required  to  display  the  menu.   It  is  primarily  used to
144 determine if the menu can be displayed in a given window.
145 
146 
147 Syntax:
148    declarations:
149      integer  menu_id
150      integer  menu_needs(3)
151      integer  code
152    call ft_menu_$describe (menu_id, menu_needs, code)
153 
154 
155 
156 Arguments:
157 menu_id
158    the    menu    identifier    returned    by    ft_menu_$create    or
159    ft_menu_$retrieve.  (Input)
160 menu_needs
161    an array into which menu related information is returned.  (Output)
162 
163 
164       Returned information:
165       menu_needs(lines_needed)       the number of lines required
166                                      to display the menu.
167 
168       menu_needs(width_needed)       the number of columns needed
169                                      to display the menu.
170 
171       menu_needs(no_of_options)      the number of options defined
172                                      in the menu.
173 code
174    return code.  (Output)
175 
176 
177 :Entry:  destroy:  03/19/85 ft_menu_$destroy
178 
179 
180 Function:  Invoked  to delete a  menu object from storage.   (Not to be
181 confused  with ft_menu_$delete,  which deletes  the menu  object from a
182 value segment.)  Deleting  the menu object has no  effect on the screen
183 contents.
184 
185 
186 Syntax:
187    declarations:
188      integer  menu_id
189      integer  code
190    call ft_menu_$destroy (menu_id, code);
191 
192 
193 
194 Arguments:
195 menu_id
196    menu  identifier returned  by ft_menu_$create  or ft_menu_$retrieve.
197    (Input/Output) Set to an invalid value  on return to prevent the old
198    menu_id from being accidentally used.
199 code
200    return code.  (Output)
201 
202 
203 :Entry:  display:  03/19/85 ft_menu_$display
204 
205 
206 Function:  Invoked to display a menu in a given window.
207 
208 
209 Syntax:
210    declarations:
211      integer  window_id
212      integer  menu_id
213      integer  code
214    call ft_menu_$display (window_id, menu_id, code)
215 
216 
217 Arguments:
218 window_id
219    a  window  identifier  returned  by  ft_window_$create.   (Input) If
220    usage_mode = 0 this argument will be ignored (see ft_menu_$init2).
221 menu_id
222    menu  identifier  returned  when  the  menu  object  was  created or
223    retrieved.  (Input)
224 code
225    return code.  (Output)
226 
227 
228 :Entry:  get_choice:  03/19/85 ft_menu_$get_choice
229 
230 
231 Function:   Returns  the  choice made  by  the user,  i.e.,  an integer
232 representing either  the menu item  chosen or the function  key (or its
233 equivalent escape sequence) entered.
234 
235 
236 Syntax:
237    declarations:
238      character*n1  function_key_info
239      integer       window_id
240      integer       menu_id
241      integer       fkeys
242      integer       selection
243      integer       code
244    call ft_menu_$get_choice (window_id, menu_id, function_key_info,
245           fkeys, selection, code)
246 
247 
248 Arguments:
249 window_id
250    a  window  identifier  returned  by  ft_window_$create.   (Input) If
251    usage_mode = 0 this argument will be ignored.  (see ft_menu_$init2)
252 menu_id
253    menu  identifier returned  by ft_menu_$create  or ft_menu_$retrieve.
254    (Input)
255 
256 
257 function_key_info
258    a character  variable (n1 as  required) used to specify  the role of
259    function  keys (if  they exist  for the  terminal being  used) or an
260    equivalent  set of  escape sequences if  the terminal  does not have
261    function keys or not the  function keys required by the application.
262    (Input) The objective  is to let the application  use the terminal's
263    function keys if possible, else specify  key sequences to be used to
264    simulate function keys.  Each character in the string corresponds to
265    one  function key.   If the  character is  a space,  then it  is not
266    relevant if  the corresponding function  key exists or  not.  If the
267    character is not a space, that  character will be used to simulate a
268    function key  if the terminal  does not have function  keys.  If the
269    terminal does not have a  function key for every non-space character
270    in  the string,  then function  keys will  be simulated.   Thus, the
271    string  " ?p  q" means  that the  caller does  not care  whether the
272    terminal has  function key 0 or  3, but the caller  does wish to use
273    function keys  1,2, and 4.  If  any of these 3  function keys is not
274    present on the  terminal, then esc-?  will substitute  for F1, esc-p
275    will substitute for F2, and esc-q will substitute for F4.
276 
277 
278 fkeys
279    if fkeys = 1 user entered a function key or escape sequence if fkeys
280    = 0 user selected an option (Output)
281 selection
282    is an integer representing the choice made by the user.  (Output) If
283    the  user has  chosen an option,  it is  a number between  1 and the
284    highest defined option.  If the user  has entered a function key, or
285    escape  sequence  simulating  a  function  key,  it  is  the  number
286    associated with the function key.
287 code
288    return code.  (Output)
289 
290 
291 :Entry:  init1:  init2:  03/19/85 ft_menu_$init1, ft_menu_$init2
292 
293 
294 Function:   These must  be the  first calls  made to  the menu manager.
295 They  set up  the necessary  environment for  the menu  application and
296 return information concerning the user i/o window.
297 
298 
299 Syntax:
300    declarations:
301      integer   code
302      integer   usage_mode
303    call ft_menu_$init1 ()
304    call ft_menu_$init2
305         (usage_mode,user_window_lines,user_window_columns,
306         user_window_id,code)
307 
308 
309 Arguments:
310 usage_mode
311    usage_mode = 0 means that the caller  does not wish to do any window
312    management at  all.  (Input) When  he/she wishes to  display a menu,
313    the window required will be  automatically created.  This means that
314    the  application  will  operate in  a  two window  mode,  the window
315    containing the menu,  and the user_io window.  Both  windows will be
316    managed  automatically  for the  user.  If  the user  specifies this
317    mode,  all calls  to the ft_window_  subroutine will  be ignored and
318    will  return  an appropriate  error code.
319    All  calls to  the ft_menu_  subroutine that
320    require a window identifier will ignore the user provided window_id.
321    usage_mode = 1  means that the user wishes to  define the number and
322    characteristics of the windows to be used in the application.  Thus,
323    calls to ft_window_  will be supported and, for  the entry points of
324    ft_menu_  that require  a window identifier,  the caller  must use a
325    legal window_id (returned by ft_window_$create).
326 
327 
328 user_window_lines
329    the number  of lines (rows) in  the user i/o window  at the time the
330    user invokes ft_menu_$init (which must be the first call to the menu
331    manager in the application).  (Output) Undefined if usage_mode = 0.
332 user_window_columns
333    the  number of  columns of  the user  i/o window  when ft_menu_$init
334    invoked.  (Output) Undefined if usage_mode = 0.
335 user_window_id
336    window  identifier of  the user  i/o window.   (Output) Undefined if
337    usage_mode = 0.
338 code
339    return code.  (Output)
340 
341 
342 :Entry:  list:  03/19/85 ft_menu_$list
343 
344 
345 Function:   Used to  list the menu  object(s) stored  in value segment.
346 The names selected are those that match a user provided string.
347 
348 
349 Syntax:
350    declarations:
351      character*168  dir_name
352      character*32   names_array(m1)
353      character*32   entry_name
354      character*32   match_string
355      integer        no_of_matches
356      integer        code
357    call ft_menu_$list (dir_name, entry_name, match_string,
358         no_of_matches, names_array, code)
359 
360 
361 Arguments:
362 dir_name
363    pathname of directory containing the menu object.  (Input)
364 entry_name
365    entry name of value segment containing the menu object.  (Input) The
366    suffix "value" need not be specified.
367 match_string
368    a character variable that is to be used as the selection criteria to
369    determine what  menu object, if  any, is contained  in the specified
370    value segment that  match (or contain) this string.   (Input) If set
371    to space(s), all names returned.
372 
373 
374 no_of_matches
375    the number of matches found.  (Output) If none, then is is 0.
376 names_array
377    an array, of extent m1.  (Output)  The user should insure that m1 is
378    sufficiently  large  to  contain  all  matches  that  may  be found.
379    Contains  the  names of  all  menu objects,  in the  specified value
380    segment, that match the character string match_string.
381 code
382    return code.  (Output)
383 
384 
385 :Entry:  retrieve:  03/19/85 ft_menu_$retrieve
386 
387 
388 Function:   Used to  retrieve a menu  object previously  stored via the
389 ft_menu_$store.  Once retrieved, the user can reference the menu object
390 via the menu identifier (menu_id).
391 
392 
393 Syntax:
394    declarations:
395      character*168  dir_name
396      character*32   entry_name
397      character*32   menu_name
398      integer        menu_id
399      integer        code
400    call ft_menu_$retrieve (dir_name, entry_name, menu_name, menu_id,
401        code)
402 
403 
404 Arguments:
405 dir_name
406    pathname of the directory containing the menu object.  (Input)
407 entry_name
408    entry  name of  value segment  containing menu  object.  (Input) The
409    suffix "value" need not be specified.
410 menu_name
411    name of the menu object used when the object was stored.  (Input)
412 menu_id
413    is the  menu id returned  by the call.   (Output) It is  used as the
414    menu object identifier.
415 code
416    return code.  (Output)
417 
418 
419 :Entry:  store:  03/19/85 ft_menu_$store
420 
421 
422 Function:  Used to store a menu object in a specified value segment.
423 
424 
425 Syntax:
426    declarations:
427      character*168  dir_name
428      character*32   entry_name
429      character*32   menu_name
430      integer        create_seg
431      integer        menu_id
432      integer        code
433    call ft_menu_$store (dir_name,entry_name, menu_name, create_seg,
434         menu_id, code)
435 
436 
437 Arguments:
438 dir_name
439    pathname of  directory into which  the menu object is  to be placed.
440    (Input)
441 entry_name
442    entry  name of  value segment  into which the  menu object  is to be
443    placed.  (Input) The suffix "value" need not be specified.
444 menu_name
445    it is the name to be assigned to the stored menu object.  (Input)
446 
447 
448 create_seg
449    create_seg  = 0  means do not  store if value  segment identified by
450    entry_name does not already exist.  (Input)
451    create_seg =  1 means create  value segment, if it  does not already
452    exist, and store menu object in it.
453 menu_id
454    it is  the menu object  identifier returned when  ft_menu_$create or
455    ft_menu_$retrieve was called.  (Input)
456 code
457    return code.  (Output)
458 
459 
460 :Entry:  terminate:  03/19/85 ft_menu_$terminate
461 
462 
463 Function:   Must  be the  last call  to  the menu  manager in  the menu
464 application.   It  will  remove  the  special  environment  created  by
465 ft_menu_$init1 and ft_menu_$init2.
466 
467 
468 Syntax:
469    declarations: none
470    call ft_menu_$terminate ()