Pages: 1
  Print  
Author Topic: UPDATE: Cross-Platorm Widgets API Complete with Full UTF-8 Support  (Read 893 times)
Offline (Male) time-killer-games
Posted on: July 02, 2019, 02:00:48 PM

Contributor
Location: Virginia Beach
Joined: Jan 2013
Posts: 1157

View Profile Email
Platform: Windows
API: Win32 (VC++)




Platform: macOS
API: Cocoa (Obj-C)




Platform: Ubuntu
API: Zenity (GTK)




Platform: KDE neon
API: KDialog (KDE)




What's Changed?

First of all, for those of you targeting Linux who aren't aware, click here 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.

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
« Last Edit: November 08, 2019, 12:29:43 PM by time-killer-games » Logged
Offline (Male) time-killer-games
Reply #1 Posted on: July 04, 2019, 11:35:16 AM

Contributor
Location: Virginia Beach
Joined: Jan 2013
Posts: 1157

View Profile Email
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.
Logged
Offline (Male) time-killer-games
Reply #2 Posted on: September 10, 2019, 10:15:54 PM

Contributor
Location: Virginia Beach
Joined: Jan 2013
Posts: 1157

View Profile Email
I updated the screenshots to reflect some new functionality that is soon to be added to ENIGMA, and has already been added to my GameMaker extension's equivalent code. Please do not be confused, these are upcoming features, and they are not available yet. But it won't take long because most of the code is already written and will need minimal tweaking. These changes only apply to the macOS Cocoa and Linux X11 Widgets Systems. In the case of Linux, only the KDialog Widgets are effected. I updated the Zenity screenshots too, but only because the older ones were taken on a version of Ubuntu that had problems updating to Bionic Beaver, so there were some visual flaws with it such as using Unity instead of GNOME still, for the desktop environment, which was a huge eye-sore for me.

Changes Include:

- [macOS] A dirty subclass hack which makes some macOS dialogs display as sheets; while normally sheet dialogs are async, the subclass forces them to be modal, (unless you run the async equivalents via the async extension ofc). This relies on a small Objective-C++ *.mm source file that was not originally written by me nor was it written for ENIGMA in specific, however it was licensed under BSD, so it is permissive and compatible with both our GPL and upcoming linking exception. The dialogs that will be displayed as sheets include show_message(), show_message_cancelable(), show_question(), show_question_cancelable(), show_attempt(), show_error(), get_string(), get_password(), get_integer(), and get_passcode(). More information on what exactly a sheet dialog even is and its distinction from a child window dialog may be read in the next bullet point found below.

- [macOS] As for the rest of the macOS dialog functions, they will not be sheets, however, they will be child windows once this update is released. Child windows by Apple's definition is a window that moves when it's parent is being dragged by the title bar to move, relative to where the parent is being dragged. However, the child window will move independent to the parent window's position if the child window is dragged by the title bar to move and the parent window will stay at the same position uneffected. So, these dialogs are child windows, they will inherit this behavior. Sheet dialogs are almost no different except they can't have a title bar so sheet dialogs will always be at a position relative to the window they are attached to, more specifically at the top-center of the window it is attached to, i.e. the parent. The child window dialogs include the file, folder, and color pickers.

- [macOS] The functions widget_get_icon() and widget_set_icon() will be added, which will allow for setting an icon for the dialogs should you want an icon to be displayed that is different from the default, which is the icon you have set for your game in the Info.plist of your macOS App Bundle. This will require you to bundle your game manually as normal. Only *.PNG is supported. You can technically use other formats as well, such as *.ICNS but formats such these won't be compatible with the Linux X11 Widgets; not cross-platform.

- [Linux X11 (KDialog)] Once this update is released you'll notice that KDialog will have a more appealing icon in the title bar of each dialog that will either match the icon used in the client area of the dialog or the game's custom icon if there is no icon in the window's client area. This custom icon can be set once another important update of mine is merged. If you want the dialogs to have a different icon in the title bar than the one used for the game window, this update, as stated in the previous bullet point, will also introduce the new functions widget_get_icon() and widget_set_icon() to get/set the current icon to use for the dialogs. Again, PNG-only. There might be other formats supported but like with Mac they probably aren't going to be supported in a cross-platform manner.
« Last Edit: September 10, 2019, 10:24:35 PM by time-killer-games » Logged
Pages: 1
  Print