DmDX help, Instruction Keyword

DMDX Help.

Instruction Keyword

<Instruction N₁,N₂,N₃ [options]>
<inst N₁,N₂,N₃ [options]>

variants:
<Instruction command>
<inst command>

options:
right2left
hardmargin

commands:
newline
nl
escape
esc
nowrap

Switch and parameter (as of 5.3.1.6) to turn on automatic formatting so people don't have to guess where line breaks in paragraphs of text should occur. When <inst> is used as a parameter only the options have any effect and when used they set that option globally for the whole item file (there is no way to override them once invoked in the parameters). N₁,N₂,N₃ specify the left, top and right coordinates of a bounding rectangle on the screen in the same fashion as other on screen rectangles are defined in DMDX (see <graphic>) with the exception that the bottom coordinate (if specified) will be ignored. Words in an item that this keyword occurs in (note there's no correlation between item number zero instructions and the <inst> keyword although they are likely to both be used in the same item) are specified in a word per frame sequence "like ", "this ", "where ", "each ", "word ", "is ", "frame ", "delimited " with a following space and DMDX automatically starts positioning frames at N₁,N₂ and adds the width of the previous frames across the screen and inserts line breaks when the word crosses the right coordinate (N₃) or in the case of the hardmargin option (as of version 5.3.1.4) being used the new line comes before the word crosses the right coordinate. The newline (nl) command forces a new line at the end of the frame they occur in (so the next frame will be drawn at the left edge of the bounding rectangle) and the escape (esc) command escapes the frame it occurs in from <inst> positioning allowing <xy> for example to be used. The nowrap command added in version 6.1.6.0 of DMDX is not intended for experimenters to use (if you don't want something to wrap keep it all in one frame), instead it is provided for internal use with the <prose> keyword (it's used to stop the cursor wrapping to the next line ahead where the subject is typing). The right2left option is for use with fonts like Hebrew where words start at the right margin and progress leftwards (use of <XYJustification RIGHTTOP> being all but mandatory, see note below). The right2left option also makes changes to the way <prose> operates, reversing the right and left arrows and making the text it emits contain \rtlch RTF control codes (the latter being necessary to get the punctuation marks on the left of the words). If <inst right2left> has been used in the parameters it also affects the progressive X keyword.

While this format looks intimidating it's actually pretty easy to use as all you have to do is type your instructions normally and then in Word for instance you can highlight that section and then replace all the spaces in that section with [space]",[space]" and not let it then continue on replacing all the spaces in the rest of the file -- you will probably want to go back and replace double space leadins to full stops (should you use them) as those single space frames can wind up being the first frame on a new line and thus be indented a bit which doesn't look good

The difference between using the hardmargin option and not is subtle but significant. Without it you have to set your right margin far enough to the left that the longest word in your instructions won't extend beyond the right edge of the screen and there are times this can be difficult to do whereas using hardmargin you're going to set your right margin much closer to the right edge of the screen and not have to worry about a word ever getting close to the right edge of the screen unless it's as wide as the whole screen and that's pretty easy to guard against. I don't see a reason not to use it, the only reason it's not the default is that I must leave DMDX operating the way it did in the past so as to not break people's old item files.

