24U SimpleDialog Plug-In 3.1.2 Syntax

SDialog_Version( { versionFormat } )

Returns version string of the active 24U SimpleDialog Plug-In, formatted as requested by the parameter.

Parameters

versionFormatDefines the format of the returned version.

Parameter values for versionFormat

"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.

Description

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.

Result

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.

Examples

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.

SDialog_Register( originalSerialNumber { & " " & upgradeSerialNumber... } )

Attempts to unlock (register) your copy of 24U SimpleDialog Plug-In with the specified code.

Parameters

originalSerialNumberThe original (non upgrade) code to unlock the full version of the plug-in.
upgradeSerialNumberThe upgrade code to unlock the full version of the plug-in.

Description

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.

Result

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.

Examples

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.

SDialog_InputDialog( dialogPrompt { ; dialogButtons { ; dialogItems... } } )

Generates and shows custom dialog.

Parameters

dialogPromptText to be displayed as dialog prompt.
dialogButtonsThe 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.
dialogItemsDescription of each dialog field. The syntax is: dialogItems = itemOptions { { ; valueIDs } ; valueList } ; currentValue. See next table to learn how to construct

Parts of dialogItems

itemOptionsItemOption consists of itemKind, itemName and moreOptions parameters. All parameters are delimited by "¶". See next table for detailed description.
valueIDsValue list (delimited by "¶") containing IDs for pop-up menu. Use it only in pop-up menu.
valueListValue list (delimited by "¶") containing values for pop-up menu. Use it only in pop-up menu.
currentValueDefault value for field.

Parts of itemOptions

itemKindThe kind of field. The list of field kinds is on the next table.
itemNameThe name of the item. Usually it is a text label on the left of the field.
moreOptionsSome special options. The format is always optionName=optionValue. See the last table to learn which options can be used in conjunction with which field.

Possible values for itemKind. This means: supported field types.

textOne line edit box. Use currentValue parameter to specify initial value.
passwordOne line edit box which hides characters you are typing. Use currentValue parameter to specify initial value.
radioOne radio button. CurrentValue 1 will set it, 0 will unset it.
checkboxOne checkbox. CurrentValue 1 will set it, 0 will unset it. On Mac, CurrentValue 2 will set it to the mixed state.
menuDialog pop-up menu. Use parameters valueList and valueIDs to set its contents.
textareaMulti-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.
captionStatic text label. Use currentValue parameter to fill its contents.
separatorStatic line which divides parts of dialog. Do not use currentValue parameter.
imageImage which should be placed to the dialog. The currentValue parameter should contain a container with image.
linkThe parameter itemName should contain URL and currentValue text description of the link. The link will be shown on the dialog with blue color.

Possible values for moreOptions.

validation=NONEDo not validate the field contents. This is the default value.
validation=CREDIT_CARDCheck if text field contains credit card number. If validation fails dialog will not be closed by the default button.
validation=SSNCheck if text field contains social security number. If validation fails dialog will not be closed by the default button.
validation=SINCheck if text field contains social insurance number. If validation fails dialog will not be closed by the default button.
validation=CZECH_IDCheck if text field contains Czech ID number. If validation fails dialog will not be closed by the default button
validation=REGEXPValidate 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=FILEMAKERValidate 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=1Put initial focus to this field.

Description

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.

Result

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.

Examples

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.

SDialog_ProgressDialog( { dialogNumber ; } action { ; actionData... } )

Shows progress bar dialog.

Parameters

dialogNumberThe 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.
actionThe action to do with selected progress dialog.
actionDataAdditional data for selected action. Mostly number or text values.

Possible values for action.

"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.

Obligatory format of actionData for action "open","show".

actionData = { minValue ; maxValue { ; curValue } ; } { topMessage { ; bottomMessage } }

Note: if minValue is the same as maxValue then indeterminate progress bar will be opened.

Obligatory format of actionData for action "update".

actionData = { { minValue ; maxValue ; } curValue ; } { { topMessage ; } bottomMessage }

Note: if not specified, value or text remains unchanged.

Possible values to be set for actionData for action "open","show","update".

minValueMinimum value of the progress bar. If not set, default value 0 will be used.
maxValueMaximum value of the progress bar. If not set, default value 100 will be used.
curValueCurrent value of the progress bar. If not set, minValue will be used.
topMessageMessage to be displayed above the progress bar. If not set, no message above progress bar will be visible.
bottomMessageMessage to be displayed under the progress bar. If not set, no message under progress bar will be visible.

Possible values to be set for actionData for action "close","stop".

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.

Obligatory format of actionData for action "incr".

actionData = { increment } { ; topMessage }

Possible values to be set for actionData for action "incr".

incrementValue, which will be added to the current value of default or selected progress bar dialog. If not set, default value 1 will be used.
topMessageMessage to be displayed over the progress bar. If not set, message remains unchanged.

Description

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.

Result

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.

Examples

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.

SDialog_Get( selector { ; moreData } )

Get parameters and dialog results.

Parameters

selectorSelected parameter of last shown dialog.
moreData Specifies more exactly parameter user want to get. If parameter is an index, indexing starts from number 1.

Possible values for selector.

"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.

Possible values for moreData.

"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 "¶".

Description

This function is used to get important SimpleDialog Plug-In parameters and to obtain results of the last shown dialog.

Result

Function returns required parameter. In the case of error the function will return negative status code.

Examples

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.

SDialog_Set( selector { ; newValue or iconSpecifier } )

Set parameters and dialog properties.

Parameters

selectorSelected parameter of last shown dialog.
newValueThe new value to be set for last shown dialog.
iconSpecifierThe new icon to be set for last shown dialog.

Possible values for selector.

"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 format and values for selector "dialog-icon".

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.

Description

By this function SimpleDialog parameters can be set. You can also use it to adjust next dialog properties.

Result

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.

Examples

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.

Status code list for SDialog_InputDialog.

-50Means paramErr, SDialog_InputDialog has wrong parameters.
-5611Resulting window is to large to fit the screen. This error is usually returned if you try to insert too large picture into dialog.
1208Returned when syntax of your validation calculation is wrong..