名称

XmList —  OSF/Motif List widget クラス

形式

#include <Xm/List.h>

解説

List は、ユーザが、選択項目のグループから 1 つ以上の項目を選択することができるようにします。 項目は、マウスポインタやキーボードを使用して、いろいろな方法でリストから選択します。

List は、アプリケーションによって定義された文字列の配列を操作します。 各文字列は、それぞれ List 中の項目になります。 すなわち、最初の文字列がポジション 1 の項目になり、2 番目の文字列がポジション 2 の項目になるわけです。

List の表示される大きさは、表示される項目の数を指定することによって設定します。 多数の選択項目をスクロールさせることによって選択できるようにする場合は、 XmCreateScrolledList という簡易関数を使用してください。

項目を選択するには、選択したい項目にマウスポインタあるいはカーソルを移動して、マウスボタンあるいは選択のために定義されているキーを押してください。 選択した時の動作にはいろいろな形式があり、それらは全て選択された項目の色を反転することによってハイライトを表現します。 そしてユーザが選択したことをアプリケーションに知らせるために適切なコールバックが呼び出されます。 アプリケーションは、選択された項目に対して要求される動作をすべて行います。

クラス

List は、Core および XmPrimitive クラスからの動作とリソースを継承します。

クラスポインタは、xmListWidgetClass です。

クラス名は、XmList です。

新しいリソース

次の表は、データを指定するのに用いる widget リソースの一覧です。 継承されたクラスのリソースの値もまた widget の属性として設定することができます。 .Xdefaults ファイルの中で名前やクラスでリソースを参照する場合は、語頭の XmN または XmC を取り除いた名称を用いてください。 .Xdefaults ファイルの中でリソースに定義された値を設定するには、語頭の Xm を取り除いた名称を用いてください。 (大文字と小文字は区別されませんが、語間のアンダースコアは必要です。 ) 「アクセス」欄の文字は、与えられたリソースを、widget 生成時に設定できるか (C)、XtSetValues で設定できるか (S)、XtGetValues で取り出すことができるか (G)、あるいは利用できないか (N/A) を示します。

XmNautomaticSelection
このリソースの値が True で、選択モードが XmBROWSE_SELECT あるいは XmEXTENDED_SELECT の場合、ユーザが新しい項目に移動した時に、XmNsingleSelectionCallback を呼び出します。 False の場合、ユーザがマウスボタンを離すまで、選択のコールバックは呼び出されません。 選択モードを持つこのリソースの対話についての詳細は、「動作」のセクションを参照してください。

XmNbrowseSelectionCallback
ブラウズ選択モードで項目が選択された場合に呼び出されるコールバックのリストを指定します。 コールバックで返されるリーズンは、XmCR_BROWSE_SELECT です。

XmNdefaultActionCallback
項目がダブルクリックによって選択された場合に呼び出されるコールバックのリストを指定します。 コールバックで返されるリーズンは、XmCR_DEFAULT_ACTION です。

XmNdoubleClickInterval
2 度の連続したクリックが、2 度のシングルクリックではなく、ダブルクリックと見なすための最大時間間隔をミリ秒で指定します。

XmNextendedSelectionCallback
項目が拡張された選択モードを使用して選択された場合に呼び出されるコールバックのリストを指定します。 コールバックで返されるリーズンは、XmCR_EXTENDED_SELECT です。

XmNfontList
リスト項目に関連するフォントリストを指定します。 これは、リスト widget の高さを決定するために XmNvisibleItemsCount リソースとともに使用されます。 フォントリストの構造についてのより詳しい情報は、XmString(3X) を参照してください。

XmNitemCount
項目の総数を指定します。 この数は、XmNitems と一致していなければなりません。 これは、エレメントがリストに付け加えられた時、あるいはエレメントがリストから削除された時はいつでも、リストによって自動的に更新されます。

XmNitems
リスト項目として表示されるコンパウンドストリングの配列を指定します。 コンパウンドストリングの生成と構造についてのより詳しい情報は、XmString(3X) を参照してください。

