をクリックしてコードビルダでXファンクションを開くとOrigin
C のコードを記述できます。
コードビルダボタンをクリックしてコードビルダでXファンクションを開くとOrigin
C のコードを記述できます。
内容 |
編集ウィンドウ上部付近に2つのボタン、コンパイルボタン
とダイアログに戻るボタン
があります。コンパイルボタンは、XファンクションのOrigin
Cコードをコンパイルするのに使用します。ダイアログに戻るボタンは、編集ウィンドウを閉じ、Xファンクションビルダダイアログに戻ります。
編集ウィンドウでは、いくつかのOrigin Cコードの背景が灰色になっています。これらのコードは読み取り専用で、変更できません。Xファンクションフレームワークはこの部分のコードを生成し、この部分は必須シンタックスになっています。
XファンクションのOrigin Cコードに追加のヘッダファイルをインクルードできます。特別な理由がなければ、追加のヘッダファイルはファイルの上部の次の行の下にインクルードすることをお勧めします。
//put additional include files here
この行の下にヘッダファイルをインクルードする事で、ファイルを整理して他のXファンクションと一貫性を持たせられます。
< と > のブラケットを使ってファイルをインクルードすると、そのファイルは、Origin インストールフォルダのOrigin C\Systemフォルダからインクルードされます。相対パスを使って、Systemフォルダの上位のフォルダに移動することもできます。これらのブラケットは、 .c および .cpp ファイルをコンパイルするときに同じ動作をします。
// "OriginC\System"フォルダにあるfft_utils.hをインクルード #include <fft_utils.h> // "OriginC\OriginLab"フォルダにあるabffiles.hをインクルード #include <..\OriginLab\abffiles.h> // 相対パス
ダブルクオテーション("")を使ってファイルをインクルードすると、それらのファイルは、ユーザファイルフォルダの「Origin C\X-Functions」フォルダからインクルードされます。この動作は、Origin Cで .c または .cpp ファイルをコンパイルするときとは異なります。この動作の違いが必要なのは、XファンクションがOriginによって維持される場所にインストールされるためです。
// ユーザファイルフォルダの "OriginC\X-Functions"フォルダに // あるmyOtherheader.hファイル #include "myOtherheader.h"
絶対パスをダブルクオテーションで囲んで指定すると、そのファイルはファイルの場所を無視してインクルードされます。
Xファンクションビルダのツリービューで、自動コンパイル依存ファイルというオプションがあります。このオプションをオンにすると、コンパイラはインクルードされた.hファイルと同じ名前を持つ.c または .cpp ファイルをチェックします。 .c または .cpp ファイルが見つかったら、ロードされ、コンパイルされます。
// "OriginC\Originlab"フォルダにあるgraph_utils.hをインクルード // 自動コンパイル依存ファイルがオンの場合 // 同じフォルダにあるgraph_utils.cファイルをロードし、コンパイル #include <..\Originlab\graph_utils.h>
他のプログラミング言語に対しても同様ですが、関数をより明確に読みやすく、作成したコードが将来でも理解しやすく、なおかつメンテナンスしやすくするために、長い関数を機能的に独立させて分割し、短い構造にすることをお勧めします。Xファンクションでは、これらの短い関数を次の行の後にキーワード static を持つ内部関数のように追加可能です。
//put your own support static functions here
例えば、GUIとのやり取りが多くあるXファンクションでは、多くのコードは xfname_event1( )で必要とされ、Originのinterp1 Xファンクションに似たスタティック関数を追加できます。
static void _update_method_show(TreeNode& trGetN)
ご覧のように、アンダーバーを使って関数名のコンポーネントを分割した表記にすることをお勧めします。
メイン関数は、Xファンクションの主要な操作を実行するすべてのコードを配置します。
Xファンクションのメイン関数は、XファンクションビルダでXファンクションと同じ名前を持ちます。例えば、Xファンクションに myXFunc という名前を付けると、メイン関数も myXFuncという名前になります。
メイン関数に渡される引数は、Xファンクションビルダダイアログにリストされた変数です。Inputとしてセットされるすべての変数は、定数の参照で渡され、OutputまたはInput/Outputとしてセットされる変数は書き換え可能な参照として渡されます。
Xファンクションのソースコードは、さまざまなイベントを取り扱うために使用する関数を含みます。各イベントハンドラー関数の名前は、Xファンクションの名前がプレフィックスとなり、アンダーバーの後にイベント名となります。例えば、Xファンクションの名前が myXFunc の場合、before_execute イベントハンドラー関数は myXFunc_before_executeという名前になります。
以下は、イベントの一覧です。
デフォルトで、すべてのイベントハンドラー関数は空です。デフォルトの動作を変更したり、イベントに追加の処理を行う時のみ、イベントハンドラー関数にコードを追加します。
次のセクションは、各イベントハンドラーの目的、渡される関数、戻り型など詳細について説明しています。
この関数は、メイン関数の実行前に2回、3回呼び出されます。
プロトタイプ
void xfname_before_execute(TreeNode& trGetN, int nGetNDialog, int& nRet, int dwCntrl)
パラメータ
trGetN
Xファンクションに渡される変数を含むツリーノードです。
nGetNDialog
関数が呼ばれるときに示される整数値です。
0より大きい値は、関数のダイアログを表示する前に呼ばれることを示します。これは、メニューからダイアログを開くを選んだり、プログラムで -d オプションを付けてXファンクションを呼び出したり、手動再計算を行うためにパラメータの変更を選ぶときに発生します。
| 値 | ダイアログを開く前 |
|---|---|
| 1 | 単純GetNBox |
| 2 | プレビュー付きGetNGraphBox |
| 3 | GetNImageBox |
-1という値は、ユーザがOKボタンを押すことによって、ダイアログが閉じたことを示しています。
0という値は、メイン関数が呼ばれようとしていることを示しています。
nRet
このオプションは、Xファンクションの実行状態を制御できます。
XFEVT_PROCEED = 0 // 通常の実行を続ける XFEVT_ABORT = 1 // 実行中止 XFEVT_PROCEED_NO_DLG = 2 // ダイアログを開かずに実行
dwCntrl
このオプションは、このXファンクションがどのようにアクセスされるかを決めるのに使用できます。可能な値は、次のようになります。
LTXF_FROM_GUI_MENU // メニューからアクセス LTXF_FROM_GUI_PROMPT // コマンドウィンドウからアクセス LTXF_FROM_AUTO_UPDATE // 自動更新でアクセス LTXF_FROM_FUNCTION // Origin C関数からアクセス LTXF_THEME_USED // テーマを使用 LTXF_CHANGE_PARAM // パラメータ変更でアクセス
次のサンプルは、Xファンクションがコマンドウィンドウからアクセスし、テーマを使用する方法を示しています。(コマンドウィンドウに xfname -t themename と入力)
if(!(dwCntrl & LTXF_FROM_GUI_PROMPT) && (dwCntrl & LTXF_THEME_USED)) { // このケースを取り扱い }
この関数は、Xファンクションに渡される各ツリーノード変数に対して1回呼び出されます。呼び出しは、before_execute 関数が呼ばれる前に起こります。
プロトタイプ
int xfname_make_tree(TreeNode& tr, LPCSTR lpcszVarName)
戻り値
ダイアログを更新するには0、ダイアログを更新しない場合は-1を返します。デフォルトの動作では-1を返します。
パラメータ
tr
作成されるツリーノードです。これはXファンクションの入力TreeNode型で定義される必要があります。
lpcszVarName
TreeNode変数の名前を示します。
これらは、主要なイベントハンドリング関数です。これらはダイアログの初期化、ダイアログ内の設定の変更、ボタンクリックなど、どんなイベントでも呼ばれます。これらの関数は、単純GetNダイアログを持つXファンクションでのみ使われます。グラフプレビュー付き、イメージプレビュー付きのXファンクションは、後のセクションで説明する異なるイベントハンドラー関数を使用します。
プロトタイプ
int xfname_event1(TreeNode& trGetN, int nRow, int nEventID, DWORD& dwEnables, LPCSTR lpcszNodeName, WndContainer& DynaCntrlContainer, string& strAux, string& strErrMsg)
戻り値
Trueが返されると、ダイアログが更新されます。
パラメータ
trGetN
これは、Xファンクションで定義する変数のツリーノードです。
nRow
ツリーノード trGetNで値変更コントロール行のインデックスです。 コントロール値が変更しないというイベントのとき、値は-1です。
nEventID
イベントタイプのID、例えばGETNE_ON_INIT, GETNE_ON_THEME等です。
dwEnables
このパラメータは、OKボタン、適用ボタン、その他カスタムボタンを有効または無効にするのに使います。これはデフォルトでTrueで、ユーザの設定が無効の時Falseにセットされ、OKボタンと適用ボタンが無効になります。
lpcszNodeName
イベントがダイアログのコントロールの変更によって生成されると、このコントロールの変数名になります。それ以外の場合、空の文字列になります。
DynaCntrlContainer
Xファンクションのダイアログウィンドウを入れるコンテナです。
strAux
このパラメータは、補助的な文字列で、高度な利用を行うためのものです。以下の定義のように、詳細はヘッダファイル<Originのインストールフォルダ>\OriginC\System\GetNBox.hをご覧ください。
#define DLG_NEED_CHANGE_GRID "GETN_CHANGE_GRID" #define GETN_CHANGE_GRID set_aux_value(strAux, DLG_NEED_CHANGE_GRID);
strErrMsg
これは、ダイアログの下に表示される文字列のメッセージです。これは通常、変数値の入力中に発生するエラーをユーザに通知するのに使います。
event1 および event1_ex イベントハンドラー関数は、グラフプレビュー付きのXファンクションで使われません。代わりに、GetNGraphPreview 関数を使用します。
グラフプレビューダイアログを持つXファンクションを作成する方法のサンプルは、GetNダイアログでグラフプレビューを作成
セクションをご覧ください。
event1 および event1_ex イベントハンドラー関数は、イメージプレビュー付きのXファンクションで使われません。代わりに、GetNImageBox 関数を使用します。
イメージプレビューダイアログを持つXファンクションを作成する方法のサンプルは、イメージGetNダイアログでグラフプレビューを作成 セクションをご覧ください。
ユーザが悪い値を -d オプションと一緒にXファンクションに渡したり、Xファンクションダイアログに悪い値を入力した時に、イベントハンドラー関数に渡されるstrErrMsg引数をセットしておくと、ダイアログにエラーメッセージを表示します。
どのイベントハンドラー関数が呼ばれるかはXファンクションが使用しているGetNダイアログに依存します。
| 使用されるGetNダイアログ | イベントハンドラー関数 |
|---|---|
| 単純GetNBox | xfname_event1 |
| プレビュー付きGetNGraphBox | GetNGraphPreview_OnChange |
| GetNImageBox | GetNImageBox_OnChange |
x1という整数型の変数を受け付けるXファンクションがあるとします。次のコードを適切なイベントハンドラー関数に挿入すると、変数 x1 の値が0以下か100以上かをチェックします。ダイアログで表示するためにstrErrMsgを適切なメッセージにセットすると、OKボタンを無効にします。値が受け入れられる範囲内にある場合、OKボタンが有効になります。
if( trGetN.x1.nVal < 0 || 100 < trGetN.x1.nVal ) { strErrMsg = "x1 is out of range.Must be from zero to 100."; bOKEnable = false; } else bOKEnable = true;
Xファンクションがプログラムで呼ばれてそのダイアログボックスは表示されないので、エラーが発生したことをユーザに通知するため別の方法が必要になります。Origin Cは、エラーメッセージを 結果ログ、コマンドウィンドウ、スクリプトウィンドウに出力するマクロを定義しています。out_str またはprintfではなく、これらのマクロを使用することを強くお勧めします。
XF_WARN マクロは警告メッセージを出力しますが、実行は停止しません。 これら3つのマクロは、最初の引数として警告メッセージを含む文字列を受け付けます。他の引数を受け付ける2つのマクロは、警告メッセージが1つまたは2つの値のフォーマット文字列であるものとします。
// 以下を仮定する // #define MIN_DATA_POINTS 5 // int nNumPts = 3; // string strWksName = "Book1"; XF_WARN("Too few data points."); XF_WARN_EX("Number of data points less than %d.", MIN_DATA_POINTS); XF_WARN_EX("Worksheet named %s was not found.", strWksName); XF_WARN_EX2("Only %d data points, need at least %d.", nNumPts, MIN_DATA_POINTS);
XF_TRACE マクロは、実行停止しないという点でXF_WARNマクロに似ています。最初の引数に対するメッセージを取ることもできますが、追加の引数もいくつでも取ることができます。
// 以下を仮定する // #define MIN_DATA_POINTS 5 // int nNumPts = 3; // string strWksName = "Book1"; XF_TRACE("Only %d data points found in %s, need at least %d.", nNumPts, strWksName, MIN_DATA_POINTS);
XF_THROW マクロは実行を停止しますが、それ以外はXF_WARN マクロと同じです。これら3つのマクロは、最初の引数として警告メッセージを含む文字列を受け付けます。他の引数を受け付ける2つのマクロは、警告メッセージが1つまたは2つの値のフォーマット文字列であるものとします。
// 以下を仮定する // #define MIN_DATA_POINTS 5 // int nNumPts = 3; // string strWksName = "Book1"; XF_THROW("Too few data points."); XF_THROW_EX("Number of data points less than %d.", MIN_DATA_POINTS); XF_THROW_EX("Worksheet named %s was not found.", strWksName); XF_THROW_EX2("Only %d data points, need at least %d.", nNumPts, MIN_DATA_POINTS);