class cymel.ui.optionbox.OptionBox

Inheritance diagram of OptionBox
class cymel.ui.optionbox.OptionBox(*args, **kwargs)

ベースクラス: object

オプションボックス作成のための抽象基底クラス。

オプションボックスを開発する場合は、このクラスを継承し、 ツール名、オプション接頭辞、デフォルト値などのクラス属性を定義したうえで、 UI 構築と値のロード/セーブ、および実行コード生成を実装する。

オプション値は OptionVar に保存され、 その値はインスタンスに作られる optionvar 属性から読み書きできる。

最小構成の例:

import cymel.ui as cmu

class MyOptionBox(cmu.OptionBox):
    TOOL_NAME = 'Test'
    TOOL_VERSION = '1.0.0'
    BUTTON_LABEL = 'Test'
    OPT_PREFIX = 'Test.'
    DEFAULTS = dict(foo=False, bar=1.0)

    def assemblePyCode(self):
        return 'print(dict(%s))' % self.assemblePyCodeWithArgs()

    def createContents(self, tabId):
        if tabId == 1:
            cmu.CheckBoxGrp('foo', ncb=1, l1='Foo', cc=self.onChanged)
            cmu.FloatFieldGrp('bar', l='Bar')

    def loadOptions(self, tabId=None):
        if (tabId == 1 or tabId is None) and self.isTabReady(1):
            cmu.Control('foo').setValue(self.get('foo'))
            cmu.Control('bar').setValue(self.get('bar'))

    def saveOptions(self, tabId=None):
        if (tabId == 1 or tabId is None) and self.isTabReady(1):
            self.set('foo', cmu.Control('foo').getValue())
            self.set('bar', cmu.Control('bar').getValue())

    def updateState(self, tabId=None):
        if (tabId == 1 or tabId is None) and self.isTabReady(1):
            cmu.Control('bar').set('enable', cmu.Control('foo').getValue())

# MyOptionBox().perform(0)  # Execute the command using the current settings.
# MyOptionBox().perform(1)  # Open the Options box.
# MyOptionBox().perform(2)  # Retrieve the command string to be executed using the current settings.

Methods:

__init__()

addMenu(**kwargs)

オプションボックスのメニューバーにメニューを追加する。

assemblePyCode()

実行用 Python コードを生成して返す。

assemblePyCodeWithArgs([modName, funcName, ...])

実行用 Python コードを生成するためのヘルパー。

createContents(tabId)

タブ内の UI コントロールを生成する。

createLayout(tabId)

タブ内のレイアウトを生成する。

currentTabId()

カレントタブインデックスを得る。

execute([echo, addQueue])

現在の設定でコマンドを実行する。

get(key)

保持している値を取得する。

getLayout([tabId])

指定 ID のレイアウトを得る。

getValidUIInstance()

現在有効な UI を持つインスタンスを得る。

get_(rawkey)

保存用キーを指定して値を取得する。

growUpWindowSize([tabId, fitW, fitH, addW])

show で呼ばれるウィンドウのリサイズ処理。

isTabReady(tabId)

タブの中身が生成済みなら setParent して True を返す。

isUIAlive()

表示したオプションボックス UI が存在しているかどうか。

keyToExec(key)

保存用キーを実行用キーへ変換する。

keyToStore(key)

実行用キーを保存用キーへ変換する。

load()

オプション値を UI にロードする。

loadOptions([tabId])

保存されたオプション値を UI にセットする。

makeWeakCB(name, *args, **kwargs)

このインスタンスを強参照しないメソッドコールバックを得る。

onChanged(*args, **kwargs)

汎用的に使える UI のチェンジコールバック。

perform(cmdi)

Maya 標準オプションボックスから呼び出される入口。

ref()

弱参照を得る。

reset()

オプション値をリセットして UI を更新する。

resetOptions()

保持しているオプション値をデフォルトにリセットする。

save()

UI の状態をオプション値として保存する。

saveOptions([tabId])

UI から値を読み取って保存する。

set(key, val)