XmNlistMarginHeight
List のボーダと項目の間のマージンの高さを指定します。

XmNlistMarginWidth
List のボーダと項目の間のマージンの幅を指定します。

XmNlistSpacing
リスト項目間のスペースを指定します。 キーボードトラバースが使用可能になっている場合、このスペースの大きさは、 Primitive における XmNhighlightThickness パラメータの値によって増加します。

XmNmultipleSelectionCallback
項目が複数選択モードで選択された場合に呼び出されるコールバックのリストを指定します。 コールバックで返されるリーズンは、XmCR_MULTIPLE_SELECT です。

XmNselectedItemCount
選択された項目リスト中の文字列の数を指定します。

XmNselectedItems
ユーザあるいはアプリケーションによって現在選択されているリスト項目を表現するコンパウンドストリングの配列を指定します。

XmNselectionPolicy
選択動作の解釈を指定します。 これは、次のいずれか 1 つです。

•XmSINGLE_SELECT — 1 つの選択のみを許します。

•XmMULTIPLE_SELECT — 複数の選択を許します。

•XmEXTENDED_SELECT — 拡張された選択を許します。

•XmBROWSE_SELECT — PM の 「ドラッグとブラウズ」機能を許します。

XmNsingleSelectionCallback
項目が単一選択モードで選択された場合に呼び出されるコールバックリストを指定します。 コールバックで返されるリーズンは、XmCR_SINGLE_SELECT です。

XmNstringDirection
文字列を描く初期方向を指定します。 このリソースの値は、XmSTRING_DIRECTION_L_TO_R および XmSTRING_DIRECTION_R_TO_L です。

XmNvisibleItemCount
List のワークエリアの表示スペースに合わせて表示される項目の数を指定します。 リストは、その高さを決定するためにこの値を使用します。

XmNhorizontalScrollBar
水平方向の ScrollBar の widget  ID を指定します。 この widget は、簡易関数 XmCreateScrolledList によって自動的に生成されます。

XmNlistSizePolicy
現在の List のワークエリアの大きさを越えて、項目が水平方向に大きくなった場合の List の動作を制御します。 この値が XmCONSTANT ならば、List が表示されているエリアの大きさは変わらず、水平方向の ScrollBar が付け加えられます。 このリソースが XmVARIABLE に設定されていれば、List は最も長い項目の大きさに合わせて大きくなり、水平方向の ScrollBar は付け加えられません。

このリソースの値が XmRESIZE_IF_POSSIBLE であれば、List は最も幅の広い項目の幅に合わせて拡大あるいは縮小しようとします。 List が最も広い幅に合わせるように大きさを変えられない場合は、最も長い項目が List の項目を表示しているエリアより広ければ水平方向の ScrollBar が付け加えられます。

大きさを変える方法は List widget が生成された時点で設定されます。 この値は、XtSetValues で後から変えることはできません。

XmNscrollBarDisplayPolicy
ScrollBar を表示する方法を指定します。 このリソースが XmAS_NEEDED に設定されている場合、垂直方向の ScrollBar は、リスト中の項目の数が、表示できる項目の数を越えた時にのみ表示されます。 XmNlistSizePolicy が XmCONSTANT あるいは XmRESIZE_IF_POSSIBLE であれば、水平方向の ScrollBar は、現在のリストの幅より広い項目がある時のみ表示されます。 このリソースが XmSTATIC に設定されている場合、垂直方向の ScrollBar は、常に表示されます。 水平方向の ScrollBar は、XmNlistSizePolicy が XmCONSTANT あるいは XmRESIZE_IF_POSSIBLE に設定されている時は、常に表示されます。

XmNscrollBarPlacement
表示されている項目に対する ScrollBar の位置を指定します。 次の値を取ります。

•XmTOP_LEFT — 水平方向の ScrollBar は、表示されている項目の上に表示され、垂直方向の ScrollBar は、表示されている項目の左に表示されます。

