Sorry, took some more days to come back. o) The API listings below were actually done before my first post, but I did not find a calm minute to continue and add some explanations to them. Thanks for the details on why the methods are named like they are currently. From a c++/win32 programmers point of view, it maybe a nobrainer to basically just "reuse" the names for the exposed methods like you did. Just guessing, this CB_ADDSTRING etc. API is ancient? As someone who's seen a handful environments targeting user interfaces, recently building WPF applications and things, I'd like to tell: The method names on the Control object feel somewhat outdated, sometimes wrong and seem extra hard to use. It's quite far from what you are used to work with in nowadays frameworks, wether it's WPF, .Net-Forms or Web/HTML-Forms.
The following is an overview of the current method names, followed by alternative #01 and #02. The latter uses properties for some of the exposed functionality to reduce the number of methods in total. Red relates to the current naming, green to suggested alternatives. In the end you find a more detailed explanation to each current Control object method and why I think a different name or an additional method/property enhances the current API.
Current Beta-API
[ul]
[li]too short names [/li]
[li]not easy to use, unclear results[/li]
[li]hard to read [/li]
[li]hard to understand [/li]
[li]does not meet any standard (means standards "I" know at least! o)[/li]
[li]unclear what these methods accept as parameters (you'd end up with help-file open all day long)[/li]
[li]unclear what they act on
[ul]AddString()
InsertString()
DeleteString()
GetCheck()
SetCheck()
GetCount()
GetData()
SetData()
GetVisible()
SetSel()
GetText()
SetEnable()
SetVisible()[/ul][/li][/ul]
Alternative API #1
[ul]
[li]more friendly, can almost be read fluently[/li]
[li]better separation of functionality[/li]
[li]intuitive naming, less guessing about parameters and expected result[/li]
[li]nearly "standard" in nowadays GUI toolkits[/li]
[li]clear differentiation between simple values and Items (which have name and (optional) value attached)
[ul]AddItem()
InsertItemAt()
RemoveItemAt()
RemoveItemByName()
IsChecked()
SetChecked()
Count()
GetItemValueAt()
GetItemValueByName()
SetItemValueAt()
SetItemValueByName()
IsEnabled()
IsVisible()
GetSelectedIndex()
SelectItemAt()
SelectItemByName()
GetValue()
SetValue()
Enable()
Disable()
Show()
Hide()[/ul][/li][/ul]
Alternative API #2 (my preferred version)
[ul][li]using all the "pro" points of alternative #01[/li]
[li]making use of read/write properties -> less methods required[/li]
[li]gets around difficult naming for getters and setters of boolean values (Get..()/Set..() vs. Is/Has..()/Set..() etc.)[/li]
[li]even easier handling[/li]
[li]also known from other frameworks
[ul]AddItem()
InsertItemAt()
RemoveItemAt()
RemoveItemByName()
GetItemValueAt()
GetItemValueByName()
SetItemValueAt()
SetItemValueByName()
SelectItemByName()
.checked [instead of IsChecked() + SetChecked()]
.count [instead of Count()]
.selectedIndex [instead of GetSelectedIndex() + SelectItemAt()]
.enabled [instead of IsEnabled() + Enable() + Disable()]
.visible [instead of IsVisible() + Show() + Hide()]
.value [instead of GetValue() + SetValue())][/ul][/li][/ul]
Detailed explanation: (method name mapping between current beta and alternatives)
[ul]
[li]AddString( strVal [, strData] )
-> AddItem( strName, [, strValue] )
AddString() does not only add a string, it adds a string (which can be seen as a name) and a corresponding value.
A name/value pair can be seen as an Item. New methods reflect that. Notice the difference strVal -> strName, strData -> strValue.
[ul][/ul][/li]
[li]InsertString( strVal [, strData, intIndex] )
-> InsertItemAt( intIndex, strName [, strValue,])
It's about indexes here compared to AddItem()/AddString(), so index should be first parameter.
Index first would also avoid dummy "strData = 0" parameter each time (optional params always go last).
Notice the difference strVal -> strName, strData -> strValue.
[ul][/ul][/li]
[li]DeleteString( intIndex or strVal )
-> RemoveItemAt( intIndex )
-> RemoveItemByName( strName )
"Remove" is more counterpartish to "AddString()" than "DeleteString()".
Its weird how the current DeleteString() accepts an integer to remove "strings" which actually are entries or items.
[ul][/ul][/li]
[li]GetCheck()
-> IsChecked() or
-> GetStatus() and/or
-> .checked (if read/write properties are possible)
Since GetCheck() also works for radiobutton, the name is misleading.
Does it return a checkbox? It works on radiobuttons as well, so GetStatus() or something seems to fit much better.
[ul][/ul][/li]
[li]SetCheck( intStatus )
-> SetChecked( intStatus )
-> .checked (if read/write properties are possible)
Similar to GetCheck(), since SetCheck() also works for radiobutton, the name is misleading.
[ul][/ul][/li]
[li]GetCount()
-> Count()
Consider turning this into a .count property like in other DO objects, or call it Count().
Because there is .size, .length and .count, another variation like GetCount() can be avoided.
[ul][/ul][/li]
[li]GetData( intIndex or strVal)
-> GetItemValueAt( intIndex )
-> GetItemValueByName( strName )
GetData() is really hard to get. What data from where?
The alternatives make clear that it's about getting a value from an item in a specific position or with a specific name.
[ul][/ul][/li]
[li]SetData( intIndex or strVal, strData )
-> SetItemValueAt( intIndex, strData)
-> SetItemValueByName( strName, strData )
It's hard to understand as well. How much easier would "SetItemValueAt( index)" be to anyones brain?
Quite a lot I think, SetData() tells me nothing, it does not speak to me.
[ul][/ul][/li]
[li]GetEnable()
-> IsEnabled() and/or
-> .enabled (if read/write properties are possible)
GetEnable() does not sound right and makes little sense.
Does it get the control and enable it? No, it just returns a bool indicating the enabled/disabled status.
[ul][/ul][/li]
[li]GetVisible()
-> IsVisible() and/or
-> .visible (if read/write properties are possible)
Same as GetEnable().
[ul][/ul][/li]
[li]GetSel()
-> GetSelectedIndex() and/or
-> .selectedIndex (if read/write properties are possible)
Does GetSel() get you the current selection? Is it a text? No, it's about the selected index from a list or combobox.
[ul][/ul][/li]
[li]SetSel( intIndex or strVal )
-> SelectItemAt( intIndex )
-> SelectItemByName( strName )
SetSel(), same as GetSel(). SetSel() does not make clear what it does and what parameters it accepts.
"SelectItemByName()" is much more easy to understand in comparison.
[ul][/ul][/li]
[li]GetText()
-> GetValue()
-> .value (if read/write properties are possible)
[ul][/ul][/li]
[li]SetText( strVal )
-> SetValue( strVal ) and/or
-> .value (if read/write properties are possible)
[ul][/ul][/li]
[li]SetEnable()
-> Enable()
-> Disable()
-> .enabled (if read/write properties are possible)
Syntax like SetEnable(false) is hard to understand and hard to read.
[ul][/ul][/li]
[li]SetVisible()
-> Show()
-> Hide()
-> .visible (if read/write properties are possible)
A name like SetVisible() implies that it always unhides items, but it does not.[/li][/ul]
Icing on the cake:
Depending on how much object oriented you want the DO API to be. An additional list and combobox Item object could be invented. This one could be prepared, added and removed "at once", in contrast to methods which always take two parameters for name/value ("string" and "data"). A (List/Combobox-) Item object and matching methods to work with makes even more clear, when a method acts or depends on simple values (Edit/Textbox-Control e.g.) or wether it is about a name/value pair - a (List/Combobox-) Item. Quick example (using suggested API): Instead of value = GetItemValueAt(1), you'd write value = GetItemAt(1).value etc.
Thanks for reading! o)