値を保存する。

set_(rawkey, val)

保存用キーを指定して値を保存する。

show()

オプションボックスを表示する。

showHelp(*args)

HELP_URL を表示する。

title()

ウィンドウタイトルを返す。

updateState([tabId])

UI の有効/無効などの状態を更新する。

Attributes:

APPLY_BUTTON_LABEL = None

"Apply" ボタンのラベル。

BUTTON_LABEL = 'Execute'

"Apply and Close" ボタンのラベル。

CLOSE_BUTTON_LABEL = None

"Close" ボタンのラベル。

COMMAND_LABEL = ''

RecentCommandQueue に追加される名前。省略時は TOOL_NAME 。

DEFAULTS = {}

OptionVar のデフォルト値辞書。

DEFAULT_TAB_INDEX = 1

最初に開くタブの番号。

DEFUNCT_KEYS = ()

廃止されたオプション名のリスト。必要に応じてoptionVarから削除される。

HELP_URL = ''

ヘルプドキュメントのURL。

INIT_HEIGHT = False

初回に growUpWindowSize で高さをフィットさせるかどうか。

INIT_WIDTH = False

初回に growUpWindowSize で幅をフィットさせるかどうか。

MIN_HEIGHT = None

growUpWindowSize におけるウィンドウの最小高。

MIN_WIDTH = None

growUpWindowSize におけるウィンドウの最小幅。

NO_RESETS = ()

リセット対象外とするオプション名リスト。

OPT_PREFIX = ''

OptionVar の接頭辞。

SHOW_ERROR_DIALOG = False

エラーを捕捉してダイアログを出すかどうか。

SUPPORTED_VERSION = (8, 5)

Mayaの最低サポートバージョン。

TAB_LABELS = ('Main',)

タブレイアウトのラベルリスト。

TOOL_NAME = 'Abstract'
TOOL_VERSION = '0.0.0'

ツールバージョン。

Methods Details:

__init__()
addMenu(**kwargs)

オプションボックスのメニューバーにメニューを追加する。

パラメータ:

kwargs -- menu コマンドに渡す引数。

戻り値の型:

str

assemblePyCode()

実行用 Python コードを生成して返す。

派生クラスで必ず実装する。assemblePyCodeWithArgs を使うと、 optionVar に保存された値から関数呼び出しや引数リストを組み立てられる。

戻り値の型:

str

assemblePyCodeWithArgs(modName=None, funcName=None, args=None, kwargs=None, argKeys=None, ignoreKeys=None, qualifyKeys=None, asDict=False, skipDefaultValues=True, commandDefaults={})

実行用 Python コードを生成するためのヘルパー。

以下の順で引数が組み立てられる。

  1. args で指定された値が位置引数になる。

  2. argKeys で指定されたキーの保存値が位置引数として追加される。

  3. kwargs で指定された値がキーワード引数になる。

  4. 内部の optionVar からキーワード引数を自動収集する。

自動収集では次の条件を考慮する。

  • skipDefaultValues が True だと、デフォルト値と同じ値は収集されない。

  • kwargs に直接指定されたキーは重複収集しない。

  • argKeys に指定されたキーはキーワード引数としては収集しない。

  • ignoreKeys に含まれるキーは収集しない。

  • qualifyKeys が指定された場合は、そのキーだけを収集する。

パラメータ:

  • modName (str) -- 関数を含むモジュール名。funcName と共に指定すると import module; module.func(...) 形式を返す。

  • funcName (str) -- 呼び出す関数名。省略した場合は引数リスト部分だけを返す。

  • args (iterable) -- 直接指定する位置引数の値。

  • kwargs (dict) -- 直接指定するキーワード引数の値。

  • argKeys (iterable) -- optionVar から位置引数として取り出すキー。

  • ignoreKeys (container) -- 自動収集から除外する実行用キー。

  • qualifyKeys (container) -- 自動収集の対象にする実行用キー。

  • asDict (bool) -- True の場合はコード文字列ではなくキーワード引数辞書を返す。

  • skipDefaultValues (bool) -- True の場合はデフォルト値と同じ値は自動収集されない。

  • commandDefaults (dict) -- skipDefaultValues=True のとき、実行コマンド側のデフォルト値が 保存用 DEFAULTS と異なる場合の比較値を指定できる。