•XmBOTTOM_LEFT — 水平方向の ScrollBar は、表示されている項目の下に表示され、垂直方向の ScrollBar は、表示されている項目の左に表示されます。

•XmTOP_RIGHT — 水平方向の ScrollBar は、表示されている項目の上に表示され、垂直方向の ScrollBar は、表示されている項目の右に表示されます。

•XmBOTTOM_RIGHT — 水平方向の ScrollBar は、表示されている項目の下に表示され、垂直方向の ScrollBar は、表示されている項目の右に表示されます。

XmNscrolledWindowMarginHeight
ScrolledWindow の上端と下端におけるマージンの高さを指定します。

XmNscrolledWindowMarginWidth
ScrolledWindow の右端と左端におけるマージンの幅を指定します。

XmNspacing
表示されている項目から ScrollBar までの距離を指定します。

XmNverticalScrollBar
垂直方向の ScrollBar の widget ID を指定します。 この widget は、簡易関数 XmCreateScrolledList によって自動的に生成されます。

継承されるリソース

List は、次のスーパークラスからの動作とリソースを継承します。 これらのリソースについての完全な解説は、そのスーパークラスのマニュアルページを参照してください。

コールバック情報

List は、新しいコールバック構造体を定義します。 アプリケーションは、まず、reason フィールドを参照し、そのリーズンに対して有効な構造体のメンバのみを使用しなければなりません。 これは、すべてのフィールドが、可能なすべてのリーズンに対して関連があるわけではないためです。 コールバック構造体は、以下のように定義されます。

typedef struct
{
intreason ;
XEvent∗ event ;
XmStringitem ;
intitem_length ;
intitem_position ;
XmString∗ selected_items ;
intselected_items_count ;
intselection_type ;
} XmListCallbackStruct ;

reasonコールバックが呼び出されたリーズンを示します。

eventコールバックを呼び出した XEvent を示します。 NULL になることもあります。

itemList の動作によって選択された項目です。 selected_items は、コールバックが終了した後で再使用される一時的な記憶空間を示します。 そのため、アプリケーションが選択されたリストをセーブしておく必要がある場合、アプリケーションはそれ自身のデータ空間にリストをコピーしなければなりません。

item_length選択動作が生じた時の項目の長さです。

item_position選択された項目の List における位置です。

selected_itemsコールバックを生じる event が生じた時に選択された項目のリストを示します。 selected_items は、コールバックが終了した後で再使用される一時的な記憶空間を示します。 そのため、アプリケーションが選択されたリストをセーブしておく必要がある場合、アプリケーションはそれ自身のデータ空間にリストをコピーしなければなりません。

selected_items_count
selected_items リスト中の項目の数です。

selection_typeいちばん最近の拡張された選択が、最初の選択 (XmINITIAL)、存在している選択の変更 (XmMODIFICATION)、あるいは隣接していない項目の追加の選択 (XmADDITION) のいずれかであることを示します。

次の表は、各々のコールバック構造体のフィールドが有効なリーズンを示します。

動作

List は、その項目の設定のためにいろいろなメソッドを用意しています。 一般的な選択モデルは次のとおりです。

ユーザは、マウスを使って希望する項目の上にマウスポインタを移動したり、あるいは上矢印や下矢印キーを使って希望する項目にアクティブなハイライトを移動するキーボードトラバースモードによって、選択したい項目にマウスポインタを移動します。 項目は、マウス上の選択ボタン (通常、マウスの左ボタン) をクリックしたり、キーボード上の選択キー (通常、スペースキーに定義されている) を押したりして選択されます。 各選択モードは、上述の動作のいくつかのバリエーションを用意しています。

キーボードによる選択のインターフェースは、トラバースが List widget に対してイネーブルである場合のみ動作するということに注意してください。

選択モードは、XmNselectionPolicy リソースによって設定され、XmNautomaticSelection リソースによって変更されます。 いろいろなモードの動作は、次のように定義されています。

