Sandbox:Roy 043

Description
creates an App Link ( class), a type of object that references or links to another object, in the same document, or in another document. It is especially designed to efficiently duplicate a single object multiple times, which helps with the creation of complex assemblies from smaller subassemblies, and from multiple reusable components like screws, nuts, and similar fasteners.

The App Link object was newly introduced in v0.19; in the past, simple duplication of objects could be achieved with, but this is a less efficient solution due to its implementation which essentially creates a copy of the internal Shape of the source object. On the other hand, a Link references directly the original Shape, so it is more memory efficient.

By itself the Link object can behave like an array, duplicating its base object many times; this can be done by setting its property to  or larger. This "Link Array" object can also be created with the different array tools of the Draft Workbench, for example,, , and.

When used with the PartDesign Workbench, Links are intended to be used with, so it is recommended to set  to  to select the features of the entire Body, and not the individual features. To create arrays of the internal PartDesign Features, use, , and.

The tool is not defined by a particular workbench, but by the base system, thus it is found in the  that is available in all workbenches. The Link object, used in conjunction with to group various objects, forms the basis of the  Assembly3 and  Assembly4 Workbenches.

... The produced object has the same icon as the original object, but has an arrow overlay indicating it is a Link.

.... The produced object has the same icon as the original object, but has an additional arrow overlay indicating it is a Link coming from an external document.

Same document

 * 1) Select one or more objects.
 * 2) There are several ways to invoke the command:
 * 3) * Press the button.
 * 4) * Select the option from the Tree view context menu or 3D view context menu.
 * 5) For each selected object a Link is created.

External document

 * 1) If required change the Tree view DocumentMode to MultiDocument with the Std_TreeMultiDocument.svg Std TreeMultiDocument command.
 * 2) Open a source document and a target document.
 * 3) Select one or more objects in the source document.
 * 4) Switch to the target document by clicking its tab in the Main view area.
 * 5) Press the  button.
 * 6) For each selected object a Link is created.

Start with empty Link

 * 1) Make sure no object is selected.
 * 2) There are several ways to invoke the command:
 * 3) * Press the button.
 * 4) * Select the option from the Tree view context menu or 3D view context menu.
 * 5) An empty Link is created.
 * 6) In the Property editor click in the  field of the Link.
 * 7) Press the  button.
 * 8) The Link dialog opens.
 * 9) Do one of the following:
 * 10) * Select an object from the same document.
 * 11) * Switch to an external document by clicking its tab in the Main view area, and select an object there.
 * 12) In both cases you can also select a subelement from an object in the 3D view. This will create a Sub-Link. See Std LinkMakeRelative.
 * 13) Press the  button.





Drag and drop
You can also create Links by performing a drag and drop operation in the Tree view.


 * 1) Select one or more objects in the Tree view.
 * 2) Hold down the  key.
 * 3) Drag the selection to the document label of the current document or an external document.
 * 4) The cursor will change.
 * 5) Drop the selection.

Link Array
A Link can be turned into an array where each element has its own placement and appearance.


 * 1) Make sure the  property of the Link is set to  (this is the default).
 * 2) Change the  of the Link to  or more. Using  results in an array with a single element, so you will typically use a value of  or more.
 * 3) Each Link element in the array can be positioned individually by changing its own  property.
 * 4) In a similar way, each element in the array can have its own appearance. See Override appearance below.
 * 5) Once you are satisfied with the placement and properties of the Link elements in the array, you can change  to  in order hide them in the Tree view. This has the benefit of making the system more responsive.



When creating this type of Link Array, you must place each of the elements manually. If you need a patterned array you should use the array tools of the Draft Workbench, like Draft OrthoArray, Draft PolarArray, and Draft CircularArray. These commands can create normal copies or Link copies depending on the options at creation time.

Link to Std Part
Std LinkMake can be used on Std Parts in order to quickly duplicate groups of objects, assemblies, positioned in space. A Link to a Part will keep the visibility of its child objects synchronized with that Part. If you hide a child object in the Link, it will be hidden in the original Part, as well as in all other Links to that Part.



Link to Std Group
A regular Std Group does not have a  property, so it cannot control the position of its child objects. However when Std LinkMake is used on a  Std Group the resulting Link does have a  and, like a  Std Part, can control the position of its child objects. A Link to a Group allows independent control of the visibility of its child objects.



Override appearance
By default a Link has the same appearance as the original. There are two ways to override that.

Override material
If the property of a Link is set to, its  property will control its appearance.

If the property of a is set to  then the individual  properties of its elements is ignored.

