Namespace and Class LrView

Summary

Functions

LrView.bind( binding )

This namespace function declares a binding to a data value in a property table.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. binding

(string or table) The data property. The name of a key in the default bound table, or, to specify a single property, a table with these entries:

• key (string) A key name for the observed property.
• bind_to_object (string) Optional. The name of an observable table containing this key, which overrides the current bound table.
• transform (function) Optional. A function that changes the value whose modification triggered the notification. Function looks like: myTransform( value, fromModel ) returns result. The value parameter is the value about to be set into the view if fromModel is true. The value parameter is the value coming from the view if fromModel is false.

To specify multiple properties, a table with these entries:

• keys (table) Multiple observed properties. Entries can be simple key names from the bound table, or you can specify a key in another table, using a key-value pair, in which the value part can be a table with these items:
  • key (string) A property name
  • bind_to_object (string) Optional. The name of an observable table containing this key, which overrides the current bound table.
  • unique_key (string) Optional. A unique name with which to identify this key, if the actual name is also used in another table.
• bind_to_object (string) Optional. The name of an observable table containing these keys, which overrides the current bound table, but is overridden by specific key specifications.
• operation (function) Required. A function defining an operation to perform on the key values; the result of this operation is passed to the transform function. Function looks like: myOperation( binder, value, fromModel ).
• transform (function) Optional. A function that changes the value whose modification triggered the notification. Function looks like: myTransform( value, fromModel ) returns result. The value parameter is the value about to be set into the view if fromModel is true. The value parameter is the value coming from the view if fromModel is false.

Return value

(table) An internal table that defines the binding. Do not modify.

LrView.conditionalItem( condition, view )

This namespace function allows you to define a view that is added to the layout only if a specific condition is true. If the condition is false, the view is ignored. (Note that this is not a binding; the condition is evaluated once when the view description is generated.)

First supported in version 2.0 of the Lightroom SDK.

Parameters

1. condition

(any type) If not nil or false, the view is included in the layout.

2. view

(view description) The view to include if condition is true.

Return value

Either the view description or kIgnoredView, depending on the value of condition.

LrView.osFactory()

This namespace function produces a factory object that can be used to create views and controls.

First supported in version 1.3 of the Lightroom SDK.

Return value

(object) The factory object.

LrView.share( name )

This namespace function declares the sharing of an attribute value with other views. Typically used with a size value (width or height), in which case the greatest of the shared values is used for all objects that share the value.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. name

(string) The name to be used to share this attribute with other views.

Return value

(table) An internal table that defines the sharing. Do not modify.

viewFactory:catalog_photo( args )

Creates a view containing a photo from the catalog.

First supported in version 4.0 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties

in addition to:

• photo: (LrPhoto) The photo.
• width: (number, default: height, if specified) The width of the box (in pixels) in which the photo will be drawn.
• height: (number, default: width, if specified) The height of the box (in pixels) in which the photo will be drawn.
If neither width nor height are specified, they both default to 200 pixels.
• frame_width: (number, default: 0) The thickness of the frame around the photo box, which is drawn with inner dimensions equal to the width and height specified for the photo box.
• frame_color: (LrColor, default: LrColor( 0, 0, 0 )) The color of the frame around the photo box.
• background_color: (LrColor, default: LrColor( 0, 0, 0 )) The color to use for filling any areas of the photo box that aren't occupied by the photo.
• mouse_down: (function, optional) Callback for this event, takes one argument, the view object that was clicked.

viewFactory:checkbox( args )

Creates a checkbox control, which displays the title text with a platform-style checkbox button. A checkbox is checked (selected) when its value is equal to its checked_value, and unchecked (deselected) when its value is equal to its unchecked_value. If its value has any other value, the button shows a mixed state.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties
• Text properties

in addition to:

• title: (string, default: nil) The display text.
• value: (any, default: nil) The current value of the checkbox.
• checked_value: (any, default: true) A value that indicates the checked state.
• unchecked_value: (any, default: false) A value that indicates the unchecked state.

viewFactory:color_well( args )

Creates a color well control, which displays the current color, and when clicked shows a UI that lets the user choose a different color.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties

in addition to:

• value: (LrColor, default: nil) The current color to display.

viewFactory:column( args )

Creates a column container, which lays out its children vertically. This view is affected by property values in its parent (such as visible), but has no non-layout properties of its own.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• Child layout properties
• Node layout properties

viewFactory:combo_box( args )

Creates a combo box control, with an editable text field and a pop-up menu of predefined text values. The user can enter any text, or select from the menu. When an item is selected from the menu, its value becomes the control value, and is displayed in the text field.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties
• Text properties
• Editable text properties (Auto completion is not supported on Windows.)

in addition to:

• items: (table, default: nil) An array of simple values to appear in the menu.These values cannot be localized in place; you must build the array with localized values.

