Skip to main content

DolDoc

DolDoc means dollar sign documents. It's uses a notation of dollar signs to specifiy the layout of a document You will need to press $ twice in TempleOS as pressing it normally puts it in escape mode. Let's see some basic usage of DolDoc

"$BG,BLUE$$FG,YELLOW$I am yellow.$FD$$BD$\n";

Here we see we have yellow on a blue background. We use FD BD to set the forground and background to their defualt colors,and FULL reference of the codes is at the bottom of this page,but here are some common ones:

CodeMeaning
TXText
FDUse(or change) default foreground color
BDUse(or change) default background color
FGSet foreground color
BGSet background color
BKTurn blink on or off with 1 or 0
BTButton Surround with newlines to make space for button border

Attributes

DolDoc entries can have attributes and arguments. For example BG here takes a color argument.

"$BG,BLUE$I am blue,$$FD";

Some arguments take names,like LM(left macro) takes a string that is inputed to the terminal when pressed.

"\n\n$BT,\"ONIONS\",LM=\"Beep;\n\"$\n\n"; //We specified a \n in LM to simulate pressing enter.

There are attributes too,they start with the plus or minus sign. Lets see an example.

 "$TX+CX,\"CENTER\"$";

Now we can see that the text is centered.

List of DolDoc flags

To use an flags,use a plus or minus sign to add/remove the flag from the item. Example:

 "$TX+CX+H,\"I have CX and H flags.\"$\n";
FlagDescrition
HWill prevenet CL from deleteing it
LWill tell the thing to behave as a link
TRWill tell the thing to behave as a tree
LSWill tell the thing to act as a list
PUWill cuase macro text to run in a popupwindow.
CWill cuase a tree to e collapsed
XWill set the exit and save flag on a macro
QWill set a exit and not-save flag on a macro
RDRefresh data on screen update
UDUpdate data on typing

DolDoc programming API.

Basics

Sometimes you will want to do more with DolDoc. To get the current DolDoc of the task,use DocPut and DocPrint to print to that document.

DocPrint(DocPut,"\n\n$$BT+CX,\"Hello\"$$\n\n");

DocPrint will return a CDocEntry. We can poke at it's data to make it do stuff. Here are some of the interesting fields of CDocEntry

 class CDocEntry:CDocEntryBase {
I64(*left_cb)(CDoc*,CDocEntry*)
I64(*right_cb)(CDoc*,CDocEntry*)
U8 *data;
};

To use the left_cb/right_cb,we must set the DOCEF_LEFT_CB/DOCEF_RIGHT_CB flags in de_flags. Here is an example:

 I64 Beep2(CDoc *,CDocEntry *) {
Beep;
}
CDocEntry *de=DocPrint(DocPut,"\n\n$$BT+CX,\"Hello\"$$\n\n");
de->de_flags|=DOCEF_LEFT_CB;
de->left_cb=&Beep2;

Make sure you print whole DolDoc commands with DocPrint,if you want to do otherwise use DocPrintPartial. If you want print multiple DolDoc commands at once,use DocPrintAtomic. If you want to type one file into another,use DocType(doc,filename)

Say you want to save a DolDoc,we can do this 2 ways,we can save to memory or a file. To save to memory,do use DocSave,

 I64 len;
U8 *mem=DocSave(DocPut,&len);
//Do whatever
Free(mem);

Or to save to a file,use DocWrite after defining the filename at DocNew.

 CDoc *doc=DocNew("Filename.DD"); //The document's filename detirmined at it's creation.
DocPrint("$TX,\"Hello World\"$");
DocWrite(doc);
DocDel(doc);

User interfaces

You may want to create user interfaces using DolDoc. There are numerous ways to do this,one way to do this is to use DocMenu. This will return a value as defined by LE or RE. These mean left expression and right expression and are DolDoc attributes(see reference). Let's see an example.

U0 CreateDialog() {
CDocEntry *nums[3];
I64 i;
DocClear(DocPut);
"$$TX+CX,\"Pick a number:\"$$\n";
for(i=0;i!=3;i++) {
nums[i]=DocPrint(DocPut,"\n\n$$BT+CX,\"%d\",LE=%d$$\n\n",i,i);
}
DocBottom(DocPut);
switch(DocMenu(DocPut)) {
start:
DocClear(DocPut);
case 0:
"You picked nothing lol.\n";
break;
case 1:
"One is the one\n";
break;
case 2:
"Two is too good\n";
break;
end:
}
}
CreateDialog;

