hschumann2/TempleOS-Source-Code

1 2                                DolDoc Overview3 4DolDoc is a TempleOS document type supported by DolDoc Routines.  In a document,5commands are bracketed with '$'s.  Use <CTRL-l> to experiment inserting a6command.  Then, use <CTRL-t> to toggle to plain text to see it.7 8Here is the grammar:9 10<DolDocCmd> := $<TwoLetterCmd>[<FlagList>][,<ArgList>]$ | $ColorName$11 12<FlagList> := +|- <FlagCode>[<FlagList>]13 14<ArgList> := <ArgCode>=<ArgExpression>[,<ArgList>]15 16 17The format of DolDoc cmds is a two character code, +/-flags, a comma and args18separated by commas.  Some commands have mandatory args.  Optional args are19indicated with <ArgCode>=.  A ColorName bracked by dollars, will change the20foreground color.21 22See ::/Doc/Widget.DD, ::/Demo/DolDoc/DemoDoc.DD, and23::/Demo/ToHtmlToTXTDemo/ToHtml.HC.24 25<TwoLetterCmd>  See Type Defines and PrsDollarCmd().26-] TX Text27  Normally, text is not bracketed with '$', but if you wish to specify flag28  attr, such as centering text, you can bracket them with '$' and enter flags29  such as "+CX".  You can't edit them normally if they are bracketed by '$'30  unless you toggle to plain text mode with <CTRL-t>.31-] CR Hard New Line32  New lines are normally not bracketed with '$'.33-] SR Soft New Line34  Word wrap uses temporary soft new lines.  Users never place soft new lines.35-] CU Cursor pos36  The cursor pos is stored as a ASCII#5 character and is not bracketed with '$'.37  Users normally do not enter cursor pos.38-] TB Tab39  Tabs are normally not bracketed with '$', but are ASCII#9.40-] CL Clear41  Clear all prev entries except ones with hold(+H) flags.  You might want +H on42  word wrap entries.  Alternatively, you can use DocClear().43-] PB Page Break44  Page break.45-] PL Page Length46  Page length.47-] LM Left Margin48  Left margin.49-] RM Right Margin50  Right margin.51-] HD Header52  Top margin.53-] FO Footer54  Bottom margin.55-] ID Indent +/- num56  Changes the indentation deeper if positive, or shallower if negative. It57  effects the behavior of trees.58 59  $ID,2$ indents 2 columns.60-] Text Colors61  You place an expression(usually a color define--see color defines) to indicate62  which of the 16 colors to use. If you enter no num, color returns to the63  default.64 65  FD Default Foreground Color66  BD Default Background Color67  FG Foreground Color68  BG Background Color69 70  $FD,BLUE$ will set the default foreground color to BLUE.71 72-] PT User Prompt73  Start of a user prompt.74-] WW Word Wrap75  Include a 1 or 0.76 77  $WW,1$ turns word-wrap on.78-] UL Underline79  Include a 1 or 0.80 81  $UL,1$ turns underline on.82-] IV Invert83  Include a 1 or 0.84 85  $IV,1$ turns invert on.86-] BK Blink87  Include a 1 or 0.88 89  $BK,1$ turns blink on.90-] SX Shift X pos91  Include a num from -7 to 7.  Only foreground is shifted.  Positive right.92 93  $SX,3$ shifts characters 3 pixels right.94-] SY Shift Y pos95  Include a num from -7 to 7.  Only foreground is shifted.  Positive down.96 97  $SY,3$ shifts characters 3 pixels down.98-] CM Cursor Movement99  This has two expressions, one for X offset and one for Y.  You can remove one100  or the other with -LE or -RE.101 102  The expressions are relative to the current cursor location, unless you make103  them relative to:104 105    +LX left106    +CX center107    +RX right108    +MRX margin relative109 110    +TY top111    +CY center112    +BY bottom113    +PRY page relative114 115  See ::/Demo/DolDoc/CursorMove.HC.116 117-] AN Anchor118  The CDocEntry.aux_str arg A="" is used for the anchor.  I don't use these very119  often, but they're good sometimes.120-] LK Link121  The CDocEntry.aux_str arg A="" is used for the link text.  With no aux the tag122  becomes the link text, as in example 3.123 124  See Link Types.125 126  Examples: <CTRL-t> to see127 128  1)File link to HelpIndex.DD129  2)File link to HelpIndex.DD with link type file130  3)File link with same tag str.  ::/Doc/HelpIndex.DD131  4)File find link searching for 'Admin'132  5)File find link searching for 5th 'CTRL'133  6)Manual page link134  7)File line num link135  8)File anchor link -- <CTRL-t> to see anchor after you click136  9)Bible Link The chapter:verse actually just does a text search.137  10) Help Index Link.138  11) Address Link.139 140  12) For in-memory document address links, see SpriteEdText().141 142-] BT Bttn143  See ::/Demo/DolDoc/MenuBttn.HC.144-] DA Data145  Used for forms that prompt for data or just displaying a value.  Use <CTRL-l>146  to help you generate the DolDoc command text you need in your HolyC class147  member's format meta-data for DocForm().  See ::/Demo/DolDoc/Form.HC,148  ::/Demo/Dsk/DataBase.HC, and ::/Adam/DolDoc/DocWidgetWiz.HC.149 150  If you are not using DocForm(), make a $DA...$ statement with DocPrint() and151  fill-in the ->data addr.  See task_title.152 153  The default raw data type for the $DA...$ command is RT=I64.  DocForm() will154  automatically reset the raw type to the value from the HolyC class member's155  definition if you leave it set to the default.  Or, if not using DocForm(),156  specify a raw data type of I8, U8, I16, U16, I32, U32, I64, U64, or F64.  See157  DocDataFmt() and DocDataScan().158 159  The CDocEntry.aux_str arg A="" is used for the print/scan format string.160 161  The default field length is LEN=64 characters.  For U8 arrays[], DocForm()162  will automatically reset the field length to the string length from the HolyC163  class member's definition.  The length measures starting after the ':' in the164  A="" format string.165 166  The space after the first ':' in the format string marks the first valid167  cursor pos.  See Data Tag Width.168-] CB Check Box169  Used for forms.  Use <CTRL-l> to help you generate the DolDoc command text you170  need in your HolyC class member's format meta-data for DocForm().  See171  ::/Demo/DolDoc/Form.HC and CEdFindText.172 173  If you are not using DocForm(), make a $CB...$ statement with DocPrint() and174  fill-in the ->data addr.  See task_title.175 176  The default raw data type for the $CB...$ command is RT=I8 which is Bool.177  DocForm() will automatically reset the raw type to the value from the HolyC cl178  ass member's definition if you leave it set to the default.  Or, if not using179  DocForm(), specify a raw data type of I8, U8, I16, U16, I32, U32, I64, U64, or180  F64.  See DocDataFmt() and DocDataScan().181-] LS List Widget182  Used for forms that prompt for data.  You must specify a define list, D="".183  Use <CTRL-l> to help you generate the DolDoc command text you need in your184  HolyC class member's format meta-data for DocForm().  See185  ::/Demo/DolDoc/Form.HC.186 187  If you are not using DocForm(), make a $LS...$ statement with DocPrint() and188  fill-in the data addr.  See task_title.189 190  The default raw data type for the $LS...$ command is RT=I64.  DocForm() will191  automatically reset the raw type to the value from the HolyC class member's192  definition if you leave it set to the default.  Or, if not using DocForm(),193  specify a raw data type of I8, U8, I16, U16, I32, U32, I64, U64, or F64.  See194  DocDataFmt() and DocDataScan().195-] MA Macro196  A left macro arg, LM="", will send text when the left mouse is clicked.197 198  A left in string, +LIS, flag will cause text to be sent to InStr() instead of199  In().  An InStr runs code.  Literal text is in quotes and messages are sent200  with Msg().  See Dir("::/Demo/InFile");View;.201 202  Macro's are usually in your ~/PersonalMenu.DD and have the '+X' flag set by203  default.  Adding '-X' prevents the usual <ESC> from being sent (which exits204  the PersonalMenu scrn).  Note: When you click a macro on the cmd line, it will205  go to the bottom and execute unless you cancel the <ESC> with a '-X'.206-] MU Menu Value207  A left expression arg, LE=<Exp>, will return a number when clicked with the208  left mouse.209 210  See PopUpRangeI64().211-] HX Hex Edit212  See DocD().213-] TR Tree Widget214  A tree widget is a branch in a collapsable tree.  The domain of the branch215  extends from the first +indent until enough -indents bring it back to where it216  started.  Tree's begin collapsed unless a -C flag is present.217 218  You might want to use DocPrintAtomic().219 220  See ::/Demo/DolDoc/TreeDemo.HC.221-] SP Sprite222  Insert a sprite into text with <CTRL-r>.  The cursor location at the time you223  press <CTRL-r> is critical because the sprite will be offset from that224  location.  This is important when adding images to programs.  Numbers for225  sprites are automatically chosen because copying to and from the clip requires226  this.  You can insert another sprite with the same image by hitting <CTRL-t>227  and manually adding a $SP...$ entry with the same BI= num.228 229  You can add a text tag to the $SP...$ cmd by manually adding text into the $SP230  ...$ cmd, as in $SP,"pic 2",BI=2$.  If you enter a tag of the form "<1>" then231  the number in the tag will be updated to match the BI= number.232-] IB Insert Binary233  Tells the compiler to insert a pointer to some binary data stored after the234  end of text in the document.  There is just one type of binary data in DOC's235  at this point -- sprites -- created with <CTRL-r>.  They have a number236  associated with them.  This number is automatically chosen, because copying to237  the clip-board and back requires renuming.  To use a $IB...$ cmd, toggle to238  plain text (<CTRL-t>) after inserting a sprite and check the number in the $SP239  ...$ cmd. Create a $IB...$ cmd with the same BI= number and the sprite will be240  inserted into the compiled stream like a string const.241 242  You can, optionally, include tag text to be displayed for the $IB...$ cmd.  If243  you set the tag to "<1>", then the editor will automatically update the tag if244  the BI= number changes.245 246  The reason for the $IB...$ cmd is to pass a arg to Sprite() and Sprite3().247  See ::/Demo/Graphics/SpritePlot.HC.248 249-] IS Insert Binary Size250  Inserts a number into the compiled stream describing the size of binary data251  associated with a bin number.  I never use this.252-] SO Song253  See Play().  CDocEntry.aux_str A="" stores the song note text.254-] HL Highlighting255  Include a 1 or 0.256 257  $HL,1$ will turn syntax highlighting on.258-] HC html259  See ::/Demo/ToHtmlToTXTDemo/ToHtml.HC to generate a html version of a260  document.  You can cause html code to be injected with HC.  Use the +HTML flag261  to inject a html link.262-] ER Error263  When errors are detected in DolDoc cmds, an ER entry is generated.264 265<FlagCode>  See Flag Defines and Simple Flags.266-] +H Hold267  Causes not to delete this cmd when cleared with CL or when the268  doc->max_entries is exceeded.  Word wrap is a good to hold.  There is no way269  to delete these entries, at this point.270-] +L Link271  Make a cmd behave as a link.  Perhaps, use this on a $SP...$ cmd.272-] +TR Tree273  Make a cmd behave as a tree branch.  Usually, this is placed on a TX entry.274  The tree extends from the start until another tree entry or when indentation275  has been expanded and reduced back to the starting value.276 277  A +C flag on a tree will start it collapsed.278-] +LS List279  Make a cmd behave as a list widget.  See above.  Usually, this is placed on a280  TX entry.281-] +PU PopUp282  A PopUp flag on a MA will cause the cmds to run in a new task, a pop-up283  window.284-] +C Collapsed285  A collapsed flag on a TR entry will cause it to start collapsed.  A -C flag286  will make it start open.287-] +X <ESC> (Exit)288  The exit flag will cause a $MA...$ macro to send an <ESC> before running to289  exit the PersonalMenu scrn and return to the cmd prompt.  Actually, the290  default $MA...$ has an exit flag set so you add a -X to turn-off ESC, for a +P291  U pop-up macro.  If an entry is already at the cmd prompt, the +X will292  movement to the bottom of the window.293-] +Q <SHIFT-ESC> (Abort Quit)294  A quit flag is similar to a +X except a <SHIFT-ESC> instead of an <ESC> to295  exit.296-] +Z Zero297  A zero flag on a HX entry will cause the offset from zero.  A -X will show the298  actual memory addr. By default, HX has the zero flag set.299-] +RD Refresh Data300  The Refresh Data flag on a DA or a CB makes the value on the scrn updated301  continuously.302-] +UD Update Data303  The Update Data flag on a DA or a CB makes the value in the CDocEntry updated304  when keys are typed on it.305-] +TC Tag CallBack306  See ::/Demo/DolDoc/CallBack.HC.307-] +LC Left CallBack308  See ::/Demo/DolDoc/ClickCallBack.HC.309-] +RC Right CallBack310  See ::/Demo/DolDoc/ClickCallBack.HC.311 312<ArgCode>  See Arg Defines.313-] T="" Tag Str314  Some cmds have a tag by default.  See TX+T.  You can code T="tag_text" as just315  "tag_text" with no T=.316-] LEN="" Field Length317  The default field length for $DA...$ commands is LEN=64 characters.  For U8318  arrays[], DocForm() will automatically reset the field length to the string319  length from the HolyC class member's definition.  The length measures starting320  after the ':' in the A="" format string.321 322  The space after the first ':' in the format string marks the first valid323  cursor pos.  See Data Tag Width.324-] A="" Auxilliary Str325  Some cmds need auxilliary strings.  A="str" means an CDocEntry.aux_str is326  present.  aux_str is used for song note text, link text, anchor text, and $DA.327  ..$ format string text.328-] D="" Define Str329  A D="" means either a define str indirection is present on a text widget, or a330  define list is present on a list widget.331 332  For indirection, the tag will be regenerated by substituting the value of a333  system #define or DefineLoad() string.  See ::/Demo/DolDoc/DefineStr.HC,334  ::/Adam/ADefine.HC and ::/Doc/MemOverview.DD.335 336  For LS widgets, see ::/Demo/DolDoc/Form.HC.337-] HTML=""338  See ::/Demo/ToHtmlToTXTDemo/ToHtml.HC to generate a html version of a339  document.  You can cause html link on an item with HTML="".340-] LE=<Exp> Left Expression341  Left expression.  CM has this by default for X offset and you can leave-off342  the LE=, just putting the <Exp>.343 344  See ::/Demo/DolDoc/MenuBttn.HC.345-] LM="" Left Macro Str346  Left macro string.347-] RE=<Exp> Right Expression348  Right expression.  CM has this by default for Y offset and you can leave-off349  the RE=, just putting the <Exp>.350 351  See ::/Demo/DolDoc/MenuBttn.HC.352-] RM="" Right Macro Str353  Right macro string.354-] BI=<Exp> Bin Number355  Binary data item number.356-] BP="" Bin Ptr357  The BinPtrLink flags lets you specify a filename and bin num to import a bin.358 359  $SP,"<tag>",BI=1,BP="filename,1"$ will import bin num "1" from filename.360  $SP,"<1>",BI=1,BP="::/Demo/Graphics/Mountain.HC.Z,Mountain"$ will import bin361  with tag name "Mountain" from "::/Demo/Graphics/Mountain.HC.Z".362-] RT=<raw_data_type>363  The default data-type for the $DA...$ and $LS...$ commands is RT=I64.  If you364  do not specify a raw type and are using DocForm(), it will use the class365  member's raw type, automatically.  The default for the $CB...$ command is RT=I366  8 which is Bool.367 368  If not using DocForm(), change it to I8, U8, I16, U16, I32, U32, I64, U64, or369  F64.  See DocDataFmt() and DocDataScan().370-] SX=<Exp> Shift X371  Shift tag text +/- 7 X pixels off the grid.372-] SY=<Exp> Shift Y373  Shift tag text +/- 7 Y pixels off the grid.374-] SCX=<Exp> Scroll X375  Scroll text in a marquee of so many columns.376-] U=<Exp> User Data377  User Data.378 379  See ::/Demo/DolDoc/MenuBttn.HC.380 381EXAMPLES:382 383<CTRL-t> to see how the following were done.384Underlined Inverted Blinking super sub385This is a big long scrolling msg.386 387Cursor Movements:388 389 390 391   Cursor moved 3 rows down and to 3rd column from left.392 393 394 395                                        Note mandatory comma after flags396 397The following may be changed to modes instead of attr with flags.398 399                                This is centered400 401                                                         This is right justified402