#375 ooDialog - unify dialog control methods

Mark Miesfeld
ooDialog (102)
Mark Miesfeld

For the addXXX() methods that add dialog controls to a user dialog there is a lot of inconsistency in both the naming of the methods and the ordering of the method arguments. This has lead to a lot of confusion and makes it difficult remember the correct method syntax without referring to the documentation all the time.

I think this is partially due to the edition of dialog controls over time, and maybe it is easier to see a solution with hindsight then it is to design it to begin with. There are two facts that could unify the addXXX() methods.

1.) Microsoft has an official name for every single dialog control and of course every control is a control. I beleive it would be better If each of the addXXX() methods simply used Microsoft's name for the control. And, tacking the word control on some methods and not on others shouldn't be done. Each one is a control and tacking control on the method name is redundent.

2.) Every single control has to have a resource ID, the four co-ordinates x, y, cx, and cy. Every single control has a set of style flags that may or may not be used. Then, some controls have text associated with them and some do not. Finally, ooDialog allows the specification of a "data attribute name" for some controls, but not for others.

I propse that the to unify the addXXX() methods, they should all have this format:

add<MsName>(id, x, y, cx, cy, styleFlags, text, attributeName)

For controls that do allow text or attributeName, those arguments will not be allowed. The style flags are optional for every control, so that argument is always optional. Where controls do allow text and attributeName, currently the args are always optional, so text and attributeName are always optional. For static controls and group boxes, Windows always requires the ID, but allows the static ID (-1) to be used. So for those controls, the id arg will be optional and default to -1. In addition some of the methods currently support the automatic calculation of either cx or cy, so for those methods cx or cy may be optional.

Converting ooDialog to the native C++ API offers a relatively painless and opportune time to implement this. For each control that ooDialog supports, the add<MsName>(...) method could be implemented with the C++ API, and use the above format. The existing addXXX() methods that do not conform to format could rearrange the argument array and forward to the appropriate method.

For instance, the addScrollBar() method already conforms to the proposed format and is simply implemented with the C++ API.

The addEntryLine() method does not conform. Microsoft calls the control an "Edit" control and the args to addEntryLine() do not fit the format above. So, a method would be implemented with the C++ API that looks like the following to the Rexx programmer (<> brackets indicate the optional args):

addEdit(id, x, y, cx, <cy>, <style>, , <attributeName>)

The existing addEntryLine() would simply re-order the arguments and forward to the addEdit() method. All existing addXXX() methods would continue to work as they currently do. Users can continue to use the existing methods if they choose. They will really just be aliases for the actual implementation.

The only fly in the ointment is that there are some methods that have the "correct" name, but the wrong argument ordering. These are addGroupBox, addCheckBox, addListbox, addComboBox, and addRadioButton. Because the argument ordering is not "correct" they can't forward to the actual implementation. For those methods, I propose using an abbreviation for the implementing method. These are easy for me to remember, not sure if it will be for others:


The list of methods would then be as follows

addStatic(<id>, x, y, cx,cy, <style>, )
addStaticText(<id>, x, y, cx, cy, <style>, )
addStaticImage(<id>, x, y, cx, cy, <style>)
addStaticRectangle(<id>, x, y, cx, cy, <style>) (or could be addStaticRect())

addGroupBx(<id>, x, y, cx, cy, <style>, )
addPushButton(id, x, y, cx, cy, <style>, , <msgToRaise>)
addCheckBx(id, x, y, cx, cy, <style>, , <attributeName>)
addRadioBtn(id, x, y, cx, cy, <style>, , <attributeName>)

addEdit(id, x, y, cx, <cy>, <style>, , <attributeName>)
addComboBx(id, x, y, cx, cy, <style>, <attributeName>)
addListBx(id, x, y, cx, cy, <style>, <attributeName>)
addScrollBar(id, x, y, cx, cy, <style>)
addListView(id, x, y, cx, cy, <style>, <attributeName>)
addTreeView(id, x, y, cx, cy, <style>, <attributeName>)
addTab(id, x, y, cx, cy, <style>, <attributeName>)
addTrackBar(id, x, y, cx, cy, <style>, <attributeName>)
addDateTimePicker(id, x, y, cx, cy, <style>, <attributeName>)
addMonthCalendar(id, x, y, cx, cy, <style>, <attributeName>)
addProgressBar(id, x, y, cx, cy, <style>)

