oota toshiya
ribbo****@users*****
2005年 9月 23日 (金) 21:40:48 JST
Index: docs/modules/Cmenu-1.1/Cmenu.pod
diff -u /dev/null docs/modules/Cmenu-1.1/Cmenu.pod:1.1
--- /dev/null Fri Sep 23 21:40:48 2005
+++ docs/modules/Cmenu-1.1/Cmenu.pod Fri Sep 23 21:40:48 2005
@@ -0,0 +1,408 @@
+=head1 NAME
+
+Cmenu - perlスクリプト中のデータ入力とメニューのためのPerl拡張
+Cmenu - Perl extension for menuing and data entry in perl scripts
+
+=head1 SYNOPSIS
+
+ use Cmenu;
+ use Curses;
+ use Text::Wrap;
+
+ &menu_initialise($main_title,$advice);
+ &menu_init($title,$sub-title,$topest,$menu_help);
+ &menu_item($item_text,$item_label,$item_style,$item_data,$item_pos)
+ &menu_item($item_text,$item_label,$item_style,$item_data,$item_pos)
+ ...
+ &menu_item($item_text,$item_label,$item_style,$item_data,$item_pos)
+
+ $sel=&menu_display($advice,$start_item);
+
+ &menu_button_set($button,$button_text);
+
+ &menu_popup($title,$text);
+ ...
+ &menu_popup();
+
+ &menu_show($title,$text,$colour);
+
+ &menu_terminate($message);
+
+=head1 DESCRIPTION
+
+CMENU はperlスクリプト中でメニューの生成のための機能を提供するために
+設計されたPerlモジュールである。
+
+CMENU is a Perl Module designed to provide functions for the
+creation of menus in perl scripts.
+
+これは perlmenu から継続しているが、画面操作のためにCursesインタフェース
+を使用する。これはまた表示のために、大きなテキストを処理する Text::Wrap
+モジュールも使う。これらの2つのモジュールはユーザのスクリプトによって
+ロードされねばならない。
+
+It follows on from perlmenu but uses a Curses interface for
+screen manipulation. It also uses the Text::Wrap module to
+process large chunks of text for display. These two modules
+should be loaded by user scripts.
+
+メニュー操作の順番は以下のとおり;
+ 1. モジュールの初期化
+ loop
+ 2. メニュー構造の定義
+ 3. いくつかのメニューオプションの定義
+ 4. メニューの呼び出し
+ 5. 選択されたメニューの処理
+ loop
+ 6. モジュールの終了
+
+モジュールはいくつかの機能も提供している。
+
+The sequence of menu processing is as follows;
+ 1. Initialise the module
+ loop
+ 2. Define a menu structure
+ 3. Define several menu options
+ 4. Call the menu
+ 5. Deal with the menu selections
+ loop
+ 6. Terminate the module
+
+The module also provide some extra functions.
+
+
+=head2 menu_initialise
+
+このルーチンはCursesを初期化し、メニューモジュールのために必要な
+構造を生成する。これは、空白でもよい2つのパラメータを受け付ける。
+ $main_title スクリプト全体で使える、全てのページで表示される題名
+ $advice 全ての画面(モジュールによって上書きされるもの以外)
+ の下部に表示される助言的な短いテキスト
+これらの関数は何も帰さない。
+
+This routine initialises Curses and creates necessary structures
+for the menu module. It accepts two parameters which may be empty;
+ $main_title A script-wide title displayed on all pages
+ $advice A short text advisory displayed at the foot
+ of every screen (unless over-ridden by the
+ module).
+The routine returns nothing.
+
+=head2 menu_init
+
+このルーチンは、コマンドラインユーティリティ "dialog"形式でグラフィック
+背景を作成する。3つのパラメータを受け付ける。
+ $title 丈夫に表示されるメニュータイトル
+ $sub_title より詳しい説明を提供するためのサブタイトルテキスト
+ $menu_help Helpキーが押されたときに表示されるヘルプファイル。
+ ヘルプファイルは構成ファイル中に定義されている標準の
+ 位置に置かれる(オプションである)
+
+The routine creates a graphic backdrop in the style of the
+command-line utility "dialog". It accepts 3 parameters
+ $title a menu title displayed at the top
+ $sub_title sub-title text used to give more description
+ $menu_help a help-file to be displayed when the Help key
+ is pressed. The help file is located in a
+ standard location as defined in the configuration
+ file. (optional)
+
+=head2 menu_item
+
+それぞれのメニュー業は以下を呼び出すことで生成される。
+ $item_text メニューオプションとして表示されるテキスト
+ $item_label テキストの脇に表示することができるテキストのラベル
+ $item_style どのようにこのオプションが表示されるか、あるいは
+ 動作するかを定義。数字の0から9を指定する。
+ 0 (既定値) テキストラベルとテキストを結合して表示
+ メニューが選択されたときにラベルが返る。
+ 1 テキストラベルの代りに番号を表示。定義順に番号が
+ 振られる。
+ 2 項目は選択リストの一部となる。メニューにつき1つ
+ の項目のみ選択リストから選択可能。
+ 3 項目はチェックリストの一部となる。チェックリストは
+ (無選択を含む)複数個の項目を選択可能。
+ 4 タイプ0のようだが、テキストがフィールドの内容であり、
+ ラベルがその意味であるデータフィールドを表示するため
+ に、異なった形で表示される所が違う。
+ 5 タイプ4のようだが項目のテキストが右寄せになる
+ 6 4と同じだが、項目が選択された場合、フィールドの内容
+ が編集可能なところが違う。
+ 7 6と同じだが、フィールドは数字値として扱われる
+ 8 4のように表示されるが、選択されたときに(テキストラベル
+ でなはく)別の参照値が返る。
+ 9 スペーサ;メニューを空白で区切る。
+
+Each line of a menu is created using this call.
+ $item_text The text to be displayed as the menu option
+ $item_label A text label which may be displayed beside
+ the text
+ $item_style How the menu option should be drawn or behave
+ Should be a number from 0 to 9
+ 0 (default) preceeds the text with a text label
+ the label is returned if the item is selected
+ 1 use number instead of a text label; numbered in
+ order of definition
+ 2 item is part of a radio list; radio lists allow
+ only ONE item to be selected per menu
+ 3 item is part of a check list; check lists allow
+ any number (inc. none) of items to be selected
+ 4 as for type 0 expect item label is rendered differently
+ usually used to list data fields where the text is
+ the contents of a field and the label is its meaning
+ 5 as for 4 except the item text is right-aligned
+ 6 as for 4 but if the item is selected, field contents
+ can be edited
+ 7 as for 6 except field treated as a numeric value
+ 8 displayed as for 4 except an alternative reference
+ (not the text label) is returned when selected
+ 9 spacer; leaves a space in the menu
+
+ $item_data 特別な情報を必要とするいくつかの項目形式
+ 2 あらかじめ選択されている選択リストの項目
+ 3 あらかじめ選択されているチェックリストの項目
+ 6 フィールドの戻り値を定義
+ 7 6と同じ
+ 8 6と同じ
+
+ $item_data Some item styles need extra information
+ 2 which item in a radio list is already active
+ 3 item in a check list already selected
+ 6 specifies the return value for the field
+ 7 as for 6
+ 8 as for 6
+
+ $item pos フィールド編集のみ(6と7);データフィールドの
+ 最大値と数字の桁数を指定。たとえば "30 2 0"
+ のように空白で区切られたリストで指定する。
+ 例の場合は30桁で2つの数字がある。
+
+ $item pos For edit fields only (6 + 7); specifies the
+ maximum length of a data field and decimal
+ precision for numbers. Passed as a space
+ seperated list eg "30 2 0", length 30 with
+ 2 decimal places
+
+=head2 menu_display
+
+実際にメニューの表示とナビゲーションを実行する。選択された動作
+に対応した情報が返る。2つのパラメータを指定できる。
+
+
+ $menu_prompt 助言として画面の下部に表示される
+ $menu_start 開始時から有効にすべき項目
+ これは、項目に対して、最初に選択するように定義
+ されたようにする。以前の選択の後にメニューに戻
+ るときに便利である(オプション)
+
+Actually performs the menu display and navigation. Returns
+information relevant to the action selected. Accepts 2 parametrs;
+
+ $menu_prompt Displayed at the foot of the screen as advice
+ $menu_start Which item should be active from the start
+ This allows items other than the first declared
+ to be selected; useful when returning to a menu
+ after an earlier selection (optional)
+
+これは、メニューナビゲーションの結果が返ってくる重要な呼び出し
+である。メニュー項目が定義されたスタイルに依存して色々な結果が
+戻る。一般的に、全ての選択が標準文字($Cmenu::menu_sep で変更可
+能)によって分離されたトークン化されたリストである。単純なメニュー
+のために、選択されたテキストラベル(0,1,4,5)またはオフセット(8)
+を戻すこともできる。
+
+This is the important call which returns the result of menu
+navigation. Depending on the style of menu items defined, various results
+will be returned. Generally all selections are a tokenised list seperated
+by a standard character ($Cmenu::menu_sep - can be changed by user). For
+simple menus, only the selected text label (0,1,4,5) or offset (8) will be
+returned.
+
+選択チェックリスト(2と3)のために、全ての選択された項目が、
+それぞれの項目のテキストラベルを使って返る。
+For radio and check lists (2 and 3) all the selected items will be returned
+using each items text label
+
+編集されたフィールドのために、より複雑な値が戻る。すべての
+メニュー上の編集可能なフィールドはトークン(編集されるか否か
+にかかわらず)が戻る。それぞれのトークンは2つのフィールドを
+持つ。それは、フィールドラベルと新しいフィールド内容である。
+それらは$Cmenu::menu_scan によって分離される。
+
+For edited data fields, more complex values are returned. All editable fields
+on a menu will have a token (whether edited or not) returned. Each token has two
+fields - the field label and the new field contents; these are seperated by
+$Cmenu::menu_sepn.
+
+任意のタイプの項目はメニュー中に含むことができるので、戻り値
+は複雑であってもよい。複雑な戻り値のために、たとえば、以下の
+ように、トークンはコマンドフラグメントを使って分割することが
+できる。
+
+ chop($return_value=&menu_display("Menu Prompt",$start_on_menu_item));
+ @selection=split(/$Cmenu::menu_sep/,$return_value);
+ for($loop=1;$loop<=$#selection;$i++) {
+ # deal with each token
+ ($field_label,$field_content) = split(/$Cmenu::menu_sepn,$selection[$i]);
+ # processing each field accordingly
+ ...
+ }
+
+Since any type of item can be included in a menu, return values may be
+equally complex. For complex return values, tokens can be split out using
+a command fragment such as
+
+ chop($return_value=&menu_display("Menu Prompt",$start_on_menu_item));
+ @selection=split(/$Cmenu::menu_sep/,$return_value);
+ for($loop=1;$loop<=$#selection;$i++) {
+ # deal with each token
+ ($field_label,$field_content) = split(/$Cmenu::menu_sepn,$selection[$i]);
+ # processing each field accordingly
+ ...
+ }
+
+最初のトークンは($selection[0])として戻り、これは通常メニューが
+閉じられた時に押されたキーである。これはめったに有効なメニュー
+項目ではない - "異常終了"が要求されていないことを確かめる必要が
+ある。
+
+The first token returned ($selection[0]) is usually the key pressed to close the
+menu was closed; this will rarely be a valid menu item - check it to make sure
+an "abort" was not requested.
+
+=head2 menu_button_set
+
+それぞれのメニューは、有効にできる最大3つのボタンを持つ。通常、
+それらはオプションに、メニュー項目を受け取りか急いでメニューを
+中止のどちらかを与える。ヘルプ機能はいつでも呼び出せる。
+
+Each menu has up to 3 buttons which can be activated. Usually these give
+options to either Accept a menu item or Abort the menu prematurely. A Help
+facility may also be called.
+
+このルーチンは、ボタンをon/offし、ボタンのテキストラベルを指定
+する(ボタン動作は、期待するにもかかわらず、作成したスクリプトは、
+それらのレスポンスに割り込むのが可能であるとしても、"ACCEPT"、
+"HELP"、または"EXIT"が必要だが変更できない)。<TAB>キーはボタン
+バーを移動する。
+
+This routine switches buttons on and off and, specifies the text label of the button
+(button actions cannot be altered yielding "ACCEPT", "HELP" or "EXIT" although your
+scripts can interret these responses however you wish). The <TAB> key
+traverses the buttons bar.
+
+ルーチンのパラメータは以下のとおり。
+ $button どのボタンが選択されたかを示す1,2または3という数字
+ $label ボタンのためのテキストラベル。空白文字列の場合はボタン
+ をoffにする。
+
+Parameters for this routine are;
+ $button a number 1, 2 or 3 specifying which button is to be set
+ $label the text label for the button; an empty string switches the button off
+
+=head2 menu_popup
+
+もしも、長いプロセスが起動された場合、簡単な画面をポップアップ
+することができる。ポップアップはシステムが何をするかを示す1行の
+文字列のみを持つ。
+ ポップアップの開始は $message 付きで呼び出す。
+ ポップアップの終了は メッセージなしで呼び出す。
+ポップアップを閉じることはメニュー表示を混乱させることに注意。
+
+Allows a simple screen to pop-up if a lengthy process has been launched. The popup
+has only one line of text to give an indication of what the system is doing;
+ To start a popup - call with $message
+ To close a popup - call with NO message
+Remember to close the popup or the menu display will get confused.
+
+=head2 menu_show
+
+画面上に色々な情報を表示する。画面は通常適当なキーを押すまで
+通常のメニューに置き代わる。
+ルーチンは3つのパラメータを取る。
+ $title ディスプレイのタイトル
+ $message 表示されるメッセージ。もしも、これが1行であれば、
+ 中心に置かれる。もしもそれより長ければ、Text::wrap
+ ルーチンが呼ばれ、画面上にうまく配置するようにテキ
+ ストが操作される。テキストの整形は全く原始的である。
+ ディスプレイは有効なウィンドウの領域を超過したとして
+ も、スクロールすることはできない。
+ $colour HELP|WARN|ERRORから選ばれた画面を描画するための色
+ スタイル。
+ HELP画面は、継続のための自動的なボタンを持つ。WARNと
+ ERRORは、複数のボタンを持つことができる(これを制御す
+ るには menu_button_setを使う)。
+
+Allows a variety of information to be shown on the screen; the display
+generally replaces normal menu rendering until the user presses an approriate key.
+The routines takes 3 parameters
+ $title the title of the display
+ $message the message to be displayed. If this is only one line it will be
+ centred; if longer the external routine Text::wrap is used to
+ manipulated the text to fit on the screen. Text formatting
+ is quite primitive.
+ The display cannot be scrolled if it exceeds the dimensions of
+ the active window
+ $colour colour style to render the display chosen from HELP|WARN|ERROR
+ HELP screens have an automatic button to continue; WARN and ERROR
+ can have multiple buttons (use menu_button_set to control these)
+
+=head2 menu_terminate
+
+メニュー機能とCursesを終了し、クローズするために、スクリプトと
+して呼ばれる。端末は妥当な状態にしなければならない。$message
+パラメータはSTDOUTにscript/routineが終了として表示する。
+
+もしも、スクリプトがこれを呼び出す前に異常終了すると、ttyの妥当
+性は失われる。妥当性を復元するために"reset"コマンドを使う。
+
+Called as the script terminates to close down menu facilities and Curses.
+The terminal should be left in a sane state. The $message parameter prints
+to STDOUT as the script/routine finishes.
+
+If a scripts aborts before calling this, the sanity of the tty will likely
+get lost; use the command "reset" to restore sanity.
+
+=head1 AUTHOR
+
+Andy Ferguson andy****@moil*****
+
+=head1 FILES
+
+cmenurc ターミナルと画面の既定値を設定する構成ファイル
+ このファイルは以下のとおり
+ システム共通 - /etc/Cmenu/.cmenurc
+ ユーザ固有 - ~/.cmenurc
+ 実行時固有 - ./cmenurc
+ 内容は提供されたファイルを参照のこと。
+
+cmenurc configuration file to set terminal and screen defaults
+ this file may be
+ System Wide - in /etc/Cmenu/.cmenurc
+ User specific - ~/.cmenurc
+ Run Specific - ./cmenurc
+ See the distributed file for contents.
+
+vt100-wy60 Wyse 60 端末上での VT100 エミュレーションのための
+ tic (terminfo)ファイル。これは、ファンクションキー
+ を設定する。
+
+vt100-wy60 A tic (terminfo) file for VT100 emulation on a Wyse 60
+ terminal; this sets the functions keys appropriately
+
+demo モジュールを使ってどのように描画できるかを表示する
+ サンプルスクリプト。
+
+demo A sample script showing how menus can be rendered with the module.
+
+=head1 BUGS
+
+* No continuation pages or checks for text displays overflowing the windows.
+* Resize and Refresh functions can misbehave in spawned shells
+* BACKTAB definition from Curses is lost so can only TAB forwards thru buttons
+
+perl(1).
+
+=head1 日本語訳
+
+2005/09/23 太田俊哉 <ribbo****@sourc*****>