TextBox
================================

.. code-block:: python

    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がリリースされた時点の話と思われる)

.. NOTE: As of PsychoPy 1.79, TextBox should be considered experimental. The two TextBox demo scripts provided have been tested on all PsychoPy supported OS's and run without exceptions. However there are very likely bugs in the existing TextBox code and the TextBox API will be further enhanced and improved (i.e. changed) over the next couple months.

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

.. Text character placement is very well defined, useful when the exact positioning of each letter needs to be known.
.. The text string that is displayed can be changed ( setText() ) and drawn ( win.draw() ) very quickly. See the TextBox vs. TextStim comparison table for details.
.. Built-in font manager; providing easy access to the font family names and styles that are available on the computer being used.

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

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

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

.. Attributes for each of the TextBox graphical elements can be changed to control many aspects of how the TextBox is displayed.

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

.. When using 'rgb' or 'rgb255' color spaces, colors can be specified as a list/tuple of 3 elements (red, green, blue), or with four elements (reg, green, blue, alpha) which allows different elements of the TextBox to use different opacity settings if desired. For colors that include the alpha channel value, it will be applied instead of the opacity setting of the TextBox, effectively overriding the stimulus defined opacity for that part of the textbox graphics. Colors that do not include an alpha channel use the opacity setting as normal.

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

.. Text Line Spacing can be controlled.
.. Only Monospace Fonts are supported.

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

.. TextBox component is not a completely standard psychopy visual stim and has the following functional difference:

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

.. TextBox attributes are never accessed directly; get* and set* methods are always used (this will be changed to use class properies in the future).
.. Setting an attribute of a TextBox only supports value replacement, ( textbox.setFontColor([1.0,1.0,1.0]) ) and does not support specifying operators.
.. Some key word arguments supported by other stimulus types in general, or by TextStim itself, are not supported by TextBox. See the TextBox class definition for the arguments that are supported.

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

.. When a new font, style, and size are used it takes about 1 second to load and process the font. This is a one time delay for a given font name, style, and size. After first being loaded, the same font style can be used or re-applied to multiple TextBox components with no significant delay.

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

.. Auto logging or auto drawing is not currently supported.

================================== ========== ==============
é …ç›®                               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
================================== ========== ==============

.. Feature 	TextBox 	TextStim
.. Change text + redraw time^ 	1.513 msec 	28.537 msec
.. No change + redraw time^ 	0.240 msec 	0.931 msec
.. Initial Creation time^ 	0.927 msec 	0.194 msec
.. MonoSpace Font Support 	Yes 	Yes
.. Non MonoSpace Font Support 	No 	Yes
.. Adjustable Line Spacing 	Yes 	No
.. Precise Text Pos. Info 	Yes 	No
.. Auto logging Support 	No 	Yes
.. Rotation Support 	No 	Yes
.. Word Wrapping Support 	Yes 	Yes

.. ^ Times are in msec.usec format. Tested using the textstim_vs_textbox.py

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

(訳注：コードは省略)

.. demo script provided with the PsychoPy distribution. Results are dependent on text length, video card, and OS. Displayed results are based on 120 character string with an average of 24 words. Test computer used Windows 7 64 bit, PsychoPy 1.79, with a i7 3.4 Ghz CPU, 8 GB RAM, and NVIDIA 480 GTX 2GB graphics card.