Since I don't see any downside to this, I'm starting to implement it. However, this leaves plenty of time for suggestions, comment, criticisms, etc..


  • Mark Miesfeld
    Mark Miesfeld

    I've played with this some and I'm not totally happy with the control names that need to be abbreviated, i.e. the ones like addGroupBx().

    An alternative would be to use a different verb than 'add' and I think this makes more sense. The same general problem is present in the getXXXControl() methods that return a new dialog control object. Those methods lend themselves eaily to changing the verb 'get', where the get can be changed to new.

    For the add methods, the dialog controls are really being placed, or put on (into) the dialog. I like place a little better, but then it is a little longer.

    So, my proposal is as above, but to use the following for the method names:

    putStatic(<id>, x, y, cx,cy, <style>, )
    putStaticText(<id>, x, y, cx, cy, <style>, )
    putStaticImage(<id>, x, y, cx, cy, <style>)
    putStaticFrame(<id>, x, y, cx, cy, <style>)

    putGroupBox(<id>, x, y, cx, cy, <style>, )
    putPushButton(id, x, y, cx, cy, <style>, , <msgToRaise>)
    putCheckBox(id, x, y, cx, cy, <style>, , <attributeName>)
    putRadioButton(id, x, y, cx, cy, <style>, , <attributeName>)

    putEdit(id, x, y, cx, <cy>, <style>, , <attributeName>)
    putComboBox(id, x, y, cx, cy, <style>, <attributeName>)
    putListBox(id, x, y, cx, cy, <style>, <attributeName>)
    putScrollBar(id, x, y, cx, cy, <style>)
    putListView(id, x, y, cx, cy, <style>, <attributeName>)
    putTreeView(id, x, y, cx, cy, <style>, <attributeName>)
    putTab(id, x, y, cx, cy, <style>, <attributeName>)
    putTrackBar(id, x, y, cx, cy, <style>, <attributeName>)
    putDateTimePicker(id, x, y, cx, cy, <style>, <attributeName>)
    putMonthCalendar(id, x, y, cx, cy, <style>, <attributeName>)
    putProgressBar(id, x, y, cx, cy, <style>)


    placeStatic(<id>, x, y, cx,cy, <style>, )
    placeStaticText(<id>, x, y, cx, cy, <style>, )
    placeStaticImage(<id>, x, y, cx, cy, <style>)
    placeStaticFrame(<id>, x, y, cx, cy, <style>)

    placeGroupBox(<id>, x, y, cx, cy, <style>, )
    placePushButton(id, x, y, cx, cy, <style>, , <msgToRaise>)
    placeCheckBox(id, x, y, cx, cy, <style>, , <attributeName>)
    placeRadioButton(id, x, y, cx, cy, <style>, , <attributeName>)

    placeEdit(id, x, y, cx, <cy>, <style>, , <attributeName>)
    placeComboBox(id, x, y, cx, cy, <style>, <attributeName>)
    placeListBox(id, x, y, cx, cy, <style>, <attributeName>)
    placeScrollBar(id, x, y, cx, cy, <style>)
    placeListView(id, x, y, cx, cy, <style>, <attributeName>)
    placeTreeView(id, x, y, cx, cy, <style>, <attributeName>)
    placeTab(id, x, y, cx, cy, <style>, <attributeName>)
    placeTrackBar(id, x, y, cx, cy, <style>, <attributeName>)
    placeDateTimePicker(id, x, y, cx, cy, <style>, <attributeName>)
    placeMonthCalendar(id, x, y, cx, cy, <style>, <attributeName>)
    placeProgressBar(id, x, y, cx, cy, <style>)

    Then each control would have a corresponding method to get a new object of the control as such:




    Which would give code looking something this:

    ::method defineDialog

    self~placeRadioButton(200, 10, 10, 45, 15, ...)
    self~placeComboBox(300, 10, 35, 65, 45, ...)
    self~placeListView(400, 10, 90, 100, 300, ...)

    ::method onClick

    rb = self~newRadioButton(200)

    -- do something with the radio button

    ::method onDoubleClick

    list = self~newListView(400)

    if list~selected == 100 then do
    -- do something

  • Rick McGuire
    Rick McGuire

    create or insert might be reasonable alternatives too. I also was not really comfortable with the Bx abbreviation. Abbreviations that only remove a single letter always seem strange to me.

  • Mark Miesfeld
    Mark Miesfeld

    Yes, both of those are good.

    Create is actually real good, I'm not sure why I didn't think of that. create() is the method used to add the dialog frame to the in-memory template, so things like createRadioButton(), createListView(), which add a radio button or list view to the in-memory template make perfect sense.

  • Mark Miesfeld
    Mark Miesfeld

    Present in the ooDialog 4.2.0 release.

  • Mark Miesfeld
    Mark Miesfeld

    • status: pending --> closed
    • pending_work_items: --> none
    • milestone: v4.2.0 --> ooDialog.4.2.0


Cancel   Add attachments