TextBox

class psychopy.visual.TextBox(window=None, text='Default Test Text.',
    font_name=None, bold=False, italic=False, font_size=32,
    font_color=(0, 0, 0, 1), dpi=72, line_spacing=0,
    line_spacing_units='pix', background_color=None, border_color=None,
    border_stroke_width=1, size=None, textgrid_shape=None,
    pos=(0.0, 0.0), align_horz='center', align_vert='center', units='norm',
    grid_color=None, grid_stroke_width=1, color_space='rgb', opacity=1.0,
    grid_horz_justification='left', grid_vert_justification='top',
    autoLog=True, interpolate=False, name=None)

TextStimと同様にウィンドウに文字を描画するために使用する。TextStimとTextBoxにはそれぞれ長所と短所があり、実験での用途に応じて使い分ける必要がある。

注：バージョン1.79で正式に追加されたが、まだ開発段階だと考えておいてほしい。二つのTextBoxのデモはPsychoPyがサポートするすべてのOS上で動作することが確認されているが、TextBoxのコードにはまだバグが含まれている可能性は高い。また、TextBoxのAPIは今後数か月のうちにさらに強化され、改善されていく可能性が高い。(訳注：この「数か月」というのはPsychoPy 1.79がリリースされた時点の話と思われる)

  • TextBoxでは各文字の配置方法が明確に定義されており、各文字の正確な位置を把握する必要がある実験で便利である。
  • 表示するテキストの変更と表示は(TextStimと比べて)非常に高速に行われる。
  • 組み込みのフォントマネージャー：使用しているPCで利用できるフォントのファミリーとスタイルへの簡単なアクセスを提供する。

TextBoxは以下のグラフィック要素を含む複合的な刺激である。

  • TextBox Border / Outline
  • TextBox Fill Area
  • Text Grid Cell Lines
  • Text Glyphs

TextBoxのそれぞれのグラフィック要素の属性を変更してTextBoxの見た目の様々な側面を制御することができる。

色空間に’rgb’および’rgb255’を使用しているときには、色は要素数3のシーケンス(赤、緑、青)または要素数4のシーケンス(赤、緑、青、アルファ)を指定できる。これによって、TextBoxの個々の要素に別々の色と透明度を設定できる。アルファチャネルを含む色を指定した場合は、TextBox全体に適用されたopacityより優先される。アルファチャネルを含まない色を指定された要素は通常通りopacityの設定に従う。

テキストの行間を設定することができる。等幅のフォントのみがサポートされる。

TextBoxは標準的なPsychoPyの視覚刺激と以下の点で根本的に異なる。

  • TextBoxの属性に直接的にアクセスすることはできない。get*, set*メソッドを常に使用する必要がある(この制限は将来的に解消される予定である)。
  • TextBoxの属性は置き換えるのみであり、演算子を適用することはできない。
  • 他のPsychoPyの刺激でサポートされるキーワード引数は、(TextStimでサポートされるものも含めて)TextBoxではサポートされない。TextBoxクラスの定義における引数を参照のこと。

新しいフォントスタイルおよびサイズを使用するときにはフォントの読み込みに1秒程度の時間を要する。この遅延はフォント名、スタイルおよびサイズの組み合わせにつき一回きりで、一度読み込まれた後は、同じフォントスタイルが複数のTextBoxで繰り返し使用されても遅延はほとんど生じない。

autoLogおよびautoDrawは現在はサポートされていない。

項目 TextBox TextStim
テキストの変更と再描画 1.513 msec 28.537 msec
テキスト変更せず再描画 0.240 msec 0.931 msec
オブジェクトの生成 0.927 msec 0.194 msec
等幅フォントのサポート Yes Yes
プロポーショナルフォントのサポート No Yes
改行幅の調整 Yes No
正確な文字位置の情報 Yes No
回転のサポート No Yes
折り返しのサポート Yes Yes

デモスクリプトがPsychoPyと一緒に配布されている。結果はテキストの長さ、ビデオカード、OSに依存する。上記の結果は平均24語、120文字の文字列の結果である。使用したPCはWindows 7 64bit、PsychoPy 1.79、Core i7 3.4GHz CPU、nVidia 480GTX 2GBグラフィックカードである。

(訳注：コードは省略)

draw()

TextBoxをグラフィックカードのバックバッファに書き込む。書き込み後にflip()を行うことによって画面上に表示される。flip()より前にdraw()が呼び出されなければ画面上には表示されない。

getAutoLog()

autoLogの設定を返す。現在のTextBoxではサポートされていない。

getBackgroundColor()

TextBoxの背景部分の長方形を塗りつぶす色を返す。TextBoxの他の要素はすべてこの長方形の上に描かれる。

getBorderColor()

