1Newt(3)               User Contributed Perl Documentation              Newt(3)
2
3
4

NAME

6       Newt - Perl bindings for Red Hat newt library
7

SYNOPSIS

9         use Newt;
10
11         Newt::Init();
12         Newt::Cls();
13
14         #A lot of Newt operations...
15
16         Newt::Finished();
17

DESCRIPTION

19       The Newt module implements perl bindings for the Red Hat newt windowing
20       system, a terminal-based window and widget library for writing
21       applications with a simple, but user-friendly, interface.
22

Basic Newt functions

24       "Newt::Init()"
25           Starts Newt services. You must use this command first.
26
27       "Newt::Finished()"
28           Ends Newt services.
29
30       "Newt::Cls()"
31           Clears the background.
32
33       "Newt::Refresh()"
34           Foreces an inmediate update of the modified portions of the screen.
35
36       "Newt::Bell()"
37           Sends a beep to the terminal.
38
39       "Newt::GetScreenSize()"
40           Returns a tuple containing the screen dimensions.
41

Keyboard input

43       "Newt::WaitForKey()"
44           Stops program execution until a key is pressed.
45
46       "Newt::ClearKeyBuffer()"
47           Discards the contents of the terminal's input buffer without
48           waiting for additional input.
49

Drawing text on the root window

51       "Newt::DrawRootText($left, $top, $text)"
52           Displays the text in the indicated position.
53
54       "Newt::PushHelpLine($text)"
55           Saves the current help line on a stack and displays the new line.
56           If the text is null, Newt's default help line is displayed. If text
57           is a string of length 0, the help line is cleared.
58
59       "Newt::PopHelpLine()"
60           Replaces the current help line with the previous one. It is
61           important not to pop more lines than the ones pushed.
62

Suspending Newt applications

64       By default, Newt programs cannot be suspended by the user. Instead,
65       programs can specify a callback function which gets invoked whe the
66       user presses the suspend key. To register such function, you can do
67       something like this:
68
69           sub my_cb {
70             ...
71           }
72
73           Newt::SetSuspendCallback(\&my_cb);
74
75       If the application should suspend and continue like most user
76       applications, the suspend callback needs two other newt functions:
77
78           Newt::Suspend();
79           Newt::Resume();
80
81       The first one tells Newt to return the terminal to its initial state.
82       Once this is done, the application can suspend itself by sending
83       SIGSTP, fork a child program or whatever. When it wants to resume using
84       the Newt interface, is must call "Newt::Resume()" before doing so.
85
86       For more information on suspending newt applications, read the original
87       newt documentation.
88

Components

