1cdk_swindow(3)             Library Functions Manual             cdk_swindow(3)
2
3
4

NAME

6       cdk_swindow - a curses scrolling window widget.
7

SYNOPSIS

9       cc [ flag ... ] file ...  -lcdk [ library ... ]
10
11       #include <cdk.h>
12
13       void activateCDKSwindow (
14                      CDKSWINDOW *swindow,
15                      chtype * actions);
16
17       void addCDKSwindow (
18                      CDKSWINDOW *swindow,
19                      const char *info,
20                      int insertPosition);
21
22       void cleanCDKSwindow (
23                      CDKSWINDOW *swindow);
24
25       int execCDKSwindow (
26                      CDKSWINDOW *swindow,
27                      const char * command,
28                      int insertPosition);
29
30       void destroyCDKSwindow (
31                      CDKSWINDOW *swindow);
32
33       void drawCDKSwindow (
34                      CDKSWINDOW *swindow,
35                      boolean box);
36
37       void dumpCDKSwindow (
38                      CDKSWINDOW *swindow,
39                      const char *filename);
40
41       void eraseCDKSwindow (
42                      CDKSWINDOW *swindow);
43                      void execCDKSwindow (
44                      CDKSWINDOW *swindow,
45                      char *command,
46                      int insertPosition);
47                      boolean getCDKSwindowBox (
48                      CDKSWINDOW *swindow);
49
50       chtype **getCDKSwindowContents (
51                      CDKSWINDOW *swindow);
52
53       int injectCDKSwindow (
54                      CDKSWINDOW *swindow,
55                      chtype input);
56
57       void jumpToLineCDKSwindow (
58                      CDKSWINDOW *swindow,
59                      int line);
60
61       void loadCDKSwindowInformation (
62                      CDKSWINDOW *swindow);
63
64       void moveCDKSwindow (
65                      CDKSWINDOW *swindow,
66                      int xpos,
67                      int ypos,
68                      boolean relative,
69                      boolean refresh);
70
71       CDKSWINDOW *newCDKSwindow (
72                      CDKSCREEN *cdkscreen,
73                      int xpos,
74                      int ypos,
75                      int height,
76                      int width,
77                      const char *title,
78                      int saveLines,
79                      boolean box,
80                      boolean shadow);
81
82       void positionCDKSwindow (
83                      CDKSWINDOW *swindow);
84
85       void saveCDKSwindowInformation (
86                      CDKSWINDOW *swindow);
87
88       void setCDKSwindow (
89                      CDKSWINDOW *swindow,
90                      CDK_CONST char **info,
91                      int lines,
92                      boolean box);
93
94       void setCDKSwindowBackgroundAttrib (
95                      CDKSWINDOW *swindow,
96                      chtype attribute);
97
98       void setCDKSwindowBackgroundColor (
99                      CDKSWINDOW *swindow,
100                      const char * color);
101
102       void setCDKSwindowBox (
103                      CDKSWINDOW *swindow,
104                      boolean boxWidget);
105
106       void setCDKSwindowBoxAttribute (
107                      CDKSWINDOW *swindow,
108                      chtype character);
109
110       void setCDKSwindowContents (
111                      CDKSWINDOW *swindow,
112                      char **info,
113                      int lines);
114
115       void setCDKSwindowHorizontalChar (
116                      CDKSWINDOW *swindow,
117                      chtype character);
118
119       void setCDKSwindowLLChar (
120                      CDKSWINDOW *swindow,
121                      chtype character);
122
123       void setCDKSwindowLRChar (
124                      CDKSWINDOW *swindow,
125                      chtype character);
126
127       void setCDKSwindowPostProcess (
128                      CDKSWINDOW *swindow,
129                      PROCESSFN callback,
130                      void * data);
131
132       void setCDKSwindowPreProcess (
133                      CDKSWINDOW *swindow,
134                      PROCESSFN callback,
135                      void * data);
136
137       void setCDKSwindowULChar (
138                      CDKSWINDOW *swindow,
139                      chtype character);
140
141       void setCDKSwindowURChar (
142                      CDKSWINDOW *swindow,
143                      chtype character);
144
145       void setCDKSwindowVerticalChar (
146                      CDKSWINDOW *swindow,
147                      chtype character);
148
149       void trimCDKSwindow (
150                      CDKSWINDOW *swindow,
151                      int start,
152                      int finish);
153

