File Dialog-7.lua

Functions

Dialog:_selectFolder (param, props, name, save) Allows user to select a folder by way of the "open file" dialog box.
Dialog:autoWrap (m, maxWidth) Auto-wrap text to fit in specified width.
Dialog:btn (label, verb, memorable) Convenience function to make a button ultimately bound for lr-dialog box.
Dialog:buttons (shortcut, cancelNotMemorable) get specified dialog buttons.
Dialog:forgetAnswer (memKey) Forget previously remembered answer.
Dialog:getAnswer (apkRaw) Determine if action already remembered, and hence there will be no prompt.
Dialog:getAnswer (apkRaw) Determine if action already remembered, and hence there will be no prompt.
Dialog:getComboBoxSelection (param) Fetch a user selection from a combo-box.
Dialog:getNumericInput (param) Prompt user to enter a string via simple dialog box.
Dialog:getPopupMenuSelection (param) Fetch a user selection from a popup-menu.
Dialog:getSimpleTextInput (param) Prompt user to enter a string via simple dialog box.
Dialog:isOk (msg, ...) Determine if its OK with the user to do something, or not - aLways prompts.
Dialog:isOkOrDontAsk (msg, id) Prompt user to continue or not, with option to remember decision.
Dialog:isYes (msg, ...) Determine if its OK with the user to do something, or not - aLways prompts.
Dialog:messageWithOptions (message, ...) Displays a message for the user to see, and provides options for the user to choose.
Dialog:new (t) Constructor for new instance.
Dialog:newClass (t) Constructor for extending class.
Dialog:presentFloatingDialog (params) Present non-modal (floating dialog), in "like" fashion in Lr4 (not officially supported) as Lr5 (1st version in which offcially supported).
Dialog:presentModalFrame (args, returnAllButtons) Presents a modal dialog without an OK button.
Dialog:promptForTargetPhotos (prefix, returnComponents, call, viewItems, accItems, noApk) Function to prompt for initiation of operation to be performed on selected photo(s), filmstrip, or whole catalog.
Dialog:putTextOnClipboard (param) Klugerian function whose impetus was to support log file contents copy-n-paste to email.
Dialog:quickTips (strTbl, oneEol) Present quick-tips dialog box.
Dialog:rememberAnswer (memKey, answer) Remember answer.
Dialog:selectFile (param, props, name) Allows user to select a file by way of the "open file" dialog box.
Dialog:selectFolder (param, props, name) Allows user to select a folder by way of the "open file" dialog box.
Dialog:selectSaveFile (param, props, name) Allows user to select a file by way of the "save file" dialog box.
Dialog:selectSaveFolder (param, props, name) Allows user to select a folder by way of the "save file" dialog box.
Dialog:showInfoAndRememberAnswer (msg, memKey, memText, okButton, cancelButton, otherButton) Show information, and remember answer for a while.
Dialog:yesNo (cancelNotMemorable, shortcut) get specified dialog buttons.
Dialog:yesNoCancel (shortcut) get specified dialog buttons.


Functions

Dialog:_selectFolder (param, props, name, save)
Allows user to select a folder by way of the "open file" dialog box.

Parameters:

  • param: table - same as run-open-panel, except all are optional:
    • title
    • prompt ("OK" button label alternative) - NOT supported.
    • can-create-directories
    • file-types (string or array of strings, optional): prefix with '.' for best results.
    • initial-directory
  • props: Properties into which folder path will be written.
  • name: Name of property to write.
  • save:

Usage:

  • Folder is written to named property if provided, in which case return value is typically ignored.
  • Internally wrapped with error handling context for ready use as button action function or the like... 

Return value:

    string: path of folder, else nil if user cancelled.
Dialog:autoWrap (m, maxWidth)
Auto-wrap text to fit in specified width.

Parameters:

  • m: text to wrap.
  • maxWidth: maximum len in real string-len characters.