戻り値:

Python コード文字列、またはキーワード引数辞書。

createContents(tabId)

タブ内の UI コントロールを生成する。

派生クラスで必ず実装する。呼び出し時には対象タブのレイアウトが setParent 済みであり、未生成のタブが初めて表示された時に 一度だけ呼ばれる。

パラメータ:

tabId (int) -- 1 から始まるタブインデックス。タブを使わない場合は 0。

createLayout(tabId)

タブ内のレイアウトを生成する。

TAB_LABELS に None や空値を指定してタブレイアウトを使わない場合は、 tabId には 0 が渡される。基底の実装は columnLayout だが、派生クラスで任意のレイアウトに置き換えられる。

パラメータ:

tabId (int) -- 1 から始まるタブインデックス。タブを使わない場合は 0。

戻り値の型:

str

currentTabId()

カレントタブインデックスを得る。

タブレイアウトを使っていない場合は 0 を返す。

戻り値の型:

int

execute(echo=True, addQueue=True)

現在の設定でコマンドを実行する。

パラメータ:

  • echo (bool) -- 実行コードを標準出力へ表示するかどうか。 表示される文字列は Python コードそのもの。

  • addQueue (bool) -- Maya の RecentCommandQueue に追加するかどうか。 リピート実行から呼ぶ場合は二重登録を避けるため False にする。

get(key)

保持している値を取得する。

keyToStore で保存用キーへ変換した後、get_ に処理を委譲する。

パラメータ:

key (str) -- 実行用キー。

戻り値:

保存されている値。

getLayout(tabId=None)

指定 ID のレイアウトを得る。

パラメータ:

tabId (int) -- 1 から始まるタブインデックス。省略時はカレントタブ。 タブレイアウトを使わない場合は 0。

戻り値の型:

str or None

classmethod getValidUIInstance()

現在有効な UI を持つインスタンスを得る。

このクラスと派生クラスを深さ優先で調べ、 生存中のオプションボックス UI を持つ最初のインスタンスを返す。

戻り値の型:

OptionBox or None

get_(rawkey)

保存用キーを指定して値を取得する。

値の取得をカスタマイズしたい場合に派生クラスでオーバーライドする。 標準では内部の OptionVar からそのまま返す。

パラメータ:

rawkey (str) -- keyToStore で変換された後のキー。

戻り値:

保存されている値。

growUpWindowSize(tabId=None, fitW=False, fitH=False, addW=0)

show で呼ばれるウィンドウのリサイズ処理。

ウィンドウサイズがタブにとって十分でなければリサイズされる。

多くの場合、UI 構築後に呼ぶ。fitW や fitH を True にすると、 小さくなる方向の調整も行う。

パラメータ:

  • tabId (int) -- 1 から始まるタブインデックス。省略時はカレントタブ。

  • fitW (bool) -- 幅が小さくなる場合もリサイズする。

  • fitH (bool) -- 高さが小さくなる場合もリサイズする。

  • addW (int) -- 計算された幅へ追加するピクセル数。

isTabReady(tabId)

タブの中身が生成済みなら setParent して True を返す。

loadOptions や saveOptions で、まだ表示されていない遅延生成タブを 誤って操作しないために利用する。

パラメータ:

tabId (int) -- 1 から始まるタブインデックス。

戻り値の型:

bool

isUIAlive()

表示したオプションボックス UI が存在しているかどうか。

オプションボックスが閉じられたり他ツールに差し替えられたりした後に、 別途保持しているインスタンスから UI の生存を確認できる。

戻り値の型:

bool

keyToExec(key)

保存用キーを実行用キーへ変換する。

パラメータ:

key (str) -- keyToStore で変換された後の保存用キー。

戻り値:

コマンド実行に使う通常のキー。

