このルーチンは XSolarisOvlSelectPartner と似ていますが、特定のビジュアルのパートナビジュアルを見つけるのではなく、特定のスクリーン上のすべてのビジュアルペアから、指定された条件にもっとも合致するオーバーレイとアンダーレイのペアを同時に選択します。オーバーレイに関係のない X エラーは別として、選択されたビジュアルを使用すれば、ウィンドウを安全に作成することができます。
このルーチンは、pCriteria で指定された条件に基づいて、特定のスクリーンの最適なビジュアルペアを探索し、それからすべてのビジュアルペア (最適なペアとそれ以外のペア) を探索します。オーバーレイとアンダーレイに関する条件は、pCriteria の各要素で指定されます。このルーチンは、指定された条件に合致するペアが見つかったかどうかに応じて成功または失敗を表す状態を戻します。
選択されたペアのオーバーレイビジュアルは、オーバーレイに関するすべてのハード条件を満たします。また、このペアのアンダーレイビジュアルは、アンダーレイに関するすべてのハード条件を満たします。オーバーレイビジュアルの属性は ovVisinfoReturn に戻され、アンダーレイビジュアルの属性は unVisinfoReturn に戻されます。すべてのハード条件 (オーバーレイとアンダーレイ) および同じ数のソフト条件 (オーバーレイまたはアンダーレイ) を満たすビジュアルペアが複数見つかった場合は、そのうち 1 つのペアが選択されて戻されます。どのペアが選択されるかは、実装状態によって異なります。
構文と引数を次に示します。
XSolarisOvlSelectStatus XSolarisOvlSelectPair (Display *display, int screen, int numCriteria, XSolarisOvlPairCriteria *pCriteria, XVisualInfo *ovVisinfoReturn, XVisualInfo *unVisinfoReturn, unsigned long *unmetOvCriteriaReturn, unsigned long *unmetUnCriteriaReturn)
display |
X サーバーへの接続を指定する。 |
screen |
ビジュアルの探索場所となるスクリーンを指定する整数。 |
numCriteria |
pCriteria 配列の中にある XSolarisOvlPairCriteria 構造体の数。 |
pCriteria |
ビジュアルのペアを選択するための条件を優先順位の高い順から低い順に指定した XSolarisOvlPairCriteria 構造体の配列。 |
ovVisinfoReturn |
呼び出し側が提供する XVisualInfo 構造体へのポインタ。正常終了の場合は、選択されたオーバーレイビジュアルの属性がこの構造体に書き込まれる。 |
unVisinfoReturn |
呼び出し側が提供する XVisualInfo 構造体へのポインタ。正常終了の場合は、選択されたアンダーレイビジュアルの属性がこの構造体に書き込まれる。 |
unmetOvCriteriaReturn |
オーバーレイビジュアルに関して満足されなかった条件を記述するビットマスクへのポインタ。この出力引数が意味を持つのは、ルーチンが XSolarisOvlQualifiedSuccess または XSolarisOvlCriteriaFailure という値を戻すときに限られる。 |
unmetUnCriteriaReturn |
アンダーレイビジュアルに関して満足されなかった条件を記述するビットマスクへのポインタ。この出力引数が意味を持つのは、ルーチンが XSolarisOvlQualifiedSuccess または XSolarisOvlCriteriaFailure という値を戻すときに限られる。 |
XSolarisOvlPairCriteria はビジュアルの選択時に使用される各種条件と、それらの条件の重要度を定義する構造体です。この構造体は次のように定義されます。
typedef struct { XSolarisOvlVisualCriteria overlayCriteria; XSolarisOvlVisualCriteria underlayCriteria; } XSolarisOvlPairCriteria;
XSolarisOvlVisualCriteria は、XSolarisOvlSelectPartner の仕様で定義されています。
XSolarisOvlSelectStatus はこの型の定義については、XSolarisOvlSelectPartner の仕様を参照してください。
XSolarisOvlPairCriteria 構造体の 1 つで指定されたすべてのハード条件とソフト条件を満たすビジュアルペアが正常に見つかった場合は、XSolarisOvlSuccess が戻されます。
選択されたビジュアルが XSolarisOvlPairCriteria 構造体の 1 つで指定されたすべてのハード条件を満たすが、ソフト条件は満たさない場合は、XSolarisOvlQualifiedSuccess が戻されます。この場合は、オーバーレイとアンダーレイに関して満たされなかったソフト条件の論理和が、それぞれ unmetOvCriteriaReturn と unmetUnCriteriaReturn に書き込まれます。
XSolarisOvlCriteriaFailure は、XSolarisOvlPairCriteria 構造体で指定されたハード条件を満たすビジュアルペアが見つからなかったことを示します。この場合は、オーバーレイとアンダーレイに関し、XSolarisOvlPairCriteria 構造体の満たされなかったハード条件のうち、もっとも緩いハード条件の 論理和が、それぞれ unmetOvCriteriaReturn と unmetUnCriteriaReturn に書き込まれます。
条件の不一致以外のエラーが発生した場合は、XSolarisOvlFailure が戻されます。
XSolarisOvlSelectPartner と同様に、XSolarisOvlSelectPair では、優先順位の高い順に条件集合を指定することができます。すなわち、単一の呼び出しで複数の条件集合が指定できます。まず、オーバーレイとアンダーレイに関する最初の条件集合に合致するビジュアルペアの探索がルーチンにより行われ、最初の条件集合のすべてのハード条件を満たすペアが見つかると、そのペアが選択されます。そのようなペアが見つからない場合は、2 番目の条件集合を使用して探索が続けられます。このような手続きは、特定の条件集合のすべてのハード条件を満たすペアが見つかるか、すべての条件集合がテストされるまで続けられます。すなわち、この優先順位の仕組みでは、もっとも望ましいペアを最初の条件集合として指定し、それより優先度の低いペアについては 2 番目以降の条件集合として指定すればよいわけです。この仕組みにより、単一のサブルーチン呼び出しで、ペアに関するユーザーの要求を優先順位の高い順に探索することができます。
指定できる条件マスクの詳細については、「オーバーレイ/アンダーレイウィンドウのビジュアルの選択」を参照してください。