ncarg_gescape(3)

1GESCAPE(3NCARG)                  NCAR GRAPHICS                 GESCAPE(3NCARG)
2
3
4

NAME

6       gescape  (Escape) - provides a standard way of implementing nonstandard
7       GKS features.  NCAR GKS has only two user-accessible  escape  functions
8       defined:  one for changing the name of a metafile and another for paus‐
9       ing in an X window.
10

SYNOPSIS

12       #include <ncarg/gks.h>
13
14       void  gescape(Gint  func_id,  const  Gescape_in_data  *in_data,  Gstore
15       *store_data,Gescape_out_data **out_data);
16

DESCRIPTION

18       func_id     (Input)  -  A  function identifier specifying the requested
19                   activity.  The legal values for  func_id  are  "-1391"  for
20                   changing  a metafile name and "-1396" for effecting a pause
21                   in an X window.
22
23       in_data.escape_r1.size
24                   (size_t, Input) - Size of the input data record array  (for
25                   input data record, see below).
26
27       in_data.escape_r1.data
28                   (void  *, Input) - Input data record.  For calls to gescape
29                   with func_id equal to -1391 the input data record should be
30                   a  character  string  containing  the desired metafile name
31                   left justified and blank filled; for calls to gescape  with
32                   func_id  equal  to  -1396 the input data record should be a
33                   character  string  containing  the  workstation  identifier
34                   encoded as a five character number.
35
36       store_data  (void  *,  Input) - Storage for output data.  Not currently
37                   in use for NCAR GKS.
38
39       out_data.escape_r1.size
40                   (size_t, Output) - Size of the output  data  record  array.
41                   Not currently in use for NCAR GKS.
42
43       out_data.escape_r1.data
44                   (void *, Output) -  Output data record.    Not currently in
45                   use for NCAR GKS.
46

USAGE

48       The sizes of the data records must always be at least "1" in value.
49

EXAMPLES

51       gescape can be used  to  dynamically  change  the  name  of  an  output
52       metafile  and  to do so one should use the calls gopen_gks and gopen_ws
53       instead of c_opngks.  If you are using c_opngks, see the man  page  for
54       setusv(3NCARG) for changing the name of the metafile.
55
56       To  change  the  name  of  the output metafile inside your program, you
57       should make a call similar to the following:
58
59              int str_len = 12;
60              Gescape_in_data in_data;
61              gopen_gks("stdout",0);
62              in_data.escape_r1.data = (Gdata *)malloc(str_len*sizeof(char));
63              strcpy(in_data.escape_r1.data, "new.cgm.name" );
64              in_data.escape_r1.size = str_len;
65              gescape(-1391,&in_data,NULL,NULL);
66
67       The call to gescape to change the metafile name must always occur  just
68       before  the call to gopen_ws that opens a CGM workstation.  Setting the
69       environment variable NCARG_GKS_OUTPUT overrides any attempt  to  change
70       the name of an output metafile via a gescape call.
71
72       See  the  "User's  Guide  for NCAR GKS-0A Graphics" for a more complete
73       example of changing metafile names from within a code.
74
75       Here is an example of a piece of code that will  create  an  X  window,
76       draw a line, and then pause waiting for a mouse click or a key click.
77
78              Gescape_in_data in_data;
79              int str_len = 5;
80
81              gopen_gks("stdout",0);
82              gopen_ws(3,NULL,8);
83              gactivate_ws(3);
84              c_line(0.,0.,1.,1.);
85              c_sflush();
86              in_data.escape_r1.data = (Gdata *)malloc(str_len*sizeof(char));
87              strcpy(in_data.escape_r1.data, "    3" );
88              in_data.escape_r1.size = str_len;
89              gescape(-1396,&in_data,NULL,NULL);
90
91              gdeactivate_ws(3);
92              gclose_ws(3);
93              gclose_gks();
94
95
96
97       The  functions  c_frame  and c_ngpict are in general much easier to use
98       and more flexible than the direct ESCAPE call for pausing in an X  win‐
99       dow.  It is suggested that those functions be used.
100

ACCESS

102       To  use  the  GKS  C-binding  routines,  load the ncarg_gks and ncarg_c
103       libraries.
104

COPYRIGHT

113       Copyright (C) 1987-2007
114       University Corporation for Atmospheric Research
115
116       This documentation is free software; you  can  redistribute  it  and/or
117       modify  it  under  the  terms of the GNU General Public License as pub‐
118       lished by the  Free  Software  Foundation;  either  version  2  of  the
119       License, or (at your option) any later version.
120
121       This  software  is  distributed in the hope that it will be useful, but
122       WITHOUT ANY  WARRANTY;  without  even  the  implied  warranty  of  MER‐
123       CHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
124       Public License for more details.
125
126       You should have received a copy of the GNU General Public License along
127       with  this  software;  if  not,  write to the Free Software Foundation,
128       Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
129
130
131
132UNIX                              March 1993                   GESCAPE(3NCARG)