24U SimpleDialog Plug-In 3.1 Syntax

This file describes syntax of 24U SimpleDialog Plug-In's functions.
 

SDialog_Version ( { versionFormat } )
 
Returns version string of the active 24U SimpleDialog Plug-In, formatted as requested by the parameter. Use:

"short" to get just the version number
"long" to get the plug-in name followed by its version number
"platform" to get the platform of the code currently running
 

SDialog_Register ( registrationCode )
 
Attempts to unlock (register) your copy of 24U SimpleDialog Plug-In with the specified code. If the code 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 result when operation is not permitted.
 

SDialog_InputDialog ( dialogPrompt { ; dialogButtons { ; dialogItems... } } )
 
Shows a custom dialog.

dialogPrompt text to be displayed as dialog prompt
dialogButtons names of dialog buttons right to left, separated by ""
no dialogButtons parameter => dialog has no buttons
dialogButtons = "" => auto buttons OK and Cancel
dialogItems... = dialogItem { ; dialogItems... }
dialogItem = itemOptions { { ; valueIDs } ; valueList } ; currentValue
  valueIDs and valueList are used with itemKind "menu" otherwise they are not needed.
  currentValue can be empty string "" or 0 but it must be present for all itemKinds except "separator", where it must not be present.
itemOptions = itemKind { & "" & itemName } { & "" & moreOptions }
  for itemKinds "checkbox", "radio" and "image" itemName is required.
moreOptions = optionName & "=" & optionData { & "" & moreOptions }
itemKind = "text" | "password" | "radio" | "checkbox" | "menu"
    | "textarea" | "caption" | "separator" | "image" | "link"
  itemKinds "text", "password", "textarea", "caption" need text as currentValue parameter.
  itemKinds "checkbox" and "radio" have value 0 for unchecked, 1 for checked and 2 for mixed state (on Mac)
  itemKind "menu" needs either valid index (type Number) pointing into valueList or one line from valueList as currentValue
  itemKind "image" needs currentValue container with picture which is in png or jpeg format. Image proportions must be reasonable - resulting window must fit on screen otherwise error -5611 is returned
  itemKind "link" place URL into itemName and text which should be written into dialog to currentValue.
valueList = valueName { & "" & valueList }
moreOptions variants supported by SimpleDialog 3.1:
  "validation=NONE" (default)
  "validation=CREDIT_CARD"
  "validation=SSN"
  "validation=SIN"
  "validation=CZECH_ID"
  "validation=REGEXP" & "" & expression not containing newlines
  "validation=FILEMAKER" & "" & FileMaker Pro calc not containing newlines
    
    FileMaker Pro calc results:
      
      0 = invalid (beeps)
      non-zero number = valid
      text = error message to display
    
    If calculation has wrong syntax, error 1208 is returned.
  
  "lines=" ("textarea" item type only)
  "focus=1" (put initial focus on this item)
    If defined in more than one items - error -50, paramErr - is returned.

Returns zero if successful, negative error code in the case of failure.
 

SDialog_ProgressDialog ( { dialogNumber ; } action { ; actionData... } )
 
Shows a progress bar.

dialogNumber the number of progress bar if multiple progress bars needed.
action = "open" | "close" | "value" | "newmax" | "newmin" | "text" | "subtext" | "show" | "incr" | "stop" | "update" | "wait"

for "open", "show"

  actionData = { minValue ; maxValue { ; curValue } ; } { topMessage { ; bottomMessage } }
  Defaults: minValue = 0, maxValue = 100, curValue = minValue, topMessage = "", bottomMessage = ""

  note: if minValue = maxValue then indeterminate progress bar will be opened

for "close", "stop"

  actionData = { "all" } - Closes all active progress bars.

for "value", "newmax", "newmin", "text", "subtext":

  actionData = newValue

for "update":

  actionData = { { minValue ; maxValue ; } curValue ; } { { topMessage ; } bottomMessage }
  Defaults: unspecified value remains unchanged

for "incr":

  actionData = { increment } { ; topMessage }
  Defaults: increment = 1, unspecified value remains unchanged.

for "wait":

  actionData = seconds (accepting fractions)
  i.e. SDialog_ProgressDialog("wait"; 0.01) will wait 10 milliseconds

Returns 0 if successful, negative error code in the case of failure.
 

SDialog_Get ( selector { ; moreData } )

SDialog_Get ( "dialog-button" )
SDialog_Get ( "dialog-value" ; itemNumber )
SDialog_Get ( "dialog-text" ; itemNumber )
SDialog_Get ( "dialog-all-values" ; valueSeparator )
SDialog_Get ( "dialog-all-text" ; valueSeparator )

For text, textarea and password items, both "text" and "value" return the same result except that empty values are omitted by "dialog-all-text" while they still appear as empty values when using "dialog-all-values".

For radio buttons and checkboxes, "text" returns name of the radio or checkbox if it is selected and empty string if it is not. "value" returns 1 for selected, 0 for unselected and 2 for mixed state.

For menu, "text" returns name of the selected menu item, "value" returns its ID, where ID is 1-based index of the item or defined by user on input by valueIDs parameter.

For link, "text" returns URL if clicked otherwise "", "value" returns number of clicks on the link.

Separators, captions and images are omitted from the items order for the purpose of this function.

SDialog_Get ( "dialog-title" )
SDialog_Get ( "dialog-width" )
SDialog_Get ( "dialog-min_width" )
SDialog_Get ( "dialog-timeout" )
SDialog_Get ( "progress-title" )   

Returns respectible value.

SDialog_Get ( "dialog-position" )
SDialog_Get ( "progress-position" )   

Returns current dialog or progress dialog position as value list (i.e. "10060").

SDialog_Set ( selector { ; newValue } )

SDialog_Set ( "dialog-icon" ; iconSpecifier )
  iconSpecifier= iconID | iconName | iconData
  iconID= 0 | 1 | 2 | 3
  iconName= "stop" | "note" | "caution" | "question"  Note: 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.

SDialog_Set ( "dialog-title" ; text )
SDialog_Set ( "dialog-position" ; leftPosition ; topPosition )

  "DEFAULT"
can be used instead of leftPosition or topPosition

SDialog_Set ( "dialog-width" ; pixels )
SDialog_Set ( "dialog-min_width" ; pixels )
SDialog_Set ( "dialog-timeout" ; seconds )

SDialog_Set ( "default-button" ; index )
SDialog_Set ( "cancel-button" ; index )

  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.

SDialog_Set ( "progress-title" ; text )
SDialog_Set ( "progress-position" ; leftPosition ; topPosition )

SDialog_Set ( "clear" )

  Clear stored values from last dialog

SDialog_Set ( "reset" )

  Equal to deactivating and re-activating the plug-in