XmSINGLE_SELECT (単一選択) :
希望する項目の上までマウスポインタあるいはキーボードハイライトを移動し、選択ボタンまたはキーを押してください。 項目は、フォアグラウンドとバックグラウンドの色を入れ替えて、選択された項目であることを示します。 以前に選択されていた項目は、選択されていない状態になります (通常表示されている状態に戻ります)。 ボタンあるいはキーが離されると、XmNsingleSelectionCallback が呼び出されます。

XmBROWSE_SELECT (ブラウズ選択) :
マウスを使用していれば、選択ボタンを押してください。 そうすると、マウスポインタの下の項目がハイライトになります。 ボタンを押したまま、マウスポインタを移動して選択した項目をドラッグしてください。 選択ボタンを離すと、マウスポインタの下の項目が選択された項目になり、XmNbrowseSelectionCallback が呼び出されます。

XmNautomaticSelection が True であれば、XmNbrowseSelectionCallback は選択ボタンが押された時に呼び出されます。 選択ボタンが押されている間に続いて入力された各項目に対して、コールバックは、マウスポインタが項目に移動した時に呼び出されます。 ボタンが離された時には、選択コールバックは呼び出されません。

キーボードによって選択され、XmNautomaticSelection が False の場合、ブラウズ選択は、単一選択モードと同じになります。 しかし、XmNautomaticSelection が True の場合、コールバックは、選択された各エレメントに対して呼び出されます。 キーボードハイライトと選択ハイライトはいずれも、ユーザがリスト中を移動するように移動します。

XmMULTIPLE_SELECT (複数選択) :
希望する項目の上まで、マウスポインタあるいはキーボードハイライトを移動して、選択ボタンあるいはキーを押してください。 項目は、フォアグラウンドとバックグラウンドの色を入れ替えて、選択された項目であることを示します。 以前に選択されていた項目は、この動作によって影響を受けません。 ボタンあるいはキーを離すと、XmNmultiSelectionCallback が呼び出されます。 このモードにおいて項目を選択されていない状態にするには、選択された項目に移動し、選択ボタンあるいはキーを押してください。 XmNmultipleSelectionCallback は、更新された選択リストを渡します。

XmEXTENDED_SELECT (拡張された選択) :
このモードは、1 回の動作で隣接する範囲の項目を選択します。 範囲の最初の項目上で選択ボタンを押してください。 これは、リスト中のそれ以前の選択をすべて選択されていない状態にして、新しい選択のプロセスを始めます。 その項目は反転表示になり、選択の中に含まれていることを示します。 ボタンを押したままで、List 中の他の項目上にカーソルをドラッグしてください。 リスト上をマウスポインタが移動すると、最初の項目と現在マウスポインタの下にある項目の間のすべての項目が反転表示され、選択に含まれていることを示します。 ボタンを離すと、XmNextendedSelectionCallback が呼び出され、選択されたすべての項目のリストを渡します。 selection_type フィールドは、XmINITIAL に設定されます。

シフトキーを押したまま、新しい終点に移動し、選択ボタンを押すことによって、選択を変更してください。 最初の始点と新しい終点の間の項目が選択されます。 選択プロセスの残りの部分は、上述のように行われます。 それ以前の選択はいずれも、選択されていない状態にはなりません。 選択ボタンが離されると、XmNextendedSelectionCallback が呼び出され、新しいものとそれ以前のもの両方の選択されたすべての項目のリストを渡します。 selection_type フィールドは、XmMODIFICATION になります。

項目は、コントロールキーを使用することによって、選択された範囲に追加したり、あるいは選択された範囲から削除することができます。 すでに選択された項目にある範囲の項目を追加するためには、新しいグループの最初の項目に移動し、コントロールキーを押したまま、選択キーを押してください。 マウスポインタの下の項目が反転表示されます。 それ以前の選択は、何も影響を受けません。 この項目は、新しい選択範囲の最初の項目になります。 マウスポインタが、コントロールキーが押されたまま追加する項目上をドラッグされると、それらの項目は、上述のように反転表示されます。 選択ボタンが離されると、XmNextendedSelectionCallback が呼び出され、新しいものとそれ以前のもの両方の選択されたすべての項目のリストを渡します。 selection_type は、XmADDITION に設定されます。