Override colors
Regardless of the state of, it is possible to individually set the appearance of the subelements (vertices, edges, faces) of a Link.
 * 1) Select the Link in the tree view. Open the context menu (right-click), and pick.
 * 2) Now pick the individual subelements that you want in the 3D view, press, and change the properties including transparency.
 * 3) To remove the custom attributes, select the elements in the list, and press.
 * 4) When you are satisfied with the result, press  to close the dialog.

as of v0.19, the coloring of the subelements is subject to the topological naming problem so it should be done as the last modelling step, when the model is not subject to change any more.



When is  and individual elements are listed in the tree view in a Link Array, each Link can be shown or hidden by pressing the  bar.

Another way to hide the individual elements is using the menu.
 * 1) Select the array, open the  menu (right click).
 * 2) In the 3D view, pick any subelement from any Link in the array.
 * 3) Press . An icon of an eye Invisible.svg should appear, indicating that this element has been hidden from the 3D view. The object will temporarily show itself when the cursor hovers over the Invisible.svg icon.
 * 4) You can click  to confirm the operation and close the dialog. The Link will remain hidden even if it is shown as visible in the tree view.



If you wish to restore the visibility of this array element, enter the dialog once more, pick the eye icon, then click on to remove the hidden status, and click  to confirm and close the dialog. The element will be visible in the 3D view again.

When the Link is for a or a, the  menu works in similar way as with arrays; it allows controlling the face color, entire object color, and visibility of the objects in the group.



Properties
The App Link ( class) is derived from the basic App DocumentObject ( class) and inherits all its properties.

The following are the specific properties available in the Property editor. The App Link will additionally show the properties of the original. The names of these linked properties appear in green in the Property editor. Hidden properties can be shown by using the command in the context menu of the Property editor.

Data

 * : it indicates the source object of the App Link; this can be an entire object, or a subelement of it (vertex, edge, or face).
 * : it defaults to, in which case the Link will override the 's own placement. If it is set to , the Link will be placed in the same position as the , and its placement will be relative to the 's placement. This can also be achieved with.
 * : it is an offset applied on top of the of the . This property is normally hidden but appears if  is set to ; in this case,  now becomes hidden.
 * : the placement of the Link in absolute coordinates.
 * : it defaults to, in which case the Tree view will show the individual Link copies, as long as is  or larger.
 * : it defaults to . If it is or larger, the App Link will behave like an array, and will duplicate the same  many times. If  is, each element in the array will be displayed in the Tree view, and each can have its own  modified. Each Link copy will have a name based on the Link's Name, augmented by , where  is a number starting from . For example, with a single , the copies will be named , , , etc.
 * : name of the execute function that will run for this particular Link object. It defaults to . Set it to to disable it.
 * : list of Link elements that have had their color overriden.
 * : or.
 * : it defaults to . It is a factor for uniform scaling in each direction, , and . For example, a cube of x  x , that is scaled by , will result in a shape with dimensions  x  x.
 * : the scale factor for each component for all Link elements when  is  or larger. If  is other than, this same value will be used in the three components.
 * : the scale factor for each Link element.
 * : the visibility state of each Link element, either  or.
 * : the placement for each Link element.
 * : the list of Link elements.


 * : a custom class associated with this object. This only exists for the Python version. See Scripting.

View

 * : it defaults to ; it can be, , ; defines the style of the edges in the 3D view.
 * : a float that determines the width in pixels of the edges in the 3D view. It defaults to.
 * : it defaults to ; if set to it will override the 's material, and it will display the colors defined in.
 * : similar to, defines the size of the vertices.
 * : if it is, the object can be picked with the pointer in the 3D view. Otherwise, the object cannot be selected until this option is set to.


 * : this property includes sub-properties that describe the appearance of the object.
 * , it defaults to, which is displayed as on base 255, light blue.
 * , it defaults to, which is displayed as on base 255, dark gray.
 * , it defaults to, which is displayed as on base 255, black.
 * , it defaults to, which is displayed as on base 255, black.
 * , it defaults to
 * , it defaults to.


 * : if individual materials have been added, they will be listed here.
 * : if the individual faces or edges of the link have been overridden they will be listed here.
 * : if the individual materials of the link have been overridden they will be listed here.
 * : a custom viewprovider class associated with this object. This only exists for the Python version. See Scripting.
 * : a custom viewprovider class associated with this object. This only exists for the Python version. See Scripting.


 * : or.
 * : see the information in App FeaturePython.
 * : see the information in App FeaturePython.


 * : see the information in App FeaturePython.
 * : see the information in App FeaturePython.

Scripting
FreeCAD Scripting Basics and scripted objects.

See Part Feature for the general information on adding objects to the document.

An App Link is created with the method of the document. its can be defined by changing its  property, or by using its  method.

The basic doesn't have a Proxy object so it can't be fully used for sub-classing.

For Python subclassing you should create a object.