viewFactory:control_spacing()

Retrieves a spacing value suitable for assignment to the spacing property of a group of controls.

First supported in version 1.3 of the Lightroom SDK.

Return value

(number) The spacing value in pixels.

viewFactory:dialog_spacing()

Retrieves a spacing value suitable for assignment to the spacing property of a group of items at the top level of a dialog.

First supported in version 1.3 of the Lightroom SDK.

Return value

(number) The spacing value in pixels.

viewFactory:edit_field( args )

Creates an edit-field control, which accepts keyboard input when it has the input focus. User input is committed (that is, the value is updated) with every keystroke if immediate is true. If immediate is false, input is committed when the control loses focus. There is a platform difference in the focus behavior:

First supported in version 1.3 of the Lightroom SDK.

• In Windows, the control loses focus when the user clicks outside it.
• In Mac OS, it loses focus when the user uses Tab to shift the focus, not when the user clicks outside the control.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties
• Text properties
• Editable text properties

viewFactory:group_box( args )

Creates a group box container, a visible containment frame for a set of controls. Can have a localizable title, which is displayed near the top left corner of the frame.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Child layout properties
• Node layout properties

in addition to:

• font: (any, default: nil, inherited) See Control properties.
• title: (string, default: nil) The display text.
• show_title: (Boolean, default: true) True to show the title.

viewFactory:label_spacing()

Retrieves a spacing value suitable for assignment to the spacing property of a group of items where the items are closely related and one of the items serves as a label for the other items.

First supported in version 1.3 of the Lightroom SDK.

Return value

(number) The spacing value in pixels.

viewFactory:password_field( args )

Creates a password field control, an editable text field that obscures the entered text, displaying only bullet characters.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties
• Text properties
• Editable text properties

viewFactory:picture( args )

Creates a picture control, which displays a static image or icon.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties

in addition to:

• value: (string, default: nil) Name of the file or resource in the plug-in. Obtain the resource with code like this: _PLUGIN:resourceId( "myLogo.png" )
• frame_width: (number, default: nil) The width of the frame to draw around the image.
• frame_color: (LrColor, default: black) The color of the frame.

viewFactory:popup_menu( args )

Creates a pop-up menu control, which offers a pop-up menu of choices, each with a title and value. When the user pops up the menu and makes a choice, the selected item's title and value become those of the control. The current title text is displayed in the control when the menu is not open.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties
• Text properties

in addition to:

• value: (any, default: nil) The current control value.
• items: (table, default: nil) Table of items to be displayed. Each entry has a localizeable title and a value.
• value_equal: (function, default: nil) A function called to compare the control value to the value of each item in turn, to determine if one is selected. The function is in the form: myValueEqual( value1, value2 ). It should return true if a condition is met, false if it is not. If it returns true for any item, that becomes the selected item, and its title is displayed in the control. If no item returns true, no item is selected, and the control is blank. The control value remains unchanged.

viewFactory:push_button( args )

Creates a push button control, which responds to a click with an action. Drawn in platform-standard style with a rounded appearance.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties
• Text properties

in addition to:

• title: (string, default: nil) The display text.
• action: (function, default: nil) A function defining the action to be taken when the button is clicked, in the form: myAction( button )

viewFactory:radio_button( args )

Creates a radio button control. The button is checked (selected) when the control value is equal to its checked_value, and unchecked (deselected) when value has any other value, except nil. When value is nil, the button shows a mixed state.

Within a container, only one of a set of radio buttons should be selected. Selecting one button should deselect all others in the set. You must enforce this in the way you bind the button values; it is not automatic.

First supported in version 1.3 of the Lightroom SDK.

As of version 6.0 of the Lightroom SDK, on Mac only, radio buttons with the same parent view will be automatically 'linked', i.e. checking one will clear all the others, as a result of a change in the underlying OS provided API. This should only be noticeable in a view construct where radio buttons are declared via the osFactory:row or osFactory:column method within the same parent view. If you wish to have more than two radio buttons in a row or column, use the osFactory:view method instead, with a place attribute of horizontal or vertical. Do not attempt to take advantage of OS X's automatic behavior, as the automatically changed radio button states will not necessarily be reflected in the property table to which the radio buttons' values are bound.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties
• Text properties

in addition to:

• title: (string, default: nil) The display text.
• value: (any, default: nil) Current value of the radio button.
• checked_value: (any) A value that indicates the checked state.

viewFactory:row( args )

Creates a row container, which lays out its children horizontally. This view is affected by property values in its parent (such as visible), but has no non-layout properties of its own.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• Child layout properties
• Node layout properties

viewFactory:scrolled_view( args )

Creates a container view with horizontal and vertical scroll bars.

First supported in version 4.0 of the Lightroom SDK.