TextBoxでは周囲に枠を描くことができる。このメソッドは枠の色を返す。

getBorderWidth()

TextBoxの枠線の幅を返す。単位は常にpixである。

getColorSpace()

TextBoxに設定された色空間を返す。以下の値がサポートされている。

  • ‘rgb’
  • ‘rbg255’
  • ‘norm’
  • hex (implicit)
  • html name (implicit)

(訳注：normは間違いと思われる。また、dklなどのPsychoPyがさぽーとするrgb, rgb255以外の色空間もサポートしている)

getDisplayedText()

TextBox内のテキストを返す。すなわち、実際に画面上に描画されているテキストを返す。これは以下の処理と同様である。

text_length=len(self.getText()) cols,rows=self.getTextGridShape()
displayed_text=self.getText()[0:min(text_length,rows*cols)]

(訳注：コードが一部間違っていると思われるので修正した。)

getFontColor()

テキストのグリフを描画する時に用いる色を返す。

getGlyphPositionForTextIndex(char_index)

char_indexに現在表示されているテキスト( getDisplayedText() )のいずれか1文字のインデックスを指定すると、指定された文字のバウンディングボックス(文字をぴったり囲む長方形)の画面上での位置、幅、高さを返す。 このメソッドはテキストグリッドのセル内におけるグリフの位置を考慮するので、戻り値はテキストグリッドのセルの位置ではなく正確にグリフの位置である。 テキストグリッドのセルの位置情報についてはgetTextGridCellPlacement()メソッド参照のこと。

グリフの位置は(x, y, width, height)というタプルで返される。xとyはバウンディングボックスの左上の座標である。

補足：

  • char_indexが現在表示されているテキストの範囲を超えている(20文字しか表示されていないのに30番目の文字を指定した場合など)ときはNoneが返される。
  • u’ ‘ (スペース) 文字の場合は、テキストグリッドのセル全体が返される。
  • u’ ‘ (改行) 文字の場合はバウンディングボックスは返されるが、ボックスの幅は0となる。

getHorzAlign()

TextBoxの座標値がTextBoxのどの位置を指すかを返す。’left’, ‘center’, ‘right’のいずれかである。

getHorzJust()

一行の文字数がTextBoxの列数より少ないときに、その行の文字をどのように配置するように設定しているかを返す。

getInterpolated()

TextBoxの描画時に補間が有効にされているかを返す。TrueであればGL_LINE_SMOOTHとGL_POLYGON_SMOOTHが有効である。

getLabel()

TextBoxに割り当てられたラベルを返す。これは刺激の描画には影響せず、内部処理にのみ利用される。

getLineSpacing()

テキストの各行の間に追加されるスペースを返す。単位はgetUnits()メソッドで返される単位に従う。

(訳注：getUnitType()の間違い？)

getName()

getLabelメソッドと同じである。

getOpacity()

TextBoxオブジェクトに現在設定されている標準の不透明度を返す。0.0が完全な透明で、1.0が完全に不透明である。

getPosition()

TextBoxの位置(x, y)を返す。単位はgetUnitType()で返される単位に従う。

getSize()

TextBoxの幅と高さを返す。単位はTextBoxに設定されている単位に従う。

getText()

表示するテキストを返す。

getTextGridCellForCharIndex(char_index)

(解説なし)

getTextGridCellPlacement()

TextBoxのテキストグリッドの情報を表す3次元のnumpyの行列(array)を返す。この行列のshape属性は(num_cols,num_rows,cell_bounds)で、num_colsはTextBoxのテキストグリッドの列数、num_rowsは行数である。cell_boundsはセルの(x座標, y座標, 幅, 高さ)の形式で各セルの情報をまとめた行列である。座標は各セルの左上を表す。行と列のインデックスは0から始まる。

テキストグリッドの行数および列数を得るには以下のようにする。

cell_pos_array=textbox.getTextGridCellPlacement()
col_row_count=cell_pos_array.shape[:2]

0行0列目(すなわち左上のセル)のセルの座標、幅、高さにアクセスするには以下のようにする。

cell00=cell_pos_array[0,0,:]

1行目、3列目のセル(インデックスは0から始まるので最初の行を1行目とする数え方で2番目の行の4番目の列に相当)にアクセスするには以下のようにする。

cell41=cell_pos_array[4,1,:]

getTextGridLineColor()

テキストグリッドの枠線を描画する色を返す。TextBoxの個々の文字はテキストグリッドのいずれかのセルに入る。色の値はTextBoxに設定された色空間で適切なものでなければならない。

Noneはテキストグリッドの枠線が非常時であることを示している。

getTextGridLineWidth()

テキストグリッドのセルの周辺に引く枠線の太さを返す。

getUnitType()

TextBoxが使用している単位を返す。位置や大きさはこの単位を用いて指定しなければならない。