DESCRIPTION

155       The  Cdk  scrolling window (swindow) widget can be used to display mes‐
156       sages.  The following functions create or manipulate  the  Cdk  swindow
157       box widget.
158

AVAILABLE FUNCTIONS

160       activateCDKSwindow
161            function  activates  the swindow widget and lets the user interact
162            with the widget.
163
164            ·   The parameter swindow is a pointer to a non-NULL swindow  wid‐
165                get.
166
167            ·   If  the actions parameter is passed with a non-NULL value, the
168                characters in the array will be injected into the widget.
169
170                To activate the widget interactively pass in  a  NULL  pointer
171                for actions.
172
173            If  the  character  entered into this widget is RETURN or TAB then
174            this function will return 1.  It will also  set  the  widget  data
175            exitType to vNORMAL.
176
177            If the character entered into this widget was ESCAPE then the wid‐
178            get will return a value of -1 and the widget data exitType will be
179            set to vESCAPE_HIT.
180
181       addCDKSwindow
182            adds information to a scrolling window.
183
184            ·   The information is supplied by the info parameter.  The infor‐
185                mation is immediately added to the scrolling window.
186
187            ·   The position of the new information is governed by  the  value
188                of  the  parameter  insertPosition.  This parameter may be two
189                values: TOP or BOTTOM.
190
191       cleanCDKSwindow
192            clears the information from the window.
193
194       destroyCDKSwindow
195            removes the widget from the screen and  frees  memory  the  object
196            used.
197
198       drawCDKSwindow
199            draws the swindow widget on the screen.
200
201            If the box parameter is true, the widget is drawn with a box.
202
203       dumpCDKSwindow
204            saves the contents of the scrolling window into the file specified
205            by the filename parameter.  It returns -1 on failure, and the num‐
206            ber of lines saved if the dump was successful.
207
208       eraseCDKSwindow
209            removes  the  widget  from  the screen.  This does NOT destroy the
210            widget.
211
212       execCDKSwindow
213            allows the user to execute a shell command and have the output  of
214            the shell command direct itself to the scrolling window.
215
216            ·   The command parameter is the command to execute.
217
218            ·   The  insertPosition  parameter  tells where the output will be
219                inserted within the scrolling window.
220
221       getCDKSwindowBox
222            returns true if the widget will be drawn with a box around it.
223
224       getCDKSwindowContents
225            returns the contents of the scrolling window.
226
227            The parameter lines will be set to the number of lines returned.
228
229       injectCDKSwindow
230            injects a single character into the widget.
231
232            ·   The parameter swindow is a pointer to a non-NULL swindow  wid‐
233                get.
234
235            ·   The  parameter  character  is the character to inject into the
236                widget.
237
238            The return value and side-effect (setting the  widget  data  exit‐
239            Type) depend upon the injected character:
240
241            RETURN or TAB
242                   the function returns 1.  The widget data exitType is set to
243                   vNORMAL.
244
245            ESCAPE the function returns -1.  The widget data exitType  is  set
246                   to vESCAPE_HIT.
247
248            Otherwise
249                   unless  modified  by  preprocessing,  postprocessing or key
250                   bindings, the function returns -1.  The widget  data  exit‐
251                   Type is set to vEARLY_EXIT.
252
253       jumpToLineCDKSwindow
254            moves the scrolling window to the given line.
255
256            The  parameter line may be an integer or one of the two predefined
257            values TOP and BOTTOM.
258
259       loadCDKSwindowInformation
260            allows the user to load the contents of a file into the  scrolling
261            window.   This  function  is interactive, and will ask for a file‐
262            name.
263
264       moveCDKSwindow
265            moves the given widget to the given position.
266
267            ·   The parameters xpos and ypos are the new position of the  wid‐
268                get.
269
270                The parameter xpos may be an integer or one of the pre-defined
271                values TOP, BOTTOM, and CENTER.
272
273                The parameter ypos may be an integer or one of the pre-defined
274                values LEFT, RIGHT, and CENTER.
275
276            ·   The  parameter relative states whether the xpos/ypos pair is a
277                relative move or an absolute move.
278
279                For example, if xpos = 1 and ypos = 2  and  relative  =  TRUE,
280                then the widget would move one row down and two columns right.
281                If the value of relative was FALSE, then the widget would move
282                to the position (1,2).
283
284                Do not use the values TOP, BOTTOM, LEFT, RIGHT, or CENTER when
285                relative = TRUE (weird things may happen).
286
287            ·   The final parameter refresh is a boolean  value  which  states
288                whether the widget will get refreshed after the move.
289
290       newCDKSwindow
291            creates a swindow widget and returns a pointer to it.  Parameters:
292
293            screen
294                 is the screen you wish this widget to be placed in.
295
296            xpos controls  the  placement  of  the object along the horizontal
297                 axis.  It may be an integer or one of the pre-defined  values
298                 LEFT, RIGHT, and CENTER.
299
300            ypos controls the placement of the object along the vertical axis.
301                 It may be an integer or one of the  pre-defined  values  TOP,
302                 BOTTOM, and CENTER.
303
304            height and
305
306            width
307                 control the height and width of the widget.  If you provide a
308                 value of zero for either of the height or the width, the wid‐
309                 get  will  be  created  with the full width and height of the
310                 screen.  If you provide a negative value, the widget will  be
311                 created the full height or width minus the value provided.
312
313            title
314                 is the string to display at the top of the widget.  The title
315                 can be more than one line; just  provide  a  carriage  return
316                 character at the line break.
317
318            saveLines
319                 is  the  number  of lines to save before throwing information
320                 away.
321
322            box  is true if the widget should be drawn with a box around it.
323
324            The shadow
325                 turns the shadow on or off around this widget.
326
327            If the widget  could  not  be  created  then  a  NULL  pointer  is
328            returned.
329
330       positionCDKSwindow
331            allows  the user to move the widget around the screen via the cur‐
332            sor/keypad keys.  See cdk_position (3) for key bindings.
333
334       saveCDKSwindowInformation
335            allows the user to save the contents of the scrolling window  into
336            a  file.   This  function is interactive, and will ask for a file‐
337            name.
338
339       setCDKSwindow
340            lets the programmer modify certain elements of an existing swindow
341            widget.
342
343            ·   The  parameter  info is a char ** of the information to set in
344                the scrolling window; lines  is  the  number  of  lines  being
345                added.
346
347            ·   The  other  parameter  names  correspond to the same parameter
348                names listed in the newCDKSwindow function.
349
350       setCDKSwindowBackgroundAttrib
351            sets the background attribute of the widget.
352
353            The parameter attribute is a curses attribute, e.g., A_BOLD.
354
355       setCDKSwindowBackgroundColor
356            sets the background color of the widget.
357
358            The parameter color is in the format of the Cdk format strings.
359
360            See cdk_display (3).
361
362       setCDKSwindowBox
363            sets whether the widget will be drawn with a box around it.
364
365       setCDKSwindowBoxAttribute
366            sets the attribute of the box.
367
368       setCDKSwindowContents
369            lets the programmer modify certain elements of an existing swindow
370            widget.
371
372            ·   The  parameter  info is a char ** of the information to set in
373                the scrolling window.
374
375            ·   lines is the number of lines being added.
376
377       setCDKSwindowHorizontalChar
378            sets the horizontal drawing character for the  box  to  the  given
379            character.
380
381       setCDKSwindowLLChar
382            sets  the  lower left hand corner of the widget's box to the given
383            character.
384
385       setCDKSwindowLRChar
386            sets the lower right hand corner of the widget's box to the  given
387            character.
388
389       setCDKSwindowPostProcess
390            allows  the  user to have the widget call a function after the key
391            has been applied to the widget.
392
393            ·   The parameter function is the callback function.
394
395            ·   The parameter data points to data passed to the callback func‐
396                tion.
397
398            To learn more about post-processing see cdk_process (3).
399
400       setCDKSwindowPreProcess
401            allows  the user to have the widget call a function after a key is
402            hit and before the key is applied to the widget.
403
404            ·   The parameter function is the callback function.
405
406            ·   The parameter data points to data passed to the callback func‐
407                tion.
408
409            To learn more about pre-processing see cdk_process (3).
410
411       setCDKSwindowULChar
412            sets  the  upper left hand corner of the widget's box to the given
413            character.
414
415       setCDKSwindowURChar
416            sets the upper right hand corner of the widget's box to the  given
417            character.
418
419       setCDKSwindowVerticalChar
420            sets the vertical drawing character for the box to the given char‐
421            acter.
422
423       trimCDKSwindow
424            removes information from a scrolling window.
425
426            The parameters start and end state where to start cutting from and
427            where to stop.
428
429            The first element in the scrolling window starts at index 0.
430