On Mac OS, the scroll bars will automatically be hidden if the content of the scroll view does not require vertical and/or horizontal scrolling ability. On Windows, the scroll bar(s) will be grayed out in such a case.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Child layout properties

in addition to:

• width: (number, default: 450) The width of the view, in pixels.
• background_color: (LrColor, default: LrColor(1, 1, 1)) The background color of the view. Note that dynamic updates via binding only works on the Mac platform for this property.
• height: (number, default: 150) The height of the view, in pixels. (Will not be allowed to be smaller than 80.)
• horizontal_scroller: (Boolean, optional) True if a horizontal scroll bar is to be present, false if not. Defaults to true.
• vertical_scroller: (Boolean, optional) True if a vertical scroll bar is to be present, false if not. Defaults to true.

viewFactory:separator( args )

Creates a separator, which draws a line 2 pixels in width in its container, but has no other behavior.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with these fields:

• fill_horizontal: (number, default: nil) The width of the horizontal line, a percentage of the parent's width in the range [0..1].
• fill_vertical: (number, default: nil) The height of the vertical line, a percentage of the parent's height in the range [0..1].

If both values are specified, the larger value determines the direction of the line.

viewFactory:simple_list( args )

Creates a simple scrolling list control, which is similar to popup_menu in that it offers a simple non-hierarchical list of choices, each with a title and value. When the user clicks on an item in the list, that selected item's value becomes the value of the control.

First supported in version 4.0 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties (except the font property)

in addition to:

• width: (number, default: 450) The width of the view, in pixels.
• height: (number, default: 150) The height of the view, in pixels. (Will not be allowed to be smaller than 80.)
• value: (table, default: nil) The current control value; an array of the values corresponding to each selected list item, if any.
• items: (table, default: nil) Table of items to be displayed. Each entry has a localizeable title and a value.
• allows_multiple_selection: (Boolean) True if the list supports selection of multiple items at one time.
• value_equal: (function, default: nil) A function called to compare the control value to the value of each item in turn, to determine selection. The function is in the form: myValueEqual( value1, value2 ). It should return true if a condition is met, false if it is not. If it returns true for any item that item's title becomes selected in the list. If no item returns true, no item is selected in the list.

viewFactory:slider( args )

Creates a slider control, which has a draggable indicator that changes an associated numeric value.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties

in addition to:

• value: (number, default: nil) Value to be displayed.
• min: (number, default: nil) The low end of the range.
• max: (number, default: nil) The high end of the range.
• integral: (Boolean, default: false) True to change the value by integer increments.

viewFactory:spacer( args )

Creates a view to consume space for the purposes of layout.This is an empty row, which affects the layout of other children of its parent. It has no properties of its own except for size; these are typically shared with its sibling rows, using the LrView.share() function.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any: of:

• width: (number, default: nil) The horizontal size in pixels.
• height: (number, default: nil) The vertical size in pixels.

viewFactory:static_text( args )

Creates a static text control that does not respond to user input, typically a label or instructions.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Control properties
• Text properties

in addition to:

• title: (string, default: nil) The display text.
• truncation: (string, default: nil) Where to truncate the text if it is too long to be displayed. Values are: 'head', 'middle', 'tail'.
• selectable: (Boolean, default: false) True to make text selectable. This feature is only available in Mac OS.
• alignment: (string, default: 'left') Text alignment within the control. Values are: 'left'. 'center', right'.
• text_color: (LrColor, default: black) Color of the text.
• mouse_down: (function) Optional. Callback for this event, takes one argument, the view object that was clicked.

viewFactory:tab_view( args )

Creates a container of tabbed pages. The containing tab view draws the frames for its tab_view_item children, but has no title. The font value is the default for the tab text of the children.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Child layout properties
• Node layout properties

in addition to:

• font: (any, default: nil) The font used in the tab titles. See Control properties.
• size: (string, default: 'regular', inherited) The font size of text in the tab titles, and a default font size for child nodes. See Control properties.
• value: (any, default: nil) The identifier of the currently selected tab.

viewFactory:tab_view_item( args )

Creates a tabbed page container in a tab view container. The localizable title text is displayed in the tab.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Child layout properties
• Node layout properties

in addition to:

• title: (string, default: nil) The display text.
• identifier: (string, required) A unique identifier for this page, used to select the current tab in the parent tab view container. Important: Previous versions of the documentation stated that this parameter could be of any type. That was incorrect; it must be present and it must be a string value.

viewFactory:view( args )

Creates a basic containment frame for a set of controls, with no visual representation.

First supported in version 1.3 of the Lightroom SDK.

Parameters

1. args

(table) A table with fields for any:

• View properties
• Child layout properties
• Node layout properties

Properties

kIgnoredView : (Read-Only)

This namespace constant defines an object that can be inserted in a view description that will be ignored when the views are created.