Macro at Startup: Difference between revisions

From FreeCAD Documentation
(translate)
(Marked this version for translation)
Line 2: Line 2:
<translate>
<translate>


= Foreword =
= Foreword = <!--T:1-->


<!--T:2-->
This documentation will explain how to set up a macro to automatically run at FreeCAD startup.
This documentation will explain how to set up a macro to automatically run at FreeCAD startup.


<!--T:3-->
Before starting, following things shall be considered :
Before starting, following things shall be considered :
* Automatically running macro at startup can be considered a security risk. You should only run macro that you trust and that you previously tested
* Automatically running macro at startup can be considered a security risk. You should only run macro that you trust and that you previously tested
Line 12: Line 14:
* This shouldn't be done for macros dealing with part modeling. This is rather appropriate for macros that add features, improve the UI, ...
* This shouldn't be done for macros dealing with part modeling. This is rather appropriate for macros that add features, improve the UI, ...


= How to =
= How to = <!--T:4-->


== Prepare the macro ==
== Prepare the macro == <!--T:5-->


<!--T:6-->
Generally, it will happen that a macro isn't directly compatible with a startup launch and shall be fine-tuned
Generally, it will happen that a macro isn't directly compatible with a startup launch and shall be fine-tuned


<!--T:7-->
Consider the below macro that you downloaded from somewhere and is stored in your 'Macro' folder with name 'MySuperMacro.FCMacro' :
Consider the below macro that you downloaded from somewhere and is stored in your 'Macro' folder with name 'MySuperMacro.FCMacro' :
</translate>
</translate>
Line 34: Line 38:
</pre>
</pre>
<translate>
<translate>
<!--T:8-->
All macros will generally present a similar structure with first import section, then definition section and finally main instruction section.
All macros will generally present a similar structure with first import section, then definition section and finally main instruction section.
We will focus on this latter because main instructions (they are quite easy to spot because they start at the full beginning of the line) are actually the ones that 'execute' the macro.
We will focus on this latter because main instructions (they are quite easy to spot because they start at the full beginning of the line) are actually the ones that 'execute' the macro.
Line 60: Line 65:
</pre>
</pre>
<translate>
<translate>
<!--T:9-->
Of course if the function 'run()' already exists in the macro, you can choose any other convenient name
Of course if the function 'run()' already exists in the macro, you can choose any other convenient name
Now the macro is ready to be integrated in FreeCAD startup.
Now the macro is ready to be integrated in FreeCAD startup.


== Integrate into FreeCAD startup ==
== Integrate into FreeCAD startup == <!--T:10-->


<!--T:11-->
First create a new folder in your user 'Mod' folder, let's say called 'MacroStartup'.
First create a new folder in your user 'Mod' folder, let's say called 'MacroStartup'.
Copy the modified macro into this newly created folder.
Copy the modified macro into this newly created folder.
Line 91: Line 98:
</pre>
</pre>
<translate>
<translate>
<!--T:12-->
Notice that it shall be done only once. If you want to run more than one macro, you can just add the others in the same file (look at the comments on the above code).
Notice that it shall be done only once. If you want to run more than one macro, you can just add the others in the same file (look at the comments on the above code).


<!--T:13-->
We are over. Your macro should automatically run at next FreeCAD launch.
We are over. Your macro should automatically run at next FreeCAD launch.


<!--T:14-->
Notice that if the original macro was downloaded through the Addon Manager, it will be overwritten on update and thus you have to follow again the steps here.
Notice that if the original macro was downloaded through the Addon Manager, it will be overwritten on update and thus you have to follow again the steps here.




<!--T:15-->
{{Userdocnavi}}
{{Userdocnavi}}




<!--T:16-->
[[Category:Poweruser Documentation]]
[[Category:Poweruser Documentation]]



Revision as of 11:20, 1 December 2019

Foreword

This documentation will explain how to set up a macro to automatically run at FreeCAD startup.

Before starting, following things shall be considered :

  • Automatically running macro at startup can be considered a security risk. You should only run macro that you trust and that you previously tested
  • You probably need some Python and coding notions to follow this procedure
  • When user folders ('Mod', 'Macro', ...) are referred to, they are located in your user FreeCAD folder.You can locate them at Start up and Configuration#User related information
  • This shouldn't be done for macros dealing with part modeling. This is rather appropriate for macros that add features, improve the UI, ...

How to

Prepare the macro

Generally, it will happen that a macro isn't directly compatible with a startup launch and shall be fine-tuned

Consider the below macro that you downloaded from somewhere and is stored in your 'Macro' folder with name 'MySuperMacro.FCMacro' :

## Import section ##
from PySide import QtGui

## Definition section (classes, functions, ...)
class MyMsgBox(QtGui.QMessageBox):

    def __init__(self):
        super(MyMsgBox, self).information(None, "MyTitle", "MyText")

##Main instruction section
MyMsgBox()

All macros will generally present a similar structure with first import section, then definition section and finally main instruction section. We will focus on this latter because main instructions (they are quite easy to spot because they start at the full beginning of the line) are actually the ones that 'execute' the macro. For later step, we'll need to programmatically import the macro then execute it. This can't be done with the actual structure of the macro. To be able to do so, we need to enclose the main instructions in a function --eg. run()-- then ensure this function is still called when the macro is manually run by the user. If you're not totally sure of what you're doing, it is advised to work on a copy of the macro (or you may just want to keep the original macro as is). The original file shall be modified as follow :

from PySide import QtGui
##The 2 below lines shall be added if not already present to ensure FreeCAD modules are imported
import FreeCAD as App
import FreeCADGui as Gui

class MyMsgBox(QtGui.QMessageBox):

    def __init__(self):
        super(MyMsgBox, self).information(None, "MyTitle", "MyText")

##Enclose the main instructions in a function
def run():
    MyMsgBox()

##Ensure main instructions are still called in case of manal run
if __name__ == '__main__':
    run()

Of course if the function 'run()' already exists in the macro, you can choose any other convenient name Now the macro is ready to be integrated in FreeCAD startup.

Integrate into FreeCAD startup

First create a new folder in your user 'Mod' folder, let's say called 'MacroStartup'. Copy the modified macro into this newly created folder. Finally create in the same folder a file called 'InitGui.py' which contains the following code :

def runMacroStartup(name):
    #Do not run when NoneWorkbench is activated because UI isn't yet completely there
    if name != "NoneWorkbench":
        #Run macro only once by disconnecting the signal at first call
        FreeCADGui.getMainWindow().workbenchActivated.disconnect(runMacroStartup)
        ##Following 2 lines shall be duplicated for each macro to run
        import MySuperMacro
        MySuperMacro.run()
        ##Eg. if a second macro shall be launched at startup
        #import MyWonderfulMacro
        #MyWonderfulMacro.run()

##The following 2 lines are important because InitGui.py files are passed to the exec() function...
##...and the runMacro wouldn't be visible outside. So explicitly add it to __main__
import __main__
__main__.runMacro = runMacro

##Connect the function that runs the macro to the appropriate signal
FreeCADGui.getMainWindow().workbenchActivated.connect(runMacro)

Notice that it shall be done only once. If you want to run more than one macro, you can just add the others in the same file (look at the comments on the above code).

We are over. Your macro should automatically run at next FreeCAD launch.

Notice that if the original macro was downloaded through the Addon Manager, it will be overwritten on update and thus you have to follow again the steps here.