getValidStrokeWidths()

グラフィックカードでサポートされている線幅の範囲を返す。TextBoxで補間が用いられていれば((最小の線幅, 最大の線幅), 線幅の粒度)を返す。補間が無効な場合は(最小の線幅, 最大の線幅)を返す。

getVertAlign()

TextBoxのY座標がどの位置を指しているかを返す。’top’, ‘center’, ‘bottom’のいずれかである。

テキストを表示するために必要な行数が現在のTextBoxの行数より多い時の動作を返す。

getWindow()

TextBoxに割り当てられているPsychoPyのウィンドウを返す。

setAutoLog(v)

autoLogを設定する。現在のTextBoxではサポートされていない。

setBackgroundColor(c)

TextBoxの背景部分の長方形を塗りつぶす色を設定する。TextBoxに設定された色空間で妥当な値でなければならない。Noneを設定すると背景を塗りつぶさない。

setBorderColor(c)

TextBoxの枠線の色を設定する。TextBoxに設定された色空間で妥当な値でなければならない。Noneを設定すると枠線を描画しない。

setBorderWidth(c)

TextBoxの枠線の幅をpix単位で指定する。値はグラフィックカードのOpenGLドライバによってサポートされる範囲内でなければならない。範囲外の値を指定した場合は範囲内で最も近い値で描画される。線の最小、最大幅を取得するにはgetValidStrokeWidths()を使用するとよい。

setFontColor(c)

TextBox内のフォントグリフを描画する際に使用する色を指定する。TextBoxに設定された色空間で妥当な値でなければならない。’rgb’と’rgb255’色空間の場合は3または4要素のシーケンスを指定できる。3要素の場合は不透明度はgetOpacity()で得られる値が用いられる。4要素の場合は第4の値がアルファ値として用いられる。

setHorzAlign(v)

X座標の値がTextBoxのどの位置に対応するかを指定する。’left’ならば左端、’right’ならば右端、’center’ならば中心である。

setHorzJust(v)

TextBox内でテキストがどのように揃えられるかを指定する。例えばTextBoxのテキストグリッドが10列(=1行が10文字)でテキストが6文字の時、左寄せで表示したければ’left’、中央寄せで表示したければ’center’(この例の場合、左右に2文字分ずつ空白ができる)、右寄せで表示したければ’right’を指定する。

setInterpolated(interpolate)

TextBoxの描画時に補間を有効にするかを設定する。TrueにすればGL_LINE_SMOOTHとGL_POLYGON_SMOOTHが有効となる。Falseにすればこれらは無効となる。

setOpacity(o)

TextBoxの不透明度を設定する。0.0なら完全な透明、1.0なら完全な不透明である。Noneを指定した場合は1.0と解釈される。

色が４次元の値で指定されている場合はこの設定は無視される。

setPosition(pos)

TextBoxの位置(x, y)を設定する。TextBoxに設定された単位に従う。

TextBoxの位置はhorzAlignmentとvertAlignmentの設定に従って決定される。詳しくはgetHorzAlignment()とgetVertAlignment()を参照のこと。

setText(text_source)

TextBoxに表示するテキストを指定する。

TextBoxの行数と列数は作成時に決定され、その後は変更されない点に注意。行数、列数を変更するには新たなTextBoxを作成しなければならない。したがって、TextBoxを作成する際に表示する予定のテキストのなかで最長のものを表示できる大きさを確保するようにすること。テキストのTextBoxからはみ出た部分は表示されない。

setTextGridLineColor(c)

テキストグリッドの線を引く際の色を指定する。これはテキストグリッド内の個々の文字のバウンディングボックスを示す線である。TextBoxに設定された色空間で妥当な値でなければならない。Noneを指定すると線を描画しない。

setTextGridLineWidth(c)

テキストグリッドのバウンディングボックスの枠線の幅をpixで指定する。値はグラフィックカードのOpenGLドライバによってサポートされる範囲内でなければならない。範囲外の値を指定した場合は範囲内で最も近い値で描画される。線の最小、最大幅および粒度を含むOpenGLのパラメータの辞書オブジェクトを得るにはgetGLineRanges()を用いる。

(訳注：getValidStrokeWidths()の間違い？)

setVertAlign(v)

Y座標の値がTextBoxのどの位置に対応するかを指定する。’top’ならば上端、’bottom’ならば下端、’center’ならば中心である。

setVertJust(v)

TextBox内でテキストがどのように揃えられるかを指定する。例えばTextBoxのテキストグリッドが3行でテキストが1行で表示できる長さだとする。上寄せで表示したければ’top’、中央寄せで表示したければ’center’(3行のうち2番目の行に表示される)、下寄せで表示したければ’bottom’を指定する。