すでに選択された項目から項目あるいは項目の範囲を削除するには、選択されていない状態にしたい最初の項目に移動して、コントロールキーを押したまま、選択ボタンを押してください。 マウスポインタの下の項目は、通常の表示状態に戻り、それがもはや選択されていないことを示します。 この項目は、選択されていない状態にされる範囲に対する最初の項目になります。 マウスポインタが、コントロールキーと選択キーを押したまま、さらに選択された項目上をドラッグすると、それらの項目は、選択されていない状態になります。 他の選択された項目は、いずれも影響を受けません。 選択キーが離された時、XmNextendedSelectionCallback が呼び出され、新しいものとそれ以前のもの両方の残っている選択された項目のリストを渡します。 selection_type は、XmADDITION に設定されます。

項目の範囲は、上述のように範囲に対する最初の項目を設定し、範囲の最後に移動し、シフトキーを押したまま選択キーを押すことによっても選択されていない状態にすることができます。 2 つの終点の間のすべての項目が選択されていない状態にされます。 ボタンが離されると、XmNextendedSelectionCallback が上述のように呼び出されます。

XmNautomaticSelection リソースが True に設定されていれば、選択ボタンが押された時に XmNextendedSelectionCallback が呼び出されます。 ユーザが選択あるいは選択されていない状態にしたその後に続く各項目に対しては、コールバックはマウスポインタが項目上に移動した時に呼び出されます。 selection_type フィールドは、現在の動作を反映して設定されます。 ボタンが離された時には、選択コールバックは呼び出されません。

拡張された選択モードにおけるキーボードによる選択は、希望する範囲の最初にキーボードハイライトを移動し、選択キーを押すことによって行われます。 選択コールバックは、selection_type の値 XmINITIAL によって呼び出されます。 そして、矢印キーを使用して、キーボードハイライトを範囲の最後に移動し、シフトキーを押したまま、選択キーを押してください。 XmNextendedSelectionCallback は、値 XmMDODIFICATON によって呼び出されます。 範囲の最初に移動して、コントロールキーを押したまま選択キーを押し、次に範囲の最後に移動し、シフトキーを押したまま選択キーを押すことによって、追加する範囲を選択してください。 それ以前に選択されたエレメントは、それらのエレメントに移動し、コントロールキーを押したまま選択キーを押すことによって削除してください。 いずれの場合においても、コールバックは上述のように呼び出されます。

XmNautomaticSelection リソースが True に設定されている状態でキーボードを使用する場合、XmNextendedSelectionCallback は、選択ボタンが押された時に呼び出されます。 ユーザが選択したその後に続く各項目に対しては、コールバックは、修飾子キーが使用されていれば、マウスポインタが項目上に移動した時に呼び出されます。 たとえば、選択キーを押して選択を始め、シフトキーを押したまま矢印キーを使って選択範囲を拡張してください。 selection_type フィールドは、現在の動作を反映して設定されます。 ボタンが離された時には、選択コールバックは呼び出されません。

XmDEFAULT-ACTION (ダブルクリック)
ある項目が XmNdoubleClickInterval によって定義される間隔内に 2 度クリックされると、List はそれをダブルクリックと判断し、XmNdefaultActionCallback が呼び出されます。 項目は、選択されていることを示すために反転表示されます。

デフォルトのトランスレーション

次に XmList におけるデフォルトのトランスレーションを示します。