90       Components are the basic blocks for construction of Newt interfaces.
91       They all are created in a similar manner. You just have to call the
92       constructor to receive a blessed object of the specified class:
93
94           $object = Newt::Foo();
95
96       Once you have a component, you can add it to a panel to create a
97       complex user input interface.
98
99   General component manipulation
100       You can attach a callback for a component like this:
101
102           sub comp_cb {
103               ...
104           }
105
106           $component->AddCallback(\%comp_cb);
107
108       Exactly when (if ever) the callback is invoked depens on the type of
109       the component.
110
111       Yo can tell if a component takes or not focus when traversing a form
112       with the following function:
113
114           $component->TakesFocus($true_or_false);
115
116       It is handy to set some arbitrary information on a component for later
117       retrieval. You do this by setting its tag:
118
119           $button->Tag("OK");
120
121       If you call this function without an argument, it replies with the
122       actual tag for that component.
123
124       In general when the return value of any method of a component isn't
125       described the method returns the component itself to allow
126       constructions like:
127
128           $panel
129               ->Add(0,0, $componet1->Set( .... ) )
130               ->Add(0,1, Newt::Label( .... ) )
131               ->Add(0,2, Newt::Panel( .... )
132                   ->Add( .... )
133                   ->Add( .... ) )
134               ->Add( .... );
135
136   Buttons
137       There are two kinds of buttons: full and compact:
138
139           $normal_button = Newt::Button($text);
140           $compact_button = Newt::CompactButton($text);
141
142   Labels
143       Labels are quite simple:
144
145           $label = Newt::Label($text);
146
147       You can set the text of an existing label like this:
148
149           $label->Set($text);
150
151   Entry boxes
152       Entry boxes are used to enter text:
153
154           $entry = Newt::Entry($width, $flags, $initial_text);
155
156       The initial text is optional. After an entry has been created, it's
157       contents can be set by using:
158
159           $entry->Set($text, $cursor_at_end);
160
161       The last parameter is optional, and signals if the cursor should be
162       moved to the end of the new value.
163
164       To get the current value of the entry box, you do this:
165
166           $entry->Get();
167
168       You can filter the characters that may be entered by using a callback
169       filter like this:
170
171           sub my_filter {
172             my ($proposed_char, $cursor_position) = @_;
173
174             ...
175
176             return(0) if $char_shoud_be_ignored;
177             return($proposed_char)    # Accept the char
178           }
179
180           $entry->SetFilter(\&my_filter);
181
182       As can be seen, filter callbacks receive a char and an integer which
183       indicates the position that the proposed char would take on the entry.
184       The filter function can return the very same char to indicate that it
185       was accepted, but it can also return another char, to actually
186       substitute the original one. If the filter wants to simply reject the
187       keystroke, it only returns 0.
188
189       When an entry is created, some flags may be specified. The flags are
190       the following and may be "OR"ed:
191
192       "NEWT::NEWT_ENTRY_SCROLL"
193           If not specified, the user cannot enter text into the entry box
194           which is wider than the entry box itself. This flag removes this
195           limitation, and lets the user enter data of an arbitrary length.
196
197       "NEWT::NEWT_FLAG_HIDDEN"
198           If specified, the value of the entry is not displayed. Useful when
199           an applications needs a password.
200
201       "NEWT::NEWT_FLAG_RETURNEXIT"
202           When specified, the entry will cause the form to stop running if
203           the user pressed return inside the entry box. Nice shortcut for
204           users.
205
206   Checkboxes
207       Newt checkboxes are peculiar, since they may have more than two states.
208       To create a normal one (checked or unchecked), do this:
209
210           $check = Newt::Checkbox("Normal checkbox");
211
212       But you can create, for example, a checkbox that switches from not
213       checked to checked with an asterisk and then to checked with an 'M':
214
215           $check = Newt::Checkbox("Normal checkbox", " ", " *M");
216
217       As you can see, you can use the two optional parameters to tell the
218       default char first and then the possible chars.
219
220       To know if a checkbox is checked after the for is ran, you use the
221       following:
222
223           print "Is checked\n" if $check->Checked();
224
225       And you can always get the actual state like this:
226
227           $state = $check->Get();
228
229   Radio groups
230       You create two kinds of radio button groups, vertical and horizontal,
231       by doing this:
232
233           $radio_group1 = Newt::VRadiogroup('Red', 'Green', 'Blue');
234           $radio_group2 = Newt::HRadiogroup('Red', 'Green', 'Blue');
235
236       You can put any number of options and the first one will always be
237       preselected. To know the index of the selected option after the form
238       has run, you do this:
239
240           $index = $radio_group->Get();
241
242   Listboxes
243       Listboxes are the most complicated components Newt provides. They can
244       allow single or multiple selection, and are easy to update. They are
245       created as follows:
246
247           $listbox = Newt::Listbox($height, $flags);
248
249       A listbox is created at a certain position and a given height. The
250       $height is used for two things. First of all, it is the minimum height
251       the listbox will use. If there are less items in the listbox then the
252       height, suggests the listbox will still take up that minimum amount of
253       space. Secondly, if the listbox is set to be scrollable (by setting the
254       "NEWT_FLAG_SCROLL" flag, $height is also the maximum height of the
255       listbox. If the listbox may not scroll, it increases its height to
256       display all of its items.
257
258       The following flags may be used when creating a listbox:
259
260       "NEWT_FLAG_SCROLL"
261           The listbox should scroll to display all of the items it contains.
262
263       "NEWT_FLAG_RETURNEXIT"
264           When the user presses return on an item in the list, the form
265           should return.
266
267       "NEWT_FLAG_BORDER"
268           A frame is drawn around the listbox, which can make it easier to
269           see which listbox has the focus when a form contains multiple
270           listboxes.
271
272       "NEWT_FLAG_MULTIPLE"
273           By default, a listbox only lets the user select one item in the
274           list at a time. When this flag is specified, they may select
275           multiple items from the list.
276
277
278       Once a listbox has been created, items are appended to the bottom like
279       this:
280
281           $listbox->Append($item1, $item2, ...);
282
283       Appending is not the only way to add items to the list. You can insert
284       items in any position by telling the item that should be before with
285       the following command:
286
287           $listbox->Insert($before, $item1, $item2, ...);
288
289       And you can change any item just by telling:
290
291           $listbox->Set($original, $new);
292
293       Of course you can delete entries:
294
295           $listbox->Delete($item1, $item2, ...);
296
297       Or just clear out the listbox:
298
299           $listbox->Clear();
300
301       You can select and unselect items, with the following:
302
303           $listbox->Select($item1, $item2, ...);
304
305           $listbox->Unselect($item1, $item2, ...);
306
307           $listbox->ClearSelection();
308
309       but if you did not sepecify the flag "NEWT_FLAG_MULTIPLE" when
310       constructing your listbox, only the last item on the argument list of
311       "Unselect()" will remain selected.
312
313       To get a list of the selected items, just issue:
314
315           @selected_items = $listbox->Get();
316
317   Scales
318       Scales provide an easy way for telling the user the advance on some
319       lengthy operation. It is a horizontal bar graph which the application
320       updates as the operation continues:
321
322           $scale = Newt::Scale($width, $fullvalue);
323
324       It is set as expected:
325
326           $scale->Set($amount);
327
328   Textboxes
329       A text box is used for displaying large amounts of text. They are
330       created as follows:
331
332           $textbox = Newt::Textbox($width, $height, $flags, $text, ...);
333
334       The $text parameter is optional, and if not supplied, the textbox is
335       created only, but it does not fill it with data. To do so, use:
336
337           $textbox->Set($text, ...);
338
339       All the arguments are simply concatenated using the double quote
340       operator.
341
342       The flags that can be passed to the constructor are the following:
343
344       "NEWT_FLAG_WRAP"
345           All text in the textbox should be wrapped to fit the width of the
346           textbox. If this flag is not specified, each newline-delimited line
347           in the text is truncated if it is too long to fit.
348
349           When Newt wraps text, it tries not to break lines on spaces or
350           tabs. Literal newline characters are respected, and may be used to
351           force line breaks.
352
353       "NEWT_FLAG_SCROLL"
354           The text should be scrollable. When this option is used, the
355           scrollbar which is added increases the width of the area used by
356           the textbox by 2 characters.
357
358   Reflowing text
359       When applications need to display large amounts of text, it is common
360       not to know exactly where the linebreaks should go. While textboxes are
361       quite willing to scroll the text, the programmer still must know what
362       width the text will look ``best'' at (where ``best'' means most exactly
363       rectangular; no lines much shorter or much longer then the rest). This
364       common is specially prevalent in internationalized programs, which need
365       to make a wide variety of message string look good on a screen.
366
367       To help with this, Newt provides routines to reformat text to look
368       good. It tries different widths to figure out which one will look
369       ``best'' to the user. As these commons are almost always used to format
370       text for textbox components, Newt makes it easy to construct a textbox
371       with reflowed text.
372
373       The following function reflows the provided text to a target width. the
374       actual width of the longest line in the returned text is between
375       "$width - $flexdown" and "$width + $flexup"; the actual maximum line
376       length is chosen to make displayed text look rectangular. The function
377       returns a tuple consisting of the reflowed text and the actual width
378       and height of it.
379
380           ($r_text, $width, $height) = Newt::ReflowText($width,
381                                                         $flexdown,
382                                                         $flexup,
383                                                         $text);
384
385       When the reflowed text is being placed in a textbox it may be easier to
386       use the following:
387
388           $textbox = Newt::TextboxReflowed($width, $flexdown,
389                                            $flexup, $flags,
390                                            $text, ...);
391
392       which creates a textbox, reflows the text, and places the reflowed text
393       in the listbox. Its parameters consist of the position of the final
394       textbox, the width and flex values for the text (which are identical to
395       the parameters passed to "Newt::Reflow()", and the flags for the
396       textbox (which are the same as the flags for "Newt::Textbox()". This
397       function does not let you limit the height of the textbox, however,
398       making limiting its use to constructing textboxes which do not need to
399       scroll.
400
401       To find out how tall the textbox created by "Newt::TextboxReflowed()"
402       is, use "Newt::GetNumLines()", which returns the number of lines in the
403       textbox. For textboxes created by "Newt::TextboxReflowed()", this is
404       always the same as the height of the textbox.
405
406       Please note that the order of the parameters of Newt::ReflowText and
407       Newt::TextboxReflowed differs from the C API to allow lists of text but
408       currently only TextboxReflowed allows this.
409
410   Scrollbars
411       Scrollbars may be attached to forms to let them contain more data than
412       they have space for. Currently, there can only be vertical scrollbars:
413
414           $scroll = Newt::VScrollbar($height,
415                                      $normalColorset,
416                                      $thumbColorset);
417
418       When a scrollbar is created, it is given a position on the screen, a
419       height, and two colors. The first color is the color used for drawing
420       the scrollbar, and the second color is used for drawing the thumb. This
421       is the only place in newt where an application specifically sets colors
422       for a component. It s done here to let the colors a scrollbar use match
423       the colors of the component the scrollbar is mated too. When a
424       scrollbar is being used with a form, $normalColorset is often
425       "NEWT_COLORSET_WINDOW" and $thumbColorset "NEWT_COLORSET_ACTCHECKBOX".
426
427       If you do not want to bother with colors, you can omit the last two
428       parameters and let Newt use the defaults.
429
430       As the scrollbar is normally updated by the component it is mated with,
431       there is no public interface for moving the thumb.
432

Panels

434       Panels are high level grid-like constructs that are used to group
435       components. You create them by specifying the number of columns and
436       rows you want, as well as a caption to be used when the panel is
437       displayed as a toplevel:
438
439           $panel = Newt::Panel(2, 3, "Panel example");
440
441       When run, panels are centered by default, but you can specify a
442       position relative to the topleft corner of the screen by appending two
443       optional integers:
444
445           $panel = Newt::Panel(2, 3, "Panel example", 5, 5);
446
447       Adding components to a panel is straightforward, you just have to
448       indicate the position the component will take in the grid:
449
450          $panel1->Add(0, 0, $mycomponent);
451
452       Several optional parameters my however be used when adding components:
453
454           $panel1->Add($col,
455                        $row,
456                        $mycomponent,
457                        $anchor,
458                        $padleft,
459                        $padtop,
460                        $padright,
461                        $padbottom,
462                        $flag);
463
464       You can specify the side of the cell to which the component will be
465       aligned by specifying an anchor. The anchor values avalaible are
466       "NEWT_ANCHOR_LEFT", "NEWT_ANCHOR_RIGHT", "NEWT_ANCHOR_TOP",
467       "NEWT_ANCHOR_BOTTOM".
468
469       You can ask for more space on the sides of the component, perhaps to
470       get a cleaner, less cluttered presentation using the padding
471       parameters, and specifiying an integer value.
472
473       Panels may be nested. For this to be done you only have to add a panel
474       to another as you would with any other component.
475
476       To run a panel as a toplevel and get user input, you may do the
477       following:
478
479           ($reason, $data) = $panel->Run();
480
481           if ($reason eq NEWT_EXIT_HOTKEY) {
482             if ($data eq NEWT_KEY_F12) {
483               print "F12 hotkey was pressed\n";
484             } else {
485               print "Some hotkey other than F12 was pressed\n";
486             }
487           } else {
488             print 'Form terminated by button ', $data->Tag(), "\n";
489           }
490
491       As can be seen on the example, when called in a list context "Run()"
492       returns two values, one is the reason why the form terminated and the
493       other is an associated data. In a scalar context only the data is
494       returned. Posible values for the reason are:
495
496       "NEWT_EXIT_HOTKEY"
497           The form exited because a hotkey was pressed. The associated data
498           contains the key pressed, that is, one of NEWT_KEY_* values. See
499           Hotkeys later for more information.
500
501       "NEWT_EXIT_COMPONENT"
502           The form exited because a component was activated, a button, for
503           instance a button. The associated data is a reference to the
504           component involved.
505
506   Hotkeys
507       Normally, a panel terminates when the user presses a button, but you
508       can define some keys as "hotkeys" that will make the "Run()" function
509       return with "NEWT_EXIT_HOTKEY". Yo do this by issuing the folowing:
510
511          $panel->AddHotKey(NEWT_KEY_F11);
512
513       F12 is always defined to be a hotkey.
514
515   Drawing panels instead of running them
516       When you run a panel the terminal is blocked until the user presses a
517       component or a key that causes the panel to exit. Sometimes is useful
518       to present the interface to the user without blocking the execution of
519       code. This can be done by only drawing the panel, not running it. It is
520       easy to show an advance status for a lengthy operation like this:
521
522          $i = 1;
523          foreach (@items) {
524             $label->Set("Processing item $i");
525             $panel->Draw();
526             $scale->Set($i);
527             process_item($_);
528             $i++
529          }
530
531   Hiding panels
532       Panels can be hidden in case you want by using the following:
533
534           $panel->Hide()
535

Constants

537       You can import all the constants exported by this package as needed or
538       using several predefined tags, with the following syntax:
539
540           use Newt qw(:exits :keys);
541
542       exits NEWT_EXIT_* constants
543       keys NEWT_KEY_* constants
544       anchors NEWT_ANCHOR_* constants
545       colorsets NEWT_COLORSET_* constanst
546       flags NEWT_FLAG_* constants
547       entry NEWT_ENTRY_* constants
548       fd NEWT_FD_* constants
549       grid NEWT_GRID_* constants
550       textbox NEWT_TEXTBOX_* constants
551       macros
552           macros to make useful buttons and panels: OK_BUTTON, CANCEL_BUTTON,
553           QUIT_BUTTON, BACK_BUTTON, OK_CANCEL_PANEL, OK_BACK_PANEL. This
554           macros only create components which are properly tagged.
555

TO DO

557       Scrollable panels.
558       Some forms stuff, like watching file descriptors.
559

SEE ALSO

561       Writing programs using Newt, by Erik Troan.
562

THANKS TO

564       Erik Troan, for writing this useful library. Thanks for his tutorial,
565       too, from where I stole complete paragraphs for this documentation, I'm
566       afraid.
567

AUTHOR

569       The original author of the Red Hat newt library is Erik Troan,
570       <ewt@redhat.com> The author of this Perl bindings is Alejandro
571       Escalante Medina, <amedina@msg.com.mx>
572

DATE

574       Version 0.1, 5th Nov 1998
575
576
577
578perl v5.16.3                      2014-06-10                           Newt(3)
Impressum