Sometimes you want a form for your application,so we need to up the ante. To do this we DocForm This uses the a class's metadata,so we need to make a class first with Metadata.

class CInput {
//Be sure to use -P with strings
U8 name[STR_LEN] format "$$DA-P,A=\"NAME:%s\"$$\n"; //Data
I64 age format "$$DA,A=\"AGE:%d\"$$\n"; //Data
Bool is_tall format "$$CB,\"Is tall\"$$\n"; //Check box
};

We can then call DocForm with a pointer to a class

CInput inp;
PopUpForm(&inp);
"%s is %d years old\n",inp.name,inp.age;
if(inp.is_tall)
"Tall!\n";

A menu can be accessed via the logo key,it appears at the top of the screen. You can make your own menus via MenuPush. A menu will send a key-press to your program when you select an item(or another type of message if you want). A typical MenuPush looks like this:

 MenuPush(
"File {"
//1st is message(Default is MSG_KEY_DOWN)
//2nd is charctor
//3rd is scancode
" Exit(,CH_SHIFT_ESC,);"
"}"
"Fruit {"
" Apple(,'apple',);"
" Banana(,'banana',);"
" Berry(,'berry',);"
"}"
"Vegetable {"
" Carrot(,'carrot',);"
" Celery(,'celery',);"
"}"
);

As you can see,the 1st argument to the entries is the message(which defaults to MSG_KEY_DOWN). The next 2 arguments are passed to the task via ScanMsg(used by GetKey and ScanKey),so you can put any type of message you want. Let's see it in action:

U0 MenuLoop() {
I64 ch;
MenuPush(
"File {"
" Exit(,CH_SHIFT_ESC,);"
"}"
"Fruit {"
" Apple(,'apple',);"
" Banana(,'banana',);"
" Berry(,'berry',);"
"}"
"Vegetable {"
" Carrot(,'carrot',);"
" Celery(,'celery',);"
"}"
);
"Access stuff from the menu!!\n";
while(ch=GetKey) {
if(ch==CH_SHIFT_ESC) break;
"Got a %c\n",ch;
}
MenuPop;
}
MenuLoop;

Reference

List of DolDoc codes

Use these for making DolDoc entities

CodeMeaning
TXText
CRNewline
SRWordwrap line
CUCursor pos
TBTab
CLClear items without +H
PBPage break
PLPage length
LMLeft margin
RMRight margin
HDHeader margin
FOBottom margin
IDIndents X indents,can be negative
FDUse(or change) default foreground color
BDUse(or change) default background color
FGSet foreground color
BGSet background color
PTPrompt
WWUse 1 to trigger word wrap, 0 to disable word wrap
ULUse 1 to trigger underline, 0 to disable it
IVUse 1 to trigger inverting the text's colors,0 to disable it
BKTurn blink on or off with 1 or 0
SXPick a number -7 through 7 to shift the text
SYPick a number -7 through 7 to shift the text
CMTakes 2 arguments X movement and Y movement
LKLink,will be explained later
BTButton, surround with newlines to make space for the button border
CBCheckbox
LSDefine a define list with D and DefineLstLoad,this will let you select items from a list.
MAMacro,will run code with is clicked,use LM to set the macro text
TRTree,use indent to nest the trees and use a negative indent to un-nest the trees.
HLTurn syntax highlighting on with 1 or 0.

Argument codes

You use a comma and the name to specify an argument value.

TThe tag(displayed text) is set with this
LENLEN sets the length of the DA field
ALinks use this for link location
DLS and list-likes use this for setting the DefineLstLoad'ed string that has the list items in it.
LELeft expression,will evaluate this expression's value when left clicked.
RERight expression,will evaluate this expression
LMLeft macro text,will put the text in input buffer when clicked.
RMRight macro text,will put the text in input buffer when clicked.
RTSet the raw type of the data of the item,use I8-64,or U8-64 or F64
UUser data
SCXScroll X in col columns
SXShift plus or minus 7 pixels
SYSame as above but for Y coordinates