あなたのオブジェクトを記述する t_atoms の 配列 (座標、その他)

box_new

box_new は t_box のためのメモリ割り当ては行いません。代わりに、あなたのオブジェクトの中にすでに存在する t_box を初期化します。引数 flags は次のような定数の組み合わせになります。

最も普通に使用されるフラグは、F_DRAWFIRSTIN、および F_GROWY か F_GROWBOTH です。次のものは、今までの例の続きです。t_myuserobject が box_new を呼び出しています。

box_new((t_box *)x, p, F_DRAWFIRSTIN | F_SAVVY, left, top, right, bottom);

Box の初期化を行った後、オブジェクトの他のフィールドの初期化を考えるでしょう。割り込みレベルを考慮した場合、初期化は行っておかなければなりません。ユーザからオブジェクトに送られるメッセージ（int や bang など）に応答して、オブジェクトの状態の変化を再描画するためにQelem を使う場合が、この「割り込みレベルの考慮」にあたります。オブジェクトはメッセージを受け取ってから直ちに描画を行うことはできないため、多くの場合、オブジェクトの論理的な値と直前に描画された値の両方の情報を把握していることが助けになります。このようにして、オブジェクトが新しい値を反映して更新される必要がある場合を識別します。

ユーザインターフェイスオブジェクトの生成ルーチンでの次のステップは、アウトレットの作成、あるいは、必要ならばインレットを追加することです。次に、Box の b_firstin フィールドにオブジェクト自身へのポインタを割り当てなければなりません。次の例では、Qelem をセットし、必要な割り当てを実行しています。後ほど、関数 myobject_redraw については簡単に説明します。

x->my_qelem = qelem_new(x, (method)myobject_redraw); x->my_box.b_firstin = (void *)x;

　これで、パッチャーウィンドウは新しく初期化されたオブジェクトの描き方を知っていることになるため、次に box_ready を呼び出したいと思います。

box_ready

box_ready は、あなたの新しい Box のインレットとアウトレットを描画する場所を計算します。そして、新しいオブジェクトが（ファイルから読み込まれるというよりは）ユーザによって作られると、box_ready はパッチャーウィンドウ上でそれを目に見える形で選択された状態にします。これは、ユーザが最初に Max メニューから、Get info... を選択して、付加的なパラメータ（例えばスライダー型のオブジェクトのレンジのようなもの）の設定を行いたい場合に便利です。

box_ready を呼び出した後、ユーザインターフェイスオブジェクトの生成ルーチンは、新しく作られたインスタンスへのポインタを返さなければなりません。

box_ready((t_box *)x); return x;

ユーザインターフェイスオブジェクトの生成ルーチンの基本的なステップについて説明してきました。ここでもう一度、オブジェクトのデフォルトのインスタンスが作られたときにパッチャーによって呼び出される最初の生成ルーチンに戻ってみましょう。このルーチンは、デフォルトの値を持つ適切な配列 argv をセットし、私たちが書いた通りの生成関数を呼び出すので、私たちはこのルーチンを実装することができます。これは、私たちのコードで重複が起きるのを防ぎます。