戻り値の型:

str

keyToStore(key)

実行用キーを保存用キーへ変換する。

コマンド実行時の引数名と OptionVar に保存するキー名を分けたい場合に、keyToExec と対でオーバーライドする。

パラメータ:

key (str) -- コマンド実行にも使われる通常のキー。

戻り値:

OptionVar に保存するキー。

戻り値の型:

str

load()

オプション値を UI にロードする。

現在のオプションボックスレイアウトを setParent したうえで、 loadOptions と updateState を呼ぶ。

loadOptions(tabId=None)

保存されたオプション値を UI にセットする。

派生クラスで必ず実装する。tabId が None の場合は、 生成済みの全タブを対象にすることを想定している。

パラメータ:

tabId (int) -- 1 から始まるタブインデックス。None の場合は全体。

makeWeakCB(name, *args, **kwargs)

このインスタンスを強参照しないメソッドコールバックを得る。

UI コールバックに直接 bound method を渡すとインスタンス寿命が延びるため、 弱参照経由で対象メソッドを呼ぶ関数を返す。

パラメータ:

  • name (str) -- 呼び出すメソッド名。

  • args -- メソッドへ渡す固定位置引数。

  • kwargs -- メソッドへ渡す固定キーワード引数。

戻り値の型:

callable

onChanged(*args, **kwargs)

汎用的に使える UI のチェンジコールバック。

デフォルトでは updateState を呼ぶ。

perform(cmdi)

Maya 標準オプションボックスから呼び出される入口。

パラメータ:

cmdi (int) -- 0 なら現在の設定で実行、 1 ならオプションボックスを開く、 2 なら現在の設定で実行される Python コード文字列を返す。

戻り値:

実行時またはコード取得時はコマンド文字列。表示時は空文字列。

ref()

弱参照を得る。

戻り値の型:

weakref.ref

reset()

オプション値をリセットして UI を更新する。

NO_RESETS の値を未保存状態で失わないように、まず saveOptions を呼び、 その後 resetOptions、loadOptions、updateState の順で処理する。

resetOptions()

保持しているオプション値をデフォルトにリセットする。

NO_RESETS に指定したキーは対象外になる。

save()

UI の状態をオプション値として保存する。

現在のオプションボックスレイアウトを setParent したうえで、 updateState と saveOptions を呼ぶ。数値フィールド編集中に Apply された場合などを考慮し、保存前に状態更新を行う。

saveOptions(tabId=None)

UI から値を読み取って保存する。

派生クラスで必ず実装する。tabId が None の場合は、 生成済みの全タブを対象にすることを想定している。

パラメータ:

tabId (int) -- 1 から始まるタブインデックス。None の場合は全体。

set(key, val)

値を保存する。

keyToStore で保存用キーへ変換した後、set_ に処理を委譲する。

パラメータ:

  • key (str) -- 実行用キー。

  • val -- 保存する値。

set_(rawkey, val)

保存用キーを指定して値を保存する。

値の保存をカスタマイズしたい場合に派生クラスでオーバーライドする。 標準では内部の OptionVar にそのまま渡す。

パラメータ:

  • rawkey (str) -- keyToStore で変換された後のキー。

  • val -- 保存する値。

show()

オプションボックスを表示する。

既に UI が存在していれば、そのウィンドウを前面に出す。 未生成の場合は Maya 標準のオプションボックス領域を取得し、タブ、 ボタン、メニューコールバックを設定する。

showHelp(*args)

HELP_URL を表示する。

Maya の showHelp を優先し、失敗した場合は Python 標準の webbrowser にフォールバックする。

title()

ウィンドウタイトルを返す。

オーバーライドすることで任意に変更できる。

戻り値の型:

str

updateState(tabId=None)

UI の有効/無効などの状態を更新する。

必要な場合だけ派生クラスで実装する。tabId が None の場合は、 生成済みの全タブを対象にすることを想定している。

パラメータ:

tabId (int) -- 1 から始まるタブインデックス。None の場合は全体。