DMDX Help.


Prose Keyword

<Prose a, b, c, d>
<Prose option>

options:
utf8
utf8bom


    Switch to facilitate typed prose, also a clock on specifier, options are only valid when <Prose> is used as a parameter.  <Prose> is used in combination with branching, macros and either <ProgressiveX> or <Instruction> to gather typed text from the console.  a, b, c and d are pre-existing macro names (they should be empty before use of <prose> commences).  After <prose> has been used macros a and b are plain text suitable for emitting into the data file and macros c and d are marked up DMDX frames suitable for display in an item (they contain double quotes and frame delimiters if more than one word has been typed).  The reason there are a pair of macros for each type of data is that the first is the data before the cursor and the last the data after the cursor. 

   
<Prose>
is quite superior to either <ZillionTypedResponses> or purely macro based typing as <prose> uses Windows messages to assemble the typed text and thus knows about case and auto-repeat, neither of which is accessible with other methods.  The only keys that need to be mapped are the ones that terminate the prose typing session, all other keys are transparent as the Windows messages used to generate the typed prose are not passed through the regular DMDX input processing system (they couldn't be because there's no way ahead of time to enumerate all possible keys, a feature central to DMDX's input processing).   Instead when a Windows message comes in that affects the prose (either printable characters or editing commands) the prose handler signals that the response has been timed out and the item should branch unconditionally back to itself to display the changed prose.  Only select keys are used, excluded keys include {, } and \ (because they're reserved for the RTF syntax) and of course ; and " that are sacrosanct DMDX item delimiters.

    As of version 5.3.3.0 of DMDX there are two options that can only be used with <prose> on the parameter line and they relate to use of <prose> with DMDX's Unicode option and they affect how Unicode characters are emitted into DMDX's output data file.  The first is utf8 that makes DMDX use the UTF-8 encoding instead of whatever the active code page is on the machine and the second utf8bom that uses UTF-8 as well as making DMDX emit the UTF-8 byte order mark (BOM) at the start of the data file that some editors require in order to recognize UTF-8 being used (the BOM should be transparent but you never can tell so it's use is optional).  Note that utf8bom only affects data files started with it in effect, if you've already run a subject and saved it's data and then switch utf8bom on there will be no BOM added to the beginning of that data file.

    <Prose> requires a rather specific item file that gathers a single character of input, displays it and then loops back to gather the next one, only breaking out of the loop once it recognizes whatever character is going to end the input session.  For example this item file records a page of typed prose:

f1 <vm desktop> <id keyboard> <nfb> <cr>
~3 ma++ mb++ mc++ md++ <mpr +F12> <dfm .75>;
+1 <delay 2> <inst .1,.1,.8> "Please ", "type ", "some ", "prose ", "and ", "press ", "F12 ", "when ", "done." <inst nl>, <inst nl>, ~c, "|", ~d <prose a,b,c,d> <mwb +F12,2 bu,-1> ;
2 <emit typed text is:~a~b:> "Done";

 
    Almost all elements of that item file are essential, feedback must be disabled, it must continuously run, the macros must be set empty before each use of <prose> (otherwise (a) on first use there would be messages about uninitialized macros being used and (b) because on repeated use there's no way the prose logic can set them up before the item has been parsed when the macros expand), F12 (or other similar keys) has (have) to be used to end typing because using the Enter key is part of typing prose and <delay 2> is needed otherwise the display will lag behind the typing.  Note that item 1 has a + correct response indicator because <prose> is a clock on keyword.

    Note that we're using <emit> in item 2 to record the typed prose in the data file and that <emit> is currently limited to 500 characters of text so if you're anticipating having more than 500 characters of prose per item something will need to be done (either I modify DMDX to allow more characters or you use a font that's too big to allow more than 500 characters on the screen at once).  Also note the preamble on that <emit>, that's because if the first character after the emit keyword is a number <emit> will try and emit a counter of that number and when it doesn't find it DMDX will puke with a syntax error when a subject starts their prose with a number...

    Here I'm using a vertical bar as a cursor (one can use the arrow keys to move around the text), you could in fact put any character you liked between the ~c and ~d frames.  In fact one thing I experimented with was having the cursor flash by making the timeout 500 milliseconds or so and having a duplicate <prose> item following with only a space between the ~c and ~d frames however a space isn't the same width as a vertical bar and having the text move a few pixels with the cursor flashing was weird.  However if you did find a character the same width as a space it would work pretty well (you also have to remove the bu -1 from the first <prose> item).

    The following example instead of gathering a page of prose gathers a single line of it instead (probably more useful for remote testing, example is here):

f1 <vm desktop><id keyboard> <nfb> <cr>
~3 ma++ mb++ mc++ md++ <mpr +enter> <dfm .75>;
+1 <delay 2> @-2 <x .1> "Please type some prose and press enter when done." ,
            <px .1> ~c, "|", ~d <prose a,b,c,d> <mwb +enter,2 bu,-1> ;
2 <emit typed text is:~a~b:> "Done";


    Here even though <Prose> is marking up the text as if it was to be displayed by in an instruction item our use of <ProgressiveX> gets around that and the fact that other keys (like Enter) will cause <inst> specific flags to be set is inconsequential if <inst> itself hasn't been used.

 
    Note that if you are going to input multiple sections of prose you have to clear the macros between usages:

f1 <vm desktop> <id keyboard> <nfb> <cr>

  

~3 ma++ mb++ mc++ md++ <mpr +enter> <dfm .75>;

 +101 <delay 2>  @-2 <x .1> "Please type some prose and press enter when done." ,

            <px .1> ~c, "|", ~d <prose a,b,c,d> <mwb +enter,102 bu,-101> ;

 102 <emit typed text is:~a~b:> "Done";

 

~3 ma++ mb++ mc++ md++;

 +111 <delay 2>  @-2 <x .1> "Please type some more prose and press enter when done." ,

            <px .1> ~c, "|", ~d <prose a,b,c,d> <mwb +enter,112 bu,-111> ;

 112 <emit typed text is:~a~b:> "Done";



    When using <prose> with right to left fonts and <inst right2left> it is necessary to include at least one character before the macros in the right to left font you wish to have the typing rendered in.  While this is true to use any font other than the default one DMDX happens to be using it's more critical for these fonts:

f1 <vm desktop> <id keyboard> <nfb> <cr>

0 ma++ mb++ mc++ md++ <mpr +enter> <dfm 1.5 > "Hebrew typing test";

+1 <delay 2> <inst right2left> <inst .2, .4, .9> <xyjustification RIGHTTOP> "אנא הקלד עוד ועוד כאן." ,

~c, "|", ~d <prose a,b,c,d> <mwb +enter, 2 bu,-1> ;

2 <emit typed text is"~a~b">"סוף";


    Note that it's possible <prose> may not correctly handle East Asian characters and other Unicode/double byte code page sorts of considerations however I expect turning DMDX's Unicode option on and the <prose utf8> option will solve them.  If you are attempting to get it working there and have trouble with characters being mangled subscribe to the DMDX list serve (details here) and let me know, there's only so much testing I can do when the locale of the machine is English and  I can't very well set it to some East Asian locale as I can't read those languages...

 

DMDX Index.