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 applica‐
21 tions 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 impor‐
61 tant 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 applica‐
76 tions, 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 com‐
97 plex user input interface.
98 General component manipulation
100 You can attach a callback for a component like this:
102 sub comp_cb {
104 ...
105 }
106 $component->AddCallback(\%comp_cb);
108 Exactly when (if ever) the callback is invoked depens on the type of
110 the component.
111 Yo can tell if a component takes or not focus when traversing a form
113 with the following function:
114 $component->TakesFocus($true_or_false);
116 It is handy to set some arbitrary information on a component for later
118 retrieval. You do this by setting its tag:
119 $button->Tag("OK");
121 If you call this function without an argument, it replies with the
123 actual tag for that component.
124 In general when the return value of any method of a component isn't
126 described the method returns the component itself to allow construc‐
127 tions like:
128 $panel
130 ->Add(0,0, $componet1->Set( .... ) )
131 ->Add(0,1, Newt::Label( .... ) )
132 ->Add(0,2, Newt::Panel( .... )
133 ->Add( .... )
134 ->Add( .... ) )
135 ->Add( .... );
136 Buttons
138 There are two kinds of buttons: full and compact:
140 $normal_button = Newt::Button($text);
142 $compact_button = Newt::CompactButton($text);
143 Labels
145 Labels are quite simple:
147 $label = Newt::Label($text);
149 You can set the text of an existing label like this:
151 $label->Set($text);
153 Entry boxes
155 Entry boxes are used to enter text:
157 $entry = Newt::Entry($width, $flags, $initial_text);
159 The initial text is optional. After an entry has been created, it's
161 contents can be set by using:
162 $entry->Set($text, $cursor_at_end);
164 The last parameter is optional, and signals if the cursor should be
166 moved to the end of the new value.
167 To get the current value of the entry box, you do this:
169 $entry->Get();
171 You can filter the characters that may be entered by using a callback
173 filter like this:
174 sub my_filter {
176 my ($proposed_char, $cursor_position) = @_;
177 ...
179 return(0) if $char_shoud_be_ignored;
181 return($proposed_char) # Accept the char
182 }
183 $entry->SetFilter(\&my_filter);
185 As can be seen, filter callbacks receive a char and an integer which
187 indicates the position that the proposed char would take on the entry.
188 The filter function can return the very same char to indicate that it
189 was accepted, but it can also return another char, to actually substi‐
190 tute the original one. If the filter wants to simply reject the key‐
191 stroke, it only returns 0.
192 When an entry is created, some flags may be specified. The flags are
194 the following and may be "OR"ed:
195 "NEWT::NEWT_ENTRY_SCROLL"
197 If not specified, the user cannot enter text into the entry box
198 which is wider than the entry box itself. This flag removes this
199 limitation, and lets the user enter data of an arbitrary length.
200 "NEWT::NEWT_FLAG_HIDDEN"
202 If specified, the value of the entry is not displayed. Useful when
203 an applications needs a password.
204 "NEWT::NEWT_FLAG_RETURNEXIT"
206 When specified, the entry will cause the form to stop running if
207 the user pressed return inside the entry box. Nice shortcut for
208 users.
209 Checkboxes
211 Newt checkboxes are peculiar, since they may have more than two
213 states. To create a normal one (checked or unchecked), do this:
214 $check = Newt::Checkbox("Normal checkbox");
216 But you can create, for example, a checkbox that switches from not
218 checked to checked with an asterisk and then to checked with an
219 'M':
220 $check = Newt::Checkbox("Normal checkbox", " ", " *M");
222 As you can see, you can use the two optional parameters to tell the
224 default char first and then the possible chars.
225 To know if a checkbox is checked after the for is ran, you use the
227 following:
228 print "Is checked\n" if $check->Checked();
230 And you can always get the actual state like this:
232 $state = $check->Get();
234 Radio groups
236 You create two kinds of radio button groups, vertical and horizon‐
238 tal, by doing this:
239 $radio_group1 = Newt::VRadiogroup('Red', 'Green', 'Blue');
241 $radio_group2 = Newt::HRadiogroup('Red', 'Green', 'Blue');
242 You can put any number of options and the first one will always be
244 preselected. To know the index of the selected option after the
245 form has run, you do this:
246 $index = $radio_group->Get();
248 Listboxes
250 Listboxes are the most complicated components Newt provides. They
252 can allow single or multiple selection, and are easy to update.
253 They are created as follows:
254 $listbox = Newt::Listbox($height, $flags);
256 A listbox is created at a certain position and a given height. The
258 $height is used for two things. First of all, it is the minimum
259 height the listbox will use. If there are less items in the listbox
260 then the height, suggests the listbox will still take up that mini‐
261 mum amount of space. Secondly, if the listbox is set to be scrol‐
262 lable (by setting the "NEWT_FLAG_SCROLL" flag, $height is also the
263 maximum height of the listbox. If the listbox may not scroll, it
264 increases its height to display all of its items.
265 The following flags may be used when creating a listbox:
267 "NEWT_FLAG_SCROLL"
269 The listbox should scroll to display all of the items it con‐
270 tains.
271 "NEWT_FLAG_RETURNEXIT"
273 When the user presses return on an item in the list, the form
274 should return.
275 "NEWT_FLAG_BORDER"
277 A frame is drawn around the listbox, which can make it easier
278 to see which listbox has the focus when a form contains multi‐
279 ple listboxes.
280 "NEWT_FLAG_MULTIPLE"
282 By default, a listbox only lets the user select one item in the
283 list at a time. When this flag is specified, they may select
284 multiple items from the list.
285 Once a listbox has been created, items are appended to the bottom
289 like this:
290 $listbox->Append($item1, $item2, ...);
292 Appending is not the only way to add items to the list. You can
294 insert items in any position by telling the item that should be
295 before with the following command:
296 $listbox->Insert($before, $item1, $item2, ...);
298 And you can change any item just by telling:
300 $listbox->Set($original, $new);
302 Of course you can delete entries:
304 $listbox->Delete($item1, $item2, ...);
306 Or just clear out the listbox:
308 $listbox->Clear();
310 You can select and unselect items, with the following:
312 $listbox->Select($item1, $item2, ...);
314 $listbox->Unselect($item1, $item2, ...);
316 $listbox->ClearSelection();
318 but if you did not sepecify the flag "NEWT_FLAG_MULTIPLE" when con‐
320 structing your listbox, only the last item on the argument list of
321 "Unselect()" will remain selected.
322 To get a list of the selected items, just issue:
324 @selected_items = $listbox->Get();
326 Scales
328 Scales provide an easy way for telling the user the advance on some
330 lengthy operation. It is a horizontal bar graph which the applica‐
331 tion updates as the operation continues:
332 $scale = Newt::Scale($width, $fullvalue);
334 It is set as expected:
336 $scale->Set($amount);
338 Textboxes
340 A text box is used for displaying large amounts of text. They are
342 created as follows:
343 $textbox = Newt::Textbox($width, $height, $flags, $text, ...);
345 The $text parameter is optional, and if not supplied, the textbox
347 is created only, but it does not fill it with data. To do so, use:
348 $textbox->Set($text, ...);
350 All the arguments are simply concatenated using the double quote
352 operator.
353 The flags that can be passed to the constructor are the following:
355 "NEWT_FLAG_WRAP"
357 All text in the textbox should be wrapped to fit the width of
358 the textbox. If this flag is not specified, each newline-delim‐
359 ited line in the text is truncated if it is too long to fit.
360 When Newt wraps text, it tries not to break lines on spaces or
362 tabs. Literal newline characters are respected, and may be used
363 to force line breaks.
364 "NEWT_FLAG_SCROLL"
366 The text should be scrollable. When this option is used, the
367 scrollbar which is added increases the width of the area used
368 by the textbox by 2 characters.
369 Reflowing text
371 When applications need to display large amounts of text, it is com‐
373 mon not to know exactly where the linebreaks should go. While
374 textboxes are quite willing to scroll the text, the programmer
375 still must know what width the text will look ``best'' at (where
376 ``best'' means most exactly rectangular; no lines much shorter or
377 much longer then the rest). This common is specially prevalent in
378 internationalized programs, which need to make a wide variety of
379 message string look good on a screen.
380 To help with this, Newt provides routines to reformat text to look
382 good. It tries different widths to figure out which one will look
383 ``best'' to the user. As these commons are almost always used to
384 format text for textbox components, Newt makes it easy to construct
385 a textbox with reflowed text.
386 The following function reflows the provided text to a target width.
388 the actual width of the longest line in the returned text is
389 between "$width - $flexdown" and "$width + $flexup"; the actual
390 maximum line length is chosen to make displayed text look rectangu‐
391 lar. The function returns a tuple consisting of the reflowed text
392 and the actual width and height of it.
393 ($r_text, $width, $height) = Newt::ReflowText($width,
395 $flexdown,
396 $flexup,
397 $text);
398 When the reflowed text is being placed in a textbox it may be eas‐
400 ier to use the following:
401 $textbox = Newt::TextboxReflowed($width, $flexdown,
403 $flexup, $flags,
404 $text, ...);
405 which creates a textbox, reflows the text, and places the reflowed
407 text in the listbox. Its parameters consist of the position of the
408 final textbox, the width and flex values for the text (which are
409 identical to the parameters passed to "Newt::Reflow()", and the
410 flags for the textbox (which are the same as the flags for
411 "Newt::Textbox()". This function does not let you limit the height
412 of the textbox, however, making limiting its use to constructing
413 textboxes which do not need to scroll.
414 To find out how tall the textbox created by "Newt::TextboxRe‐
416 flowed()" is, use "Newt::GetNumLines()", which returns the number
417 of lines in the textbox. For textboxes created by "Newt::TextboxRe‐
418 flowed()", this is always the same as the height of the textbox.
419 Please note that the order of the parameters of Newt::ReflowText
421 and Newt::TextboxReflowed differs from the C API to allow lists of
422 text but currently only TextboxReflowed allows this.
423 Scrollbars
425 Scrollbars may be attached to forms to let them contain more data
427 than they have space for. Currently, there can only be vertical
428 scrollbars:
429 $scroll = Newt::VScrollbar($height,
431 $normalColorset,
432 $thumbColorset);
433 When a scrollbar is created, it is given a position on the screen,
435 a height, and two colors. The first color is the color used for
436 drawing the scrollbar, and the second color is used for drawing the
437 thumb. This is the only place in newt where an application specifi‐
438 cally sets colors for a component. It s done here to let the colors
439 a scrollbar use match the colors of the component the scrollbar is
440 mated too. When a scrollbar is being used with a form, $normalCol‐
441 orset is often "NEWT_COLORSET_WINDOW" and $thumbColorset "NEWT_COL‐
442 ORSET_ACTCHECKBOX".
443 If you do not want to bother with colors, you can omit the last two
445 parameters and let Newt use the defaults.
446 As the scrollbar is normally updated by the component it is mated
448 with, there is no public interface for moving the thumb.
449
451 Panels are high level grid-like constructs that are used to group com‐
452 ponents. You create them by specifying the number of columns and rows
453 you want, as well as a caption to be used when the panel is displayed
454 as a toplevel:
455 $panel = Newt::Panel(2, 3, "Panel example");
457 When run, panels are centered by default, but you can specify a posi‐
459 tion relative to the topleft corner of the screen by appending two
460 optional integers:
461 $panel = Newt::Panel(2, 3, "Panel example", 5, 5);
463 Adding components to a panel is straightforward, you just have to indi‐
465 cate the position the component will take in the grid:
466 $panel1->Add(0, 0, $mycomponent);
468 Several optional parameters my however be used when adding components:
470 $panel1->Add($col,
472 $row,
473 $mycomponent,
474 $anchor,
475 $padleft,
476 $padtop,
477 $padright,
478 $padbottom,
479 $flag);
480 You can specify the side of the cell to which the component will be
482 aligned by specifying an anchor. The anchor values avalaible are
483 "NEWT_ANCHOR_LEFT", "NEWT_ANCHOR_RIGHT", "NEWT_ANCHOR_TOP",
484 "NEWT_ANCHOR_BOTTOM".
485 You can ask for more space on the sides of the component, perhaps to
487 get a cleaner, less cluttered presentation using the padding parame‐
488 ters, and specifiying an integer value.
489 Panels may be nested. For this to be done you only have to add a panel
491 to another as you would with any other component.
492 To run a panel as a toplevel and get user input, you may do the follow‐
494 ing:
495 ($reason, $data) = $panel->Run();
497 if ($reason eq NEWT_EXIT_HOTKEY) {
499 if ($data eq NEWT_KEY_F12) {
500 print "F12 hotkey was pressed\n";
501 } else {
502 print "Some hotkey other than F12 was pressed\n";
503 }
504 } else {
505 print 'Form terminated by button ', $data->Tag(), "\n";
506 }
507 As can be seen on the example, when called in a list context "Run()"
509 returns two values, one is the reason why the form terminated and the
510 other is an associated data. In a scalar context only the data is
511 returned. Posible values for the reason are:
512 "NEWT_EXIT_HOTKEY"
514 The form exited because a hotkey was pressed. The associated data
515 contains the key pressed, that is, one of NEWT_KEY_* values. See
516 Hotkeys later for more information.
517 "NEWT_EXIT_COMPONENT"
519 The form exited because a component was activated, a button, for
520 instance a button. The associated data is a reference to the compo‐
521 nent involved.
522 Hotkeys
524 Normally, a panel terminates when the user presses a button, but
526 you can define some keys as "hotkeys" that will make the "Run()"
527 function return with "NEWT_EXIT_HOTKEY". Yo do this by issuing the
528 folowing:
529 $panel->AddHotKey(NEWT_KEY_F11);
531 F12 is always defined to be a hotkey.
533 Drawing panels instead uf running them
535 When you run a panel the terminal is blocked until the user presses
537 a component or a key that causes the panel to exit. Sometimes is
538 useful to present the interface to the user without blocking the
539 execution of code. This can be done by only drawing the panel, not
540 running it. It is easy to show an advance status for a lengthy
541 operation like this:
542 $i = 1;
544 foreach (@items) {
545 $label->Set("Processing item $i");
546 $panel->Draw();
547 $scale->Set($i);
548 process_item($_);
549 $i++
550 }
551 Hiding panels
553 Panels can be hidden in case you want by using the following:
555 $panel->Hide()
557
559 You can import all the constants exported by this package as needed or
560 using several predefined tags, with the following syntax:
561 use Newt qw(:exits :keys);
563 exits NEWT_EXIT_* constants
565 keys NEWT_KEY_* constants
566 anchors NEWT_ANCHOR_* constants
567 colorsets NEWT_COLORSET_* constanst
568 flags NEWT_FLAG_* constants
569 entry NEWT_ENTRY_* constants
570 fd NEWT_FD_* constants
571 grid NEWT_GRID_* constants
572 textbox NEWT_TEXTBOX_* constants
573 macros
574 macros to make useful buttons and panels: OK_BUTTON, CANCEL_BUTTON,
575 QUIT_BUTTON, BACK_BUTTON, OK_CANCEL_PANEL, OK_BACK_PANEL. This
576 macros only create components which are properly tagged.
577
579 Scrollable panels.
580 Some forms stuff, like watching file descriptors.
581
583 Writing programs using Newt, by Erik Troan.
584
586 Erik Troan, for writing this useful library. Thanks for his tutorial,
587 too, from where I stole complete paragraphs for this documentation, I'm
588 afraid.
589
591 The original author of the Red Hat newt library is Erik Troan,
592 <ewt@redhat.com> The author of this Perl bindings is Alejandro
593 Escalante Medina, <amedina@msg.com.mx>
594
596 Version 0.1, 5th Nov 1998
597perl v5.8.8 2007-03-01 Newt(3)