void *myuserobject_menu (t_patcher *p, long left,long top, long font) { t_atom argv[20]; // myuserobject_new が必要とする argv のセットアップ // 最初に、パッチャーに関する値 argv[0].a_type = A_OBJ; argv[0].a_w.w_obj = (t_object *)p; // 座標に関する値（フォント情報は使用されません） argv[1].a_type = argv[2].a_type = argv[3].a_type = argv[4].a_type = A_LONG; argv[1].a_w.w_long = left; argv[2].a_w.w_long = top; argv[3].a_w.w_long = right; argv[4].a_w.w_long = bottom; return myuserobject_new(0, 5, argv); }

box_free

この関数は、パッチコードのような、box に結びつけられているデータ構造体を解放します。box が可視である場合、パッチャーウィンドウ上の box があった領域を再描画します。

click

バインディング

宣言

マウスがクリックされた場所 (ローカル座標で表されます）

パッチャーウィンドウがあなたの Box の長方形領域内でクリックを検知した時にこのメッセージが送られます。適切な方法でマウスを追跡し、これに応答しなければなりません。pt はローカル座標で表されるマウス位置、modifires は標準の Macintosh イベントレコードの modifiers フィールドです。マウスボタンが上げられるのを待つループを実装するよりは、マウスのトラッキングを行うために wind_drag を使って下さい。描画やマウストラッキングの前にカレントグラフポートをセットするためには、patcher_setport を使います。

重要：click メソッドの中でアウトレットからメッセージを送る場合、送信の前に lockout フラグをセットし、終了後に復元しておかなければなりません。これは、アウトレットから０を送信する click ルーチンのサンプルです。

void myObject_click (t_myuserobject *x, Point pt, short modifiers) { short savelock; savelock = lockout_set(1); outlet_int (x->m_ob.o_outlet,0); lockout_set (savelock); }

update

バインディング

宣言

update メソッドは、 box の中でユーザインターフェイスオブジェクトを描画します。加えて、ユーザがオブジェクトの box 長方形領域を拡大、縮小できる場合、update メソッドで、オブジェクトのサイズ変更が行われたかどうかをチェックしなければなりません。例えば、スライダーオブジェクトならば、新しい幅に基づいた「スライダーハンドル」のビットマップを再構築したいと考えるでしょう。このような比較を行うために、オブジェクト内に「古い」Boxのサイズに関する状況を保存する必要があります。また、box_size 関数を使って、大き過ぎたり、小さ過ぎたりしないようにサイズ変更を行うことが可能です。

ハイライトが可能なユーザインターフェイスオブジェクトを作りたい場合には、update メソッドで t_box の b_hilited フィールドを見に行く必要があります。このフィールドが０以外ならばオブジェクトをハイライト状態で、そうでなければ、ハイライトしていない状態で描画しなければなりません。加えて、後述するような key メッセージに応答するメソッドを実装しなければなりません。これによって、ユーザはオブジェクト内でタイプ入力できるようになります。ナンバーボックスはハイライト可能なユーザインターフェイスオブジェクトの例です。

update メソッド以外のルーチンで描画を行う計画がある場合には、patcher_setport および box_nodraw というルーチンについての情報を参照して下さい。これについては後述します。また、ユーザインターフェイスオブジェクトでインデックスカラーをサポートしようとする場合には、「ユーザインターフェイスオブジェクトと色」というセクションを参照して、color および wcolor というメッセージに関する情報を得る必要があるでしょう。。

psave

バインディング

宣言

ユーザインターフェイスオブジェクトを書く場合に行わなければならないことの中で、psave メソッドを書くことはもっとも不可解なことでしょう。Max ファイルが開かれる際にオブジェクトを再現することができるようにするメッセージを作成するためには、binbuf_vinsert（Chapter 7 で説明しています）または、binbuf_insert を使います。最初に、あなたのオブジェクトの t_box の b_hidden フィールドがチェックされて、隠された状態に設定されているかどうかを判定する必要があります。ユーザは、Max メニューの Hide on Lock を選択することで、box やパッチコードを隠すことができます。

その後、あなたのオブジェクトの内部データを下のサンプルのような方法で保存します。このサンプルから変更しなければならない点は、binbuf_vinsert に渡すフォーマット文字列に加え、追加したアーギュメントを保存することくらいです。また、あなたのオブジェクトのクラス名は知っておかなければなりません。下のサンプルの中で、私たちのオブジェクトは myuserobject という名前を持っています。ユーザインターフェイスオブジェクトを次のような構造体と共に保存し、オブジェクトの座標と共に my_range と my_value を保存することを仮定しています。

typedef struct myuserobject { t_box my_box; long my_range; long my_value; } t_myuserobject;

これは、適切な psave メソッドです。

void myObject_psave(myObject *x, void *w) { short hidden; Rect *r; hidden = myObj.my_box.b_hidden; r = &myObj.my_box.b_rect; if (hidden) { binbuf_vinsert(w,"sssslllll", gensym("#P"),gensym("hidden"), gensym("user"),gensym("myobject"), (long)(r->left), (long)(r->top), (long)(r->right - r->left), (long)(r->bottom - r->top), (long)(x->my_range)); } else { binbuf_vinsert(w,"ssslllll", gensym("#P"),gensym("user"), gensym("myobject"), (long)(r->left),(long)(r->top), (long)(r->right - r->left), (long)(r->bottom - r->top), (long)(x->my_range)); } }

まず最初に、前に定義した myuserobject_new 関数が使うことのできる形（最初に左、上、...という順です）で、座標を保存します。

いくつか説明しておく点があります。hidden は Max に b_hidden アトリビュートがセットされた Box を作るように命じるための特別なキーワードです。これは、Max ファイルが開かれた際、自動的に行われます。user はエクスターナルとして書かれたユーザインターフェイスオブジェクトが必要とする特別なキーワードです。user を含めるのを忘れてしまうと、オブジェクトは、次のようなエラーを引き起こすでしょう。

patcher: doesn’t understand ‘myobject’

これは、ファイルからロードされる際に起こります。

binbuf_vinsert への残りの引数は、オブジェクトボックスの座標、および保存したい他の情報です。

上のような psave メソッドを実行した結果を文字として見た場合、次のようになるでしょう。

#P user myobject 200 200 18 18 128;

bfont

バインディング

宣言

ユーザがインターフェイスオブジェクトを選択し、Font メニューから new font または font size を選んだ際に、オブジェクトの Box のサイズやアピアランスを変更したい場合、bfont メソッドを実装しなければなりません。このメソッドは、ユーザのこのような操作が実行された後に呼び出されます。IncDec や umenu は このメソッドが実装された Max ユーザインターフェイスオブジェクトの例です。

key

バインディング

宣言

box_new の 引数 flags で F_HILITE ビットをセットされたインターフェイスオブジェクトは、ユーザがオブジェクトをハイライト表示させ、Macintosh キーボードのキーを押した際に key メッセージを受け取ります。オブジェクトは、keyvalue によって渡されるキーのASCII値に応答して、それに適したようにオブジェクトの状態を変更し、オブジェクト自身を再描画しなければなりません。

enter

バインディング

宣言

このメッセージは、ユーザが [Return] または [Enter] キーを押し、他のボックスをハイライト表示させるか、パッチャーウィンドウ内の box の外でクリックした時に送られます。このメッセージへの応答では、表示が「ペンディング」を表す状態のもの（Number Box で見られる３つのドットのようなもの）を取り除き、タイプされた値を受け入れなければなりません。

clipregion

バインディング

宣言

このメッセージによって、あなたのオブジェクトが描画領域として、通常の長方形領域のサブセットである非長方形領域を定義することができます。例えば、umenu オブジェクトは角丸長方形によって現在選択されているアイテムを表示します。引数 result には次の４つの値のうちの１つを設定します。

• CLIPRGN_RGN は、 Mac OS のリージョン（サンプルを後述）に パラメータ rgn を設定し、オブジェクトはその定義された領域でのみ描画されることを示します。



• CLIPRGN_RECT は、長方形領域すべてがオブジェクトによって満たされることを意味します。この場合、パラメータ rgn は変更しません。



• CLIPRGN_EMPTY は、あなたのオブジェクトが何も描画しないことを意味します。dropfile や ubutton のような透過オブジェクトはこの設定を使っています。パラメータ rgn を変更してはいけません。



• CLIPRGN_COMPLEX は、あなたのオブジェクトのクリッピング領域が非常に複雑で、リージョンとして定義する意味をもたないことを意味します。その代わり、パッチャーは常にあなたのオブジェクトを他のオブジェクトの上に描画します。comment オブジェクトは、この設定を使って、テキストを透過的に他のオブジェクトの上に描画しています。パラメータ rgn を変更してはいけません。

次の例では、オブジェクトはclipregion メソッドの中で円形のクリッピング領域を定義しています。

void myobject_clipregion (t_myobject *x, RgnHandle *rgn,short *result) { *result = CLIPRGN_RGN; OpenRgn(); FrameOval(&x->my_box.b_rect); // box の長方形領域を使います。 CloseRgn(*rgn = NewRgn()); }

clipregion メソッドに関するより詳しい情報は、後述の 透過オブジェクトに関するセクションを参照して下さい。

また、現在 Macintosh 用 でない UI オブジェクトの領域を指定する方法はありません。したがって、 CLIRGN_RGN モードは目下のところ Windows XP ではサポートされていない点にも注意して下さい。

bidle

バインディング

宣言

bidle メッセージは、ロックされたパッチャーウィンドウでカーソルがあなたのオブジェクトの上にある場合に送られます。一般的にカーソルの追跡は、例えばMacintosh 上でマウス位置を探す場合ならば、Mac OS の関数 GetMouse を呼び出すでしょう。カーソルを違う形のものに設定したい場合には、値を返す前に wind_setcursor に引数 -1 を与えて呼び出して下さい。

bidleout

バインディング

宣言

bidleout メッセージは、ロックされたパッチャーウィンドウで、カーソルがあなたのオブジェクトの長方形領域から出たときに送られます。

box_ownerlocked

この関数は、box を持っているパッチャーウィンドウがロックされていれば０以外、ロックされていなければ０の値を返します。（通常、ロックされていないパッチャーでは、パッチャーウィンドウの最上部に UIオブジェクトツールバーが表示されています。

ユーザインターフェイスオブジェクトは、パッチャーウィンドウがロックされた場合、自分自身を違う形で描画したい場合もあるでしょう。box のアウトレットがパッチャーがロックされると１ピクセル下方に広げられることに気がつくかもしれません。これは、あなたのために自動的に行なわれています。

box_size

box_nodraw

box_nodraw は描画の際に、ユーザインターフェイスオブジェクトの update メソッドの外で使われなければなりません。この関数は、Box の存在するパッチャーがロックされていて、Box が非表示の場合（ユーザが Max メニューから Hide on Lock を選んだ場合）、０以外の値を返します。この関数はクリッピング領域をセットすることもできるので、あなたのオブジェクトを他のオブジェクトに対して正しく描画することができます。例えば、あなたのオブジェクトが部分的に bpactcher の端で隠されている場合、box_nodraw はクリッピング処理を行なってくれます。しかし、これらのサービスは、box_new に F_SAVVY フラグを渡した場合にしか提供されません。このフラグは、box_nodraw と box_enddraw を、update 以外の描画で使っていたことを示しています。

オブジェクトは型指定されたメッセージ（すなわち、A_CANT アーギュメント型指定子を持つメッセージ以外のメッセージ） を受け取ったときに描画してはいけません。例えば、slider は int メッセージに応答してセットされた queue 関数の中で値が変わった場合に描画されます。queue 関数の中では、描画の前に box_nodraw がチェックされます。box_nodraw はまずオブジェクトのパッチャーウィンドウが可視であると（patcher_setport で）判定した後にのみ、呼び出されなくてはなりません。box_nodraw は、ユーザインターフェイスオブジェクトの update メソッドの中でを呼び出されるとクラッシュを引き起こします。すべてのクリッピングは、box_new に F_SAVVY フラグを渡したかどうかにかかわらず update メソッドの中でセットアップされます。

box_enddraw

box_enddraw は、update メソッドの外で描画が行なわれた場合に使います。これは、描画が完了し、その前のbox_nodraw の呼び出しで False が返されたときに呼び出されます。描画ルーチンの例は次のようなものになるでしょう。

if (gp = patcher_setport(x->m_box.b_patcher)) { if (!box_nodraw((t_box *)x)) { // ここで描画を行ないます box_enddraw((t_box *)x); } patcher_restoreport(gp); }

box_nodraw と　box_enddraw から最大の便益を引き出すために、インスタンス生成ルーチンの中でbox_new を呼び出す場合にF_SAVVY フラグを追加して下さい。

box_new((t_box *)x, patcher, F_DRAWFIRSTIN | F_NODRAWBOX | F_GROWBOTH | F_SAVVY, l, t, r, b);

box_redraw

この関数は、影響の及ぶ範囲にある他の Box や パッチコードと同様に、Box 全体を消し、再描画します。あなたのオブジェクトは結果として update メッセージを受け取ります。

box_visible

この関数は、スクリーン上でBox が見える場合は０以外の値を、見えない場合は０を返します。

patcher_deselectbox

patcher_dirty

この関数は、パッチャーウィンドウの dirty ビットを設定します。これにより、ウィンドウが閉じられるときに、ユーザに対して変更を保存するかどうか尋ねます。これを行なう必要があるのは、あなたのオブジェクトが、データをパッチャーの中に保存していて（例えば、table オブジェクトはその要素をパッチャーの中に保存することができます）、そのデータが変更された場合だけです。

注：ユーザインタフェイスオブジェクト以外のオブジェクトの場合、Box を「所有するパッチャー」の識別は、オブジェクト生成関数（これが可能な唯一の時です）の中で、シンボル #P に結び付けられたオブジェクトを取得することによって可能になります。

void *mypatcher; mypatcher = ((t_symbol *)gensym("#P"))->s_thing;

patcher_selectbox

patcher_setport

この関数はカレントグラフポートをパッチャーウィンドウに設定します。patcher_setport はそれまでのポートを返しますが、パッチャーウィンドウがその時点で可視になっていない場合０を返します。可視でない場合は何も描画すべきではありません。patcher_setport が成功した場合、パッチャーウィンドウでの一連の描画が終わった後、その戻り値で SetPort を呼び出します。この関数は、wind_setport と同じではない点に注意して下さい。この関数の使い方は、Chapter 10 の中で示した、wind_setportの例と類似していますが、ユーザインタフェイスオブジェクトで patcher_setport の代わりに wind_setport を使わないで下さい。あなたが賢い考えだと思って、パッチャーの p_wind フィールドを wind_setport に渡したとしたら、結果的に火傷をすることになるでしょう。それは、bpatcher オブジェクトに含まれるパッチャーは、このフィールドに無効な情報を持っているからです。

注：Windows XP 上でも、クリッピングリージョンが正しく働くために、この関数を呼び出すことは重要です。しかし、返される GrafPtr は不透明な型を持っているため、これは patcher_restoreport の呼び出しによってポート復元するときにだけ使用されるべきです。

注（追加）：Windows XP 上で、QTML を使っている場合、XQT_patcher_setportおよび XQT_patcher_restoreport を使う必要があります。これ以上の詳細については、後述の　XQT API を参照して下さい。

patcher_restoreport

この関数は、カレントのグラフポートを、patcher_setport によって返されたポートにセットします。

patcher_okclose

patcher_okclose を呼び出した後、パッチャーウィンドウは、オブジェクトターゲットで受け取ったあらゆる okcloseメッセージを送り出します。あなたのオブジェクトがパッチャーウィンドウそれ自身を開いたケースでは、ウィンドウの保存、またはクローズを標準でない方法で処理したい場合もあるでしょう。okclock メソッドを実装し、パッチャーウィンドウを開いた後、オブジェクト自身を patcher_okclose に渡します。okclock メソッドの書き方の説明は、Chapter 10 を参照して下さい。

ispatcher

オブジェクトがパッチャーである場合はゼロ以外の値を、そうでない場合は０を返します。ウィンドウリストから、すべてのパッチャーウィンドウを見つけるために、これを使いたいと思うかも知れません。Macintosh上では、最初に、Macintosh ウィンドウに結び付けられた Max の t_wind オブジェクトへのポインタを得るために GetWRefCon を使います。Windows XP では、Windows ウィンドウに結び付けられた Max の t_wind へのポインタを得るために、wind_fromhwnd を使うことができます。その後、有効な t_wind が返された場合、その t_wind の w_assoc フィールド で ispatcher を呼び出します。

あるいは、あなたがパッチャーの box のリストを横断的に見る場合、（b_firstin フィールドで） box に結び付けられているオブジェクトが、サブパッチャーかどうかを知ることに興味を持つかもしれません。box それ自身を渡す代わりに、box の b_firstin フィールドがゼロ以外の値であるかどうかをチェックし、そうである場合に、ispatcher に box を渡します。ispatcher には実際の Max オブジェクトを渡す必要があります。

isnewex

オブジェクトがノーマルオブジェクトのテキストを持つオブジェクトボックスの場合、０以外の値が返されます。そして、t_box の b_firstin フィールドでオブジェクト自身へのポインタを知ることができます。isnewex には、実際の Max オブジェクトを渡すことを確認して下さい。

注：どのような場合でも、ext_mess.h で定義されている ob_name または ob_class というマクロを使って、オブジェクトの型を見つけることができます。その後、文字列（ob_name の場合）またはシンボル（ob_class の場合）を探しているものと比較します。ispatcher と isnewex は若干速く動作します。

newex_knows

この関数は、オブジェクトがノーマルオブジェクトのテキストを持つオブジェクトで、これがバインドされているオブジェクトが msg で与えられたメソッドをもつ場合、０以外の値を返します。

patcher_eachdo

関数 fun は非表示のサブパッチを含むメモリ上のパッチャーごとに呼び出されます。これは、次のように宣言されます。

あなたの関数は、他のパッチャーのために引き続き呼び出しを行ないたい場合は０を、止める場合は０以外の値を返さなければなりません。patcher_eachdo は特定のオブジェクトのための探索ルーチンとして使うこともできるでしょう。これは、ビルトインオブジェクトである send や receiveで dblclick メッセージへの応答として使われています。これらのオブジェクトは同じ t_symbol にバインドされている他の send や receive オブジェクトがないかどうか全てのパッチャーを探索します。そして、該当のオブジェクトのウィンドウを前面に移動させます。

assist_drawstring

パッチャーウィンドウのアシスタンスエリアには、ユーザがオブジェクトをクリックしている間、役に立つメッセージを表示するために使われます。bpatcher オブジェクトの内側に見えるものをスクロールしているとき、その時点での水平、および垂直方向のオフセット値が表示されるのは、その一例です。

color

color メッセージにはいくつかの使い方があります。第１に、オブジェクトが選択された時 color メニューが有効ならば、このメッセージに応答しなければなりません。第２に、ユーザが color を 0 に設定する（これは、たいてい黒またはグレーになります）と、オブジェクトに color メッセージが送られます。このメッセージは、ユーザがオブジェクトの色を変更するために、直接送信することも可能です。このメッセージを受け取った場合には、オブジェクトの再描画をキューに入れるだけでなく、引数として受けとった値を box の b_color フィールドの値に設定します。Max ユーザは　color メッセージに対してどのような引数でも送ることができるため、この値を 0 〜 15（標準の色セットのインデックス値）に制限する必要があります。

バインディング

宣言

このメッセージに応答して、オブジェクトの b_color フィールド に指定された色の値をセットしなければなりません。その後、オブジェクトの再描画を行ないます。これは、defer 関数を使ってオブジェクトの再描画を行なう方法の例です。

void myuserobject_color (t_myuserobject *x, long color) { x->m_box.b_color = color; // box の色フィールドを設定 defer(x,(method)myuserobject_docolor,0,0,0); // 再描画の実行 } void myuserobject_docolor (t_myuserobject *x) { GrafPtr gp; if (gp = patcher_setport(x->m_box.b_patcher)) { if (!box_nodraw((t_box *)x)) { myuserobject_update(x); box_enddraw((t_box *)x); } SetPort(gp); } }

update メッセージでは、box の b_color フィールドの色の値を、標準の色セットを参照するためのインデックスに変換する必要があります。これは、box_color 関数によって行なうことができます。

frgb, brgb, rgb1 etc.

バインディング

宣言

これらのメッセージはオブジェクトの構成要素の色を変更します。そして、低い優先度でオブジェクトの再描画を行います。これはその例です。ここでは、オブジェクトに m_fg というフィールドがあり、このフィールドが持つ RGB カラーの値によって、オブジェクトが使用する前景色が決められるという前提になっています。下記の frgb メソッドでは、Max の色表現（各要素あたり８ビット）と Mac OS の色表現（各要素あたり１６ビット）の間での変換を行い、その後、オブジェクトの再描画を待機状態にさせています。

void myuserobject_frgb (t_myuserobject *x, long r, long g, long b) { x->m_fg.red = CLIP(r*257, 0, 65535); x->m_fg.green = CLIP(g*257, 0, 65535); x->m_fg.blue = CLIP(b*257, 0, 65535); defer(x,(method)myuserobject_doredraw,0,0,0); }

これは、myuserobject_doredraw 関数です。これまでの、他のサンプルでもおなじみのものです。

void myuserobject_doredraw(t_myuserobject *x) { GrafPtr gp; if (gp = patcher_setport(x->m_box.b_patcher)) { if (!box_nodraw((t_box *)x)) { myuserobject_update(x); box_enddraw((t_box *)x); } SetPort(gp); } }

box_color

バインディング

box_color は box の b_color フィールドにカラーインデックス（0-15）が格納されていることを前提にしています。この関数はパッチャーウィンドウがカラーで表示されているかどうかをチェックし、そうであれば b_color フィールドに対応した RGB 値を調べて、その値を前景色にセットします。box_color を呼び出した後、オブジェクトの色をつけたい部分の描画ができるようになります。その際、RGBForeColor を呼び出すことによって、前景色を黒に復元することができます。

Windows XP では、適切なネイティブ Win32 API 呼び出し、または適切な QTML QuickTime 呼び出しと共に、 box_getcolor を使わなければならない点に注意して下さい。Windows XP で box_color を呼び出すと、予想外の結果を引き起こします。これは、前景色を黒にリセットするための RGBForeColor の呼び出しが存在しないためです。

box_usecolor

box_usecolor は、あなたのオブジェクトボックスがカラーで描画されるようになっている場合には０以外の値を、そうでない場合は０を返します。この決定を行う際、異なる色深度をもつマルチモニタについての考慮がなされます。あなたのオブジェクトが update メッセージを受け取るたびに、この関数を呼び出すことは良い方法であると言えます。

box_getcolor

box_getcolor は、引数 index で与えられたカラーインデックス（0-15）の色の RGB 値を、rgb に返します。

inspector_open

inspector_open 関数は Max に組み込まれています。これは、myobject-insp.pat を、サーチパスから探索して開きます。 inspector_open を使ってパッチを開くことによって、特別なバインディングが実行されます。これによって、パッチ内の thisobject オブジェクトは、調べられるインスタンスとリンクされます。インスペクタパッチは、特別なテクニックを使って書かれる必要があります。これについては、 hslider の例の中で書かれています。

notify_free

この関数は、インスペクタを持ったあらゆるオブジェクトの free メソッドで呼び出すようにして下さい。これによって、開いているインスペクタからオブジェクトを切り離します。notify_free は box_free の前に呼び出されなければなりません。

pstate

バインディング

宣言

pstate はあなたのオブジェクトのクラスの名前となるシンボルを含みます。その後に、設定を反映した値が続きます。これらは保存、復元することができます。例えば、次はオブジェクトの内部にある３つの設定、m_multipler、m_weight、m_length を保存する pstate メソッドです。

void myobject_pstate(t_myobject *x, void *w) { binbuf_vinsert(w, "slll", gensym("myobject"), x->m_multiplier, x->m_weight, x->m_length); }

qtimage_open

ファイル名、パス、および GWorld(gp) を与えられると、qtimage_open はファイルを開き、与えられた GWorld の中へレンダリングします。イメージの描画時に、スケーリングや時間のオフセット（時系列メディアの場合）などの処理のために、extra の情報が使われる場合があります

gp が　NULL の場合、qtimage_open は新規に３２ビットオフスクリーン gworld を生成し、その中にイメージを（必要ならスケーリング処理を行って）レンダリングします。呼出しを行ったオブジェクトには、このメモリを解放する責任があります。呼出しを行うオブジェクトが、オンスクリーン GWorld、非３２ビット GWorld、あるいはオートフィットスケーリングモードを使用したい場合、gp は有効なポインタでなければなりません。

Windows XP 上では、CGrafPtr が QTML グラフィックワールドで動作します。このため、QTI_FLAG_QTML_GWORLD フィールドが　extra->flags にセットされている必要があります。後述する qtimage_extra_flags_set メソッドを使って、これをセットすることができます。

qtimage_getrect

qti_extra_new

qti_extra_free

qti_extra_matrix_get

qti_matrix_get は、qti_extra オブジェクトの matrix メンバの内容を、MatrixRecord の中にコピーします。MatrixRecord や、それを使ってイメージを変形する方法に関しての詳しい情報は、Apple QuickTime デベロッパドキュメンテーションを参照して下さい。extra と matrix は共に有効なポインタでなければなりません。

qti_extra_matrix_set

qti_extra_matrix_set は MatrixRecord の内容を qti_extra オブジェクトの matrix メンバにコピーします。MatrixRecord や、それを使ってイメージを変形する方法に関しての詳しい情報は、Apple QuickTime デベロッパドキュメンテーションを参照して下さい。qtimage_open や qtimage_rect でスケーリングに使われる qti_extra オブジェクトの matrix メンバのために、qti_extra オブジェクトの スケールモードは QTI_SCALEMODE_MATRIX にセットされていなければなりません（qti_extra_scalemode_set を参照）。 extra と matrix は共に有効なポインタでなければなりません。

qti_extra_rect_get

qti_extra_rect_get は qti_extra オブジェクトの rect メンバの内容を、標準の Rect 構造体にコピーします。Rect 構造体を使ってイメージを変形する方法に関する詳しい情報は Apple QuickTime デベロッパドキュメンテーションを参照して下さい。 extra と rct は共に有効なポインタでなければなりません。

qti_extra_rect_set

qti_extra_rect_set は Rect 構造体の内容を、qti_extra オブジェクトの rect メンバにコピーします。Rect 構造体を使ってイメージを変形する方法に関する詳しい情報は Apple QuickTime デベロッパドキュメンテーションを参照して下さい。qtimage_open や qtimage_rect でスケーリングに使われる qti_extra オブジェクトの rect メンバのために、qti_extra オブジェクトのスケールモード・メンバ変数は QTI_SCALEMODE_RECT にセットされていなければなりません（qti_extra_scalemode_set を参照）。 extra と rct は共に有効なポインタでなければなりません。

qti_extra_scalemode_get

extra と scalemode は共に有効なポインタでなければなりません。

qti_extra_scalemode_set

qti_extra_scalemode_set は、long の値を qti_extra オブジェクトの rect メンバ変数にコピーします。extra は有効なポインタでなければなりません。scalemode の可能な値は次のようになっています。

QTI_SCALEMODE_NONE

QTI_SCALEMODE_MATRIX

QTI_SCALEMODE_RECT

QTI_SCALEMODE_AUTOFIT

QTI_SCLEMODE_AUTOFIT を使った場合、qtimage_opne は有効な GWorld へのポインタ(gp)を必要とします。また、QTI_SCALEMODE_AUTOFIT を使った場合、qtimage_rect 関数は使用されません。これは、rect が、 qtimage_open に渡された GWorld と同じ大きさでイメージをレンダリングすることを要求するためです。

qti_extra_time_get

タイムユニットに関する詳しい情報は、Apple QuickTime デベロッパドキュメンテーションを参照して下さい。 extra と time は共に有効なポインタでなければなりません。

qti_extra_time_set

extra は有効なポインタでなければなりません。タイムユニットに関する詳しい情報は、Apple QuickTime デベロッパドキュメンテーションを参照して下さい。

qti_extra_flags_get

extra と flags は共に有効なポインタでなければなりません。

qti_extra_flags_set

extraは有効なポインタでなければなりません。

XQT_GetQuickTimeVersion

QuickTime がインストールされていれば、そのバージョンが返されます。インストールされていない場合は 0 が返されます。

XQT_CheckFunPtr

ppfn によって参照される関数ポインタが NULL の場合、QuickTime ライブラリから“name”で指定された関数をロードしようと試みます。戻り値はエラーコードです。

XQT_OpenMovieFilePathSpec

OpenMovieFile と同じですが、QT FSSpec ではなく Max の PATH_SPEC を使います。この２つは Macintosh 上では同じものですが、Windows 上では異なります。戻り値はエラーコードです。

XQT_QT2MaxSpecCopy

QT の FSSpect を Max の PATH_SPEC に変換します。戻り値はエラーコードです。

XQT_ Max2QTSpecCopy

Max の PATH_SPEC を QT の FSSpec へコピーする場合に、XQT_Max2QTSpecCopy を使います。 （訳注：原文は“Use XQT_Max2QTSpecCopy to open a movie file.”となっていますが、誤植と思われます）

Max の PATH_SPEC を QT の FSSpec に変換します。 戻り値はエラーコードです。

XQT_patcher_setport

QTML ベースの UI エクスターナルのために、patcher_setport を置き換えるもの。Macintosh バージョンと違って、これは update メソッドの中でも呼び出されなければなりません。

XQT_patcher_getport

Max パッチャーの QT ポートを返します。

XQT_patcher_restoreport

以前のポートをリストア（復元）するための SetPort を置き換えるもの。これは、QTML ベースの UI エクスターナルが必要とするもので、XQT_patcher_setport が使われた場合、必ず一対の処理として用いなければなりません。

XQT_wind_setport

QTML ベースの UI エクスターナルのために、wind_setport を置き換えるもの。Macintosh バージョンと違って、これは update メソッドの中でも呼び出されなければなりません。

XQT_wind_getport

Max ウィンドウの QT ポートを返します。

注：XQT_SetPortによってポートを保存していることを確認して下さい。wind_restoreport でリストア（復元処理）を行うと、予想外の結果を引き起こしてしまいます。

XQT_box_nodraw

QTML ベースの UI エクスターナルを作る場合、box_nodraw の代わりに XQT_box_nodraw を使います。
（訳注：原文は、”Use XQT_box_nodraw in place of wind_setport when making QTML-based UI externs.”となっています）

QTML ベースの UI エクスターナルの場合に必要とされ、 box_nodraw を置き換えるものです。

XQT_box_enddraw

QTML ベースの UI エクスターナルを作る場合、box_enddraw の代わりに XQT_box_enddraw を使います。 （訳注：原文は、”Use XQT_box_enddraw to get a Max patcher’s QT port”となっています）

QTML ベースの UI エクスターナルの場合に必要とされ、box_enddraw を置き換えるものです。