Adjustment to *Ex() functions

[ocornut]

Possibly more contentiously, I had a go at adding default argument "helpers" - i.e. version of functions that elide defaulted arguments. After playing with this a bit I actually felt like it worked best when the "helpers" are the default, so you get functions like this:

CIMGUI_API bool ImGui_BeginCombo(const char* label, const char* preview_value); // Implied flags = 0
CIMGUI_API bool ImGui_BeginComboEx(const char* label, const char* preview_value, ImGuiComboFlags flags /* = 0 */);

...the logic being that this gives an experience close to C++, where if you type "ImGui_BeginCombo(" you get the version with only the required arguments, and if you want to specify everything you need ImGui_BeginComboEx() instead.

I picked "Ex" as the suffix for that after considering a bunch of alternatives ("WithArgs", and even at one point just "_" as a kind of minimilist "doesn't get in the way when reading code" option), mainly because it's short and also there's a bit of prior history in that the Win32 API has a reasonable number of places where there are "basic" versions of function calls and then "Ex" versions with more arguments (for slightly different reasons, admittedly, but still).

The downside of this is that there are already a couple of places that use "Ex" in the code, though, so I'm not 100% sure this is the right avenue to go down. Other suggestions gratefully accepted!

I believe this is a great idea but it'll require a few passes of tweaking.

---

• [x] Suggestion 1: when the first default parameters is a flags that default to = 0 it could be exclused from the Ex rules.

  bool ImGui_ColorEdit4Ex(const char* label, float col[4], ImGuiColorEditFlags flags /* = 0 */);
  bool ImGui_ColorEdit4(const char* label, float col[4]);                                           // Implied flags = 0

  would become

  bool ImGui_ColorEdit4(const char* label, float col[4], ImGuiColorEditFlags flags /* = 0 */);

  Seems like a good tradeoff to reduce noise of api surface, since passing a 0 flag is simple. Further parameters would still get included in the Ex() function. ImGui_TableSetupColumn() would include the flags but following parameters go in ImGui_TableSetupColumnEx().

---

• [x] Suggestion 2: Likewise for the first default parameter that is ImGuiCond cond = 0

  void ImGui_SetNextWindowSizeEx(ImVec2 size, ImGuiCond cond /* = 0 */);
  void ImGui_SetNextWindowSize(ImVec2 size);

  would become

  void ImGui_SetNextWindowSize(ImVec2 size, ImGuiCond cond /* = 0 */);

---

• [x] Suggestion 3 Manually marking functions to disable the generation of the Ex functions. I think this is preferable for low-level functions:

  void ImGui_LoadIniSettingsFromDisk(const char* ini_filename);                             // call after CreateContext() and before the first call to NewFrame(). NewFrame() automatically calls LoadIniSettingsFromDisk(io.IniFilename).
  void ImGui_LoadIniSettingsFromMemoryEx(const char* ini_data, size_t ini_size /* = 0 */);  // call after CreateContext() and before the first call to NewFrame() to provide .ini data from your own data source.
  const char* ImGui_SaveIniSettingsToMemoryEx(size_t* out_ini_size /* = NULL */);           // return a zero-terminated string with the .ini data which you can save by your own mean. call when io.WantSaveIniSettings is set, then save data by your own mean and clear io.WantSaveIniSettings.
  const char* ImGui_SaveIniSettingsToMemory();                                              // Implied out_ini_size = NULL
  ImGui_SetAllocatorFunctionsEx
  ImGuiStorage_**Ex

  And it is also preferable for functions that are not frequently written in user's sources e.g

  ImGui_CreateContextEx
  ImGui_DestroyContextEx
  ImGui_ShowDemoWindowEx
  ImGui_ShowMetricsWindowEx
  ImGui_ShowAboutWindowEx
  ImGui_ShowStyleEditorEx
  ImGui_StyleColorsDarkEx
  ImGui_StyleColorsLightEx
  ImGui_StyleColorsClassicEx
  ImGuiInputTextCallbackData_InsertCharsEx
  ImColor_SetHSVEx
  ImColor_HSVEx

  (many others)

I would go as far as suggesting to consider including functions which are semi-frequently called but also frequently expanded on and easy to call with default parameters (no non-trivial types):

bool ImGui_BeginEx(const char* name, bool* p_open /* = NULL */, ImGuiWindowFlags flags /* = 0 */);

But we can iterate on the specific functions once we've done a first pass.

[ShironekoBen]

e2f03ea31a8f8e091bccdbdb13a363d01437a3c8 adds selective suppression of default argument helpers, with a few more additions to the list I found whilst scanning through the headers.

[ocornut]

NEVER MIND my post was looking at wrong copy of cimgui.h (download from Actions but may be opened wrong one?) Adding new functions now :)

~~Thanks. I can see the block:~~

    mod_generate_default_argument_functions.apply(dom_root,
                                                  # We ignore functions that don't get called often because in those
                                                  # cases the default helper doesn't add much value but does clutter
                                                  # up the header file
                                                  functions_to_ignore=[
                                                      'ImGui_LoadIniSettingsFromDisk',
                                                      'ImGui_LoadIniSettingsFromMemory',
                                                      'ImGui_SaveIniSettingsToMemory',
                                                      'ImGui_SaveIniSettingsToMemory',
                                                      'ImGui_SetAllocatorFunctions',
                                                      'ImGui_CreateContext',
                                                      'ImGui_DestroyContext',
                                                      'ImGui_ShowDemoWindow',
                                                      'ImGui_ShowMetricsWindow',
                                                      'ImGui_ShowAboutWindow',
                                                      'ImGui_ShowStyleEditor',
                                                      'ImGui_StyleColorsDark',
                                                      'ImGui_StyleColorsLight',
                                                      'ImGui_StyleColorsClassic',
[...]

But they seem to still appear in cimgui.h ?

CIMGUI_API void ImGui_StyleColorsDarkEx(ImGuiStyle* dst /* = NULL */);     // new, recommended style (default)
CIMGUI_API void ImGui_StyleColorsDark();                                   // Implied dst = NULL

So maybe something doesn't work with it currently?

[ocornut]

I have done a pass on cimgui.h and removed a few more Ex functions: a3c59ed There are probably other tweaks needed but for now it seems reasonable to close this. Thank you!