From: vsr Date: Tue, 8 Dec 2009 16:42:38 +0000 (+0000) Subject: Merge from V5_1_3_BR branch (07/12/09) X-Git-Tag: V6_0_0 X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=145626550396ebfb1ee66f8942e07ab6a63c1ba8;p=samples%2Fpyhello.git Merge from V5_1_3_BR branch (07/12/09) --- diff --git a/Makefile.am b/Makefile.am index 3eead60..baf9fc9 100644 --- a/Makefile.am +++ b/Makefile.am @@ -41,3 +41,13 @@ EXTRA_DIST += \ dist-hook: rm -rf `find $(distdir) -name CVS` + +usr_docs: + (cd doc && $(MAKE) $(AM_MAKEFLAGS) usr_docs) + +docs: usr_docs + +dev_docs: + (cd doc && $(MAKE) $(AM_MAKEFLAGS) dev_docs) + + diff --git a/configure.ac b/configure.ac index e109a99..c31f543 100644 --- a/configure.ac +++ b/configure.ac @@ -146,6 +146,14 @@ echo CHECK_QT +echo +echo --------------------------------------------- +echo Testing html generators +echo --------------------------------------------- +echo + +CHECK_HTML_GENERATORS + echo echo --------------------------------------------- echo Testing Kernel @@ -169,13 +177,12 @@ echo --------------------------------------------- echo CHECK_CORBA_IN_GUI + if test "x${CORBA_IN_GUI}" != "xyes"; then - echo "failed : For configure PYHELLO1 module necessary full GUI !" + echo "failed : For configure PYHELLO module necessary full GUI !" exit fi - - echo echo --------------------------------------------- echo Summary @@ -183,7 +190,7 @@ echo --------------------------------------------- echo echo Configure -variables="python_ok omniORB_ok qt_ok Kernel_ok" +variables="python_ok omniORB_ok qt_ok doxygen_ok Kernel_ok" for var in $variables do @@ -224,6 +231,7 @@ AC_OUTPUT([ \ bin/runAppli \ bin/Makefile \ doc/Makefile \ + doc/doxyfile \ src/Makefile \ src/PYHELLO/Makefile \ src/PYHELLOGUI/Makefile \ diff --git a/doc/Makefile.am b/doc/Makefile.am index 6e3f6da..58b662c 100755 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,6 +21,33 @@ # include $(top_srcdir)/adm_local/unix/make_common_starter.am -dist_doc_DATA = dev_guide.pdf +EXTRA_DIST += static -EXTRA_DIST += dev_guide.txt +usr_docs: doxyfile + $(DOXYGEN) doxyfile + +docs: usr_docs + +dev_docs: + +clean-local: + @for filen in `find . -maxdepth 1` ; do \ + case $${filen} in \ + ./Makefile | ./doxyfile ) ;; \ + . | .. ) ;; \ + *) echo "Removing $${filen}" ; rm -rf $${filen} ;; \ + esac ; \ + done ; + +install-data-local: usr_docs + $(INSTALL) -d $(DESTDIR)$(docdir)/gui/PYHELLO + @for filen in `find . -maxdepth 1` ; do \ + case $${filen} in \ + ./Makefile | ./doxyfile | ./doxyfile.bak ) ;; \ + . | .. ) ;; \ + *) echo "Installing $${filen}" ; cp -rp $${filen} $(DESTDIR)$(docdir)/gui/PYHELLO ;;\ + esac ; \ + done ; + +uninstall-local: + rm -rf $(DESTDIR)$(docdir)/gui/PYHELLO diff --git a/doc/dev_guide.pdf b/doc/dev_guide.pdf deleted file mode 100644 index a459804..0000000 Binary files a/doc/dev_guide.pdf and /dev/null differ diff --git a/doc/dev_guide.txt b/doc/dev_guide.txt deleted file mode 100644 index 82e54ec..0000000 --- a/doc/dev_guide.txt +++ /dev/null @@ -1,303 +0,0 @@ - -.. _pysalome: - -================================================================ -Guide for the development of a SALOME module in Python -================================================================ - -The purpose of this document is to describe briefly the different steps in the development of a SALOME module -in Python. - -Steps in construction of the example module -==================================================== -The example module chosen to illustrate the process to construct a module is extremely simple. -It will contain a single component and this component will have a single service called getBanner that -will accept a character string as the sole argument and that will return a character string obtained by -concatenation of “Hello” and the input chain. This component will be completed by a graphic GUI written in PyQt. - -The different steps in the development will be as follows: - - - create a module tree structure - - create a SALOME component that can be loaded by a Python container - - configure the module so that the component is known to SALOME - - add a graphic GUI - -Create the module tree structure -======================================= -Firstly, we will simply put a SALOME component written in Python and that can be loaded by a Python -container, into the example module. An idl interface and a Python implementation of the component will be -all that are necessary. -The following file structure is necessary so that this can be implemented in a SALOME module:: - - + PYHELLO1_SRC - + build_configure - + configure.ac - + Makefile.am - + adm_local - + Makefile.am - + unix - + Makefile.am - + make_common_starter.am - + config_files - + Makefile.am - + check_PYHELLO.m4 - + bin - + Makefile.am - + VERSION.in - + runAppli.in - + myrunSalome.py - + idl - + Makefile.am - + PYHELLO_Gen.idl - + src - + Makefile.am - + PYHELLO - + Makefile.am - + PYHELLO.py - + doc - -The module name is PYHELLO, the component name is PYHELLO and all the files will be put in a directory named PYHELLO1_SRC. -All files are essential except for VERSION.in, runAppli.in and runSalome.py. -VERSION.in is used to document the module, it must give its version and its compatibilities or -incompatibilities with other modules. Therefore, it is strongly recommended but is not essential for operation. -The runAppli.in and runSalome.py files are not essential but make the example easier to use. - -**Warning**: the files of the basic platform (KERNEL) must not be copied to initialise a module tree structure. -It is usually preferable to copy files from another module such as GEOM or MED. - -Implementation of automake, configure --------------------------------------- -SALOME uses autoconf and automake to build the configure script that is used for the installation to test -the system configuration and to preconfigure the module construction Makefile files. -The build_configure file contains a procedure that starts from configure.ac and uses automake to build -the configure script. -automake starts from Makefile.am files to build Makefile.in files. -All files with an "in" extension are skeletons that will be transformed by the configure process. - -Almost all files used for this process are located in the basic platform that is referenced by the -KERNEL_ROOT_DIR environment variable as well as GUI_ROOT_DIR for the graphical user interface (GUI). -However, some files must be modified as a function of the target -module. This is the case for build_configure and configure.ac files that usually need to be adapted. - -The basic files for configuration of the KERNEL module and other modules are collected in the salome_adm -directory of the KERNEL module. However, in order to be able to use the CORBA objects of the KERNEL module, -the files in the salome_adm directory have to be overwritten, using the make_common_starter.am file in -the adm_local directory of the example module. - -config_files is a directory in which the m4 files that are used to test the configuration of the system in the -configure process can be placed. If the salome_adm files are not sufficient, others can be added in adm_local. - -The idl directory --------------------------------------- -The idl directory requires a Makefile.am that must make the compilation of the idl PYHELLO_Gen.idl file -and install all the generated files in the right module installation directories. The BASE_IDL_FILES target has -to be modified to reach this goal. - -The idl file itself must define a CORBA module for which the name must be different from the module -name to avoid name conflicts and define a CORBA interface that is derived at least from the Component interface -of the Engines module. -The name of the CORBA module will be PYHELLO_ORB and the name of the interface will be PYHELLO_Gen. - -The src directory --------------------------------------- -The src directory will contain all components and the GUI for the module. Each of these entities must have -its own directory. - -For the moment, the module will only contain a single directory for the engine of the PYHELLO component -and its name will be PYHELLO. - -The Makefile.am will simply trigger the path of sub-directories described by the SUBDIRS target. - -The PYHELLO directory -''''''''''''''''''''''' -This directory contains the Python module that represents the component and therefore contains the PYHELLO class -and a Makefile.am file that simply exports the PYHELLO.py module into the installation directory of the SALOME module. - -The PYHELLO.py module contains the PYHELLO class that is derived from the PYHELLO_Gen interface of the CORBA -PYHELLO_ORB_POA module and the SALOME_ComponentPy_i class of the SALOME_ComponentPy module. - -The doc directory --------------------------------------- -This contains nothing for the moment. It could contain this document. - -The bin directory --------------------------------------- -VERSION.in is used to document the module, it must define its version and its compatibilities -or incompatibilities with other modules. Therefore, it is strongly recommended but is not essential for operation. - -The runAppli.in file is the equivalent of the runSalome in the KERNEL module configured to implement the KERNEL -module and this PYHELLO module. - -The myrunSalome.py file is the file of the KERNEL module modified to run only with a Python container, -with the test function that creates the PYHELLO component instead of a MED component, -and automatic completion in Python. - -Creating a component that can be loaded by a container -====================================================== -The files presented above are sufficient to build and install the PYHELLO1_SRC module, to start -the SALOME platform composed of the KERNEL and PYHELLO1 modules, and to request the Python container -to load a PYHELLO component. - -All the following steps are only possible if the SALOME prerequisite software is accessible in the module -developer environment. - -Construction, installation ---------------------------------- -In PYHELLO1_SRC, enter:: - - export KERNEL_ROOT_DIR= - ./build_configure - -Go into ../PYHELLO1_BUILD and enter:: - - ../PYHELLO1_SRC/configure --prefix= - make - make install - -Running the platform -------------------------------- -Move into the and enter:: - - ./bin/salome/runAppli - -This command runs SALOME configured for KERNEL and the PYHELLO1 module. At the end of running, -the user sees a Python interpreter configured for SALOME that provides access to SALOME CORBA objects. - -runAppli is a shell that executes a Python script, by passing arguments to it in a command line:: - - python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall - -These arguments state that the myrunSalome.py script located in the PYHELLO module will be used, that the PYHELLO -component will be activated and all SALOME processes that existed before the run will be killed. - -This command will not function unless the following environment variables have previously been set:: - - export KERNEL_ROOT_DIR= - export PYHELLO_ROOT_DIR= - -**Warning**: it is possible that the SALOME run will not reach the end. In some circumstances, the time to -start CORBA servers may be long and could exceed the timeout. If the reason for -this is that the time to load dynamic libraries is long, it is possible that a second run immediately -afterwards will be successful. - -Loading the example component ------------------------------------- -The PYHELLO_ORB module has to be imported before making a request to load the component into the Python -container, to obtain access to methods of the component. This Python container was made accessible -in the runSalome.py by means of the container variable:: - - import PYHELLO_ORB - c=container.load_impl("PYHELLO","PYHELLO") - c.makeBanner("Christian") - -The last instruction must return ‘Hello Christian’. - -Proceed as follows to see CORBA objects created by these actions:: - - clt.showNS() - -Declared SALOME component -============================== -For the moment, the PYHELLO component was loaded by making a direct request to the Python container. This is -not the standard method for loading a component. The normal method uses the LifeCycle service that uses -catalog services to identify the component and its properties and then calls the requested container to load the component. - -Before this method can be used, the component must be declared in a catalog in the XML format, for which -the name must be Catalog.xml. In our case, it will be PYHELLOCatalog.xml. This catalog will be stored in -the resources directory. - -Updated tree structure:: - - + PYHELLO1_SRC - + build_configure - + configure.ac - + Makefile.am - + adm_local - + bin - + idl - + src - + doc - + resources - + PYHELLOCatalog.xml - -The remainder of the files are identical, apart from adding the resources directory and the PYHELLOCatalog.xml file. -However, the Makefile.am has to be modified so that the catalog is actually installed in the installation -directory. It simply needs to be specified in the salomeres_SCRIPTS target. - -Construction, installation ---------------------------------- -There is no need to do another configure to take account of this modification. -All that is necessary is to enter PYHELLO1_BUILD and then:: - - ./config.status - make - make install - -Starting the platform -------------------------------- -The platform is started in the same way as before. Go into PYHELLO1_INSTALL and do:: - - ./bin/salome/runAppli - -Loading the example component ------------------------------------- -The method of loading the component is not very different from that described above. The services of the -LifeCycle module are used in this case instead of calling the container directly. -The call sequence is contained in the runSalome.Py test function. :: - - c=test(clt) - c.makeBanner("Christian") - -The test function creates the LifeCycle. It then asks for the PYHELLO component to be loaded in the FactoryServerPy container:: - - def test(clt): - """ - Test function that creates an instance of PYHELLO component - usage : pyhello=test(clt) - """ - import LifeCycleCORBA - lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb) - import PYHELLO_ORB - pyhello = lcc.FindOrLoadComponent("FactoryServerPy", "PYHELLO") - return pyhello - -Loading from the application interface (IAPP) ----------------------------------------------------------- -Before a component can be loaded dynamically using the IAPP components bar, the icon representing the -component will have to be declared in the catalog. -It is declared by simply adding a line for the icon to the component catalog:: - - PYHELLO.png - -and putting the corresponding file in the module resources directory. - -Adding a graphic GUI -=========================== -The next step to complete the module consists of adding a graphic interface to the PYHELLO component, that will -be written in Python using the Qt widgets library. This graphic interface must be integrated into the SALOME -application interface (IAPP), and therefore must respect some constraints that we will see. - -Firstly note the contour of the GUI of a component. The behaviour of the GUI is given by a Python module -that has a standard name GUI.py. It must propose conventional entry points that the IAPP will use to -activate this GUI or to inform it of specific events. GUI commands are activated through a menu bar and a -button bar that are integrated into the menu bar and into the IAPP button bar. - -Python module implanting the behaviour of the GUI ------------------------------------------------------ -The behaviour of the PYHELLO component GUI is implanted in the Python PYHELLOGUI.py module in the -PYHELLOGUI sub-directory. The Makefile.am located in the src directory must be updated to include -the PYHELLOGUI subdirectory. A Makefile.am must be added into the PYHELLOGUI subdirectory. -Important targets are salomescript_SCRIPTS and salomeres_DATA. - -The salomescript_SCRIPTS target must be updated with the name of the Python modules to be made visible in Salome, in other -words mainly so that they are importable (Python import command). - -The salomeres_DATA target must be updated with the names of files that are used for multi-linguism. - -Menu bar and button bar ----------------------------------- -The menu bar and button bar for the PYHELLO component are dynamically added when importing the PYHELLOGUI module. -They are created by calling the Python functions createMenu, createAction and createTool from the sgPyQt SALOME -interface object. Every action must have a unique id. -Some icons are used. They must be installed in the resources directory. - diff --git a/doc/doxyfile.in b/doc/doxyfile.in new file mode 100755 index 0000000..436dfae --- /dev/null +++ b/doc/doxyfile.in @@ -0,0 +1,74 @@ +# Copyright (C) 2007-2008 CEA/DEN, EDF R&D, OPEN CASCADE +# +# Copyright (C) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, +# CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +# +# See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com +# + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = "PYHELLO sample module reference manual v.@VERSION@" +OUTPUT_DIRECTORY = . +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +TAB_SIZE = 5 + +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES + +#--------------------------------------------------------------------------- +#Input related options +#--------------------------------------------------------------------------- +INPUT = @srcdir@ +FILE_PATTERNS = *.doc +EXCLUDE = +IMAGE_PATH = @srcdir@/images +EXAMPLE_PATH = + +#--------------------------------------------------------------------------- +#HTML related options +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = . +HTML_HEADER = @srcdir@/static/header.html +HTML_FOOTER = @srcdir@/static/footer.html +#HTML_STYLESHEET = @srcdir@/static/doxygen.css +TOC_EXPAND = YES +DISABLE_INDEX = NO +GENERATE_TREEVIEW = YES +TREEVIEW_WIDTH = 300 + +#--------------------------------------------------------------------------- +#LaTeX related option +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO + +#--------------------------------------------------------------------------- +#RTF related options +#--------------------------------------------------------------------------- +GENERATE_RTF = NO + +#--------------------------------------------------------------------------- +#External reference options +#--------------------------------------------------------------------------- +TAGFILES = +ALLEXTERNALS = NO diff --git a/doc/index.doc b/doc/index.doc new file mode 100644 index 0000000..c181c2b --- /dev/null +++ b/doc/index.doc @@ -0,0 +1,666 @@ +/*! + +\mainpage Introduction to PYHELLO sample module + +The purpose of the \b PYHELLO module is to describe briefly the different +steps in the development of a SALOME module in Python. + +Contents: +- \subpage dev_steps +- \subpage tree_structure +- \subpage build_proc_files +- \subpage idl_dir +- \subpage src_dir +- \subpage bin_dir +- \subpage doc_dir +- \subpage build_procedure +- \subpage run_procedure +- \subpage load_module +- \subpage catalog_def +- \subpage load_lcc +- \subpage load_iapp + +\ref dev_steps ">> Next" + +\page dev_steps Steps in construction of the example module + +The example module chosen to illustrate the process of SALOME module +development is extremely simple. The module contains a single +component and this component provides a single service called \b +makeBanner that accepts a character string as the sole argument and +that returns a character string obtained by the concatenation of a +'Hello' and the input string. The component also provides a simple +GUI. + +The steps in the development are as follows: +- create a module tree structure +- create a SALOME component that can be loaded by a Python SALOME container +- configure the module so that the component is known to SALOME +- add a graphic GUI + +\ref main "<< Previous"
\ref tree_structure ">> Next" + +\page tree_structure Create the module tree structure + +The first step in the development process is the creation of the +module tree file structure. The typical SALOME module usually includes +some set of the configuration files (used in the build procedure of a +module), Makefiles, IDL file that provides a definition of a CORBA +services implemented in a module and a set of source Python files +which implement the module CORBA engine and (optionally) its GUI. + +The following file structure is typical for the SALOME module: + +
++ PYHELLO1_SRC
+   + build_configure
+   + configure.ac
+   + Makefile.am
+   + adm_local
+     + Makefile.am
+     + unix
+       + Makefile.am
+       + make_common_starter.am
+       + config_files
+         + Makefile.am
+         + check_PYHELLO.m4
+   + bin
+     + Makefile.am
+     + VERSION.in
+     + runAppli.in
+     + myrunSalome.py
+   + idl
+     + Makefile.am
+     + PYHELLO_Gen.idl
+   + src
+     + Makefile.am
+     + PYHELLO
+       + Makefile.am
+       + PYHELLO.py
+       + PYHELLO_utils.py
+     + PYHELLOGUI
+       + Makefile.am
+       + PYHELLOGUI.py
+       + PYHELLO_msg_en.ts
+       + PYHELLO_icons.ts
+   + resources
+     + Makefile.am
+     + PYHELLO.png
+     + PYHELLO_small.png
+     + ExecPYHELLO.png
+     + handshake.png
+     + stop.png
+     + PYHELLOCatalog.xml.in
+     + SalomeApp.xml
+   + doc
+     + Makefile.am
+     + doxyfile.in
+     + index.doc
+
+ +Note that other files can be optionally present. For example, in some +SALOME modules sources tree you can find such files as AUTHORS, +INSTALL, ChangeLog, COPYING, NEWS, README, etc. Some files are +specific only for this PYHELLO sample module, for example PNG images +in the resources directory which are used in the GUI dialog boxes etc. + +The usual way of the sources directory tree structure initial creation +is to copy it from the existing SALOME module. + +\warning The files of the platform base module (KERNEL) must not be +copied to initialise a module tree structure. It is usually preferable +to copy files from another module such as GEOM or MED. + +The module name is PYHELLO, the component name is PYHELLO and all the +files are put in a directory named PYHELLO1_SRC. +Below is a short description of these files. Note, that files with .in +suffix are the autoconf templates from which the actual files are +generated during the build procedure. + +- build_configure, configure.ac, Makefile.am, make_common_starter.am + +These files are a part of the build system based on GNU +automake/autoconf auto-tools. These files define the build procedure, +namely, compilation and installation rules like compiler and linker +options, installation destination folder, package version etc. + +- adm_local/unix/config_files/check_PYHELLO.m4 + +The files in this directory are also a part of the GNU auto-tools +-based build procedure. The scripts written in m4 language are usually +used to test an availability of some 3rd-party pre-requisite product, +compiler feature, different configuration options. + +- bin/VERSION.in + +This file is used to document the module, it must give its version (at +least) and (optionally) compatibilities or incompatibilities with +other modules. This file is strongly recommended but is not essential +for operation of the module. + +- bin/runAppli.in +- bin/runSalome.py + +These files are not essential but make the example easier to +use. These are scripts that can be used to run SALOME session with +PYHELLO module. + +- idl/PYHELLO_Gen.idl + +This is the CORBA IDL definition of the services implemented by SALOME +PYHELLO module. + +- src/PYHELLO/PYHELLO.py +- src/PYHELLO/PYHELLO_utils.py + +These files provide the implementation of a CORBA engine of the +PYHELLO module. In particular, this is an implementation of the +services defined in the PYHELLO_Gen.idl file. + +- src/PYHELLOGUI/PYHELLOGUI.py + +The src/PYHELLOGUI is an optional directory that provides an +implementation of PYHELLO module's GUI. Strictly speaking, the +GUI is optional for each SALOME module. In some cases it's +enough to implement CORBA engine only. Then, the services of the +module will be avaiable in a CORBA environment. The module can be +loaded to the SALOME container and its services can be used in the +Supervisor computation schemas, in Python scripts or/and refer to it +in other modules. A GUI is necessary in the cases if it is planned to +access to the module functionality from the SALOME GUI session via +menu actions, dialog boxes and so on. + +- src/PYHELLOGUI/PYHELLO_msg_en.ts +- src/PYHELLOGUI/PYHELLO_icons.ts + +These files provide a description (internationalization) of GUI +resources of the PYHELLO module. PYHELLO_msg_en.ts provides an English +translation of the string resources used in a module. PYHELLO_icons.ts +defines images and icons resources used within the GUI of the +PYHELLO module. Please refer to Qt linguist documentation for more +details. + +- resources/PYHELLO.png +- resources/PYHELLO_small.png +- resources/ExecPYHELLO.png +- resources/handshake.png +- resources/stop.png + +The resources folder usually includes different resource files used +within the SALOME module. For example, PYHELLO.png file provides an icon +of PYHELLO module to be shown in the SALOME GUI desktop. ExecPYHELLO.png is +an icon for the makeBanner() function used in the menu and +toolbar. The icons handshake.png and stop.png are used in the dialog +boxes and PYHELLO_small.png icon is used to display in the Object +browser for root PYHELLO entity. + +- resources/PYHELLOCatalog.xml.in + +The XML description of the CORBA services provided by the PYHELLO +module. This file is parsed by Supervisor and YACS module to generate +the list of service nodes to be used in the calculation schemas. The +simplest way to create this file is to use Catalog Generator utility +provided by the SALOME KERNEL module, that can automatically generate +XML description file from the IDL file. + +- resources/SalomeApp.xml + +This file is essential for the module. It provides some parameters of +the module which define module behavior in SALOME. In particular it +should provide a section with the name corresponding to the name of a +module ("PYHELLO" in this case) with the following parameters: +\code +
+ + + +
+\endcode + +The "name" parameter defines GUI name of a module. The "icon" +parameter defines a GUI icon of a module. The parameter "library" +specifies the name of the C++ library representing the front-end of +the module in the SALOME GUI desktop. The Python modules which do not +implement its own C++ front-end GUI library should specify +"SalomePyQtGUI" value in this parameter. + +The section "resources" also specifies the directory that contains +resources of a module (icons, translation files, etc). + +\code +
+ +
+\endcode + +- doc/doxyfile.in + +The Doxygen configuration file. The Doxygen is used to build this +documentation. The file doxyfile.in provides a rules for the +generation of module documentation. + +- doc/index.doc + +An input file for the Doxygen, which provides a source of this documentation. + +\ref dev_steps "<< Previous"
\ref build_proc_files ">> Next" + +\page build_proc_files Build procedure input files + +SALOME uses autoconf and automake GNU auto-tools to build the +modules. The configure script is used for the build procedure to test +the system configuration and to pre-configure the module construction +Makefile files. + +The \b build_configure script provides a procedure that uses \b +configure.ac and set of \b Makefile.am files as input and uses autoconf +to generate the configure script and automake to generate Makefile.in +files. + +The files with an .in extension are the skeletons that are the input +of the configure script (to be more precise, these files should be +listed in the end of the configure.ac file in the AC_OUTPUT() +autoconf macro) and are transformed by the configure process. + +Almost all files used for this process are located in the platform +base module KERNEL that is referenced by the KERNEL_ROOT_DIR +environment variable, namely in its salome_adm sub-folder. +Similarly, the GUI_ROOT_DIR environment variable is used for the +graphical user interface (GUI), that also provides a set of +configuration utilities (m4 files) in its adm_local folder. However, +some files must be modified as a function of the target module. This +is the case for build_configure and configure.ac files which usually +need to be adapted to the module needs. + +The file \b make_common_starter.am file in the adm_local directory of +the example module provides basic build rules to be used in other +Makefile.am files. To refer to this file in the Makefile.am it is +necessary to use "include" clause: + +\code +include $(top_srcdir)/adm_local/unix/make_common_starter.am +\endcode + +The adm_local/unix/config_files is a directory in which the m4 files +that are used to test the configuration of the system in the configure +process can be placed. If the salome_adm files are not sufficient, +additional configuration files can be put to the adm_local directory. + +\ref tree_structure "<< Previous"
\ref idl_dir ">> Next" + +\page idl_dir The idl directory + +The idl directory requires a Makefile.am that must make the +compilation of the idl PYHELLO_Gen.idl file and install all the +generated files into the correct module installation directories. The +BASEIDL_FILES target has to be modified to reach this goal. + +The idl file itself must define a CORBA module for which the name must +be different from the module name to avoid name conflicts and define a +CORBA interface that is derived at least from the Component interface +of the Engines module. The name of the CORBA module will be +\b PYHELLO_ORB and the name of the interface will be \b PYHELLO_Gen. + +\ref build_proc_files "<< Previous"
\ref src_dir ">> Next" + +\page src_dir The src directory + +The src contains all source files required to build and install CORBA +engine and (optionally) GUI of the module. Each of these entities usually +has (but this is not actually obligatory) its own directory. + +The Makefile.am simply triggers the path of sub-directories described +by the SUBDIRS target. + +- The src/PYHELLO directory + +This directory contains the Python files that implement the engine +of the module. The Makefile.am defines the rules used to install these +files to the destination folder. The name of the module +engine Python file is predefined and should be set as .py +where is a name of the module. In the case of the PYHELLO +module, the name of the engine Python script should be PYHELLO.so. + +The PYHELLO.py Python script implements PYHELLO class that is derived +from the PYHELLO_Gen interface of the PYHELLO_ORB__POA CORBA module, +the SALOME_ComponentPy_i class (base implementation of SALOME +Python module engine exported by the KERNEL module) and +SALOME_DriverPy_i class that provides base implementation of +persistence mechanism. + +In particular, PYHELLO class implements makeBanner() function that is +defined in the IDL interface PYHELLO_ORB::PYHELLO_Gen. + +\code +def makeBanner( self, name ): + banner = "Hello %s!" % name + return banner +\endcode + +Other services +defined in PYHELLO_Gen CORBA interface also should be implemented by +this class. + +- The src/PYHELLOGUI directory + +This directory contains the Python files that implement the GUI +of PYHELLO module. The name of the module GUI Python script is +predefined and should be set as GUI.py where is a +name of the module. In the case of the PYHELLO module, the name of the +GUI Python script should be PYHELLOGUI.py. + +The implementation of GUI of the PYHELLO module should be done +according to the architecture and rules specified by the SALOME GUI +module. The PYHELLO.py script should implement a set of the functions +which define the module behavior in GUI, for example, create menus, +toolbars, define context popup menus, objects selection behavior, +implement dialog boxes etc. + +Here below is a short description of these methods. For more details +please refer to the SALOME GUI module documentation. + +- initialize() - module first initialization; usually used to create + GUI actions, menus, toolbars and so on; +- activate() - module activation; perform actions which should + be done when the module is activated by the user; +- deactivate() - module deactivation; perform actions which should + be done when the module is deactivated by the user; +- windows() - get a list and a position of the windows to be + associated with the module; these windows will be automatically + opened and positioned according to the setting defined by the value + returned by this function; +- views() - get a list of the compatible viewers; these viewers + will be automatically opened/raised on the module activation; +- createPopupMenu() - create and return context popup menu according + to the current selection; +- createPreferences() - initialize module's preferences; +- preferenceChanged() - callback function that is called when some + module's preference is changed by the user; allows to perform the + corresponding actions; +- engineIOR() - to get the reference to the module CORBA engine + +Note, that some of these methods are optional and need not be +obligatory implemented because SalomePyQtGUI_Module class provides a +base implementation of these functions. It's sometimes enough to +implement only some of them, depending on the module needs. + +In the case of PYHELLO module, some of these functions are +implemented to provide a sample for the development: + +- engineIOR() that initializes PYHELLO module's eggine: + +\code +def engineIOR(): + IOR = "" + if getORB() and getEngine(): + IOR = getORB().object_to_string( getEngine() ) + pass + return IOR +\endcode + +- initialize() that sets default module preferences + +\code +def initialize(): + if not sgPyQt.hasSetting( "PYHELLO", "def_obj_name"): + sgPyQt.addSetting( "PYHELLO", "def_obj_name", GUIcontext.DEFAULT_NAME ) + if not sgPyQt.hasSetting( "PYHELLO", "creation_mode"): + sgPyQt.addSetting( "PYHELLO", "creation_mode", 0 ) +\endcode + +- createPreferences() that initializes module preferences for the + application's Preferences dialog box + +\code +def createPreferences(): + if verbose() : print "PYHELLOGUI.createPreferences() : study : %d" % _getStudyId() + gid = sgPyQt.addPreference( "General" ) + gid = sgPyQt.addPreference( "Object creation", gid ) + pid = sgPyQt.addPreference( "Default name", gid, SalomePyQt.PT_String, "PYHELLO", "def_obj_name" ) + pid = sgPyQt.addPreference( "Default creation mode", gid, SalomePyQt.PT_Selector, "PYHELLO", "creation_mode" ) + strings = QStringList() + strings.append( "Default name" ) + strings.append( "Generate name" ) + strings.append( "Ask name" ) + indexes = [] + indexes.append( QVariant(0) ) + indexes.append( QVariant(1) ) + indexes.append( QVariant(2) ) + sgPyQt.setPreferenceProperty( pid, "strings", QVariant( strings ) ) + sgPyQt.setPreferenceProperty( pid, "indexes", QVariant( indexes ) ) + pass +\endcode + +- windows() that defines dockable windows layout + +\code +def windows(): + if verbose() : print "PYHELLOGUI.windows() : study : %d" % _getStudyId() + wm = {} + wm[SalomePyQt.WT_ObjectBrowser] = Qt.LeftDockWidgetArea + wm[SalomePyQt.WT_PyConsole] = Qt.BottomDockWidgetArea + return wm +\endcode + +Please refer to PYHELLOGUI.py script for more details about +implementation of other callback functions. + +An implemention of the ShowHello() function is quite simple. It shows +the small dialog box allowing user to enter the name, and then uses +reference to the module CORBA engine to invoke its makeBanner() +service. + +Note, that GUI elements of the Python module are implemented with help +of PyQt toolkit which provides a Python wrappings of the Qt library. + +\ref idl_dir "<< Previous"
\ref bin_dir ">> Next" + +\page bin_dir The bin directory + +The file VERSION.in is used to document the module, it must define its +version and (optionally) its compatibilities or incompatibilities with +other modules. Therefore, it is strongly recommended but is not +essential for correct operation of the module. + +The runAppli.in file is the equivalent of the runSalome script +distributed by the KERNEL module but configured to start SALOME +session with PYHELLO module only. + +The myrunSalome.py file reuses part of functionality provided by the +KERNEL's runSalome.py script. It is used to run SALOME session and +start PYHELLO module in this session. + +\ref src_dir "<< Previous"
\ref doc_dir ">> Next" + +\page doc_dir The doc directory + +This directory provides documentation files of the module. The +documentation of the module can be implemented in the arbitrary +way. But if you want your documentation to appear in the SALOME GUI +desktop's Help menu, some specific actions should be done as follows. + +The documentation should be generated in the HTML format. For example, +the documentation of the PYHELLO module is generated using Doxygen +tool. It allows to generate structured set of HTML pages from the set +of input plain text files. Input source files should include Doxygen +tags and optionally direct HTML tags. For more details please refer to +the Doxygen documentation. + +The resulting documentation of a module should include at least one +file index.html. All the HTML and image files should be exported by +the build procedure to the following directory: +/share/doc/salome/gui/ +where is a module installation folder and +MODULE is its name. For example, for PYHELLO module, at least one file +should exist: +/share/doc/salome/gui/PYHELLO/index.html. + +The SALOME GUI automatically searches for the index.html file in the +mentioned module directory. If the file is found, the corresponding +menu command is automatically added to the Help menu of the SALOME GUI +desktop. + +\ref bin_dir "<< Previous"
\ref build_procedure ">> Next" + +\page build_procedure Construction, installation + +Before building PYHELLO module, please ensure that SALOME environment is +set properly. Assume that SALOME environment is set in env_products.sh +script. In order to build and install PYHELLO module, you have to +perform several steps: + +
+[bash% ] source env_products.sh
+[bash% ] mkdir PYHELLO_BUILD
+[bash% ] cd PYHELLO_BUILD
+[bash% ] ../PYHELLO1_SRC/build_configure
+[bash% ] ../PYHELLO1_SRC/configure --prefix=
+[bash% ] make
+[bash% ] make install
+
+ +The first command creates a build directory for the PYHELLO module. Then +next step is to cd to this build directory. From this directory you +sequentially invoke build_configure, configure, make and make install +commands. On each step, you have to ensure that the operation is +finished correctly (no errors raised). + +The variable above defines the +destination directory to which the PYHELLO module should be +installed. After the last step is finished, the PYHELLO module is built +and installed to the directory. + +\ref doc_dir "<< Previous"
\ref run_procedure ">> Next" + +\page run_procedure Running SALOME + +Go to the the directory and type: + +
+[bash% ] ./bin/salome/runAppli
+
+ +This command runs SALOME session configured for KERNEL and the PYHELLO +module. At the end of running, the user will be prompted by the +Python interpreter command line configured for SALOME that provides +access to SALOME Python API (including CORBA interfaces). + +The runAppli file is a shell script that executes a Python commands +running SALOME session by passing arguments to it in a command line: + +
+${KERNEL_ROOT_DIR}/bin/salome/envSalome.py python -i $PYHELLO_ROOT_DIR/bin/salome/myrunSalome.py --modules=PYHELLO --killall
+
+ +These arguments state that the myrunSalome.py script located in the +PYHELLO module will be used, that the PYHELLO component will be +activated and all previously running SALOME sessions should be +shutdowned. + +This command will not function unless the following environment +variables have previously been set: + +
+export KERNEL_ROOT_DIR=
+export PYHELLO_ROOT_DIR=
+
+ +\warning It is possible that the SALOME run will not reach the end. +In some circumstances, the time to start CORBA servers may be long and +could exceed the timeout. If the reasons is that the time to +load dynamic libraries is long, it is possible that a second run +immediately afterwards will be successful. + +\ref build_procedure "<< Previous"
\ref load_module ">> Next" + +\page load_module Loading PYHELLO component + +The PYHELLO_ORB module has to be imported before making a request to +load the component into the container, to obtain access to methods of +the component. This container is made accessible in the runSalome.py +by means of the \b container variable: + +
+>> import PYHELLO_ORB
+>> c=container.load_impl("PYHELLO","PYHELLO")
+>> c.makeBanner("Christian")
+
+ +The last instruction returns a string "Hello Christian". Proceed as +follows to see the CORBA objects created by these actions: + +
+>> clt.showNS()
+
+ +\ref run_procedure "<< Previous"
\ref catalog_def ">> Next" + +\page catalog_def PYHELLO module catalog definition + +In the example from the previous chapter, the PYHELLO component was +loaded by making a direct request to the SALOME container. This is not +the standard method for loading of a component. The normal way uses +the SALOME LifeCycle service that invokes SALOME Module Catalog +services to identify the component and its properties and then calls +the requested container to load the component. + +Before this method can be used, the component must be declared in a +catalog in the XML format, for which the name must be +Catalog.xml. In our case, it will be PYHELLOCatalog.xml. +Usually this catalog is put to the resources sub-directory of the +directory tree. The simplest way to create this file is to use Catalog +Generator utility provided by the SALOME KERNEL module, that can +automatically generate XML description file from the IDL file. + +\ref load_module "<< Previous"
\ref load_lcc ">> Next" + +\page load_lcc Loading PYHELLO component via LifeCycle service + +The method of loading the component is not very different from that +is described above. The services of the LifeCycle module are used in +this case instead of calling the container directly. The call sequence +is contained in the runSalome.Py \b test() function. + +
+    c=test(clt)
+    c.makeBanner("Christian")
+
+ +The test function creates the LifeCycle object. It then asks for the +PYHELLO component to be loaded in the FactoryServer container: + +\code +def test(clt): + """ + Test function that creates an instance of PYHELLO component + usage : hello=test(clt) + """ + import LifeCycleCORBA + lcc = LifeCycleCORBA.LifeCycleCORBA(clt.orb) + import PYHELLO_ORB + pyhello = lcc.FindOrLoadComponent("FactoryServePy", "PYHELLO") + return pyhello +\endcode + +\ref catalog_def "<< Previous"
\ref load_iapp ">> Next" + +\page load_iapp Loading from the GUI (IAPP) + +In order to activate PYHELLO module in the SALOME GUI desktop, the user +should press the PYHELLO module's button on the "Modules" toolbar or +select the name of the module in the combo box on this toolbar. + +The image file to be used as an icon of a module should be exported by +the module build procedure. The icon file name is defined in the +corresponding SalomeApp.xml configuration file: +\code +
+ + + +
+\endcode + +\ref load_lcc "<< Previous" + +*/ diff --git a/doc/static/doxygen.css b/doc/static/doxygen.css new file mode 100755 index 0000000..88e613d --- /dev/null +++ b/doc/static/doxygen.css @@ -0,0 +1,170 @@ +H1 { + text-align: center; +} + +CAPTION { + font-weight: bold +} + +/* Link in the top navbar */ +A.qindex {} + +A.qindexRef {} + +/* Link to any cross-referenced Doxygen element */ +A.el { + text-decoration: none; + font-weight: bold +} + +A.elRef { + font-weight: bold +} + +/* Link to any cross-referenced Doxygen element inside a code section + (ex: header) +*/ +A.code { + text-decoration: none; + font-weight: normal; + color: #4444ee +} + +A.codeRef { + font-weight: normal; + color: #4444ee +} + +A:hover { + text-decoration: none; + background-color: lightblue +} + +DL.el { + margin-left: -1cm +} + +/* A code fragment (ex: header) */ +DIV.fragment { + width: 100%; + border: none; + background-color: #CCCCCC +} + +/* In the alpha list (coumpound index), style of an alphabetical index letter */ +DIV.ah { + background-color: #CCCCCC; + font-weight: bold; + color: #ffffff; + margin-bottom: 3px; + margin-top: 3px +} + +/* Method name (+ type) */ +TD.md { + background-color: lightblue; + font-weight: bold; +} + +/* Method parameter (some of them) */ +TD.mdname1 { + background-color: lightblue; + font-weight: bold; color: #602020; +} + +/* Method parameter (some of them) */ +TD.mdname { + background-color: lightblue; + font-weight: bold; + color: #602020; + width: 600px; +} + +/* Separator between methods group (usually empty, seems not supported by IE) */ +DIV.groupHeader { + margin-left: 16px; + margin-top: 12px; + margin-bottom: 6px; + font-weight: bold +} + +DIV.groupText { + margin-left: 16px; + font-style: italic; + font-size: smaller +} + +BODY { + background: #FFFFFF; +} + +/*div.div-page { + background-color: #FFFFFF; + margin-left: 1em; + margin-right: 1em; + margin-top: 1em; + margin-bottom: 0.1em; + + padding-left: 1em; + padding-right: 1em; + padding-top: 0.5em; + padding-bottom: 0.5em; + + border: 2px solid #0D299A; + border-width: 2px; + border-color: #0D299A; +}*/ + +div.tabs { + text-align: justify; + margin-left : 2px; + margin-right : 2px; + margin-top : 2px; + margin-bottom : 2px + font-weight: bold; + color: #FFFFFF; +} + +DIV.div-footer { + margin-left: 1em; + margin-right: 1em; + margin-bottom: 0.2em; + text-align: right; + font-size: 9pt; +} + +/* In File List, Coumpound List, etc, 1st column of the index */ +TD.indexkey { + background-color: #CCCCCC; + font-weight: bold; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px +} + +/* In File List, Coumpound List, etc, 2nd column of the index */ +TD.indexvalue { + background-color: #CCCCCC; + font-style: italic; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px +} + +span.keyword { color: #008000 } +span.keywordtype { color: #604020 } +span.keywordflow { color: #e08000 } +span.comment { color: #800000 } +span.preprocessor { color: #806020 } +span.stringliteral { color: #002080 } +span.charliteral { color: #008080 } diff --git a/doc/static/footer.html b/doc/static/footer.html new file mode 100755 index 0000000..6eab03c --- /dev/null +++ b/doc/static/footer.html @@ -0,0 +1,12 @@ + + + + + +
+
+Copyright © 2007-2008 CEA/DEN, EDF R&D, OPEN CASCADE
+Copyright © 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN, CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
+
+ + diff --git a/doc/static/header.html b/doc/static/header.html new file mode 100755 index 0000000..a70a95e --- /dev/null +++ b/doc/static/header.html @@ -0,0 +1,12 @@ + + + + + $title + + +
+
+SALOME documentation central +
+
diff --git a/src/PYHELLOGUI/PYHELLOGUI.py b/src/PYHELLOGUI/PYHELLOGUI.py index 911eb60..554c359 100644 --- a/src/PYHELLOGUI/PYHELLOGUI.py +++ b/src/PYHELLOGUI/PYHELLOGUI.py @@ -106,7 +106,7 @@ __study2context__ = {} # current context __current_context__ = None # object counter -__id__ = 0 +__objectid__ = 0 ################################################ @@ -405,6 +405,7 @@ def ShowHELLO(): # Create new object ### def CreateObject(): + global __objectid__ default_name = str( sgPyQt.stringSetting( "PYHELLO", "def_obj_name", GUIcontext.DEFAULT_NAME ).trimmed() ) try: if sgPyQt.action( GUIcontext.OPTION_3_ID ).isChecked(): @@ -418,18 +419,16 @@ def CreateObject(): name = str( name.trimmed() ) elif sgPyQt.action( GUIcontext.OPTION_2_ID ).isChecked(): # generate object name - global __id__ - __id__ = __id__ + 1 - name = "%s %d" % ( default_name, __id__ ) + __objectid__ = __objectid__ + 1 + name = "%s %d" % ( default_name, __objectid__ ) else: name = default_name pass pass except: # generate object name - global __id__ - __id__ = __id__ + 1 - name = "%s %d" % ( default_name, __id__ ) + __objectid__ = __objectid__ + 1 + name = "%s %d" % ( default_name, __objectid__ ) pass if not name: return getEngine().createObject( _getStudy(), name )