App DocumentObjectGroup

From FreeCAD Documentation
Revision as of 07:23, 13 January 2020 by Vocx (talk | contribs) (→‎How to use: See the Std Group page for the complete information, including its use in Scripting.)
Other languages:
Do no translate, this information will be moved to Std_Group


Introduction

An App DocumentObjectGroup object, or formally an App::DocumentObjectGroup, is a simple element that allows grouping any type of App DocumentObject in the tree view no matter its type of data.

It was developed to organize the objects in the tree view in a way that is logical for the user.

Simplified diagram of the relationships between the core objects in the program. The App::DocumentObjectGroup class has an extension that allows it to group any type of object; the Group itself doesn't have many properties.

How to use

  1. Press the Group button in the structure toolbar. An empty Group is created.
  2. To add objects to a Group, select them in tree view, and then drag and drop them over the Group.
  3. To remove objects from a Group, drag them out of the Group, and onto the document label at the top of the tree view.

See the Std Group page for the complete information, including its use in Scripting.

Properties

An App DocumentObjectGroup (App::DocumentObjectGroup class) is derived from the basic App DocumentObject (App::DocumentObject class), therefore it shares all the latter's properties.

In addition to the properties described in App DocumentObject, the App DocumentObjectGroup has some properties that help it manage objects, like DataGroup.

See Property for all property types that scripted objects can have.

These are the properties available in the property editor. Hidden properties can be shown by using the Show all command in the context menu of the property editor.

Data

Base

  • DataLabel (String): the user editable name of this object, it is an arbitrary UTF8 string.
  • DataGroup (LinkList): a list of referenced objects. By default, it is empty [].

Hidden properties Data

  • DataExpression Engine (ExpressionEngine): a list of expressions. By default, it is empty [].
  • DataLabel2 (String): a longer, user editable description of this object, it is an arbitrary UTF8 string that may include newlines. By default, it is an empty string "".
  • DataProxy (PythonObject): a custom class associated with this object. This only exists for the Python version.
  • DataVisibility (Bool): whether to display the object or not.
  • Data_ Group Touched (Bool): whether the group is touched or not.

View

The App DocumentObjectGroup has five properties of the basic App GeoFeature, but it isn't derived from it.

Base

  • ViewDisplay Mode (Enumeration): by default it's empty.
  • ViewOn Top When Selected (Enumeration): Disabled (default), Enabled, Object, Element.
  • ViewSelection Style (Enumeration): Shape (default), BoundBox. If the option is Shape, the entire shape (vertices, edges, and faces) will be highlighted in the 3D view; if it is BoundBox only the bounding box will be highlighted.
  • ViewShow In Tree (Bool): if it is true, the object appears in the tree view. Otherwise, it is set as invisible.
  • ViewVisibility (Bool): if it is true, the object appears in the 3D view; otherwise it is invisible. By default this property can be toggled on and off by pressing the Space bar in the keyboard.

Hidden properties View

  • ViewProxy (PythonObject): a custom class associated with this object. This only exists for the Python version.

Scripting

See also: FreeCAD Scripting Basics, and scripted objects.

An App DocumentObjectGroup is created with the addObject() method of the document. Once a Group exists, other objects can be added to it with the addObject() or addObjects() methods of this Group.

import FreeCAD as App

doc = App.newDocument()
obj = App.ActiveDocument.addObject("App::DocumentObjectGroup", "Group")

bod1 = App.ActiveDocument.addObject("PartDesign::Body", "Body")
bod2 = App.ActiveDocument.addObject("Part::Box", "Box")

obj.addObjects([bod1, bod2])
App.ActiveDocument.recompute()

This basic App::DocumentObjectGroup doesn't have a Proxy object so it can't be fully used for sub-classing.

Therefore, for Python scripting, the recommendation is to create the App::DocumentObjectGroupPython object.

import FreeCAD as App

doc = App.newDocument()
obj = App.ActiveDocument.addObject("App::DocumentObjectGroupPython", "Name")
obj.Label = "Custom label"

For example, a FEM Analysis is an App::DocumentObjectGroupPython object with a custom icon and additional properties.