1Newt(3) User Contributed Perl Documentation Newt(3)
2
6 Newt - Perl bindings for Red Hat newt library
7
9 use Newt;
10 Newt::Init();
12 Newt::Cls();
13 #A lot of Newt operations...
15 Newt::Finished();
17
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
24 "Newt::Init()"
25 Starts Newt services. You must use this command first.
26 "Newt::Finished()"
28 Ends Newt services.
29 "Newt::Cls()"
31 Clears the background.
32 "Newt::Refresh()"
34 Foreces an inmediate update of the modified portions of the screen.
35 "Newt::Bell()"
37 Sends a beep to the terminal.
38 "Newt::GetScreenSize()"
40 Returns a tuple containing the screen dimensions.
41
43 "Newt::WaitForKey()"
44 Stops program execution until a key is pressed.
45 "Newt::ClearKeyBuffer()"
47 Discards the contents of the terminal's input buffer without
48 waiting for additional input.
49
51 "Newt::DrawRootText($left, $top, $text)"
52 Displays the text in the indicated position.
53 "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 "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
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 sub my_cb {
70 ...
71 }
72 Newt::SetSuspendCallback(\&my_cb);
74 If the application should suspend and continue like most user
76 applications, the suspend callback needs two other newt functions:
77 Newt::Suspend();
79 Newt::Resume();
80 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 For more information on suspending newt applications, read the original
87 newt documentation.
88
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 $object = Newt::Foo();
95 Once you have a component, you can add it to a panel to create a
97 complex user input interface.
98 General component manipulation
100 You can attach a callback for a component like this:
101 sub comp_cb {
103 ...
104 }
105 $component->AddCallback(\%comp_cb);
107 Exactly when (if ever) the callback is invoked depens on the type of
109 the component.
110 Yo can tell if a component takes or not focus when traversing a form
112 with the following function:
113 $component->TakesFocus($true_or_false);
115 It is handy to set some arbitrary information on a component for later
117 retrieval. You do this by setting its tag:
118 $button->Tag("OK");
120 If you call this function without an argument, it replies with the
122 actual tag for that component.
123 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 $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 Buttons
137 There are two kinds of buttons: full and compact:
138 $normal_button = Newt::Button($text);
140 $compact_button = Newt::CompactButton($text);
141 Labels
143 Labels are quite simple:
144 $label = Newt::Label($text);
146 You can set the text of an existing label like this:
148 $label->Set($text);
150 Entry boxes
152 Entry boxes are used to enter text:
153 $entry = Newt::Entry($width, $flags, $initial_text);
155 The initial text is optional. After an entry has been created, it's
157 contents can be set by using:
158 $entry->Set($text, $cursor_at_end);
160 The last parameter is optional, and signals if the cursor should be
162 moved to the end of the new value.
163 To get the current value of the entry box, you do this:
165 $entry->Get();
167 You can filter the characters that may be entered by using a callback
169 filter like this:
170 sub my_filter {
172 my ($proposed_char, $cursor_position) = @_;
173 ...
175 return(0) if $char_shoud_be_ignored;
177 return($proposed_char) # Accept the char
178 }
179 $entry->SetFilter(\&my_filter);
181 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 When an entry is created, some flags may be specified. The flags are
190 the following and may be "OR"ed:
191 "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 "NEWT::NEWT_FLAG_HIDDEN"
198 If specified, the value of the entry is not displayed. Useful when
199 an applications needs a password.
200 "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 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 $check = Newt::Checkbox("Normal checkbox");
211 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 $check = Newt::Checkbox("Normal checkbox", " ", " *M");
216 As you can see, you can use the two optional parameters to tell the
218 default char first and then the possible chars.
219 To know if a checkbox is checked after the for is ran, you use the
221 following:
222 print "Is checked\n" if $check->Checked();
224 And you can always get the actual state like this:
226 $state = $check->Get();
228 Radio groups
230 You create two kinds of radio button groups, vertical and horizontal,
231 by doing this:
232 $radio_group1 = Newt::VRadiogroup('Red', 'Green', 'Blue');
234 $radio_group2 = Newt::HRadiogroup('Red', 'Green', 'Blue');
235 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 $index = $radio_group->Get();
241 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 $listbox = Newt::Listbox($height, $flags);
248 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 The following flags may be used when creating a listbox:
259 "NEWT_FLAG_SCROLL"
261 The listbox should scroll to display all of the items it contains.
262 "NEWT_FLAG_RETURNEXIT"
264 When the user presses return on an item in the list, the form
265 should return.
266 "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 "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 Once a listbox has been created, items are appended to the bottom like
279 this:
280 $listbox->Append($item1, $item2, ...);
282 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 $listbox->Insert($before, $item1, $item2, ...);
288 And you can change any item just by telling:
290 $listbox->Set($original, $new);
292 Of course you can delete entries:
294 $listbox->Delete($item1, $item2, ...);
296 Or just clear out the listbox:
298 $listbox->Clear();
300 You can select and unselect items, with the following:
302 $listbox->Select($item1, $item2, ...);
304 $listbox->Unselect($item1, $item2, ...);
306 $listbox->ClearSelection();
308 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 To get a list of the selected items, just issue:
314 @selected_items = $listbox->Get();
316 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 $scale = Newt::Scale($width, $fullvalue);
323 It is set as expected:
325 $scale->Set($amount);
327 Textboxes
329 A text box is used for displaying large amounts of text. They are
330 created as follows:
331 $textbox = Newt::Textbox($width, $height, $flags, $text, ...);
333 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 $textbox->Set($text, ...);
338 All the arguments are simply concatenated using the double quote
340 operator.
341 The flags that can be passed to the constructor are the following:
343 "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 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 "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 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 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 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 ($r_text, $width, $height) = Newt::ReflowText($width,
381 $flexdown,
382 $flexup,
383 $text);
384 When the reflowed text is being placed in a textbox it may be easier to
386 use the following:
387 $textbox = Newt::TextboxReflowed($width, $flexdown,
389 $flexup, $flags,
390 $text, ...);
391 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 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 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 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 $scroll = Newt::VScrollbar($height,
415 $normalColorset,
416 $thumbColorset);
417 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 If you do not want to bother with colors, you can omit the last two
428 parameters and let Newt use the defaults.
429 As the scrollbar is normally updated by the component it is mated with,
431 there is no public interface for moving the thumb.
432
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 $panel = Newt::Panel(2, 3, "Panel example");
440 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 $panel = Newt::Panel(2, 3, "Panel example", 5, 5);
446 Adding components to a panel is straightforward, you just have to
448 indicate the position the component will take in the grid:
449 $panel1->Add(0, 0, $mycomponent);
451 Several optional parameters my however be used when adding components:
453 $panel1->Add($col,
455 $row,
456 $mycomponent,
457 $anchor,
458 $padleft,
459 $padtop,
460 $padright,
461 $padbottom,
462 $flag);
463 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 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 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 To run a panel as a toplevel and get user input, you may do the
477 following:
478 ($reason, $data) = $panel->Run();
480 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 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 "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 "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 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 $panel->AddHotKey(NEWT_KEY_F11);
512 F12 is always defined to be a hotkey.
514 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 $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 Hiding panels
532 Panels can be hidden in case you want by using the following:
533 $panel->Hide()
535
537 You can import all the constants exported by this package as needed or
538 using several predefined tags, with the following syntax:
539 use Newt qw(:exits :keys);
541 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
557 Scrollable panels.
558 Some forms stuff, like watching file descriptors.
559
561 Writing programs using Newt, by Erik Troan.
562
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
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
574 Version 0.1, 5th Nov 1998
575perl v5.16.3 2014-06-10 Newt(3)