Usage:

    Assumes single line-feed as term char. 

Return values:

  1. wrapped text (string)
  2. number of lines required to display wrapped text.
Dialog:btn (label, verb, memorable)
Convenience function to make a button ultimately bound for lr-dialog box.

Parameters:

  • label: (string, required) button text
  • verb: (string, required) return value
  • memorable: (boolean, default=true) pass false to make otherwise memorable buttons not memorable.
Dialog:buttons (shortcut, cancelNotMemorable)
get specified dialog buttons.

Parameters:

  • shortcut: (string, required) specification keys:
    YesNo - 'ok' => Yes, 'cancel' => No.
  • cancelNotMemorable:
Dialog:forgetAnswer (memKey)
Forget previously remembered answer.

Parameters:

  • memKey:

Usage:

    Call before a loop where you always want user to answer the first time, even if not subsequently. 
Dialog:getAnswer (apkRaw)
Determine if action already remembered, and hence there will be no prompt.

Parameters:

  • apkRaw:
Dialog:getAnswer (apkRaw)
Determine if action already remembered, and hence there will be no prompt.

Parameters:

  • apkRaw:
Dialog:getComboBoxSelection (param)
Fetch a user selection from a combo-box.

Parameters:

  • param: Table with the following elements:
    • title - goes on window frame
    • subtitle - static text banner goes in content at top.
    • items - for combo box.

Usage:

  • self-wrapped.
  • multiple selection is not supported. 

Return value:

    string, or nil for cancel.
Dialog:getNumericInput (param)
Prompt user to enter a string via simple dialog box.

Parameters:

  • param: table with the following elements:
    • title - window frame title
    • subtitle - static text banner at top of content.

Usage:

    self-wrapped. 

Return value:

    string, or nil for cancelled.
Dialog:getPopupMenuSelection (param)
Fetch a user selection from a popup-menu.

Parameters:

  • param: Table with the following elements:
    • title - goes on window frame
    • subtitle - static text banner goes in content at top.
    • items - for popup menu.

Usage:

  • self-wrapped.
  • multiple selection is not supported. 

Return values:

  1. selected item's value, or nil for cancel.
  2. msg - in case of failure.
Dialog:getSimpleTextInput (param)
Prompt user to enter a string via simple dialog box.