..    from psychopy import visual
..    win=visual.Window((....)

..    # A Textbox stim that will look similar to a TextStim component #

..    textstimlike=visual.TextBox(
..        window=win, text="This textbox looks most like a textstim.",
..        font_size=18, font_color=[-1,-1,1], color_space='rgb',
..        size=(1.8,.1), pos=(0.0,.5), units='norm')

..    # A Textbox stim that uses more of the supported graphical features #

..    textboxloaded=visual.TextBox(
..        window=win text='TextBox showing all supported graphical elements',
..        font_size=32, font_color=[1,1,1], 
..        border_color=[-1,-1,1], # draw a blue border around stim
..        border_stroke_width=4, # border width of 4 pix.
..        background_color=[-1,-1,-1], # fill the stim background
..        grid_color=[1,-1,-1,0.5], # draw a red line around each
..                      # possible letter area, # 50% transparent
..        grid_stroke_width=1, # with a width of 1 pix
..        textgrid_shape=[20,2], # specify area of text box
..            # by the number of cols x
..            # number of rows of text to support
..            # instead of by a screen # units width x height.
..        pos=(0.0,-.5), # If the text string length < num rows * num cols in # textgrid_shape, how should text be justified? # grid_horz_justification='center', grid_vert_justification='center', )

..    textstimlike.draw() textboxloaded.draw() win.flip()

draw()
---------------------------------------

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

.. Draws the TextBox to the back buffer of the graphics card. Then call win.flip() to display the changes drawn. If draw() is not called prior to a call to win.flip(), the textBox will not be displayed for that retrace.

getAutoLog()
--------------------------------------

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

.. Indicates if changes to textBox attribute values should be logged automatically by PsychoPy. *Currently not supported by TextBox.

getBackgroundColor()
-----------------------

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

.. Get the color used to fill the rectangular area of the TextBox stim. All other graphical elements of the TextBox are drawn on top of the background.

getBorderColor()
-----------------------

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

.. A border can be drawn around the perimeter of the TextBox. This method sets the color of that border.

getBorderWidth()
-------------------------

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

.. Get the stroke width of the optional TextBox area outline. This is always given in pixel units.

getColorSpace()
--------------------------

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

- 'rgb'
- 'rbg255'
- 'norm'
- hex (implicit)
- html name (implicit)

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

.. Returns the psychopy color space used when specifying colors for the TextBox. Supported values are:
.. 'rgb'
.. 'rbg255'
.. 'norm'
.. hex (implicit)
.. html name (implicit)
.. See the Color Space section of the PsychoPy docs for details.

getDisplayedText()
-------------------------

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

.. Return the text that fits within the TextBox and therefore is actually seen. This is equal to:

.. code-block:: python

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

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


getFontColor()
-------------------------------

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

.. Return the color used when drawing text glyphs.

getGlyphPositionForTextIndex(char_index)
-----------------------------------------------

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

.. For the provided char_index, which is the index of one chatacter in the current text being displayed by the TextBox ( getDisplayedText() ), return the bounding box position, width, and height for the associated glyph drawn to the screen. This factors in the glyphs position within the textgrid cell it is being drawn in, so the returned bounding box is for the actual glyph itself, not the textgrid cell. For textgrid cell placement information, see the getTextGridCellPlacement() method.

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

補足：

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

.. The glyph position for the given text index is returned as a tuple (x,y,width,height), where x,y is the top left hand corner of the bounding box.

.. Special Cases:

.. If the index provided is out of bounds for the currently displayed text, None is returned.
.. For u' ' (space) characters, the full textgrid cell bounding box is returned.
.. For u' ' ( new line ) characters,the textgrid cell bounding box is returned, but with the box width set to 0.

getHorzAlign()
-----------------------

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

.. Return what textbox x position should be interpreted as. Valid options are 'left', 'center', or 'right' .

getHorzJust()
----------------------------

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

.. Return how text should laid out horizontally when the number of columns of each text grid row is greater than the number needed to display the text for that text row.

getInterpolated()
----------------------------

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

.. Returns whether interpolation is enabled for the TextBox when it is drawn. When True, GL_LINE_SMOOTH and GL_POLYGON_SMOOTH are enabled within OpenGL; otherwise they are disabled.

getLabel()
-----------------------

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

.. Return the label / name assigned to the textbox. This does not impact how the stimulus looks when drawn, and instead is used for internal purposes only.

getLineSpacing()
-------------------------

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

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

.. Return the additional spacing being applied between rows of text. The value is in units specified by the textbox getUnits() method.

getName()
---------------------

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

.. Same as the GetLabel method.

getOpacity()
-----------------------

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

.. Get the default TextBox transparency level used for color related attributes. 0.0 equals fully transparent, 1.0 equals fully opaque.

getPosition()
-----------------------

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

.. Return the x,y position of the textbox, in getUnitType() coord space.

getSize()
------------------------

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

.. Return the width,height of the TextBox, using the unit type being used by the stimulus.

getText()
----------------------

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

.. Return the text to display.

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から始まる。

.. Returns a 3d numpy array containing position information for each text grid cell in the TextBox. The array has the shape (num_cols,num_rows,cell_bounds), where num_cols is the number of textgrid columns in the TextBox. num_rows is the number of textgrid rows in the TextBox. cell_bounds is a 4 element array containing the (x pos, y pos, width, height) data for the given cell. Position fields are for the top left hand corner of the cell box. Column and Row indices start at 0.

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

.. To get the shape of the textgrid in terms of columns and rows, use:

.. code-block:: python

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

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

.. To access the position, width, and height for textgrid cell at column 0 and row 0 (so the top left cell in the textgrid):

.. code-block:: python

    cell00=cell_pos_array[0,0,:]

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

.. For the cell at col 3, row 1 (so 4th cell on second row):

.. code-block:: python

    cell41=cell_pos_array[4,1,:]

getTextGridLineColor()
-----------------------

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

.. Return the color used when drawing the outline of the text grid cells. Each letter displayed in a TextBox populates one of the text cells defined by the shape of the TextBox text grid. Color value must be valid for the color space being used by the TextBox.

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

.. A value of None indicates drawing of the textgrid lines is disabled.

getTextGridLineWidth()
-----------------------

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

.. Return the stroke width (in pixels) of the optional lines drawn around the text grid cell areas.

getUnitType()
-------------------

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

.. Returns which of the psychopy coordinate systems are used by the TextBox. Position and size related attributes mush be specified relative to the unit type being used. Valid options are:

..                pix
..                norm
..                cm

getValidStrokeWidths()
--------------------------------

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

.. Returns the stroke width range supported by the graphics card being used. If the TextBox is Interpolated, a tuple is returns using float values, with the following structure:

..         ((min_line_width, max_line_width), line_width_granularity)

.. If Interpolation is disabled for the TextBox, the returned tuple elements are int values, with the following structure:

.. (min_line_width, max_line_width)

getVertAlign()
----------------

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

.. Return what textbox y position should be interpreted as. Valid options are 'top', 'center', or 'bottom' .

.. getVertJust()

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

.. Return how text should layed out vertically when the number of text grid rows is greater than the number needed to display the current text

getWindow()
-------------------

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

.. Returns the psychopy window that the textBox is associated with.

setAutoLog(v)
-----------------------

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

.. Specify if changes to textBox attribute values should be logged automatically by PsychoPy. True enables auto logging; False disables it. *Currently not supported by TextBox.

setBackgroundColor(c)
--------------------------

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

.. Set the fill color used to fill the rectangular area of the TextBox stim. Color value must be valid for the color space being used by the TextBox.

.. A value of None will disable drawing of the TextBox background.

setBorderColor(c)
---------------------

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

.. Set the color to use for the border of the textBox. The TextBox border is a rectangular outline drawn around the edges of the TextBox stim. Color value must be valid for the color space being used by the TextBox.

.. A value of None will disable drawing of the border.

setBorderWidth(c)
-----------------------

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

.. Set the stroke width (in pixels) to use for the border of the TextBox stim. Border values must be within the range of stroke widths supported by the OpenGL driver used by the graphics. Setting the width outside the valid range will result in the stroke width being clamped to the nearest end of the valid range.

.. Use the TextBox.getValidStrokeWidths() to access the minimum - maximum range of valid line widths.

setFontColor(c)
-----------------------

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

.. Set the color to use when drawing text glyphs within the TextBox. Color value must be valid for the color space being used by the TextBox. For 'rgb', 'rgb255', and 'norm' based colors, three or four element lists are valid. Three element colors use the TextBox getOpacity() value to determine the alpha channel for the color. Four element colors use the value of the fourth element to set the alpha value for the color.

setHorzAlign(v)
------------------------

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

.. Specify how the horizontal (x) component of the TextBox position is to be interpreted. left = x position is the left edge, right = x position is the right edge x position, and center = the x position is used to center the stim horizontally.

setHorzJust(v)
--------------------

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

.. Specify how text within the TextBox should be aligned horizontally. For example, if a text grid has 10 columns, and the text being displayed is 6 characters in length, the horizontal justification determines if the text should be draw starting at the left of the text columns (left), or should be centered on the columns ('center', in this example there would be two empty text cells to the left and right of the text.), or should be drawn such that the last letter of text is drawn in the last column of the text row ('right').

setInterpolated(interpolate)
----------------------------------

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

.. Specify whether interpolation should be enabled for the TextBox when it is drawn. When interpolate == True, GL_LINE_SMOOTH and GL_POLYGON_SMOOTH are enabled within OpenGL. When interpolate is set to False, GL_POLYGON_SMOOTH and GL_LINE_SMOOTH are disabled.

setOpacity(o)
------------------------

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

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

.. Sets the TextBox transparency level to use for color related attributes of the Textbox. 0.0 equals fully transparent, 1.0 equals fully opaque.

.. If opacity is set to None, it is assumed to have a default value of 1.0.

.. When a color is defined with a 4th element in the colors element list, then this opacity value is ignored and the alpha value provided in the color itself is used for that TextGrid element instead.

setPosition(pos)
-----------------------

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

.. Set the (x,y) position of the TextBox on the Monitor. The position must be given using the unit coord type used by the stim.

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

.. The TextBox position is interpreted differently depending on the Horizontal and Vertical Alignment settings of the stim. See getHorzAlignment() and getVertAlignment() for more information.

.. For example, if the TextBox alignment is specified as left, top, then the position specifies the top left hand corner of where the stim will be drawn. An alignment of bottom,right indicates that the position value will define where the bottom right corner of the TextBox will be drawn. A horz., vert. alignment of center, center will place the center of the TextBox at pos.

setText(text_source)
------------------------

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

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

.. Set the text to be displayed within the Textbox.

.. Note that once a TextBox has been created, the number of character rows and columns is static. To change the size of a TextBox, a new TextBox stim must be created to replace the current Textbox stim. Therefore ensure that the textbox is large enough to display the largest length string to be presented in the TextBox. Characters that do not fit within the TextBox will not be displayed.

.. Color value must be valid for the color space being used by the TextBox.

setTextGridLineColor(c)
-------------------------------

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

.. Set the color used when drawing text grid lines. These are lines that can be drawn which mark the bounding box for each character within the TextBox text grid. Color value must be valid for the color space being used by the TextBox.

.. Provide a value of None to disable drawing of textgrid lines.

setTextGridLineWidth(c)
----------------------------

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

.. Set the stroke width (in pixels) to use for the text grid character bounding boxes. Border values must be within the range of stroke widths supported by the OpenGL driver used by the computer graphics card. Setting the width outside the valid range will result in the stroke width being clamped to the nearest end of the valid range.

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

.. Use the TextBox.getGLineRanges() to access a dict containing some OpenGL parameters which provide the minimum, maximum, and resolution of valid line widths.

setVertAlign(v)
------------------------

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


.. Specify how the vertical (y) component of the TextBox position is to be interpreted. top = y position is the top edge, bottom = y position is the bottom edge y position, and center = the y position is used to center the stim vertically.

setVertJust(v)
-------------------------

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

.. Specify how text within the TextBox should be aligned vertically. For example, if a text grid has 3 rows for text, and the text being displayed all fits on one row, the vertical justification determines if the text should be draw on the top row of the text grid (top), or should be centered on the rows ('center', in this example there would be one row above and below the row used to draw the text), or should be drawn on the last row of the text grid, ('bottom').