1=head1 NAME 2 3UI::Dialog::Backend - simply a collection of primarily internal methods. 4 5=head1 SYNOPSIS 6 7 use UI::Dialog::Backend; 8 BEGIN { 9 use vars qw( @ISA ); 10 @ISA = qw( UI::Dialog::Backend ); 11 } 12 13=head1 ABSTRACT 14 15UI::Dialog::Backend is simply a collection of primarily internal methods. 16 17=head1 DESCRIPTION 18 19While this module is inherited by all UI::Dialog backend modules, this module 20itself is not meant for direct usage. The "STATE METHODS" and "UTILITY METHODS" 21documentation is applicable to all backends thus rendering the POD for this class 22more important to the end-programmer than the usage of the class itself. 23 24=head1 EXPORT 25 26=over 2 27 28None 29 30=back 31 32=head1 INHERITS 33 34=over 2 35 36None 37 38=back 39 40=head1 BACKEND EXTENSIONS 41 42=head2 nautilus 43 44=over 4 45 46=item EXAMPLE 47 48=over 6 49 50 my @paths = $d->nautilus->paths(); 51 52=back 53 54=item DESCRIPTION 55 56=over 6 57 58This method gives access to the UI::Dialog::Backend::Nautilus class. This will 59automagically try to load the UI::Dialog::Backend::Nautilus module or it will 60silently fail. 61 62=back 63 64=back 65 66=head2 xosd 67 68=over 4 69 70=item EXAMPLE 71 72=over 6 73 74 $d->xosd->line( "a line of text on your screen" ); 75 76=back 77 78=item DESCRIPTION 79 80=over 6 81 82This method gives access to the UI::Dialog::Backend::XOSD class. This will 83automagically try to load the UI::Dialog::Backend::XOSD module or it will 84silently fail. 85 86=back 87 88=back 89 90=head2 notify_send 91 92=over 4 93 94=item EXAMPLE 95 96=over 6 97 98 $d->notify_send->notify_send( "a line of text on your screen" ); 99 100=back 101 102=item DESCRIPTION 103 104=over 6 105 106This method gives access to the UI::Dialog::Backend::NotifySend class. This will 107automagically try to load the UI::Dialog::Backend::NotifySend module or it will 108silently fail. 109 110=back 111 112=back 113 114=head1 STATE METHODS 115 116=head2 attr( ) 117 118=over 4 119 120=item EXAMPLE 121 122=over 6 123 124 my $value = $self->attr('listheight'); 125 my $new_value = $d->attr('listheight',5); 126 127=back 128 129=item DESCRIPTION 130 131=over 6 132 133Either sets and returns the value of the desired attribute, or just returns 134the value of the desired attribute. 135 136=back 137 138=item RETURNS 139 140=over 6 141 142a single SCALAR. 143 144=back 145 146=back 147 148=head2 state( ) 149 150=over 4 151 152=item EXAMPLE 153 154=over 6 155 156 if ($d->state() eq "OK") { 157 # the last user response was "OK" 158 } else { 159 # something other than an "OK" response 160 } 161 162=back 163 164=item DESCRIPTION 165 166=over 6 167 168Returns the state of the last dialog widget command. The value can be one of 169"OK", "CANCEL" or "ESC". The return data is based on the exit codes (return 170value) of the last widget displayed. Some backends also support other exit 171values than the standard few and these are represented as "EXTRA" (3), "HELP" 172(2), and "ERROR" (255). 173 174=back 175 176=item RETURNS 177 178=over 6 179 180a single SCALAR. 181 182=back 183 184=back 185 186=head2 ra( ) 187 188=over 4 189 190=item EXAMPLE 191 192=over 6 193 194 my @array = $d->ra(); 195 196=back 197 198=item DESCRIPTION 199 200=over 6 201 202Returns the last widget's data as an array. 203 204=back 205 206=item RETURNS 207 208=over 6 209 210an ARRAY. 211 212=back 213 214=back 215 216=head2 rs( ) 217 218=over 4 219 220=item EXAMPLE 221 222=over 6 223 224 my $string = $d->rs(); 225 226=back 227 228=item DESCRIPTION 229 230=over 6 231 232Returns the last widget's data as a (possibly multiline) string. 233 234=back 235 236=item RETURNS 237 238=over 6 239 240a SCALAR. 241 242=back 243 244=back 245 246=head2 rv( ) 247 248=over 4 249 250=item EXAMPLE 251 252=over 6 253 254 my $string = $d->rv(); 255 256=back 257 258=item DESCRIPTION 259 260=over 6 261 262Returns the last widget's exit status, aka: return value. This is the value 263used when determining the state() of a widget. 264 265=back 266 267=item RETURNS 268 269=over 6 270 271a SCALAR. 272 273=back 274 275=back 276 277=head1 CALLBACK FUNCTIONS 278 279=head2 PRE 280 281=over 4 282 283=item EXAMPLE 284 285=over 6 286 287 sub CB_PRE { 288 my $widget_args = shift(); 289 print "Caller: ".$args->{'caller'}."\n"; 290 } 291 my $d = new UI::Dialog ( callbacks => { PRE => \&CB_PRE } ); 292 293=back 294 295=item DESCRIPTION 296 297=over 6 298 299This function recieves a hasref of the current argument values and is called 300before any widget performs any operations. 301 302=back 303 304=back 305 306=head2 POST 307 308=over 4 309 310=item EXAMPLE 311 312=over 6 313 314 sub CB_POST { 315 my $widget_args = shift(); 316 my $state = shift(); 317 print "Caller: ".$args->{'caller'}.", State: ".$state."\n"; 318 } 319 my $d = new UI::Dialog ( callbacks => { POST => \&CB_POST } ); 320 321=back 322 323=item DESCRIPTION 324 325=over 6 326 327This function recieves a hasref of the current argument values and the one word 328state indicator (as reported by state()) and is called after all widget 329operations have been performed (including other callback functions). 330 331=back 332 333=back 334 335=head2 OK 336 337=over 4 338 339=item EXAMPLE 340 341=over 6 342 343 sub CB_OK_FUNC { 344 my $widget_args = shift(); 345 print "Widget caller: ".$args->{'caller'}."\n"; 346 } 347 my $d = new UI::Dialog ( callbacks => { OK => \&CB_OK_FUNC } ); 348 349=back 350 351=item DESCRIPTION 352 353=over 6 354 355This function recieves a hasref of the current argument values and is called 356when any widget finishes with a state() of "OK" but before the POST callback. 357 358=back 359 360=back 361 362=head2 CANCEL 363 364=over 4 365 366=item EXAMPLE 367 368=over 6 369 370 sub CB_CANCEL { 371 my $widget_args = shift(); 372 print "Caller: ".$args->{'caller'}."\n"; 373 } 374 my $d = new UI::Dialog ( callbacks => { CANCEL => \&CB_CANCEL } ); 375 376=back 377 378=item DESCRIPTION 379 380=over 6 381 382This function recieves a hasref of the current argument values and is called 383when any widget finishes with a state() of "CANCEL" but before the POST 384callback. Be forewarned that with respect to the yesno() type widgets, a 385user response of "NO" is interpreted as "CANCEL" and will execute this function. 386 387=back 388 389=back 390 391=head2 ESC 392 393=over 4 394 395=item EXAMPLE 396 397=over 6 398 399 sub CB_ESC { 400 my $widget_args = shift(); 401 print "Caller: ".$args->{'caller'}."\n"; 402 } 403 my $d = new UI::Dialog ( callbacks => { ESC => \&CB_ESC } ); 404 405=back 406 407=item DESCRIPTION 408 409=over 6 410 411This function recieves a hasref of the current argument values and is called 412when any widget finishes with a state() of "ESC" but before the POST callback. 413 414=back 415 416=back 417 418=head2 HELP 419 420=over 4 421 422=item EXAMPLE 423 424=over 6 425 426 sub CB_HELP { 427 my $widget_args = shift(); 428 print "Caller: ".$args->{'caller'}."\n"; 429 } 430 my $d = new UI::Dialog ( callbacks => { HELP => \&CB_HELP } ); 431 432=back 433 434=item DESCRIPTION 435 436=over 6 437 438This function recieves a hasref of the current argument values and is called 439when any widget finishes with a state() of "HELP" but before the POST callback. 440The user response of "HELP" is not supported by all backends. 441 442=back 443 444=back 445 446=head2 EXTRA 447 448=over 4 449 450=item EXAMPLE 451 452=over 6 453 454 sub CB_EXTRA { 455 my $widget_args = shift(); 456 print "Caller: ".$args->{'caller'}."\n"; 457 } 458 my $d = new UI::Dialog ( callbacks => { EXTRA => \&CB_EXTRA } ); 459 460=back 461 462=item DESCRIPTION 463 464=over 6 465 466This function recieves a hasref of the current argument values and is called 467when any widget finishes with a state() of "EXTRA" but before the POST callback. 468The user response of "EXTRA" is not supported by all backends. 469 470=back 471 472=back 473 474=head1 UTILITY METHODS 475 476=head2 beep( ) 477 478=over 4 479 480=item EXAMPLE 481 482=over 6 483 484 $d->beep(); 485 486=back 487 488=item DESCRIPTION 489 490=over 6 491 492If the beep(1) application can be found, use it to make a beep sound. 493Otherwise print "\a" to STDERR which normally is good enough to make 494some noise. 495 496=back 497 498=item RETURNS 499 500=over 6 501 502TRUE (1) regardless of result. 503 504=back 505 506=back 507 508=head2 clear( ) 509 510=over 4 511 512=item EXAMPLE 513 514=over 6 515 516 $d->clear(); 517 518=back 519 520=item DESCRIPTION 521 522=over 6 523 524Clear the terminal screen via STDOUT and the `clear` command. This method is 525technically useless for any GUI based dialog variants. 526 527=back 528 529=item RETURNS 530 531=over 6 532 533TRUE (1) regardless of result. 534 535=back 536 537=back 538 539=head2 word_wrap( ) 540 541=over 4 542 543=item EXAMPLE 544 545=over 6 546 547 my @wrapped_text = $d->word_wrap($cols,$indent,$sub_indent,@text); 548 549=back 550 551=item DESCRIPTION 552 553=over 6 554 555Using the Text::Wrap::wrap function, wrap the words in a string (or array of 556strings). This is primarily used within the _organize_text() method but may 557be of use to the end-programmer. 558 559=back 560 561=item RETURNS 562 563=over 6 564 565A word-wrapped version of the given text data. 566 567=back 568 569=back 570 571=head2 gen_tempfile_name( ) 572 573=over 4 574 575=item EXAMPLE 576 577=over 6 578 579 my $tempfile = $d->gen_tempfile_name(); 580 581=back 582 583=item DESCRIPTION 584 585=over 6 586 587This method returns a temporary file name generated using one of the following 588(in order): the File::Temp perl module if detected, the program "mktemp" or 589an extremely simplistic built-in name generator. 590 591=back 592 593=item RETURNS 594 595=over 6 596 597A temporary file name. 598 599=back 600 601=back 602 603=head2 gen_random_string( ) 604 605=over 4 606 607=item EXAMPLE 608 609=over 6 610 611 my $random_string = $d->gen_random_string(5); 612 613=back 614 615=item DESCRIPTION 616 617=over 6 618 619This will return a string of random (printable) characters of an arbitrary 620user-definable length (defaults to 5); 621 622=back 623 624=item RETURNS 625 626=over 6 627 628A string of random ASCII characters. 629 630=back 631 632=back 633 634=head1 WIDGET WRAPPER METHODS 635 636These methods are common methods to most backends as they do not have native 637support for the functionality, yet the functionality is achievable by utilizing 638existing compatible methods. 639 640=head2 fselect( ) 641 642=over 4 643 644=item EXAMPLE 645 646=over 6 647 648 my $path = $self->fselect( path => $start_path ); 649 650=back 651 652=item DESCRIPTION 653 654=over 6 655 656Using the menu() and msgbox() widgets we can simulate a file browser interface. 657Note: to select a directory, go into it and then pick the '.' entry. 658 659=back 660 661=item RETURNS 662 663=over 6 664 665a SCALAR for positive results and FALSE (0) for everything else. 666 667=back 668 669=back 670 671=head2 dselect( ) 672 673=over 4 674 675=item EXAMPLE 676 677=over 6 678 679 my $path = $self->dselect( path => $start_path ); 680 681=back 682 683=item DESCRIPTION 684 685=over 6 686 687Using the fselect() widget we can simulate a directory browser interface. 688Note: to select a directory, go into it and then pick the '.' entry. 689 690=back 691 692=item RETURNS 693 694=over 6 695 696a SCALAR for positive results and FALSE (0) for everything else. 697 698=back 699 700=back 701 702=head1 BACKEND METHODS 703 704These methods are only necessary for someone wishing to create more 705UI::Dialog::Backend:: Modules. These are never needed to be directly 706used but are none the less documented here for reference purposes. 707 708=head2 command_state( ) 709 710=over 4 711 712=item EXAMPLE 713 714=over 6 715 716 if ($self->command_state("/some/shell/command")) { 717 #: command succeeded 718 } else { 719 #: command failed 720 } 721 722=back 723 724=item DESCRIPTION 725 726=over 6 727 728This will execute the given command and send STDOUT and STDERR to /dev/null 729then analyse the exit code and return accordingly. 730 731=back 732 733=item RETURNS 734 735=over 6 736 737TRUE (1) for positive results and FALSE (0) for anything else. 738 739=back 740 741=back 742 743=head2 command_string( ) 744 745=over 4 746 747=item EXAMPLE 748 749=over 6 750 751 my ($rv,$scalar) = $self->command_string("/some/shell/command"); 752 if ($rv >= 1) { 753 #: command failed 754 } else { 755 #: command succeeded 756 print "The command results: ".$scalar."\n"; 757 } 758 759=back 760 761=item DESCRIPTION 762 763=over 6 764 765This will execute the given command, catch STDOUT and STDERR, then return 766the SCALAR data. 767 768=back 769 770=item RETURNS 771 772=over 6 773 774a SCALAR for positive results and FALSE (0) for anything else. 775 776=back 777 778=back 779 780=head2 command_array( ) 781 782=over 4 783 784=item EXAMPLE 785 786=over 6 787 788 my ($rv,@array) = $self->command_array("/some/shell/command"); 789 if ($rv >= 1) { 790 #: command failed 791 } else { 792 #: command succeeded 793 foreach my $line_of_output (@array) { 794 print "The command results: ".$line_of_output."\n"; 795 } 796 } 797 798=back 799 800=item DESCRIPTION 801 802=over 6 803 804This will execute the given command, catch STDOUT and STDERR, then return 805the data, split by newlines, as an ARRAY. 806 807=back 808 809=item RETURNS 810 811=over 6 812 813an ARRAY for positive results and FALSE (0) for anything else. 814 815=back 816 817=back 818 819=head2 _pre( ) 820 821=over 4 822 823=item EXAMPLE 824 825=over 6 826 827 my $args = $self->_pre(@_); 828 829=back 830 831=item DESCRIPTION 832 833=over 6 834 835This will use _merge_attrs(), perform any pre-widget-exec things and 836then return the current argument list as a hashref. This is used in 837every widget before anything is actually done in the widget and is 838responsible for running the optional callback function labelled "PRE". 839 840=back 841 842=item RETURNS 843 844=over 6 845 846a HASHREF. 847 848=back 849 850=back 851 852=head2 _post( ) 853 854=over 4 855 856=item EXAMPLE 857 858=over 6 859 860 $self->_post( $args ); 861 862=back 863 864=item DESCRIPTION 865 866=over 6 867 868This method is used in every widget after all operations (for the immediate 869widget call) are complete but before the widget actually returns anything. This 870method is responsible for running the optional callback funcions labelled "OK", 871"ESC", "CANCEL" and "POST" with "POST" being executed absolutely last. 872 873=back 874 875=item RETURNS 876 877=over 6 878 879Nothing. 880 881=back 882 883=back 884 885=head2 _merge_attrs( ) 886 887=over 4 888 889=item EXAMPLE 890 891=over 6 892 893 my $args = $self->_merge_attrs(@_); 894 895=back 896 897=item DESCRIPTION 898 899=over 6 900 901This will apply the arguments passed in with the defaults stored in 902$self->{'_opts'} (which was instantiated upon object construction). 903The return result is the "current" options as defined by the defaults 904with the argument options overriding them. 905 906=back 907 908=item RETURNS 909 910=over 6 911 912a HASHREF. 913 914=back 915 916=back 917 918=head2 _find_bin( ) 919 920=over 4 921 922=item EXAMPLE 923 924=over 6 925 926 my $ZenityBinaryPath = $self->_find_bin('zenity'); 927 928=back 929 930=item DESCRIPTION 931 932=over 6 933 934This will look in the default path directories for the program of the given 935name. The default PATH list is: /bin, /usr/bin, /usr/local/bin, /opt/bin. 936 937=back 938 939=item RETURNS 940 941=over 6 942 943a SCALAR. 944 945=back 946 947=back 948 949=head2 _esc_text( ) 950 951=over 4 952 953=item EXAMPLE 954 955=over 6 956 957 my $escaped_text = $self->_esc_text( $raw_text ); 958 959=back 960 961=item DESCRIPTION 962 963=over 6 964 965This will escape the following with a prefixing '\' character: 966 967 Character -> Escaped 968 969 " \" 970 ` \` 971 ( \( 972 ) \) 973 [ \[ 974 ] \] 975 { \} 976 } \} 977 $ \$ 978 < \< 979 > \> 980 981=back 982 983=item RETURNS 984 985=over 6 986 987an SCALAR for positive results and FALSE (0) for anything else. 988 989=back 990 991=back 992 993=head2 _strip_text( ) 994 995=over 4 996 997=item EXAMPLE 998 999=over 6 1000 1001 my $clean_text = $self->_strip_text( $text_with_markup ); 1002 1003=back 1004 1005=item DESCRIPTION 1006 1007=over 6 1008 1009This will strip various markup sequences from within the given argument data. 1010 1011=back 1012 1013=item RETURNS 1014 1015=over 6 1016 1017an SCALAR for positive results and FALSE (0) for anything else. 1018 1019=back 1020 1021=back 1022 1023=head2 _organize_text( ) 1024 1025=over 4 1026 1027=item EXAMPLE 1028 1029=over 6 1030 1031 my $final_text1 = $self->_organize_text( $text_with_markup ); 1032 my $final_text2 = $self->_organize_text( \@text_with_markup ); 1033 1034=back 1035 1036=item DESCRIPTION 1037 1038=over 6 1039 1040This will strip various markup sequences from within the given argument data. 1041 1042=back 1043 1044=item RETURNS 1045 1046=over 6 1047 1048a SCALAR for positive results and FALSE (0) for anything else. 1049 1050=back 1051 1052=back 1053 1054=head2 _is_bsd( ) 1055 1056=over 4 1057 1058=item EXAMPLE 1059 1060=over 6 1061 1062 if ($self->_is_bsd()) { 1063 # do something with BSD specific characteristics 1064 } else { 1065 # do something with general perl characteristics 1066 } 1067 1068=back 1069 1070=item DESCRIPTION 1071 1072=over 6 1073 1074This simply checks (case-insensitively) the perlvar $^0 for the string "bsd". 1075 1076=back 1077 1078=item RETURNS 1079 1080=over 6 1081 1082TRUE (1) for positive results and FALSE (0) for anything else. 1083 1084=back 1085 1086=back 1087 1088=head2 _list_dir( ) 1089 1090=over 4 1091 1092=item EXAMPLE 1093 1094=over 6 1095 1096 my $menu_list = $self->_list_dir( '/some/path/to/a/directory', 1097 [ 'optional', 'prefix', 'items' ] ); 1098 1099=back 1100 1101=item DESCRIPTION 1102 1103=over 6 1104 1105Gather a list of the contents of a directory and forumlate a list suitable for 1106use with most (if not all) file/path selection dialog variant widgets. An 1107optional array reference will have all elements prefixing the directory list. 1108 1109=back 1110 1111=item RETURNS 1112 1113=over 6 1114 1115an ARRAYREF for positive results and FALSE (0) for anything else. 1116 1117=back 1118 1119=back 1120 1121=head2 _debug( ) 1122 1123=over 4 1124 1125=item EXAMPLE 1126 1127=over 6 1128 1129 $self->_debug( $debuging_message_string, $debuging_level ); 1130 1131=back 1132 1133=item DESCRIPTION 1134 1135=over 6 1136 1137This method will print to STDERR the debugging message provided if and only 1138if the debuging level is greater than or equal to the $debuging_level. The 1139debugging level argument is optional and defaults to a level of 1. 1140 1141=back 1142 1143=item RETURNS 1144 1145=over 6 1146 1147TRUE (1) for positive results and FALSE (0) for anything else. 1148 1149=back 1150 1151=back 1152 1153=head2 _error( ) 1154 1155=over 4 1156 1157=item EXAMPLE 1158 1159=over 6 1160 1161 $self->_error( $error_message_string ); 1162 1163=back 1164 1165=item DESCRIPTION 1166 1167=over 6 1168 1169This method will print to STDERR the error message provided regardless of 1170debugging level. 1171 1172=back 1173 1174=item RETURNS 1175 1176=over 6 1177 1178TRUE (1) for positive results and FALSE (0) for anything else. 1179 1180=back 1181 1182=back 1183 1184=head1 SEE ALSO 1185 1186=over 2 1187 1188=item PERLDOC 1189 1190 UI::Dialog 1191 UI::Dialog::Console 1192 UI::Dialog::GNOME 1193 UI::Dialog::KDE 1194 UI::Dialog::Backend::ASCII 1195 UI::Dialog::Backend::CDialog 1196 UI::Dialog::Backend::GDialog 1197 UI::Dialog::Backend::KDialog 1198 UI::Dialog::Backend::Nautilus 1199 UI::Dialog::Backend::Whiptail 1200 UI::Dialog::Backend::XDialog 1201 UI::Dialog::Backend::XOSD 1202 UI::Dialog::Backend::Zenity 1203 1204=back 1205 1206=over 2 1207 1208=item MAN FILES 1209 1210 dialog(1), whiptail(1), zenity(1), gdialog(1), Xdialog(1), 1211 kdialog(1), nautilus(1) and osd_cat(1). 1212 1213=back 1214 1215=head1 BUGS 1216 1217Please email the author with any bug reports. Include the name of the 1218module in the subject line. 1219 1220=head1 AUTHOR 1221 1222Kevin C. Krinke, E<lt>kevin@krinke.caE<gt> 1223 1224=head1 COPYRIGHT AND LICENSE 1225 1226 Copyright (C) 2004-2016 Kevin C. Krinke <kevin@krinke.ca> 1227 1228 This library is free software; you can redistribute it and/or 1229 modify it under the terms of the GNU Lesser General Public 1230 License as published by the Free Software Foundation; either 1231 version 2.1 of the License, or (at your option) any later version. 1232 1233 This library is distributed in the hope that it will be useful, 1234 but WITHOUT ANY WARRANTY; without even the implied warranty of 1235 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 1236 Lesser General Public License for more details. 1237 1238 You should have received a copy of the GNU Lesser General Public 1239 License along with this library; if not, write to the Free Software 1240 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 1241 1242=cut 1243