SDL dlglib Library queries

[mavison]

On the web page https://www.bbcbasic.co.uk/bbcsdl/differences.html it says that dlglib.bbc provides a 'dialogue box' functionality loosely similar to WINLIB2*.

The documentation for WINLIB2 is on web page http://www.bbcbasic.co.uk/bbcwin/manual ... #newdialog

There is also an example SDL program general/dlgdemo.bbc which gives some clues.

I have been trying to use dlglib to create a simple dialog box, with some headings, some editable fields, a multi-line text box, and some buttons. However, I have found some differences between WINLIB2 and dlglib which I have listed here in case they are of use to anyone else, and I have some questions.

Comparison of BB4W WINLIB2 and SDL dlglib

Note there are likely to be errors and omissions - any corrections welcome!

These PROCs all seem the same in both BB4W & SDL:
PROC_groupbox(dlg%,text$,id%,x%,y%,cx%,cy%,style%)
PROC_checkbox(dlg%,text$,id%,x%,y%,cx%,cy%,style%)
PROC_radiobutton(dlg%,text$,id%,x%,y%,cx%,cy%,style%)
PROC_static(dlg%,text$,id%,x%,y%,cx%,cy%,style%)
PROC_closedialog(dlg%)

FN_newdialog(title$,x%,y%,cx%,cy%,font%,size%)
SDL parms are only (title$,x%,y%)

PROC_pushbutton(dlg%,text$,id%,x%,y%,cx%,cy%,style%)
SDL is PROC_button but parms seem the same.

PROC_editbox(dlg%,text$,id%,x%,y%,cx%,cy%,style%)
SDL is PROC_textbox
Parameters appear the same, but the style% is different:
ES_WANTRETURN and ES_MULTILINE are not defined in SDL and the value do not
seem to work to provide a multi-line edit box.

PROC_showdialog(dlg%)
SDL is result% = FN_showdialog(dlg%,x%,y%)
If x% or x% are &80000000 the width + height are centralised in the window
else they are offsets of top left in the window (in dialog units?)
Returned integer result% is I think the id% of clicked button.

Setting contents of Dialog Box:

BB4W: SYS "SetDlgItemText", !dlg%, id%, text$
SDL: PROC_setdlgitemtext(D%, 101, "New text")

BB4W: SYS "SetDlgItemInt", !dlg%, id%, value%, signed%
SDL: no obvious equivalent

Reading Contents of Dialog Box:

BB4W: DIM text% 255 :SYS "GetDlgItemText", !dlg%, id%, text%, 255
SDL: text$ = FN_getdlgitemtext(dlg%, id%)

BB4W: DIM text% 65535 :SYS "GetDlgItemText", !dlg%, id%, text%, 65535 TO Len%
SDL: no obvious equivalent

Questions

• Is there any other documentation for dlglib?

• Where can I find the definition of 'Dialog box units' that are used in WINLIB2 docs?

• How can a multi-line edit box be used with dlglib?

• How can the missing parms cx%,cy%,font%,size% in FN_newdialog be defined?

• Is there any explanation of PROC_registerdlgcallback(dlg%, FNmycb()) in dlgdemo?

[RichardRussell]

Is there any other documentation for dlglib?

Sorry, no. I suspect yours is the first and the best documentation available!

Where can I find the definition of 'Dialog box units' that are used in WINLIB2 docs?

DIalog box units are related to the font size (in both BB4W and BBCSDL), the idea being that the box will automatically scale to suit the font size. I think one unit is approximately a quarter of the character height, but you should probably consider them as 'arbitrary'.

How can a multi-line edit box be used with dlglib?

I've never attempted to write a general purpose multi-line edit box for BBCSDL. The editing panes in both supplied IDEs (Andy Parkes' BBCEdit and my SDLIDE) are effectively highly customised edit controls, but neither is written to be at all 'portable'. If somebody fancies writing such an add-on for dlglib.bbc (in a separate library, I would suggest) that would be a great addition.

How can the missing parms cx%,cy%,font%,size% in FN_newdialog be defined?

I think cx%,cy% have simply become parameters of FN_showdialog() instead (it sort of makes sense that the position of the dialogue box should be determined when you show it, not when you define it). font% and size% aren't needed (the scale is determined by the current font size).

Is there any explanation of PROC_registerdlgcallback(dlg%, FNmycb()) in dlgdemo

As used in dlgdemo.bbc, it provides a substitute for the Windows BS_DEFAULT (BS_DEFPUSHBUTTON) style, which causes the Enter key to have the same effect as clicking on one of the buttons (usually the OK button). It can also be used to make the Escape key behave like the Cancel button. The callback function is called whenever a key is pressed, and periodically by the timer.

[mavison]

Richard, thanks for your reply. Helpful, but disappointing, because without multi-line my dialog is not really viable.

I might be tempted to have a go with some multi-line code, but I need a few more clues eg (a) a single-line box size does not seem to limit how much text can be added (it just scrolls), and (b) would each key need to be trapped with registerdlgcallback somehow? How and what are the parms passsed to FNmycb?

[RichardRussell]

without multi-line my dialog is not really viable.

