Returns version string of the active 24U SimpleDialog Plug-In, formatted as requested by the parameter.
versionFormat | Defines the format of the returned version. |
"short" | To get just the version number. Default value. |
"long" | To get the plug-in name followed by its version number. |
"platform" | To get the platform of the code currently running. |
This function is very important and it has the same output format in all 24U Plug-Ins. You should call this function every time you need to check if the plug-in is properly installed to the FileMaker. Even if the plug-in is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.
Returns requested version format or platform. If this function returns "?" than the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.
SDialog_Version( "long" )
This will return the plug-in name and its version. In this case it is "24U SimpleDialog Plug-In 3.1.2".
SDialog_Version( "platform" )
Returns "Mac OS X" or "Windows" depending on the platform the plug-in is currently running.
Attempts to unlock (register) your copy of 24U SimpleDialog Plug-In with the specified code.
originalSerialNumber | The original (non upgrade) code to unlock the full version of the plug-in. |
upgradeSerialNumber | The upgrade code to unlock the full version of the plug-in. |
If the code(s) is valid, 24U SimpleDialog Plug-In gets unlocked and stays in this state until you quit the FileMaker Pro application, deactivate the plug-in, or the registration code expires. While unlocked, 24U SimpleDialog Plug-In is fully functional and does not bother the user with a shareware reminder.
Returns a non-zero error code when the serial numbers are wrong if the numbers cannot be used. Returns 0 if the plug-in was successfully registered.
SDialog_Register( "SDI31J-CM244H-U4UGBN" )
This function will register the plug-in with serial number SDI31J-CM244H-U4UGBN. This method is useful when you register the plug-in with developer license but it can be used for end-user licenses as well.
SDialog_Register( "SDI28J-CM244H-U4UGBN SDI31J-BTPDSK-D3AJ9C" )
Use combination of serial numbers delimited by empty space to register using upgrade code. The first code must be the original one, all other codes should be upgrade codes.
SDialog_Register( "SDI11J-CM244H-U4UGBN SDI27J-BTPDSK-D3AJ9C SDI31J-5B4J7Z-W9KFNS" )
The example of using one original number and two upgrade numbers. The original is for version 1.1 and upgrades are for 2.7 and 3.1.
Note: All serial numbers here are only for demonstration purposes. They will not work in real plug-in.
Generates and shows custom dialog.
dialogPrompt | Text to be displayed as dialog prompt. |
dialogButtons | The names of dialog buttons, right to left, separated by "¶". If this parameter is omitted dialog will have no buttons. The default value is "" empty string which has special meaning: generate buttons Ok and Cancel. |
dialogItems | Description of each dialog field. The syntax is: dialogItems = itemOptions { { ; valueIDs } ; valueList } ; currentValue. See next table to learn how to construct |
itemOptions | ItemOption consists of itemKind, itemName and moreOptions parameters. All parameters are delimited by "¶". See next table for detailed description. |
valueIDs | Value list (delimited by "¶") containing IDs for pop-up menu. Use it only in pop-up menu. |
valueList | Value list (delimited by "¶") containing values for pop-up menu. Use it only in pop-up menu. |
currentValue | Default value for field. |
itemKind | The kind of field. The list of field kinds is on the next table. |
itemName | The name of the item. Usually it is a text label on the left of the field. |
moreOptions | Some special options. The format is always optionName=optionValue. See the last table to learn which options can be used in conjunction with which field. |
text | One line edit box. Use currentValue parameter to specify initial value. |
password | One line edit box which hides characters you are typing. Use currentValue parameter to specify initial value. |
radio | One radio button. CurrentValue 1 will set it, 0 will unset it. |
checkbox | One checkbox. CurrentValue 1 will set it, 0 will unset it. On Mac, CurrentValue 2 will set it to the mixed state. |
menu | Dialog pop-up menu. Use parameters valueList and valueIDs to set its contents. |
textarea | Multi-line edit box. Similar to text but the field can contain multiple lines and pressing enter while you are in textarea will not cause pressing default button. |
caption | Static text label. Use currentValue parameter to fill its contents. |
separator | Static line which divides parts of dialog. Do not use currentValue parameter. |
image | Image which should be placed to the dialog. The currentValue parameter should contain a container with image. |
link | The parameter itemName should contain URL and currentValue text description of the link. The link will be shown on the dialog with blue color. |
validation=NONE | Do not validate the field contents. This is the default value. |
validation=CREDIT_CARD | Check if text field contains credit card number. If validation fails dialog will not be closed by the default button. |
validation=SSN | Check if text field contains social security number. If validation fails dialog will not be closed by the default button. |
validation=SIN | Check if text field contains social insurance number. If validation fails dialog will not be closed by the default button. |
validation=CZECH_ID | Check if text field contains Czech ID number. If validation fails dialog will not be closed by the default button |
validation=REGEXP | Validate field content against regular expression. Write regular expression to the next line. If validation fails dialog will not be closed by the default button. |
validation=FILEMAKER | Validate field content against FileMaker calculation. To get the field content inside the calculation use "x" (see example). If calculation returns non-zero number it pass if it returns 0 it failed. If it returns text it will be shown inside small message box dialog. |
lines=<number> | Only for textarea field. It specifies how many lines should the field have. The minimum is 4. The Maximum is limited by display height. |
focus=1 | Put initial focus to this field. |
This is the main function of 24U SimpleDialog Plug-In. Various types of dialogs can created by this function. From simple ones similar to FileMaker built in function to very complex, form-like dialogs with pictures.
Function shows the dialog if parameters are correct and when the dialog is closed it returns 0. Otherwise it does not show dialog and it returns status code. See status code list at the end of this file.
SDialog_InputDialog( "Super Simple Dialog" )
This command will show the most simple "dialog". The dialog will have no buttons and no fields. It can be closed by esc key or you can set timeout to close via SDialog_Set( "dialog-timeout" ; timeout ).
|
|
SDialog_InputDialog( "Simple with buttons" ; "First¶Second" )
This will create simple dialog with no fields. The dialog will contain two buttons with labels "First" and "Second".
|
|
SDialog_InputDialog( "One text field" ; "" ; "text¶textField" ; "Initial Text" )
This will create a dialog with default buttons Ok and Cancel and one text field with label "textField" containing "Initial Text".
|
|
SDialog_InputDialog( "Complex dialog" ; "Ok¶Cancel¶Yes¶No¶WTF?" ; "caption¶Name:" ; "Very complex dialog" ; "text¶textField" ; "Important text field" ; "separator" ; "textArea¶Description¶lines=8" ; "Write description here..." ; "menu¶priority" ; "Very High¶High¶Normal¶Low¶Very Low" ; "Choose priority..." ; "checkbox¶Is it complex enough?" ; 0 )
This will create a complex dialog with several text boxes, separator, pop-up menu and five buttons. See how moreOptions parameter is used in textArea field.
|
|
SDialog_InputDialog( "Menu ValueID versus Value" ; "" ; "menu¶priority" ; "11¶8¶6¶4¶1" ; "Very High¶High¶Normal¶Low¶Very Low" ; "Choose priority..." )
This will create a simple dialog which contain a menu. You will see Very High, High etc. in menu but when you call SDialog_Get( "dialog-value" ; 1 ) you will obtain the number from valueIDs.
|
|
SDialog_InputDialog( "Enter your credit card number" ; "" ; "text¶Your Card:¶validation=CREDIT_CARD" ; "XXXX XXXX XXXX XXXX")
This will create a dialog which contain default buttons Ok and Cancel and input text field with validation for credit card number.
|
|
SDialog_InputDialog( "Enter more than 5 characters" ;""; "text¶Number¶validation=FILEMAKER¶If ( Length( x ) > 5 ; 1 ; 0)";"" )
This will create a dialog which contain default buttons Ok and Cancel and input text field with validation for text longer than 5 characters.
|
|
SDialog_InputDialog( "Enter a number" ; "" ; "text¶Number¶validation=REGEXP¶^[0-9]+$" ; "")
This will create a dialog which contain default buttons Ok and Cancel and input text field with easy regular expression validation for numbers.
|
|
Shows progress bar dialog.
dialogNumber | The index number of progress bar dialogs if multiple progress bar dialogs are needed. Indexing starts from 0 ( default value ) and is fully selectable by user. That means, user can open three progress dialogs with indexes 0,2,5 or 1,2,3 with the same final result. |
action | The action to do with selected progress dialog. |
actionData | Additional data for selected action. Mostly number or text values. |
"open" | Open default or selected progress bar dialog. |
"close" | Close default or selected progress bar dialog. ActionData may contain the index number of progress bar dialog user want to close. |
"show" | Open default or selected progress bar dialog. |
"stop" | Close default or selected progress bar dialog. ActionData may contain the index number of progress bar dialog user want to close. |
"value" | Set actionData value as a new current value for default or selected progress bar. The number should be the same or higher than current minimum and lower than current maximum value. |
"newmin" | Set actionData value as a new minimum value for default or selected progress bar. ActionData should contain new progress minimum. The number should be lower than current maximum value. |
"newmax" | Set actionData value as a new maximum value for default or selected progress bar. ActionData should contain new progress maximum. The number should be higher than current minimum value and its maximum number is 28278783. |
"text" | Set actionData text as a new message above the progress bar of default or selected progress dialog. |
"subtext" | Set actionData text as a new message under the progress bar of default or selected progress dialog. |
"incr" | Add actionData value to the current value of default or selected progress bar dialog. |
"update" | Update progress bar parameters for default or selected progress bar dialog. Works only when progress bar dialog is already open. |
"wait" | Set actionData as a wait time ( in seconds ) for default or selected progress bar dialog. ActionData number may be a fraction, for example 1.5 second can be set. |
actionData = { minValue ; maxValue { ; curValue } ; } { topMessage { ; bottomMessage } }
Note: if minValue is the same as maxValue then indeterminate progress bar will be opened.
actionData = { { minValue ; maxValue ; } curValue ; } { { topMessage ; } bottomMessage }
Note: if not specified, value or text remains unchanged.
minValue | Minimum value of the progress bar. If not set, default value 0 will be used. |
maxValue | Maximum value of the progress bar. If not set, default value 100 will be used. |
curValue | Current value of the progress bar. If not set, minValue will be used. |
topMessage | Message to be displayed above the progress bar. If not set, no message above progress bar will be visible. |
bottomMessage | Message to be displayed under the progress bar. If not set, no message under progress bar will be visible. |
0,1,2... | Index number of progress bar dialog that user want to close. If not set, default value 0 will be used. |
"all" | This text closes all active progress bar dialogs. |
actionData = { increment } { ; topMessage }
increment | Value, which will be added to the current value of default or selected progress bar dialog. If not set, default value 1 will be used. |
topMessage | Message to be displayed over the progress bar. If not set, message remains unchanged. |
Use this function to create and maintain a dialog with progress bar. More progress bar dialogs can be displayed at the same time. The number of visible progress bar dialogs is not limited, however it is recomended to display maximum 5 of them at the same time. If two or more progress bar dialogs are open at the same place, then the last opened dialog is on the top and visible.
Warning: It is highly recommended to use progress dialogs only in scripts. User has to ensure opening and closing progress bar dialog inside one script. If it is not ensured, FileMaker may lock or crash.
If parameters are correct the function will show progress dialog and immediately return 0. In the case of error, no progress is shown and status code is returned.
SDialog_ProgressDialog( "show" )
This command will show the most simple progress bar dialog. It will be opened with default values, as described above.
|
|
SDialog_ProgressDialog( 2 ; "show" ; 50 ; 250 ; 150 ; "My progress dialog." ; "This is a test." )
This command will open progress bar dialog with index number 2. It will be opened with user defined values, minValue = 50, maxValue = 250, curValue = 80, topMessage = "My progress dialog.", bottomMessage = "This is a text.".
|
|
SDialog_ProgressDialog( 5 ; "show" ; 100 ; 100 ; 0 ; "My indeterminate progress dialog." ; "This is a test of indeterminate progress dialog." )
This command will open indeterminate progress bar dialog with index number 5. It is used to show progress when user don't know progress bar range when opening the progress bar dialog.
|
|
SDialog_ProgressDialog( 2 ; "update" ; 50 ; 550 ; 250 ; "My updated progress dialog." ; "This is a updated test." )
This command will update progress bar dialog with index number 2.
|
|
SDialog_ProgressDialog( 4 ; "newmax" ; 500 )
This command will change maxValue for progress bar dialog with index number 4 to 500.
SDialog_ProgressDialog( "close" ; 2 )
This command will close progress bar dialog with index number 2.
SDialog_ProgressDialog( "close" ; "all" )
This command will close all actually opened progress dialog bars.
SDialog_ProgressDialog( 4 ; "incr" ; 5 )
This command will add 5 to the current value for the progress bar dialog with index number 4.
SDialog_ProgressDialog( "wait" ; 0.01 )
This command will pause progress bar dialog for 10 miliseconds.
Get parameters and dialog results.
selector | Selected parameter of last shown dialog. |
moreData | Specifies more exactly parameter user want to get. If parameter is an index, indexing starts from number 1. |
"dialog-button" | Get value of the dialog button. Index of this button must be specified in moreData parameter. |
"dialog-value" | Get value of the dialog field. Index of this field is specified in moreData parameter. |
"dialog-text" | Get text value of the dialog field. Index of this field is specified in moreData parameter. |
"dialog-all-values" | Get list of all dialog values separated by moreData parameter. If moredata is not specified, default delimiter will be used. |
"dialog-width" | Get dialog current width. |
"dialog-min_width" | Get dialog minimal width. |
"dialog-timeout" | Get dialog timeout. |
"dialog-title" | Get dialog title. |
"dialog-position" | Get dialog position in X¶Y format. |
"progress-title" | Get progress dialog title. |
"progress-position" | Get progress dialog position in X¶Y format. |
"itemNumber" | User want to get parameter of component with this index number. Indexing starts from number 1. |
"valueSeparator" | Specifies user defined delimiter. Default delimiter is "¶". |
This function is used to get important SimpleDialog Plug-In parameters and to obtain results of the last shown dialog.
Function returns required parameter. In the case of error the function will return negative status code.
SDialog_Get( "dialog-position" )
This command will return position of currently active dialog, f.e. 200¶160.
SDialog_Get( "dialog-width" )
This command will return width of the last dialog in pixels.
SDialog_Get( "dialog-value" ; 2 )
This command will return value of the field with index 2 from the last dialog.
SDialog_Get( "dialog-text" ; 5 )
This command will return text value of the field with index 5 from the last dialog.
SDialog_Get( "dialog-all-values" ; "")
This command will return all non-empty fields of the last dialog, separated by the string passed to it as a moreData parameter. In the case of checkboxes and radio buttons, name of every checked checkbox and radio button is returned.
Set parameters and dialog properties.
selector | Selected parameter of last shown dialog. |
newValue | The new value to be set for last shown dialog. |
iconSpecifier | The new icon to be set for last shown dialog. |
"dialog-icon" | Set dialog icon. More detailed description is in the table below. |
"dialog-title" | Set dialog title. |
"dialog-position" | Set newValue as a dialog position from left upper corner. Format of newValue should be "leftPosition ; topPosition". Values mustn't lie outside screen. "DEFAULT" can be used instead of leftPosition or topPosition and means in the middle of the screen. All edges of the dialog must lie inside screen. |
"dialog-width" | Set dialog current width in pixels. All edges of the dialog must lie inside screen, otherwise error message is returned. |
"dialog-min_width" | Set dialog minimal width in pixels. |
"dialog-timeout" | Set newValue as a dialog timeout in seconds. NewValue number may be a fraction, for example 5.7 seconds can be set. |
"default-button" | Set button with index newValue as a default button. |
"cancel-button" | Set button with index newValue as a cancel button. |
"progress-title" | Set progress dialog title. |
"progress-position" | Set newValue as a progress dialog position from left upper corner. Format of newValue should be "leftPosition ; topPosition". Values mustn't lie outside screen. "DEFAULT" can be used instead of leftPosition or topPosition and means in the middle of the screen. All edges of the dialog must lie inside screen. |
"clear" | Clear stored values from last dialog. |
"reset" | Equal to deactivating and re-activating the plug-in. |
iconSpecifier = iconID | iconName | iconData
"iconID" | Icon index number of the system icons. Possible values are 0 | 1 | 2 | 3. |
"iconName" | Name of the system icons. Possible values are "stop" | "note" | "caution" | "question". Note that question icon is available only in Windows. |
"iconData" | Png or jpeg picture in container. Do not use too large pictures. If Window cannot fit on screen error -5611 is returned. |
By this function SimpleDialog parameters can be set. You can also use it to adjust next dialog properties.
Function returns the value which was really set. If this value is different from your original newValue the function cannot set your value for some reason. In the case of error the function will return negative status code.
SDialog_Set( "dialog-title" ; "My custom title" ) and SDialog_InputDialog( "Simple with buttons" ; "First¶Second" )
These commands will set dialog title and then open a simple dialog.
|
|
SDialog_Set( "dialog-position" ; 500 ; "DEFAULT" )
This command will set dialog position to 500 in X axis and to the default position in Y axis.
SDialog_Set( "dialog-width" ; 800 )
This command will set dialog width to 800 pixels.
SDialog_Set( "dialog-icon" ; "stop" ) and SDialog_InputDialog( "Simple with buttons" ; "First¶Second" )
These commands will set stop icon and then open a simple dialog.
|
|
SDialog_Set( "dialog-timeout" ; 10 )
This command will set dialog timeout to 10 second. When user inactive, dialog will disappear after this time.
SDialog_Set( "default-button" ; 1 )
This command will set button with index 1 as a default dialog button.Use 1-based index to specify which button on the next dialog window should be default (has initial focus and is pressed on enter) and cancel (is pressed on Esc and Command+.).
The initial values are 1 for default and 2 for cancel button.
If index is out of bounds no button will be default or cancel. I.e. if index for default button is set to 0 no button will be the default one.
-50 | Means paramErr, SDialog_InputDialog has wrong parameters. |
-5611 | Resulting window is to large to fit the screen. This error is usually returned if you try to insert too large picture into dialog. |
1208 | Returned when syntax of your validation calculation is wrong.. |