moduleAddDockModule()

Adds a new dock module to a GEDI or VISION module or to the Script Editor.

Synopsis

int moduleAddDockModule(string moduleName, string panelFile, [, dyn_string dollars] [, mapping options]);

Parameters

Parameter Description
moduleName The label of the dock module.
panelFile The panel that should be opened in the dock module , for example, console.pnl
dollars The dollar parameters that are passed.
options

The following keys are available:

"area"(string): specifies where to place the dock module: LeftDockWidgetArea, RightDockWidgetArea, TopDockWidgetArea BottomDockWidgetArea. The default value is: RightDockWidgetArea

"allowedAreas"(string): specifies where you can move the dock module to. Allowed as "area" plus: AllDockWidgetAreas, NoDockWidgetArea, The values can be combined by using the "|", for example, "LeftDockWidgetArea|RightDockWidgetArea". The default value is: AllDockWidgetAreas

"features"(string): A combination of: DockWidgetClosable, DockWidgetMovable, DockWidgetFloatable, DockWidgetVerticalTitleBar AllDockWidgetFeatures, NoDockWidgetFeatures ( see http://doc.qt.io/qt-5/qdockwidget.html#DockWidgetFeature-enum)

The default value is: DockWidgetClosable|DockWidgetMovable|DockWidgetFloatable

"tabifyWith"(string): module Name, which must be another Dock Module, onto which the newly created one will be added on top of.

"floating"(bool): If the value is set to true, the dock module will not be docked but floating on top of the main module. A floating dock widget is an independent window "on top" of its parent MainWindow. The default value is: false (docked).

"size"(dyn_int): It is possible to define a default size for the given panel via dyn_int (width, height). Caution: The size defined in the mapping is only used at the first creation of the dock module. When closing the module, its settings are saved in the PVSS00ui.ini file. This means that these settings are used when this dock module is started again, regardless of the given mapping. Depending on the dock modules position it may happen that only the height or width of the defined size is applied.

If the main module was opened at the position (-2, -2) , the position as well as the dock module states of the main module (e.g. where they were when closed, if they were floating, etc). are saved in the PVSS00ui.ini file.

These saved settings will be automatically applied the next time Dock Modules are created inside a main module with the same name. Thus, the settings are saved under the main module name.

The title of the Dock Module is the current panel title (e.g. language dependent as defined in Gedi)

if moduleAddDockModule() is called another time with the same module name as in an exiting Dock Module, the given options will be applied to the new module and the panel is used as well.

Return value

The function returns the ID of the added dock module.

Error

Missing or invalid arguments.

Description

Adds a new dock module to a GEDI or VISION module. It can also add modules to the Script Editor.

If the dock module should be added to the GEDI, the script should be located in wincc_oa_path or <project_directory>/scripts/gedi and must be called <name>_ext.ctl. When the GEDI is started, all scripts from this directory will be loaded.

Similar to adding a dock module to the GEDI, adding a module to the Script Editor requires the script to be placed in the <project_directory>/scripts/scriptEditor directory with a filename following the <name>_ext.ctl pattern. To load the scripts and show the dock module, the GEDI has to be closed and reopened.

The function moduleAddDockModule() can be called even when the module was already added as a dock module, in which case the system applies the properties from the options argument to the existing dock module again.

Example

The following example adds the dock module "MyDock" containing the console.pnl to the GEDI module.

Do not use the function myModuleName() for the parameter "moduleName" since the new dock module name must be specified for the parameter.

main()
{
   moduleAddDockModule("myDock", "projAdmin/console.pnl");
}

Figure: Dock module "myDock" containing the console panel

Example

The following example opens several panels in several modules at different positions.

main()
{
   mapping oleft, oright, oright2, otop, obottom;

  //"area"(string): specifies where to place the dock:LeftDockWidgetArea, RightDockWidgetArea, TopDockWidgetArea, BottomDockWidgetArea.
  //The default value is: RightDockWidgetArea
  oleft["area"] = "LeftDockWidgetArea";
  oright["area"] = "RightDockWidgetArea";
  otop["area"] = "TopDockWidgetArea";
  obottom["area"] = "BottomDockWidgetArea";


//"allowedAreas"(string): where the user can move the dock to. Allowed: as "area" plus: AllDockWidgetAreas, NoDockWidgetArea
  //The values can be combined by using the "|", for example, "LeftDockWidgetArea|RightDockWidgetArea".
  //The default value is: AllDockWidgetAreas
  oleft["allowedAreas"] = "LeftDockWidgetArea";

// oright["allowedAreas"] = "RightDockWidgetArea";
  // otop["allowedAreas"] = "TopDockWidgetArea";
  // obottom["allowedAreas"] = "BottomDockWidgetArea";
  oright["allowedAreas"] = "RightDockWidgetArea|TopDockWidgetArea";
  otop["allowedAreas"] = "AllDockWidgetAreas";
  obottom["allowedAreas"] = "NoDockWidgetArea";


// "features"(string): A combination of: DockWidgetClosable DockWidgetMovable DockWidgetFloatable DockWidgetVerticalTitleBar
  // AllDockWidgetFeatures NoDockWidgetFeatures  ( see http://doc.qt.io/qt-5/qdockwidget.html#DockWidgetFeature-enum)
  // If not specified, the default is: DockWidgetClosable|DockWidgetMovable|DockWidgetFloatable
   oleft["features"] = "DockWidgetClosable";

//oleft["features"] = "DockWidgetMovable";
  //oleft["features"] = "DockWidgetFloatable";
  //oleft["features"] = "DockWidgetVerticalTitleBar";
  oright["features"] = "DockWidgetFloatable|DockWidgetVerticalTitleBar";
  otop["features"] = "AllDockWidgetFeatures";
  obottom["features"] = "NoDockWidgetFeatures";

  // "tabifyWith"(string): module Name, which must be another Dock Module, onto which the newly created one will be added on top of.
  //If the value is set to true, the dock module will not be docked but floating on top of the main module. A floating dock widget is an independent
  //window "on top" of its parent MainWindow. The default value is: false (docked).
  otop["floating"] = "true";

  // Adds panels to different moduls
  moduleAddDockModule("left", "docksub.pnl", makeDynString("$a:hello","$b:hallo"), oleft);
  moduleAddDockModule("right", "docksub.pnl", makeDynString("$a:hello","$b:hallo"), oright);
  moduleAddDockModule("top", "docksub2.pnl", makeDynString("$a:hello","$b:hallo"), otop);
  moduleAddDockModule("bottom", "docksub2.pnl", makeDynString("$a:hello","$b:hallo"), obottom);
  moduleAddDockModule("right2", "docksub.pnl", makeDynString("$a:hello","$b:hallo"), oright2);
}

Example

This example uses the function moduleAddDockModule on an existing dock module to define the module as floating by using:

moduleAddDockModule(moduleName, "", makeMapping("floating", true));

This example also shows that the panel name given can be an empty string in which case the existing panel is not changed. When passing an empty panel name when the module is just being created, no panel will be loaded. When loading a panel, the dock window will get the panels current title as the dock module window title.

Assignment

Miscellaneous functions

Availability

UI