Parameters:

  • param: table with the following elements:
    • title - window frame title
    • subtitle - static text banner at top of content.
    • init - initial value optional.
  • width_in_chars - edit-field width (in fat characters).
  • height_in_lines - edit-field height (in lines).
  • Usage:

      self-wrapped. 

    Return value:

      string, or nil for cancelled.
    Dialog:isOk (msg, ...)
    Determine if its OK with the user to do something, or not - aLways prompts.

    For more complex prompts, use confirm box directly.

    Parameters:

    • msg: string message.
    • ...:

    Usage:

      buttons are OK/Cancel. 

    Return value:

      boolean true iff is ok.
    Dialog:isOkOrDontAsk (msg, id)
    Prompt user to continue or not, with option to remember decision.

    Parameters:

    • msg: string message.
    • id: string key for dismissal option.

    Usage:

      Same as is-ok plain, except with option to suppress next time. 

    Return value:

      boolean true iff is user answered ok this time or previously...
    Dialog:isYes (msg, ...)
    Determine if its OK with the user to do something, or not - aLways prompts.

    For more complex prompts, use confirm box directly.

    Parameters:

    • msg: string message.
    • ...:

    Usage:

      buttons are Yes/No. 

    Return value:

      boolean true iff is ok.
    Dialog:messageWithOptions (message, ...)
    Displays a message for the user to see, and provides options for the user to choose.

    Parameters:

    • message: ( string or table, default="" )
      If string
      - message is info-type format string.
      If table
      - message table contains the following members:
      - info (string) info format string, or
      - warning (string) warning format string, or
      - error (string) error format string.
      - actionPrefKey (string, default=nil ) for "do not show" informational messages only (never warning or error messages).
      - This should be a user friendly string since these prefs are now individual clearable by user via combo_box. - buttons ( table, default = nil ) button entries are tables with members:
      label (string, required) button display text
      verb (string, required) button return text
      forget (string, default=false) whether button must not be remembered (only applies if actionPrefKey is passed),
      In which case, at least one button must not be forgetable.
      *** One button must have verb='ok' Note: A cancel button is not optional in the dialog box, but it is optional as a parameter to this function. - if passed, it may be used to change the label and optionally make memorable (the default for cancel button (labeled "Cancel") is not memorable). the verb must be 'cancel' (that's what makes it a "cancel" button definition). - if not passed, then it defaults to "Cancel" label, returns 'cancel', and is not memorable (will not be remembered by checking 'Don't show again'). - viewItems (array, default=nil) of items to be added to main UI. Normal use does not include these, but for special occasions: - width (integer, default=nil) units are pixels, or - width_in_chars (integer, default=nil) units are that of big fat characters, generally 50% to double that of true character width. - height (integer, default=nil) of message text, in pixels, or - height_in_lines (integer, default = nil) in lines - best to include an extra line or two to spare and to keep it above the buttons. - wrap (boolean, default=false) whether text should be wrapped at width. Note: strings without spaces are still truncated to fit. *** Requires width AND height to be specified somehow. - call (Call, default=nil) if passed, auto-caption will be displayed and previous caption restored.
    • ...: ( any type, default = nil, nil, nil, ... ) variables to be formatted

    Usage:

    • Like lr-dialogs.message, lr-dialogs.message-with-do-not-show, lr-dialogs.confirm, and lr-dialogs.prompt-for-action-with-do-not-show combined,
      except won't compress nor truncate the message.
    • Will automatically wrap if lines are too long, at space if possible, otherwise cuts in the middle.
      Max width chosen to accomodate most whole file paths.
    • Supports formatting and named parameter passing.
    • Examples:
      app:show( "I'm simple" ) -- informational
      app:show( "I'm ^1 simple", howSimple ) -- informational/formatted.
      app:show( { info="I'm simple" } ) -- informational using named parameter passing.
      app:show( { info="I'm ^1 simple" }, "very" ) -- informational, named, formatted.
      app:show( { confirm="I'm asking, but I'll remember your answer", actionPrefKey="QuestionablePrompt", buttons={{label="Yes",verb='ok'},{label='No',verb='cancel',memorable=true}} } ) -- confirm prompt, both yes and no answers can be remembered. app:show( { warning="I'm ^1 simple" }, adjective ) -- simple warning, formatted.
      app:show( { info="I'm ^1 simple", actionPrefKey="My friendly prompt", buttons={ {label='OK',verb='ok'},{label='Not OK',verb='other',memorable=false} }, "not so" ) -- you can remember OK button only,
      app:show( { error="I'm an error", buttons={{label="I guess its OK...",verb='ok'},{label='Abort',verb='cancel'}} } ) -- error message with custom cancel button.
    Dialog:new (t)
    Constructor for new instance.

    Parameters:

    • t:
    Dialog:newClass (t)
    Constructor for extending class.

    Parameters:

    • t:
    Dialog:presentFloatingDialog (params)
    Present non-modal (floating dialog), in "like" fashion in Lr4 (not officially supported) as Lr5 (1st version in which offcially supported).

    Parameters:

    • params: (table, required) parameter elements:
      name (string, default: "generic") unique dialog box name - used for guarding. Note: if there are no other guarded calls active, the default name will suffice.
      guard (number, default: no guarding) App.guardXXX - whether call should be guarded internally or not. Usually call should be guarded externally if not internally.
      args (table) params may be dialog box args (if all other params to default), or may be member of params, in order to pass the others in enclosing table.
      be sure to consider:
      title (string, default: "app-name - floating dialog") recommended to override.
      save_frame (string, default: don't save) hardly any reason not to allow user to define spot - recommend app-name - window-name.
      resizable (boolean, default: false) usually good to set true, since floaters may have too big frame for contents - allows user to control.
      background_color (LrColor, default: white) rarely needs to be otherwise specified.
      contents (view, required) a complete view, not an array of view items...
      blockTask (boolean, default: blocking, if called from async task, else non-blocking) note: this is an emulation via wrappage, actual floater will be blocking regardless.
      windowWillClose (function, default: nil) callback when window is closing (Lr5), or has closed (Lr4). Recommend using for finalization, if not handled externally.
      onShow (function, default: nil) callback when dialog about to be presented, contains to-front and close functions, which work as advertised in Lr5, and do nothing in Lr4.

    Usage:

    • Supports Lr4 (by somewhat emulating Lr5) and Lr5 (by somewhat emulating Lr4). - DO NOT PUT A QUIT BUTTON IF LR4 (quitting requires 'X').
    • Call-forwards: to-front and close - not supported in Lr4. So cross-version contexts must not be dependent on them.
    • examples: 
      dia:presentFloatingDialog { -- param table is args.
      title=str:fmtx( "^1 - My fancy dbox..", app:getAppName() ),
      save_frame=str:fmtx( "^1 - My fancy dbox..", app:getAppName() ), -- can be same as title
      resizable = true, -- generally a good idea for floaters.
      contents = vf:view( vi ), -- excludes quit button if Lr4.
      blockTask = true, -- wrapped externally in async task
      windowWillClose = nil, -- finale handled in calling context.
      onShow = function( callForward ) self.toFront = callForward.toFront; self.close = callForward.close end -- calling context expects these to be defined, even if no-ops in Lr4.
      }
      dia:presentFloatingDialog { -- param table has name, guard, and args.
      name=str:fmtx( "^1 - My fancy dbox..", app:getAppName() ),
      guard=App.guardVocal,
      args = {
      save_frame=str:fmtx( "^1 - My fancy dbox..", app:getAppName() ), -- can be same as title
      resizable = true, -- generally a good idea for floaters.
      contents = vf:view( vi ), -- excludes quit button if Lr4.
      blockTask = false, -- not internally wrapped in async task.
      windowWillClose = function() exifTool:closeSession( self.ets ) end
      onShow = function( callForward ) self.toFront = callForward.toFront; self.close = callForward.close end
      }}
    Dialog:presentModalFrame (args, returnAllButtons)
    Presents a modal dialog without an OK button.

    Parameters:

    • args: same as to lr-dialog -> present-modal-dialog
    • returnAllButtons: true => return first button click, else hold out for 'cancel' button.

    Usage:

      *** Only suitable if when you don't need form elements to be commited upon dismissal. 

    Return value:

      string: dismissal button - either 'ok' or one of the other buttons passed - never returns 'cancel', even if cancel button clicked (Mac).
    Dialog:promptForTargetPhotos (prefix, returnComponents, call, viewItems, accItems, noApk)
    Function to prompt for initiation of operation to be performed on selected photo(s), filmstrip, or whole catalog.

    Parameters:

    • prefix: (string, required) operation prefix e.g. "Update metadata of", "Adjust"
    • returnComponents: (boolean, default=false) true => omit the prompt and return confirm, subs, buttons, and actionPrefKey items. false => prompt user and return photos.
    • call: (Call, required) call object instance.
    • viewItems:
    • accItems:
    • noApk:

    Usage:

    • check if call has been canceled upon return. If not canceled, then there will be at least one target photo.
    • Named parameter passing is supported (i.e. parameters can be named members of a single table if you prefer). 
    Dialog:putTextOnClipboard (param)
    Klugerian function whose impetus was to support log file contents copy-n-paste to email.

    Presents text in a multi-line edit-field with instructions to user to copy to clipboard...

    Parameters:

    • param:
    Dialog:quickTips (strTbl, oneEol)
    Present quick-tips dialog box.

    Parameters:

    • strTbl: - table of "paragraph" strings - will be concatenated with double EOL between.
    • oneEol:

    Usage:

      Convenience function for presenting a help string with standard title, buttons, and link to web for more info. 
    Dialog:rememberAnswer (memKey, answer)
    Remember answer.

    Parameters:

    • memKey:
    • answer:

    Usage:

      Used in case presentation is via custom dialog box. 
    Dialog:selectFile (param, props, name)
    Allows user to select a file by way of the "open file" dialog box.

    Parameters:

    • param: Same as run-open-panel, except all are optional:
      • title
      • prompt ("OK" button label alternative)
      • fileTypes
      • initialDirectory
    • props: Properties into which folder path will be written.
    • name: Name of property to write.

    Usage:

      File path is written to named property if provided, in which case return value is typically ignored. 

    Return value:

      string: path of file, else nil if user cancelled.
    Dialog:selectFolder (param, props, name)
    Allows user to select a folder by way of the "open file" dialog box.

    Parameters:

    • param: table - same as run-open-panel, except all are optional:
      • title
      • prompt ("OK" button label alternative) - NOT supported.
      • can-create-directories
      • file-types (string or array of strings, optional): prefix with '.' for best results.
      • initial-directory
    • props: Properties into which folder path will be written.
    • name: Name of property to write.

    Usage:

      Folder is written to named property if provided, in which case return value is typically ignored. 

    Return value:

      string: path of folder, else nil if user cancelled.
    Dialog:selectSaveFile (param, props, name)
    Allows user to select a file by way of the "save file" dialog box.

    Parameters:

    • param: Same as run-save-panel, except all are optional:
      • title
      • prompt ("OK" button label alternative)
      • fileTypes
      • initialDirectory
    • props: Properties into which folder path will be written.
    • name: Name of property to write.

    Usage:

      File path is written to named property if provided, in which case return value is typically ignored. 

    Return value:

      string: path of file, else nil if user cancelled.
    Dialog:selectSaveFolder (param, props, name)
    Allows user to select a folder by way of the "save file" dialog box.

    Parameters:

    • param: table - same as run-open-panel, except all are optional:
      • title
      • prompt ("OK" button label alternative) - NOT supported.
      • can-create-directories
      • file-types (string or array of strings, optional): prefix with '.' for best results.
      • initial-directory
    • props: Properties into which folder path will be written.
    • name: Name of property to write.

    Usage:

      Folder is written to named property if provided, in which case return value is typically ignored. 

    Return value:

      string: path of folder, else nil if user cancelled.
    Dialog:showInfoAndRememberAnswer (msg, memKey, memText, okButton, cancelButton, otherButton)
    Show information, and remember answer for a while.

    Parameters:

    • msg:
    • memKey:
    • memText:
    • okButton:
    • cancelButton:
    • otherButton:

    Usage:

    • Keyword consolidator uses like function in rc-utils: its the only one using this technique, so this function is reserved in case kwc is ever ported to elare framework.
    • How long answer is remembered is governed by the plugin - generally memory lasts for the duration of a service.
    • Must be used in conjunction with "forget-answer" or there's not much point in it...
    • Unlike normal Lr memory, remembers "cancel" answer as well. 
    Dialog:yesNo (cancelNotMemorable, shortcut)
    get specified dialog buttons.

    Parameters:

    • cancelNotMemorable:
    • shortcut: (string, required) specification keys:
      YesNo - 'ok' => Yes, 'cancel' => No.
    Dialog:yesNoCancel (shortcut)
    get specified dialog buttons.

    Parameters:

    • shortcut: (string, required) specification keys:
      YesNo - 'ok' => Yes, 'cancel' => No.

    Valid XHTML 1.0!