Button1<Motion>:ListButtonMotion()
Shift Ctrl ~Meta<Btn1Down>: ListShiftCtrlSelect()
Shift Ctrl ~Meta<Btn1Up>:ListShiftCtrlUnSelect()
Shift Ctrl ~Meta<KeyDown>space: ListKbdShiftCtrlSelect()
Shift Ctrl ~Meta<KeyUp>space: ListKbdShiftCtrlUnSelect()
Shift Ctrl ~Meta<KeyDown>Select: ListKbdShiftCtrlSelect()
Shift Ctrl ~Meta<KeyUp>Select: ListKbdShiftCtrlUnSelect()
Shift ~Ctrl ~Meta<Btn1Down>: ListShiftSelect()
Shift ~Ctrl ~Meta<Btn1Up>: ListShiftUnSelect()
Shift ~Ctrl ~Meta<KeyDown>space: ListKbdShiftSelect()
Shift ~Ctrl ~Meta<KeyUp>space: ListKbdShiftUnSelect()
Shift ~Ctrl ~Meta<KeyDown>Select ListKbdShiftSelect()
Shift ~Ctrl ~Meta<KeyUp>Select ListKbdShiftUnSelect()
Ctrl ~Shift ~Meta<Btn1Down>: ListCtrlSelect()
Ctrl ~Shift ~Meta<Btn1Up>: ListCtrlUnSelect()
Ctrl ~Shift ~Meta<KeyDown>space: ListKbdCtrlSelect()
Ctrl ~Shift ~Meta<KeyUp>space: ListKbdCtrlUnselect()
Ctrl ~Shift ~Meta<KeyDown>Select: ListKbdCtrlSelect()
Ctrl ~Shift ~Meta<KeyUp>Select: ListKbdCtrlUnselect()
~Shift ~Ctrl ~Meta<Btn1Down>: ListElementSelect()
~Shift ~Ctrl ~Meta<Btn1Up>: ListElementUnSelect()
~Shift ~Ctrl ~Meta<KeyDown>space: ListKbdSelect()
~Shift ~Ctrl ~Meta<KeyUp>space: ListKbdUnSelect()
~Shift ~Ctrl ~Meta<KeyDown>Select ListKbdSelect()
~Shift ~Ctrl ~Meta<KeyUp>Select ListKbdUnSelect()
Shift Ctrl ~Meta<Key>Up:ListShiftCtrlPrevElement()
Shift Ctrl ~Meta<Key>Down: ListShiftCtrlNextElement()
Shift ~Ctrl ~Meta<Key>Up:ListShiftPrevElement()
Shift ~Ctrl ~Meta<Key>Down: ListShiftNextElement()
~Shift Ctrl ~Meta<Key>Up:ListCtrlPrevElement()
~Shift Ctrl ~Meta<Key>Down: ListCtrlNextElement()
~Shift ~Ctrl ~Meta<Key>Up: ListPrevElement()
~Shift ~Ctrl ~Meta<Key>Down: ListNextElement()
<Enter>:ListEnter()
<Leave>:ListLeave()
<FocusIn>:ListFocusIn()
<FocusOut>:ListFocusOut()
<Unmap>:PrimitiveUnmap()
Shift<Key>Tab:PrimitivePrevTabGroup()
<Key>Tab:PrimitiveNextTabGroup()
<Key>Home:PrimitiveTraverseHome()

キーボードトラバース

XmPrimitive(3XM) から継承されない動作に関するキーボードトラバースについては、このマニュアルページの「動作」のセクションに記述されています。

関連事項

Core(3XM), XmCreateList(3XM), XmCreateScrolledList(3XM), XmFontListCreate(3XM), XmListAddItem(3XM), XmListAddItemUnselected(3XM), XmListDeleteItem(3XM), XmListDeletePos(3XM), XmListDeselectItem(3XM), XmListDeselectAllItems(3XM), XmListSelectItem(3XM), XmListSetHorizPos(3XM), XmListSetItem(3XM), XmListSetPos(3XM), XmListSetBottomItem(3XM), XmListSetBottomPos(3XM), XmListSelectPos(3XM), XmListDeselectPos(3XM), XmListItemExists(3XM), XmPrimitive(3XM), XmStringCreate(3XM)

NEWS-OSRelease 4.1C