Property¶
Property(メニューの種類 PROPERTY)は、ユーザープロパティを 1 つ定義します。
定義には型、引数、Enum 項目、コールバック、保存先、Property ID が含まれます。
定義は項目名で読み取り、変更します。
Property Stack は Property Stack で説明します。
関数 |
用途 |
|---|---|
定義を |
|
定義、保存先、Property ID を変更します。 |
関連項目: 設定を Property のスイッチにする。
関数¶
- pme.editing.update_property(pm_uid, changes, *, expected_digest=None, dry_run=False)¶
Property の定義、保存先、Property ID を、エディターと同じ処理で変更します。
すべての変更を、最初の書き込みの前に検査します。1 つでも拒否されれば、何も書き込みません。 そのあと、変更を 3 つのグループに分け、決まった順序で保存します。
- パラメータ:
pm_uid (str) -- Property の UID。
changes (dict) -- 項目名と新しい値の対応。項目名は Property の定義 の項目のうち、読み取り専用のもの以外です。 部分指定です。指定しない項目は、初期化の規則 による変化を除き、 値を保持します。
Noneは引数をエディター既定値に戻し、コールバックを削除します。expected_digest (str or None) --
read_pm()["property"]["digest"]。保存されている Property が変わっている場合、更新はstale_propertyで拒否されます。dry_run (bool) -- 変更を検査し、書き込まずに返ります。
- 戻り値:
下で説明する結果。
- 戻り値の型:
- 例外:
TypeError --
changesがマッピングではない。multiselect、expand、horizontal、restore_default、property_id_lockedが bool ではない。コールバックが文字列でもNoneでもない。property_idが文字列ではない。storageがNoneでも空でない文字列でもない。itemsがマッピングのシーケンスではない、項目のidentifierが文字列ではない、またはuid、name、iconが文字列でもNoneでもない。expected_digestが文字列でもNoneでもない。dry_runが bool ではない。ValueError -- 項目名が不明。
typeが 5 つの型のいずれでもない。sizeが 1〜32 の整数ではない。項目にuid、identifier、name、icon以外のキーがある。UID がない、不正、または曖昧。メニューが Property ではない。RuntimeError -- Blender のメインスレッド以外から呼ばれた、PME の読み込みが完了していない、または PME の Preferences を利用できない。
グループ
group実行される条件
保存処理
storagestorageが保存値と異なる。エディターの保存先の設定。移動先の保存先に合わせて、新しい Property ID を選ぶことがあります。
property_id保存されている Property ID または Lock が、要求されたものと異なる。 保存先グループが選んだ ID も含みます。
エディターの Edit Property ID。
definitionその他の項目が保存値と異なる。
エディターの各項目のあと、Blender への 1 回の登録。
各グループの終了時点で、Property は完成した形です。
groupsは実行したグループ、pendingは実行しなかったグループを示します。結果
キー
型
値
statusstr
下の ステータス を参照してください。
committedbool
statusが"committed"のときだけTrue。dry_runbool
dry_run引数。pm_uidstr
pm_uid引数。beforedict
呼び出し前の
read_pm()["property"]。afterdict
呼び出し後の
read_pm()["property"]。何も書き込まなければbeforeと同じです。candidatedict or None
保存する定義。
storage、property_id、property_id_lockedを含みます。 変更が拒否されたときはNone。changed_fieldslist[str]
beforeとafterで値が異なる項目名。dry run のあとは空です。groupslist[dict]
実行したグループごとに 1 要素:
groupとstatus("committed"、"rejected"、"restored_failure"、"unknown"のいずれか)。dry run のあとは空です。pendinglist[str]
実行が必要で、実行されなかったグループ。dry run のあとは、実行されるはずのグループ。
registrationdict or None
definitionグループが実行されたときに設定されます。下の 登録 を参照してください。storageとproperty_idのグループも Property を登録します。どのグループのあとでも、after["storage"]とafter["registered_property_id"]が、登録先と登録名を示します。recoverydict or None
グループが失敗したあとに設定されます:
scope(そのグループ) とsaved_definition_matches。diagnosticslist[dict]
問題ごとに 1 要素:
code、field(またはfields)、messageと、診断 に挙げる詳細。警告にはseverity: "warning"も付きます。登録
キー
型
値
statusstr
"committed"、"failed"、または Property が無効の間は"not_applicable"。registered_property_idstr
Property が登録された名前。登録されていないときは空です。
reason_codestr
成功時は空。無効な Property では
property_disabled。 それ以外では失敗した段階のコード (host_registration_failedなど)。failed_stagestr
成功時は空。それ以外では失敗した段階:
validate、claim、resolve_owner、prepare_metadata、inspect_native、migrate、migrate_native、prepare_cleanup、register_new、commit_ownership、publish、commit_metadataのいずれか。blocked_ownerstr
保存値の移動を妨げたデータブロック (
Object 'Cube'など)。 それ以外では空です。ステータス
共通の語彙は ステータスの値 にあります。
status意味
committed実行が必要なすべてのグループが保存されました。
validateddry_run=Trueで、変更を受け付けられます。何も書き込んでいません。unchanged変更が保存されている Property と一致します。何も書き込んでいません。 dry run でも返ります。
rejected保存されている Property は変わっていません。
diagnosticsが原因を示します。 原因は検査、または最初に実行したグループの失敗です。partial先のグループが確定したあとで、グループが失敗しました。先のグループは保存されたままです。
pendingが実行されなかったグループを示します。restored_failureBlender が保存した定義の登録を拒否し、保存した定義を元に戻しました。
unknown失敗したグループが保存されている Property を変えたまま残したか、 復元を確認できませんでした。
recovery["scope"]がそのグループを示します。 再試行の前にread_pm()を呼んでください。診断
拒否: 最初の書き込みの前に検査します。ステータスは
rejectedです。 警告: ステータスに影響しません。グループ: 書き込み中にグループが失敗しました。code影響
原因と追加のキー
stale_property拒否
expected_digestが保存されている digest と異なります。fieldは"digest"です。field_not_applicable拒否
項目が変更後の型に該当しない、または ID の保存先に
restore_defaultが指定されています。default_type_mismatch拒否
defaultの型が違う、またはベクトルで長さが違います。default_not_in_items拒否
指定した、または保持した
defaultが、項目にない識別子を指しています。missingがそれらを列挙します。argument_type_mismatch拒否
min、max、stepが整数 (INT) または有限の数 (FLOAT) ではない、 またはprecisionが整数ではありません。argument_out_of_range拒否
precisionが 0〜6 の範囲外の整数。INT のdefault、min、max、stepが 32 bit の範囲 (-2147483648〜2147483647) 外の整数。または FLOAT のdefault、min、max、stepが 32 bit float の範囲 (約 ±3.4028235e38) 外の有限の数で、 Blender が無限大として登録してしまう値。fieldがその項目を示します。argument_not_a_choice拒否
subtypeまたはunitが、その型とサイズで受け付けられない値です。choicesが受け付ける値を列挙します。min_greater_than_max拒否
結果の
minがmaxより大きくなります。minとmaxが両方の値を示します。もう一方の境界値を読めない場合は検査しません。multiselect_item_limit拒否
Multi-Select の Enum が 31 項目を超えます。
limitとcountが数を示します。item_identifier_invalid拒否
識別子が空、または空白や
|を含みます。indexが項目を示します。item_identifier_duplicate拒否
識別子が前の識別子と重複しています。
indexが項目を示します。item_identifier_reserved拒否
識別子が予約された名前です (Enum 項目 に記載)。
indexが項目を示します。item_name_invalid拒否
名前が
|を含みます。indexが項目を示します。item_uid_duplicate拒否
2 つの項目が同じ
uidを指定しています。item_uid_unknown拒否
uidがこの Property の項目ではありません。uidsがそれらを列挙します。set_requires_get拒否
結果が Getter のない Setter になります。
argument_unreadable_would_be_replaced拒否
リテラルではない保存済みの引数が、呼び出しで指定していない値に置き換わります。
textに保存されたテキストが入ります。その引数を明示的に渡すと置き換えます。storage_type_unknown拒否
storageが Blender の ID 型名ではありません。empty、too_long、invalid_identifier、non_ascii、python_keyword、reserved_access_name拒否
Property ID が空、63 バイトより長い、ASCII 英字で始まり英数字と
_が続く形ではない、非 ASCII、Python のキーワード、またはkeys、values、items、getのいずれかです。property_idまたはstorageが変わるときに検査します。owner_reserved拒否
移動先の保存先に、その名前の属性がすでにあります (Blender のプロパティや、 別の Property が登録したプロパティなど)。
manual_prop_id_collision拒否
同じ保存先の別の Property が、その Property ID を保存しています。
reserved拒否
Property ID がほかの理由で予約されています。
callback_compile_error警告
指定したコールバックに構文エラーがあります。エディターと同じく保存されます。
argument_unreadable警告
リテラルではない保存済みの引数が保持されます。
textに保存されたテキストが入ります。property_readback_differs警告
確定後、保存されている Property が
candidateと異なります。fieldsが項目名を列挙します。storage_registration_failedグループ
保存先グループが受け付けられませんでした。
messageはエディターの報告をつなげたものです。Property ID 段階のコード
グループ
property_idグループが受け付けられませんでした。codeは上の Property ID のコード、runtime_prop_id_register_failed、または登録のreason_codeです。effect_codesが実行した段階を列挙します。definition_registration_failedグループ
Blender が保存した定義の登録を拒否しました。
registrationに詳細が入ります。例
新しい Property を、長さの単位を持つ 0〜1 の Float にします。
created = pme.create_pm(pme.PmCreationSpec("PROPERTY", name="Bevel Width")) before = pme.editing.read_pm(created.pm_uid)["property"] result = pme.editing.update_property( created.pm_uid, {"type": "FLOAT", "default": 0.1, "min": 0.0, "max": 1.0, "unit": "LENGTH"}, expected_digest=before["digest"], ) assert result["status"] == "committed", result["diagnostics"]
補足
storageが変わるとき、要求された、または保持される Property ID を、 移動先の保存先で検査します。検証、保存、読み取りのいずれもコールバックを実行しません。On Init も実行されません。
保存値は通常の登録の規則に従います。エディターと同じく、
typeやsizeを変えると保存値は破棄されます。失敗後に保存値は復元されません。確定したグループ、または
unknownで終わったグループは、read_pm()["version"]を 1 増やします。選択中のメニューと、編集中の下書きは変わりません。
定義グループの保存中に発生した例外は、保存した定義を復元したあとで再送出されます。 その注記に、復元を確認できたかどうかが記されます。再試行の前に
read_pm()を呼んでください。この呼び出しは、Preferences のディスクへの保存、Undo ステップの追加、 Property の表示を行いません。