As I made clear from the start, BBC BASIC for SDL 2.0 has a different support model from BBC BASIC for Windows. The product is, and will remain, entirely free, but in exchange I hope users will contribute more towards libraries, documentation etc. dlglib.bbc exists solely because I needed the functionality myself, and since I have not needed a general-purpose multi-line edit control it doesn't contain one!

I might be tempted to have a go with some multi-line code, but I need a few more clues eg (a) a single-line box size does not seem to limit how much text can be added (it just scrolls), and (b) would each key need to be trapped with registerdlgcallback somehow? How and what are the parms passsed to FNmycb?

I don't think the callback is specifically relevant to a multi-line edit control; it is called (if one has been registered) by the 'common' dialogue box management code in dlglib, and so long as a multi-line edit control was integrated in the same way as all the other controls the callback will happen 'automatically' with a new control.

If I was to consider implementing a multi-line edit control myself I think my starting point would probably not be the single-line textbox but the listbox control. My guess is that adding an editing capability to the listbox code would be less effort than adding the multiline and scrolling capability to the textbox code, but that is without having thought about it in any detail.

If you are contemplating writing your own control what you need to know is how it interfaces with the outside world. Fundamentally each control has two interfaces: a public interface consisting of a procedure of the form PROC_mynewcontrol() (you know about this already from the other controls) and a private interface consisting of a function of the form FN_mynewcontrol@dlg(). The private interface is notified of relevant events by the common dialogue manager code (you will appreciate that dialogue controls must be 'event driven' since the user can move focus between controls at will).

The events that the dialogue control is notified of are DLG_INIT (should more accurately be called DLG_REDRAW), DLG_INKEY (keypresses), DLG_CLICK (mouse clicks), DLG_GAINFOCUS, DLG_LOSEFOCUS, DLG_MOUSEIN, DLG_MOUSEOUT, DLG_MOUSEMOVE (should be self-explanatory), DLG_UNCLICK (mouse button released) DLG_TIMER (periodic) and DLG_DISABLE.

[mavison]

Thanks for your hints about a multi-line text box. I will investigate when I get chance - which will prompt more questions, I am sure.

I have just noticed that if a button has an id of 10 or over, clicking it seems to do nothing. My previous dialogs happened to use only 1-9 and worked fine, but for some reason I started a new one at 11, and none worked. Is this a restriction somewhere?

[RichardRussell]

I have just noticed that if a button has an id of 10 or over, clicking it seems to do nothing. My previous dialogs happened to use only 1-9 and worked fine, but for some reason I started a new one at 11, and none worked. Is this a restriction somewhere?

There's a maximum of nine or ten buttons that can terminate the dialogue, yes, but usually you only need two such buttons (OK and Cancel) or at most three (e.g. OK, Apply and Close). If you need more than that - and certainly if you need as many as ten - it would suggest that your dialogue box design is unconventional and should be reconsidered.

The way that dialogue boxes are supposed to work is that you interact with the various controls (choosing from checkbuttons and radiobuttons, entering data in textboxes, making selections from listboxes or comboboxes etc.) whilst the dialogue box remains 'open', and then, when you are satisfied that the entries are what you want, you click on OK (or Cancel if you want to abandon the whole thing) which closes the dialogue.

There should not be, unless I have done something really silly, any limitation on the number of buttons etc. which can be clicked to activate a handler. If you are finding there is such a limitation please let me know, preferably with a code example.

[mavison]

It was not the number of buttons that caused me the problems ... I only had two, but their ids were 11 and 12, and it was the id being over 9 that seems to cause it to be ignored (at least to end the dialog). I had thought that ids were purely user choice.

[RichardRussell]

I had thought that ids were purely user choice.

Even in BB4W that's not the case: IDOK is 1 and IDCANCEL is 2 and you must use those values if things are to work correctly. Here's the full set of IDs which are defined by Microsoft in WinUser.h:

Code: Select all

#define IDOK            1
#define IDCANCEL        2
#define IDABORT         3
#define IDRETRY         4
#define IDIGNORE        5
#define IDYES           6
#define IDNO            7
#define IDCLOSE         8
#define IDHELP          9

The way I've handled this in BBCSDL's dlglib.bbc is that any IDs in that range (1-9) cause FN_showdialog() (or FN_showdialogex()) to return to the caller, because they are typically used to terminate the dialogue. Other IDs won't cause FN_showdialog() to exit but may activate handlers that you provide using FN_setproc() in the same way as you would in Windows.

[RichardRussell]

You might also like to read this blog post by Raymond Chen which goes into more detail about the predefined IDs, and why dialogue editors allocate IDs starting at 100 (BB4W's DLGEDIT is no exception, I think). It lists a couple of more recently added IDs (IDTRYAGAIN and IDCONTINUE) but I've never used those.

[KenDown]

Hmmm. I take issue with the statement that we *must* use 1 for "OK" and "2" for "Cancel". I have a program which uses multiple tabs, each one of which has its own OK button. (For example, one tab lets me select objects to place on the screen after setting parameters such as size and colour. Obviously I would be unhappy if OK there triggered the OK for indicating that the slide is complete. I have different values for each "OK" button and have not encountered any problems from so doing.