<XYJustification LEFTBOTTOM> is a useful keyword to use with <inst> if more than one font or bitmaps are to be included in the item as it will line up the bottoms of the frames up instead of the tops as the default justification would (you'll want to make sure the top coordinate is a bit lower on the screen as that will be the bottom of the first line of instructions). Note that in order to get the base lines of the fonts to line up you're probably going to have to include spaces in the smaller font frames that are in the larger font size. Large bitmaps might be kind of entertaining but hey. Also, note that while <XYJustification LEFTBOTTOM> and <XYJustification LEFTTOP> work with <inst> <XYJustification CENTER> is positively toxic (same probably goes for <XYJustification RIGHTBOTTOM> unless you're using a right to left font). So if you're using <XYJustification CENTER> to position bitmaps nicely you're going to have to toggle back to <XYJustification LEFTTOP> or <XYJustification LEFTBOTTOM> for <inst> use. And then of course if you're using <inst esc> to position bitmaps then you'll have to be doing that toggling in the item from frame to frame as conditions change -- except of course that <xyjustification> was a global per item attribute and you couldn't change it multiple times per item (only the last one will be used) until I rectified that in version 5.2.1.2. You'll have to turn on the frame by frame MDSP option with <xyjustification framebyframe> but having done so you can have item files like this that display a centered image for the subject to type about:

f1 <vm desktop> <id keyboard> <nfb> <cr> <xyjustification framebyframe>
~77 ma++ mb++ mc++ md++ <mpr +enter>;
+1 <inst .2,.5,.82 hardmargin> <delay 2> <inst esc> <xyjustification center> <xy .5,.25> <bmp> "DMDXICO.BMP" , <xyjustification lefttop> "Please type the name: ", <ln 3> ~c, "|", ~d <prose a,b,c,d> <mwb +enter,77 bu,-1>;
~77 etc... ;

Note that while the coordinates are all technically optional you're really going to need to specify the right N₃ coordinate otherwise words will be truncated by the edge of the screen. Also note that once the coordinate specifying form of this keyword occurs in an item it's active for the whole item, there's no way to have two different rectangles of text in one item and it is only possible to have a frame not subject to <inst>'s formatting by including <inst esc> in it. Even if the <inst> is in the last frame of the item all frames before it not escaped will still be affected. And you really shouldn't be using things like feedback or more specifically <ZillionTypedResponses> to gather responses as <inst> will be interfering with all that text formatting too (although the <prose> keyword used above is designed to work with <inst>). If you need to combine them do so in separate items and continue from the first to the second and have the second not erase the screen from the first item (along with the usual <fbocb> to not erase stuff as typing is happening and so on):

<ep> <vm desktop> <zil> <ztr> <ntl> <cr> <fbocb> <eop>
0 <inst .1,.1,.92 hardmargin> "complicated ", "instructions ", "for ", "typing ", "in ", "the ", "following ", "item" c;
+1 ! "Type:" * ;

There are several rather unobvious features to using right to left fonts in DMDX. prior to version 4.3.0.0 While the GDI portion of Windows that actually renders text in DMDX is aware of right to left fonts and will reverse the letter order so the display renders correctly it can only do that for individual requests and when there are font changes or formatting changes DMDX must make multiple requests for a given frame to be rendered. For example say the following was actually in a right to left font "right to left" with no formatting it's one request from DMDX and GDI will in fact render "tfel ot htgir". However if we say bold the "to" it's now three requests and in versions of DMDX prior to 4.3.0.0 we'd get "htgir ot tfel". Worse, when you go back and edit something in Word even though the formatting is uniform across the string Word will render it in two sections so DMDX's rendering would be faulty. To save the end user from these problems I modified DMDX in version 4.3.0.0 to parse the right to left codes in the RTF and so on. Prior to that to get around this the right2left option was added so the following can be used:

0 <xyjustification RIGHTTOP> <inst .08,.4,.9 hardmargin right2left> "right ", "to ", " left";

Note that if you edit either of those three words (in Word at least) the word will be scrambled when DMDX renders it in versions prior to 4.3.0.0. The solution in the past was to just retype the word from scratch in one edit, these days you're just going to use a non-ancient version of DMDX...

Should you be faced with having to make an item file with copious amounts of instructions that works on both a 16:9 widescreen display and 4:3 standard displays as I was when I was crafting the introduction you can detect which display you're running on using the VideoModeX and VideoModeY tokens added in version 5.3.1.2 in the counter expression evaluator and use a larger or smaller bounding rectangle with the help of a macro or two (one is all that's needed but for clarity I use two here):

~1 mx+.1+ my+.15+ <bi 3, ((videomodex * 10) / videomodey) .GT. 14>;
~1 mx+.02+ my+.07+; ! use more of the screen when 4:3;
~3 <dfm .8>;

0 <inst ~x, ~y, .92 hardmargin> <xyjustification leftbottom>
"Lorem ", "ipsum ", "dolor ", "sit ", "amet, ", "ne ", "ubique ", "ridens ", "voluptaria ", "his, ", "in ", "augue ", "debet ", "facilisi ", "duo. ", "Oratio ", "assentior ", "sea ", "no, ", "eu ", "docendi ", "fastidii ", "iudicabit ", "mei. ", "Suas ", "rationibus ", "efficiendi ", "in ", "mei. ", "Vel ", "sonet ", "elitr ", "deleniti ", "an.", <inst nl>, <inst nl>,

"Lorem ", "ipsum ", "dolor ", "sit ", "amet, ", "ne ", "ubique ", "ridens ", "voluptaria ", "his, ", "in ", "augue ", "debet ", "facilisi ", "duo. ", "Oratio ", "assentior ", "sea ", "no, ", "eu ", "docendi ", "fastidii ", "iudicabit ", "mei. ", "Suas ", "rationibus ", "efficiendi ", "in ", "mei. ", "Vel ", "sonet ", "elitr ", "deleniti ", "an.", <inst nl>, <inst nl>,

<inst esc> "Hit the space bar to continue..." @12;

DMDX Index.