ENIGMA Forums

General fluff => Announcements => Topic started by: time-killer-games on July 02, 2019, 02:00:48 pm

Title: UPDATE: Cross-Platorm Widgets API Complete with Full UTF-8 Support
Post by: time-killer-games on July 02, 2019, 02:00:48 pm
Platform: Windows
API: Win32 (VC++)


(https://i.imgur.com/9KbQWD9.gif)

Platform: macOS
API: Cocoa (Obj-C)


(https://i.imgur.com/hjDkmCz.gif)

Platform: Ubuntu
API: Zenity (GTK+)


(https://i.imgur.com/uBlwHAM.gif)

Platform: KDE neon
API: KDialog (Qt5)


(https://i.imgur.com/AAN4INH.gif)

What's Changed?

First of all, for those of you targeting Linux who aren't aware, click here (https://enigma-dev.org/docs/Wiki/Dialogs#Zenity_Widgets) for the  terminal commands needed to install the appropriate packages and dependencies used in the Linux widget systems - Zenity and KDialog. Installation instructions will be different depending on your Linux distro. Other info is there that Linux and non-Linux users alike may benefit from.

We recently updated Windows Widgets to include the same GML and EDL function set as the other actively supported systems - Cocoa Widgets for macOS, Zenity for Linux distro's using GTK+ for windowing, and KDialog for Linux distro's using KDE for windowing. Windows Widgets also now has full UTF-8 support with these same functions, just as the other systems and platforms already supported. This means we now have a fully cross-platform API that will work seamlessly on all platforms and windowing systems we support.

If you want to use these same exact functions in GameMaker Studio 2 or Unity, you may override GameMaker's implementations with these functions using my Dialog Module extension, or the Unity plugin, which are both free and open source. MIT License. Links to GameMaker Marketplace, Unity, and itch.io as well as GitHub and SourceForge here (http://dialogmodule.weebly.com/).

Known Issues

- get_open_filenames() and get_open_filenames_ext() can only return a maximum of 3 files from a given drive's root, so if your files are selected directly from C:\, I:\, etc. without being within a subfolder or subfolders of the given drive, i.e. Program Files, Users, etc. you will not be able to return more than 3 files regardless of how man files you actually selected, if not in drive's root, you will be able to select up to the buffer limit. This is a Windows-only issue. Mac and Linux have no limit to the amount of files you may select. I don't know how to fix this and will need help with it. I don't know what the source of the problem is with Windows multi-select and how I chose to write it.

- get_directory() and get_directory_alt() do not work on Windows XP, this will be fixed in a patch which will check the current Windows Version and if Windows XP then use an older API to take care of the same desired effect - selecting a directory. This will be fixed at some point. I have other priorities ahead of this one right now.

- get_string(), get_password(), get_integer(), and get_passcode() do not resize to fit the contents of the string provided by the first argument to each function. Windows-only  bug. Instead, the string will get truncated if long enough. This will probably be fixed when we support the Visual Studio compiler, CMake, so that I may use the same InputBox API I use in the GameMaker extension equivalent which does not have this bug.

- TODO: I need to wipe Josh's ass for him by renaming the current show_error() implementation to show_error_retriable(), this will eliminate the need for the second argument and it will be removed, and also this will mean Josh will let me give the function a return value, like what the GameMaker extension equivalent currently does. Then I'll write a new show_error() implementation from scratch that will only have a 'Abort' and an 'Ignore' button when non-fatal, and just an 'Abort' button when fatal. This can't be done until KDialog support's changing the 'OK' button's text on a single button dialog. It's on KDialog's roadmap, but KDE developers have yet to add it.

Cheers,
Samuel
Title: Re: UPDATE: Cross-Platorm Widgets API Complete with Full UTF-8 Support
Post by: time-killer-games on July 04, 2019, 11:35:16 am
List of Newly Cross-Platform Functions

GML Function:
real show_message(string str)
   
Description:
​Displays a modal information message box with an "OK" button to make it close. When the dialog Is closed, it will return 1 and go back to the main application. The developer may set the message text using the argument.

EDL Function:
real show_message_cancelable(string str)
   
Description:
​Displays a modal information message box with an "OK" button to make it close. Clicking "OK" will return 1, and clicking "Cancel" will return -1. When the function returns, the dialog closes, and the user is then taken back to the main application. The developer may set the message text using the argument.

GML Function:
real show_question(string str)
   
Description:
​Displays a modal question message box with a "Yes" and a "No" button, for the user to choose which to click as their answer. When "Yes" is clicked, 1 is returned or if "No" is clicked, zero is returned. The user will then be sent back to the main application. The developer may set the message text using the argument.

EDL Function:
real show_question_cancelable(string str)
   
Description:
​Displays a modal question message box with a "Yes", a "No", and a "Cancel" button, for the user to choose which to click as their answer. When "Yes" is clicked, 1 is returned. If "No" is clicked, zero is returned. If "Cancel" is clicked, -1 is returned. The developer may set the message text using the argument.

EDL Function:
real show_attempt(string str)
   
Description:
Displays a modal error message box which will prompt the user as to whether they want to retry a specific action that previously just failed, or cancel the operation. The "Retry" button returns zero, and the "Cancel" button returns -1. The developer may use the argument to specify a description of the action that just failed as the error.

GML Function:
real show_error(string str,real abort)
   
Description:
Displays a modal error message box which will prompt the user as to whether they want to abort the application, retry the action that errored, or ignore the error. The first argument is the error message text. The second argument is for whether the error message is fatal, meaning it will abort regardless of the button clicked. When the error is not fatal, only the "Abort" button will force the application to close. When non-fatal, clicking the "Retry" button will cause the function to return zero, and the "Ignore" button returns -1. When the application aborts, there is no return value to be retrieved. In ENIGMA, this function has no return value no matter what because Josh is a bitch.

GML Function:
string get_string(string str,string def)
   
Description:
Displays a modal string input box with the message text defined in the first argument, and the default string to show in the text box used as the second argument. There is an "OK" button, that when clicked the dialog closes and returns the string that is left in the text box. If "Cancel" was clicked, the dialog closes and returns an empty string.

EDL Function:
string get_password(string str,string def)
   
Description:
​Displays a modal string input box with the message text defined in the first argument, and the default string to show in the text box used as the second argument. There is an "OK" button, that when clicked the dialog closes and returns the string that is left in the text box. If "Cancel" was clicked, the dialog closes and returns an empty string. Text entry is hidden.

GML Function:
real get_integer(string str,real def)
   
Description:
Displays a modal number input box with the message text defined in the first argument, and the default number in the text box used as the second argument. There is an "OK" button, that when clicked the dialog closes and returns the number that is left in the text box. If "Cancel" was clicked, the dialog closes and returns zero. If a value that is not recognized as a valid number is entered, zero is always returned. The default number and the number returned cannot exceed 15 digits, therefore it will always be limited to a value from -999999999999999 to 999999999999999. ENIGMA allows you to go beyond these numbers by displaying scientific notation, because Josh likes stupid shit.

EDL Function:
real get_passcode(string str,real def)
   
Description:
Displays a modal number input box with the message text defined in the first argument, and the default number in the text box used as the second argument. There is an "OK" button, that when clicked the dialog closes and returns the number that is left in the text box. If "Cancel" was clicked, the dialog closes and returns zero. If a value that is not recognized as a valid number is entered, zero is always returned. The default number and the number returned cannot exceed 15 digits, therefore it will always be limited to a value from -999999999999999 to 999999999999999. Text entry is hidden. ENIGMA allows you to go beyond these numbers by displaying scientific notation, because Josh likes stupid shit.

GML Function:
string get_open_filename(string filter,string fname)
   
Description:
Displays a modal single file selection dialog using the given filter which is used like "Description1|Extension1|Description2|Extension2A;Extension2B" where the earlier is the description of the file filter and the latter is the extension pattern. The descriptions and extension patterns are separated by a vertical slash character "|", and if one of the descriptions describe multiple file patterns, separate the file patterns with a semicolon. An example of a filter argument can be "Image Files|*.png;*.jpeg;*.jpg;*.gif" which will allow selection of a single png, jpeg, jpg, or gif file. The second argument is the default file name for the dialog to have in the text box. When "Cancel" is chosen an empty string is returned, otherwise the file selected is returned.

GML Function:
string get_open_filename_ext(string filter,string fname,string dir,string title)
   
Description:
Displays a modal single file selection dialog using the given filter which is used like "Description1|Extension1|Description2|Extension2A;Extension2B" where the earlier is the description of the file filter and the latter is the extension pattern. The descriptions and extension patterns are separated by a vertical slash character "|", and if one of the descriptions describe multiple file patterns, separate the file patterns with a semicolon. An example of a filter argument can be "Image Files|*.png;*.jpeg;*.jpg;*.gif" which will allow selection of a single png, jpeg, jpg, or gif file. The second argument is the default file name for the dialog to have in the text box. When "Cancel" is chosen an empty string is returned, otherwise the file selected is returned. The third argument specifies the default directory for the dialog open in. The last argument changes the window title text.

EDL Function:
string get_open_filenames(string filter,string fname)
   
Description:
Displays a modal multiple file selection dialog using the given filter which is used like "Description1|Extension1|Description2|Extension2A;Extension2B" where the earlier is the description of the file filter and the latter is the extension pattern. The descriptions and extension patterns are separated by a vertical slash character "|", and if one of the descriptions describe multiple file patterns, separate the file patterns with a semicolon. An example of a filter argument can be "Image Files|*.png;*.jpeg;*.jpg;*.gif" which will allow selection of one or more png, jpeg, jpg, or gif files. The second argument is the default file name for the dialog to have in the text box. When "Cancel" is chosen an empty string is returned, otherwise the file(s) selected are returned.

EDL Function:
string get_open_filenames_ext(string filter,string fname,string dir,string title)
   
Description:
Displays a modal multiple file selection dialog using the given filter which is used like "Description1|Extension1|Description2|Extension2A;Extension2B" where the earlier is the description of the file filter and the latter is the extension pattern. The descriptions and extension patterns are separated by a vertical slash character "|", and if one of the descriptions describe multiple file patterns, separate the file patterns with a semicolon. An example of a filter argument can be "Image Files|*.png;*.jpeg;*.jpg;*.gif" which will allow selection of one or more png, jpeg, jpg, or gif files. The second argument is the default file name for the dialog to have in the text box. When "Cancel" is chosen an empty string is returned, otherwise the file(s) selected are returned. The third argument specifies the default directory for the dialog open in. The last argument changes the window title text.

GML Function:
string get_save_filename(string filter,string fname)
   
Description:
Displays a modal single file "save as" dialog using the given filter which is used like "Description1|Extension1|Description2|Extension2A;Extension2B" where the earlier is the description of the file filter and the latter is the extension pattern. The descriptions and extension patterns are separated by a vertical slash character "|", and if one of the descriptions describe multiple file patterns, separate the file patterns with a semicolon. An example of a filter argument can be "Image Files|*.png;*.jpeg;*.jpg;*.gif" which will allow selection of a single png, jpeg, jpg, or gif file. The second argument is the default file name for the dialog to have in the text box. When "Cancel" is chosen an empty string is returned, otherwise the file name entered or selected is returned.

GML Function:
string get_save_filename_ext(string filter,string fname,string dir,string title)
   
Description:
Displays a modal single file "save as" dialog using the given filter which is used like "Description1|Extension1|Description2|Extension2A;Extension2B" where the earlier is the description of the file filter and the latter is the extension pattern. The descriptions and extension patterns are separated by a vertical slash character "|", and if one of the descriptions describe multiple file patterns, separate the file patterns with a semicolon. An example of a filter argument can be "Image Files|*.png;*.jpeg;*.jpg;*.gif" which will allow selection of a single png, jpeg, jpg, or gif file. The second argument is the default file name for the dialog to have in the text box. When "Cancel" is chosen an empty string is returned, otherwise the file name entered or selected is returned. The third argument specifies the default directory for the dialog open in. The last argument changes the window title text.

GML Function:
string get_directory(string dname)
   
Description:
Displays a modal single folder selection dialog. Use the argument to define the default place for the dialog to open in. When "Cancel" is chosen, an empty string is returned, otherwise the directory selected is returned, including the trailing slash at the end.

GML Function:
string get_directory_alt(string capt,string root)
   
Description:
Displays an alternative modal single folder selection dialog. Use the first argument to define the title caption of the dialog. Use the second argument to define the default place for the dialog to open in. When "Cancel" is chosen, an empty string is returned, otherwise the directory selected is returned, including the trailing slash at the end.

GML Function:
real get_color(real defcol)
   
Description:
Displays a modal color selection dialog. When the "OK" button is clicked, the color that is selected is returned, and if "Cancel" is clicked, the value -1 is returned. Use the argument to specify the default color to be selected when the dialog first opens.

EDL Function:
real get_color_ext(real defcol,string title)
   
Description:
Displays a modal color selection dialog. When the "OK" button is clicked, the color that is selected is returned, and if "Cancel" is clicked, the value -1 is returned. Use the first argument to specify the default color to be selected when the dialog first opens. Use the second argument to change the default title bar caption.

EDL Function:
string message_get_caption()

Description:
Gets the custom window title bar caption text previously set by message_set_caption(), and returns an empty string if there was no custom window title bar caption text previously set.

EDL Function:
string message_set_caption(string str)

Description:
Sets the custom window title bar caption text of message, question, input, and error-like dialogs. Use an empty string for the argument to reset the value to its default text, which will either be the main game's name/title, or "Error", depending on the type of dialog.