KEY BINDINGS

432       When  the  widget  is  activated there are several default key bindings
433       which will help the user enter or manipulate the  information  quickly.
434       The  following  table outlines the keys and their actions for this wid‐
435       get.
436
437          ┌────────────────────────────────────────────────────────────────┐
438Key               Action                                        
439          ├────────────────────────────────────────────────────────────────┤
440          │Left Arrow        Scrolls the window left one column.           │
441          │Right Arrow       Scrolls the window right one column.          │
442          │Up Arrow          Scrolls the window up one row.                │
443          │Down Arrow        Scrolls the window down one row.              │
444          ├────────────────────────────────────────────────────────────────┤
445          │Prev Page                                                       │
446          │Ctrl-B                                                          │
447          │b                                                               │
448          │B                 Scroll the window backward one page.          │
449          ├────────────────────────────────────────────────────────────────┤
450          │Next Page                                                       │
451          │Ctrl-F                                                          │
452          │Space                                                           │
453          │f                                                               │
454          │F                 Scroll the window forward one page.           │
455          ├────────────────────────────────────────────────────────────────┤
456          │Home                                                            │
457          │|                 Scroll the list to the left margin.           │
458          ├────────────────────────────────────────────────────────────────┤
459          │End                                                             │
460          │$                 Scroll the list to the right margin.          │
461          ├────────────────────────────────────────────────────────────────┤
462          │1                                                               │
463          │<                                                               │
464          │g                 Move to the top of the scrolling window.      │
465          │>                                                               │
466          │G                 Move to the bottom of the scrolling window.   │
467          ├────────────────────────────────────────────────────────────────┤
468          │l                                                               │
469          │L                 Load a file into the scrolling window.        │
470          ├────────────────────────────────────────────────────────────────┤
471          │s                                                               │
472          │S                 Save the contents  of  the  scrolling  window │
473          │                  into a file.                                  │
474          ├────────────────────────────────────────────────────────────────┤
475          │Return            Set  the  widget's  exitType to vNORMAL, exit │
476          │                  the widget and return 1.                      │
477          │Tab               Set the widget's exitType  to  vNORMAL,  exit │
478          │                  the widget and return 1.                      │
479          │Escape            Set  the  widget's  exitType  to vESCAPE_HIT, │
480          │                  exit the widget and return -1.                │
481          │Ctrl-L            Refreshes the screen.                         │
482          ├────────────────────────────────────────────────────────────────┤
483          └────────────────────────────────────────────────────────────────┘

SEE ALSO

485       cdk(3), cdk_binding(3), cdk_display(3), cdk_position(3), cdk_screen(3)
486
487
488
489                                                                cdk_swindow(3)
Impressum